tdd-loop
/tdd-loop
Runs strict test-driven development one behaviour at a time. Picks the next smallest behaviour from the spec or task list, writes one failing test, makes the smallest change that passes it, then refactors with the tests green. A guard script records each step and refuses the usual shortcuts. It rejects a red step that fails for the wrong reason (syntax, import or compile error, missing function, no tests ran) and code written before any failing test. It also rejects a test that was edited, deleted, skipped or focused with .only to reach green. Works with pytest, unittest, Jest, Vitest, go test
- Author
- milad-ahmd ↗
- Repository
- tdd-loop ↗
- Licence
- MIT
- Last repository change
- 02.11.2026
Assessment and security
- Files in this package
- 3
- Scripts
- 2
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 02.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 2 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/tdd_guard.py, scripts/test_tdd_guard.py
What it does and when to use it
Runs strict test-driven development one behaviour at a time. Picks the next smallest behaviour from the spec or task list, writes one failing test, makes the smallest change that passes it, then refactors with the tests green. A guard script records each step and refuses the usual shortcuts. It rejects a red step that fails for the wrong reason (syntax, import or compile error, missing function, no tests ran) and code written before any failing test. It also rejects a test that was edited, deleted, skipped or focused with .only to reach green. Works with pytest, unittest, Jest, Vitest, go test
Original author description
Runs strict test-driven development one behaviour at a time. Picks the next smallest behaviour from the spec or task list, writes one failing test, makes the smallest change that passes it, then refactors with the tests green. A guard script records each step and refuses the usual shortcuts. It rejects a red step that fails for the wrong reason (syntax, import or compile error, missing function, no tests ran) and code written before any failing test. It also rejects a test that was edited, deleted, skipped or focused with .only to reach green. Works with pytest, unittest, Jest, Vitest, go test
How it works
- 0. Set up once
- 1. Make a behaviour list
- 2. Red: one failing test
- 3. Green: the smallest change that passes
- 4. Refactor with the tests green
- 5. Commit and repeat
- Report
- What not to do
SKILL.md preview
---
name: tdd-loop
description: Runs strict test-driven development one behaviour at a time. Picks the next smallest behaviour from the spec or task list, writes one failing test, makes the smallest change that passes it, then refactors with the tests green. A guard script records each step and refuses the usual shortcuts. It rejects a red step that fails for the wrong reason (syntax, import or compile error, missing function, no tests ran) and code written before any failing test. It also rejects a test that was edited, deleted, skipped or focused with .only to reach green. Works with pytest, unittest, Jest, Vitest, go test, cargo test, RSpec, Maven and Gradle. Use when the user asks to do TDD, work test-first, write the test first, follow red green refactor, build a feature test-driven from a spec or user story, or stop the agent from changing tests to make them pass.
---
# TDD Loop
Build one behaviour at a time: a failing test, the least code that passes it, then a cleanup with the tests green. The guard script makes each step checkable, so "I wrote the test first" is a recorded fact rather than a claim.
## 0. Set up once
```bash
python3 scripts/tdd_guard.py detect # suggests the test command from project files
```
Pick a command that runs once and exits (`npx vitest run`, not `vitest` in watch mode). Prefer one that runs the current test file or test, so cycles stay fast, and run the whole suite before each commit. The guard keeps its state in `.tdd/` at the project root and writes a `.tdd/.gitignore` so git ignores it. Add `.tdd/` to the project's `.gitignore` too if the user wants it listed there.
Run one test:
| Runner | Command |
|---|---|
| pytest | `python3 -m pytest -q tests/test_slug.py::test_lowercases` |
| unittest | `python3 -m unittest tests.test_slug.SlugTest.test_lowercases` |
| Vitest / Jest | `npx vitest run src/slug.test.ts -t "lowercases"` / `npx jest src/slug.test.ts -t "lowercases"` |
| go test | `go test ./slug -run '^TestLowercases$'` |
| cargo | `cargo test lowercases` |
| Maven | `mvn -Dtest=SlugTest#lowercases test` |
## 1. Make a behaviour list
From the spec, issue or user story, write a short list of behaviours, each one observable from outside: "`slugify('Hello World')` returns `hello-world`", "a cart with an expired code is charged full price". Order them so each builds on the last, simplest and most central first. Show the list to the user and keep it updated in the conversation.
Slice vertically. One behaviour goes through every layer it needs (route, service, storage) in a single cycle. Don't write all the models first, then all the services.
## 2. Red: one failing test
Write exactly one test for the next behaviour. Test through the public interface (the function, the endpoint, the CLI), and assert on results the caller can see, not on private helpers or which internal methods were called. If the code doesn't exist yet, add a stub that compiles and returns a placeholder, so the test fails on its assertion rather than on an import.
```bash
python3 scripts/tdd_guard.py red --test "python3 -m pytest -q tests/test_slug.py"
python3 scripts/tdd_guard.py red --test "npx vitest run src/slug.test.ts" --files src/slug.test.ts
python3 scripts/tdd_guard.py red # later cycles reuse the recorded command
```
`red` passes only when the command fails on an assertion. It refuses if the tests pass already, if the failure is a syntax, import, compile or collection error, a missing function, a missing command, a timeout, or if no tests ran. It records SHA-256 snapshots of the test files: `--files`, plus every test file `git status` shows as changed. Without `--files` it needs at least one test file that is new or changed since the last cycle. It warns when more than one new test appeared, when the new test's name isn't in the failure output, and when source files were already changed. If the error really is the behaviour under test, pass `--allow-error "reason"`, which is recorded.
## 3. Green: the smallest change that passes
Change only production code. Hard-coding the expected value is fine when it is the simplest thing that passes. The next test will force the general version.
```bash
python3 scripts/tdd_guard.py green
```
`green` re-runs the recorded command and passes only if it exits 0 with tests run and no test file changed since red. A changed or deleted test file, or an added skip or focus marker (`@pytest.mark.skip`, `@unittest.skip`, `it.skip`, `xit`, `describe.only`, `t.Skip()`, `#[ignore]`, `@Disabled`), fails the check and prints the diff. This covers older test files too. If the test itself was wrong, revert it and run `red` again, or tell the user why and run `green --allow-test-change "reason"`.
## 4. Refactor with the tests green
Remove duplication, rename, extract, and simplify the test code as well as the production code. Keep the behaviour the same and re-run after each small step.
```bash
python3 scripts/tdd_guard.py refactor
```
It passes when the tests pass and no test file lost tests or assertions, gained a skip marker or was deleted. It lists the test files that changed. If a test was added, write it in the next red cycle instead.
## 5. Commit and repeat
Commit after each refactor if the user wants a commit per cycle; otherwise keep going. Tick the behaviour off the list and return to step 2. `python3 scripts/tdd_guard.py status` shows the phase, the guarded files and the cycle count.
Exit codes for every command: `0` check passed, `1` check failed (the reason is printed), `2` usage or state error, such as `green` with no recorded red. Add `--json` for machine-readable output and `--dir` to point at the project root.
## Report
After each cycle, give one line: behaviour, test name, red reason (assertion), green, refactor done or skipped, commit. At the end, list the behaviours done and the ones left, plus any `--allow-*` overrides and why they were needed.
## What not to do
- Skip red, or write the implementation and then a test that passes on the first run.
- Write several tests before making any of them pass.
- Change, loosen, delete, `.skip`, `xit` or `.only` a test to get to green.
- Mock everything. Mock only what is slow or outside your control (network, clock, payment provider), and use real objects for the rest.
- Assert on implementation details (private methods, call counts on internal collaborators) that break on every refactor.
- Add behaviour during refactor, or refactor while red.
- Run `--allow-test-change` or `--allow-error` without telling the user the reason.
- Delete `.tdd/` to get around a failed check. Fix the cause, or ask the user.
Files in this package (3)
- SKILL.md 7 KB
- scripts/tdd_guard.py 34 KB
- scripts/test_tdd_guard.py 18 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · milad-ahmd/tdd-loop | 100 | MIT |
| ramboz/jig | 100 | MIT |
| ramboz/jig | 100 | MIT |
| ramboz/jig | 100 | MIT |
| daniel-kindl/dkstack | 90 | MIT |
Database snapshot: 13.11.2026 · package version 9ae56b251009 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100tdd
Test-driven development: the agent writes the failing test, then the code, one behavior at a time. Use when building a feature or fixing a bug test-first, or when the user says tdd, red-green, or test-first. - 100tdd
Runs a strict red-green-refactor loop for one acceptance criterion or behaviour: write the failing test, show the failure, write the minimum code, show it passing, refactor with tests green. Use inside /dev-story, or whenever the user wants to build or fix behaviour test-first. - 100tdd-engineer
Drives implementation through Red, Green, Refactor cycles: writes one failing test from a scenario, makes it pass with the simplest change, then refactors, reporting actual test results at every step. Use when implementing new behaviour. - 100tdd
Enforces strict RED-GREEN-REFACTOR test-driven development — one failing test at a time, minimal code to pass, then refactor against an inline quality checklist and a test-provenance check (`provenance` runs it alone). Triggers on "tdd", "write tests", "test driven", "red green refactor", "/tdd". - 100tdd-engineer
Drives implementation through Red, Green, Refactor cycles: writes one failing test from a scenario, makes it pass with the simplest change, then refactors, reporting actual test results at every step. Use when implementing new behaviour. - 100054-design-tdd
Use when Java implementation work should be guided by Test-Driven Development, including maintaining a test list, choosing the next behavior, writing a failing test first, implementing only enough production code to pass, and refactoring while keeping tests green. This should…