|
| 1 | +# AGENTS.md |
| 2 | + |
| 3 | +## About Spec Kit and Specify |
| 4 | + |
| 5 | +**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. |
| 6 | + |
| 7 | +**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. |
| 8 | + |
| 9 | +The toolkit supports multiple AI coding assistants, allowing teams to use their preferred tools while maintaining consistent project structure and development practices. |
| 10 | + |
| 11 | +--- |
| 12 | + |
| 13 | +## Adding New Agent Support |
| 14 | + |
| 15 | +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. |
| 16 | + |
| 17 | +### Overview |
| 18 | + |
| 19 | +Specify supports multiple AI agents by generating agent-specific command files and directory structures when initializing projects. Each agent has its own conventions for: |
| 20 | + |
| 21 | +- **Command file formats** (Markdown, TOML, etc.) |
| 22 | +- **Directory structures** (`.claude/commands/`, `.windsurf/workflows/`, etc.) |
| 23 | +- **Command invocation patterns** (slash commands, CLI tools, etc.) |
| 24 | +- **Argument passing conventions** (`$ARGUMENTS`, `{{args}}`, etc.) |
| 25 | + |
| 26 | +### Current Supported Agents |
| 27 | + |
| 28 | +| Agent | Directory | Format | CLI Tool | Description | |
| 29 | +|-------|-----------|---------|----------|-------------| |
| 30 | +| **Claude Code** | `.claude/commands/` | Markdown | `claude` | Anthropic's Claude Code CLI | |
| 31 | +| **Gemini CLI** | `.gemini/commands/` | TOML | `gemini` | Google's Gemini CLI | |
| 32 | +| **GitHub Copilot** | `.github/prompts/` | Markdown | N/A (IDE-based) | GitHub Copilot in VS Code | |
| 33 | +| **Cursor** | `.cursor/commands/` | Markdown | `cursor-agent` | Cursor CLI | |
| 34 | +| **Qwen Code** | `.qwen/commands/` | TOML | `qwen` | Alibaba's Qwen Code CLI | |
| 35 | +| **opencode** | `.opencode/command/` | Markdown | `opencode` | opencode CLI | |
| 36 | +| **Windsurf** | `.windsurf/workflows/` | Markdown | N/A (IDE-based) | Windsurf IDE workflows | |
| 37 | + |
| 38 | +### Step-by-Step Integration Guide |
| 39 | + |
| 40 | +Follow these steps to add a new agent (using Windsurf as an example): |
| 41 | + |
| 42 | +#### 1. Update AI_CHOICES Constant |
| 43 | + |
| 44 | +Add the new agent to the `AI_CHOICES` dictionary in `src/specify_cli/__init__.py`: |
| 45 | + |
| 46 | +```python |
| 47 | +AI_CHOICES = { |
| 48 | + "copilot": "GitHub Copilot", |
| 49 | + "claude": "Claude Code", |
| 50 | + "gemini": "Gemini CLI", |
| 51 | + "cursor": "Cursor", |
| 52 | + "qwen": "Qwen Code", |
| 53 | + "opencode": "opencode", |
| 54 | + "windsurf": "Windsurf" # Add new agent here |
| 55 | +} |
| 56 | +``` |
| 57 | + |
| 58 | +#### 2. Update CLI Help Text |
| 59 | + |
| 60 | +Update all help text and examples to include the new agent: |
| 61 | + |
| 62 | +- Command option help: `--ai` parameter description |
| 63 | +- Function docstrings and examples |
| 64 | +- Error messages with agent lists |
| 65 | + |
| 66 | +#### 3. Update Release Package Script |
| 67 | + |
| 68 | +Modify `.github/workflows/scripts/create-release-packages.sh`: |
| 69 | + |
| 70 | +##### Add to ALL_AGENTS array: |
| 71 | +```bash |
| 72 | +ALL_AGENTS=(claude gemini copilot cursor qwen opencode windsurf) |
| 73 | +``` |
| 74 | + |
| 75 | +##### Add case statement for directory structure: |
| 76 | +```bash |
| 77 | +case $agent in |
| 78 | + # ... existing cases ... |
| 79 | + windsurf) |
| 80 | + mkdir -p "$base_dir/.windsurf/workflows" |
| 81 | + generate_commands windsurf md "\$ARGUMENTS" "$base_dir/.windsurf/workflows" "$script" ;; |
| 82 | +esac |
| 83 | +``` |
| 84 | + |
| 85 | +#### 4. Update Agent Context Scripts |
| 86 | + |
| 87 | +##### Bash script (`scripts/bash/update-agent-context.sh`): |
| 88 | + |
| 89 | +Add file variable: |
| 90 | +```bash |
| 91 | +WINDSURF_FILE="$REPO_ROOT/.windsurf/rules/specify-rules.md" |
| 92 | +``` |
| 93 | + |
| 94 | +Add to case statement: |
| 95 | +```bash |
| 96 | +case "$AGENT_TYPE" in |
| 97 | + # ... existing cases ... |
| 98 | + windsurf) update_agent_file "$WINDSURF_FILE" "Windsurf" ;; |
| 99 | + "") |
| 100 | + # ... existing checks ... |
| 101 | + [ -f "$WINDSURF_FILE" ] && update_agent_file "$WINDSURF_FILE" "Windsurf"; |
| 102 | + # Update default creation condition |
| 103 | + ;; |
| 104 | +esac |
| 105 | +``` |
| 106 | + |
| 107 | +##### PowerShell script (`scripts/powershell/update-agent-context.ps1`): |
| 108 | + |
| 109 | +Add file variable: |
| 110 | +```powershell |
| 111 | +$windsurfFile = Join-Path $repoRoot '.windsurf/rules/specify-rules.md' |
| 112 | +``` |
| 113 | + |
| 114 | +Add to switch statement: |
| 115 | +```powershell |
| 116 | +switch ($AgentType) { |
| 117 | + # ... existing cases ... |
| 118 | + 'windsurf' { Update-AgentFile $windsurfFile 'Windsurf' } |
| 119 | + '' { |
| 120 | + foreach ($pair in @( |
| 121 | + # ... existing pairs ... |
| 122 | + @{file=$windsurfFile; name='Windsurf'} |
| 123 | + )) { |
| 124 | + if (Test-Path $pair.file) { Update-AgentFile $pair.file $pair.name } |
| 125 | + } |
| 126 | + # Update default creation condition |
| 127 | + } |
| 128 | +} |
| 129 | +``` |
| 130 | + |
| 131 | +#### 5. Update CLI Tool Checks (Optional) |
| 132 | + |
| 133 | +For agents that require CLI tools, add checks in the `check()` command and agent validation: |
| 134 | + |
| 135 | +```python |
| 136 | +# In check() command |
| 137 | +tracker.add("windsurf", "Windsurf IDE (optional)") |
| 138 | +windsurf_ok = check_tool_for_tracker("windsurf", "https://windsurf.com/", tracker) |
| 139 | + |
| 140 | +# In init validation (only if CLI tool required) |
| 141 | +elif selected_ai == "windsurf": |
| 142 | + if not check_tool("windsurf", "Install from: https://windsurf.com/"): |
| 143 | + console.print("[red]Error:[/red] Windsurf CLI is required for Windsurf projects") |
| 144 | + agent_tool_missing = True |
| 145 | +``` |
| 146 | + |
| 147 | +**Note**: Skip CLI checks for IDE-based agents (Copilot, Windsurf). |
| 148 | + |
| 149 | +## Agent Categories |
| 150 | + |
| 151 | +### CLI-Based Agents |
| 152 | +Require a command-line tool to be installed: |
| 153 | +- **Claude Code**: `claude` CLI |
| 154 | +- **Gemini CLI**: `gemini` CLI |
| 155 | +- **Cursor**: `cursor-agent` CLI |
| 156 | +- **Qwen Code**: `qwen` CLI |
| 157 | +- **opencode**: `opencode` CLI |
| 158 | + |
| 159 | +### IDE-Based Agents |
| 160 | +Work within integrated development environments: |
| 161 | +- **GitHub Copilot**: Built into VS Code/compatible editors |
| 162 | +- **Windsurf**: Built into Windsurf IDE |
| 163 | + |
| 164 | +## Command File Formats |
| 165 | + |
| 166 | +### Markdown Format |
| 167 | +Used by: Claude, Cursor, opencode, Windsurf |
| 168 | + |
| 169 | +```markdown |
| 170 | +--- |
| 171 | +description: "Command description" |
| 172 | +--- |
| 173 | + |
| 174 | +Command content with {SCRIPT} and $ARGUMENTS placeholders. |
| 175 | +``` |
| 176 | + |
| 177 | +### TOML Format |
| 178 | +Used by: Gemini, Qwen |
| 179 | + |
| 180 | +```toml |
| 181 | +description = "Command description" |
| 182 | + |
| 183 | +prompt = """ |
| 184 | +Command content with {SCRIPT} and {{args}} placeholders. |
| 185 | +""" |
| 186 | +``` |
| 187 | + |
| 188 | +## Directory Conventions |
| 189 | + |
| 190 | +- **CLI agents**: Usually `.<agent-name>/commands/` |
| 191 | +- **IDE agents**: Follow IDE-specific patterns: |
| 192 | + - Copilot: `.github/prompts/` |
| 193 | + - Cursor: `.cursor/commands/` |
| 194 | + - Windsurf: `.windsurf/workflows/` |
| 195 | + |
| 196 | +## Argument Patterns |
| 197 | + |
| 198 | +Different agents use different argument placeholders: |
| 199 | +- **Markdown/prompt-based**: `$ARGUMENTS` |
| 200 | +- **TOML-based**: `{{args}}` |
| 201 | +- **Script placeholders**: `{SCRIPT}` (replaced with actual script path) |
| 202 | +- **Agent placeholders**: `__AGENT__` (replaced with agent name) |
| 203 | + |
| 204 | +## Testing New Agent Integration |
| 205 | + |
| 206 | +1. **Build test**: Run package creation script locally |
| 207 | +2. **CLI test**: Test `specify init --ai <agent>` command |
| 208 | +3. **File generation**: Verify correct directory structure and files |
| 209 | +4. **Command validation**: Ensure generated commands work with the agent |
| 210 | +5. **Context update**: Test agent context update scripts |
| 211 | + |
| 212 | +## Common Pitfalls |
| 213 | + |
| 214 | +1. **Forgetting update scripts**: Both bash and PowerShell scripts must be updated |
| 215 | +2. **Missing CLI checks**: Only add for agents that actually have CLI tools |
| 216 | +3. **Wrong argument format**: Use correct placeholder format for each agent type |
| 217 | +4. **Directory naming**: Follow agent-specific conventions exactly |
| 218 | +5. **Help text inconsistency**: Update all user-facing text consistently |
| 219 | + |
| 220 | +## Future Considerations |
| 221 | + |
| 222 | +When adding new agents: |
| 223 | +- Consider the agent's native command/workflow patterns |
| 224 | +- Ensure compatibility with the Spec-Driven Development process |
| 225 | +- Document any special requirements or limitations |
| 226 | +- Update this guide with lessons learned |
| 227 | + |
| 228 | +--- |
| 229 | + |
| 230 | +*This documentation should be updated whenever new agents are added to maintain accuracy and completeness.* |
0 commit comments