agentleFS
Sign inStart free
qyndexqyndex/claude-init/.claude/skills/tdd-loop/SKILL.md

tdd-loop

Skill2 starsChanged 5 months agoMITView on GitHub

The strict red→green→refactor loop, mechanically enforced. Write a failing test FIRST (red), capture the failure as a durable artifact, implement minimally (green), capture the pass, then refactor. Round 10 A — the skill 5 files referenced that did not exist.

9 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

11 rules. 0 are common, 8 are distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 9 edited versions we read keep these.

  • 8

    Distinctive

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    No production code without a failing test that demanded it.

    line 13
  2. Very specific:

    Write the test that encodes the spec's acceptance criterion.

    line 19
  3. Very specific:

    Run the task's accept: command (or the specific test).

    line 20
  4. Distinctive:

    If the test passes on first run, the test is wrong (asserts nothing, or the behavior already exists).

    line 22
  5. Distinctive:

    Write the minimum code to make the test pass.

    line 26
  6. Distinctive:

    Run the same command.

    line 27
  7. Distinctive:

    Never add behavior here — that needs a new red test.

    line 34
  8. Distinctive:

    One test, one behavior: Don't batch 5 behaviors into one test.

    line 50
  9. Distinctive:

    AC-tagged: Every test that proves an acceptance criterion carries its AC id.

    line 51
  10. Distinctive:

    Minimal green: Don't implement beyond what the red test demands.

    line 53
  11. Distinctive:

    Test is AC-tagged and contains ≥1 real assertion

    line 71

“Common” is measured: kept by at least 6 in 10 of the 9 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

TDD Loop — red → green → refactor, enforced

Mandate

No production code without a failing test that demanded it. The transition from red to green is captured as a durable artifact (verify/<date>/<task>/red.log + green.log), not just pasted in the transcript — so the factory can PROVE the test went red before it went green.

The loop

1. RED — write the failing test first

  • Write the test that encodes the spec's acceptance criterion. Tag it with the AC id, UNPADDED (@AC-1 / { tag: ['@AC-1'] } / docstring AC-1) — matching the spec template's **AC-1**: form (e2e-audit e2e-rig-3).
  • Run the task's accept: command (or the specific test).
  • Capture the failure: bash .claude/scripts/tdd-ledger.sh red <task-id> "<accept-command>" → writes verify/<date>/<task-id>/red.log with the command + exit code (MUST be non-zero) + output excerpt.
  • If the test passes on first run, the test is wrong (asserts nothing, or the behavior already exists). Fix the test until it fails for the RIGHT reason.

2. GREEN — implement minimally

  • Write the minimum code to make the test pass. No speculative features (CLAUDE.md §I.2 Simplicity First).
  • Run the same command.
  • Capture the pass: bash .claude/scripts/tdd-ledger.sh green <task-id> "<accept-command>" → writes verify/<date>/<task-id>/green.log (exit code MUST be 0).

3. REFACTOR — clean up, stay green

  • Improve names, remove duplication, extract helpers.
  • Re-run; confirm still green (the green.log timestamp updates).
  • Never add behavior here — that needs a new red test.

Enforcement (what makes this real, not honor-system)

MechanismWhat it catches
tdd-ledger.sh writes red.log + green.logProof the test went red before green; both committed under verify/
verify.sh requires both logs for any [x] taskA task marked done without a red→green transition fails the gate
assert-density.sh (verify.sh + CI)Assertion-free tests (expect(true).toBe(true))
validate.sh accept-is-a-test gateaccept: echo done — accept must invoke a test runner
story-test-map.sh (wired into verify.sh)User story without an E2E test
mutation.yml on critical pathsTests that pass but don't actually constrain behavior

Hard rules

  • Red before green, always. The ledger proves it. Skipping red = the task fails verify.
  • One test, one behavior. Don't batch 5 behaviors into one test.
  • AC-tagged. Every test that proves an acceptance criterion carries its AC id.
  • Assertions required. A test with no expect/assert is not a test.
  • Minimal green. Don't implement beyond what the red test demands.
  • Refactor stays green. New behavior in refactor → stop, write a new red test.

The honest ceiling

Tooling proves a test ran red-then-green, contains assertions, and kills mutants. It does NOT prove the test asserts the RIGHT behavior — that the test maps to spec intent rather than to the implementation. That judgment stays with the agent's discipline (this skill) + the reviewer agent reading the diff against the spec. Tooling raises the floor; the reviewer certifies the ceiling.

References

  • obra/superpowers: test-driven-development skill (the discipline)
  • Kent Beck, TDD By Example (red/green/refactor origin)
  • Ledger: .claude/scripts/tdd-ledger.sh
  • Gate: .claude/scripts/verify.sh + assert-density.sh

Done means

  • verify/<date>/<task-id>/red.log exists (exit ≠ 0)
  • verify/<date>/<task-id>/green.log exists (exit = 0)
  • Test is AC-tagged and contains ≥1 real assertion
  • Code is minimal for the test
  • Refactor left it green

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free