tdd-protocol

Write a failing test first and signal [RED], then write the minimum code to pass it and signal [GREEN], and only refactor after tests pass. This protocol adds a Mutate phase between Green and Refactor to verify the tests actually catch broken code.

Mutation testing deliberately weakens the code under test — deleting a guard, changing a condition, or shifting a boundary — and confirms the test suite goes red. If the suite still passes, the tests are theater and must be strengthened before refactoring.

Use gremlins for Go, installed via go install github.com/go-gremlins/gremlins/cmd/gremlins@latest, and Stryker for TypeScript or JavaScript, initialized with npx stryker init. If neither tool is available, the mutation gate is skipped or done by hand.

The hook blocks Write or Edit operations on implementation files when no test file has been touched in the session. Write the failing test first, then retry; the stderr message lists expected test-file locations, and SKIP_TDD_GUARD=1 is the documented escape hatch.

Do not use it to decide what to build — brainstorming and plan-writing skills own that upstream phase. It governs only the code-writing cycle once a plan exists, and many file types like docs, configs, and shell scripts are exempt from the guard.