@windyroad/tdd

TDD state machine enforcement for Claude Code. Forces the Red-Green-Refactor cycle so your AI agent writes tests before implementation -- every time. Maturity: Experimental.

Part of Windy Road Agent Plugins.

What It Does

AI agents love to jump straight to implementation. This plugin stops that. It enforces a strict TDD state machine:

IDLE ──> RED ──> GREEN ──> RED (next test)
                   │
                   └──> Refactor (staying GREEN)

• IDLE -- No test written yet. Implementation file edits are blocked.
• RED -- A failing test exists. Implementation edits are allowed.
• GREEN -- Tests pass. You can refactor or write a new failing test.
• BLOCKED -- Test runner error or timeout. Fix the setup before continuing.

The agent must write a failing test first. There are no shortcuts.

Install

npx @windyroad/tdd

Restart Claude Code after installing.

Usage

The plugin activates automatically. On first use in a project without a test framework, it directs you to set one up:

/wr-tdd:setup-tests

This examines your codebase, recommends a test runner, configures package.json, and creates an example test.

Once active, the workflow is enforced on every edit:

1. Write a test file (*.test.ts, *.spec.ts, etc.) that describes the desired behaviour
2. The test must fail (RED state) -- proving the test is meaningful
3. Write the minimum implementation to make it pass (GREEN state)
4. Refactor while keeping tests green
5. Repeat

Test files and config/doc files are always writable regardless of state.

Supported test layouts

The hook associates an implementation file with its tracked test by matching one of the following path shapes (per P201):

| Shape | Impl path | Test path | |---|---|---| | Same-directory | src/foo.js | src/foo.test.js or src/foo.spec.js | | __tests__/-adjacent | src/foo.js | src/__tests__/foo.test.js | | Parent __tests__/ | src/components/Hero.tsx | src/__tests__/Hero.test.tsx | | test/-mirror (Vitest default; many Jest setups) | src/foo.js, src/a/b/foo.js, packages/<pkg>/src/foo.js | test/foo.test.js, test/a/b/foo.test.js, packages/<pkg>/test/foo.test.js | | Cucumber step-definitions | features/step_definitions/checkout.steps.js | features/checkout.feature |

The test/-mirror rule replaces the last src path segment with test, so it works at any nesting depth and for monorepo workspace layouts.

How It Works

| Hook | Trigger | What it does | |------|---------|-------------| | tdd-inject.sh | Every prompt | Injects the current TDD state into the prompt | | tdd-enforce-edit.sh | Edit or Write | Blocks implementation edits in IDLE or BLOCKED state | | tdd-post-write.sh | After edit | Runs tests and transitions the state machine | | tdd-review-test.sh | After edit | Classifies new test files as STRUCTURAL (asserts source content) or BEHAVIOURAL (exercises the target) and surfaces structural-test regressions per ADR-052 | | tdd-setup-marker.sh | Skill completes | Marks test setup as done | | tdd-reset.sh | Session end | Resets the TDD state |

Updating and Uninstalling

npx @windyroad/tdd --update
npx @windyroad/tdd --uninstall

Licence

MIT