stdd

stdd

Spec and test driven development for Claude Code. Enforces spec-first, one-test-at-a-time TDD through three layers: a PreToolUse guard hook, a git pre-commit gate, and slash commands that embed the red-green-refactor loop.

Install

From GitHub (requires the repo to be public):

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

The first command registers the repo as a marketplace; the second installs the plugin.

Local / development (no GitHub required):

claude --plugin-dir ./stdd

Once Claude Code starts, run /stdd:setup in your project to finish initialisation (see Quick start below).

How it works

Three enforcement layers

Layer	What it does	When it fires
PreToolUse hook	Blocks writes of new src/ files unless a spec and a test already exist	Every Write call during the session
Git pre-commit	Blocks commits while any test is failing	git commit
Slash commands	Walk you through spec creation and the TDD loop	Invoked explicitly

The guard hook in detail

The hook gates new files in src/ only. It does not block:

• Edits to files that already exist
• Writes outside src/
• Test files (*.test.*, *.spec.*, *_test.*, *_spec.*) — these are the RED-phase artifact and must be writable before the implementation file
• Any write while a .tdd-in-progress marker is present (created and removed by /stdd:tdd)

To pass the gate without the marker, two prerequisites must exist:

1. A spec at docs/specs/<feature>.md
2. A test file — either co-located (src/<feature>.test.<ext>) or in tests/

Feature names map flexibly: src/my_feature.ts matches both docs/specs/my_feature.md and docs/specs/my-feature.md.

Turning the guard off

Create an empty .stdd-off file in the project root to disable the guard hook entirely. Remove it to re-enable. The file is gitignored — the switch is per-developer, not checked in.

touch .stdd-off   # off
rm .stdd-off      # back on

Supported test frameworks

run-tests.sh detects and runs whichever framework the project uses:

Framework	Detected by	Command
pytest	pyproject.toml / setup.py / setup.cfg / pytest.ini	python -m pytest tests/ -v
Bun	bun.lockb	bun test
Node (npm)	package.json (no bun.lockb)	npm test
Go	go.mod	go test ./...
Rust	Cargo.toml	cargo test
Ruby	Gemfile	bundle exec rspec

Bun is checked before Node because both projects have a package.json.

Quick start

/stdd:setup          ← run once per project (creates dirs, installs hooks and rules)
/stdd:spec <name>    ← guided interview that writes docs/specs/<name>.md
/stdd:tdd  <name>    ← runs the red-green-refactor loop against that spec

1. Initialise the project

/stdd:setup

Creates docs/specs/, src/, tests/, scripts/, installs scripts/run-tests.sh and .git/hooks/pre-commit, and writes .claude/rules/stdd.md so the workflow rules are always in context.

Safe to re-run — existing files are not overwritten.

2. Write a spec

/stdd:spec calculator

Claude asks four questions (problem, inputs/outputs, behaviour, acceptance criteria) and writes docs/specs/calculator.md — as detailed as the feature warrants.

3. Implement with TDD

/stdd:tdd calculator

Works through each acceptance criterion one at a time:

RED      write one failing test          → run tests (must fail)
GREEN    write the minimum code          → run tests (must pass)
REFACTOR clean up what you just wrote    → run tests (must still pass)
         ↳ back to RED for the next criterion

The loop creates a .tdd-in-progress marker so the guard hook allows src/ writes during implementation. The marker is removed at the end.

Project layout after setup

docs/specs/        specs (one .md per feature)
src/               implementation + co-located tests (*.test.<ext>)
tests/             tests (alternative to co-location)
scripts/
  run-tests.sh     language-agnostic test runner
.git/hooks/
  pre-commit       blocks commits while tests fail
.claude/rules/
  stdd.md          workflow rules (always in context)

Commands

Command	Purpose
/stdd:setup	One-time project initialisation
/stdd:spec <name>	Guided spec creation
/stdd:tdd <name>	Red-green-refactor loop

References

• Claude Code plugins — create and distribute a marketplace
• Claude Code plugins — discover and install