stdd

stdd

stdd is a Claude Code plugin that makes the agent write a spec and a test before it writes code, and stops it committing while a test fails.

The rules are enforced by shell scripts wired to Git hooks, not by asking the model nicely. So the agent can't skip a step, even when it's tempted to.

How it splits up control

stdd draws a hard line between three kinds of decision.

• The machine decides go or no-go. A handful of shell scripts check plain facts: does this file exist, did the tests pass, does a hash match. That's all that can block a write or a commit. No judgement, no guessing.
• The model does the work. The slash commands run Claude, which writes the spec, picks the next test, and cleans up the code. Useful, but it can only propose. It never gets to decide whether a check passes.
• You make the judgement calls. Is this spec good enough to build? Does this review finding matter? Should I skip a check just this once? stdd puts these in front of you and keeps the agent out of them.

One rule holds it together: only the mechanical checks can gate. When stdd asks for a spec review before you build, the check is just that a review ran against the current spec; a hash proves that. Whether the review was any good is your call, not the script's.

Quickstart

Install the plugin:

/plugin marketplace add dominik-rehse/stdd
/plugin install stdd@stdd

Set up your project once:

/stdd:setup

Then work one slice at a time:

/stdd:spec auth/login            # interview you into a spec with numbered criteria
/stdd:review auth/login --spec   # red-team the spec before you build
/stdd:tdd auth/login             # write a failing test, make it pass, refactor, repeat

If the agent tries to jump straight to code, the guard stops it:

✗ Write blocked: no spec or test exists for src/auth/login.ts.
  Write the spec and a failing test first, or run /stdd:spec auth/login.

And a commit with a failing test doesn't go through:

✗ Commit blocked: 1 test failing.

That's the whole idea. The rest of this page is detail.

The workflow

The slash commands are where Claude works on your code. You stay in the loop on the decisions that matter, and the checks hold whatever it writes to a fixed bar.

Command	What it does
/stdd:setup	Set up the project: folders, test runner, pre-commit gate. Run once.
/stdd:plan <sketch>	Turn a rough sketch into an ordered backlog of slices in docs/roadmap.md.
/stdd:spec <name>	Interview you into one self-contained spec, with numbered acceptance criteria.
/stdd:review <name> --spec	Red-team a spec in a fresh context before you build. Required for a critical spec.
/stdd:tdd <name>	Run the loop, one criterion at a time: RED → GREEN → REFACTOR → MARK.
/stdd:review <name>	Show which criteria have tests. No name: sweep docs/ for drift.
/stdd:remove <name>	Retire a whole feature: delete its spec, code, and tests together, sweep docs/, record the decision.
/stdd:mutate <name>	Optional. Estimate how strong a spec's tests are, by mutation testing. Never gates.
/stdd:worktree <name>	Set up a parallel worktree for a slice marked Independent? yes.
/stdd:batch [slice ...]	Fan out independent slices to parallel worktree subagents.
/stdd:land [slice ...]	Merge the finished worktrees back, re-check, clean up. Stops on any conflict or failure.

The usual path is plan once, then for each slice: spec → review --spec → tdd, with mutate when a spec is worth the extra scrutiny.