From 15a5630047089d1eb5b6701863ba8e373552501a Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Tue, 21 Oct 2025 10:28:09 -0700 Subject: [PATCH 01/22] Use VS Code handoffs --- templates/commands/constitution.md | 3 +++ templates/commands/plan.md | 5 +++++ templates/commands/specify.md | 4 ++++ templates/commands/tasks.md | 5 +++++ 4 files changed, 17 insertions(+) diff --git a/templates/commands/constitution.md b/templates/commands/constitution.md index dc0793455..1889ec1ff 100644 --- a/templates/commands/constitution.md +++ b/templates/commands/constitution.md @@ -1,5 +1,8 @@ --- description: Create or update the project constitution from interactive or provided principle inputs, ensuring all dependent templates stay in sync. +handoffs: + - label: Build Specification + agent: speckit.spec --- ## User Input diff --git a/templates/commands/plan.md b/templates/commands/plan.md index 2891e221b..f4a98f1c5 100644 --- a/templates/commands/plan.md +++ b/templates/commands/plan.md @@ -1,5 +1,10 @@ --- description: Execute the implementation planning workflow using the plan template to generate design artifacts. +handoffs: + - label: Create Tasks + agent: speckit.tasks + prompt: Break the plan into tasks + send: true scripts: sh: scripts/bash/setup-plan.sh --json ps: scripts/powershell/setup-plan.ps1 -Json diff --git a/templates/commands/specify.md b/templates/commands/specify.md index a75ad280d..b9499246f 100644 --- a/templates/commands/specify.md +++ b/templates/commands/specify.md @@ -1,5 +1,9 @@ --- description: Create or update the feature specification from a natural language feature description. +handoffs: + - label: Build Technical Plan + agent: speckit.plan + prompt: Create a plan for the spec scripts: sh: scripts/bash/create-new-feature.sh --json "{ARGS}" ps: scripts/powershell/create-new-feature.ps1 -Json "{ARGS}" diff --git a/templates/commands/tasks.md b/templates/commands/tasks.md index 964640096..561b664c7 100644 --- a/templates/commands/tasks.md +++ b/templates/commands/tasks.md @@ -1,5 +1,10 @@ --- description: Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts. +handoffs: + - label: Implement Project + agent: speckit.implement + prompt: Start the implementation in phases + send: true scripts: sh: scripts/bash/check-prerequisites.sh --json ps: scripts/powershell/check-prerequisites.ps1 -Json From c59be99dc4a1fce90d8cca148b8cc51cc941439d Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Tue, 21 Oct 2025 10:35:46 -0700 Subject: [PATCH 02/22] Testing hand-offs --- .github/workflows/scripts/create-release-packages.sh | 6 +++--- AGENTS.md | 12 ++++++++++-- scripts/bash/update-agent-context.sh | 2 +- scripts/powershell/update-agent-context.ps1 | 2 +- 4 files changed, 15 insertions(+), 7 deletions(-) diff --git a/.github/workflows/scripts/create-release-packages.sh b/.github/workflows/scripts/create-release-packages.sh index 5462a14fd..25e42ae00 100644 --- a/.github/workflows/scripts/create-release-packages.sh +++ b/.github/workflows/scripts/create-release-packages.sh @@ -95,7 +95,7 @@ generate_commands() { { echo "description = \"$description\""; echo; echo "prompt = \"\"\""; echo "$body"; echo "\"\"\""; } > "$output_dir/speckit.$name.$ext" ;; md) echo "$body" > "$output_dir/speckit.$name.$ext" ;; - prompt.md) + chatmode.md) echo "$body" > "$output_dir/speckit.$name.$ext" ;; esac done @@ -146,8 +146,8 @@ build_variant() { generate_commands gemini toml "{{args}}" "$base_dir/.gemini/commands" "$script" [[ -f agent_templates/gemini/GEMINI.md ]] && cp agent_templates/gemini/GEMINI.md "$base_dir/GEMINI.md" ;; copilot) - mkdir -p "$base_dir/.github/prompts" - generate_commands copilot prompt.md "\$ARGUMENTS" "$base_dir/.github/prompts" "$script" + mkdir -p "$base_dir/.github/chatmodes" + generate_commands copilot chatmode.md "\$ARGUMENTS" "$base_dir/.github/chatmodes" "$script" # Create VS Code workspace settings mkdir -p "$base_dir/.vscode" [[ -f templates/vscode-settings.json ]] && cp templates/vscode-settings.json "$base_dir/.vscode/settings.json" diff --git a/AGENTS.md b/AGENTS.md index 492603cd5..b8f29097f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -33,7 +33,7 @@ Specify supports multiple AI agents by generating agent-specific command files a |-------|-----------|---------|----------|-------------| | **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 | +| **GitHub Copilot** | `.github/chatmodes/` | 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 | @@ -307,6 +307,7 @@ Work within integrated development environments: ### Markdown Format Used by: Claude, Cursor, opencode, Windsurf, Amazon Q Developer +**Standard format:** ```markdown --- description: "Command description" @@ -315,6 +316,13 @@ description: "Command description" Command content with {SCRIPT} and $ARGUMENTS placeholders. ``` +**GitHub Copilot Chat Mode format:** +```markdown +# Command Name + +Command content with {SCRIPT} and $ARGUMENTS placeholders. +``` + ### TOML Format Used by: Gemini, Qwen @@ -330,7 +338,7 @@ Command content with {SCRIPT} and {{args}} placeholders. - **CLI agents**: Usually `./commands/` - **IDE agents**: Follow IDE-specific patterns: - - Copilot: `.github/prompts/` + - Copilot: `.github/chatmodes/` - Cursor: `.cursor/commands/` - Windsurf: `.windsurf/workflows/` diff --git a/scripts/bash/update-agent-context.sh b/scripts/bash/update-agent-context.sh index 71d7e68d0..0957fdb1e 100644 --- a/scripts/bash/update-agent-context.sh +++ b/scripts/bash/update-agent-context.sh @@ -61,7 +61,7 @@ AGENT_TYPE="${1:-}" # Agent-specific file paths CLAUDE_FILE="$REPO_ROOT/CLAUDE.md" GEMINI_FILE="$REPO_ROOT/GEMINI.md" -COPILOT_FILE="$REPO_ROOT/.github/copilot-instructions.md" +COPILOT_FILE="$REPO_ROOT/.github/chatmodes/copilot-instructions.md" CURSOR_FILE="$REPO_ROOT/.cursor/rules/specify-rules.mdc" QWEN_FILE="$REPO_ROOT/QWEN.md" AGENTS_FILE="$REPO_ROOT/AGENTS.md" diff --git a/scripts/powershell/update-agent-context.ps1 b/scripts/powershell/update-agent-context.ps1 index 2fb4abe4d..9898c5245 100644 --- a/scripts/powershell/update-agent-context.ps1 +++ b/scripts/powershell/update-agent-context.ps1 @@ -46,7 +46,7 @@ $NEW_PLAN = $IMPL_PLAN # Agent file paths $CLAUDE_FILE = Join-Path $REPO_ROOT 'CLAUDE.md' $GEMINI_FILE = Join-Path $REPO_ROOT 'GEMINI.md' -$COPILOT_FILE = Join-Path $REPO_ROOT '.github/copilot-instructions.md' +$COPILOT_FILE = Join-Path $REPO_ROOT '.github/chatmodes/copilot-instructions.md' $CURSOR_FILE = Join-Path $REPO_ROOT '.cursor/rules/specify-rules.mdc' $QWEN_FILE = Join-Path $REPO_ROOT 'QWEN.md' $AGENTS_FILE = Join-Path $REPO_ROOT 'AGENTS.md' From 8e9d25e9be648e47127ffd8c9b1ea3b988e5bcec Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Tue, 21 Oct 2025 10:39:11 -0700 Subject: [PATCH 03/22] Update with prompt --- templates/commands/constitution.md | 1 + 1 file changed, 1 insertion(+) diff --git a/templates/commands/constitution.md b/templates/commands/constitution.md index 1889ec1ff..0344142b4 100644 --- a/templates/commands/constitution.md +++ b/templates/commands/constitution.md @@ -3,6 +3,7 @@ description: Create or update the project constitution from interactive or provi handoffs: - label: Build Specification agent: speckit.spec + prompt: Implement the feature specification based on the updated constitution. I want to build... --- ## User Input From 317ae4dad98a9a29354c265cf7655fef6e717b8c Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Tue, 21 Oct 2025 10:48:59 -0700 Subject: [PATCH 04/22] Update prompts --- templates/commands/constitution.md | 2 +- templates/commands/plan.md | 4 +++- templates/commands/specify.md | 3 +++ templates/commands/tasks.md | 4 ++++ 4 files changed, 11 insertions(+), 2 deletions(-) diff --git a/templates/commands/constitution.md b/templates/commands/constitution.md index 0344142b4..d3bd158e5 100644 --- a/templates/commands/constitution.md +++ b/templates/commands/constitution.md @@ -2,7 +2,7 @@ description: Create or update the project constitution from interactive or provided principle inputs, ensuring all dependent templates stay in sync. handoffs: - label: Build Specification - agent: speckit.spec + agent: speckit.specify prompt: Implement the feature specification based on the updated constitution. I want to build... --- diff --git a/templates/commands/plan.md b/templates/commands/plan.md index f4a98f1c5..06b4a6fc3 100644 --- a/templates/commands/plan.md +++ b/templates/commands/plan.md @@ -4,7 +4,9 @@ handoffs: - label: Create Tasks agent: speckit.tasks prompt: Break the plan into tasks - send: true + - label: Create Checklist + agent: speckit.checklist + prompt: Create a checklist for the following domain... scripts: sh: scripts/bash/setup-plan.sh --json ps: scripts/powershell/setup-plan.ps1 -Json diff --git a/templates/commands/specify.md b/templates/commands/specify.md index b9499246f..a7ae5dd43 100644 --- a/templates/commands/specify.md +++ b/templates/commands/specify.md @@ -4,6 +4,9 @@ handoffs: - label: Build Technical Plan agent: speckit.plan prompt: Create a plan for the spec + - label: Clarify Spec Requirements + agent: speckit.clarify + prompt: Clarify specification requirements scripts: sh: scripts/bash/create-new-feature.sh --json "{ARGS}" ps: scripts/powershell/create-new-feature.ps1 -Json "{ARGS}" diff --git a/templates/commands/tasks.md b/templates/commands/tasks.md index 561b664c7..c3179e3ff 100644 --- a/templates/commands/tasks.md +++ b/templates/commands/tasks.md @@ -1,6 +1,10 @@ --- description: Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts. handoffs: + - label: Analyze For Consistency + agent: speckit.analyze + prompt: Start the implementation in phases + send: true - label: Implement Project agent: speckit.implement prompt: Start the implementation in phases From dbd1437aeaa08a2a54239c4d46feaaef58f2c234 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Tue, 21 Oct 2025 13:17:48 -0700 Subject: [PATCH 05/22] Let's switch to proper prompts --- .github/workflows/scripts/create-release-packages.sh | 6 +++--- AGENTS.md | 9 ++++++--- scripts/bash/update-agent-context.sh | 2 +- scripts/powershell/update-agent-context.ps1 | 2 +- templates/commands/analyze.md | 1 + templates/commands/checklist.md | 1 + templates/commands/clarify.md | 1 + templates/commands/constitution.md | 1 + templates/commands/implement.md | 1 + templates/commands/plan.md | 1 + templates/commands/specify.md | 1 + templates/commands/tasks.md | 3 ++- 12 files changed, 20 insertions(+), 9 deletions(-) diff --git a/.github/workflows/scripts/create-release-packages.sh b/.github/workflows/scripts/create-release-packages.sh index 25e42ae00..5462a14fd 100644 --- a/.github/workflows/scripts/create-release-packages.sh +++ b/.github/workflows/scripts/create-release-packages.sh @@ -95,7 +95,7 @@ generate_commands() { { echo "description = \"$description\""; echo; echo "prompt = \"\"\""; echo "$body"; echo "\"\"\""; } > "$output_dir/speckit.$name.$ext" ;; md) echo "$body" > "$output_dir/speckit.$name.$ext" ;; - chatmode.md) + prompt.md) echo "$body" > "$output_dir/speckit.$name.$ext" ;; esac done @@ -146,8 +146,8 @@ build_variant() { generate_commands gemini toml "{{args}}" "$base_dir/.gemini/commands" "$script" [[ -f agent_templates/gemini/GEMINI.md ]] && cp agent_templates/gemini/GEMINI.md "$base_dir/GEMINI.md" ;; copilot) - mkdir -p "$base_dir/.github/chatmodes" - generate_commands copilot chatmode.md "\$ARGUMENTS" "$base_dir/.github/chatmodes" "$script" + mkdir -p "$base_dir/.github/prompts" + generate_commands copilot prompt.md "\$ARGUMENTS" "$base_dir/.github/prompts" "$script" # Create VS Code workspace settings mkdir -p "$base_dir/.vscode" [[ -f templates/vscode-settings.json ]] && cp templates/vscode-settings.json "$base_dir/.vscode/settings.json" diff --git a/AGENTS.md b/AGENTS.md index b8f29097f..23906556e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -33,7 +33,7 @@ Specify supports multiple AI agents by generating agent-specific command files a |-------|-----------|---------|----------|-------------| | **Claude Code** | `.claude/commands/` | Markdown | `claude` | Anthropic's Claude Code CLI | | **Gemini CLI** | `.gemini/commands/` | TOML | `gemini` | Google's Gemini CLI | -| **GitHub Copilot** | `.github/chatmodes/` | Markdown | N/A (IDE-based) | GitHub Copilot in VS Code | +| **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 | @@ -318,7 +318,10 @@ Command content with {SCRIPT} and $ARGUMENTS placeholders. **GitHub Copilot Chat Mode format:** ```markdown -# Command Name +--- +description: "Command description" +mode: speckit.command-name +--- Command content with {SCRIPT} and $ARGUMENTS placeholders. ``` @@ -338,7 +341,7 @@ Command content with {SCRIPT} and {{args}} placeholders. - **CLI agents**: Usually `./commands/` - **IDE agents**: Follow IDE-specific patterns: - - Copilot: `.github/chatmodes/` + - Copilot: `.github/prompts/` - Cursor: `.cursor/commands/` - Windsurf: `.windsurf/workflows/` diff --git a/scripts/bash/update-agent-context.sh b/scripts/bash/update-agent-context.sh index 0957fdb1e..becbded2e 100644 --- a/scripts/bash/update-agent-context.sh +++ b/scripts/bash/update-agent-context.sh @@ -61,7 +61,7 @@ AGENT_TYPE="${1:-}" # Agent-specific file paths CLAUDE_FILE="$REPO_ROOT/CLAUDE.md" GEMINI_FILE="$REPO_ROOT/GEMINI.md" -COPILOT_FILE="$REPO_ROOT/.github/chatmodes/copilot-instructions.md" +COPILOT_FILE="$REPO_ROOT/.github/prompts/copilot-instructions.md" CURSOR_FILE="$REPO_ROOT/.cursor/rules/specify-rules.mdc" QWEN_FILE="$REPO_ROOT/QWEN.md" AGENTS_FILE="$REPO_ROOT/AGENTS.md" diff --git a/scripts/powershell/update-agent-context.ps1 b/scripts/powershell/update-agent-context.ps1 index 9898c5245..db30c3b70 100644 --- a/scripts/powershell/update-agent-context.ps1 +++ b/scripts/powershell/update-agent-context.ps1 @@ -46,7 +46,7 @@ $NEW_PLAN = $IMPL_PLAN # Agent file paths $CLAUDE_FILE = Join-Path $REPO_ROOT 'CLAUDE.md' $GEMINI_FILE = Join-Path $REPO_ROOT 'GEMINI.md' -$COPILOT_FILE = Join-Path $REPO_ROOT '.github/chatmodes/copilot-instructions.md' +$COPILOT_FILE = Join-Path $REPO_ROOT '.github/prompts/copilot-instructions.md' $CURSOR_FILE = Join-Path $REPO_ROOT '.cursor/rules/specify-rules.mdc' $QWEN_FILE = Join-Path $REPO_ROOT 'QWEN.md' $AGENTS_FILE = Join-Path $REPO_ROOT 'AGENTS.md' diff --git a/templates/commands/analyze.md b/templates/commands/analyze.md index 4c2986765..0f4846059 100644 --- a/templates/commands/analyze.md +++ b/templates/commands/analyze.md @@ -1,5 +1,6 @@ --- description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation. +mode: speckit.analyze scripts: sh: scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks ps: scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks diff --git a/templates/commands/checklist.md b/templates/commands/checklist.md index 0900e33a4..9e6383aa6 100644 --- a/templates/commands/checklist.md +++ b/templates/commands/checklist.md @@ -1,5 +1,6 @@ --- description: Generate a custom checklist for the current feature based on user requirements. +mode: speckit.checklist scripts: sh: scripts/bash/check-prerequisites.sh --json ps: scripts/powershell/check-prerequisites.ps1 -Json diff --git a/templates/commands/clarify.md b/templates/commands/clarify.md index 65f2536f7..4093d0c7f 100644 --- a/templates/commands/clarify.md +++ b/templates/commands/clarify.md @@ -1,5 +1,6 @@ --- description: Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec. +mode: speckit.clarify scripts: sh: scripts/bash/check-prerequisites.sh --json --paths-only ps: scripts/powershell/check-prerequisites.ps1 -Json -PathsOnly diff --git a/templates/commands/constitution.md b/templates/commands/constitution.md index d3bd158e5..e0050f06d 100644 --- a/templates/commands/constitution.md +++ b/templates/commands/constitution.md @@ -1,5 +1,6 @@ --- description: Create or update the project constitution from interactive or provided principle inputs, ensuring all dependent templates stay in sync. +mode: speckit.constitution handoffs: - label: Build Specification agent: speckit.specify diff --git a/templates/commands/implement.md b/templates/commands/implement.md index c6ddc672d..9102d515a 100644 --- a/templates/commands/implement.md +++ b/templates/commands/implement.md @@ -1,5 +1,6 @@ --- description: Execute the implementation plan by processing and executing all tasks defined in tasks.md +mode: speckit.implement scripts: sh: scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks ps: scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks diff --git a/templates/commands/plan.md b/templates/commands/plan.md index 06b4a6fc3..cff93a744 100644 --- a/templates/commands/plan.md +++ b/templates/commands/plan.md @@ -1,5 +1,6 @@ --- description: Execute the implementation planning workflow using the plan template to generate design artifacts. +mode: speckit.plan handoffs: - label: Create Tasks agent: speckit.tasks diff --git a/templates/commands/specify.md b/templates/commands/specify.md index a7ae5dd43..c5eea64c0 100644 --- a/templates/commands/specify.md +++ b/templates/commands/specify.md @@ -1,5 +1,6 @@ --- description: Create or update the feature specification from a natural language feature description. +mode: speckit.specify handoffs: - label: Build Technical Plan agent: speckit.plan diff --git a/templates/commands/tasks.md b/templates/commands/tasks.md index c3179e3ff..4674e7e0b 100644 --- a/templates/commands/tasks.md +++ b/templates/commands/tasks.md @@ -1,9 +1,10 @@ --- description: Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts. +mode: speckit.tasks handoffs: - label: Analyze For Consistency agent: speckit.analyze - prompt: Start the implementation in phases + prompt: Run a project analysis for consistency send: true - label: Implement Project agent: speckit.implement From 14a574a6a8591c4522ac11601c08f91656345b96 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Tue, 21 Oct 2025 14:29:45 -0700 Subject: [PATCH 06/22] Chatmodes are back in vogue --- .github/workflows/scripts/create-release-packages.sh | 6 +++--- AGENTS.md | 4 ++-- scripts/bash/update-agent-context.sh | 2 +- scripts/powershell/update-agent-context.ps1 | 2 +- templates/commands/analyze.md | 1 - templates/commands/checklist.md | 1 - templates/commands/clarify.md | 1 - templates/commands/constitution.md | 1 - templates/commands/implement.md | 1 - templates/commands/plan.md | 1 - templates/commands/specify.md | 1 - templates/commands/tasks.md | 1 - 12 files changed, 7 insertions(+), 15 deletions(-) diff --git a/.github/workflows/scripts/create-release-packages.sh b/.github/workflows/scripts/create-release-packages.sh index 5462a14fd..25e42ae00 100644 --- a/.github/workflows/scripts/create-release-packages.sh +++ b/.github/workflows/scripts/create-release-packages.sh @@ -95,7 +95,7 @@ generate_commands() { { echo "description = \"$description\""; echo; echo "prompt = \"\"\""; echo "$body"; echo "\"\"\""; } > "$output_dir/speckit.$name.$ext" ;; md) echo "$body" > "$output_dir/speckit.$name.$ext" ;; - prompt.md) + chatmode.md) echo "$body" > "$output_dir/speckit.$name.$ext" ;; esac done @@ -146,8 +146,8 @@ build_variant() { generate_commands gemini toml "{{args}}" "$base_dir/.gemini/commands" "$script" [[ -f agent_templates/gemini/GEMINI.md ]] && cp agent_templates/gemini/GEMINI.md "$base_dir/GEMINI.md" ;; copilot) - mkdir -p "$base_dir/.github/prompts" - generate_commands copilot prompt.md "\$ARGUMENTS" "$base_dir/.github/prompts" "$script" + mkdir -p "$base_dir/.github/chatmodes" + generate_commands copilot chatmode.md "\$ARGUMENTS" "$base_dir/.github/chatmodes" "$script" # Create VS Code workspace settings mkdir -p "$base_dir/.vscode" [[ -f templates/vscode-settings.json ]] && cp templates/vscode-settings.json "$base_dir/.vscode/settings.json" diff --git a/AGENTS.md b/AGENTS.md index 23906556e..b8cb1f181 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -33,7 +33,7 @@ Specify supports multiple AI agents by generating agent-specific command files a |-------|-----------|---------|----------|-------------| | **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 | +| **GitHub Copilot** | `.github/chatmodes/` | 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 | @@ -341,7 +341,7 @@ Command content with {SCRIPT} and {{args}} placeholders. - **CLI agents**: Usually `./commands/` - **IDE agents**: Follow IDE-specific patterns: - - Copilot: `.github/prompts/` + - Copilot: `.github/chatmodes/` - Cursor: `.cursor/commands/` - Windsurf: `.windsurf/workflows/` diff --git a/scripts/bash/update-agent-context.sh b/scripts/bash/update-agent-context.sh index becbded2e..0957fdb1e 100644 --- a/scripts/bash/update-agent-context.sh +++ b/scripts/bash/update-agent-context.sh @@ -61,7 +61,7 @@ AGENT_TYPE="${1:-}" # Agent-specific file paths CLAUDE_FILE="$REPO_ROOT/CLAUDE.md" GEMINI_FILE="$REPO_ROOT/GEMINI.md" -COPILOT_FILE="$REPO_ROOT/.github/prompts/copilot-instructions.md" +COPILOT_FILE="$REPO_ROOT/.github/chatmodes/copilot-instructions.md" CURSOR_FILE="$REPO_ROOT/.cursor/rules/specify-rules.mdc" QWEN_FILE="$REPO_ROOT/QWEN.md" AGENTS_FILE="$REPO_ROOT/AGENTS.md" diff --git a/scripts/powershell/update-agent-context.ps1 b/scripts/powershell/update-agent-context.ps1 index db30c3b70..9898c5245 100644 --- a/scripts/powershell/update-agent-context.ps1 +++ b/scripts/powershell/update-agent-context.ps1 @@ -46,7 +46,7 @@ $NEW_PLAN = $IMPL_PLAN # Agent file paths $CLAUDE_FILE = Join-Path $REPO_ROOT 'CLAUDE.md' $GEMINI_FILE = Join-Path $REPO_ROOT 'GEMINI.md' -$COPILOT_FILE = Join-Path $REPO_ROOT '.github/prompts/copilot-instructions.md' +$COPILOT_FILE = Join-Path $REPO_ROOT '.github/chatmodes/copilot-instructions.md' $CURSOR_FILE = Join-Path $REPO_ROOT '.cursor/rules/specify-rules.mdc' $QWEN_FILE = Join-Path $REPO_ROOT 'QWEN.md' $AGENTS_FILE = Join-Path $REPO_ROOT 'AGENTS.md' diff --git a/templates/commands/analyze.md b/templates/commands/analyze.md index 0f4846059..4c2986765 100644 --- a/templates/commands/analyze.md +++ b/templates/commands/analyze.md @@ -1,6 +1,5 @@ --- description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation. -mode: speckit.analyze scripts: sh: scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks ps: scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks diff --git a/templates/commands/checklist.md b/templates/commands/checklist.md index 9e6383aa6..0900e33a4 100644 --- a/templates/commands/checklist.md +++ b/templates/commands/checklist.md @@ -1,6 +1,5 @@ --- description: Generate a custom checklist for the current feature based on user requirements. -mode: speckit.checklist scripts: sh: scripts/bash/check-prerequisites.sh --json ps: scripts/powershell/check-prerequisites.ps1 -Json diff --git a/templates/commands/clarify.md b/templates/commands/clarify.md index 4093d0c7f..65f2536f7 100644 --- a/templates/commands/clarify.md +++ b/templates/commands/clarify.md @@ -1,6 +1,5 @@ --- description: Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec. -mode: speckit.clarify scripts: sh: scripts/bash/check-prerequisites.sh --json --paths-only ps: scripts/powershell/check-prerequisites.ps1 -Json -PathsOnly diff --git a/templates/commands/constitution.md b/templates/commands/constitution.md index e0050f06d..d3bd158e5 100644 --- a/templates/commands/constitution.md +++ b/templates/commands/constitution.md @@ -1,6 +1,5 @@ --- description: Create or update the project constitution from interactive or provided principle inputs, ensuring all dependent templates stay in sync. -mode: speckit.constitution handoffs: - label: Build Specification agent: speckit.specify diff --git a/templates/commands/implement.md b/templates/commands/implement.md index 9102d515a..c6ddc672d 100644 --- a/templates/commands/implement.md +++ b/templates/commands/implement.md @@ -1,6 +1,5 @@ --- description: Execute the implementation plan by processing and executing all tasks defined in tasks.md -mode: speckit.implement scripts: sh: scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks ps: scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks diff --git a/templates/commands/plan.md b/templates/commands/plan.md index cff93a744..06b4a6fc3 100644 --- a/templates/commands/plan.md +++ b/templates/commands/plan.md @@ -1,6 +1,5 @@ --- description: Execute the implementation planning workflow using the plan template to generate design artifacts. -mode: speckit.plan handoffs: - label: Create Tasks agent: speckit.tasks diff --git a/templates/commands/specify.md b/templates/commands/specify.md index c5eea64c0..a7ae5dd43 100644 --- a/templates/commands/specify.md +++ b/templates/commands/specify.md @@ -1,6 +1,5 @@ --- description: Create or update the feature specification from a natural language feature description. -mode: speckit.specify handoffs: - label: Build Technical Plan agent: speckit.plan diff --git a/templates/commands/tasks.md b/templates/commands/tasks.md index 4674e7e0b..87e4c5113 100644 --- a/templates/commands/tasks.md +++ b/templates/commands/tasks.md @@ -1,6 +1,5 @@ --- description: Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts. -mode: speckit.tasks handoffs: - label: Analyze For Consistency agent: speckit.analyze From 37e87c78a0c0c47e6e799a39394c4de15f0fdb3d Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Tue, 21 Oct 2025 14:34:19 -0700 Subject: [PATCH 07/22] Hand offs with prompts --- .../scripts/create-release-packages.sh | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/.github/workflows/scripts/create-release-packages.sh b/.github/workflows/scripts/create-release-packages.sh index 25e42ae00..d79f14033 100644 --- a/.github/workflows/scripts/create-release-packages.sh +++ b/.github/workflows/scripts/create-release-packages.sh @@ -101,6 +101,26 @@ generate_commands() { done } +generate_copilot_prompts() { + local chatmodes_dir=$1 prompts_dir=$2 + mkdir -p "$prompts_dir" + + # Generate a .prompt.md file for each .chatmode.md file + for chatmode_file in "$chatmodes_dir"/speckit.*.chatmode.md; do + [[ -f "$chatmode_file" ]] || continue + + local basename=$(basename "$chatmode_file" .chatmode.md) + local prompt_file="$prompts_dir/${basename}.prompt.md" + + # Create prompt file with agent frontmatter + cat > "$prompt_file" < Date: Tue, 21 Oct 2025 14:44:17 -0700 Subject: [PATCH 08/22] Prompt updates --- templates/commands/clarify.md | 4 ++++ templates/commands/specify.md | 3 ++- 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/templates/commands/clarify.md b/templates/commands/clarify.md index 65f2536f7..b91d0f90b 100644 --- a/templates/commands/clarify.md +++ b/templates/commands/clarify.md @@ -1,5 +1,9 @@ --- description: Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec. +handoffs: + - label: Build Technical Plan + agent: speckit.plan + prompt: Create a plan for the spec. I am building with... scripts: sh: scripts/bash/check-prerequisites.sh --json --paths-only ps: scripts/powershell/check-prerequisites.ps1 -Json -PathsOnly diff --git a/templates/commands/specify.md b/templates/commands/specify.md index a7ae5dd43..1329120d2 100644 --- a/templates/commands/specify.md +++ b/templates/commands/specify.md @@ -3,10 +3,11 @@ description: Create or update the feature specification from a natural language handoffs: - label: Build Technical Plan agent: speckit.plan - prompt: Create a plan for the spec + prompt: Create a plan for the spec. I am building with... - label: Clarify Spec Requirements agent: speckit.clarify prompt: Clarify specification requirements + send: true scripts: sh: scripts/bash/create-new-feature.sh --json "{ARGS}" ps: scripts/powershell/create-new-feature.ps1 -Json "{ARGS}" From 9786e588b7900c8eae9a76e0a9e5d0400d204cf1 Mon Sep 17 00:00:00 2001 From: "den (work)" <53200638+localden@users.noreply.github.com> Date: Tue, 21 Oct 2025 15:12:33 -0700 Subject: [PATCH 09/22] Lint fixes --- AGENTS.md | 29 +++++++++++++--- CHANGELOG.md | 4 +-- CONTRIBUTING.md | 1 - README.md | 49 +++++++++++++------------- SECURITY.md | 16 ++++----- SUPPORT.md | 3 +- docs/README.md | 3 +- docs/index.md | 7 ++-- docs/installation.md | 4 ++- docs/local-development.md | 10 ++++-- docs/quickstart.md | 2 +- spec-driven.md | 1 - templates/agent-file-template.md | 5 +++ templates/checklist-template.md | 1 - templates/commands/analyze.md | 1 - templates/commands/checklist.md | 38 +++++++++++--------- templates/commands/clarify.md | 56 +++++++++++++++--------------- templates/commands/constitution.md | 8 ++--- templates/commands/implement.md | 42 +++++++++++----------- templates/commands/plan.md | 3 +- templates/commands/specify.md | 21 ++++++----- templates/commands/tasks.md | 8 ++--- templates/plan-template.md | 1 - templates/spec-template.md | 1 - templates/tasks-template.md | 5 ++- 25 files changed, 176 insertions(+), 143 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index b8cb1f181..eb587e414 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -68,12 +68,14 @@ AGENT_CONFIG = { ``` **Key Design Principle**: The dictionary key should match the actual executable name that users install. For example: + - ✅ Use `"cursor-agent"` because the CLI tool is literally called `cursor-agent` - ❌ Don't use `"cursor"` as a shortcut if the tool is `cursor-agent` This eliminates the need for special-case mappings throughout the codebase. **Field Explanations**: + - `name`: Human-readable display name shown to users - `folder`: Directory where agent-specific files are stored (relative to project root) - `install_url`: Installation documentation URL (set to `None` for IDE-based agents) @@ -102,12 +104,14 @@ Update the **Supported AI Agents** section in `README.md` to include the new age Modify `.github/workflows/scripts/create-release-packages.sh`: -##### Add to ALL_AGENTS array: +##### Add to ALL_AGENTS array + ```bash ALL_AGENTS=(claude gemini copilot cursor-agent qwen opencode windsurf q) ``` -##### Add case statement for directory structure: +##### Add case statement for directory structure + ```bash case $agent in # ... existing cases ... @@ -131,14 +135,16 @@ gh release create "$VERSION" \ #### 5. Update Agent Context Scripts -##### Bash script (`scripts/bash/update-agent-context.sh`): +##### 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 ... @@ -151,14 +157,16 @@ case "$AGENT_TYPE" in esac ``` -##### PowerShell script (`scripts/powershell/update-agent-context.ps1`): +##### 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 ... @@ -200,6 +208,7 @@ elif selected_ai == "windsurf": **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 @@ -207,6 +216,7 @@ elif selected_ai == "windsurf": **Example - The Cursor Lesson:** ❌ **Wrong approach** (requires special-case mapping): + ```python AGENT_CONFIG = { "cursor": { # Shorthand that doesn't match the actual tool @@ -222,6 +232,7 @@ if agent_key == "cursor": ``` ✅ **Correct approach** (no mapping needed): + ```python AGENT_CONFIG = { "cursor-agent": { # Matches the actual executable name @@ -234,6 +245,7 @@ AGENT_CONFIG = { ``` **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 @@ -289,6 +301,7 @@ echo "✅ Done" ### CLI-Based Agents Require a command-line tool to be installed: + - **Claude Code**: `claude` CLI - **Gemini CLI**: `gemini` CLI - **Cursor**: `cursor-agent` CLI @@ -298,16 +311,20 @@ Require a command-line tool to be installed: - **CodeBuddy CLI**: `codebuddy` 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, Amazon Q Developer **Standard format:** + ```markdown --- description: "Command description" @@ -317,6 +334,7 @@ Command content with {SCRIPT} and $ARGUMENTS placeholders. ``` **GitHub Copilot Chat Mode format:** + ```markdown --- description: "Command description" @@ -327,6 +345,7 @@ Command content with {SCRIPT} and $ARGUMENTS placeholders. ``` ### TOML Format + Used by: Gemini, Qwen ```toml @@ -348,6 +367,7 @@ Command content with {SCRIPT} and {{args}} placeholders. ## Argument Patterns Different agents use different argument placeholders: + - **Markdown/prompt-based**: `$ARGUMENTS` - **TOML-based**: `{{args}}` - **Script placeholders**: `{SCRIPT}` (replaced with actual script path) @@ -383,4 +403,3 @@ When adding new agents: --- *This documentation should be updated whenever new agents are added to maintain accuracy and completeness.* - diff --git a/CHANGELOG.md b/CHANGELOG.md index 3ca2ee00f..8259e8f1d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -63,7 +63,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - New `/clarify` command template to surface up to 5 targeted clarification questions for an existing spec and persist answers into a Clarifications section in the spec. - New `/analyze` command template providing a non-destructive cross-artifact discrepancy and alignment report (spec, clarifications, plan, tasks, constitution) inserted after `/tasks` and before `/implement`. - - Note: Constitution rules are explicitly treated as non-negotiable; any conflict is a CRITICAL finding requiring artifact remediation, not weakening of principles. + - Note: Constitution rules are explicitly treated as non-negotiable; any conflict is a CRITICAL finding requiring artifact remediation, not weakening of principles. ## [0.0.16] - 2025-09-22 @@ -140,7 +140,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Updated command instructions in the CLI. - Cleaned up the code to not render agent-specific information when it's generic. - ## [0.0.6] - 2025-09-17 ### Added @@ -166,4 +165,3 @@ N/A ### Changed N/A - diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 928949154..da41f4760 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -125,4 +125,3 @@ Please be respectful to maintainers and disclose AI assistance. - [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/) - [Using Pull Requests](https://help.github.com/articles/about-pull-requests/) - [GitHub Help](https://help.github.com) - diff --git a/README.md b/README.md index cb20ad6c0..27fce7889 100644 --- a/README.md +++ b/README.md @@ -417,16 +417,16 @@ At this stage, your project folder contents should resemble the following: ```text └── .specify ├── memory - │ └── constitution.md + │ └── constitution.md ├── scripts - │ ├── check-prerequisites.sh - │ ├── common.sh - │ ├── create-new-feature.sh - │ ├── setup-plan.sh - │ └── update-claude-md.sh + │ ├── check-prerequisites.sh + │ ├── common.sh + │ ├── create-new-feature.sh + │ ├── setup-plan.sh + │ └── update-claude-md.sh ├── specs - │ └── 001-create-taskify - │ └── spec.md + │ └── 001-create-taskify + │ └── spec.md └── templates ├── plan-template.md ├── spec-template.md @@ -440,6 +440,7 @@ With the baseline specification created, you can go ahead and clarify any of the You should run the structured clarification workflow **before** creating a technical plan to reduce rework downstream. Preferred order: + 1. Use `/speckit.clarify` (structured) – sequential, coverage-based questioning that records answers in a Clarifications section. 2. Optionally follow up with ad-hoc free-form refinement if something still feels vague. @@ -477,23 +478,23 @@ The output of this step will include a number of implementation detail documents . ├── CLAUDE.md ├── memory -│ └── constitution.md +│ └── constitution.md ├── scripts -│ ├── check-prerequisites.sh -│ ├── common.sh -│ ├── create-new-feature.sh -│ ├── setup-plan.sh -│ └── update-claude-md.sh +│ ├── check-prerequisites.sh +│ ├── common.sh +│ ├── create-new-feature.sh +│ ├── setup-plan.sh +│ └── update-claude-md.sh ├── specs -│ └── 001-create-taskify -│ ├── contracts -│ │ ├── api-spec.json -│ │ └── signalr-spec.md -│ ├── data-model.md -│ ├── plan.md -│ ├── quickstart.md -│ ├── research.md -│ └── spec.md +│ └── 001-create-taskify +│ ├── contracts +│ │ ├── api-spec.json +│ │ └── signalr-spec.md +│ ├── data-model.md +│ ├── plan.md +│ ├── quickstart.md +│ ├── research.md +│ └── spec.md └── templates ├── CLAUDE-template.md ├── plan-template.md @@ -575,6 +576,7 @@ Once ready, use the `/speckit.implement` command to execute your implementation ``` The `/speckit.implement` command will: + - Validate that all prerequisites are in place (constitution, spec, plan, and tasks) - Parse the task breakdown from `tasks.md` - Execute tasks in the correct order, respecting dependencies and parallel execution markers @@ -625,4 +627,3 @@ This project is heavily influenced by and based on the work and research of [Joh ## 📄 License This project is licensed under the terms of the MIT open source license. Please refer to the [LICENSE](./LICENSE) file for the full terms. - diff --git a/SECURITY.md b/SECURITY.md index 67a9cbf2c..6424c8b21 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -4,7 +4,7 @@ Thanks for helping make GitHub safe for everyone. GitHub takes the security of our software products and services seriously, including all of the open source code repositories managed through our GitHub organizations, such as [GitHub](https://github.com/GitHub). -Even though [open source repositories are outside of the scope of our bug bounty program](https://bounty.github.com/index.html#scope) and therefore not eligible for bounty rewards, we will ensure that your finding gets passed along to the appropriate maintainers for remediation. +Even though [open source repositories are outside of the scope of our bug bounty program](https://bounty.github.com/index.html#scope) and therefore not eligible for bounty rewards, we will ensure that your finding gets passed along to the appropriate maintainers for remediation. ## Reporting Security Issues @@ -16,13 +16,13 @@ Instead, please send an email to opensource-security[@]github.com. Please include as much of the information listed below as you can to help us better understand and resolve the issue: - * The type of issue (e.g., buffer overflow, SQL injection, or cross-site scripting) - * Full paths of source file(s) related to the manifestation of the issue - * The location of the affected source code (tag/branch/commit or direct URL) - * Any special configuration required to reproduce the issue - * Step-by-step instructions to reproduce the issue - * Proof-of-concept or exploit code (if possible) - * Impact of the issue, including how an attacker might exploit the issue +* The type of issue (e.g., buffer overflow, SQL injection, or cross-site scripting) +* Full paths of source file(s) related to the manifestation of the issue +* The location of the affected source code (tag/branch/commit or direct URL) +* Any special configuration required to reproduce the issue +* Step-by-step instructions to reproduce the issue +* Proof-of-concept or exploit code (if possible) +* Impact of the issue, including how an attacker might exploit the issue This information will help us triage your report more quickly. diff --git a/SUPPORT.md b/SUPPORT.md index c75ce9bd0..c6acf76e0 100644 --- a/SUPPORT.md +++ b/SUPPORT.md @@ -1,4 +1,4 @@ -# Support +# Support ## How to file issues and get help @@ -17,4 +17,3 @@ For help or questions about using this project, please: ## GitHub Support Policy Support for this project is limited to the resources listed above. - diff --git a/docs/README.md b/docs/README.md index 7a155cfa6..a9edc81dc 100644 --- a/docs/README.md +++ b/docs/README.md @@ -7,11 +7,13 @@ This folder contains the documentation source files for Spec Kit, built using [D To build the documentation locally: 1. Install DocFX: + ```bash dotnet tool install -g docfx ``` 2. Build the documentation: + ```bash cd docs docfx docfx.json --serve @@ -31,4 +33,3 @@ To build the documentation locally: ## Deployment Documentation is automatically built and deployed to GitHub Pages when changes are pushed to the `main` branch. The workflow is defined in `.github/workflows/docs.yml`. - diff --git a/docs/index.md b/docs/index.md index e134404e2..38a6de34e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -18,7 +18,7 @@ Spec-Driven Development **flips the script** on traditional software development Spec-Driven Development is a structured process that emphasizes: -- **Intent-driven development** where specifications define the "_what_" before the "_how_" +- **Intent-driven development** where specifications define the "*what*" before the "*how*" - **Rich specification creation** using guardrails and organizational principles - **Multi-step refinement** rather than one-shot code generation from prompts - **Heavy reliance** on advanced AI model capabilities for specification interpretation @@ -36,19 +36,23 @@ Spec-Driven Development is a structured process that emphasizes: Our research and experimentation focus on: ### Technology Independence + - Create applications using diverse technology stacks - Validate the hypothesis that Spec-Driven Development is a process not tied to specific technologies, programming languages, or frameworks ### Enterprise Constraints + - Demonstrate mission-critical application development - Incorporate organizational constraints (cloud providers, tech stacks, engineering practices) - Support enterprise design systems and compliance requirements ### User-Centric Development + - Build applications for different user cohorts and preferences - Support various development approaches (from vibe-coding to AI-native development) ### Creative & Iterative Processes + - Validate the concept of parallel implementation exploration - Provide robust iterative feature development workflows - Extend processes to handle upgrades and modernization tasks @@ -60,4 +64,3 @@ Please see our [Contributing Guide](https://github.com/github/spec-kit/blob/main ## Support For support, please check our [Support Guide](https://github.com/github/spec-kit/blob/main/SUPPORT.md) or open an issue on GitHub. - diff --git a/docs/installation.md b/docs/installation.md index d4dfaa3dd..6daff2431 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -42,11 +42,13 @@ uvx --from git+https://github.com/github/spec-kit.git specify init --script sh uvx --from git+https://github.com/github/spec-kit.git specify init --script ps @@ -63,6 +65,7 @@ uvx --from git+https://github.com/github/spec-kit.git specify init --script ps # Force PowerShell uvx --from git+https://github.com/github/spec-kit.git specify init --script sh # Force POSIX shell @@ -120,4 +121,3 @@ implement specs/002-create-taskify/plan.md - Read the complete methodology for in-depth guidance - Check out more examples in the repository - Explore the source code on GitHub - diff --git a/spec-driven.md b/spec-driven.md index 13edc9e3f..0e546ff3c 100644 --- a/spec-driven.md +++ b/spec-driven.md @@ -401,4 +401,3 @@ By embedding these principles into the specification and planning process, SDD e This isn't about replacing developers or automating creativity. It's about amplifying human capability by automating mechanical translation. It's about creating a tight feedback loop where specifications, research, and code evolve together, each iteration bringing deeper understanding and better alignment between intent and implementation. Software development needs better tools for maintaining alignment between intent and implementation. SDD provides the methodology for achieving this alignment through executable specifications that generate code rather than merely guiding it. - diff --git a/templates/agent-file-template.md b/templates/agent-file-template.md index f73499792..27961a8b1 100644 --- a/templates/agent-file-template.md +++ b/templates/agent-file-template.md @@ -3,20 +3,25 @@ Auto-generated from all feature plans. Last updated: [DATE] ## Active Technologies + [EXTRACTED FROM ALL PLAN.MD FILES] ## Project Structure + ``` [ACTUAL STRUCTURE FROM PLANS] ``` ## Commands + [ONLY COMMANDS FOR ACTIVE TECHNOLOGIES] ## Code Style + [LANGUAGE-SPECIFIC, ONLY FOR LANGUAGES IN USE] ## Recent Changes + [LAST 3 FEATURES AND WHAT THEY ADDED] diff --git a/templates/checklist-template.md b/templates/checklist-template.md index 1c8b11a18..806657da0 100644 --- a/templates/checklist-template.md +++ b/templates/checklist-template.md @@ -38,4 +38,3 @@ - Add comments or findings inline - Link to relevant resources or documentation - Items are numbered sequentially for easy reference - diff --git a/templates/commands/analyze.md b/templates/commands/analyze.md index 4c2986765..827d4e4ca 100644 --- a/templates/commands/analyze.md +++ b/templates/commands/analyze.md @@ -185,4 +185,3 @@ Ask the user: "Would you like me to suggest concrete remediation edits for the t ## Context {ARGS} - diff --git a/templates/commands/checklist.md b/templates/commands/checklist.md index 0900e33a4..e32a2c843 100644 --- a/templates/commands/checklist.md +++ b/templates/commands/checklist.md @@ -10,12 +10,14 @@ scripts: **CRITICAL CONCEPT**: Checklists are **UNIT TESTS FOR REQUIREMENTS WRITING** - they validate the quality, clarity, and completeness of requirements in a given domain. **NOT for verification/testing**: + - ❌ NOT "Verify the button clicks correctly" - ❌ NOT "Test error handling works" - ❌ NOT "Confirm the API returns 200" - ❌ NOT checking if code/implementation matches the spec **FOR requirements quality validation**: + - ✅ "Are visual hierarchy requirements defined for all card types?" (completeness) - ✅ "Is 'prominent display' quantified with specific sizing/positioning?" (clarity) - ✅ "Are hover state requirements consistent across all interactive elements?" (consistency) @@ -80,7 +82,7 @@ You **MUST** consider the user input before proceeding (if not empty). - spec.md: Feature requirements and scope - plan.md (if exists): Technical details, dependencies - tasks.md (if exists): Implementation tasks - + **Context Loading Strategy**: - Load only necessary portions relevant to active focus areas (avoid full-file dumping) - Prefer summarizing long sections into concise scenario/requirement bullets @@ -91,7 +93,7 @@ You **MUST** consider the user input before proceeding (if not empty). - Create `FEATURE_DIR/checklists/` directory if it doesn't exist - Generate unique checklist filename: - Use short, descriptive name based on domain (e.g., `ux.md`, `api.md`, `security.md`) - - Format: `[domain].md` + - Format: `[domain].md` - If file exists, append to existing file - Number items sequentially starting from CHK001 - Each `/speckit.checklist` run creates a NEW file (never overwrites existing checklists) @@ -103,7 +105,7 @@ You **MUST** consider the user input before proceeding (if not empty). - **Consistency**: Do requirements align with each other? - **Measurability**: Can requirements be objectively verified? - **Coverage**: Are all scenarios/edge cases addressed? - + **Category Structure** - Group items by requirement quality dimensions: - **Requirement Completeness** (Are all necessary requirements documented?) - **Requirement Clarity** (Are requirements specific and unambiguous?) @@ -114,14 +116,14 @@ You **MUST** consider the user input before proceeding (if not empty). - **Non-Functional Requirements** (Performance, Security, Accessibility, etc. - are they specified?) - **Dependencies & Assumptions** (Are they documented and validated?) - **Ambiguities & Conflicts** (What needs clarification?) - + **HOW TO WRITE CHECKLIST ITEMS - "Unit Tests for English"**: - + ❌ **WRONG** (Testing implementation): - "Verify landing page displays 3 episode cards" - "Test hover states work on desktop" - "Confirm logo click navigates home" - + ✅ **CORRECT** (Testing requirements quality): - "Are the exact number and layout of featured episodes specified?" [Completeness] - "Is 'prominent display' quantified with specific sizing/positioning?" [Clarity] @@ -130,7 +132,7 @@ You **MUST** consider the user input before proceeding (if not empty). - "Is the fallback behavior specified when logo image fails to load?" [Edge Cases] - "Are loading states defined for asynchronous episode data?" [Completeness] - "Does the spec define visual hierarchy for competing UI elements?" [Clarity] - + **ITEM STRUCTURE**: Each item should follow this pattern: - Question format asking about requirement quality @@ -138,28 +140,28 @@ You **MUST** consider the user input before proceeding (if not empty). - Include quality dimension in brackets [Completeness/Clarity/Consistency/etc.] - Reference spec section `[Spec §X.Y]` when checking existing requirements - Use `[Gap]` marker when checking for missing requirements - + **EXAMPLES BY QUALITY DIMENSION**: - + Completeness: - "Are error handling requirements defined for all API failure modes? [Gap]" - "Are accessibility requirements specified for all interactive elements? [Completeness]" - "Are mobile breakpoint requirements defined for responsive layouts? [Gap]" - + Clarity: - "Is 'fast loading' quantified with specific timing thresholds? [Clarity, Spec §NFR-2]" - "Are 'related episodes' selection criteria explicitly defined? [Clarity, Spec §FR-5]" - "Is 'prominent' defined with measurable visual properties? [Ambiguity, Spec §FR-4]" - + Consistency: - "Do navigation requirements align across all pages? [Consistency, Spec §FR-10]" - "Are card component requirements consistent between landing and detail pages? [Consistency]" - + Coverage: - "Are requirements defined for zero-state scenarios (no episodes)? [Coverage, Edge Case]" - "Are concurrent user interaction scenarios addressed? [Coverage, Gap]" - "Are requirements specified for partial data loading failures? [Coverage, Exception Flow]" - + Measurability: - "Are visual hierarchy requirements measurable/testable? [Acceptance Criteria, Spec §FR-1]" - "Can 'balanced visual weight' be objectively verified? [Measurability, Spec §FR-2]" @@ -195,7 +197,7 @@ You **MUST** consider the user input before proceeding (if not empty). - ❌ "Click", "navigate", "render", "load", "execute" - ❌ Test cases, test plans, QA procedures - ❌ Implementation details (frameworks, APIs, algorithms) - + **✅ REQUIRED PATTERNS** - These test requirements quality: - ✅ "Are [requirement type] defined/specified/documented for [scenario]?" - ✅ "Is [vague term] quantified/clarified with specific criteria?" @@ -225,6 +227,7 @@ To avoid clutter, use descriptive types and clean up obsolete checklists when do **UX Requirements Quality:** `ux.md` Sample items (testing the requirements, NOT the implementation): + - "Are visual hierarchy requirements defined with measurable criteria? [Clarity, Spec §FR-1]" - "Is the number and positioning of UI elements explicitly specified? [Completeness, Spec §FR-1]" - "Are interaction state requirements (hover, focus, active) consistently defined? [Consistency]" @@ -235,6 +238,7 @@ Sample items (testing the requirements, NOT the implementation): **API Requirements Quality:** `api.md` Sample items: + - "Are error response formats specified for all failure scenarios? [Completeness]" - "Are rate limiting requirements quantified with specific thresholds? [Clarity]" - "Are authentication requirements consistent across all endpoints? [Consistency]" @@ -244,6 +248,7 @@ Sample items: **Performance Requirements Quality:** `performance.md` Sample items: + - "Are performance requirements quantified with specific metrics? [Clarity]" - "Are performance targets defined for all critical user journeys? [Coverage]" - "Are performance requirements under different load conditions specified? [Completeness]" @@ -253,6 +258,7 @@ Sample items: **Security Requirements Quality:** `security.md` Sample items: + - "Are authentication requirements specified for all protected resources? [Coverage]" - "Are data protection requirements defined for sensitive information? [Completeness]" - "Is the threat model documented and requirements aligned to it? [Traceability]" @@ -282,10 +288,10 @@ Sample items: ``` **Key Differences:** + - Wrong: Tests if the system works correctly - Correct: Tests if the requirements are written correctly - Wrong: Verification of behavior - Correct: Validation of requirement quality -- Wrong: "Does it do X?" +- Wrong: "Does it do X?" - Correct: "Is X clearly specified?" - diff --git a/templates/commands/clarify.md b/templates/commands/clarify.md index b91d0f90b..d43a79486 100644 --- a/templates/commands/clarify.md +++ b/templates/commands/clarify.md @@ -91,8 +91,8 @@ Execution steps: 3. Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Do NOT output them all at once. Apply these constraints: - Maximum of 10 total questions across the whole session. - Each question must be answerable with EITHER: - * A short multiple‑choice selection (2–5 distinct, mutually exclusive options), OR - * A one-word / short‑phrase answer (explicitly constrain: "Answer in <=5 words"). + - A short multiple‑choice selection (2–5 distinct, mutually exclusive options), OR + - A one-word / short‑phrase answer (explicitly constrain: "Answer in <=5 words"). - Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance validation. - Ensure category coverage balance: attempt to cover the highest impact unresolved categories first; avoid asking two low-impact questions when a single high-impact area (e.g., security posture) is unresolved. - Exclude questions already answered, trivial stylistic preferences, or plan-level execution details (unless blocking correctness). @@ -102,14 +102,14 @@ Execution steps: 4. Sequential questioning loop (interactive): - Present EXACTLY ONE question at a time. - For multiple‑choice questions: - * **Analyze all options** and determine the **most suitable option** based on: + - **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] - ` - * Then render all options as a Markdown table: + - 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] - ` + - Then render all options as a Markdown table: | Option | Description | |--------|-------------| @@ -118,36 +118,36 @@ Execution steps: | C |