github-spec-kit/AGENTS.md

AGENTS.md

About Spec Kit and Specify

GitHub Spec Kit is a comprehensive toolkit for implementing Spec-Driven Development (SDD) - a methodology that emphasizes creating clear specifications before implementation. The toolkit includes templates, scripts, and workflows that guide development teams through a structured approach to building software.

Specify CLI is the command-line interface that bootstraps projects with the Spec Kit framework. It sets up the necessary directory structures, templates, and AI agent integrations to support the Spec-Driven Development workflow.

The toolkit supports multiple AI coding assistants, allowing teams to use their preferred tools while maintaining consistent project structure and development practices.

---

Adding New Agent Support

This section explains how to add support for new AI agents/assistants to the Specify CLI. Use this guide as a reference when integrating new AI tools into the Spec-Driven Development workflow.

Overview

Specify supports multiple AI agents by generating agent-specific command files and directory structures when initializing projects. Each agent has its own conventions for:

• Command file formats (Markdown, TOML, etc.)
• Directory structures (.claude/commands/, .windsurf/workflows/, etc.)
• Command invocation patterns (slash commands, CLI tools, etc.)
• Argument passing conventions ($ARGUMENTS, {{args}}, etc.)

Current Supported Agents

Agent	Directory	Format	CLI Tool	Description
Claude Code	.claude/commands/	Markdown	claude	Anthropic's Claude Code CLI
Gemini CLI	.gemini/commands/	TOML	gemini	Google's Gemini CLI
GitHub Copilot	.github/agents/	Markdown	N/A (IDE-based)	GitHub Copilot in VS Code
Cursor	.cursor/commands/	Markdown	N/A (IDE-based)	Cursor IDE (--ai cursor-agent)
Qwen Code	.qwen/commands/	Markdown	qwen	Alibaba's Qwen Code CLI
opencode	.opencode/command/	Markdown	opencode	opencode CLI
Codex CLI	.agents/skills/	Markdown	codex	Codex CLI (--ai codex --ai-skills)
Windsurf	.windsurf/workflows/	Markdown	N/A (IDE-based)	Windsurf IDE workflows
Junie	.junie/commands/	Markdown	junie	Junie by JetBrains
Kilo Code	.kilocode/workflows/	Markdown	N/A (IDE-based)	Kilo Code IDE
Auggie CLI	.augment/commands/	Markdown	auggie	Auggie CLI
Roo Code	.roo/commands/	Markdown	N/A (IDE-based)	Roo Code IDE
CodeBuddy CLI	.codebuddy/commands/	Markdown	codebuddy	CodeBuddy CLI
Qoder CLI	.qoder/commands/	Markdown	qodercli	Qoder CLI
Kiro CLI	.kiro/prompts/	Markdown	kiro-cli	Kiro CLI
Amp	.agents/commands/	Markdown	amp	Amp CLI
SHAI	.shai/commands/	Markdown	shai	SHAI CLI
Tabnine CLI	.tabnine/agent/commands/	TOML	tabnine	Tabnine CLI
Kimi Code	.kimi/skills/	Markdown	kimi	Kimi Code CLI (Moonshot AI)
Pi Coding Agent	.pi/prompts/	Markdown	pi	Pi terminal coding agent
iFlow CLI	.iflow/commands/	Markdown	iflow	iFlow CLI (iflow-ai)
Forge	.forge/commands/	Markdown	forge	Forge CLI (forgecode.dev)
IBM Bob	.bob/commands/	Markdown	N/A (IDE-based)	IBM Bob IDE
Trae	.trae/rules/	Markdown	N/A (IDE-based)	Trae IDE
Antigravity	.agent/commands/	Markdown	N/A (IDE-based)	Antigravity IDE (--ai agy --ai-skills)
Mistral Vibe	.vibe/prompts/	Markdown	vibe	Mistral Vibe CLI
Generic	User-specified via --ai-commands-dir	Markdown	N/A	Bring your own agent

Step-by-Step Integration Guide

Follow these steps to add a new agent (using a hypothetical new agent as an example):

1. Add to AGENT_CONFIG

IMPORTANT: Use the actual CLI tool name as the key, not a shortened version.

Add the new agent to the AGENT_CONFIG dictionary in src/specify_cli/__init__.py. This is the single source of truth for all agent metadata:

AGENT_CONFIG = {
    # ... existing agents ...
    "new-agent-cli": {  # Use the ACTUAL CLI tool name (what users type in terminal)
        "name": "New Agent Display Name",
        "folder": ".newagent/",  # Directory for agent files
        "commands_subdir": "commands",  # Subdirectory name for command files (default: "commands")
        "install_url": "https://example.com/install",  # URL for installation docs (or None if IDE-based)
        "requires_cli": True,  # True if CLI tool required, False for IDE-based agents
    },
}

Key Design Principle: The dictionary key should match the actual executable name that users install. For example:

• ✅ Use "cursor-agent" because the CLI tool is literally called cursor-agent
• ❌ Don't use "cursor" as a shortcut if the tool is cursor-agent

This eliminates the need for special-case mappings throughout the codebase.

Field Explanations:

• name: Human-readable display name shown to users
• folder: Directory where agent-specific files are stored (relative to project root)
• commands_subdir: Subdirectory name within the agent folder where command/prompt files are stored (default: "commands")
  • Most agents use "commands" (e.g., .claude/commands/)
  • Some agents use alternative names: "agents" (copilot), "workflows" (windsurf, kilocode), "prompts" (codex, kiro-cli, pi), "command" (opencode - singular)
  • This field enables --ai-skills to locate command templates correctly for skill generation
• install_url: Installation documentation URL (set to None for IDE-based agents)
• requires_cli: Whether the agent requires a CLI tool check during initialization

2. Update CLI Help Text

Update the --ai parameter help text in the init() command to include the new agent:

ai_assistant: str = typer.Option(None, "--ai", help="AI assistant to use: claude, gemini, copilot, cursor-agent, qwen, opencode, codex, windsurf, kilocode, auggie, codebuddy, new-agent-cli, or kiro-cli"),

Also update any function docstrings, examples, and error messages that list available agents.

3. Update README Documentation

Update the Supported AI Agents section in README.md to include the new agent:

• Add the new agent to the table with appropriate support level (Full/Partial)
• Include the agent's official website link
• Add any relevant notes about the agent's implementation
• Ensure the table formatting remains aligned and consistent

4. Update Release Package Script

Modify .github/workflows/scripts/create-release-packages.sh:

Add to ALL_AGENTS array

ALL_AGENTS=(claude gemini copilot cursor-agent qwen opencode windsurf kiro-cli)

Add case statement for directory structure

case $agent in
  # ... existing cases ...
  windsurf)
    mkdir -p "$base_dir/.windsurf/workflows"
    generate_commands windsurf md "\$ARGUMENTS" "$base_dir/.windsurf/workflows" "$script" ;;
esac

4. Update GitHub Release Script

Modify .github/workflows/scripts/create-github-release.sh to include the new agent's packages:

gh release create "$VERSION" \
  # ... existing packages ...
  .genreleases/spec-kit-template-windsurf-sh-"$VERSION".zip \
  .genreleases/spec-kit-template-windsurf-ps-"$VERSION".zip \
  # Add new agent packages here

5. Update Agent Context Scripts

Bash script (scripts/bash/update-agent-context.sh)

Add file variable:

WINDSURF_FILE="$REPO_ROOT/.windsurf/rules/specify-rules.md"

Add to case statement:

case "$AGENT_TYPE" in
  # ... existing cases ...
  windsurf) update_agent_file "$WINDSURF_FILE" "Windsurf" ;;
  "")
    # ... existing checks ...
    [ -f "$WINDSURF_FILE" ] && update_agent_file "$WINDSURF_FILE" "Windsurf";
    # Update default creation condition
    ;;
esac

PowerShell script (scripts/powershell/update-agent-context.ps1)

Add file variable:

$windsurfFile = Join-Path $repoRoot '.windsurf/rules/specify-rules.md'

Add to switch statement:

switch ($AgentType) {
    # ... existing cases ...
    'windsurf' { Update-AgentFile $windsurfFile 'Windsurf' }
    '' {
        foreach ($pair in @(
            # ... existing pairs ...
            @{file=$windsurfFile; name='Windsurf'}
        )) {
            if (Test-Path $pair.file) { Update-AgentFile $pair.file $pair.name }
        }
        # Update default creation condition
    }
}

6. Update CLI Tool Checks (Optional)

For agents that require CLI tools, add checks in the check() command and agent validation:

# In check() command
tracker.add("windsurf", "Windsurf IDE (optional)")
windsurf_ok = check_tool_for_tracker("windsurf", "https://windsurf.com/", tracker)

# In init validation (only if CLI tool required)
elif selected_ai == "windsurf":
    if not check_tool("windsurf", "Install from: https://windsurf.com/"):
        console.print("[red]Error:[/red] Windsurf CLI is required for Windsurf projects")
        agent_tool_missing = True

Note: CLI tool checks are now handled automatically based on the requires_cli field in AGENT_CONFIG. No additional code changes needed in the check() or init() commands - they automatically loop through AGENT_CONFIG and check tools as needed.

Important Design Decisions

Using Actual CLI Tool Names as Keys

CRITICAL: When adding a new agent to AGENT_CONFIG, always use the actual executable name as the dictionary key, not a shortened or convenient version.

Why this matters:

• The check_tool() function uses shutil.which(tool) to find executables in the system PATH
• If the key doesn't match the actual CLI tool name, you'll need special-case mappings throughout the codebase
• This creates unnecessary complexity and maintenance burden

Example - The Cursor Lesson:

❌ Wrong approach (requires special-case mapping):

AGENT_CONFIG = {
    "cursor": {  # Shorthand that doesn't match the actual tool
        "name": "Cursor",
        # ...
    }
}

# Then you need special cases everywhere:
cli_tool = agent_key
if agent_key == "cursor":
    cli_tool = "cursor-agent"  # Map to the real tool name

✅ Correct approach (no mapping needed):

AGENT_CONFIG = {
    "cursor-agent": {  # Matches the actual executable name
        "name": "Cursor",
        # ...
    }
}

# No special cases needed - just use agent_key directly!

Benefits of this approach:

• Eliminates special-case logic scattered throughout the codebase
• Makes the code more maintainable and easier to understand
• Reduces the chance of bugs when adding new agents
• Tool checking "just works" without additional mappings

7. Update Devcontainer files (Optional)

For agents that have VS Code extensions or require CLI installation, update the devcontainer configuration files:

VS Code Extension-based Agents

For agents available as VS Code extensions, add them to .devcontainer/devcontainer.json:

{
  "customizations": {
    "vscode": {
      "extensions": [
        // ... existing extensions ...
        // [New Agent Name]
        "[New Agent Extension ID]"
      ]
    }
  }
}

CLI-based Agents

For agents that require CLI tools, add installation commands to .devcontainer/post-create.sh:

#!/bin/bash

# Existing installations...

echo -e "\n🤖 Installing [New Agent Name] CLI..."
# run_command "npm install -g [agent-cli-package]@latest" # Example for node-based CLI
# or other installation instructions (must be non-interactive and compatible with Linux Debian "Trixie" or later)...
echo "✅ Done"

Quick Tips:

• Extension-based agents: Add to the extensions array in devcontainer.json
• CLI-based agents: Add installation scripts to post-create.sh
• Hybrid agents: May require both extension and CLI installation
• Test thoroughly: Ensure installations work in the devcontainer environment

Agent Categories

CLI-Based Agents

Require a command-line tool to be installed:

• Claude Code: claude CLI
• Gemini CLI: gemini CLI
• Qwen Code: qwen CLI
• opencode: opencode CLI
• Codex CLI: codex CLI (requires --ai-skills)
• Junie: junie CLI
• Auggie CLI: auggie CLI
• CodeBuddy CLI: codebuddy CLI
• Qoder CLI: qodercli CLI
• Kiro CLI: kiro-cli CLI
• Amp: amp CLI
• SHAI: shai CLI
• Tabnine CLI: tabnine CLI
• Kimi Code: kimi CLI
• Mistral Vibe: vibe CLI
• Pi Coding Agent: pi CLI
• iFlow CLI: iflow CLI
• Forge: forge CLI

IDE-Based Agents

Work within integrated development environments:

• GitHub Copilot: Built into VS Code/compatible editors
• Cursor: Built into Cursor IDE (--ai cursor-agent)
• Windsurf: Built into Windsurf IDE
• Kilo Code: Built into Kilo Code IDE
• Roo Code: Built into Roo Code IDE
• IBM Bob: Built into IBM Bob IDE
• Trae: Built into Trae IDE
• Antigravity: Built into Antigravity IDE (--ai agy --ai-skills)

Command File Formats

Markdown Format

Used by: Claude, Cursor, GitHub Copilot, opencode, Windsurf, Junie, Kiro CLI, Amp, SHAI, IBM Bob, Kimi Code, Qwen, Pi, Codex, Auggie, CodeBuddy, Qoder, Roo Code, Kilo Code, Trae, Antigravity, Mistral Vibe, iFlow, Forge

Standard format:

---
description: "Command description"
---

Command content with {SCRIPT} and $ARGUMENTS placeholders.

GitHub Copilot Chat Mode format:

---
description: "Command description"
mode: speckit.command-name
---

Command content with {SCRIPT} and $ARGUMENTS placeholders.

TOML Format

Used by: Gemini, Tabnine

description = "Command description"

prompt = """
Command content with {SCRIPT} and {{args}} placeholders.
"""

Directory Conventions

• CLI agents: Usually .<agent-name>/commands/
• Singular command exception:
  • opencode: .opencode/command/ (singular command, not commands)
• Nested path exception:
  • Tabnine: .tabnine/agent/commands/ (extra agent/ segment)
• Shared .agents/ folder:
  • Amp: .agents/commands/ (shared folder, not .amp/)
  • Codex: .agents/skills/ (shared folder; requires --ai-skills; invoked as $speckit-<command>)
• Skills-based exceptions:
  • Kimi Code: .kimi/skills/ (skills, invoked as /skill:speckit-<command>)
• Prompt-based exceptions:
  • Kiro CLI: .kiro/prompts/
  • Pi: .pi/prompts/
  • Mistral Vibe: .vibe/prompts/
• Rules-based exceptions:
  • Trae: .trae/rules/
• IDE agents: Follow IDE-specific patterns:
  • Copilot: .github/agents/
  • Cursor: .cursor/commands/
  • Windsurf: .windsurf/workflows/
  • Kilo Code: .kilocode/workflows/
  • Roo Code: .roo/commands/
  • IBM Bob: .bob/commands/
  • Antigravity: .agent/skills/ (--ai-skills required; .agent/commands/ is deprecated)

Argument Patterns

Different agents use different argument placeholders:

• Markdown/prompt-based: $ARGUMENTS
• TOML-based: {{args}}
• Forge-specific: {{parameters}} (uses custom parameter syntax)
• Script placeholders: {SCRIPT} (replaced with actual script path)
• Agent placeholders: __AGENT__ (replaced with agent name)

Special Processing Requirements

Some agents require custom processing beyond the standard template transformations:

Copilot Integration

GitHub Copilot has unique requirements:

• Commands use .agent.md extension (not .md)
• Each command gets a companion .prompt.md file in .github/prompts/
• Installs .vscode/settings.json with prompt file recommendations
• Context file lives at .github/copilot-instructions.md

Implementation: Extends IntegrationBase with custom setup() method that:

1. Processes templates with process_template()
2. Generates companion .prompt.md files
3. Merges VS Code settings

Forge Integration

Forge has special frontmatter and argument requirements:

• Uses {{parameters}} instead of $ARGUMENTS
• Strips handoffs frontmatter key (Forge-specific collaboration feature)
• Injects name field into frontmatter when missing

Implementation: Extends MarkdownIntegration with custom setup() method that:

1. Inherits standard template processing from MarkdownIntegration
2. Adds extra $ARGUMENTS → {{parameters}} replacement after template processing
3. Applies Forge-specific transformations via _apply_forge_transformations()
4. Strips handoffs frontmatter key
5. Injects missing name fields
6. Ensures the shared update-agent-context.* scripts include a forge case that maps context updates to AGENTS.md (similar to opencode/codex/pi) and lists forge in their usage/help text

Standard Markdown Agents

Most agents (Bob, Claude, Windsurf, etc.) use MarkdownIntegration:

• Simple subclass with just key, config, registrar_config set
• Inherits standard processing from MarkdownIntegration.setup()
• No custom processing needed

Testing New Agent Integration

1. Build test: Run package creation script locally
2. CLI test: Test specify init --ai <agent> command
3. File generation: Verify correct directory structure and files
4. Command validation: Ensure generated commands work with the agent
5. Context update: Test agent context update scripts

Common Pitfalls

1. Using shorthand keys instead of actual CLI tool names: Always use the actual executable name as the AGENT_CONFIG key (e.g., "cursor-agent" not "cursor"). This prevents the need for special-case mappings throughout the codebase.
2. Forgetting update scripts: Both bash and PowerShell scripts must be updated when adding new agents.
3. Incorrect requires_cli value: Set to True only for agents that actually have CLI tools to check; set to False for IDE-based agents.
4. Wrong argument format: Use correct placeholder format for each agent type ($ARGUMENTS for Markdown, {{args}} for TOML).
5. Directory naming: Follow agent-specific conventions exactly (check existing agents for patterns).
6. Help text inconsistency: Update all user-facing text consistently (help strings, docstrings, README, error messages).

Future Considerations

When adding new agents:

• Consider the agent's native command/workflow patterns
• Ensure compatibility with the Spec-Driven Development process
• Document any special requirements or limitations
• Update this guide with lessons learned
• Verify the actual CLI tool name before adding to AGENT_CONFIG

---

This documentation should be updated whenever new agents are added to maintain accuracy and completeness.