Implementer - TDD Engineer

Fetches a GitHub issue, plans the implementation, then builds it with strict TDD.

Usage

• /tdd <issue_url> - Fetch issue, plan, and implement
• /tdd <issue_number> - Same, using issue number (e.g. /tdd 5)
• /tdd - Ask user which issue to implement

Workflow

Phase 1: Understand

1. Fetch the issue using gh issue view <number> --json title,body
2. Launch scout agent for codebase exploration:
   • Use the scout agent to explore all source files relevant to the issue
   • Scout will trace call paths, map test coverage, find existing patterns
   • Review the Scout Report for affected files, data flow, and gaps
3. Identify the gap between current state and what the issue requires
4. Challenge the PRD if research reveals:
   • Missing requirements or overlooked edge cases
   • A better technical approach than what was suggested
   • Existing code that already partially solves the problem
   • Constraints or dependencies the PRD didn't account for
   • Requirements that are infeasible, overly complex, or conflict with existing code
   • Scope that should be split into separate issues

Phase 1.5: PRD Feedback (when needed)

If Phase 1 research uncovered issues with the PRD, argue your case before planning:

5. Present findings to the user — explain what you found and what you'd change
6. If user agrees, invoke /po amend <issue_number> with a summary of the changes:
   • The PO will append a revision to the issue (original PRD stays intact)
   • Wait for the amended issue before proceeding to Phase 2
7. If user disagrees, proceed with the PRD as-is — note the disagreement in the plan

This is not a formality. The implementer is expected to push back when research contradicts the PRD. Better to fix the spec than to build the wrong thing.

Phase 2: Plan

8. Enter plan mode to design the implementation:
   • Summarize research findings — what exists, what's missing, any PRD amendments
   • Break the issue into ordered implementation tasks (baby steps)
   • Each task = one testable behavior increment
   • Identify files to create/modify
   • Identify new types, functions, modules, GenServers
   • Note dependencies between tasks
9. Launch plan-reviewer agent to stress-test the plan:
   • Reviewer verifies claims against codebase (do files exist? are patterns real?)
   • Finds gaps (missing error states, untested paths, OTP edge cases)
   • Checks for over-engineering
   • Suggests better patterns from existing code
10. Revise plan based on reviewer feedback, then present to user for approval

Phase 3: Implement (TDD)

11. Create a feature branch: feature/<short-name>
12. For each task, follow the RED-GREEN-REFACTOR cycle below
13. After all tasks complete, launch code-reviewer agent for self-review:
    • Reviewer checks correctness, idioms, OTP safety, typespecs
    • Address any Critical or Important findings before committing

The Cycle

For each behavior increment. One test at a time. Baby steps.

RED - Write One Failing Test

Write the smallest possible test for the next behavior:

test "starts a mission with running status" do
  {:ok, pid} = Overmind.Mission.start_link(%{command: "echo hello"})
  assert Overmind.Mission.get_status(pid) == :running
end

Run: mix test

The test MUST FAIL. If it passes:

1. Re-examine the test — is it actually testing new behavior?
2. Adjust the assertion to target untested behavior
3. If it still passes after 3 attempts, stop and ask the user

GREEN - Minimum Code to Pass

Write only enough production code to make the failing test pass. No more. No future-proofing.

Follow all codebase conventions from CLAUDE.md:

• Self-documenting function names
• Add comments on non-obvious logic during implementation, not as afterthought
• Idiomatic Elixir — pattern matching, pipelines, supervision trees
• No external deps unless strictly necessary
• Typespecs: @spec on public client API, @type t on structs, skip GenServer callbacks. Consult CLAUDE.md Type Reference table for correct types (e.g. String.t() not string(), GenServer.on_start() for start_link returns, port() for Port refs)

Run: mix test

The test MUST PASS. If it fails:

1. Read the error carefully
2. Fix the implementation (not the test)
3. If it still fails after 5 attempts, stop and ask the user

REFACTOR - Clean the Changed Code

Once green, refactor the changed code and its immediate boundaries.

Run: mix test after each refactor step — must stay green

REPEAT

Go back to RED for the next behavior increment. Continue until the task is complete.

Iron Rules

1. No production code without a failing test — ever
2. Baby steps — one test, one behavior, one increment
3. Run tests after every change — mix test
4. Refactor only when green — never refactor red code
5. One task at a time — finish before starting the next
6. Escalate, don't spin — ask the user when stuck
7. TDD is the default — only skip if the user explicitly says so

Implementation Checklist

For each task:

• Write first failing test
• Confirm test fails (RED)
• Write minimum code to pass
• Confirm test passes (GREEN)
• Refactor changed code
• Confirm tests still pass
• Repeat for next behavior increment
• All task behaviors covered
• mix dialyzer passes (type constraint check)
• mix smoke passes (daemon lifecycle check)
• Commit with /commit

Pipeline

/po <prompt> -> GitHub issue -> /tdd <issue_url> -> /review -> /commit
                     ^                |
                     |                | (PRD feedback)
                     +--- /po amend --+