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	cursor-agent	Cursor CLI
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 (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)
IBM Bob	.bob/commands/	Markdown	N/A (IDE-based)	IBM Bob IDE
Trae	.trae/rules/	Markdown	N/A (IDE-based)	Trae IDE
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
• Cursor: cursor-agent CLI
• Qwen Code: qwen CLI
• opencode: opencode CLI
• Junie: junie CLI
• Kiro CLI: kiro-cli CLI
• CodeBuddy CLI: codebuddy CLI
• Qoder CLI: qodercli CLI
• Amp: amp CLI
• SHAI: shai CLI
• Tabnine CLI: tabnine CLI
• Kimi Code: kimi CLI
• Pi Coding Agent: pi CLI

IDE-Based Agents

Work within integrated development environments:

• GitHub Copilot: Built into VS Code/compatible editors
• Windsurf: Built into Windsurf IDE
• IBM Bob: Built into IBM Bob IDE

Command File Formats

Markdown Format

Used by: Claude, Cursor, opencode, Windsurf, Junie, Kiro CLI, Amp, SHAI, IBM Bob, Kimi Code, Qwen, Pi

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/
• Skills-based exceptions:
  • Codex: .agents/skills/ (skills, invoked as $speckit-<command>)
• Prompt-based exceptions:
  • Kiro CLI: .kiro/prompts/
  • Pi: .pi/prompts/
• IDE agents: Follow IDE-specific patterns:
  • Copilot: .github/agents/
  • Cursor: .cursor/commands/
  • Windsurf: .windsurf/workflows/

Argument Patterns

Different agents use different argument placeholders:

• Markdown/prompt-based: $ARGUMENTS
• TOML-based: {{args}}
• Script placeholders: {SCRIPT} (replaced with actual script path)
• Agent placeholders: __AGENT__ (replaced with agent name)

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

---

Agent Pack System (new)

The agent pack system is a declarative, self-contained replacement for the legacy AGENT_CONFIG + case/switch architecture. Each agent is defined by a speckit-agent.yml manifest and an optional bootstrap.py module. When bootstrap.py is absent, the built-in DefaultBootstrap class derives its directory layout from the manifest's commands_dir field.

--agent flag on specify init

specify init --agent <id> uses the pack-based init flow instead of the legacy --ai flow. Both accept the same agent IDs, but --agent additionally enables installed-file tracking so that specify agent switch can cleanly tear down agent files later.

specify init my-project --agent claude          # Pack-based flow (with file tracking)
specify init --here --agent gemini --ai-skills  # With skills

--agent and --ai are mutually exclusive. When --agent is used, init-options.json gains "agent_pack": true. The generic agent (which requires --ai-commands-dir) falls through to the legacy flow since it has no embedded pack.

specify agent subcommands

Command	Description
specify agent list	List all available agent packs
specify agent list --installed	List only agents installed in the current project
specify agent info <id>	Show detailed information about an agent pack
specify agent switch <id>	Switch the active agent (tears down old, sets up new)
specify agent search [query]	Search agents by name, ID, description, or tags
specify agent validate <path>	Validate an agent pack directory
specify agent export <id>	Export an agent pack for editing
specify agent add <id>	Install an agent pack from a local path
specify agent remove <id>	Remove a cached/override agent pack

Pack resolution order

Agent packs resolve by priority (highest first):

1. User-level (~/.specify/agents/<id>/) — applies to all projects
2. Project-level (.specify/agents/<id>/) — project-specific override
3. Catalog cache (downloaded via specify agent add)
4. Embedded (bundled in the specify-cli wheel)

Trust boundary

Agent packs can include a bootstrap.py module that is dynamically imported and executed. Pack authors can run arbitrary code through this mechanism. Only install packs from trusted sources. The 4-level resolution stack means that placing a pack in any of the resolution directories causes its code to run when the agent is loaded.

Installed-file tracking

When using --agent, all installed files are recorded in .specify/agent-manifest-<id>.json with SHA-256 hashes. During specify agent switch, the CLI:

1. Checks for user-modified files before teardown
2. Prompts for confirmation if files were changed
3. Feeds tracked file lists into teardown for precise, file-level removal (directories are never deleted)

---

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