Skip to content

Update AGENTS.md#2626

Open
Noor-ul-ain001 wants to merge 1 commit into
github:mainfrom
Noor-ul-ain001:patch-1
Open

Update AGENTS.md#2626
Noor-ul-ain001 wants to merge 1 commit into
github:mainfrom
Noor-ul-ain001:patch-1

Conversation

@Noor-ul-ain001
Copy link
Copy Markdown

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.

@Noor-ul-ain001 Noor-ul-ain001 requested a review from mnriem as a code owner May 19, 2026 02:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant