This document describes the multi-agent support architecture that enables Spec Kit to work with 16+ AI coding assistants. It covers the AGENT_CONFIG registry system, command file generation, format variations, and context management mechanisms that abstract heterogeneous agent conventions into a unified framework.
For details on the workflow commands that agents execute, see Spec-Driven Development Workflow. For information on the CLI commands that initialize agent-specific project structures, see Core CLI Tool.
Spec Kit supports multiple AI agents through an adapter pattern that abstracts three primary axes of variation:
.claude/commands/, .github/agents/, .windsurf/workflows/, etc.)The architecture centralizes agent metadata in a single registry (AGENT_CONFIG), generates agent-specific command files from unified templates during project initialization, and provides context update scripts that synchronize project information across all installed agents.
Sources: src/specify_cli/__init__.py126-229 AGENTS.md1-414
The AGENT_CONFIG dictionary in src/specify_cli/__init__.py serves as the single source of truth for all agent metadata. Each agent entry contains four fields:
Key Design Principle: The dictionary key must match the actual executable name in the system PATH (e.g., "cursor-agent" not "cursor") to eliminate special-case mappings in tool checking logic.
| Agent Key | Display Name | Directory | CLI Tool Required | Type |
|---|---|---|---|---|
copilot | GitHub Copilot | .github/ | No | IDE-based |
claude | Claude Code | .claude/ | Yes | CLI-based |
gemini | Gemini CLI | .gemini/ | Yes | CLI-based |
cursor-agent | Cursor | .cursor/ | No | IDE-based |
qwen | Qwen Code | .qwen/ | Yes | CLI-based |
opencode | opencode | .opencode/ | Yes | CLI-based |
codex | Codex CLI | .codex/ | Yes | CLI-based |
windsurf | Windsurf | .windsurf/ | No | IDE-based |
kilocode | Kilo Code | .kilocode/ | No | IDE-based |
auggie | Auggie CLI | .augment/ | Yes | CLI-based |
codebuddy | CodeBuddy | .codebuddy/ | Yes | CLI-based |
qoder | Qoder CLI | .qoder/ | Yes | CLI-based |
roo | Roo Code | .roo/ | No | IDE-based |
q | Amazon Q Developer CLI | .amazonq/ | Yes | CLI-based |
amp | Amp | .agents/ | Yes | CLI-based |
shai | SHAI | .shai/ | Yes | CLI-based |
bob | IBM Bob | .bob/ | No | IDE-based |
Sources: src/specify_cli/__init__.py126-229 AGENTS.md30-51
CLI-based agents require an executable CLI tool in the system PATH. The check_tool() function uses shutil.which() to verify tool availability.
Tool Check Implementation:
Special Case - Claude Migration: The Claude CLI tool moved from global PATH to ~/.claude/local/claude after the claude migrate-installer command. The check_tool() function prioritizes this location before checking PATH.
Sources: src/specify_cli/__init__.py484-513 src/specify_cli/__init__.py233 AGENTS.md306-319
IDE-based agents (requires_cli: False) do not require tool checking. They work within integrated development environments through extensions or built-in features.
Sources: src/specify_cli/__init__.py126-229 AGENTS.md320-327
Agents accept command definitions in two formats:
Used by: Claude, Copilot, Cursor, opencode, Windsurf, Kilocode, Auggie, Roo, CodeBuddy, Qoder, Amazon Q, Amp, SHAI, IBM Bob
Structure:
GitHub Copilot Chat Mode Variant:
Used by: Gemini, Qwen
Structure:
Sources: AGENTS.md328-366
Command files are generated during project initialization through the release package creation pipeline:
Processing Steps:
templates/commands/ directory{SCRIPT} with actual script paths$ARGUMENTS or {{args}})Sources: AGENTS.md109-128 AGENTS.md328-383
Each agent expects commands in a specific directory:
Sources: src/specify_cli/__init__.py126-229 AGENTS.md368-374
Two cross-platform scripts parse plan.md to extract technology stack information and update agent-specific context files:
scripts/bash/update-agent-context.shscripts/powershell/update-agent-context.ps1Update Flow:
Agent context files (e.g., CLAUDE.md, GEMINI.md) contain:
/speckit.* workflow commandsBash Script Pattern:
PowerShell Script Pattern:
Sources: AGENTS.md142-189
The following diagram shows how the AGENT_CONFIG registry integrates with the initialization flow, command generation, and context management:
Sources: src/specify_cli/__init__.py126-229 src/specify_cli/__init__.py350-423 src/specify_cli/__init__.py484-513 src/specify_cli/__init__.py751-898 AGENTS.md142-189
The agent selection and initialization process follows this sequence:
Sources: src/specify_cli/__init__.py980-1269 src/specify_cli/__init__.py350-423 src/specify_cli/__init__.py484-513 src/specify_cli/__init__.py751-898
The CI/CD pipeline generates 32 distinct package variants during releases:
Formula: 16 agents × 2 script types (sh, ps) = 32 packages
Package Naming Convention:
spec-kit-template-{agent}-{script}-v{version}.zip
Examples:
spec-kit-template-claude-sh-v0.1.0.zipspec-kit-template-claude-ps-v0.1.0.zipspec-kit-template-gemini-sh-v0.1.0.zipspec-kit-template-gemini-ps-v0.1.0.zipEach package contains:
Shared Resources
.specify/memory/ - Constitution and project memory.specify/scripts/ - Workflow automation scripts (bash or PowerShell).specify/templates/ - Specification templatesAgent-Specific Resources
.{agent}/ directory - Agent's command directory structureGEMINI.md, QWEN.md)Sources: AGENTS.md109-128
Adding a new agent requires updates to five system components:
src/specify_cli/__init__.py--ai parameter documentationcreate-release-packages.sh and create-github-release.shREADME.md and AGENTS.mdUse the actual CLI tool name as the AGENT_CONFIG key, not a shorthand or convenient alias.
Rationale: The check_tool() function uses shutil.which(tool) which searches for the exact executable name in PATH. Mismatched keys require special-case mappings throughout the codebase.
Example - Correct Approach:
Example - Incorrect Approach:
1. Add to AGENT_CONFIG (src/specify_cli/__init__.py126-229):
2. Update CLI Help Text (src/specify_cli/__init__.py983):
3. Add to Release Script (.github/workflows/scripts/create-release-packages.sh):
4. Update Context Scripts:
Bash (scripts/bash/update-agent-context.sh):
PowerShell (scripts/powershell/update-agent-context.ps1):
Sources: AGENTS.md52-410
create-release-packages.sh locally to verify package generationspecify init test-project --ai new-agentcheck_tool() detects installation correctly| Error | Cause | Solution |
|---|---|---|
| Tool not found | AGENT_CONFIG key doesn't match executable | Use actual CLI tool name as key |
| Wrong format | Agent needs TOML but generates Markdown | Update generate_commands call with correct format |
| Wrong placeholder | Using $ARGUMENTS for TOML agent | Use {{args}} for TOML format |
| Directory not created | Missing case in release script | Add agent case to create-release-packages.sh |
| Context not updated | Missing from update scripts | Add agent file variables to both bash and PowerShell scripts |
Sources: AGENTS.md385-391 AGENTS.md392-400
The AI Agent Integration system achieves "write once, deploy everywhere" through:
AGENT_CONFIG dictionary as single source of truthfolder fieldrequires_cli fieldThis architecture enables supporting 16+ agents without code duplication, allows adding new agents through configuration changes rather than code changes, and maintains consistency across heterogeneous agent conventions.
Refresh this wiki