sddx-workflow 0.9.0 → 0.10.0

package/templates/windsurf-rules/sddx-workflow.md

@@ -4,23 +4,52 @@ trigger: always_on
 
 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` — all 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
 
 ## Available commands
 
+### Project setup
+| Command | Purpose |
+|---|---|
+| `/bootstrap` | Populate project context — interview or `--scan` |
+| `/scan` | Discovery-only pass over an existing codebase |
+| `/conventions-sync` | Refresh conventions, 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 |
 | `/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 |
 | `/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 blocking ambiguity |
+| `/spec-amend` | Documented Change Request |
+| `/spec-analyze` | Cross-consistency analysis |
+| `/verify` | Strict mechanical audit |
+| `/review` | Lighter human-touch final pass |
 | `/finish` | Stage files and generate commit message |
 
+### Multi-spec
+| Command | Purpose |
+|---|---|
+| `/spec-status` | Show all active specs and phase |
+| `/spec-conflicts` | Detect file 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`.
+
 Full definitions for each command are in `.sdd/workflow.md`.

package/templates/windsurf-workflows/ask.md

@@ -0,0 +1,9 @@
+---
+description: Research and exploration — no code changes
+---
+
+Execute the /ask command defined in .sdd/workflow.md.
+
+The topic is whatever you typed after the command (e.g. `/ask how does auth refresh work`).
+
+Research and exploration only — do not modify any files. Read, analyze, and summarize findings with explicit options or recommendations.

package/templates/windsurf-workflows/assume.md

@@ -0,0 +1,11 @@
+---
+description: Surface all assumptions before acting — stop for confirmation
+---
+
+Execute the /assume command defined in .sdd/workflow.md.
+
+The context is whatever you typed after the command.
+
+List every assumption being made about the task, codebase state, and technical decisions.
+For each: what you're assuming, why, and what changes if it's wrong.
+Stop and wait for confirmation before proceeding.

package/templates/windsurf-workflows/bootstrap.md

@@ -0,0 +1,10 @@
+---
+description: Populate project context via interview or codebase scan
+---
+
+Execute the /bootstrap command defined in .sdd/workflow.md.
+
+If the project already has code, scan the codebase first (read structure, package files, schema, routes), infer what you can, then ask only about what the code cannot answer.
+If it's a new project, ask the 6 interview questions defined in workflow.md one at a time.
+
+Present the full draft of .sdd/project-overview.md and .sdd/conventions.md for approval before writing any file.

package/templates/windsurf-workflows/bugfix.md

@@ -0,0 +1,11 @@
+---
+description: Reproduce → diagnose → fix → validate
+---
+
+Execute the /bugfix command defined in .sdd/workflow.md.
+
+The bug or error is whatever you described after the command.
+
+Follow the stages in order without skipping: Reproduce → Diagnose → Fix → Validate.
+Stop after Reproduce if the bug cannot be confirmed with a test or repro case.
+Escalate to /spec-new if the fix scope exceeds ~1 file or ~50 lines.

package/templates/windsurf-workflows/conventions-sync.md

@@ -0,0 +1,7 @@
+---
+description: Refresh .sdd/conventions.md from current project state — preserves manual sections
+---
+
+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/windsurf-workflows/finish.md

@@ -0,0 +1,9 @@
+---
+description: Stage files and generate a conventional commit message
+---
+
+Execute the /finish command defined in .sdd/workflow.md.
+
+Run git status and git diff. Stage all relevant files (exclude .env*, build artifacts, scratch files). Determine the commit type. Draft a conventional commit message following the format in workflow.md — one overview sentence, detailed bullets with reasoning, optional footer for non-obvious context.
+
+Stop and present the staged file list and commit message for approval before committing.

package/templates/windsurf-workflows/impl-gap.md

@@ -0,0 +1,9 @@
+---
+description: Stop and report when a task is blocked by ambiguity or impossibility
+---
+
+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/windsurf-workflows/refactor.md

@@ -0,0 +1,9 @@
+---
+description: Restructure without changing external behavior
+---
+
+Execute the /refactor command defined in .sdd/workflow.md.
+
+The target is whatever you named after the command.
+
+Run existing tests first to establish a green baseline. Implement in small steps — tests must stay green throughout. No new features or bug fixes mixed in.

package/templates/windsurf-workflows/research.md

@@ -0,0 +1,9 @@
+---
+description: Targeted exploration with non-binding artifact — separates exploration from commitment
+---
+
+Execute the /research command defined in .sdd/workflow.md.
+
+Usage: `/research <feature> <topic>` (e.g. `/research auth-refresh jwt-libraries`).
+
+Investigate options for the topic. Read specs/<feature>/1-requirements.md and write a research artifact in that spec's folder with options, pros/cons, current versions/maintenance status, and a non-binding recommendation. Do NOT modify 2-plan.md.

package/templates/windsurf-workflows/review.md

@@ -0,0 +1,9 @@
+---
+description: Lighter human-touch final pass — runs after /verify
+---
+
+Execute the /review command defined in .sdd/workflow.md.
+
+The spec name is whatever you typed after the command (e.g. `/review auth-refresh`).
+
+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.

package/templates/windsurf-workflows/scan.md

@@ -0,0 +1,7 @@
+---
+description: Discovery-only pass over an existing codebase — writes scan-report.md
+---
+
+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/windsurf-workflows/spec-amend.md

@@ -0,0 +1,9 @@
+---
+description: Documented Change Request for post-approval spec changes
+---
+
+Execute the /spec-amend command defined in .sdd/workflow.md.
+
+Usage: `/spec-amend <feature> <change-summary>`.
+
+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 to 1-requirements.md or 2-plan.md.

package/templates/windsurf-workflows/spec-analyze.md

@@ -0,0 +1,9 @@
+---
+description: Cross-consistency analysis (goal-task coverage, plan-task coverage, scope creep)
+---
+
+Execute the /spec-analyze command defined in .sdd/workflow.md.
+
+The spec name is whatever you typed after the command (e.g. `/spec-analyze auth-refresh`).
+
+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/<spec>/analysis.md.

package/templates/windsurf-workflows/spec-clarify.md

@@ -0,0 +1,9 @@
+---
+description: Pre-plan clarification — generates blocking and non-blocking questions
+---
+
+Execute the /spec-clarify command defined in .sdd/workflow.md.
+
+The spec name is whatever you typed after the command (e.g. `/spec-clarify auth-refresh`).
+
+Generate categorized clarification questions for specs/<spec>/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/windsurf-workflows/spec-conflicts.md

@@ -0,0 +1,7 @@
+---
+description: Detect file-level conflicts between active specs — detection only
+---
+
+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/windsurf-workflows/spec-new.md

@@ -0,0 +1,10 @@
+---
+description: Scaffold a spec folder for a new feature
+---
+
+Execute the /spec-new command defined in .sdd/workflow.md.
+
+The feature name is whatever you typed after the command (e.g. `/spec-new auth-refresh`).
+
+Create a specs/<feature>/ folder by copying the three template files from specs/_template/.
+Replace <Feature Name> in each file title with the actual feature name.

package/templates/windsurf-workflows/spec-plan.md

@@ -0,0 +1,10 @@
+---
+description: Generate technical plan — stops for approval before any code
+---
+
+Execute the /spec-plan command defined in .sdd/workflow.md.
+
+The spec name is whatever you typed after the command (e.g. `/spec-plan auth-refresh`).
+
+Read specs/<spec>/1-requirements.md, run /assume to surface assumptions, then draft the technical plan in specs/<spec>/2-plan.md.
+Stop for explicit approval before writing any implementation code.

package/templates/windsurf-workflows/spec-status.md

@@ -0,0 +1,7 @@
+---
+description: Show state of all active specs — phase, progress, outstanding CRs and gaps
+---
+
+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/windsurf-workflows/spec-tasks.md

@@ -0,0 +1,11 @@
+---
+description: Execute approved plan one task at a time, TDD-first
+---
+
+Execute the /spec-tasks command defined in .sdd/workflow.md.
+
+The spec name is whatever you typed after the command (e.g. `/spec-tasks auth-refresh`).
+
+Then read the approved specs/<spec>/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/windsurf-workflows/verify.md

@@ -0,0 +1,9 @@
+---
+description: Strict mechanical audit — read-only; writes verify-report.md
+---
+
+Execute the /verify command defined in .sdd/workflow.md.
+
+The spec name is whatever you typed after the command (e.g. `/verify auth-refresh`).
+
+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/<spec>/verify-report.md. Do not modify code or specs.