sddx-workflow 0.9.0 → 0.10.0

package/templates/AGENTS.md

@@ -2,7 +2,7 @@
 
 This project uses the SDD Protocol. Read these files before starting any task:
 
-1. **[.sdd/workflow.md](.sdd/workflow.md)** — commands, ceremony levels, and stop points
+1. **[.sdd/workflow.md](.sdd/workflow.md)** — commands, permissions, stop points, anti-patterns
 2. **[.sdd/project-overview.md](.sdd/project-overview.md)** — what this app is, its non-goals, domains, and definition of done
 3. **[.sdd/conventions.md](.sdd/conventions.md)** — project-specific conventions and patterns
 
@@ -10,15 +10,48 @@ This project uses the SDD Protocol. Read these files before starting any task:
 
 Type `/skills` or `$skill-name` to invoke. Skills are defined in `.agents/skills/`.
 
+### Project setup
 | Intent | Skill |
 |---|---|
-| Initialize project context | `$bootstrap` (new) · `$bootstrap --scan` (existing) |
-| Explore / research | `$ask` |
+| Initialize project context (new) | `$bootstrap` |
+| Initialize project context (existing codebase) | `$bootstrap --scan` |
+| Discovery-only scan of an existing codebase | `$scan` |
+| Refresh conventions from current project state | `$conventions-sync` |
+
+### Exploration
+| Intent | Skill |
+|---|---|
+| Research / ask without changing anything | `$ask` |
+| Non-binding research artifact for a topic | `$research` |
 | Surface and validate assumptions | `$assume` |
+
+### Feature flow
+| Intent | Skill |
+|---|---|
+| Scaffold a spec folder | `$spec-new` |
+| Clarify a draft before planning | `$spec-clarify` |
+| Generate technical plan (stops for approval) | `$spec-plan` |
+| Execute approved plan one task at a time | `$spec-tasks` |
+| Stop and report an implementation gap | `$impl-gap` |
+| Document a Change Request for spec edits | `$spec-amend` |
+| Cross-consistency analysis (goals / plan / tasks) | `$spec-analyze` |
+| Strict mechanical audit | `$verify` |
+| Lighter human-touch final pass | `$review` |
+| Stage and commit | `$finish` |
+
+### Multi-spec
+| Intent | Skill |
+|---|---|
+| Show state of all active specs | `$spec-status` |
+| Detect file-level conflicts between specs | `$spec-conflicts` |
+
+### Other
+| Intent | Skill |
+|---|---|
 | Fix a confirmed bug | `$bugfix` → `$finish` |
 | Restructure without behavior change | `$refactor` → `$finish` |
-| New feature | `$spec-new` → `$spec-plan` → `$spec-tasks` → `$review` → `$finish` |
-| Stage + commit after any work | `$finish` |
+
+Standard workflow: `$spec-new` → `$spec-clarify` → `$spec-plan` → `$spec-tasks` → `$verify` → `$review` → `$finish`.
 
 ## Active Specs
 

package/templates/CLAUDE.md

@@ -2,21 +2,92 @@
 
 This project uses the SDD Protocol. Read these files before starting any task:
 
-1. **[.sdd/workflow.md](.sdd/workflow.md)** — commands, ceremony levels, and stop points
+1. **[.sdd/workflow.md](.sdd/workflow.md)** — commands, permissions, stop points, anti-patterns
 2. **[.sdd/project-overview.md](.sdd/project-overview.md)** — what this app is, its non-goals, domains, and definition of done
 3. **[.sdd/conventions.md](.sdd/conventions.md)** — project-specific conventions and patterns
 
 ## Quick Reference
 
+### Project setup
 | Intent | Command |
 |---|---|
-| Initialize project context | `/bootstrap` (new) · `/bootstrap --scan` (existing) |
-| Explore / research | `/ask` |
+| Initialize project context (new) | `/bootstrap` |
+| Initialize project context (existing codebase) | `/bootstrap --scan` |
+| Discovery-only scan, no `.sdd/` writes | `/scan` |
+| Refresh conventions from current project state | `/conventions-sync` |
+
+### Exploration
+| Intent | Command |
+|---|---|
+| Research / ask without changing anything | `/ask` |
+| Non-binding research artifact for a topic | `/research` |
 | Surface and validate assumptions | `/assume` |
+
+### Feature flow
+| Intent | Command |
+|---|---|
+| Scaffold a spec folder | `/spec-new` |
+| Clarify a draft before planning | `/spec-clarify` |
+| Generate technical plan (stops for approval) | `/spec-plan` |
+| Execute approved plan one task at a time | `/spec-tasks` |
+| Stop and report an implementation gap | `/impl-gap` |
+| Document a Change Request for spec edits | `/spec-amend` |
+| Cross-consistency analysis | `/spec-analyze` |
+| Strict mechanical audit | `/verify` |
+| Lighter human-touch final pass | `/review` |
+| Stage and commit | `/finish` |
+
+### Multi-spec awareness
+| Intent | Command |
+|---|---|
+| Show state of all active specs | `/spec-status` |
+| Detect file-level conflicts between specs | `/spec-conflicts` |
+
+### Other
+| Intent | Command |
+|---|---|
 | Fix a confirmed bug | `/bugfix` → `/finish` |
 | Restructure without behavior change | `/refactor` → `/finish` |
-| New feature | `/spec-new` → `/spec-plan` → `/spec-tasks` → `/review` → `/finish` |
-| Stage + commit after any work | `/finish` |
+
+Standard workflow: `/spec-new` → `/spec-clarify` → `/spec-plan` → `/spec-tasks` → `/verify` → `/review` → `/finish`.
+
+## Per-Phase Permissions
+
+See `.sdd/workflow.md` §Per-Phase Permissions for the full table. Quick summary:
+
+| Command | Edit specs | Edit code |
+|---|---|---|
+| `/spec-plan` | ✓ (`2-plan.md` only) | ✗ |
+| `/spec-tasks` | ✓ (`3-tasks.md` checklist only) | ✓ |
+| `/impl-gap` | ✓ (`impl-gaps.md` only) | ✗ |
+| `/spec-amend` | ✓ (with CR approval) | ✗ |
+| `/verify`, `/review` | ✗ | ✗ |
+| `/bugfix`, `/refactor` | ✗ | ✓ |
+
+## Files to Read Per Command
+
+What context to load before running each command. Skip the rest — context budget is finite.
+
+| Command | Always read | Conditionally read |
+|---|---|---|
+| `/bootstrap`, `/scan` | `package.json`, env files, manifests | Existing `.sdd/project-overview.md` if updating |
+| `/spec-new` | `specs/_template/*` | — |
+| `/spec-clarify`, `/spec-plan`, `/spec-tasks` | `specs/<feature>/*.md`, `.sdd/conventions.md`, `.sdd/project-overview.md` | Relevant domain file `.sdd/domains/<x>.md` |
+| `/impl-gap` | `specs/<feature>/2-plan.md`, `specs/<feature>/3-tasks.md` | The current task code under work |
+| `/verify`, `/spec-analyze` | All `specs/<feature>/*.md`, files listed in "Components Affected" | Prior `verify-report.md` / `analysis.md` |
+| `/review` | `verify-report.md`, all changed files | `2-plan.md` tradeoffs section |
+| `/bugfix` | Test suite root, the failing path | `.sdd/conventions.md` |
+| `/refactor` | Target files, their tests, callers | — |
+| `/conventions-sync` | `.sdd/conventions.md`, `package.json`, lint/format configs | — |
+| `/finish` | `git status`, `git diff` | — |
+
+## Anti-Patterns
+
+See `.sdd/workflow.md` §Anti-Patterns for the full list. The three most critical:
+
+1. **Edit approved spec files silently.** Use `/spec-amend` or explicit user approval.
+2. **Improvise when the spec is ambiguous.** Use `/impl-gap` and stop.
+3. **Skip `/verify` before `/finish`.** Mechanical checks exist to catch real problems.
 
 ## Active Specs
 

package/templates/claude-commands/conventions-sync.md

@@ -0,0 +1,3 @@
+Execute the /conventions-sync command defined in .sdd/workflow.md.
+
+Refresh .sdd/conventions.md against current project state. Preserve sections marked `<!-- manual -->` verbatim; regenerate auto-sections from scanned packages, structure, lint/format configs, ORM/router in use. Present the diff for explicit approval before writing.

package/templates/claude-commands/impl-gap.md

@@ -0,0 +1,10 @@
+Execute the /impl-gap command defined in .sdd/workflow.md.
+
+Usage: /impl-gap <feature>
+
+A task is blocked by ambiguity, contradiction, or technical impossibility. STOP execution. Create specs/<feature>/impl-gaps.md from the template if missing, then append a GAP entry with the current task, problem, impact, proposed resolution, action required, and resolution placeholder. Do not improvise — wait for human direction.
+
+If the gap requires changing the spec:
+- Escalate to /spec-amend. A formal CR is required before any approved spec edit.
+
+Feature: $ARGUMENTS

package/templates/claude-commands/research.md

@@ -0,0 +1,7 @@
+Execute the /research command defined in .sdd/workflow.md.
+
+Usage: /research <feature> <topic>
+
+Targeted exploration that produces a non-binding research artifact. Read specs/<feature>/1-requirements.md, investigate options (frameworks, libraries, patterns), and write specs/<feature>/research-<topic>.md with options, pros/cons, current state, and a non-binding recommendation. Do NOT modify 2-plan.md.
+
+Feature and topic: $ARGUMENTS

package/templates/claude-commands/review.md

@@ -1,5 +1,5 @@
 Execute the /review command defined in .sdd/workflow.md.
 
-Audit the spec before closing. Verify all goals (G1, G2…) are satisfied, every acceptance scenario has a passing test, no out-of-scope changes were introduced, and the implementation is the simplest that meets requirements.
+Lighter human-touch final pass — runs AFTER /verify has reported green. Read the implementation qualitatively: clarity, naming, simplicity, leaky abstractions, copy-paste smell, comments that lie. Note minor follow-ups; don't enforce mechanical checks (that's /verify's job). If a structural issue is found, escalate to /spec-amend instead of editing.
 
 Spec: $ARGUMENTS

package/templates/claude-commands/scan.md

@@ -0,0 +1,5 @@
+Execute the /scan command defined in .sdd/workflow.md.
+
+Discovery-only pass over the codebase. Detect frameworks, dependencies, structure, naming patterns, lint/format configs. Write scan-report.md at repo root. Do NOT write any .sdd/ files — /bootstrap --scan is the command that does that.
+
+Scope [optional sub-path]: $ARGUMENTS

package/templates/claude-commands/spec-amend.md

@@ -0,0 +1,7 @@
+Execute the /spec-amend command defined in .sdd/workflow.md.
+
+Usage: /spec-amend <feature> <change-summary>
+
+A spec change after approval requires a Change Request. Create specs/<feature>/amendments.md from the template if missing, then append a CR entry with motive, requirement changes, plan changes, affected tasks, and status "Pending approval". Stop for explicit approval before propagating any change.
+
+Feature and change summary: $ARGUMENTS

package/templates/claude-commands/spec-analyze.md

@@ -0,0 +1,5 @@
+Execute the /spec-analyze command defined in .sdd/workflow.md.
+
+Cross-consistency analysis for a single spec. Check: goal-to-task coverage (every G-ID referenced by a task), plan-to-task coverage (every "Components Affected" entry referenced by a task), scope creep (tasks without goal IDs). Write specs/$ARGUMENTS/analysis.md. Do not modify any other file.
+
+Spec: $ARGUMENTS

package/templates/claude-commands/spec-clarify.md

@@ -0,0 +1,5 @@
+Execute the /spec-clarify command defined in .sdd/workflow.md.
+
+Generate categorized clarification questions for a draft 1-requirements.md — blocking vs. non-blocking. Present them to the user, then record questions and answers in a Clarifications section of specs/$ARGUMENTS/1-requirements.md. No other section is modified.
+
+Feature: $ARGUMENTS

package/templates/claude-commands/spec-conflicts.md

@@ -0,0 +1,3 @@
+Execute the /spec-conflicts command defined in .sdd/workflow.md.
+
+Cross-reference "Components Affected" across all active specs. Any file listed by two or more specs is a potential conflict — report file, the specs touching it, and a sequencing recommendation. Detection only; do not modify any spec.

package/templates/claude-commands/spec-status.md

@@ -0,0 +1,3 @@
+Execute the /spec-status command defined in .sdd/workflow.md.
+
+Show the state of all active specs (folders under specs/ excluding _template and _done). For each: feature name, current phase inferred from file state, progress (N/M tasks), outstanding CRs or unresolved gaps. Do not modify any file.

package/templates/claude-commands/spec-tasks.md

@@ -1,5 +1,5 @@
 Execute the /spec-tasks command defined in .sdd/workflow.md.
 
-Read the approved specs/$ARGUMENTS/2-plan.md and execute tasks one at a time.
-Write the test first (red), implement until green, run the full suite, then move to the next task.
-Stop if tests fail or if a task reveals new scope.
+Then read the approved specs/$ARGUMENTS/2-plan.md and execute tasks one at a time. Write the test first (red), implement until green, run the full suite, then move to the next task.
+
+If a task is blocked by ambiguity, contradiction, or technical impossibility, STOP and run /impl-gap — never improvise. If the gap requires changing the spec, escalate to /spec-amend.

package/templates/claude-commands/verify.md

@@ -0,0 +1,5 @@
+Execute the /verify command defined in .sdd/workflow.md.
+
+Strict mechanical audit — read-only. Check: all tasks marked complete, every goal has an artifact, every acceptance scenario has a passing test, full test suite green, no out-of-scope file changes, no unresolved /impl-gap entries, no pending CRs. Write specs/$ARGUMENTS/verify-report.md. Do not modify code or specs.
+
+Spec: $ARGUMENTS

package/templates/codex-skills/conventions-sync/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: conventions-sync
+description: Refresh .sdd/conventions.md from current project state. Preserves sections marked `<!-- manual -->`. Shows diff for approval before writing. Use when the project's stack or patterns drift from documented conventions.
+---
+
+Execute the /conventions-sync command defined in .sdd/workflow.md.
+
+Scan packages, structure, lint/format configs, ORM/router. Preserve manual sections verbatim; regenerate auto-sections. Present diff and STOP for approval before writing.

package/templates/codex-skills/impl-gap/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: impl-gap
+description: Formal stop-and-report channel when /spec-tasks hits an ambiguity, contradiction, or technical impossibility. Append a GAP entry to specs/<feature>/impl-gaps.md and wait for direction. Never improvise a fix.
+---
+
+Execute the /impl-gap command defined in .sdd/workflow.md.
+
+Usage: /impl-gap <feature>
+
+STOP execution. Create specs/<feature>/impl-gaps.md from the template if missing, then append a GAP entry with current task, problem, impact, proposed resolution, action required, and resolution placeholder. Wait for human direction. If the gap requires changing the spec, escalate to /spec-amend.

package/templates/codex-skills/research/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: research
+description: Targeted exploration that produces a non-binding research artifact. Use before /spec-plan when comparing frameworks, libraries, patterns, or architectures — separates exploration from commitment.
+---
+
+Execute the /research command defined in .sdd/workflow.md.
+
+Usage: /research <feature> <topic>
+
+Investigate options for the topic. Read specs/<feature>/1-requirements.md and write specs/<feature>/research-<topic>.md with options, pros/cons, current versions/maintenance status, and a non-binding recommendation. Do NOT modify 2-plan.md.

package/templates/codex-skills/review/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: review
-description: Final audit before closing a spec or merging. Use after all spec tasks are complete to verify goals are met, tests pass, and no scope creep was introduced.
+description: Lighter human-touch final pass after /verify reports green. Qualitative reading — clarity, naming, simplicity, leaky abstractions, comments that lie. Notes minor follow-ups; mechanical checks live in /verify.
 ---
 
 Execute the /review command defined in .sdd/workflow.md.
 
-Audit the spec before closing. Verify all goals (G1, G2…) are satisfied, every acceptance scenario has a passing test, no out-of-scope changes were introduced, and the implementation is the simplest that meets requirements.
+Read the implementation qualitatively. Surface unclear naming, leaky abstractions, copy-paste smell, and comments that lie. Note minor follow-ups; do not enforce mechanical checks (that is /verify's job). If a structural issue is found, escalate to /spec-amend.

package/templates/codex-skills/scan/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: scan
+description: Discovery-only pass over an existing codebase. Detects frameworks, dependencies, structure, naming patterns. Writes scan-report.md at repo root. Does NOT write .sdd/ files — use /bootstrap --scan for that.
+---
+
+Execute the /scan command defined in .sdd/workflow.md.
+
+Read package manifests, directory structure, lint/format configs, and observable conventions. Produce scan-report.md at repo root with findings. Do not modify any .sdd/ file.

package/templates/codex-skills/spec-amend/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: spec-amend
+description: Documented change-request mechanism for post-approval changes to a spec. Append a CR entry to specs/<feature>/amendments.md and stop for human approval before propagating any change. Use when an /impl-gap escalates or the user requests a spec change.
+---
+
+Execute the /spec-amend command defined in .sdd/workflow.md.
+
+Usage: /spec-amend <feature> <change-summary>
+
+A spec change after approval requires a Change Request. Create specs/<feature>/amendments.md from the template if missing, then append a CR entry with motive, requirement changes, plan changes, affected tasks, and status "Pending approval". Stop for explicit approval before propagating any change.

package/templates/codex-skills/spec-analyze/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: spec-analyze
+description: Cross-consistency analysis between requirements, plan, and tasks for a single spec. Checks goal-to-task coverage, plan-to-task coverage, scope creep. Writes analysis.md. Use before /verify when you suspect drift.
+---
+
+Execute the /spec-analyze command defined in .sdd/workflow.md.
+
+Check: every G-ID referenced by at least one task; every "Components Affected" entry referenced by at least one task; any task lacking a goal reference (scope creep). Write specs/<feature>/analysis.md.

package/templates/codex-skills/spec-clarify/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: spec-clarify
+description: Structured pre-plan clarification of a draft 1-requirements.md. Generates blocking and non-blocking questions, records answers in a Clarifications section. Use before /spec-plan when ambiguities remain.
+---
+
+Execute the /spec-clarify command defined in .sdd/workflow.md.
+
+Generate categorized clarification questions (blocking / non-blocking) for the draft requirements. Wait for answers. Append questions and answers to a Clarifications section of specs/<feature>/1-requirements.md. No other section is modified.

package/templates/codex-skills/spec-conflicts/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: spec-conflicts
+description: Detect file-level conflicts between active specs by cross-referencing "Components Affected". Detection only — sequencing is a human decision.
+---
+
+Execute the /spec-conflicts command defined in .sdd/workflow.md.
+
+For each pair of active specs, report files that appear in both "Components Affected" sections. Suggest sequencing without making the decision.

package/templates/codex-skills/spec-status/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: spec-status
+description: Show state of all active specs (folders under specs/ excluding _template and _done). Reports phase, progress, outstanding CRs and gaps per spec. Read-only.
+---
+
+Execute the /spec-status command defined in .sdd/workflow.md.
+
+List each active spec with its phase, progress, and any outstanding CRs or unresolved gaps. Do not modify any file.

package/templates/codex-skills/spec-tasks/SKILL.md

@@ -5,6 +5,6 @@ description: Execute an approved technical plan as atomic tasks, one at a time.
 
 Execute the /spec-tasks command defined in .sdd/workflow.md.
 
-Read the approved specs/<name>/2-plan.md and execute tasks one at a time.
-Write the test first (red), implement until green, run the full suite, then move to the next task.
-Stop if tests fail or if a task reveals new scope.
+Then read the approved specs/<feature>/2-plan.md and execute tasks one at a time. Write the test first (red), implement until green, run the full suite, then move to the next task.
+
+If a task is blocked by ambiguity, contradiction, or technical impossibility, STOP and run /impl-gap — never improvise. If the gap requires changing the spec, escalate to /spec-amend.

package/templates/codex-skills/verify/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: verify
+description: Strict mechanical audit before /review. Read-only. Checks task completion, goal coverage, test suite, scope creep, pending CRs and gaps. Writes verify-report.md. Use after /spec-tasks finishes.
+---
+
+Execute the /verify command defined in .sdd/workflow.md.
+
+Read-only mechanical audit. Check: all tasks marked complete, every goal has an artifact, every acceptance scenario has a passing test, full test suite green, no out-of-scope file changes, no unresolved /impl-gap entries, no pending CRs. Write specs/<feature>/verify-report.md. Do not modify code or specs.

package/templates/conventions/base.md

@@ -5,28 +5,35 @@
 
 ## Tech Stack
 
+<!-- auto -->
 <!-- Primary technologies, frameworks, libraries, and their versions -->
 
 ## File & Folder Structure
 
+<!-- auto -->
 <!-- How the project is organized. Point out anything non-obvious. -->
 
 ## Naming Conventions
 
+<!-- auto -->
 <!-- Files, functions, variables, types — rules and examples -->
 
 ## Code Style
 
+<!-- auto -->
 <!-- Patterns to follow, abstractions in use, preferred approaches -->
 
 ## Patterns to Avoid
 
+<!-- manual -->
 <!-- Anti-patterns, deprecated approaches, things that have caused bugs before -->
 
 ## Testing
 
+<!-- auto -->
 <!-- How tests are structured, what needs to be tested, coverage expectations -->
 
 ## Domain Glossary
 
+<!-- manual -->
 <!-- Key terms in this project and what they mean precisely -->

package/templates/copilot-instructions.md

@@ -2,7 +2,7 @@
 
 This project uses the SDD Protocol. Before starting any task, read:
 
-1. `.sdd/workflow.md` — all commands, ceremony levels, and stop points
+1. `.sdd/workflow.md` — commands, permissions, stop points, anti-patterns
 2. `.sdd/project-overview.md` — what this app is, its non-goals, and domains
 3. `.sdd/conventions.md` — project-specific conventions and patterns
 
@@ -10,24 +10,54 @@ This project uses the SDD Protocol. Before starting any task, read:
 
 Use these slash commands in Copilot Chat (type `/` to see them):
 
+### Project setup
+| Command | Purpose |
+|---|---|
+| `/bootstrap` | Populate project context — interview or `--scan` |
+| `/scan` | Discovery-only pass — writes `scan-report.md`, no `.sdd/` |
+| `/conventions-sync` | Refresh `.sdd/conventions.md`, preserving manual sections |
+
+### Exploration
 | Command | Purpose |
 |---|---|
-| `/bootstrap` | Populate project context — interview or codebase scan |
 | `/ask` | Research only — no code changes |
+| `/research` | Non-binding research artifact for a topic |
 | `/assume` | List assumptions and stop for confirmation |
-| `/bugfix` | Reproduce → diagnose → fix → validate |
-| `/refactor` | Restructure without behavior change |
+
+### Feature flow
+| Command | Purpose |
+|---|---|
 | `/spec-new` | Scaffold a spec folder |
+| `/spec-clarify` | Pre-plan clarification — blocking vs. non-blocking questions |
 | `/spec-plan` | Generate technical plan — stop for approval |
 | `/spec-tasks` | Execute plan one task at a time, TDD-first |
-| `/review` | Final audit before closing |
+| `/impl-gap` | Stop and report a blocking ambiguity |
+| `/spec-amend` | Documented Change Request for post-approval edits |
+| `/spec-analyze` | Cross-consistency analysis — writes `analysis.md` |
+| `/verify` | Strict mechanical audit — read-only |
+| `/review` | Lighter human-touch final pass |
 | `/finish` | Stage files and generate commit message |
 
+### Multi-spec
+| Command | Purpose |
+|---|---|
+| `/spec-status` | Show all active specs and their phase |
+| `/spec-conflicts` | Detect file-level conflicts between specs |
+
+### Other
+| Command | Purpose |
+|---|---|
+| `/bugfix` | Reproduce → diagnose → fix → validate |
+| `/refactor` | Restructure without behavior change |
+
+Standard workflow: `/spec-new` → `/spec-clarify` → `/spec-plan` → `/spec-tasks` → `/verify` → `/review` → `/finish`.
+
 ## Execution principles
 
 1. Surface assumptions before acting — never pick an interpretation silently; if a simpler approach exists, say so and push back
 2. Minimum code — only what was asked; no speculative flexibility, no error handling for impossible scenarios; ask "would a senior engineer say this is overcomplicated?"
 3. Surgical changes — touch only what the task requires; match existing style; remove only orphans *your* changes created, not pre-existing dead code; every changed line must trace to the request
 4. Verify before moving on — transform vague tasks into verifiable goals ("Fix bug" → "Write failing test, then make it pass"); define "done" before starting
+5. Use the right channel for changes — never edit approved spec files silently; `/spec-amend` for spec changes, `/impl-gap` for blocked tasks
 
 Full definitions for each command are in `.sdd/workflow.md`.

package/templates/copilot-prompts/conventions-sync.prompt.md

@@ -0,0 +1,8 @@
+---
+description: Refresh .sdd/conventions.md from current project state — preserves manual sections
+mode: agent
+---
+
+Execute the /conventions-sync command defined in .sdd/workflow.md.
+
+Scan packages, structure, lint/format configs, ORM/router. Preserve sections marked `<!-- manual -->` verbatim; regenerate auto-sections. Present diff and STOP for approval before writing.

package/templates/copilot-prompts/impl-gap.prompt.md

@@ -0,0 +1,10 @@
+---
+description: Stop and report when a task is blocked by ambiguity or impossibility
+mode: agent
+---
+
+Execute the /impl-gap command defined in .sdd/workflow.md.
+
+Usage: /impl-gap ${input:specName}
+
+STOP execution. Create specs/${input:specName}/impl-gaps.md from the template if missing, then append a GAP entry with current task, problem, impact, proposed resolution, action required, and resolution placeholder. Wait for human direction. If the gap requires changing the spec, escalate to /spec-amend.

package/templates/copilot-prompts/research.prompt.md

@@ -0,0 +1,10 @@
+---
+description: Targeted exploration with non-binding artifact — separates exploration from commitment
+mode: agent
+---
+
+Execute the /research command defined in .sdd/workflow.md.
+
+Usage: /research ${input:specName} ${input:topic}
+
+Investigate options for the topic. Read specs/${input:specName}/1-requirements.md and write specs/${input:specName}/research-${input:topic}.md with options, pros/cons, current versions/maintenance status, and a non-binding recommendation. Do NOT modify 2-plan.md.

package/templates/copilot-prompts/review.prompt.md

@@ -1,10 +1,10 @@
 ---
-description: Final audit before closing a spec
+description: Lighter human-touch final pass — runs after /verify
 mode: agent
 ---
 
 Execute the /review command defined in .sdd/workflow.md.
 
-Verify: all goals (G1, G2…) satisfied, every acceptance scenario has a passing test, full test suite passes, no out-of-scope changes, no speculative code, implementation is the simplest that meets requirements.
+Read the implementation qualitatively: clarity, naming, simplicity, leaky abstractions, copy-paste smell, comments that lie. Note minor follow-ups; don't enforce mechanical checks (that's /verify's job). If a structural issue is found, escalate to /spec-amend.
 
 Spec: ${input:specName}

package/templates/copilot-prompts/scan.prompt.md

@@ -0,0 +1,8 @@
+---
+description: Discovery-only pass over an existing codebase — writes scan-report.md
+mode: agent
+---
+
+Execute the /scan command defined in .sdd/workflow.md.
+
+Read package manifests, directory structure, lint/format configs, and observable conventions. Produce scan-report.md at repo root with findings. Do not modify any .sdd/ file.

package/templates/copilot-prompts/spec-amend.prompt.md

@@ -0,0 +1,10 @@
+---
+description: Documented Change Request for post-approval spec changes
+mode: agent
+---
+
+Execute the /spec-amend command defined in .sdd/workflow.md.
+
+Usage: /spec-amend ${input:specName} ${input:changeSummary}
+
+Create specs/${input:specName}/amendments.md from the template if missing, then append a CR entry with motive, requirement changes, plan changes, affected tasks, and status "Pending approval". Stop for explicit approval before propagating any change to 1-requirements.md or 2-plan.md.

package/templates/copilot-prompts/spec-analyze.prompt.md

@@ -0,0 +1,8 @@
+---
+description: Cross-consistency analysis (goal-task coverage, plan-task coverage, scope creep)
+mode: agent
+---
+
+Execute the /spec-analyze command defined in .sdd/workflow.md.
+
+Check: every G-ID referenced by at least one task; every "Components Affected" entry referenced by at least one task; any task lacking a goal reference (scope creep). Write specs/${input:specName}/analysis.md.

package/templates/copilot-prompts/spec-clarify.prompt.md

@@ -0,0 +1,8 @@
+---
+description: Pre-plan clarification — generates blocking and non-blocking questions
+mode: agent
+---
+
+Execute the /spec-clarify command defined in .sdd/workflow.md.
+
+Generate categorized clarification questions for specs/${input:specName}/1-requirements.md (blocking vs. non-blocking). Wait for answers. Append questions and answers to a Clarifications section of the requirements doc. No other section is modified.

package/templates/copilot-prompts/spec-conflicts.prompt.md

@@ -0,0 +1,8 @@
+---
+description: Detect file-level conflicts between active specs — detection only
+mode: agent
+---
+
+Execute the /spec-conflicts command defined in .sdd/workflow.md.
+
+Cross-reference "Components Affected" across all active specs. Report each file touched by two or more specs, naming the specs and suggesting sequencing. Do not modify any spec.

package/templates/copilot-prompts/spec-status.prompt.md

@@ -0,0 +1,8 @@
+---
+description: Show state of all active specs — phase, progress, outstanding CRs and gaps
+mode: agent
+---
+
+Execute the /spec-status command defined in .sdd/workflow.md.
+
+List directories under specs/ excluding _template and _done. For each: feature name, current phase, progress (N/M tasks), outstanding CRs or unresolved gaps. Do not modify any file.

package/templates/copilot-prompts/spec-tasks.prompt.md

@@ -5,6 +5,6 @@ mode: agent
 
 Execute the /spec-tasks command defined in .sdd/workflow.md.
 
-Read the approved specs/${input:specName}/2-plan.md and execute tasks one at a time.
-Write the test first (red), implement until green, run the full suite, then move to the next task.
-Stop immediately if tests fail or a task reveals new scope.
+Then read the approved specs/${input:specName}/2-plan.md and execute tasks one at a time. Write the test first (red), implement until green, run the full suite, then move to the next task.
+
+If a task is blocked by ambiguity, contradiction, or technical impossibility, STOP and run /impl-gap — never improvise. If the gap requires changing the spec, escalate to /spec-amend.

package/templates/copilot-prompts/verify.prompt.md

@@ -0,0 +1,8 @@
+---
+description: Strict mechanical audit — read-only; writes verify-report.md
+mode: agent
+---
+
+Execute the /verify command defined in .sdd/workflow.md.
+
+Read-only mechanical audit. Check: all tasks marked complete, every goal has an artifact, every acceptance scenario has a passing test, full test suite green, no out-of-scope file changes, no unresolved /impl-gap entries, no pending CRs. Write specs/${input:specName}/verify-report.md. Do not modify code or specs.