| name | apd-tdd |
| description | MANDATORY during the APD builder phase on Codex (between apd:apd_advance_pipeline('spec', ...) and apd:apd_advance_pipeline('builder')) whenever implementing a feature, fixing a bug, or writing new code. Write a FAILING test first, watch it fail, write minimal code to pass, refactor while green. Every file write goes through apd:apd_guard_write(apd_role, file_path); scope is enforced server-side from .apd/agents/<apd_role>.md. Triggers on "implement", "add feature", "fix bug", "write code", "TDD", "test-first", "builder". |
APD Test-Driven Development (Codex)
On Codex this skill applies to the native builder subagent dispatched between
apd:apd_advance_pipeline('spec', ...) and
apd:apd_advance_pipeline('builder'). The orchestrator coordinates the phase
and must not implement source changes itself.
When to use / When to skip
Use when:
- You are inside the APD builder phase
- You are about to write or modify production code (any non-test source file)
- You are fixing a bug that has reached Phase 4 of
apd-debug
Skip when:
- You are reading code without modifying it
- You are running an existing test suite (use shell directly)
- You are editing documentation, configuration, or scaffolding files
The Iron Law
NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
Write code before the test? Delete it. Start over. No exceptions.
Red → Green → Refactor
1. RED — failing test first
Write ONE minimal test that describes the behavior you want. Run it.
Watch it fail. If it passes on the first run, you are testing existing
behavior — fix the test to actually describe the new requirement.
Before each test-file write, call
apd:apd_guard_write(apd_role="<role>", file_path="<path>"). The server reads
scope from .apd/agents/<role>.md on every call — you only pass the role
name and target path. Use apd:apd_list_agents() to discover which roles are
defined. (Argument is apd_role, not role, to avoid Codex's
multi_agent role-mismatch approval prompt.)
2. GREEN — minimal code to pass
Write the SIMPLEST code that makes the test pass. Nothing more.
- No extra features
- No "while I'm here" improvements
- No over-engineering
3. REFACTOR — clean up (tests stay green)
Only once green: remove duplication, improve names, extract helpers. If a
test goes red during refactoring, revert immediately.
4. Next behavior
Pick the next behavior. Write the next failing test. Repeat.
Scope enforcement on every write
Builder scope is declared in the agent frontmatter
(.apd/agents/<role>.md, scope: list). Call
apd:apd_guard_write(apd_role="<role>", file_path="<path>") before every
Write/Edit — the server reads scope from the agent file itself, so the
role name is the only handle you need (and can't widen).
Do NOT bypass with direct Bash writes — guard-bash-scope blocks writes
into .apd/pipeline/ and reviewed-files scope, and the verifier will
fail the cycle.
Common rationalizations
| Excuse | Reality |
|---|
| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
| "I'll test after" | Tests that pass immediately prove nothing. WATCH them fail first. |
| "Need to explore first" | Fine. Throw away exploration code, then start with TDD. |
| "TDD will slow me down" | TDD is faster than debugging. Every time. |
| "Manual test is faster" | Manual testing doesn't prove edge cases or prevent regressions. |
| "I can't test this" | You can't test the CURRENT design. Simplify the design. |
Exit criteria
You're done when:
- Every new function has a test you watched fail
- All tests pass locally — both new and the prior suite (no regressions)
- Edge cases are covered (empty input, invalid input, boundary values)
- Every write went through
apd:apd_guard_write(apd_role=..., file_path=...)
- No unrelated files touched outside the agent's
scope:
- Refactor pass left tests green
Hand-off
- After this skill completes → call
apd:apd_advance_pipeline('builder')
- Then return control to the orchestrator, which dispatches the primary reviewer and calls
apd:apd_advance_pipeline('reviewer') — that step writes .adversarial-pending as the green light for the adversarial subagent
- Do NOT call
apd:apd_adversarial_pass before reviewer.done exists; the pre-flight gate refuses the call
- If a test goes red unexpectedly → switch to
apd-debug (Phase 4 of debug uses this skill again)
- Never skip — even for "trivial" changes. Especially for trivial changes.
