This document catalogs the 17 AI coding assistants currently supported by Spec Kit and details their configuration metadata, directory structures, and installation requirements. The system uses a single source of truth (AGENT_CONFIG dictionary) to drive agent integration throughout the CLI and template generation pipeline.
For information about the agent configuration system architecture, see page 6.2. For details on how agent context files are updated, see page 6.3. For guidance on adding new agents, see page 6.5.
The Spec Kit system categorizes AI agents into two primary types based on their deployment and invocation patterns. The AGENT_CONFIG dictionary in the CLI serves as the canonical registry for all agent metadata.
Sources: src/specify_cli/__init__.py126-229 src/specify_cli/__init__.py484-513 src/specify_cli/__init__.py981-1269 src/specify_cli/__init__.py233
The following table presents all 17 agents currently registered in the AGENT_CONFIG dictionary, including their metadata fields that control CLI behavior and template generation.
| Agent Key | Display Name | Directory | Format | requires_cli | Install URL |
|---|---|---|---|---|---|
claude | Claude Code | .claude/ | Markdown | True | https://docs.anthropic.com/en/docs/claude-code/setup |
gemini | Gemini CLI | .gemini/ | TOML | True | https://github.com/google-gemini/gemini-cli |
copilot | GitHub Copilot | .github/ | Special (.agent.md + .prompt.md) | False | None |
cursor-agent | Cursor | .cursor/ | Markdown | False | None |
qwen | Qwen Code | .qwen/ | TOML | True | https://github.com/QwenLM/qwen-code |
opencode | opencode | .opencode/ | Markdown | True | https://opencode.ai |
codex | Codex CLI | .codex/ | Markdown | True | https://github.com/openai/codex |
windsurf | Windsurf | .windsurf/ | Markdown | False | None |
kilocode | Kilo Code | .kilocode/ | Markdown | False | None |
auggie | Auggie CLI | .augment/ | Markdown | True | https://docs.augmentcode.com/cli/setup-auggie/install-auggie-cli |
codebuddy | CodeBuddy | .codebuddy/ | Markdown | True | https://www.codebuddy.ai/cli |
qoder | Qoder CLI | .qoder/ | Markdown | True | https://qoder.com/cli |
roo | Roo Code | .roo/ | Markdown | False | None |
q | Amazon Q Developer CLI | .amazonq/ | Markdown | True | https://aws.amazon.com/developer/learning/q-developer-cli/ |
amp | Amp | .agents/ | Markdown | True | https://ampcode.com/manual#install |
shai | SHAI | .shai/ | Markdown | True | https://github.com/ovh/shai |
bob | IBM Bob | .bob/ | Markdown | False | None |
Sources: src/specify_cli/__init__.py126-229 AGENTS.md32-50
CLI-based agents require standalone command-line tools to be installed on the user's system. The CLI performs tool validation during initialization using the check_tool() function, which leverages shutil.which() to locate executables in the system PATH.
Each CLI-based agent entry in AGENT_CONFIG includes the following metadata:
| Agent Key | Executable Name | Command Directory | Argument Syntax | Notes |
|---|---|---|---|---|
claude | claude | .claude/commands/ | $ARGUMENTS | Special handling for ~/.claude/local/claude path after claude migrate-installer |
gemini | gemini | .gemini/commands/ | {{args}} | Uses TOML format with escaped backslashes |
qwen | qwen | .qwen/commands/ | {{args}} | Uses TOML format with escaped backslashes |
opencode | opencode | .opencode/command/ | $ARGUMENTS | Standard Markdown format |
codex | codex | .codex/commands/ | $ARGUMENTS | Requires CODEX_HOME environment variable |
auggie | auggie | .augment/rules/ | $ARGUMENTS | Auggie CLI |
codebuddy | codebuddy | .codebuddy/commands/ | $ARGUMENTS | CodeBuddy CLI |
qoder | qoder | .qoder/commands/ | $ARGUMENTS | Qoder CLI |
q | q | .amazonq/prompts/ | $ARGUMENTS | Amazon Q Developer CLI |
amp | amp | .agents/commands/ | $ARGUMENTS | Amp CLI |
shai | shai | .shai/commands/ | $ARGUMENTS | SHAI CLI |
Sources: src/specify_cli/__init__.py484-513 src/specify_cli/__init__.py1096-1111 src/specify_cli/__init__.py233 src/specify_cli/__init__.py986
IDE-based agents are integrated directly into development environments and do not require separate CLI tool installations. The system skips tool validation for these agents during initialization.
| Agent Key | IDE/Editor | Agent Directory | Subdirectory | Notes |
|---|---|---|---|---|
copilot | VS Code / Compatible Editors | .github/ | agents/ and prompts/ | Special paired file format: .agent.md + .prompt.md |
cursor-agent | Cursor IDE | .cursor/ | commands/ | IDE-based but uses command files |
windsurf | Windsurf IDE | .windsurf/ | workflows/ | Windsurf-specific workflow format |
kilocode | Kilo Code IDE | .kilocode/ | rules/ | Uses rules directory convention |
roo | Roo Code IDE | .roo/ | rules/ | Uses rules directory convention |
bob | IBM Bob IDE | .bob/ | commands/ | IBM Bob IDE agent |
GitHub Copilot requires a unique file structure with paired command definitions:
.github/
├── agents/
│ └── speckit-command-name.agent.md # Agent definition with mode field
└── prompts/
└── speckit-command-name.prompt.md # Prompt template
The mode field in .agent.md files follows the pattern speckit.command-name and enables Copilot Chat mode integration.
Sources: src/specify_cli/__init__.py127-132 src/specify_cli/__init__.py169-228 AGENTS.md332-354
The following diagram maps agent keys to their respective directory structures within initialized projects:
Sources: src/specify_cli/__init__.py126-229 src/specify_cli/__init__.py751-898 src/specify_cli/__init__.py637-749
When --ai flag is omitted, the CLI presents an interactive arrow-key selection interface:
The select_with_arrows() function src/specify_cli/__init__.py350-423 creates a Rich Live display with arrow navigation, supporting ↑/↓, Ctrl+P/N, Enter, and Esc keys. The function uses readchar.readkey() src/specify_cli/__init__.py330-348 for cross-platform keyboard input detection.
Sources: src/specify_cli/__init__.py350-423 src/specify_cli/__init__.py1088-1093 src/specify_cli/__init__.py330-348
The specify check command src/specify_cli/__init__.py1281-1321 validates all registered agents and reports their availability:
The function uses a StepTracker src/specify_cli/__init__.py245-328 to provide hierarchical status output with visual indicators:
● (green) for tools found○ (dim green) for pending checks○ (yellow) for skipped checks● (red) for errorsSources: src/specify_cli/__init__.py1281-1321 src/specify_cli/__init__.py484-513 src/specify_cli/__init__.py245-328
Different agents use different command file formats and argument placeholder conventions:
| Format | Agents Using It | Argument Placeholder | File Extension |
|---|---|---|---|
| Markdown with YAML frontmatter | claude, opencode, codex, windsurf, q, amp, shai, auggie, codebuddy, cursor-agent, kilocode, roo | $ARGUMENTS | .md |
| TOML | gemini, qwen | {{args}} | .toml |
| Paired Markdown | copilot | $ARGUMENTS | .agent.md + .prompt.md |
The build pipeline performs the following replacements when generating agent-specific command files:
{SCRIPT} → Actual script file extension (sh or ps1){AGENT_SCRIPT} → Agent-specific script file extension$ARGUMENTS or {{args}} → Agent-appropriate argument syntax__AGENT__ → Actual agent keySources: AGENTS.md327-362 AGENTS.md371-379
Critical Design Principle: Agent keys in AGENT_CONFIG must match the actual executable name that users install, not a convenient shorthand. This eliminates the need for special-case mappings throughout the codebase.
The check_tool() function src/specify_cli/__init__.py484-513 directly uses the agent key with shutil.which(tool) to find executables in the system PATH. If the key doesn't match the actual CLI tool name, special-case mappings would be required throughout the codebase.
This design choice eliminates scattered conditional logic and makes the codebase more maintainable.
Sources: AGENTS.md209-256 src/specify_cli/__init__.py145-150 src/specify_cli/__init__.py484-513
Some agents require environment variables to be set before use:
| Agent | Variable | Purpose | Example |
|---|---|---|---|
codex | CODEX_HOME | Points to .codex/ directory | export CODEX_HOME=/path/to/project/.codex (Unix) or setx CODEX_HOME C:\path\to\project\.codex (Windows) |
The CLI provides setup instructions for required environment variables in the post-initialization output.
Sources: src/specify_cli/__init__.py1197-1206
When CLI tool validation fails for a required agent, the system displays a detailed error panel:
The --ignore-agent-tools flag allows initialization to proceed without tool validation, useful for CI/CD environments or when installing agents after project setup.
Sources: src/specify_cli/__init__.py1053-1064 src/specify_cli/__init__.py938
Refresh this wiki