Update AGENTS.md#2626
Open
Noor-ul-ain001 wants to merge 1 commit 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
| | `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}}`) | | ||
|
|
||
| > **Note:** `MarkdownIntegration`, `TomlIntegration`, `YamlIntegration`, and `SkillsIntegration` override `setup()` and `command_filename()` to provide format-specific filenames and template processing behavior. |
Comment on lines
+89
to
+92
| ```python | ||
| self.manifest.add("path/to/command.md") | ||
| self.manifest.add("path/to/context.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
258
to
262
| <!-- 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 ... | ||
|
|
Comment on lines
+290
to
+293
| def test_setup_creates_command_files(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() |
Comment on lines
+308
to
+312
| def test_teardown_removes_managed_files(tmp_path): | ||
| integration = MycliIntegration() | ||
| integration.setup(project_dir=tmp_path) | ||
| integration.teardown(project_dir=tmp_path) | ||
|
|
| | `$ARGUMENTS` | User-supplied arguments at runtime | Most Markdown agents | | ||
| | `{{args}}` | User-supplied arguments at runtime | TOML and YAML agents (Gemini, Goose) | | ||
| | `{{parameters}}` | User-supplied arguments at runtime | Forge | | ||
| | `{SCRIPT}` | Absolute path to the spec script | All agents | |
| | 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()` | |
|
|
||
| context = tmp_path / "MYCLI.md" | ||
| assert context.exists() | ||
| assert "spec-kit:start" in context.read_text() |
| 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
+89
to
+102
| ```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. | ||
|
|
||
| ### Why this matters | ||
|
|
||
| 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
+284
to
+328
| ```python | ||
| import pytest | ||
| from pathlib import Path | ||
| from specify_cli.integrations.mycli import MycliIntegration | ||
|
|
||
|
|
||
| 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) | ||
|
|
||
| # User content above the managed section should survive | ||
| assert "My custom notes" in user_file.read_text() | ||
| ``` |
Collaborator
|
Please address Copilot feedback and resolve conflicts |
Contributor
Author
|
I have fix the changes |
| 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
+88
to
+102
|
|
||
| ```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. | ||
|
|
||
| ### Why this matters | ||
|
|
||
| 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. --> | ||
|
|
||
| ... Spec Kit instructions ... | ||
|
|
||
| <!-- spec-kit:end --> | ||
| ``` |
Comment on lines
284
to
328
| ```python | ||
| import pytest | ||
| from pathlib import Path | ||
| from specify_cli.integrations.mycli import MycliIntegration | ||
|
|
||
|
|
||
| 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()) | ||
|
|
||
| # Uninstall cleanly | ||
| cd my-project && specify integration uninstall <key> | ||
|
|
||
| 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) | ||
|
|
||
| # User content above the managed section should survive | ||
| assert "My custom notes" in user_file.read_text() | ||
| ``` |
Comment on lines
+561
to
+563
| --- | ||
|
|
||
| ## Common Pitfalls | ||
| ## Updating Devcontainer Configuration |
mnriem
requested changes
May 27, 2026
mnriem
left a comment
mnriem
left a comment
Collaborator
There was a problem hiding this comment.
Please address Copilot feedback
Rebased onto current main and reworked so the additions match the current architecture rather than the stale base this branch was written against. The original revision documented the retired Windsurf integration and a CLI-managed `context_file` field that no longer exists (context files are now owned by the opt-in agent-context extension), and described the manifest at the wrong path with a non-existent API. This version keeps all current AGENTS.md content unchanged and adds four onboarding-focused sections, verified against the code: - Quickstart — Add a New Integration in 5 Steps (links into the existing step-by-step section; notes context files are extension-owned) - IntegrationManifest — File Tracking (correct path .specify/integrations/<key>.manifest.json and real API: record_file / record_existing / hash-guarded uninstall) - Error Handling and Debugging (symptom/cause/fix table + debug tips) - Contribution Checklist Purely additive (+88 lines, no deletions); all internal anchors resolve. Assisted-by: Claude Opus 4.8 (model: claude-opus-4-8, autonomous) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
Author
|
@
Rather than reintroduce that drift, the branch now keeps all current Commit: Posted on behalf of @Noor-ul-ain001 by Claude Opus 4.8 (model: claude-opus-4-8), acting autonomously. |
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.