diff --git a/AGENTS.md b/AGENTS.md index eb3d27065..8dc0b7d21 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,276 +10,278 @@ The toolkit supports multiple AI coding assistants, allowing teams to use their --- -## 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) | -| **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: +## Integration Architecture -```python -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 - }, -} +Each AI agent is a self-contained **integration subpackage** under `src/specify_cli/integrations//`. The package exposes a single class that declares all metadata, inherits setup/teardown logic from a base class, and registers itself in the global `INTEGRATION_REGISTRY` at import time. + +``` +src/specify_cli/integrations/ +├── __init__.py # INTEGRATION_REGISTRY + _register_builtins() +├── base.py # IntegrationBase, MarkdownIntegration, TomlIntegration, SkillsIntegration +├── manifest.py # IntegrationManifest (file tracking) +├── claude/ # Example: SkillsIntegration subclass +│ ├── __init__.py # ClaudeIntegration class +│ └── scripts/ # Thin wrapper scripts +│ ├── update-context.sh +│ └── update-context.ps1 +├── gemini/ # Example: TomlIntegration subclass +│ ├── __init__.py +│ └── scripts/ +├── windsurf/ # Example: MarkdownIntegration subclass +│ ├── __init__.py +│ └── scripts/ +├── copilot/ # Example: IntegrationBase subclass (custom setup) +│ ├── __init__.py +│ └── scripts/ +└── ... # One subpackage per supported agent ``` -**Key Design Principle**: The dictionary key should match the actual executable name that users install. For example: +The registry is the **single source of truth**. Supported agents, their directories, formats, and capabilities are all derived from the integration classes — no separate tables or config dicts to maintain. + +--- + +## Adding a New Integration -- ✅ 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` +### 1. Choose a base class -This eliminates the need for special-case mappings throughout the codebase. +| Your agent needs… | Subclass | +|---|---| +| Standard markdown commands (`.md`) | `MarkdownIntegration` | +| TOML-format commands (`.toml`) | `TomlIntegration` | +| Skill directories (`speckit-/SKILL.md`) | `SkillsIntegration` | +| Fully custom output (companion files, settings merge, etc.) | `IntegrationBase` directly | -**Field Explanations**: +Most agents only need `MarkdownIntegration` — a minimal subclass with zero method overrides. -- `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. Create the subpackage -#### 2. Update CLI Help Text +Create `src/specify_cli/integrations//__init__.py`. The `key` **must match the actual CLI tool name** (the executable users install and run). Use a Python-safe directory name if the key contains hyphens (e.g., `kiro_cli/` for key `"kiro-cli"`). -Update the `--ai` parameter help text in the `init()` command to include the new agent: +**Minimal example — Markdown agent (Windsurf):** ```python -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"), -``` +"""Windsurf IDE integration.""" -Also update any function docstrings, examples, and error messages that list available agents. +from ..base import MarkdownIntegration -#### 3. Update README Documentation -Update the **Supported AI Agents** section in `README.md` to include the new agent: +class WindsurfIntegration(MarkdownIntegration): + key = "windsurf" + config = { + "name": "Windsurf", + "folder": ".windsurf/", + "commands_subdir": "workflows", + "install_url": None, + "requires_cli": False, + } + registrar_config = { + "dir": ".windsurf/workflows", + "format": "markdown", + "args": "$ARGUMENTS", + "extension": ".md", + } + context_file = ".windsurf/rules/specify-rules.md" +``` -- 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 +**TOML agent (Gemini):** -#### 4. Update Release Package Script +```python +"""Gemini CLI integration.""" -Modify `.github/workflows/scripts/create-release-packages.sh`: +from ..base import TomlIntegration -##### Add to ALL_AGENTS array -```bash -ALL_AGENTS=(claude gemini copilot cursor-agent qwen opencode windsurf kiro-cli) +class GeminiIntegration(TomlIntegration): + key = "gemini" + config = { + "name": "Gemini CLI", + "folder": ".gemini/", + "commands_subdir": "commands", + "install_url": "https://github.com/google-gemini/gemini-cli", + "requires_cli": True, + } + registrar_config = { + "dir": ".gemini/commands", + "format": "toml", + "args": "{{args}}", + "extension": ".toml", + } + context_file = "GEMINI.md" ``` -##### Add case statement for directory structure +**Skills agent (Codex):** -```bash -case $agent in - # ... existing cases ... - windsurf) - mkdir -p "$base_dir/.windsurf/workflows" - generate_commands windsurf md "\$ARGUMENTS" "$base_dir/.windsurf/workflows" "$script" ;; -esac -``` +```python +"""Codex CLI integration — skills-based agent.""" -#### 4. Update GitHub Release Script +from __future__ import annotations -Modify `.github/workflows/scripts/create-github-release.sh` to include the new agent's packages: +from ..base import IntegrationOption, SkillsIntegration -```bash -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 + +class CodexIntegration(SkillsIntegration): + key = "codex" + config = { + "name": "Codex CLI", + "folder": ".agents/", + "commands_subdir": "skills", + "install_url": "https://github.com/openai/codex", + "requires_cli": True, + } + registrar_config = { + "dir": ".agents/skills", + "format": "markdown", + "args": "$ARGUMENTS", + "extension": "/SKILL.md", + } + context_file = "AGENTS.md" + + @classmethod + def options(cls) -> list[IntegrationOption]: + return [ + IntegrationOption( + "--skills", + is_flag=True, + default=True, + help="Install as agent skills (default for Codex)", + ), + ] ``` -#### 5. Update Agent Context Scripts +#### Required fields -##### Bash script (`scripts/bash/update-agent-context.sh`) +| Field | Location | Purpose | +|---|---|---| +| `key` | Class attribute | Unique identifier; must match the CLI executable name | +| `config` | Class attribute (dict) | Agent metadata: `name`, `folder`, `commands_subdir`, `install_url`, `requires_cli` | +| `registrar_config` | Class attribute (dict) | Command output config: `dir`, `format`, `args` placeholder, file `extension` | +| `context_file` | Class attribute (str or None) | Path to agent context/instructions file (e.g., `"CLAUDE.md"`, `".github/copilot-instructions.md"`) | -Add file variable: +**Key design rule:** `key` must be the actual executable name (e.g., `"cursor-agent"` not `"cursor"`). This ensures `shutil.which(key)` works for CLI-tool checks without special-case mappings. -```bash -WINDSURF_FILE="$REPO_ROOT/.windsurf/rules/specify-rules.md" -``` +### 3. Register it -Add to case statement: +In `src/specify_cli/integrations/__init__.py`, add one import and one `_register()` call inside `_register_builtins()`. Both lists are alphabetical: -```bash -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 +```python +def _register_builtins() -> None: + # -- Imports (alphabetical) ------------------------------------------- + from .claude import ClaudeIntegration + # ... + from .newagent import NewAgentIntegration # ← add import + # ... + + # -- Registration (alphabetical) -------------------------------------- + _register(ClaudeIntegration()) + # ... + _register(NewAgentIntegration()) # ← add registration + # ... ``` -##### PowerShell script (`scripts/powershell/update-agent-context.ps1`) +### 4. Add scripts -Add file variable: +Create two thin wrapper scripts in `src/specify_cli/integrations//scripts/` that delegate to the shared context-update scripts. Each is ~25 lines of boilerplate. -```powershell -$windsurfFile = Join-Path $repoRoot '.windsurf/rules/specify-rules.md' +**`update-context.sh`:** + +```bash +#!/usr/bin/env bash +# update-context.sh — integration: create/update +set -euo pipefail + +_script_dir="$(cd "$(dirname "$0")" && pwd)" +_root="$_script_dir" +while [ "$_root" != "/" ] && [ ! -d "$_root/.specify" ]; do _root="$(dirname "$_root")"; done +if [ -z "${REPO_ROOT:-}" ]; then + if [ -d "$_root/.specify" ]; then + REPO_ROOT="$_root" + else + git_root="$(git rev-parse --show-toplevel 2>/dev/null || true)" + if [ -n "$git_root" ] && [ -d "$git_root/.specify" ]; then + REPO_ROOT="$git_root" + else + REPO_ROOT="$_root" + fi + fi +fi + +exec "$REPO_ROOT/.specify/scripts/bash/update-agent-context.sh" ``` -Add to switch statement: +**`update-context.ps1`:** ```powershell -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 +# update-context.ps1 — integration: create/update +$ErrorActionPreference = 'Stop' + +$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Definition +$repoRoot = try { git rev-parse --show-toplevel 2>$null } catch { $null } +if (-not $repoRoot -or -not (Test-Path (Join-Path $repoRoot '.specify'))) { + $repoRoot = $scriptDir + $fsRoot = [System.IO.Path]::GetPathRoot($repoRoot) + while ($repoRoot -and $repoRoot -ne $fsRoot -and -not (Test-Path (Join-Path $repoRoot '.specify'))) { + $repoRoot = Split-Path -Parent $repoRoot } } -``` - -#### 6. Update CLI Tool Checks (Optional) -For agents that require CLI tools, add checks in the `check()` command and agent validation: - -```python -# 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 +& "$repoRoot/.specify/scripts/powershell/update-agent-context.ps1" -AgentType ``` -**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 +Replace `` with your integration key and `` / `` with the appropriate values. -### Using Actual CLI Tool Names as Keys +You must also add the agent to the shared context-update scripts so the shared dispatcher recognises the new key: -**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. +- **`scripts/bash/update-agent-context.sh`** — add a file-path variable and a case in `update_specific_agent()`. +- **`scripts/powershell/update-agent-context.ps1`** — add a file-path variable, a switch case in `Update-SpecificAgent`, and an entry in `Update-AllExistingAgents`. -**Why this matters:** +### 5. Test it -- 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 +```bash +# Install into a test project +specify init my-project --integration -**Example - The Cursor Lesson:** +# Verify files were created +ls -R my-project// -❌ **Wrong approach** (requires special-case mapping): +# Uninstall cleanly +cd my-project && specify integration uninstall +``` -```python -AGENT_CONFIG = { - "cursor": { # Shorthand that doesn't match the actual tool - "name": "Cursor", - # ... - } -} +Each integration also has a dedicated test file at `tests/integrations/test_integration_.py`. Run it with: -# Then you need special cases everywhere: -cli_tool = agent_key -if agent_key == "cursor": - cli_tool = "cursor-agent" # Map to the real tool name +```bash +pytest tests/integrations/test_integration_.py -v ``` -✅ **Correct approach** (no mapping needed): +### 6. Optional overrides -```python -AGENT_CONFIG = { - "cursor-agent": { # Matches the actual executable name - "name": "Cursor", - # ... - } -} +The base classes handle most work automatically. Override only when the agent deviates from standard patterns: -# No special cases needed - just use agent_key directly! -``` +| Override | When to use | Example | +|---|---|---| +| `command_filename(template_name)` | Custom file naming or extension | Copilot → `speckit.{name}.agent.md` | +| `options()` | Integration-specific CLI flags via `--integration-options` | Codex → `--skills` flag | +| `setup()` | Custom install logic (companion files, settings merge) | Copilot → `.agent.md` + `.prompt.md` + `.vscode/settings.json` | +| `teardown()` | Custom uninstall logic | Rarely needed; base handles manifest-tracked files | -**Benefits of this approach:** +**Example — Copilot (fully custom `setup`):** -- 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 +Copilot extends `IntegrationBase` directly because it creates `.agent.md` commands, companion `.prompt.md` files, and merges `.vscode/settings.json`. See `src/specify_cli/integrations/copilot/__init__.py` for the full implementation. -#### 7. Update Devcontainer files (Optional) +### 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 +#### VS Code Extension-based Agents For agents available as VS Code extensions, add them to `.devcontainer/devcontainer.json`: -```json +```jsonc { "customizations": { "vscode": { "extensions": [ // ... existing extensions ... - // [New Agent Name] "[New Agent Extension ID]" ] } @@ -287,7 +289,7 @@ For agents available as VS Code extensions, add them to `.devcontainer/devcontai } ``` -##### CLI-based Agents +#### CLI-based Agents For agents that require CLI tools, add installation commands to `.devcontainer/post-create.sh`: @@ -297,62 +299,16 @@ For agents that require CLI tools, add installation commands to `.devcontainer/p # 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)... +# run_command "npm install -g [agent-cli-package]@latest" 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 - -### 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 - **Standard format:** ```markdown @@ -376,8 +332,6 @@ Command content with {SCRIPT} and $ARGUMENTS placeholders. ### TOML Format -Used by: Gemini, Tabnine - ```toml description = "Command description" @@ -386,33 +340,6 @@ Command content with {SCRIPT} and {{args}} placeholders. """ ``` -## Directory Conventions - -- **CLI agents**: Usually `./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-`) -- **Skills-based exceptions**: - - Kimi Code: `.kimi/skills/` (skills, invoked as `/skill:speckit-`) -- **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: @@ -422,33 +349,14 @@ Different agents use different argument placeholders: - **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 ` 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 +1. **Using shorthand keys instead of actual CLI tool names**: The integration `key` must match the executable name (e.g., `"cursor-agent"` not `"cursor"`). `shutil.which(key)` is used for CLI tool checks — mismatches require special-case mappings. +2. **Forgetting update scripts**: Both bash and PowerShell thin wrappers and the shared context-update scripts must be updated. +3. **Incorrect `requires_cli` value**: Set to `True` only for agents that have a CLI tool; set to `False` for IDE-based agents. +4. **Wrong argument format**: Use `$ARGUMENTS` for Markdown agents, `{{args}}` for TOML agents. +5. **Skipping registration**: The import and `_register()` call in `_register_builtins()` must both be added. --- -*This documentation should be updated whenever new agents are added to maintain accuracy and completeness.* +*This documentation should be updated whenever new integrations are added to maintain accuracy and completeness.*