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:
- A spec at
docs/specs/<feature>.md
- 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
dominik-rehse