Workflow — SDD

/sdd-feature

✋ 3 approvals

→

commit · /clear

fresh context

→

/sdd-implement

✋ approve plan

→

/sdd-validate

same session is fine

Cheat sheet

Type	When	What happens
/sdd-feature csv-export Let users export reports	You want a new feature or a multi-file change	Requirements → design → tasks, each approved by you. Writes `specs/csv-export/`.
commit the spec · /clear	All three spec files are approved	Agents work from committed files, and a fresh context keeps the build focused on the spec.
/sdd-implement csv-export	The spec is committed	Plan → your approval → one agent per task, then a check, a commit and a tick for each.
/sdd-validate csv-export	Every task is ticked	An independent reviewer gives a pass/fail verdict per acceptance criterion, then the docs and STATE.md are updated.
/sdd-implement a and b	Several specs are ready and don't share files	Each feature is built in its own worktree, at the same time.
/sdd-implement csv-export	A session ended mid-feature	It resumes at the first unticked task.

Step by step

W·01

Spec the feature

Requirements · Design (with stack-gap check) · Tasks with checks · no code

you approve each phase design stops at every stack gap research runs in Explore agents

Requirements. Claude interviews you one question at a time, including edge cases you may not have considered. Writes user stories, numbered acceptance criteria (AC-1, AC-2…) and an Out of scope list. You approve.

Design. Explore agents look at the relevant code and send back summaries. The design is checked against tech.md, and stops at every stack gap until you choose an option. Ends with a plan for verifying each acceptance criterion. You approve.

Tasks. Small tasks, each with the files it touches, a check command, and the acceptance criteria it covers. Groups are marked PARALLEL or SEQUENTIAL. You approve.

→

Commit the spec, then run /clear. The skill offers to make the commit.

Invoke: name first, description optional

/sdd-feature csv-export let users export any report as CSV

specs/csv-export/tasks.md

## Group 1: PARALLEL
- [ ] T1: Add CSV serializer
  - Files: src/export/csv.ts, test/csv.test.ts
  - Do: toCsv(rows, columns) per design.md
  - Check: `npm test -- csv.test.ts`
  - Covers: AC-1, AC-2
- [ ] T2: Add Export button
  - Files: src/ui/ReportToolbar.tsx, …
  - Check: `npm test -- ReportToolbar`
  - Covers: AC-3

<!-- GATE: Group 1 before Group 2 -->

## Group 2: SEQUENTIAL
- [ ] T3: Wire button to serializer
  - …

Stack gap: example

GAP: large exports need a background job queue

Not in the current stack. Options:

A) Stream the response, no queue

B) BullMQ + Redis: persistent jobs

C) SQS: managed, adds an AWS dependency

Recommendation: A, because…

Why every task has a check: an agent that can run a test knows when it's done. Without one, "looks done" is the only signal, and you end up checking every task by hand. Checks are also why /sdd-implement can run a whole group of tasks without stopping to ask you.

W·02

Implement

The main conversation coordinates · one sdd-implementer agent per task · check → commit → tick

plan first, then your approval one commit per task resumes where it stopped stops at blockers

Load and check. Confirms all three spec files exist and are committed, skips tasks that are already ticked, and checks every task has Files and Check lines.

Plan. Lists the groups, which tasks run in parallel, and each task's check. You approve.

Dispatch. Each task goes to a new sdd-implementer agent that sees only the spec and the code. Tasks in a PARALLEL group run at the same time.

Verify and commit. The coordinator re-runs the task's check, makes sure only the expected files changed, ticks the task and commits feat(csv-export): … [T1].

Wrap up. Runs the full test suite and offers /code-review to look for bugs. STATE.md shows the feature as awaiting validation.

Invoke, after committing the spec and running /clear

/sdd-implement csv-export

MAIN CONVERSATION (coordinator) plan → ✋ you approve │ ├─ sdd-implementer T1 ─┐ PARALLEL ├─ sdd-implementer T2 ─┘ │ each → report: DONE | BLOCKED │ ├─ run check · commit [T1] · tick ├─ run check · commit [T2] · tick ── GATE ── ├─ sdd-implementer T3 └─ run check · commit [T3] · tick

When an agent reports BLOCKED (a stack gap, a contradiction in the spec, or a check that can't pass), the coordinator stops and asks you. Agents can't ask you questions directly, so they report back instead of guessing.

W·03

Validate

Independent pass/fail per acceptance criterion · then steering docs · STATE.md · CHANGELOG · README · version

same session is fine the first step is a hard stop anyone on the team can run it

Conformance. sdd-reviewer, a read-only agent that never saw the implementation, checks each acceptance criterion with evidence and runs the full test suite. Any failure stops here.

Steering docs. Updates structure.md and tech.md where the feature changed them, including stack-gap decisions.

STATE.md. Moves the feature to Done and sets the hash to HEAD.

Metadata. Updates the CHANGELOG, README and version, only where those files exist. Asks before a version bump.

Invoke

/sdd-validate csv-export

sdd-reviewer verdict

| AC   | Verdict | Evidence                      |
| AC-1 | PASS    | csv.test.ts › escapes commas  |
| AC-2 | PASS    | csv.test.ts › header row      |
| AC-3 | FAIL    | no test for empty report      |

Commits:    one per task
Scope:      ok
Test suite: npm test → pass

OVERALL: FAIL

Why it no longer needs a new session: previously, validation needed a fresh session so the work wasn't judged by the conversation that built it. The reviewer agent now provides that fresh view automatically. The housekeeping that follows needs your answers, so it stays in the main conversation.

Several features in parallel

Parallel features in worktrees

Spec each feature · commit the specs · implement them at once in separate copies of the repo · merge · validate each

SPEC (one at a time, with your approval) /sdd-feature feature-a → commit spec /sdd-feature feature-b → commit spec IMPLEMENT (/sdd-implement feature-a and feature-b) worktree feature-a ← feature agent → sdd-implementer per task → commits worktree feature-b ← feature agent → sdd-implementer per task → commits MERGE you review and merge each branch into main VALIDATE (on main, one per feature) /sdd-validate feature-a /sdd-validate feature-b

.claude/settings.json (recommended)

{
  "worktree": { "baseRef": "head" }
}

Why this setting: by default, a new worktree starts from your remote default branch, so specs you've only committed locally would be missing. "head" starts it from your current commit instead. /sdd-implement checks this and offers to add the setting.

.worktreeinclude (optional)

.env
.env.local

A worktree is a fresh checkout without your gitignored files. List the ones the tests need (such as .env) in .worktreeinclude at the project root, and they're copied into each new worktree. Also make sure .claude/worktrees/ is in .gitignore.

✓ before running in parallel

Every spec is approved and committed, and every stack gap was resolved while writing the spec.

✓ overlap is checked for you

/sdd-implement compares the features' Files lists. Features that share files run one after another, in an order it proposes.

⚠ merging is your step

Each feature ends up on its own branch. Review and merge each one. Nothing is merged automatically.

⚠ validate after merging

Run /sdd-validate on main after each merge, so STATE.md describes the code that actually shipped.

FeatureWorkflow

Feature
Workflow