💫 Toolkit to help you get started with SDD or any other process!
Update with Windsurf support
Den Delimarsky 🌺0889635e6659
diff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlindex b90568cf6..c12f0ffa4 100644--- a/.github/workflows/release.yml+++ b/.github/workflows/release.yml@@ -81,7 +81,7 @@ jobs:cat > release_notes.md << EOFTemplate release ${{ steps.get_tag.outputs.new_version }}- Updated specification-driven development templates for GitHub Copilot, Claude Code, Gemini CLI, Cursor, Qwen, and opencode.+ Updated specification-driven development templates for GitHub Copilot, Claude Code, Gemini CLI, Cursor, Qwen, opencode, and Windsurf.Now includes per-script variants for POSIX shell (sh) and PowerShell (ps).@@ -98,6 +98,8 @@ jobs:- spec-kit-template-opencode-ps-${{ steps.get_tag.outputs.new_version }}.zip- spec-kit-template-qwen-sh-${{ steps.get_tag.outputs.new_version }}.zip- spec-kit-template-qwen-ps-${{ steps.get_tag.outputs.new_version }}.zip+ - spec-kit-template-windsurf-sh-${{ steps.get_tag.outputs.new_version }}.zip+ - spec-kit-template-windsurf-ps-${{ steps.get_tag.outputs.new_version }}.zipEOFecho "Generated release notes:"@@ -122,6 +124,8 @@ jobs:spec-kit-template-opencode-ps-${{ steps.get_tag.outputs.new_version }}.zip \spec-kit-template-qwen-sh-${{ steps.get_tag.outputs.new_version }}.zip \spec-kit-template-qwen-ps-${{ steps.get_tag.outputs.new_version }}.zip \+ spec-kit-template-windsurf-sh-${{ steps.get_tag.outputs.new_version }}.zip \+ spec-kit-template-windsurf-ps-${{ steps.get_tag.outputs.new_version }}.zip \--title "Spec Kit Templates - $VERSION_NO_V" \--notes-file release_notes.mdenv:diff --git a/.github/workflows/scripts/create-release-packages.sh b/.github/workflows/scripts/create-release-packages.shindex d45f33e91..8d7eaf221 100644--- a/.github/workflows/scripts/create-release-packages.sh+++ b/.github/workflows/scripts/create-release-packages.sh@@ -154,13 +154,16 @@ build_variant() {opencode)mkdir -p "$base_dir/.opencode/command"generate_commands opencode md "\$ARGUMENTS" "$base_dir/.opencode/command" "$script" ;;+ windsurf)+ mkdir -p "$base_dir/.windsurf/workflows"+ generate_commands windsurf md "\$ARGUMENTS" "$base_dir/.windsurf/workflows" "$script" ;;esac( cd "$base_dir" && zip -r "../spec-kit-template-${agent}-${script}-${NEW_VERSION}.zip" . )echo "Created spec-kit-template-${agent}-${script}-${NEW_VERSION}.zip"}# Determine agent list-ALL_AGENTS=(claude gemini copilot cursor qwen opencode)+ALL_AGENTS=(claude gemini copilot cursor qwen opencode windsurf)ALL_SCRIPTS=(sh ps)diff --git a/AGENTS.md b/AGENTS.mdnew file mode 100644index 000000000..c7fb657de--- /dev/null+++ b/AGENTS.md@@ -0,0 +1,230 @@+# 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/prompts/` | Markdown | N/A (IDE-based) | GitHub Copilot in VS Code |+| **Cursor** | `.cursor/commands/` | Markdown | `cursor-agent` | Cursor CLI |+| **Qwen Code** | `.qwen/commands/` | TOML | `qwen` | Alibaba's Qwen Code CLI |+| **opencode** | `.opencode/command/` | Markdown | `opencode` | opencode CLI |+| **Windsurf** | `.windsurf/workflows/` | Markdown | N/A (IDE-based) | Windsurf IDE workflows |++### Step-by-Step Integration Guide++Follow these steps to add a new agent (using Windsurf as an example):++#### 1. Update AI_CHOICES Constant++Add the new agent to the `AI_CHOICES` dictionary in `src/specify_cli/__init__.py`:++```python+AI_CHOICES = {+ "copilot": "GitHub Copilot",+ "claude": "Claude Code",+ "gemini": "Gemini CLI",+ "cursor": "Cursor",+ "qwen": "Qwen Code",+ "opencode": "opencode",+ "windsurf": "Windsurf" # Add new agent here+}+```++#### 2. Update CLI Help Text++Update all help text and examples to include the new agent:++- Command option help: `--ai` parameter description+- Function docstrings and examples+- Error messages with agent lists++#### 3. Update Release Package Script++Modify `.github/workflows/scripts/create-release-packages.sh`:++##### Add to ALL_AGENTS array:+```bash+ALL_AGENTS=(claude gemini copilot cursor qwen opencode windsurf)+```++##### Add case statement for directory structure:+```bash+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 Agent Context Scripts++##### Bash script (`scripts/bash/update-agent-context.sh`):++Add file variable:+```bash+WINDSURF_FILE="$REPO_ROOT/.windsurf/rules/specify-rules.md"+```++Add to case statement:+```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+```++##### PowerShell script (`scripts/powershell/update-agent-context.ps1`):++Add file variable:+```powershell+$windsurfFile = Join-Path $repoRoot '.windsurf/rules/specify-rules.md'+```++Add to switch statement:+```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+ }+}+```++#### 5. 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+```++**Note**: Skip CLI checks for IDE-based agents (Copilot, Windsurf).++## 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++### IDE-Based Agents+Work within integrated development environments:+- **GitHub Copilot**: Built into VS Code/compatible editors+- **Windsurf**: Built into Windsurf IDE++## Command File Formats++### Markdown Format+Used by: Claude, Cursor, opencode, Windsurf++```markdown+---+description: "Command description"+---++Command content with {SCRIPT} and $ARGUMENTS placeholders.+```++### TOML Format+Used by: Gemini, Qwen++```toml+description = "Command description"++prompt = """+Command content with {SCRIPT} and {{args}} placeholders.+"""+```++## Directory Conventions++- **CLI agents**: Usually `.<agent-name>/commands/`+- **IDE agents**: Follow IDE-specific patterns:+ - Copilot: `.github/prompts/`+ - 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. **Forgetting update scripts**: Both bash and PowerShell scripts must be updated+2. **Missing CLI checks**: Only add for agents that actually have CLI tools+3. **Wrong argument format**: Use correct placeholder format for each agent type+4. **Directory naming**: Follow agent-specific conventions exactly+5. **Help text inconsistency**: Update all user-facing text consistently++## 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++---++*This documentation should be updated whenever new agents are added to maintain accuracy and completeness.*\ No newline at end of filediff --git a/scripts/bash/update-agent-context.sh b/scripts/bash/update-agent-context.shindex a79edd9e3..ba3ab33eb 100644--- a/scripts/bash/update-agent-context.sh+++ b/scripts/bash/update-agent-context.sh@@ -4,7 +4,7 @@ REPO_ROOT=$(git rev-parse --show-toplevel)CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)FEATURE_DIR="$REPO_ROOT/specs/$CURRENT_BRANCH"NEW_PLAN="$FEATURE_DIR/plan.md"-CLAUDE_FILE="$REPO_ROOT/CLAUDE.md"; GEMINI_FILE="$REPO_ROOT/GEMINI.md"; COPILOT_FILE="$REPO_ROOT/.github/copilot-instructions.md"; CURSOR_FILE="$REPO_ROOT/.cursor/rules/specify-rules.mdc"; QWEN_FILE="$REPO_ROOT/QWEN.md"; AGENTS_FILE="$REPO_ROOT/AGENTS.md"+CLAUDE_FILE="$REPO_ROOT/CLAUDE.md"; GEMINI_FILE="$REPO_ROOT/GEMINI.md"; COPILOT_FILE="$REPO_ROOT/.github/copilot-instructions.md"; CURSOR_FILE="$REPO_ROOT/.cursor/rules/specify-rules.mdc"; QWEN_FILE="$REPO_ROOT/QWEN.md"; AGENTS_FILE="$REPO_ROOT/AGENTS.md"; WINDSURF_FILE="$REPO_ROOT/.windsurf/rules/specify-rules.md"AGENT_TYPE="$1"[ -f "$NEW_PLAN" ] || { echo "ERROR: No plan.md found at $NEW_PLAN"; exit 1; }echo "=== Updating agent context files for feature $CURRENT_BRANCH ==="@@ -54,13 +54,15 @@ case "$AGENT_TYPE" incursor) update_agent_file "$CURSOR_FILE" "Cursor IDE" ;;qwen) update_agent_file "$QWEN_FILE" "Qwen Code" ;;opencode) update_agent_file "$AGENTS_FILE" "opencode" ;;+ windsurf) update_agent_file "$WINDSURF_FILE" "Windsurf" ;;"") [ -f "$CLAUDE_FILE" ] && update_agent_file "$CLAUDE_FILE" "Claude Code"; \[ -f "$GEMINI_FILE" ] && update_agent_file "$GEMINI_FILE" "Gemini CLI"; \[ -f "$COPILOT_FILE" ] && update_agent_file "$COPILOT_FILE" "GitHub Copilot"; \[ -f "$CURSOR_FILE" ] && update_agent_file "$CURSOR_FILE" "Cursor IDE"; \[ -f "$QWEN_FILE" ] && update_agent_file "$QWEN_FILE" "Qwen Code"; \[ -f "$AGENTS_FILE" ] && update_agent_file "$AGENTS_FILE" "opencode"; \- if [ ! -f "$CLAUDE_FILE" ] && [ ! -f "$GEMINI_FILE" ] && [ ! -f "$COPILOT_FILE" ] && [ ! -f "$CURSOR_FILE" ] && [ ! -f "$QWEN_FILE" ] && [ ! -f "$AGENTS_FILE" ]; then update_agent_file "$CLAUDE_FILE" "Claude Code"; fi ;;- *) echo "ERROR: Unknown agent type '$AGENT_TYPE' (expected claude|gemini|copilot|cursor|qwen|opencode)"; exit 1 ;;+ [ -f "$WINDSURF_FILE" ] && update_agent_file "$WINDSURF_FILE" "Windsurf"; \+ if [ ! -f "$CLAUDE_FILE" ] && [ ! -f "$GEMINI_FILE" ] && [ ! -f "$COPILOT_FILE" ] && [ ! -f "$CURSOR_FILE" ] && [ ! -f "$QWEN_FILE" ] && [ ! -f "$AGENTS_FILE" ] && [ ! -f "$WINDSURF_FILE" ]; then update_agent_file "$CLAUDE_FILE" "Claude Code"; fi ;;+ *) echo "ERROR: Unknown agent type '$AGENT_TYPE' (expected claude|gemini|copilot|cursor|qwen|opencode|windsurf)"; exit 1 ;;esac-echo; echo "Summary of changes:"; [ -n "$NEW_LANG" ] && echo "- Added language: $NEW_LANG"; [ -n "$NEW_FRAMEWORK" ] && echo "- Added framework: $NEW_FRAMEWORK"; [ -n "$NEW_DB" ] && [ "$NEW_DB" != "N/A" ] && echo "- Added database: $NEW_DB"; echo; echo "Usage: $0 [claude|gemini|copilot|cursor|qwen|opencode]"+echo; echo "Summary of changes:"; [ -n "$NEW_LANG" ] && echo "- Added language: $NEW_LANG"; [ -n "$NEW_FRAMEWORK" ] && echo "- Added framework: $NEW_FRAMEWORK"; [ -n "$NEW_DB" ] && [ "$NEW_DB" != "N/A" ] && echo "- Added database: $NEW_DB"; echo; echo "Usage: $0 [claude|gemini|copilot|cursor|qwen|opencode|windsurf]"diff --git a/scripts/powershell/update-agent-context.ps1 b/scripts/powershell/update-agent-context.ps1index e9f345508..0a1272848 100644--- a/scripts/powershell/update-agent-context.ps1+++ b/scripts/powershell/update-agent-context.ps1@@ -15,6 +15,7 @@ $copilotFile = Join-Path $repoRoot '.github/copilot-instructions.md'$cursorFile = Join-Path $repoRoot '.cursor/rules/specify-rules.mdc'$qwenFile = Join-Path $repoRoot 'QWEN.md'$agentsFile = Join-Path $repoRoot 'AGENTS.md'+$windsurfFile = Join-Path $repoRoot '.windsurf/rules/specify-rules.md'Write-Output "=== Updating agent context files for feature $currentBranch ==="@@ -75,6 +76,7 @@ switch ($AgentType) {'cursor' { Update-AgentFile $cursorFile 'Cursor IDE' }'qwen' { Update-AgentFile $qwenFile 'Qwen Code' }'opencode' { Update-AgentFile $agentsFile 'opencode' }+ 'windsurf' { Update-AgentFile $windsurfFile 'Windsurf' }'' {foreach ($pair in @(@{file=$claudeFile; name='Claude Code'},@@ -82,16 +84,17 @@ switch ($AgentType) {@{file=$copilotFile; name='GitHub Copilot'},@{file=$cursorFile; name='Cursor IDE'},@{file=$qwenFile; name='Qwen Code'},- @{file=$agentsFile; name='opencode'}+ @{file=$agentsFile; name='opencode'},+ @{file=$windsurfFile; name='Windsurf'})) {if (Test-Path $pair.file) { Update-AgentFile $pair.file $pair.name }}- if (-not (Test-Path $claudeFile) -and -not (Test-Path $geminiFile) -and -not (Test-Path $copilotFile) -and -not (Test-Path $cursorFile) -and -not (Test-Path $qwenFile) -and -not (Test-Path $agentsFile)) {+ if (-not (Test-Path $claudeFile) -and -not (Test-Path $geminiFile) -and -not (Test-Path $copilotFile) -and -not (Test-Path $cursorFile) -and -not (Test-Path $qwenFile) -and -not (Test-Path $agentsFile) -and -not (Test-Path $windsurfFile)) {Write-Output 'No agent context files found. Creating Claude Code context file by default.'Update-AgentFile $claudeFile 'Claude Code'}}- Default { Write-Error "ERROR: Unknown agent type '$AgentType'. Use: claude, gemini, copilot, cursor, qwen, opencode or leave empty for all."; exit 1 }+ Default { Write-Error "ERROR: Unknown agent type '$AgentType'. Use: claude, gemini, copilot, cursor, qwen, opencode, windsurf or leave empty for all."; exit 1 }}Write-Output ''@@ -101,4 +104,4 @@ if ($newFramework) { Write-Output "- Added framework: $newFramework" }if ($newDb -and $newDb -ne 'N/A') { Write-Output "- Added database: $newDb" }Write-Output ''-Write-Output 'Usage: ./update-agent-context.ps1 [claude|gemini|copilot|cursor|qwen|opencode]'+Write-Output 'Usage: ./update-agent-context.ps1 [claude|gemini|copilot|cursor|qwen|opencode|windsurf]'diff --git a/src/specify_cli/__init__.py b/src/specify_cli/__init__.pyindex d6c494078..2c1c3c3c9 100644--- a/src/specify_cli/__init__.py+++ b/src/specify_cli/__init__.py@@ -72,7 +72,8 @@ AI_CHOICES = {"gemini": "Gemini CLI","cursor": "Cursor","qwen": "Qwen Code",- "opencode": "opencode"+ "opencode": "opencode",+ "windsurf": "Windsurf"}# Add script type choicesSCRIPT_TYPE_CHOICES = {"sh": "POSIX Shell (bash/zsh)", "ps": "PowerShell"}@@ -750,7 +751,7 @@ def ensure_executable_scripts(project_path: Path, tracker: StepTracker | None =@app.command()def init(project_name: str = typer.Argument(None, help="Name for your new project directory (optional if using --here)"),- ai_assistant: str = typer.Option(None, "--ai", help="AI assistant to use: claude, gemini, copilot, cursor, qwen or opencode"),+ ai_assistant: str = typer.Option(None, "--ai", help="AI assistant to use: claude, gemini, copilot, cursor, qwen, opencode or windsurf"),script_type: str = typer.Option(None, "--script", help="Script type to use: sh or ps"),ignore_agent_tools: bool = typer.Option(False, "--ignore-agent-tools", help="Skip checks for AI agent tools like Claude Code"),no_git: bool = typer.Option(False, "--no-git", help="Skip git repository initialization"),@@ -764,7 +765,7 @@ def init(This command will:1. Check that required tools are installed (git is optional)- 2. Let you choose your AI assistant (Claude Code, Gemini CLI, GitHub Copilot, Cursor, Qwen Code or opencode)+ 2. Let you choose your AI assistant (Claude Code, Gemini CLI, GitHub Copilot, Cursor, Qwen Code, opencode or Windsurf)3. Download the appropriate template from GitHub4. Extract the template to a new project directory or current directory5. Initialize a fresh git repository (if not --no-git and no existing repo)@@ -777,7 +778,7 @@ def init(specify init my-project --ai copilot --no-gitspecify init my-project --ai cursorspecify init my-project --ai qwen- specify init my-project --ai opencode+ specify init my-project --ai windsurfspecify init --ignore-agent-tools my-projectspecify init --here --ai claudespecify init --here@@ -1002,6 +1003,7 @@ def check():tracker.add("qwen", "Qwen Code CLI")tracker.add("code", "VS Code (for GitHub Copilot)")tracker.add("cursor-agent", "Cursor IDE agent (optional)")+ tracker.add("windsurf", "Windsurf IDE (optional)")tracker.add("opencode", "opencode")git_ok = check_tool_for_tracker("git", "https://git-scm.com/downloads", tracker)@@ -1012,6 +1014,7 @@ def check():if not code_ok:code_ok = check_tool_for_tracker("code-insiders", "https://code.visualstudio.com/insiders/", tracker)cursor_ok = check_tool_for_tracker("cursor-agent", "https://cursor.sh/", tracker)+ windsurf_ok = check_tool_for_tracker("windsurf", "https://windsurf.com/", tracker)opencode_ok = check_tool_for_tracker("opencode", "https://opencode.ai/", tracker)console.print(tracker.render())@@ -1020,7 +1023,7 @@ def check():if not git_ok:console.print("[dim]Tip: Install git for repository management[/dim]")- if not (claude_ok or gemini_ok or cursor_ok or qwen_ok or opencode_ok):+ if not (claude_ok or gemini_ok or cursor_ok or qwen_ok or windsurf_ok or opencode_ok):console.print("[dim]Tip: Install an AI assistant for the best experience[/dim]")