Merge pull request #897 from isdaniel/add-more-lang

Support more lang of Common Patterns by Technology
Merge pull request #766 from thenets/use-the-number-prefix-to-find-the-right-spec
2026-01-30 20:52:03 +00:00 · 2025-10-15 10:56:08 -07:00 · 2025-10-15 10:55:33 -07:00 · 2025-10-15 10:52:25 -07:00 · 2025-10-15 10:51:34 -07:00 · 2025-10-15 23:55:00 +08:00
16 changed files with 554 additions and 311 deletions
--- a/.github/workflows/scripts/create-github-release.sh
+++ b/.github/workflows/scripts/create-github-release.sh
@@ -22,8 +22,8 @@ gh release create "$VERSION" \
  .genreleases/spec-kit-template-claude-ps-"$VERSION".zip \
  .genreleases/spec-kit-template-gemini-sh-"$VERSION".zip \
  .genreleases/spec-kit-template-gemini-ps-"$VERSION".zip \
-  .genreleases/spec-kit-template-cursor-sh-"$VERSION".zip \
-  .genreleases/spec-kit-template-cursor-ps-"$VERSION".zip \
+  .genreleases/spec-kit-template-cursor-agent-sh-"$VERSION".zip \
+  .genreleases/spec-kit-template-cursor-agent-ps-"$VERSION".zip \
  .genreleases/spec-kit-template-opencode-sh-"$VERSION".zip \
  .genreleases/spec-kit-template-opencode-ps-"$VERSION".zip \
  .genreleases/spec-kit-template-qwen-sh-"$VERSION".zip \
@@ -38,6 +38,8 @@ gh release create "$VERSION" \
  .genreleases/spec-kit-template-auggie-ps-"$VERSION".zip \
  .genreleases/spec-kit-template-roo-sh-"$VERSION".zip \
  .genreleases/spec-kit-template-roo-ps-"$VERSION".zip \
+  .genreleases/spec-kit-template-codebuddy-sh-"$VERSION".zip \
+  .genreleases/spec-kit-template-codebuddy-ps-"$VERSION".zip \
  .genreleases/spec-kit-template-q-sh-"$VERSION".zip \
  .genreleases/spec-kit-template-q-ps-"$VERSION".zip \
  --title "Spec Kit Templates - $VERSION_NO_V" \
--- a/.github/workflows/scripts/create-release-packages.sh
+++ b/.github/workflows/scripts/create-release-packages.sh
@@ -6,7 +6,7 @@ set -euo pipefail
 # Usage: .github/workflows/scripts/create-release-packages.sh <version>
 #   Version argument should include leading 'v'.
 #   Optionally set AGENTS and/or SCRIPTS env vars to limit what gets built.
-#     AGENTS  : space or comma separated subset of: claude gemini copilot cursor qwen opencode windsurf codex (default: all)
+#     AGENTS  : space or comma separated subset of: claude gemini copilot cursor-agent qwen opencode windsurf codex (default: all)
 #     SCRIPTS : space or comma separated subset of: sh ps (default: both)
 #   Examples:
 #     AGENTS=claude SCRIPTS=sh $0 v0.2.0
@@ -91,6 +91,7 @@ generate_commands() {
    
    case $ext in
      toml)
+        body=$(printf '%s\n' "$body" | sed 's/\\/\\\\/g')
        { echo "description = \"$description\""; echo; echo "prompt = \"\"\""; echo "$body"; echo "\"\"\""; } > "$output_dir/speckit.$name.$ext" ;;
      md)
        echo "$body" > "$output_dir/speckit.$name.$ext" ;;
@@ -132,7 +133,7 @@ build_variant() {
  [[ -d templates ]] && { mkdir -p "$SPEC_DIR/templates"; find templates -type f -not -path "templates/commands/*" -not -name "vscode-settings.json" -exec cp --parents {} "$SPEC_DIR"/ \; ; echo "Copied templates -> .specify/templates"; }
  
  # NOTE: We substitute {ARGS} internally. Outward tokens differ intentionally:
-  #   * Markdown/prompt (claude, copilot, cursor, opencode): $ARGUMENTS
+  #   * Markdown/prompt (claude, copilot, cursor-agent, opencode): $ARGUMENTS
  #   * TOML (gemini, qwen): {{args}}
  # This keeps formats readable without extra abstraction.

@@ -151,9 +152,9 @@ build_variant() {
      mkdir -p "$base_dir/.vscode"
      [[ -f templates/vscode-settings.json ]] && cp templates/vscode-settings.json "$base_dir/.vscode/settings.json"
      ;;
-    cursor)
+    cursor-agent)
      mkdir -p "$base_dir/.cursor/commands"
-      generate_commands cursor md "\$ARGUMENTS" "$base_dir/.cursor/commands" "$script" ;;
+      generate_commands cursor-agent md "\$ARGUMENTS" "$base_dir/.cursor/commands" "$script" ;;
    qwen)
      mkdir -p "$base_dir/.qwen/commands"
      generate_commands qwen toml "{{args}}" "$base_dir/.qwen/commands" "$script"
@@ -176,6 +177,10 @@ build_variant() {
    roo)
      mkdir -p "$base_dir/.roo/commands"
      generate_commands roo md "\$ARGUMENTS" "$base_dir/.roo/commands" "$script" ;;
+    codebuddy)
+      mkdir -p "$base_dir/.codebuddy/commands"
+      generate_commands codebuddy md "\$ARGUMENTS" "$base_dir/.codebuddy/commands" "$script" ;;
+
    q)
      mkdir -p "$base_dir/.amazonq/prompts"
      generate_commands q md "\$ARGUMENTS" "$base_dir/.amazonq/prompts" "$script" ;;
@@ -185,10 +190,9 @@ build_variant() {
 }

 # Determine agent list
-ALL_AGENTS=(claude gemini copilot cursor qwen opencode windsurf codex kilocode auggie roo q)
+ALL_AGENTS=(claude gemini copilot cursor-agent qwen opencode windsurf codex kilocode auggie roo codebuddy q)
 ALL_SCRIPTS=(sh ps)

-
 norm_list() {
  # convert comma+space separated -> space separated unique while preserving order of first occurrence
  tr ',\n' '  ' | awk '{for(i=1;i<=NF;i++){if(!seen[$i]++){printf((out?" ":"") $i)}}}END{printf("\n")}'
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -37,56 +37,57 @@ Specify supports multiple AI agents by generating agent-specific command files a
 | **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 |
+| **Codex CLI** | `.codex/commands/` | Markdown | `codex` | Codex CLI |
 | **Windsurf** | `.windsurf/workflows/` | Markdown | N/A (IDE-based) | Windsurf IDE workflows |
+| **Kilo Code** | `.kilocode/rules/` | Markdown | N/A (IDE-based) | Kilo Code IDE |
+| **Auggie CLI** | `.augment/rules/` | Markdown | `auggie` | Auggie CLI |
+| **Roo Code** | `.roo/rules/` | Markdown | N/A (IDE-based) | Roo Code IDE |
+| **CodeBuddy CLI** | `.codebuddy/commands/` | Markdown | `codebuddy` | CodeBuddy CLI |
 | **Amazon Q Developer CLI** | `.amazonq/prompts/` | Markdown | `q` | Amazon Q Developer CLI |

-
 ### Step-by-Step Integration Guide

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

-#### 1. Update AI_CHOICES Constant
+#### 1. Add to AGENT_CONFIG

-Add the new agent to the `AI_CHOICES` dictionary in `src/specify_cli/__init__.py`:
+**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:

 ```python
-AI_CHOICES = {
-    "copilot": "GitHub Copilot",
-    "claude": "Claude Code", 
-    "gemini": "Gemini CLI",
-    "cursor": "Cursor",
-    "qwen": "Qwen Code",
-    "opencode": "opencode",
-    "windsurf": "Windsurf",
-    "q": "Amazon Q Developer CLI"  # Add new agent here
+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
+        "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
+    },
 }
 ```

-Also update the `agent_folder_map` in the same file to include the new agent's folder for the security notice:
+**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`

-```python
-agent_folder_map = {
-    "claude": ".claude/",
-    "gemini": ".gemini/",
-    "cursor": ".cursor/",
-    "qwen": ".qwen/",
-    "opencode": ".opencode/",
-    "codex": ".codex/",
-    "windsurf": ".windsurf/",  
-    "kilocode": ".kilocode/",
-    "auggie": ".auggie/",
-    "copilot": ".github/",
-    "q": ".amazonq/" # Add new agent folder here
-}
-```
+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)
+- `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 all help text and examples to include the new agent:
+Update the `--ai` parameter help text in the `init()` command to include the new agent:

- Command option help: `--ai` parameter description
- Function docstrings and examples
- Error messages with agent lists
+```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 q"),
+```
+
+Also update any function docstrings, examples, and error messages that list available agents.

 #### 3. Update README Documentation

@@ -103,7 +104,7 @@ Modify `.github/workflows/scripts/create-release-packages.sh`:

 ##### Add to ALL_AGENTS array:
 ```bash
-ALL_AGENTS=(claude gemini copilot cursor qwen opencode windsurf q)
+ALL_AGENTS=(claude gemini copilot cursor-agent qwen opencode windsurf q)
 ```

 ##### Add case statement for directory structure:
@@ -190,17 +191,65 @@ elif selected_ai == "windsurf":
        agent_tool_missing = True
 ```

-**Note**: Skip CLI checks for IDE-based agents (Copilot, Windsurf).
+**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):
+```python
+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):
+```python
+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

 ## 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
+- **CodeBuddy CLI**: `codebuddy` CLI

 ### IDE-Based Agents
 Work within integrated development environments:
@@ -257,20 +306,23 @@ Different agents use different argument placeholders:

 ## 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
+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.*
+*This documentation should be updated whenever new agents are added to maintain accuracy and completeness.*
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,19 @@ All notable changes to the Specify CLI and templates are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

+## [0.0.19] - 2025-10-10
+
+### Added
+
+- Support for CodeBuddy (thank you to [@lispking](https://github.com/lispking) for the contribution).
+- You can now see Git-sourced errors in the Specify CLI.
+
+### Changed
+
+- Fixed the path to the constitution in `plan.md` (thank you to [@lyzno1](https://github.com/lyzno1) for spotting).
+- Fixed backslash escapes in generated TOML files for Gemini (thank you to [@hsin19](https://github.com/hsin19) for the contribution).
+- Implementation command now ensures that the correct ignore files are added (thank you to [@sigent-amazon](https://github.com/sigent-amazon) for the contribution).
+
 ## [0.0.18] - 2025-10-06

 ### Added
--- a/README.md
+++ b/README.md
@@ -20,16 +20,16 @@
 ## Table of Contents

 - [🤔 What is Spec-Driven Development?](#-what-is-spec-driven-development)
- [⚡ Get started](#-get-started)
+- [⚡ Get Started](#-get-started)
 - [📽️ Video Overview](#️-video-overview)
 - [🤖 Supported AI Agents](#-supported-ai-agents)
 - [🔧 Specify CLI Reference](#-specify-cli-reference)
- [📚 Core philosophy](#-core-philosophy)
- [🌟 Development phases](#-development-phases)
- [🎯 Experimental goals](#-experimental-goals)
+- [📚 Core Philosophy](#-core-philosophy)
+- [🌟 Development Phases](#-development-phases)
+- [🎯 Experimental Goals](#-experimental-goals)
 - [🔧 Prerequisites](#-prerequisites)
- [📖 Learn more](#-learn-more)
- [📋 Detailed process](#-detailed-process)
+- [📖 Learn More](#-learn-more)
+- [📋 Detailed Process](#-detailed-process)
 - [🔍 Troubleshooting](#-troubleshooting)
 - [👥 Maintainers](#-maintainers)
 - [💬 Support](#-support)
@@ -40,7 +40,7 @@

 Spec-Driven Development **flips the script** on traditional software development. For decades, code has been king — specifications were just scaffolding we built and discarded once the "real work" of coding began. Spec-Driven Development changes this: **specifications become executable**, directly generating working implementations rather than just guiding them.

-## ⚡ Get started
+## ⚡ Get Started

 ### 1. Install Specify

@@ -61,6 +61,12 @@ specify init <PROJECT_NAME>
 specify check
 ```

+To upgrade specify run:
+
+```bash
+uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git
+```
+
 #### Option 2: One-time Usage

 Run directly without installing:
@@ -137,6 +143,7 @@ Want to see Spec Kit in action? Watch our [video overview](https://www.youtube.c
 | [Windsurf](https://windsurf.com/)                         | ✅ |                                                   |
 | [Kilo Code](https://github.com/Kilo-Org/kilocode)         | ✅ |                                                   |
 | [Auggie CLI](https://docs.augmentcode.com/cli/overview)   | ✅ |                                                   |
+| [CodeBuddy CLI](https://www.codebuddy.ai/cli)             | ✅ |                                                   |
 | [Roo Code](https://roocode.com/)                          | ✅ |                                                   |
 | [Codex CLI](https://github.com/openai/codex)              | ✅ |                                                   |
 | [Amazon Q Developer CLI](https://aws.amazon.com/developer/learning/q-developer-cli/) | ⚠️ | Amazon Q Developer CLI [does not support](https://github.com/aws/amazon-q-developer-cli/issues/3064) custom arguments for slash commands. |
@@ -157,7 +164,7 @@ The `specify` command supports the following options:
 | Argument/Option        | Type     | Description                                                                  |
 |------------------------|----------|------------------------------------------------------------------------------|
 | `<project-name>`       | Argument | Name for your new project directory (optional if using `--here`, or use `.` for current directory) |
-| `--ai`                 | Option   | AI assistant to use: `claude`, `gemini`, `copilot`, `cursor`, `qwen`, `opencode`, `codex`, `windsurf`, `kilocode`, `auggie`, `roo`, or `q` |
+| `--ai`                 | Option   | AI assistant to use: `claude`, `gemini`, `copilot`, `cursor-agent`, `qwen`, `opencode`, `codex`, `windsurf`, `kilocode`, `auggie`, `roo`, `codebuddy`, or `q` |
 | `--script`             | Option   | Script variant to use: `sh` (bash/zsh) or `ps` (PowerShell)                 |
 | `--ignore-agent-tools` | Flag     | Skip checks for AI agent tools like Claude Code                             |
 | `--no-git`             | Flag     | Skip git repository initialization                                          |
@@ -177,7 +184,7 @@ specify init my-project
 specify init my-project --ai claude

 # Initialize with Cursor support
-specify init my-project --ai cursor
+specify init my-project --ai cursor-agent

 # Initialize with Windsurf support
 specify init my-project --ai windsurf
@@ -240,7 +247,7 @@ Additional commands for enhanced quality and validation:
 |------------------|------------------------------------------------------------------------------------------------|
 | `SPECIFY_FEATURE` | Override feature detection for non-Git repositories. Set to the feature directory name (e.g., `001-photo-albums`) to work on a specific feature when not using Git branches.<br/>**Must be set in the context of the agent you're working with prior to using `/speckit.plan` or follow-up commands. |

-## 📚 Core philosophy
+## 📚 Core Philosophy

 Spec-Driven Development is a structured process that emphasizes:

@@ -249,7 +256,7 @@ Spec-Driven Development is a structured process that emphasizes:
 - **Multi-step refinement** rather than one-shot code generation from prompts
 - **Heavy reliance** on advanced AI model capabilities for specification interpretation

-## 🌟 Development phases
+## 🌟 Development Phases

 | Phase | Focus | Key Activities |
 |-------|-------|----------------|
@@ -257,7 +264,7 @@ Spec-Driven Development is a structured process that emphasizes:
 | **Creative Exploration** | Parallel implementations | <ul><li>Explore diverse solutions</li><li>Support multiple technology stacks & architectures</li><li>Experiment with UX patterns</li></ul> |
 | **Iterative Enhancement** ("Brownfield") | Brownfield modernization | <ul><li>Add features iteratively</li><li>Modernize legacy systems</li><li>Adapt processes</li></ul> |

-## 🎯 Experimental goals
+## 🎯 Experimental Goals

 Our research and experimentation focus on:

@@ -285,22 +292,22 @@ Our research and experimentation focus on:

 ## 🔧 Prerequisites

- **Linux/macOS** (or WSL2 on Windows)
- AI coding agent: [Claude Code](https://www.anthropic.com/claude-code), [GitHub Copilot](https://code.visualstudio.com/), [Gemini CLI](https://github.com/google-gemini/gemini-cli), [Cursor](https://cursor.sh/), [Qwen CLI](https://github.com/QwenLM/qwen-code), [opencode](https://opencode.ai/), [Codex CLI](https://github.com/openai/codex), [Windsurf](https://windsurf.com/), or [Amazon Q Developer CLI](https://aws.amazon.com/developer/learning/q-developer-cli/)
+- **Linux/macOS/Windows**
+- [Supported](#-supported-ai-agents) AI coding agent.
 - [uv](https://docs.astral.sh/uv/) for package management
 - [Python 3.11+](https://www.python.org/downloads/)
 - [Git](https://git-scm.com/downloads)

 If you encounter issues with an agent, please open an issue so we can refine the integration.

-## 📖 Learn more
+## 📖 Learn More

 - **[Complete Spec-Driven Development Methodology](./spec-driven.md)** - Deep dive into the full process
 - **[Detailed Walkthrough](#-detailed-process)** - Step-by-step implementation guide

 ---

-## 📋 Detailed process
+## 📋 Detailed Process

 <details>
 <summary>Click to expand the detailed step-by-step walkthrough</summary>
@@ -538,7 +545,26 @@ You can also ask Claude Code (if you have the [GitHub CLI](https://docs.github.c
 >[!NOTE]
 >Before you have the agent implement it, it's also worth prompting Claude Code to cross-check the details to see if there are any over-engineered pieces (remember - it can be over-eager). If over-engineered components or decisions exist, you can ask Claude Code to resolve them. Ensure that Claude Code follows the [constitution](base/memory/constitution.md) as the foundational piece that it must adhere to when establishing the plan.

-### STEP 6: Implementation
+### **STEP 6:** Generate task breakdown with /speckit.tasks
+
+With the implementation plan validated, you can now break down the plan into specific, actionable tasks that can be executed in the correct order. Use the `/speckit.tasks` command to automatically generate a detailed task breakdown from your implementation plan:
+
+```text
+/speckit.tasks
+```
+
+This step creates a `tasks.md` file in your feature specification directory that contains:
+
+- **Task breakdown organized by user story** - Each user story becomes a separate implementation phase with its own set of tasks
+- **Dependency management** - Tasks are ordered to respect dependencies between components (e.g., models before services, services before endpoints)
+- **Parallel execution markers** - Tasks that can run in parallel are marked with `[P]` to optimize development workflow
+- **File path specifications** - Each task includes the exact file paths where implementation should occur
+- **Test-driven development structure** - If tests are requested, test tasks are included and ordered to be written before implementation
+- **Checkpoint validation** - Each user story phase includes checkpoints to validate independent functionality
+
+The generated tasks.md provides a clear roadmap for the `/speckit.implement` command, ensuring systematic implementation that maintains code quality and allows for incremental delivery of user stories.
+
+### **STEP 7:** Implementation

 Once ready, use the `/speckit.implement` command to execute your implementation plan:

--- a/docs/installation.md
+++ b/docs/installation.md
@@ -3,7 +3,7 @@
 ## Prerequisites

 - **Linux/macOS** (or Windows; PowerShell scripts now supported without WSL)
- AI coding agent: [Claude Code](https://www.anthropic.com/claude-code), [GitHub Copilot](https://code.visualstudio.com/), or [Gemini CLI](https://github.com/google-gemini/gemini-cli)
+- AI coding agent: [Claude Code](https://www.anthropic.com/claude-code), [GitHub Copilot](https://code.visualstudio.com/), [Codebuddy CLI](https://www.codebuddy.ai/cli) or [Gemini CLI](https://github.com/google-gemini/gemini-cli)
 - [uv](https://docs.astral.sh/uv/) for package management
 - [Python 3.11+](https://www.python.org/downloads/)
 - [Git](https://git-scm.com/downloads)
@@ -34,6 +34,7 @@ You can proactively specify your AI agent during initialization:
 uvx --from git+https://github.com/github/spec-kit.git specify init <project_name> --ai claude
 uvx --from git+https://github.com/github/spec-kit.git specify init <project_name> --ai gemini
 uvx --from git+https://github.com/github/spec-kit.git specify init <project_name> --ai copilot
+uvx --from git+https://github.com/github/spec-kit.git specify init <project_name> --ai codebuddy
 ```

 ### Specify Script Type (Shell vs PowerShell)
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "specify-cli"
-version = "0.0.18"
+version = "0.0.19"
 description = "Specify CLI, part of GitHub Spec Kit. A tool to bootstrap your projects for Spec-Driven Development (SDD)."
 requires-python = ">=3.11"
 dependencies = [
--- a/scripts/bash/common.sh
+++ b/scripts/bash/common.sh
@@ -19,21 +19,21 @@ get_current_branch() {
        echo "$SPECIFY_FEATURE"
        return
    fi
-    
+
    # Then check git if available
    if git rev-parse --abbrev-ref HEAD >/dev/null 2>&1; then
        git rev-parse --abbrev-ref HEAD
        return
    fi
-    
+
    # For non-git repos, try to find the latest feature directory
    local repo_root=$(get_repo_root)
    local specs_dir="$repo_root/specs"
-    
+
    if [[ -d "$specs_dir" ]]; then
        local latest_feature=""
        local highest=0
-        
+
        for dir in "$specs_dir"/*; do
            if [[ -d "$dir" ]]; then
                local dirname=$(basename "$dir")
@@ -47,13 +47,13 @@ get_current_branch() {
                fi
            fi
        done
-        
+
        if [[ -n "$latest_feature" ]]; then
            echo "$latest_feature"
            return
        fi
    fi
-    
+
    echo "main"  # Final fallback
 }

@@ -65,35 +65,77 @@ has_git() {
 check_feature_branch() {
    local branch="$1"
    local has_git_repo="$2"
-    
+
    # For non-git repos, we can't enforce branch naming but still provide output
    if [[ "$has_git_repo" != "true" ]]; then
        echo "[specify] Warning: Git repository not detected; skipped branch validation" >&2
        return 0
    fi
-    
+
    if [[ ! "$branch" =~ ^[0-9]{3}- ]]; then
        echo "ERROR: Not on a feature branch. Current branch: $branch" >&2
        echo "Feature branches should be named like: 001-feature-name" >&2
        return 1
    fi
-    
+
    return 0
 }

 get_feature_dir() { echo "$1/specs/$2"; }

+# Find feature directory by numeric prefix instead of exact branch match
+# This allows multiple branches to work on the same spec (e.g., 004-fix-bug, 004-add-feature)
+find_feature_dir_by_prefix() {
+    local repo_root="$1"
+    local branch_name="$2"
+    local specs_dir="$repo_root/specs"
+
+    # Extract numeric prefix from branch (e.g., "004" from "004-whatever")
+    if [[ ! "$branch_name" =~ ^([0-9]{3})- ]]; then
+        # If branch doesn't have numeric prefix, fall back to exact match
+        echo "$specs_dir/$branch_name"
+        return
+    fi
+
+    local prefix="${BASH_REMATCH[1]}"
+
+    # Search for directories in specs/ that start with this prefix
+    local matches=()
+    if [[ -d "$specs_dir" ]]; then
+        for dir in "$specs_dir"/"$prefix"-*; do
+            if [[ -d "$dir" ]]; then
+                matches+=("$(basename "$dir")")
+            fi
+        done
+    fi
+
+    # Handle results
+    if [[ ${#matches[@]} -eq 0 ]]; then
+        # No match found - return the branch name path (will fail later with clear error)
+        echo "$specs_dir/$branch_name"
+    elif [[ ${#matches[@]} -eq 1 ]]; then
+        # Exactly one match - perfect!
+        echo "$specs_dir/${matches[0]}"
+    else
+        # Multiple matches - this shouldn't happen with proper naming convention
+        echo "ERROR: Multiple spec directories found with prefix '$prefix': ${matches[*]}" >&2
+        echo "Please ensure only one spec directory exists per numeric prefix." >&2
+        echo "$specs_dir/$branch_name"  # Return something to avoid breaking the script
+    fi
+}
+
 get_feature_paths() {
    local repo_root=$(get_repo_root)
    local current_branch=$(get_current_branch)
    local has_git_repo="false"
-    
+
    if has_git; then
        has_git_repo="true"
    fi
-    
-    local feature_dir=$(get_feature_dir "$repo_root" "$current_branch")
-    
+
+    # Use prefix-based lookup to support multiple branches per spec
+    local feature_dir=$(find_feature_dir_by_prefix "$repo_root" "$current_branch")
+
    cat <<EOF
 REPO_ROOT='$repo_root'
 CURRENT_BRANCH='$current_branch'
--- a/scripts/bash/update-agent-context.sh
+++ b/scripts/bash/update-agent-context.sh
@@ -35,7 +35,7 @@
 #    - Creates default Claude file if no agent files exist
 #
 # Usage: ./update-agent-context.sh [agent_type]
-# Agent types: claude|gemini|copilot|cursor|qwen|opencode|codex|windsurf|kilocode|auggie|q
+# Agent types: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|q
 # Leave empty to update all existing agent files

 set -e
@@ -69,6 +69,7 @@ WINDSURF_FILE="$REPO_ROOT/.windsurf/rules/specify-rules.md"
 KILOCODE_FILE="$REPO_ROOT/.kilocode/rules/specify-rules.md"
 AUGGIE_FILE="$REPO_ROOT/.augment/rules/specify-rules.md"
 ROO_FILE="$REPO_ROOT/.roo/rules/specify-rules.md"
+CODEBUDDY_FILE="$REPO_ROOT/CODEBUDDY.md"
 Q_FILE="$REPO_ROOT/AGENTS.md"

 # Template file
@@ -249,7 +250,7 @@ get_commands_for_language() {
            echo "cargo test && cargo clippy"
            ;;
        *"JavaScript"*|*"TypeScript"*)
-            echo "npm test && npm run lint"
+            echo "npm test \&\& npm run lint"
            ;;
        *)
            echo "# Add commands for $lang"
@@ -557,7 +558,7 @@ update_specific_agent() {
        copilot)
            update_agent_file "$COPILOT_FILE" "GitHub Copilot"
            ;;
-        cursor)
+        cursor-agent)
            update_agent_file "$CURSOR_FILE" "Cursor IDE"
            ;;
        qwen)
@@ -581,12 +582,15 @@ update_specific_agent() {
        roo)
            update_agent_file "$ROO_FILE" "Roo Code"
            ;;
+        codebuddy)
+            update_agent_file "$CODEBUDDY_FILE" "CodeBuddy CLI"
+            ;;
        q)
            update_agent_file "$Q_FILE" "Amazon Q Developer CLI"
            ;;
        *)
            log_error "Unknown agent type '$agent_type'"
-            log_error "Expected: claude|gemini|copilot|cursor|qwen|opencode|codex|windsurf|kilocode|auggie|roo|q"
+            log_error "Expected: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|q"
            exit 1
            ;;
    esac
@@ -646,6 +650,11 @@ update_all_existing_agents() {
        found_agent=true
    fi

+    if [[ -f "$CODEBUDDY_FILE" ]]; then
+        update_agent_file "$CODEBUDDY_FILE" "CodeBuddy CLI"
+        found_agent=true
+    fi
+
    if [[ -f "$Q_FILE" ]]; then
        update_agent_file "$Q_FILE" "Amazon Q Developer CLI"
        found_agent=true
@@ -674,7 +683,8 @@ print_summary() {
    fi
    
    echo
-    log_info "Usage: $0 [claude|gemini|copilot|cursor|qwen|opencode|codex|windsurf|kilocode|auggie|q]"
+
+    log_info "Usage: $0 [claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|codebuddy|q]"
 }

 #==============================================================================
--- a/scripts/powershell/update-agent-context.ps1
+++ b/scripts/powershell/update-agent-context.ps1
@@ -9,7 +9,7 @@ Mirrors the behavior of scripts/bash/update-agent-context.sh:
 2. Plan Data Extraction
 3. Agent File Management (create from template or update existing)
 4. Content Generation (technology stack, recent changes, timestamp)
- 5. Multi-Agent Support (claude, gemini, copilot, cursor, qwen, opencode, codex, windsurf, kilocode, auggie, roo, q)
+ 5. Multi-Agent Support (claude, gemini, copilot, cursor-agent, qwen, opencode, codex, windsurf, kilocode, auggie, roo, q)

 .PARAMETER AgentType
 Optional agent key to update a single agent. If omitted, updates all existing agent files (creating a default Claude file if none exist).
@@ -25,7 +25,7 @@ Relies on common helper functions in common.ps1
 #>
 param(
    [Parameter(Position=0)]
-    [ValidateSet('claude','gemini','copilot','cursor','qwen','opencode','codex','windsurf','kilocode','auggie','roo','q')]
+    [ValidateSet('claude','gemini','copilot','cursor-agent','qwen','opencode','codex','windsurf','kilocode','auggie','roo','codebuddy','q')]
    [string]$AgentType
 )

@@ -54,6 +54,7 @@ $WINDSURF_FILE = Join-Path $REPO_ROOT '.windsurf/rules/specify-rules.md'
 $KILOCODE_FILE = Join-Path $REPO_ROOT '.kilocode/rules/specify-rules.md'
 $AUGGIE_FILE   = Join-Path $REPO_ROOT '.augment/rules/specify-rules.md'
 $ROO_FILE      = Join-Path $REPO_ROOT '.roo/rules/specify-rules.md'
+$CODEBUDDY_FILE = Join-Path $REPO_ROOT 'CODEBUDDY.md'
 $Q_FILE        = Join-Path $REPO_ROOT 'AGENTS.md'

 $TEMPLATE_FILE = Join-Path $REPO_ROOT '.specify/templates/agent-file-template.md'
@@ -369,7 +370,7 @@ function Update-SpecificAgent {
        'claude'   { Update-AgentFile -TargetFile $CLAUDE_FILE   -AgentName 'Claude Code' }
        'gemini'   { Update-AgentFile -TargetFile $GEMINI_FILE   -AgentName 'Gemini CLI' }
        'copilot'  { Update-AgentFile -TargetFile $COPILOT_FILE  -AgentName 'GitHub Copilot' }
-        'cursor'   { Update-AgentFile -TargetFile $CURSOR_FILE   -AgentName 'Cursor IDE' }
+        'cursor-agent' { Update-AgentFile -TargetFile $CURSOR_FILE   -AgentName 'Cursor IDE' }
        'qwen'     { Update-AgentFile -TargetFile $QWEN_FILE     -AgentName 'Qwen Code' }
        'opencode' { Update-AgentFile -TargetFile $AGENTS_FILE   -AgentName 'opencode' }
        'codex'    { Update-AgentFile -TargetFile $AGENTS_FILE   -AgentName 'Codex CLI' }
@@ -377,8 +378,9 @@ function Update-SpecificAgent {
        'kilocode' { Update-AgentFile -TargetFile $KILOCODE_FILE -AgentName 'Kilo Code' }
        'auggie'   { Update-AgentFile -TargetFile $AUGGIE_FILE   -AgentName 'Auggie CLI' }
        'roo'      { Update-AgentFile -TargetFile $ROO_FILE      -AgentName 'Roo Code' }
+        'codebuddy' { Update-AgentFile -TargetFile $CODEBUDDY_FILE -AgentName 'CodeBuddy CLI' }
        'q'        { Update-AgentFile -TargetFile $Q_FILE        -AgentName 'Amazon Q Developer CLI' }
-        default { Write-Err "Unknown agent type '$Type'"; Write-Err 'Expected: claude|gemini|copilot|cursor|qwen|opencode|codex|windsurf|kilocode|auggie|roo|q'; return $false }
+        default { Write-Err "Unknown agent type '$Type'"; Write-Err 'Expected: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|q'; return $false }
    }
 }

@@ -395,6 +397,7 @@ function Update-AllExistingAgents {
    if (Test-Path $KILOCODE_FILE) { if (-not (Update-AgentFile -TargetFile $KILOCODE_FILE -AgentName 'Kilo Code')) { $ok = $false }; $found = $true }
    if (Test-Path $AUGGIE_FILE)   { if (-not (Update-AgentFile -TargetFile $AUGGIE_FILE   -AgentName 'Auggie CLI')) { $ok = $false }; $found = $true }
    if (Test-Path $ROO_FILE)      { if (-not (Update-AgentFile -TargetFile $ROO_FILE      -AgentName 'Roo Code')) { $ok = $false }; $found = $true }
+    if (Test-Path $CODEBUDDY_FILE) { if (-not (Update-AgentFile -TargetFile $CODEBUDDY_FILE -AgentName 'CodeBuddy CLI')) { $ok = $false }; $found = $true }
    if (Test-Path $Q_FILE)        { if (-not (Update-AgentFile -TargetFile $Q_FILE        -AgentName 'Amazon Q Developer CLI')) { $ok = $false }; $found = $true }
    if (-not $found) {
        Write-Info 'No existing agent files found, creating default Claude file...'
@@ -410,7 +413,7 @@ function Print-Summary {
    if ($NEW_FRAMEWORK) { Write-Host "  - Added framework: $NEW_FRAMEWORK" }
    if ($NEW_DB -and $NEW_DB -ne 'N/A') { Write-Host "  - Added database: $NEW_DB" }
    Write-Host ''
-    Write-Info 'Usage: ./update-agent-context.ps1 [-AgentType claude|gemini|copilot|cursor|qwen|opencode|codex|windsurf|kilocode|auggie|roo|q]'
+    Write-Info 'Usage: ./update-agent-context.ps1 [-AgentType claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|codebuddy|q]'
 }

 function Main {
--- a/src/specify_cli/init.py
+++ b/src/specify_cli/init.py
@@ -64,19 +64,86 @@ def _github_auth_headers(cli_token: str | None = None) -> dict:
    token = _github_token(cli_token)
    return {"Authorization": f"Bearer {token}"} if token else {}

-AI_CHOICES = {
-    "copilot": "GitHub Copilot",
-    "claude": "Claude Code",
-    "gemini": "Gemini CLI",
-    "cursor": "Cursor",
-    "qwen": "Qwen Code",
-    "opencode": "opencode",
-    "codex": "Codex CLI",
-    "windsurf": "Windsurf",
-    "kilocode": "Kilo Code",
-    "auggie": "Auggie CLI",
-    "roo": "Roo Code",
-    "q": "Amazon Q Developer CLI",
+# Agent configuration with name, folder, install URL, and CLI tool requirement
+AGENT_CONFIG = {
+    "copilot": {
+        "name": "GitHub Copilot",
+        "folder": ".github/",
+        "install_url": None,  # IDE-based, no CLI check needed
+        "requires_cli": False,
+    },
+    "claude": {
+        "name": "Claude Code",
+        "folder": ".claude/",
+        "install_url": "https://docs.anthropic.com/en/docs/claude-code/setup",
+        "requires_cli": True,
+    },
+    "gemini": {
+        "name": "Gemini CLI",
+        "folder": ".gemini/",
+        "install_url": "https://github.com/google-gemini/gemini-cli",
+        "requires_cli": True,
+    },
+    "cursor-agent": {
+        "name": "Cursor",
+        "folder": ".cursor/",
+        "install_url": None,  # IDE-based
+        "requires_cli": False,
+    },
+    "qwen": {
+        "name": "Qwen Code",
+        "folder": ".qwen/",
+        "install_url": "https://github.com/QwenLM/qwen-code",
+        "requires_cli": True,
+    },
+    "opencode": {
+        "name": "opencode",
+        "folder": ".opencode/",
+        "install_url": "https://opencode.ai",
+        "requires_cli": True,
+    },
+    "codex": {
+        "name": "Codex CLI",
+        "folder": ".codex/",
+        "install_url": "https://github.com/openai/codex",
+        "requires_cli": True,
+    },
+    "windsurf": {
+        "name": "Windsurf",
+        "folder": ".windsurf/",
+        "install_url": None,  # IDE-based
+        "requires_cli": False,
+    },
+    "kilocode": {
+        "name": "Kilo Code",
+        "folder": ".kilocode/",
+        "install_url": None,  # IDE-based
+        "requires_cli": False,
+    },
+    "auggie": {
+        "name": "Auggie CLI",
+        "folder": ".augment/",
+        "install_url": "https://docs.augmentcode.com/cli/setup-auggie/install-auggie-cli",
+        "requires_cli": True,
+    },
+    "codebuddy": {
+        "name": "CodeBuddy",
+        "folder": ".codebuddy/",
+        "install_url": "https://www.codebuddy.ai/cli",
+        "requires_cli": True,
+    },
+    "roo": {
+        "name": "Roo Code",
+        "folder": ".roo/",
+        "install_url": None,  # IDE-based
+        "requires_cli": False,
+    },
+    "q": {
+        "name": "Amazon Q Developer CLI",
+        "folder": ".amazonq/",
+        "install_url": "https://aws.amazon.com/developer/learning/q-developer-cli/",
+        "requires_cli": True,
+    },
 }

 SCRIPT_TYPE_CHOICES = {"sh": "POSIX Shell (bash/zsh)", "ps": "PowerShell"}
@@ -131,7 +198,7 @@ class StepTracker:
                    s["detail"] = detail
                self._maybe_refresh()
                return
-        # If not present, add it
+
        self.steps.append({"key": key, "label": key, "status": status, "detail": detail})
        self._maybe_refresh()

@@ -148,7 +215,6 @@ class StepTracker:
            label = step["label"]
            detail_text = step["detail"].strip() if step["detail"] else ""

-            # Circles (unchanged styling)
            status = step["status"]
            if status == "done":
                symbol = "[green]●[/green]"
@@ -272,7 +338,6 @@ def select_with_arrows(options: dict, prompt_text: str = "Select an option", def
        console.print("\n[red]Selection failed.[/red]")
        raise typer.Exit(1)

-    # Suppress explicit selection print; tracker / later logic will report consolidated status
    return selected_key

 console = Console()
@@ -296,7 +361,6 @@ app = typer.Typer(

 def show_banner():
    """Display the ASCII art banner."""
-    # Create gradient effect with different colors
    banner_lines = BANNER.strip().split('\n')
    colors = ["bright_blue", "blue", "cyan", "bright_cyan", "white", "bright_white"]

@@ -312,8 +376,6 @@ def show_banner():
@app.callback()
 def callback(ctx: typer.Context):
    """Show banner when no subcommand is provided."""
-    # Show banner only when no subcommand and no help flag
-    # (help is handled by BannerGroup)
    if ctx.invoked_subcommand is None and "--help" not in sys.argv and "-h" not in sys.argv:
        show_banner()
        console.print(Align.center("[dim]Run 'specify --help' for usage information[/dim]"))
@@ -337,18 +399,16 @@ def run_command(cmd: list[str], check_return: bool = True, capture: bool = False
            raise
        return None

-def check_tool_for_tracker(tool: str, tracker: StepTracker) -> bool:
-    """Check if a tool is installed and update tracker."""
-    if shutil.which(tool):
-        tracker.complete(tool, "available")
-        return True
-    else:
-        tracker.error(tool, "not found")
-        return False
-
-def check_tool(tool: str, install_hint: str) -> bool:
-    """Check if a tool is installed."""
+def check_tool(tool: str, tracker: StepTracker = None) -> bool:
+    """Check if a tool is installed. Optionally update tracker.
    
+    Args:
+        tool: Name of the tool to check
+        tracker: Optional StepTracker to update with results
+        
+    Returns:
+        True if tool is found, False otherwise
+    """
    # Special handling for Claude CLI after `claude migrate-installer`
    # See: https://github.com/github/spec-kit/issues/123
    # The migrate-installer command REMOVES the original executable from PATH
@@ -356,12 +416,19 @@ def check_tool(tool: str, install_hint: str) -> bool:
    # This path should be prioritized over other claude executables in PATH
    if tool == "claude":
        if CLAUDE_LOCAL_PATH.exists() and CLAUDE_LOCAL_PATH.is_file():
+            if tracker:
+                tracker.complete(tool, "available")
            return True
    
-    if shutil.which(tool):
-        return True
-    else:
-        return False
+    found = shutil.which(tool) is not None
+    
+    if tracker:
+        if found:
+            tracker.complete(tool, "available")
+        else:
+            tracker.error(tool, "not found")
+    
+    return found

 def is_git_repo(path: Path = None) -> bool:
    """Check if the specified path is inside a git repository."""
@@ -383,26 +450,38 @@ def is_git_repo(path: Path = None) -> bool:
    except (subprocess.CalledProcessError, FileNotFoundError):
        return False

-def init_git_repo(project_path: Path, quiet: bool = False) -> bool:
+def init_git_repo(project_path: Path, quiet: bool = False) -> Tuple[bool, Optional[str]]:
    """Initialize a git repository in the specified path.
-    quiet: if True suppress console output (tracker handles status)
+    
+    Args:
+        project_path: Path to initialize git repository in
+        quiet: if True suppress console output (tracker handles status)
+    
+    Returns:
+        Tuple of (success: bool, error_message: Optional[str])
    """
    try:
        original_cwd = Path.cwd()
        os.chdir(project_path)
        if not quiet:
            console.print("[cyan]Initializing git repository...[/cyan]")
-        subprocess.run(["git", "init"], check=True, capture_output=True)
-        subprocess.run(["git", "add", "."], check=True, capture_output=True)
-        subprocess.run(["git", "commit", "-m", "Initial commit from Specify template"], check=True, capture_output=True)
+        subprocess.run(["git", "init"], check=True, capture_output=True, text=True)
+        subprocess.run(["git", "add", "."], check=True, capture_output=True, text=True)
+        subprocess.run(["git", "commit", "-m", "Initial commit from Specify template"], check=True, capture_output=True, text=True)
        if not quiet:
            console.print("[green]✓[/green] Git repository initialized")
-        return True
+        return True, None

    except subprocess.CalledProcessError as e:
+        error_msg = f"Command: {' '.join(e.cmd)}\nExit code: {e.returncode}"
+        if e.stderr:
+            error_msg += f"\nError: {e.stderr.strip()}"
+        elif e.stdout:
+            error_msg += f"\nOutput: {e.stdout.strip()}"
+        
        if not quiet:
            console.print(f"[red]Error initializing git repository:[/red] {e}")
-        return False
+        return False, error_msg
    finally:
        os.chdir(original_cwd)

@@ -438,7 +517,6 @@ def download_template_from_github(ai_assistant: str, download_dir: Path, *, scri
        console.print(Panel(str(e), title="Fetch Error", border_style="red"))
        raise typer.Exit(1)

-    # Find the template asset for the specified AI assistant
    assets = release_data.get("assets", [])
    pattern = f"spec-kit-template-{ai_assistant}-{script_type}"
    matching_assets = [
@@ -523,7 +601,6 @@ def download_and_extract_template(project_path: Path, ai_assistant: str, script_
    """
    current_dir = Path.cwd()

-    # Step: fetch + download combined
    if tracker:
        tracker.start("fetch", "contacting GitHub API")
    try:
@@ -556,12 +633,10 @@ def download_and_extract_template(project_path: Path, ai_assistant: str, script_
        console.print("Extracting template...")

    try:
-        # Create project directory only if not using current directory
        if not is_current_dir:
            project_path.mkdir(parents=True)

        with zipfile.ZipFile(zip_path, 'r') as zip_ref:
-            # List all files in the ZIP for debugging
            zip_contents = zip_ref.namelist()
            if tracker:
                tracker.start("zip-list")
@@ -569,13 +644,11 @@ def download_and_extract_template(project_path: Path, ai_assistant: str, script_
            elif verbose:
                console.print(f"[cyan]ZIP contains {len(zip_contents)} items[/cyan]")

-            # For current directory, extract to a temp location first
            if is_current_dir:
                with tempfile.TemporaryDirectory() as temp_dir:
                    temp_path = Path(temp_dir)
                    zip_ref.extractall(temp_path)

-                    # Check what was extracted
                    extracted_items = list(temp_path.iterdir())
                    if tracker:
                        tracker.start("extracted-summary")
@@ -583,7 +656,6 @@ def download_and_extract_template(project_path: Path, ai_assistant: str, script_
                    elif verbose:
                        console.print(f"[cyan]Extracted {len(extracted_items)} items to temp location[/cyan]")

-                    # Handle GitHub-style ZIP with a single root directory
                    source_dir = temp_path
                    if len(extracted_items) == 1 and extracted_items[0].is_dir():
                        source_dir = extracted_items[0]
@@ -593,14 +665,12 @@ def download_and_extract_template(project_path: Path, ai_assistant: str, script_
                        elif verbose:
                            console.print(f"[cyan]Found nested directory structure[/cyan]")

-                    # Copy contents to current directory
                    for item in source_dir.iterdir():
                        dest_path = project_path / item.name
                        if item.is_dir():
                            if dest_path.exists():
                                if verbose and not tracker:
                                    console.print(f"[yellow]Merging directory:[/yellow] {item.name}")
-                                # Recursively copy directory contents
                                for sub_item in item.rglob('*'):
                                    if sub_item.is_file():
                                        rel_path = sub_item.relative_to(item)
@@ -616,10 +686,8 @@ def download_and_extract_template(project_path: Path, ai_assistant: str, script_
                    if verbose and not tracker:
                        console.print(f"[cyan]Template files merged into current directory[/cyan]")
            else:
-                # Extract directly to project directory (original behavior)
                zip_ref.extractall(project_path)

-                # Check what was extracted
                extracted_items = list(project_path.iterdir())
                if tracker:
                    tracker.start("extracted-summary")
@@ -629,16 +697,14 @@ def download_and_extract_template(project_path: Path, ai_assistant: str, script_
                    for item in extracted_items:
                        console.print(f"  - {item.name} ({'dir' if item.is_dir() else 'file'})")

-                # Handle GitHub-style ZIP with a single root directory
                if len(extracted_items) == 1 and extracted_items[0].is_dir():
-                    # Move contents up one level
                    nested_dir = extracted_items[0]
                    temp_move_dir = project_path.parent / f"{project_path.name}_temp"
-                    # Move the nested directory contents to temp location
+
                    shutil.move(str(nested_dir), str(temp_move_dir))
-                    # Remove the now-empty project directory
+
                    project_path.rmdir()
-                    # Rename temp directory to project directory
+
                    shutil.move(str(temp_move_dir), str(project_path))
                    if tracker:
                        tracker.add("flatten", "Flatten nested directory")
@@ -654,7 +720,7 @@ def download_and_extract_template(project_path: Path, ai_assistant: str, script_
                console.print(f"[red]Error extracting template:[/red] {e}")
                if debug:
                    console.print(Panel(str(e), title="Extraction Error", border_style="red"))
-        # Clean up project directory if created and not current directory
+
        if not is_current_dir and project_path.exists():
            shutil.rmtree(project_path)
        raise typer.Exit(1)
@@ -664,7 +730,7 @@ def download_and_extract_template(project_path: Path, ai_assistant: str, script_
    finally:
        if tracker:
            tracker.add("cleanup", "Remove temporary archive")
-        # Clean up downloaded ZIP file
+
        if zip_path.exists():
            zip_path.unlink()
            if tracker:
@@ -722,7 +788,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, or use '.' for current directory)"),
-    ai_assistant: str = typer.Option(None, "--ai", help="AI assistant to use: claude, gemini, copilot, cursor, qwen, opencode, codex, windsurf, kilocode, auggie or q"),
+    ai_assistant: str = typer.Option(None, "--ai", help="AI assistant to use: claude, gemini, copilot, cursor-agent, qwen, opencode, codex, windsurf, kilocode, auggie, codebuddy, or q"),
    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"),
@@ -737,7 +803,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, opencode, Codex CLI, Windsurf, Kilo Code, Auggie CLI, or Amazon Q Developer CLI)
+    2. Let you choose your AI assistant
    3. Download the appropriate template from GitHub
    4. Extract the template to a new project directory or current directory
    5. Initialize a fresh git repository (if not --no-git and no existing repo)
@@ -752,13 +818,13 @@ def init(
        specify init .                     # Initialize in current directory (interactive AI selection)
        specify init --here --ai claude    # Alternative syntax for current directory
        specify init --here --ai codex
+        specify init --here --ai codebuddy
        specify init --here
        specify init --here --force  # Skip confirmation when current directory not empty
    """

    show_banner()

-    # Handle '.' as shorthand for current directory (equivalent to --here)
    if project_name == ".":
        here = True
        project_name = None  # Clear project_name to use existing validation logic
@@ -809,91 +875,57 @@ def init(
        f"{'Working Path':<15} [dim]{current_dir}[/dim]",
    ]

-    # Add target path only if different from working dir
    if not here:
        setup_lines.append(f"{'Target Path':<15} [dim]{project_path}[/dim]")

    console.print(Panel("\n".join(setup_lines), border_style="cyan", padding=(1, 2)))

-    # Check git only if we might need it (not --no-git)
-    # Only set to True if the user wants it and the tool is available
    should_init_git = False
    if not no_git:
-        should_init_git = check_tool("git", "https://git-scm.com/downloads")
+        should_init_git = check_tool("git")
        if not should_init_git:
            console.print("[yellow]Git not found - will skip repository initialization[/yellow]")

    if ai_assistant:
-        if ai_assistant not in AI_CHOICES:
-            console.print(f"[red]Error:[/red] Invalid AI assistant '{ai_assistant}'. Choose from: {', '.join(AI_CHOICES.keys())}")
+        if ai_assistant not in AGENT_CONFIG:
+            console.print(f"[red]Error:[/red] Invalid AI assistant '{ai_assistant}'. Choose from: {', '.join(AGENT_CONFIG.keys())}")
            raise typer.Exit(1)
        selected_ai = ai_assistant
    else:
-        # Use arrow-key selection interface
+        # Create options dict for selection (agent_key: display_name)
+        ai_choices = {key: config["name"] for key, config in AGENT_CONFIG.items()}
        selected_ai = select_with_arrows(
-            AI_CHOICES, 
+            ai_choices, 
            "Choose your AI assistant:", 
            "copilot"
        )

-    # Check agent tools unless ignored
    if not ignore_agent_tools:
-        agent_tool_missing = False
-        install_url = ""
-        if selected_ai == "claude":
-            if not check_tool("claude", "https://docs.anthropic.com/en/docs/claude-code/setup"):
-                install_url = "https://docs.anthropic.com/en/docs/claude-code/setup"
-                agent_tool_missing = True
-        elif selected_ai == "gemini":
-            if not check_tool("gemini", "https://github.com/google-gemini/gemini-cli"):
-                install_url = "https://github.com/google-gemini/gemini-cli"
-                agent_tool_missing = True
-        elif selected_ai == "qwen":
-            if not check_tool("qwen", "https://github.com/QwenLM/qwen-code"):
-                install_url = "https://github.com/QwenLM/qwen-code"
-                agent_tool_missing = True
-        elif selected_ai == "opencode":
-            if not check_tool("opencode", "https://opencode.ai"):
-                install_url = "https://opencode.ai"
-                agent_tool_missing = True
-        elif selected_ai == "codex":
-            if not check_tool("codex", "https://github.com/openai/codex"):
-                install_url = "https://github.com/openai/codex"
-                agent_tool_missing = True
-        elif selected_ai == "auggie":
-            if not check_tool("auggie", "https://docs.augmentcode.com/cli/setup-auggie/install-auggie-cli"):
-                install_url = "https://docs.augmentcode.com/cli/setup-auggie/install-auggie-cli"
-                agent_tool_missing = True
-        elif selected_ai == "q":
-            if not check_tool("q", "https://github.com/aws/amazon-q-developer-cli"):
-                install_url = "https://aws.amazon.com/developer/learning/q-developer-cli/"
-                agent_tool_missing = True
-        # GitHub Copilot and Cursor checks are not needed as they're typically available in supported IDEs
+        agent_config = AGENT_CONFIG.get(selected_ai)
+        if agent_config and agent_config["requires_cli"]:
+            install_url = agent_config["install_url"]
+            if not check_tool(selected_ai):
+                error_panel = Panel(
+                    f"[cyan]{selected_ai}[/cyan] not found\n"
+                    f"Install from: [cyan]{install_url}[/cyan]\n"
+                    f"{agent_config['name']} is required to continue with this project type.\n\n"
+                    "Tip: Use [cyan]--ignore-agent-tools[/cyan] to skip this check",
+                    title="[red]Agent Detection Error[/red]",
+                    border_style="red",
+                    padding=(1, 2)
+                )
+                console.print()
+                console.print(error_panel)
+                raise typer.Exit(1)

-        if agent_tool_missing:
-            error_panel = Panel(
-                f"[cyan]{selected_ai}[/cyan] not found\n"
-                f"Install with: [cyan]{install_url}[/cyan]\n"
-                f"{AI_CHOICES[selected_ai]} is required to continue with this project type.\n\n"
-                "Tip: Use [cyan]--ignore-agent-tools[/cyan] to skip this check",
-                title="[red]Agent Detection Error[/red]",
-                border_style="red",
-                padding=(1, 2)
-            )
-            console.print()
-            console.print(error_panel)
-            raise typer.Exit(1)
-
-    # Determine script type (explicit, interactive, or OS default)
    if script_type:
        if script_type not in SCRIPT_TYPE_CHOICES:
            console.print(f"[red]Error:[/red] Invalid script type '{script_type}'. Choose from: {', '.join(SCRIPT_TYPE_CHOICES.keys())}")
            raise typer.Exit(1)
        selected_script = script_type
    else:
-        # Auto-detect default
        default_script = "ps" if os.name == "nt" else "sh"
-        # Provide interactive selection similar to AI if stdin is a TTY
+
        if sys.stdin.isatty():
            selected_script = select_with_arrows(SCRIPT_TYPE_CHOICES, "Choose script type (or press Enter)", default_script)
        else:
@@ -902,12 +934,10 @@ def init(
    console.print(f"[cyan]Selected AI assistant:[/cyan] {selected_ai}")
    console.print(f"[cyan]Selected script type:[/cyan] {selected_script}")

-    # Download and set up project
-    # New tree-based progress (no emojis); include earlier substeps
    tracker = StepTracker("Initialize Specify Project")
-    # Flag to allow suppressing legacy headings
+
    sys._specify_tracker_active = True
-    # Pre steps recorded as completed before live rendering
+
    tracker.add("precheck", "Check required tools")
    tracker.complete("precheck", "ok")
    tracker.add("ai-select", "Select AI assistant")
@@ -927,30 +957,31 @@ def init(
    ]:
        tracker.add(key, label)

-    # Use transient so live tree is replaced by the final static render (avoids duplicate output)
+    # Track git error message outside Live context so it persists
+    git_error_message = None
+
    with Live(tracker.render(), console=console, refresh_per_second=8, transient=True) as live:
        tracker.attach_refresh(lambda: live.update(tracker.render()))
        try:
-            # Create a httpx client with verify based on skip_tls
            verify = not skip_tls
            local_ssl_context = ssl_context if verify else False
            local_client = httpx.Client(verify=local_ssl_context)

            download_and_extract_template(project_path, selected_ai, selected_script, here, verbose=False, tracker=tracker, client=local_client, debug=debug, github_token=github_token)

-            # Ensure scripts are executable (POSIX)
            ensure_executable_scripts(project_path, tracker=tracker)

-            # Git step
            if not no_git:
                tracker.start("git")
                if is_git_repo(project_path):
                    tracker.complete("git", "existing repo detected")
                elif should_init_git:
-                    if init_git_repo(project_path, quiet=True):
+                    success, error_msg = init_git_repo(project_path, quiet=True)
+                    if success:
                        tracker.complete("git", "initialized")
                    else:
                        tracker.error("git", "init failed")
+                        git_error_message = error_msg
                else:
                    tracker.skip("git", "git not available")
            else:
@@ -973,31 +1004,32 @@ def init(
                shutil.rmtree(project_path)
            raise typer.Exit(1)
        finally:
-            # Force final render
            pass

-    # Final static tree (ensures finished state visible after Live context ends)
    console.print(tracker.render())
    console.print("\n[bold green]Project ready.[/bold green]")
+    
+    # Show git error details if initialization failed
+    if git_error_message:
+        console.print()
+        git_error_panel = Panel(
+            f"[yellow]Warning:[/yellow] Git repository initialization failed\n\n"
+            f"{git_error_message}\n\n"
+            f"[dim]You can initialize git manually later with:[/dim]\n"
+            f"[cyan]cd {project_path if not here else '.'}[/cyan]\n"
+            f"[cyan]git init[/cyan]\n"
+            f"[cyan]git add .[/cyan]\n"
+            f"[cyan]git commit -m \"Initial commit\"[/cyan]",
+            title="[red]Git Initialization Failed[/red]",
+            border_style="red",
+            padding=(1, 2)
+        )
+        console.print(git_error_panel)

    # Agent folder security notice
-    agent_folder_map = {
-        "claude": ".claude/",
-        "gemini": ".gemini/",
-        "cursor": ".cursor/",
-        "qwen": ".qwen/",
-        "opencode": ".opencode/",
-        "codex": ".codex/",
-        "windsurf": ".windsurf/",
-        "kilocode": ".kilocode/",
-        "auggie": ".augment/",
-        "copilot": ".github/",
-        "roo": ".roo/",
-        "q": ".amazonq/"
-    }
-
-    if selected_ai in agent_folder_map:
-        agent_folder = agent_folder_map[selected_ai]
+    agent_config = AGENT_CONFIG.get(selected_ai)
+    if agent_config:
+        agent_folder = agent_config["folder"]
        security_notice = Panel(
            f"Some agents may store credentials, auth tokens, or other identifying and private artifacts in the agent folder within your project.\n"
            f"Consider adding [cyan]{agent_folder}[/cyan] (or parts of it) to [cyan].gitignore[/cyan] to prevent accidental credential leakage.",
@@ -1008,7 +1040,6 @@ def init(
        console.print()
        console.print(security_notice)

-    # Boxed "Next steps" section
    steps_lines = []
    if not here:
        steps_lines.append(f"1. Go to the project folder: [cyan]cd {project_name}[/cyan]")
@@ -1061,32 +1092,21 @@ def check():
    tracker = StepTracker("Check Available Tools")

    tracker.add("git", "Git version control")
-    tracker.add("claude", "Claude Code CLI")
-    tracker.add("gemini", "Gemini CLI")
-    tracker.add("qwen", "Qwen Code CLI")
+    git_ok = check_tool("git", tracker=tracker)
+    
+    agent_results = {}
+    for agent_key, agent_config in AGENT_CONFIG.items():
+        agent_name = agent_config["name"]
+        
+        tracker.add(agent_key, agent_name)
+        agent_results[agent_key] = check_tool(agent_key, tracker=tracker)
+    
+    # Check VS Code variants (not in agent config)
    tracker.add("code", "Visual Studio Code")
+    code_ok = check_tool("code", tracker=tracker)
+    
    tracker.add("code-insiders", "Visual Studio Code Insiders")
-    tracker.add("cursor-agent", "Cursor IDE agent")
-    tracker.add("windsurf", "Windsurf IDE")
-    tracker.add("kilocode", "Kilo Code IDE")
-    tracker.add("opencode", "opencode")
-    tracker.add("codex", "Codex CLI")
-    tracker.add("auggie", "Auggie CLI")
-    tracker.add("q", "Amazon Q Developer CLI")
-
-    git_ok = check_tool_for_tracker("git", tracker)
-    claude_ok = check_tool_for_tracker("claude", tracker)  
-    gemini_ok = check_tool_for_tracker("gemini", tracker)
-    qwen_ok = check_tool_for_tracker("qwen", tracker)
-    code_ok = check_tool_for_tracker("code", tracker)
-    code_insiders_ok = check_tool_for_tracker("code-insiders", tracker)
-    cursor_ok = check_tool_for_tracker("cursor-agent", tracker)
-    windsurf_ok = check_tool_for_tracker("windsurf", tracker)
-    kilocode_ok = check_tool_for_tracker("kilocode", tracker)
-    opencode_ok = check_tool_for_tracker("opencode", tracker)
-    codex_ok = check_tool_for_tracker("codex", tracker)
-    auggie_ok = check_tool_for_tracker("auggie", tracker)
-    q_ok = check_tool_for_tracker("q", tracker)
+    code_insiders_ok = check_tool("code-insiders", tracker=tracker)

    console.print(tracker.render())

@@ -1094,7 +1114,8 @@ 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 windsurf_ok or kilocode_ok or opencode_ok or codex_ok or auggie_ok or q_ok):
+
+    if not any(agent_results.values()):
        console.print("[dim]Tip: Install an AI assistant for the best experience[/dim]")

 def main():
--- a/templates/commands/clarify.md
+++ b/templates/commands/clarify.md
@@ -97,7 +97,15 @@ Execution steps:

 4. Sequential questioning loop (interactive):
    - Present EXACTLY ONE question at a time.
-    - For multiple‑choice questions render options as a Markdown table:
+    - For multiple‑choice questions:
+       * **Analyze all options** and determine the **most suitable option** based on:
+          - Best practices for the project type
+          - Common patterns in similar implementations
+          - Risk reduction (security, performance, maintainability)
+          - Alignment with any explicit project goals or constraints visible in the spec
+       * Present your **recommended option prominently** at the top with clear reasoning (1-2 sentences explaining why this is the best choice).
+       * Format as: `**Recommended:** Option [X] - <reasoning>`
+       * Then render all options as a Markdown table:

       | Option | Description |
       |--------|-------------|
@@ -106,9 +114,14 @@ Execution steps:
       | C | <Option C description> | (add D/E as needed up to 5)
       | Short | Provide a different short answer (<=5 words) | (Include only if free-form alternative is appropriate)

-    - For short‑answer style (no meaningful discrete options), output a single line after the question: `Format: Short answer (<=5 words)`.
+       * After the table, add: `You can reply with the option letter (e.g., "A"), accept the recommendation by saying "yes" or "recommended", or provide your own short answer.`
+    - For short‑answer style (no meaningful discrete options):
+       * Provide your **suggested answer** based on best practices and context.
+       * Format as: `**Suggested:** <your proposed answer> - <brief reasoning>`
+       * Then output: `Format: Short answer (<=5 words). You can accept the suggestion by saying "yes" or "suggested", or provide your own answer.`
    - After the user answers:
-       * Validate the answer maps to one option or fits the <=5 word constraint.
+       * If the user replies with "yes", "recommended", or "suggested", use your previously stated recommendation/suggestion as the answer.
+       * Otherwise, validate the answer maps to one option or fits the <=5 word constraint.
       * If ambiguous, ask for a quick disambiguation (count still belongs to same question; do not advance).
       * Once satisfactory, record it in working memory (do not yet write to disk) and move to the next queued question.
    - Stop asking further questions when:
--- a/templates/commands/implement.md
+++ b/templates/commands/implement.md
@@ -54,27 +54,66 @@ You **MUST** consider the user input before proceeding (if not empty).
   - **IF EXISTS**: Read research.md for technical decisions and constraints
   - **IF EXISTS**: Read quickstart.md for integration scenarios

-4. Parse tasks.md structure and extract:
+4. **Project Setup Verification**:
+   - **REQUIRED**: Create/verify ignore files based on actual project setup:
+   
+   **Detection & Creation Logic**:
+   - Check if the following command succeeds to determine if the repository is a git repo (create/verify .gitignore if so):
+
+     ```sh
+     git rev-parse --git-dir 2>/dev/null
+     ```
+   - Check if Dockerfile* exists or Docker in plan.md → create/verify .dockerignore
+   - Check if .eslintrc* or eslint.config.* exists → create/verify .eslintignore
+   - Check if .prettierrc* exists → create/verify .prettierignore
+   - Check if .npmrc or package.json exists → create/verify .npmignore (if publishing)
+   - Check if terraform files (*.tf) exist → create/verify .terraformignore
+   - Check if .helmignore needed (helm charts present) → create/verify .helmignore
+   
+   **If ignore file already exists**: Verify it contains essential patterns, append missing critical patterns only
+   **If ignore file missing**: Create with full pattern set for detected technology
+   
+   **Common Patterns by Technology** (from plan.md tech stack):
+   - **Node.js/JavaScript**: `node_modules/`, `dist/`, `build/`, `*.log`, `.env*`
+   - **Python**: `__pycache__/`, `*.pyc`, `.venv/`, `venv/`, `dist/`, `*.egg-info/`
+   - **Java**: `target/`, `*.class`, `*.jar`, `.gradle/`, `build/`
+   - **C#/.NET**: `bin/`, `obj/`, `*.user`, `*.suo`, `packages/`
+   - **Go**: `*.exe`, `*.test`, `vendor/`, `*.out`
+   - **Ruby**: `.bundle/`, `log/`, `tmp/`, `*.gem`, `vendor/bundle/`
+   - **PHP**: `vendor/`, `*.log`, `*.cache`, `*.env`
+   - **Rust**: `target/`, `debug/`, `release/`, `*.rs.bk`, `*.rlib`, `*.prof*`, `.idea/`, `*.log`, `.env*`
+   - **Kotlin**: `build/`, `out/`, `.gradle/`, `.idea/`, `*.class`, `*.jar`, `*.iml`, `*.log`, `.env*`
+   - **C++**: `build/`, `bin/`, `obj/`, `out/`, `*.o`, `*.so`, `*.a`, `*.exe`, `*.dll`, `.idea/`, `*.log`, `.env*`
+   - **C**: `build/`, `bin/`, `obj/`, `out/`, `*.o`, `*.a`, `*.so`, `*.exe`, `Makefile`, `config.log`, `.idea/`, `*.log`, `.env*`
+   - **Universal**: `.DS_Store`, `Thumbs.db`, `*.tmp`, `*.swp`, `.vscode/`, `.idea/`
+   
+   **Tool-Specific Patterns**:
+   - **Docker**: `node_modules/`, `.git/`, `Dockerfile*`, `.dockerignore`, `*.log*`, `.env*`, `coverage/`
+   - **ESLint**: `node_modules/`, `dist/`, `build/`, `coverage/`, `*.min.js`
+   - **Prettier**: `node_modules/`, `dist/`, `build/`, `coverage/`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`
+   - **Terraform**: `.terraform/`, `*.tfstate*`, `*.tfvars`, `.terraform.lock.hcl`
+
+5. Parse tasks.md structure and extract:
   - **Task phases**: Setup, Tests, Core, Integration, Polish
   - **Task dependencies**: Sequential vs parallel execution rules
   - **Task details**: ID, description, file paths, parallel markers [P]
   - **Execution flow**: Order and dependency requirements

-5. Execute implementation following the task plan:
+6. Execute implementation following the task plan:
   - **Phase-by-phase execution**: Complete each phase before moving to the next
   - **Respect dependencies**: Run sequential tasks in order, parallel tasks [P] can run together  
   - **Follow TDD approach**: Execute test tasks before their corresponding implementation tasks
   - **File-based coordination**: Tasks affecting the same files must run sequentially
   - **Validation checkpoints**: Verify each phase completion before proceeding

-6. Implementation execution rules:
+7. Implementation execution rules:
   - **Setup first**: Initialize project structure, dependencies, configuration
   - **Tests before code**: If you need to write tests for contracts, entities, and integration scenarios
   - **Core development**: Implement models, services, CLI commands, endpoints
   - **Integration work**: Database connections, middleware, logging, external services
   - **Polish and validation**: Unit tests, performance optimization, documentation

-7. Progress tracking and error handling:
+8. Progress tracking and error handling:
   - Report progress after each completed task
   - Halt execution if any non-parallel task fails
   - For parallel tasks [P], continue with successful tasks, report failed ones
@@ -82,7 +121,7 @@ You **MUST** consider the user input before proceeding (if not empty).
   - Suggest next steps if implementation cannot proceed
   - **IMPORTANT** For completed tasks, make sure to mark the task off as [X] in the tasks file.

-8. Completion validation:
+9. Completion validation:
   - Verify all required tasks are completed
   - Check that implemented features match the original specification
   - Validate that tests pass and coverage meets requirements
--- a/templates/commands/plan.md
+++ b/templates/commands/plan.md
@@ -20,7 +20,7 @@ You **MUST** consider the user input before proceeding (if not empty).

 1. **Setup**: Run `{SCRIPT}` from repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").

-2. **Load context**: Read FEATURE_SPEC and `.specify/memory/constitution.md`. Load IMPL_PLAN template (already copied).
+2. **Load context**: Read FEATURE_SPEC and `/memory/constitution.md`. Load IMPL_PLAN template (already copied).

 3. **Execute plan workflow**: Follow the structure in IMPL_PLAN template to:
   - Fill Technical Context (mark unknowns as "NEEDS CLARIFICATION")
--- a/templates/commands/tasks.md
+++ b/templates/commands/tasks.md
@@ -22,27 +22,13 @@ You **MUST** consider the user input before proceeding (if not empty).
   - **Optional**: data-model.md (entities), contracts/ (API endpoints), research.md (decisions), quickstart.md (test scenarios)
   - Note: Not all projects have all documents. Generate tasks based on what's available.

-3. **Execute task generation workflow** (follow the template structure):
+3. **Execute task generation workflow**:
   - Load plan.md and extract tech stack, libraries, project structure
-   - **Load spec.md and extract user stories with their priorities (P1, P2, P3, etc.)**
-   - If data-model.md exists: Extract entities → map to user stories
-   - If contracts/ exists: Each file → map endpoints to user stories
-   - If research.md exists: Extract decisions → generate setup tasks
-   - **Generate tasks ORGANIZED BY USER STORY**:
-     - Setup tasks (shared infrastructure needed by all stories)
-     - **Foundational tasks (prerequisites that must complete before ANY user story can start)**
-     - For each user story (in priority order P1, P2, P3...):
-       - Group all tasks needed to complete JUST that story
-       - Include models, services, endpoints, UI components specific to that story
-       - Mark which tasks are [P] parallelizable
-       - If tests requested: Include tests specific to that story
-     - Polish/Integration tasks (cross-cutting concerns)
-   - **Tests are OPTIONAL**: Only generate test tasks if explicitly requested in the feature spec or user asks for TDD approach
-   - Apply task rules:
-     - Different files = mark [P] for parallel
-     - Same file = sequential (no [P])
-     - If tests requested: Tests before implementation (TDD order)
-   - Number tasks sequentially (T001, T002...)
+   - Load spec.md and extract user stories with their priorities (P1, P2, P3, etc.)
+   - If data-model.md exists: Extract entities and map to user stories
+   - If contracts/ exists: Map endpoints to user stories
+   - If research.md exists: Extract decisions for setup tasks
+   - Generate tasks organized by user story (see Task Generation Rules below)
   - Generate dependency graph showing user story completion order
   - Create parallel execution examples per user story
   - Validate task completeness (each user story has all needed tasks, independently testable)
@@ -52,12 +38,9 @@ You **MUST** consider the user input before proceeding (if not empty).
   - Phase 1: Setup tasks (project initialization)
   - Phase 2: Foundational tasks (blocking prerequisites for all user stories)
   - Phase 3+: One phase per user story (in priority order from spec.md)
-     - Each phase includes: story goal, independent test criteria, tests (if requested), implementation tasks
-     - Clear [Story] labels (US1, US2, US3...) for each task
-     - [P] markers for parallelizable tasks within each story
-     - Checkpoint markers after each story phase
+   - Each phase includes: story goal, independent test criteria, tests (if requested), implementation tasks
   - Final Phase: Polish & cross-cutting concerns
-   - Numbered tasks (T001, T002...) in execution order
+   - All tasks must follow the strict checklist format (see Task Generation Rules below)
   - Clear file paths for each task
   - Dependencies section showing story completion order
   - Parallel execution examples per story
@@ -69,6 +52,7 @@ You **MUST** consider the user input before proceeding (if not empty).
   - Parallel opportunities identified
   - Independent test criteria for each story
   - Suggested MVP scope (typically just User Story 1)
+   - Format validation: Confirm ALL tasks follow the checklist format (checkbox, ID, labels, file paths)

 Context for task generation: {ARGS}

@@ -76,10 +60,44 @@ The tasks.md should be immediately executable - each task must be specific enoug

 ## Task Generation Rules

-**IMPORTANT**: Tests are optional. Only generate test tasks if the user explicitly requested testing or TDD approach in the feature specification.
-
 **CRITICAL**: Tasks MUST be organized by user story to enable independent implementation and testing.

+**Tests are OPTIONAL**: Only generate test tasks if explicitly requested in the feature specification or if user requests TDD approach.
+
+### Checklist Format (REQUIRED)
+
+Every task MUST strictly follow this format:
+
+```text
+- [ ] [TaskID] [P?] [Story?] Description with file path
+```
+
+**Format Components**:
+
+1. **Checkbox**: ALWAYS start with `- [ ]` (markdown checkbox)
+2. **Task ID**: Sequential number (T001, T002, T003...) in execution order
+3. **[P] marker**: Include ONLY if task is parallelizable (different files, no dependencies on incomplete tasks)
+4. **[Story] label**: REQUIRED for user story phase tasks only
+   - Format: [US1], [US2], [US3], etc. (maps to user stories from spec.md)
+   - Setup phase: NO story label
+   - Foundational phase: NO story label  
+   - User Story phases: MUST have story label
+   - Polish phase: NO story label
+5. **Description**: Clear action with exact file path
+
+**Examples**:
+
+- ✅ CORRECT: `- [ ] T001 Create project structure per implementation plan`
+- ✅ CORRECT: `- [ ] T005 [P] Implement authentication middleware in src/middleware/auth.py`
+- ✅ CORRECT: `- [ ] T012 [P] [US1] Create User model in src/models/user.py`
+- ✅ CORRECT: `- [ ] T014 [US1] Implement UserService in src/services/user_service.py`
+- ❌ WRONG: `- [ ] Create User model` (missing ID and Story label)
+- ❌ WRONG: `T001 [US1] Create model` (missing checkbox)
+- ❌ WRONG: `- [ ] [US1] Create User model` (missing Task ID)
+- ❌ WRONG: `- [ ] T001 [US1] Create model` (missing file path)
+
+### Task Organization
+
 1. **From User Stories (spec.md)** - PRIMARY ORGANIZATION:
   - Each user story (P1, P2, P3...) gets its own phase
   - Map all related components to their story:
@@ -94,22 +112,21 @@ The tasks.md should be immediately executable - each task must be specific enoug
   - If tests requested: Each contract → contract test task [P] before implementation in that story's phase
   
 3. **From Data Model**:
-   - Map each entity → to the user story(ies) that need it
+   - Map each entity to the user story(ies) that need it
   - If entity serves multiple stories: Put in earliest story or Setup phase
   - Relationships → service layer tasks in appropriate story phase
   
 4. **From Setup/Infrastructure**:
   - Shared infrastructure → Setup phase (Phase 1)
   - Foundational/blocking tasks → Foundational phase (Phase 2)
-     - Examples: Database schema setup, authentication framework, core libraries, base configurations
-     - These MUST complete before any user story can be implemented
   - Story-specific setup → within that story's phase

-5. **Ordering**:
-   - Phase 1: Setup (project initialization)
-   - Phase 2: Foundational (blocking prerequisites - must complete before user stories)
-   - Phase 3+: User Stories in priority order (P1, P2, P3...)
-     - Within each story: Tests (if requested) → Models → Services → Endpoints → Integration
-   - Final Phase: Polish & Cross-Cutting Concerns
-   - Each user story phase should be a complete, independently testable increment
+### Phase Structure
+
+- **Phase 1**: Setup (project initialization)
+- **Phase 2**: Foundational (blocking prerequisites - MUST complete before user stories)
+- **Phase 3+**: User Stories in priority order (P1, P2, P3...)
+  - Within each story: Tests (if requested) → Models → Services → Endpoints → Integration
+  - Each phase should be a complete, independently testable increment
+- **Final Phase**: Polish & Cross-Cutting Concerns

--- a/templates/vscode-settings.json
+++ b/templates/vscode-settings.json
@@ -8,6 +8,6 @@
    },
    "chat.tools.terminal.autoApprove": {
        ".specify/scripts/bash/": true,
-        ".specify/scripts/ps/": true
+        ".specify/scripts/powershell/": true
    }
 }
Author	SHA1	Message	Date
Den Delimarsky	c59595d065	Merge pull request #897 from isdaniel/add-more-lang Support more lang of Common Patterns by Technology	2025-10-15 10:56:08 -07:00
Den Delimarsky	1c16a68df2	Merge pull request #766 from thenets/use-the-number-prefix-to-find-the-right-spec Use the number prefix to find the right spec	2025-10-15 10:55:33 -07:00
Den Delimarsky	39bf3e4d9a	Merge pull request #894 from tennc/main update codebuddy to codebuddy cli	2025-10-15 10:52:25 -07:00
Den Delimarsky	045696641a	Merge pull request #895 from zidoshare/main Fix: incorrect command formatting in agent context file	2025-10-15 10:51:34 -07:00
danielshih	41690cd1d4	format content as copilot suggest	2025-10-15 23:55:00 +08:00
danielshih	e45c469709	Ruby, PHP, Rust, Kotlin, C, C++	2025-10-15 23:15:39 +08:00
hongxuww	8c9e586662	Fix: Fix incorrect command formatting in agent context file The issue is that `sed` treats `&&` as a placeholder instead of a regular character. So in the CLAUDE.md file's "Commands" section, it incorrectly shows: `npm test [ONLY COMMANDS FOR ACTIVE TECHNOLOGIES][ONLY COMMANDS FOR ACTIVE TECHNOLOGIES] npm run lint` instead of the correct: `npm test && npm run lint`	2025-10-15 14:04:22 +00:00
root	ce844c6259	Update CodeBuddy agent name to 'CodeBuddy CLI'	2025-10-15 21:52:59 +08:00
root	84b46cd1b9	Rename CodeBuddy to CodeBuddy CLI in update script	2025-10-15 21:50:11 +08:00
root	0cca67fcd2	Update AI coding agent references in installation guide	2025-10-15 21:47:36 +08:00
root	66fc4c292d	Rename CodeBuddy to CodeBuddy CLI in AGENTS.md	2025-10-15 21:42:08 +08:00
root	2baae57b26	Update README.md	2025-10-15 21:38:16 +08:00
root	514b0548fe	Update CodeBuddy link in README.md	2025-10-15 21:36:01 +08:00
root	be7db635cc	update codebuddyCli	2025-10-15 21:34:40 +08:00
Den Delimarsky	7b55522213	Merge pull request #886 from jarrensj/docs/fix-heading-capitalization-consistency docs: fix heading capitalization for consistency	2025-10-14 23:39:23 -07:00
Jarren San Jose	7ca792509b	docs: fix heading capitalization for consistency	2025-10-14 18:48:47 -07:00
den (work)	3e476c2ba6	Update README.md	2025-10-14 10:38:40 -07:00
den (work)	654a00aac9	Update tasks.md	2025-10-14 10:33:58 -07:00
Den Delimarsky	4690d13f88	Merge pull request #868 from benzyc/patch-1 Update README.md	2025-10-14 07:36:05 -07:00
Den Delimarsky	e7bb98de42	Merge pull request #873 from zidoshare/main fix: update CODEBUDDY file path in agent context scripts	2025-10-14 07:35:13 -07:00
hongxuww	d4f5c75519	fix: update CODEBUDDY file path in agent context scripts	2025-10-14 09:30:43 +00:00
benzyc	09f57a87fa	Update README.md Currently spec-kit is compatible with windows directly, therefore change the prerequisites from Linux/masos to linux/macos/windows. This is quite important for windows users	2025-10-14 09:59:27 +08:00
Den Delimarsky	b702fcbbc0	Merge pull request #861 from uberspeck/docs/add-speckit-tasks-step docs: add /speckit.tasks walkthrough step	2025-10-13 17:47:36 -07:00
Brian Campbell	2c1de4202e	docs(readme): add /speckit.tasks step and renumber walkthrough	2025-10-13 10:18:08 -06:00
Den Delimarsky	e65660ffc3	Merge pull request #831 from ben-edgar/bugfix/cursor-package-name-update fix: align Cursor agent naming to use 'cursor-agent' consistently	2025-10-11 09:05:49 -07:00
Ben Greene	f7ae5781b7	A few more places to update from code review	2025-10-10 21:12:06 -04:00
Ben Greene	d09552fc63	fix: align Cursor agent naming to use 'cursor-agent' consistently The Python CLI was configured to use "cursor-agent" as the agent key in AGENT_CONFIG, causing it to search for release packages with the pattern "spec-kit-template-cursor-agent-sh-.zip". However, the release build scripts were generating packages named "spec-kit-template-cursor-sh-.zip", resulting in a mismatch that prevented successful template downloads. This commit updates the release scripts to use "cursor-agent" consistently throughout, aligning with the AGENT_CONFIG key and the documented best practice of using actual CLI tool names as dictionary keys. Changes: - Update ALL_AGENTS array in create-release-packages.sh - Update case statement for cursor-agent in build_variant() - Update release asset paths in create-github-release.sh - Update documentation in README.md and AGENTS.md to reflect correct usage This ensures that `specify init --ai cursor-agent` correctly finds and downloads the matching release package from GitHub. Fixes the bug where cursor-agent initialization would fail with "No matching release asset found" error. Written with the help of a cursor agent	2025-10-10 20:43:20 -04:00
Den Delimarsky	ed5dbf197f	Merge pull request #828 from github/localden/updates Update clarify.md	2025-10-10 13:19:10 -07:00
den (work)	df4d7fa062	Update clarify.md	2025-10-10 13:09:11 -07:00
Den Delimarsky	b4ecd14ffa	Merge pull request #800 from technoch1ef/patch-1 feat: add documentation for upgrading specify installation	2025-10-10 13:03:59 -07:00
Den Delimarsky	26fde7cfda	Merge pull request #827 from github/localden/updates Update vscode-settings.json	2025-10-10 12:30:16 -07:00
den (work)	8abc812c57	Update vscode-settings.json	2025-10-10 12:29:46 -07:00
Den Delimarsky	940714df0a	Merge pull request #826 from github/localden/updates Hot Fix	2025-10-10 11:58:36 -07:00
den (work)	f393ae9825	Update instructions and bug fix	2025-10-10 11:58:10 -07:00
Den Delimarsky	97dee3e4bf	Merge pull request #825 from github/localden/updates Spec Kit Updates (0.0.19)	2025-10-10 11:50:47 -07:00
den (work)	aec568949c	Update __init__.py	2025-10-10 11:49:51 -07:00
den (work)	ed9044345b	Consolidate Cursor naming	2025-10-10 11:45:51 -07:00
den (work)	058ee510a7	Update CHANGELOG.md	2025-10-10 11:35:48 -07:00
den (work)	e91aca54ee	Git errors are now highlighted.	2025-10-10 11:35:05 -07:00
den (work)	9c87fdd5bb	Update __init__.py	2025-10-10 11:22:57 -07:00
den (work)	301a556110	Merge branch 'localden/updates' of https://github.com/github/spec-kit into localden/updates	2025-10-10 11:15:22 -07:00
den (work)	bb9ec8e638	Refactor agent configuration	2025-10-10 11:12:54 -07:00
Den Delimarsky	e83d2c777d	Update src/specify_cli/__init__.py Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>	2025-10-10 11:07:45 -07:00
Den Delimarsky	68809bdacb	Update scripts/powershell/update-agent-context.ps1 Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>	2025-10-10 11:07:21 -07:00
Den Delimarsky	3cc545243b	Update AGENTS.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>	2025-10-10 11:07:12 -07:00
Den Delimarsky	9ef389baba	Update templates/commands/implement.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>	2025-10-10 11:05:38 -07:00
Den Delimarsky	426ac8ab2e	Update templates/commands/implement.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>	2025-10-10 11:05:16 -07:00
den (work)	4de1b6b6c3	Merge branch 'localden/updates' of https://github.com/github/spec-kit into localden/updates	2025-10-10 11:04:28 -07:00
den (work)	199c63901f	Update CHANGELOG.md	2025-10-10 11:04:25 -07:00
Den Delimarsky	369ed643d7	Merge pull request #462 from lispking/codebuddy feat: support codebuddy ai	2025-10-10 11:04:10 -07:00
Den Delimarsky	6c947cc8d8	Merge branch 'main' into codebuddy	2025-10-10 11:03:13 -07:00
den (work)	07d506feb5	Update changelog	2025-10-10 10:53:21 -07:00
Den Delimarsky	0124a0f32e	Merge pull request #816 from sigent-amazon/feature/add-ignore-file-verification Add ignore file(s) verification step to /speckit.implement command	2025-10-10 10:51:48 -07:00
Den Delimarsky	e7936c3fd0	Merge pull request #808 from hsin19/feature/escape-toml-backslashes fix: correctly escape backslashes in TOML slash command outputs	2025-10-10 10:47:26 -07:00
den (work)	583d556677	Update plan.md	2025-10-10 10:43:31 -07:00
Simon Gent	72ed39d8a1	Add ignore file verification step to /speckit.implement command - Added step 4 for project setup verification - Detects and creates/verifies ignore files based on project setup - Includes patterns for .gitignore, .dockerignore, .eslintignore, .prettierignore, .npmignore, .terraformignore, .helmignore - Provides technology-specific patterns (Node.js, Python, Java, C#/.NET, Go) - Includes tool-specific patterns (Docker, ESLint, Prettier, Terraform) - Renumbered subsequent steps 5-9	2025-10-10 10:11:06 +01:00
Eric Yeh	7c4c1edd85	Escape backslashes in TOML outputs	2025-10-10 06:09:38 +08:00
Oleksandr Ovcharov	5846a38c68	add how to upgrade specify installation	2025-10-09 16:19:36 +02:00
Luiz Costa	47e5f7c2e2	Use the number prefix to find the right spec	2025-10-07 06:45:25 -03:00
King	aa599b8af1	Merge branch 'main' into codebuddy	2025-09-26 09:12:09 +08:00
King	2b2f5a7c2a	Merge branch 'main' into codebuddy	2025-09-23 12:00:46 +08:00
lispking	8b09559690	update CodeBuddy to international site	2025-09-23 05:22:35 +08:00
lispking	318b76de50	feat: support codebuddy ai	2025-09-22 14:34:43 +08:00
King	a85fdd4051	Merge branch 'main' into codebuddy	2025-09-22 14:23:00 +08:00
lispking	92621bca7d	feat: support codebuddy ai	2025-09-22 14:20:31 +08:00