tdd

name	tdd
description	Test-driven development for one feature slice or bug fix. Use when Codex should work red-green-refactor, add behavior-focused tests, protect public interfaces, or turn a repro into a regression test during implementation.

Test-Driven Development

Use TDD to build one behavior at a time through public interfaces.

Read docs/agents/domain.md and docs/agents/verification.md if they exist.

Principles

• Test behavior, not implementation details.
• Prefer integration-style seams that exercise real code paths.
• Write one test, make it pass, then repeat.
• Refactor only while tests are green.
• Do not write a batch of imagined tests before seeing the implementation path.

Workflow

1. Choose The Seam

Pick the highest useful public interface:

• UI workflow, HTTP endpoint, CLI command, public API, domain service, or fixture-based path.
• Existing test style in the repo.
• A seam that can also serve acceptance or regression evidence.

If no good seam exists, state the limitation and use the best command/manual verification available. Do not invent brittle tests just to appear test-first.

2. Red

Write one focused test for one observable behavior. It should fail for the right reason when practical.

3. Green

Implement the smallest change that passes the test. Avoid speculative interfaces or future options.

4. Refactor

Clean duplication or awkward design only after the test is green. Keep the public behavior unchanged and rerun the focused check after each meaningful refactor.

5. Repeat

Add the next behavior only after learning from the previous cycle. Stop when the work item's acceptance criteria are covered.

6. Record Evidence

For handoff and acceptance, record:

• Tests added or changed.
• The command that proves them.
• Any broader regression command run.
• Any behavior that remains manual or risky.

Test Quality Checklist

• The test name uses project domain vocabulary.
• The test would survive an internal refactor.
• The test fails if the user-visible behavior is wrong.
• Mocks are only used at true external boundaries.
• The tested seam matches the acceptance criterion or bug repro.