Skip to content

💫 Toolkit to help you get started with SDD or any other process!

Consistency updates to commands

den (work)8374777206c9
diff --git a/templates/commands/analyze.md b/templates/commands/analyze.md
index ef418dc0a..ab11284c2 100644
--- a/templates/commands/analyze.md
+++ b/templates/commands/analyze.md
@@ -5,100 +5,182 @@ scripts:
ps: scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks
---
-The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding with the prompt (if not empty).
-
-User input:
-
-`$ARGUMENTS
-`
-Goal: Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `/tasks` has successfully produced a complete `tasks.md`.
-
-STRICTLY READ-ONLY: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually).
-
-Constitution Authority: The project constitution (`/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/analyze`.
-
-Execution steps:
-
-1. Run `{SCRIPT}` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths:
- - SPEC = FEATURE_DIR/spec.md
- - PLAN = FEATURE_DIR/plan.md
- - TASKS = FEATURE_DIR/tasks.md
- Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command).
-
-2. Load artifacts:
- - Parse spec.md sections: Overview/Context, Functional Requirements, Non-Functional Requirements, User Stories, Edge Cases (if present).
- - Parse plan.md: Architecture/stack choices, Data Model references, Phases, Technical constraints.
- - Parse tasks.md: Task IDs, descriptions, phase grouping, parallel markers [P], referenced file paths.
- - Load constitution `/memory/constitution.md` for principle validation.
-
-3. Build internal semantic models:
- - Requirements inventory: Each functional + non-functional requirement with a stable key (derive slug based on imperative phrase; e.g., "User can upload file" -> `user-can-upload-file`).
- - User story/action inventory.
- - Task coverage mapping: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases).
- - Constitution rule set: Extract principle names and any MUST/SHOULD normative statements.
-
-4. Detection passes:
- A. Duplication detection:
- - Identify near-duplicate requirements. Mark lower-quality phrasing for consolidation.
- B. Ambiguity detection:
- - Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria.
- - Flag unresolved placeholders (TODO, TKTK, ???, <placeholder>, etc.).
- C. Underspecification:
- - Requirements with verbs but missing object or measurable outcome.
- - User stories missing acceptance criteria alignment.
- - Tasks referencing files or components not defined in spec/plan.
- D. Constitution alignment:
- - Any requirement or plan element conflicting with a MUST principle.
- - Missing mandated sections or quality gates from constitution.
- E. Coverage gaps:
- - Requirements with zero associated tasks.
- - Tasks with no mapped requirement/story.
- - Non-functional requirements not reflected in tasks (e.g., performance, security).
- F. Inconsistency:
- - Terminology drift (same concept named differently across files).
- - Data entities referenced in plan but absent in spec (or vice versa).
- - Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note).
- - Conflicting requirements (e.g., one requires to use Next.js while other says to use Vue as the framework).
-
-5. Severity assignment heuristic:
- - CRITICAL: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality.
- - HIGH: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion.
- - MEDIUM: Terminology drift, missing non-functional task coverage, underspecified edge case.
- - LOW: Style/wording improvements, minor redundancy not affecting execution order.
-
-6. Produce a Markdown report (no file writes) with sections:
-
- ### Specification Analysis Report
- | ID | Category | Severity | Location(s) | Summary | Recommendation |
- |----|----------|----------|-------------|---------|----------------|
- | A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version |
- (Add one row per finding; generate stable IDs prefixed by category initial.)
-
- Additional subsections:
- - Coverage Summary Table:
- | Requirement Key | Has Task? | Task IDs | Notes |
- - Constitution Alignment Issues (if any)
- - Unmapped Tasks (if any)
- - Metrics:
- * Total Requirements
- * Total Tasks
- * Coverage % (requirements with >=1 task)
- * Ambiguity Count
- * Duplication Count
- * Critical Issues Count
-
-7. At end of report, output a concise Next Actions block:
- - If CRITICAL issues exist: Recommend resolving before `/implement`.
- - If only LOW/MEDIUM: User may proceed, but provide improvement suggestions.
- - Provide explicit command suggestions: e.g., "Run /specify with refinement", "Run /plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'".
-
-8. Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.)
-
-Behavior rules:
-- NEVER modify files.
-- NEVER hallucinate missing sections—if absent, report them.
-- KEEP findings deterministic: if rerun without changes, produce consistent IDs and counts.
-- LIMIT total findings in the main table to 50; aggregate remainder in a summarized overflow note.
-- If zero issues found, emit a success report with coverage statistics and proceed recommendation.
-
-Context: {ARGS}
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Goal
+
+Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `/tasks` has successfully produced a complete `tasks.md`.
+
+## Operating Constraints
+
+**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually).
+
+**Constitution Authority**: The project constitution (`/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/analyze`.
+
+## Execution Steps
+
+### 1. Initialize Analysis Context
+
+Run `{SCRIPT}` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths:
+
+- SPEC = FEATURE_DIR/spec.md
+- PLAN = FEATURE_DIR/plan.md
+- TASKS = FEATURE_DIR/tasks.md
+
+Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command).
+
+### 2. Load Artifacts (Progressive Disclosure)
+
+Load only the minimal necessary context from each artifact:
+
+**From spec.md:**
+
+- Overview/Context
+- Functional Requirements
+- Non-Functional Requirements
+- User Stories
+- Edge Cases (if present)
+
+**From plan.md:**
+
+- Architecture/stack choices
+- Data Model references
+- Phases
+- Technical constraints
+
+**From tasks.md:**
+
+- Task IDs
+- Descriptions
+- Phase grouping
+- Parallel markers [P]
+- Referenced file paths
+
+**From constitution:**
+
+- Load `/memory/constitution.md` for principle validation
+
+### 3. Build Semantic Models
+
+Create internal representations (do not include raw artifacts in output):
+
+- **Requirements inventory**: Each functional + non-functional requirement with a stable key (derive slug based on imperative phrase; e.g., "User can upload file" → `user-can-upload-file`)
+- **User story/action inventory**: Discrete user actions with acceptance criteria
+- **Task coverage mapping**: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases)
+- **Constitution rule set**: Extract principle names and MUST/SHOULD normative statements
+
+### 4. Detection Passes (Token-Efficient Analysis)
+
+Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary.
+
+#### A. Duplication Detection
+
+- Identify near-duplicate requirements
+- Mark lower-quality phrasing for consolidation
+
+#### B. Ambiguity Detection
+
+- Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria
+- Flag unresolved placeholders (TODO, TKTK, ???, `<placeholder>`, etc.)
+
+#### C. Underspecification
+
+- Requirements with verbs but missing object or measurable outcome
+- User stories missing acceptance criteria alignment
+- Tasks referencing files or components not defined in spec/plan
+
+#### D. Constitution Alignment
+
+- Any requirement or plan element conflicting with a MUST principle
+- Missing mandated sections or quality gates from constitution
+
+#### E. Coverage Gaps
+
+- Requirements with zero associated tasks
+- Tasks with no mapped requirement/story
+- Non-functional requirements not reflected in tasks (e.g., performance, security)
+
+#### F. Inconsistency
+
+- Terminology drift (same concept named differently across files)
+- Data entities referenced in plan but absent in spec (or vice versa)
+- Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note)
+- Conflicting requirements (e.g., one requires Next.js while other specifies Vue)
+
+### 5. Severity Assignment
+
+Use this heuristic to prioritize findings:
+
+- **CRITICAL**: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality
+- **HIGH**: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion
+- **MEDIUM**: Terminology drift, missing non-functional task coverage, underspecified edge case
+- **LOW**: Style/wording improvements, minor redundancy not affecting execution order
+
+### 6. Produce Compact Analysis Report
+
+Output a Markdown report (no file writes) with the following structure:
+
+## Specification Analysis Report
+
+| ID | Category | Severity | Location(s) | Summary | Recommendation |
+|----|----------|----------|-------------|---------|----------------|
+| A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version |
+
+(Add one row per finding; generate stable IDs prefixed by category initial.)
+
+**Coverage Summary Table:**
+
+| Requirement Key | Has Task? | Task IDs | Notes |
+|-----------------|-----------|----------|-------|
+
+**Constitution Alignment Issues:** (if any)
+
+**Unmapped Tasks:** (if any)
+
+**Metrics:**
+
+- Total Requirements
+- Total Tasks
+- Coverage % (requirements with >=1 task)
+- Ambiguity Count
+- Duplication Count
+- Critical Issues Count
+
+### 7. Provide Next Actions
+
+At end of report, output a concise Next Actions block:
+
+- If CRITICAL issues exist: Recommend resolving before `/implement`
+- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions
+- Provide explicit command suggestions: e.g., "Run /specify with refinement", "Run /plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'"
+
+### 8. Offer Remediation
+
+Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.)
+
+## Operating Principles
+
+### Context Efficiency
+
+- **Minimal high-signal tokens**: Focus on actionable findings, not exhaustive documentation
+- **Progressive disclosure**: Load artifacts incrementally; don't dump all content into analysis
+- **Token-efficient output**: Limit findings table to 50 rows; summarize overflow
+- **Deterministic results**: Rerunning without changes should produce consistent IDs and counts
+
+### Analysis Guidelines
+
+- **NEVER modify files** (this is read-only analysis)
+- **NEVER hallucinate missing sections** (if absent, report them accurately)
+- **Prioritize constitution violations** (these are always CRITICAL)
+- **Use examples over exhaustive rules** (cite specific instances, not generic patterns)
+- **Report zero issues gracefully** (emit success report with coverage statistics)
+
+## Context
+
+{ARGS}
diff --git a/templates/commands/checklist.md b/templates/commands/checklist.md
index 7465527b3..b21737c07 100644
--- a/templates/commands/checklist.md
+++ b/templates/commands/checklist.md
@@ -5,12 +5,14 @@ scripts:
ps: scripts/powershell/check-prerequisites.ps1 -Json
---
-The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding with the prompt (if not empty).
+## User Input
-User input:
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
-`$ARGUMENTS
-`
## Execution Steps
1. **Setup**: Run `{SCRIPT}` from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS list.
diff --git a/templates/commands/clarify.md b/templates/commands/clarify.md
index c5821623e..eed35410b 100644
--- a/templates/commands/clarify.md
+++ b/templates/commands/clarify.md
@@ -5,11 +5,15 @@ scripts:
ps: scripts/powershell/check-prerequisites.ps1 -Json -PathsOnly
---
-The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding with the prompt (if not empty).
+## User Input
-User input:
+```text
+$ARGUMENTS
+```
-`$ARGUMENTS`
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
Goal: Detect and reduce ambiguity or missing decision points in the active feature specification and record the clarifications directly in the spec file.
diff --git a/templates/commands/constitution.md b/templates/commands/constitution.md
index c8b37912d..f6f8b2431 100644
--- a/templates/commands/constitution.md
+++ b/templates/commands/constitution.md
@@ -2,11 +2,15 @@
description: Create or update the project constitution from interactive or provided principle inputs, ensuring all dependent templates stay in sync.
---
-The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding with the prompt (if not empty).
+## User Input
-User input:
+```text
+$ARGUMENTS
+```
-`$ARGUMENTS`
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
You are updating the project constitution at `/memory/constitution.md`. This file is a TEMPLATE containing placeholder tokens in square brackets (e.g. `[PROJECT_NAME]`, `[PRINCIPLE_1_NAME]`). Your job is to (a) collect/derive concrete values, (b) fill the template precisely, and (c) propagate any amendments across dependent artifacts.
diff --git a/templates/commands/implement.md b/templates/commands/implement.md
index bc20db016..6478e9e79 100644
--- a/templates/commands/implement.md
+++ b/templates/commands/implement.md
@@ -5,11 +5,15 @@ scripts:
ps: scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks
---
-The user input can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding with the prompt (if not empty).
+## User Input
-User input:
+```text
+$ARGUMENTS
+```
-`$ARGUMENTS`
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
1. Run `{SCRIPT}` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute.
diff --git a/templates/commands/plan.md b/templates/commands/plan.md
index 37b4851fb..7348ada4f 100644
--- a/templates/commands/plan.md
+++ b/templates/commands/plan.md
@@ -8,13 +8,15 @@ agent_scripts:
ps: scripts/powershell/update-agent-context.ps1 -AgentType __AGENT__
---
-The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding with the prompt (if not empty).
+## User Input
-User input:
+```text
+$ARGUMENTS
+```
-`$ARGUMENTS`
+You **MUST** consider the user input before proceeding (if not empty).
-## Execution Steps
+## Outline
1. **Setup**: Run `{SCRIPT}` from repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH.
- Before proceeding: Check FEATURE_SPEC has `## Clarifications` section. If missing or ambiguous, instruct user to run `/clarify` first.
diff --git a/templates/commands/specify.md b/templates/commands/specify.md
index d9e1e2fef..357c00831 100644
--- a/templates/commands/specify.md
+++ b/templates/commands/specify.md
@@ -5,11 +5,15 @@ scripts:
ps: scripts/powershell/create-new-feature.ps1 -Json "{ARGS}"
---
-The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding with the prompt (if not empty).
+## User Input
-User input:
+```text
+$ARGUMENTS
+```
-`$ARGUMENTS`
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
The text the user typed after `/specify` in the triggering message **is** the feature description. Assume you always have it available in this conversation even if `{ARGS}` appears literally below. Do not ask the user to repeat it unless they provided an empty command.
diff --git a/templates/commands/tasks.md b/templates/commands/tasks.md
index ad05d3c9a..d6beea739 100644
--- a/templates/commands/tasks.md
+++ b/templates/commands/tasks.md
@@ -5,13 +5,15 @@ scripts:
ps: scripts/powershell/check-prerequisites.ps1 -Json
---
-The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding with the prompt (if not empty).
+## User Input
-User input:
+```text
+$ARGUMENTS
+```
-`$ARGUMENTS`
+You **MUST** consider the user input before proceeding (if not empty).
-## Execution Steps
+## Outline
1. **Setup**: Run `{SCRIPT}` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute.