Update AGENTS.md#2626
Open
Noor-ul-ain001 wants to merge 3 commits into
Open
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates AGENTS.md to provide a more structured, end-to-end guide for adding new AI agent integrations to Spec Kit, including base-class selection guidance, integration architecture explanation, and contributor checklists.
Changes:
- Adds a Quickstart section and reorganizes the document around a clearer “add an integration” workflow.
- Introduces reference tables (base class + method overrides), a manifest-tracking explanation, and a complete “mycli” walkthrough.
- Expands guidance for testing, debugging, and contribution readiness checks.
Show a summary per file
| File | Description |
|---|---|
| AGENTS.md | Reworked integration contributor documentation: quickstart, architecture, base-class/method guidance, manifest + context behavior, examples, debugging, and checklist. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 1/1 changed files
- Comments generated: 9
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
| | `teardown()` | Delegates to `IntegrationManifest.uninstall()`, which removes tracked files when safe and may skip modified files | The agent created files outside the standard manifest or needs custom uninstall behavior | | ||
| | `command_filename(template_name)` | In `IntegrationBase`, returns `speckit.{template_name}.md` | The agent uses a different naming convention (e.g., Copilot uses `speckit.<name>.agent.md`) | | ||
| | `options()` | Returns an empty list (no extra CLI flags) | The agent supports integration-specific install options (e.g., `--skills` for Codex) | | ||
| | `process_template(content)` | Base implementation processes known placeholders such as `{SCRIPT}`, `$ARGUMENTS`, and `__AGENT__` when used by subclasses that call it | The agent uses non-standard placeholders (e.g., Forge uses `{{parameters}}`) | |
Comment on lines
+87
to
+95
| When `setup()` installs files, it registers each file path with the manifest: | ||
|
|
||
| ```python | ||
| self.manifest.add("path/to/command.md") | ||
| self.manifest.add("path/to/context.md") | ||
| ``` | ||
|
|
||
| The manifest is persisted to a hidden file inside the integration's folder (e.g., `.windsurf/.specify-manifest.json`). When the user runs `specify integration uninstall <key>`, `teardown()` reads the manifest and removes only the files that belong to this integration. Files that the user created manually are never touched. | ||
|
|
Comment on lines
+98
to
103
| Without the manifest, uninstall would either: | ||
| - Remove files it should not (destructive), or | ||
| - Leave files behind (messy) | ||
|
|
||
| The manifest solves both problems. If you are writing a custom `setup()` method, always register every file you create with `self.manifest.add(path)`. | ||
|
|
Comment on lines
+257
to
264
| ```markdown | ||
| <!-- spec-kit:start --> | ||
| <!-- This section is managed by Specify CLI. Do not edit manually. --> | ||
|
|
||
| # Verify files were created in the commands directory configured by | ||
| # config["folder"] + config["commands_subdir"] (for example, .windsurf/workflows/) | ||
| ls -R my-project/.windsurf/workflows/ | ||
| ... Spec Kit instructions ... | ||
|
|
||
| # Uninstall cleanly | ||
| cd my-project && specify integration uninstall <key> | ||
| <!-- spec-kit:end --> | ||
| ``` |
Comment on lines
+290
to
+293
| def test_setup_creates_command_files(tmp_path): | ||
| integration = MycliIntegration() | ||
| integration.setup(project_dir=tmp_path) | ||
|
|
Comment on lines
+290
to
+324
| def test_setup_creates_command_files(tmp_path): | ||
| integration = MycliIntegration() | ||
| integration.setup(project_dir=tmp_path) | ||
|
|
||
| commands_dir = tmp_path / ".mycli" / "commands" | ||
| assert commands_dir.exists() | ||
| assert any(commands_dir.iterdir()), "Expected at least one command file" | ||
|
|
||
|
|
||
| def test_setup_creates_context_file(tmp_path): | ||
| integration = MycliIntegration() | ||
| integration.setup(project_dir=tmp_path) | ||
|
|
||
| context = tmp_path / "MYCLI.md" | ||
| assert context.exists() | ||
| assert "spec-kit:start" in context.read_text() | ||
|
|
||
|
|
||
| def test_teardown_removes_managed_files(tmp_path): | ||
| integration = MycliIntegration() | ||
| integration.setup(project_dir=tmp_path) | ||
| integration.teardown(project_dir=tmp_path) | ||
|
|
||
| commands_dir = tmp_path / ".mycli" / "commands" | ||
| assert not commands_dir.exists() or not any(commands_dir.iterdir()) | ||
|
|
||
|
|
||
| def test_teardown_preserves_user_files(tmp_path): | ||
| integration = MycliIntegration() | ||
| integration.setup(project_dir=tmp_path) | ||
|
|
||
| user_file = tmp_path / "MYCLI.md" | ||
| user_file.write_text("# My custom notes\n\n" + user_file.read_text()) | ||
|
|
||
| integration.teardown(project_dir=tmp_path) |
Comment on lines
+528
to
+532
| | CLI check fails for `requires_cli: True` agent | `key` does not match executable name | Set `key` to the exact name users type in the terminal (verified by `shutil.which(key)`) | | ||
| | Command files have wrong argument syntax | Wrong `args` value in `registrar_config` | Use `$ARGUMENTS` for Markdown agents, `{{args}}` for TOML/YAML agents | | ||
| | Context file not created or updated | `context_file` is `None` or points to wrong path | Set `context_file` to the exact relative path the agent reads | | ||
| | Uninstall leaves files behind | Files created in `setup()` not registered with manifest | Call `self.manifest.add(path)` for every file created in a custom `setup()` | | ||
| | Black background in table cells (docx output) | `ShadingType.SOLID` used instead of `ShadingType.CLEAR` | Use `ShadingType.CLEAR` for all cell shading | |
| **Inspect the manifest file** to see what files are tracked for an integration: | ||
|
|
||
| ```bash | ||
| cat .mycli/.specify-manifest.json |
Comment on lines
+542
to
+546
| **Run with verbose output** to trace what Specify CLI is doing during install: | ||
|
|
||
| ```bash | ||
| specify init my-project --integration mycli --verbose | ||
| ``` |
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
This PR updates AGENTS.md to enhance documentation for adding new AI agent integrations to Spec Kit, improving onboarding for new contributors and standardizing integration patterns.
Changes Overview
Documentation Structure
Adds a "Quickstart" section providing a 5-step path from initial setup to working integration
Restructures content with clearer hierarchical organization and descriptive headings
Consolidates integration architecture explanation with directory tree visualization
Technical Reference
Introduces a base class reference table with selection criteria (MarkdownIntegration, TomlIntegration, YamlIntegration, SkillsIntegration, IntegrationBase)
Documents IntegrationManifest file tracking mechanism and its role in safe uninstallation
Provides method reference table specifying override conditions for setup(), teardown(), command_filename(), options(), and process_template()
Practical Guidance
Adds a complete end-to-end example (mycli) demonstrating integration from creation to verification
Expands testing documentation with structured test patterns and assertion guidelines
Includes debugging section with common error scenarios and resolution strategies
Adds contribution checklist for integration PRs
Motivation
The existing AGENTS.md adequately describes existing integrations but lacks structured guidance for new contributors. Adding an integration previously required inferring patterns from multiple existing implementations. This update provides:
Decision framework for base class selection
Step-by-step implementation instructions with copy-paste templates
Test structure specifications with example assertions
Debugging reference for frequent failure modes
Testing
Verified all code examples against existing integration implementations (Claude, Gemini, Windsurf, Copilot, Codex, Goose)
Confirmed directory structures and file paths match current codebase in src/specify_cli/integrations/
Validated placeholder consistency across documentation ($ARGUMENTS, {{args}}, {{parameters}})
Reviewed integration registration process in src/specify_cli/integrations/init.py
Verified context file behavior documentation matches base class implementation
Confirmed contribution checklist completeness for new integration PRs
AI Disclosure
This contribution was developed with assistance from Claude (Anthropic). AI assistance was used for:
Analyzing existing documentation to identify structural gaps
Organizing technical content into tables and decision frameworks
Generating illustrative examples based on existing integration patterns
Formatting debugging checklists and contribution requirements
All technical information presented has been verified against the Spec Kit codebase. The AI assisted with presentation and organization of existing knowledge; no novel technical requirements were generated.