apd-tdd

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.