This document explains the multi-agent architecture that enables Spec Kit to support 16+ AI coding assistants with heterogeneous conventions. It covers format variations (Markdown vs TOML), directory structure patterns, placeholder conventions, and the adapter pattern that transforms a single command template into agent-specific files across all platforms.
For information about the AGENT_CONFIG registry and agent metadata, see Agent Configuration System. For details about updating agent context files with project information, see Agent Context Management. For the complete list of supported agents and their characteristics, see Supported AI Agents.
The system must accommodate two fundamentally different command file formats used by various AI agents.
Agents using Markdown format include Claude Code, Cursor, opencode, GitHub Copilot, Windsurf, Kilo Code, Roo Code, CodeBuddy, Qoder, Amazon Q Developer, Amp, SHAI, and IBM Bob.
Standard Markdown Structure:
GitHub Copilot Chat Mode Variant:
The GitHub Copilot format includes an additional mode field in the YAML frontmatter that specifies the command invocation pattern.
Agents using TOML format include Gemini CLI and Qwen Code.
TOML Structure:
The TOML format separates the description field from the prompt body and uses a different placeholder syntax for arguments.
| Agent Category | Script Placeholder | Arguments Placeholder | Agent Name Placeholder |
|---|---|---|---|
| Markdown agents | {SCRIPT} | $ARGUMENTS | __AGENT__ |
| TOML agents | {SCRIPT} | {{args}} | __AGENT__ |
| All agents | {SCRIPT} (replaced with actual script path) | Varies by format | __AGENT__ (replaced with agent name) |
Sources: AGENTS.md329-383
Each agent follows a specific directory convention for storing command files. The system must generate files in the correct location for each agent.
Directory Convention Patterns:
| Pattern | Agents | Example |
|---|---|---|
.<agent>/commands/ | Claude, Cursor, Gemini, Qwen, opencode, Codex, CodeBuddy, Qoder, IBM Bob | .claude/commands/, .cursor/commands/ |
.<agent>/workflows/ | Windsurf | .windsurf/workflows/ |
.<agent>/rules/ | Kilo Code, Auggie, Roo Code | .kilocode/rules/, .augment/rules/ |
.<agent>/prompts/ | Amazon Q Developer | .amazonq/prompts/ |
.github/agents/ | GitHub Copilot | .github/agents/ |
.agents/commands/ | Amp | .agents/commands/ |
The folder field in AGENT_CONFIG src/specify_cli/__init__.py63-87 defines the base directory for each agent. Command generation scripts must create the full path including subdirectories.
Sources: AGENTS.md32-50 AGENTS.md367-374
The system transforms a single command template into agent-specific files through a multi-stage processing pipeline.
The generate_commands() function in the release script .github/workflows/scripts/create-release-packages.sh50-110 implements the processing pipeline:
Processing Steps:
templates/commands/{SCRIPT} → Actual script path (bash or PowerShell)__AGENT__ → Agent display name$ARGUMENTS placeholderdescription and prompt fields, use {{args}} placeholderCase Statement for Agent-Specific Generation:
Sources: .github/workflows/scripts/create-release-packages.sh50-150 AGENTS.md329-366
The AGENT_CONFIG dictionary serves as the single source of truth for all agent metadata, eliminating scattered configuration and special-case mappings.
| Field | Type | Purpose | Example |
|---|---|---|---|
name | str | Human-readable display name | "Claude Code" |
folder | str | Base directory for agent files | ".claude/" |
install_url | str or None | Installation documentation URL | "https://claude.ai/cli" or None |
requires_cli | bool | Whether CLI tool check is required | True for CLI agents, False for IDE agents |
The dictionary key MUST match the actual executable name. This eliminates the need for special-case mappings throughout the codebase.
Example from Cursor:
❌ Wrong approach (creates maintenance burden):
✅ Correct approach (no mapping needed):
The check_tool() function uses shutil.which(tool) to find executables in the system PATH src/specify_cli/__init__.py100-120 If the key doesn't match the actual CLI tool name, the check will fail or require special-case mappings.
Sources: AGENTS.md56-87 AGENTS.md208-249 src/specify_cli/__init__.py63-87
The context management scripts update agent-specific files with project information extracted from plan.md, ensuring agents receive current tech stack and dependency information.
The Bash script scripts/bash/update-agent-context.sh1-150 defines file variables for each agent:
Agent-Specific Update Logic:
The PowerShell script scripts/powershell/update-agent-context.ps11-180 uses similar logic with PowerShell syntax:
Sources: scripts/bash/update-agent-context.sh20-150 scripts/powershell/update-agent-context.ps120-180 AGENTS.md140-188
The system differentiates between CLI-based and IDE-based agents, which have different installation and validation requirements.
| Category | Characteristic | Tool Check Required | Examples |
|---|---|---|---|
| CLI-based | Requires command-line tool installation | Yes (requires_cli: True) | Claude Code (claude), Gemini CLI (gemini), Cursor (cursor-agent) |
| IDE-based | Built into IDE, no separate tool | No (requires_cli: False) | GitHub Copilot, Windsurf, Kilo Code, IBM Bob |
| Agent | CLI Tool | Install URL | Directory |
|---|---|---|---|
| Claude Code | claude | https://claude.ai/cli | .claude/ |
| Gemini CLI | gemini | https://ai.google.dev/gemini-api/docs/cli | .gemini/ |
| Cursor | cursor-agent | https://cursor.sh/ | .cursor/ |
| Qwen Code | qwen | https://qwenlm.github.io/ | .qwen/ |
| opencode | opencode | https://opencode.ai/ | .opencode/ |
| Codex CLI | codex | https://codex.io/ | .codex/ |
| Auggie CLI | auggie | https://augment.dev/ | .augment/ |
| CodeBuddy CLI | codebuddy | https://codebuddy.ai/ | .codebuddy/ |
| Qoder CLI | qoder | https://qoder.ai/ | .qoder/ |
| Amazon Q Developer CLI | q | https://aws.amazon.com/q/ | .amazonq/ |
| Amp | amp | https://amp.dev/ | .agents/ |
| SHAI | shai | https://shai.ai/ | .shai/ |
| Agent | IDE/Extension | Installation Method | Directory |
|---|---|---|---|
| GitHub Copilot | VS Code extension | VS Code marketplace | .github/ |
| Windsurf | Windsurf IDE | Download IDE installer | .windsurf/ |
| Kilo Code | Kilo Code IDE | Download IDE installer | .kilocode/ |
| Roo Code | Roo Code IDE | Download IDE installer | .roo/ |
| IBM Bob | IBM Bob IDE | Download IDE installer | .bob/ |
The requires_cli field in AGENT_CONFIG src/specify_cli/__init__.py86 determines whether the CLI tool check is performed during specify init and specify check commands. This field is automatically consulted by the validation logic src/specify_cli/__init__.py200-220 eliminating the need for hardcoded agent lists.
Sources: AGENTS.md303-326 AGENTS.md32-50
The process for integrating a new AI agent involves updating multiple files across the codebase to ensure consistent support.
Step 1: Update AGENT_CONFIG src/specify_cli/__init__.py63-87
Step 2: Update CLI Help Text src/specify_cli/__init__.py150-160
Step 3: Update Release Script .github/workflows/scripts/create-release-packages.sh20-30
Step 4: Update Context Scripts scripts/bash/update-agent-context.sh20-50
| Pitfall | Impact | Solution |
|---|---|---|
| Using shorthand keys instead of actual CLI tool names | Tool checks fail, requires special-case mappings | Always use exact executable name in AGENT_CONFIG key |
| Forgetting to update both Bash and PowerShell scripts | Context updates fail on one platform | Update both update-agent-context.sh and .ps1 |
Incorrect requires_cli value | Unnecessary tool checks or missing validations | Set True only for agents with CLI tools |
| Wrong argument placeholder format | Generated commands don't work | Use $ARGUMENTS for Markdown, {{args}} for TOML |
| Incorrect directory naming | Files created in wrong location | Follow exact agent conventions from AGENT_CONFIG |
| Inconsistent help text | Confusing user experience | Update all user-facing text consistently |
Sources: AGENTS.md52-410 src/specify_cli/__init__.py63-87
| Benefit | Description |
|---|---|
| Write once, deploy everywhere | Single command template generates files for 16+ agents |
| Centralized configuration | AGENT_CONFIG eliminates scattered agent metadata |
| Format abstraction | System handles Markdown vs TOML conversion automatically |
| Extensibility | Adding new agents requires no changes to core templates |
| Maintainability | Changes to commands propagate to all agents automatically |
| Aspect | Trade-off |
|---|---|
| Code generation | Adds build complexity but enables multi-agent support |
| Multiple scripts | Bash + PowerShell duplication for cross-platform support |
| Testing burden | Must verify command generation for all agent × format combinations |
| Release pipeline | 32 package variants (16 agents × 2 script types) increase CI/CD time |
The architecture enforces several constraints that maintain system consistency:
Sources: AGENTS.md208-249 AGENTS.md390-410
Refresh this wiki