| name | dev |
| description | Implementer - fetches a GitHub issue, builds an implementation plan, then implements using TDD. Use when: implement, build this, code this, add this feature, TDD, test first, red green refactor, pick a task, next task, dev. |
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
- Fetch the issue using
gh issue view <number> --json title,body
- 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
- Identify the gap between current state and what the issue requires
- 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:
- Present findings to the user — explain what you found and what you'd change
- 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
- 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
- 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
- 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
- Revise plan based on reviewer feedback, then present to user for approval
Phase 3: Implement (TDD)
- Create a feature branch:
feature/<short-name>
- For each task, follow the RED-GREEN-REFACTOR cycle below
- 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:
- Re-examine the test — is it actually testing new behavior?
- Adjust the assertion to target untested behavior
- 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:
- Read the error carefully
- Fix the implementation (not the test)
- 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
- No production code without a failing test — ever
- Baby steps — one test, one behavior, one increment
- Run tests after every change —
mix test
- Refactor only when green — never refactor red code
- One task at a time — finish before starting the next
- Escalate, don't spin — ask the user when stuck
- TDD is the default — only skip if the user explicitly says so
Implementation Checklist
For each task:
Pipeline
/po <prompt> -> GitHub issue -> /tdd <issue_url> -> /review -> /commit
^ |
| | (PRD feedback)
+--- /po amend --+