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
Comment on lines
+69
to
+74
| | `setup()` | Processes templates, writes command files, updates the context file | The agent needs companion files, settings merges, or non-standard file layouts | | ||
| | `teardown()` | Removes all files tracked by the integration manifest | The agent created files outside the standard manifest (rare) | | ||
| | `command_filename(template_name)` | Returns `<template_name><extension>` | 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)` | Replaces `{SCRIPT}`, `$ARGUMENTS`, and `__AGENT__` placeholders | The agent uses non-standard placeholders (e.g., Forge uses `{{parameters}}`) | | ||
|
|
Comment on lines
+85
to
+93
| 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
+255
to
262
| ```markdown | ||
| <!-- spec-kit:start --> | ||
| <!-- This section is managed by Specify CLI. Do not edit manually. --> | ||
|
|
||
| ... Spec Kit instructions ... | ||
|
|
||
| # Uninstall cleanly | ||
| cd my-project && specify integration uninstall <key> | ||
| <!-- spec-kit:end --> | ||
| ``` |
Comment on lines
+472
to
+475
| | `{SCRIPT}` | Absolute path to the spec script | All agents | | ||
| | `__AGENT__` | Name of the current agent | All agents | | ||
|
|
||
| Always check `registrar_config["args"]` for the correct placeholder before writing command templates for a new integration. |
| | 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()` | |
| | 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
+288
to
+292
| def test_setup_creates_command_files(tmp_path): | ||
| integration = MycliIntegration() | ||
| integration.setup(project_dir=tmp_path) | ||
|
|
||
| commands_dir = tmp_path / ".mycli" / "commands" |
Comment on lines
+394
to
+396
| ├── spec.md | ||
| ├── implement.md | ||
| └── review.md |
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.