tdd

name	tdd
description	Build new behavior test-first using strict Red-Green-Refactor cycles. Use this when you want to drive a new feature or behavior from failing tests before writing the implementation.
user-invocable	true

Test-Driven Development

Implement features using strict Red-Green-Refactor cycles. Implements the testing protocol in rules/godmode-testing.md.

---

Auto Mode

Auto Mode suppresses confirmation prompts, not the clarifying questions that decide what the tests assert. If a target behavior is genuinely ambiguous — the expected output, an edge case's contract — don't ask blank: lead with the contract you'd assert and invite the override (e.g. "I'll assert this edge case returns an empty list rather than throwing — correct me before I write the red test"), because the tests encode it and guessing bakes the wrong contract into red-green. This is the clarifying rendering of the shared recommendation convention (godmode:recommend-convention) defined in rules/godmode-recommend.md. For low-stakes decomposition choices, use reasonable defaults and surface the behavior list + assumptions inline, then run the cycles. Treat course-corrections as normal input.

---

The Job

Break the feature into small behaviors. For each behavior, run one Red-Green-Refactor cycle.

---

The Cycle

RED — Write a failing test

• Write ONE test for the next desired behavior
• Run it. It MUST fail. If it passes, the test is wrong.
• The test should fail for the RIGHT reason (not syntax/import error)
• Test name: should [expected behavior] when [condition]

GREEN — Make it pass with minimal code

• Write the SIMPLEST code that makes the test pass
• No optimization, no elegance — just pass
• Run ALL tests. Every test must pass.

REFACTOR — Clean up while green

• Remove duplication, improve naming, simplify logic
• Run tests after EACH refactoring change
• If any test breaks: revert and try smaller step

---

Rules

• NEVER write production code without a failing test first
• One test at a time. Don't batch.
• Commit after each GREEN step (atomic progress)
• Test behavior, not implementation details
• Keep tests independent — no shared mutable state
• Detect and use the project's existing test framework
• When .planning/STANDARDS.md is present, the code you write must honor it as authoritative project context over the generic defaults where it has spoken (see "Project Standards Precedence" in rules/godmode-coding.md)

---

Workflow Per Feature

1. List the behaviors to implement (3-7 items typically)
2. Order from simplest to most complex
3. For each: RED → GREEN → REFACTOR → COMMIT
4. After all: run quality gates (from config/quality-gates.txt)

---

Progress Report

After each cycle:

Cycle N: [test name]
  RED:      Test written, fails as expected
  GREEN:    [approach taken], all tests pass
  REFACTOR: [what was cleaned up] (or "none needed")
  Tests:    X passing / X total

---

Agent Routing

Step	Agent	Purpose
Before first RED	MUST spawn @researcher	Find test framework, utilities, naming conventions, fixtures, and existing test patterns
REFACTOR	Always run /verify (5 parallel review lenses) when >3 files changed	Review refactored code for correctness and adherence to project patterns

Rule: Never explore the codebase inline when @researcher can do it in parallel.

---

Feeding Back Into the Workflow

After the behavior list is generated (end of "Workflow Per Feature" step 1), decide how the work re-enters the workflow spine:

• Run all cycles now (default). Drive each behavior through RED-GREEN-REFACTOR immediately, committing after each GREEN. Best when the feature is small and well-scoped.
• Defer as a work unit. When the feature is large (4+ behaviors) and deserves its own planning pass, append a work unit to .planning/missions/<mission_id>/ROADMAP.md describing the feature and its behaviors, then pick it up with /brief N. The brief captures the why + what, /plan N breaks it down into the same behavior list, and /build N drives the cycles.

In Auto Mode, run all cycles now unless the feature clearly needs its own planning pass — then append a work unit and say so inline.

Appended work-unit note (for .planning/missions/<mission_id>/ROADMAP.md):

- TDD: [feature name] — N behaviors, each one RED-GREEN-REFACTOR cycle.
  Behaviors: [short list]. Drive test-first; quality gates per cycle.

---

Output

The Progress Report above narrates each Red-Green-Refactor cycle as it runs; close the whole run with one consolidated result block. It leads with the terminal state, summarizes the cycles, and names one next move:

• Status — all behaviors driven test-first to green, or the remaining work deferred as a work unit.
• Cycles — the behaviors implemented, each one a completed Red→Green→Refactor cycle.
• Tests — the passing/total count and the files changed.
• Gates — the quality-gate results (all ✓).
• Next — the single onward pointer:

"Implemented [N] behaviors test-first; [X]/[X] tests pass and all quality gates are green. Run /ship to take the feature to a PR."

When the remaining behaviors are deferred instead of driven now, the next-step names the work-unit handoff:

"Drove [N] behaviors; appended the rest as a work unit to .planning/missions/<mission_id>/ROADMAP.md. Run /brief N to plan it."

---

Related

• @test-writer — for adding coverage to existing code (not TDD)
• /refactor — for refactoring existing code without adding features
• /debug — if a test reveals a bug, switch to debugging protocol

Spine: decompose into behaviors, then either run the cycles now (/ship) or append a work unit to .planning/missions/<mission_id>/ROADMAP.md and resume the spine at /brief N.