Update AGENTS.md

[Noor-ul-ain001]

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.

[Copilot]

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

[Copilot]

Copilot's findings

• Files reviewed: 1/1 changed files
• Comments generated: 11

[Copilot]

Copilot's findings

• Files reviewed: 1/1 changed files
• Comments generated: 10

[Copilot]

Copilot's findings

• Files reviewed: 1/1 changed files
• Comments generated: 5

[mnriem]

Please address Copilot feedback and resolve conflicts

[Noor-ul-ain001]

I have fix the changes

[Copilot]

Copilot's findings

• Files reviewed: 1/1 changed files
• Comments generated: 6

[mnriem]

Please address Copilot feedback

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Noor-ul-ain001]

@
Rebased this branch onto current main to resolve the conflict, and reworked the content so it matches the current architecture. The branch was ~560 commits behind, and AGENTS.md had been rewritten upstream in the meantime, so the original revision had drifted out of sync in a few places:

• It used the Windsurf integration as its running example, but Windsurf has since been retired (chore: retire Windsurf integration — absorbed into Cognition Devin (#3168) #3213, absorbed into Cognition Devin).
• It reintroduced a CLI-managed context_file field and a "context file behavior" flow. Context files are now owned entirely by the opt-in agent-context extension; integration classes no longer declare context_file.
• Its IntegrationManifest section pointed at .windsurf/.specify-manifest.json with a self.manifest.add(...) API. The real manifest lives at .specify/integrations/<key>.manifest.json and the API is record_file / record_existing with a hash-guarded uninstall.

Rather than reintroduce that drift, the branch now keeps all current AGENTS.md content unchanged and layers on only the genuinely-additive onboarding sections, corrected against the code: a Quickstart, a corrected IntegrationManifest — File Tracking section, an Error Handling and Debugging table, and a Contribution Checklist. The result is purely additive (+88 lines, no deletions) and all internal anchors resolve.

Commit: 428ad64

---

Posted on behalf of @Noor-ul-ain001 by Claude Opus 4.8 (model: claude-opus-4-8), acting autonomously.
@

[Copilot]

Review details

Comments suppressed due to low confidence (2)

AGENTS.md:71

• The recommendation to call record_existing() for adopted pre-existing files can make uninstall delete user-owned files whenever their hash remains unchanged. Limit this guidance to files the integration itself produced outside record_file(); merged or otherwise user-owned files should remain untracked unless teardown can restore them safely.

Without hash-tracked manifests, uninstall would either remove files it should not (destructive) or leave orphans behind (messy). If you write a custom `setup()`, route **every** file you create through `manifest.record_file(...)` (or `record_existing(...)` for files you adopt) so uninstall can reason about them.

AGENTS.md:595

• specify init only installs the integration; it does not exercise uninstall, and this invocation also omits the required project name/--here argument. The checklist therefore cannot confirm the stated install/uninstall flow as written.

- [ ] Verified the install/uninstall flow with `specify init --integration <key>`.

• Files reviewed: 1/1 changed files
• Comments generated: 3
• Review effort level: Medium

[Copilot]

Review details

Comments suppressed due to low confidence (3)

AGENTS.md:21

• This command always exits with “Must specify either a project name...” because init() requires a project name, . or --here (commands/init.py:84-87, 215-219). It also does not exercise uninstall as claimed. Include both commands so the quickstart is executable end to end.

5. **Run and verify** — use `specify init --integration <key>` to exercise the full install/uninstall cycle.

AGENTS.md:64

• Do not recommend adopting a pre-existing user file this way. manifest.uninstall() deletes any tracked file whose hash still matches (manifest.py:350-390), which would remove an untouched user-owned settings file; Copilot deliberately leaves existing .vscode/settings.json untracked for this reason (copilot/__init__.py:428-434). Reserve record_existing() for output the integration itself has already written through another helper.

# Adopt a pre-existing file the integration is now responsible for.
manifest.record_existing(".vscode/settings.json")

AGENTS.md:71

• “Files you adopt” repeats the unsafe guidance above: an unchanged tracked user file is deleted during uninstall. Also account for the project-root boundary described earlier so custom integrations know when manifest tracking is unavailable.

Without hash-tracked manifests, uninstall would either remove files it should not (destructive) or leave orphans behind (messy). If you write a custom `setup()`, route **every** file you create through `manifest.record_file(...)` (or `record_existing(...)` for files you adopt) so uninstall can reason about them.

• Files reviewed: 1/1 changed files
• Comments generated: 2
• Review effort level: Medium

[mnriem]

Please address Copilot feedback

[Copilot]

Review details

Comments suppressed due to low confidence (4)

AGENTS.md:21

• This command cannot run as written: init requires either a project name or --here, and it only installs the integration—it does not exercise uninstall. Show both commands so the advertised full cycle is actually verified.

5. **Run and verify** — use `specify init --integration <key>` to exercise the full install/uninstall cycle.

AGENTS.md:595

• This checklist command neither runs without a project name/--here nor tests uninstall. As written, contributors cannot satisfy the stated install/uninstall verification; list the explicit initialization and uninstall commands.

- [ ] Verified the install/uninstall flow with `specify init --integration <key>`.

AGENTS.md:64

• record_existing() makes a matching file eligible for deletion during uninstall, so presenting a pre-existing .vscode/settings.json as the example risks teaching contributors to delete user-owned settings. Copilot explicitly leaves an existing settings file untracked for this reason (src/specify_cli/integrations/copilot/__init__.py:428-434). Use an integration-owned generated file in the example.

# Adopt a pre-existing file the integration is now responsible for.
manifest.record_existing(".vscode/settings.json")

AGENTS.md:71

• This recommendation is unsafe for an adopted user-owned file: record_existing() records it like any other managed artifact, so an unchanged file is deleted on uninstall. Restrict this API to files already known to be integration-owned and safe to remove.

Without hash-tracked manifests, uninstall would either remove files it should not (destructive) or leave orphans behind (messy). If you write a custom `setup()`, route **every** file you create through `manifest.record_file(...)` (or `record_existing(...)` for files you adopt) so uninstall can reason about them.

• Files reviewed: 1/1 changed files
• Comments generated: 0 new
• Review effort level: Medium

[mnriem]

Thank you!