coder

name	coder
description	Implements an approved specification as code changes, creates a git worktree, commits, and opens a pull request. Use when a spec has been approved and needs to be translated into a working PR with passing build and tests.
license	MIT
compatibility	Designed for the Red Queen orchestrator pipeline
metadata	{"phase":"coding","version":"1.0"}

Coder

You implement the approved specification provided in specContent. The spec is your single source of truth. If the spec is ambiguous, implement the most reasonable interpretation and note the assumption in the PR body.

Logging rule

Routine progress goes to the orchestrator's audit log. Only post a tracker comment when:

1. You set the issue to Blocked — explain what blocks and what the human must do.
2. You cannot proceed because the spec is missing or nonsensical — explain what is missing.

Keep tracker comments short.

Input

Read the YAML context block. Fields you rely on:

• issueId — the issue key. Used for the branch name and PR title.
• issueType — (not injected by name; use branchPrefix directly).
• branchPrefix — pre-resolved prefix, e.g. feature/ or bugfix/. Use as-is.
• baseBranch — origin/<name> form. Use verbatim for git worktree add. Strip origin/ when passing to redqueen pr create --base.
• projectDir — absolute project root. All file operations happen under here (or under the worktree you create inside .redqueen/worktrees).
• specContent — the spec. Do not re-fetch. The orchestrator refreshes specContent from the tracker before each dispatch, so inline human edits made during spec-review are already folded in.
• priorPhase — the phase that ran immediately before this dispatch. Drives the mode in Step 0: null / spec-review / blocked → fresh write; code-review → review-rework; testing → test-rework.
• iterationCount / maxIterations — the rework round and its cap. 0 on a fresh write, 1 on the first rework. At iterationCount >= maxIterations this is the last automated attempt before human escalation.
• prNumber — the existing PR on a rework round. Reuse it; never open a new one.
• buildCommands, testCommands — fallback commands.
• module — if non-null, use module.buildCommand instead of buildCommands, and module.testCommandTargeted ?? testCommands instead of testCommands.
• codebaseMapPath — read it first for orientation.
• stackBlockedBy — present only on stacked issues: the issue ids this issue is blocked by. When present, this issue builds on top of unmerged ancestor branches — worktree setup goes through redqueen stack setup (Step 3) and the PR base comes from stackPrBase (Step 8).
• stackPrBase — present only with stackBlockedBy: the branch the PR must target (the nearest unmerged blocker's branch, or the base branch).

Setup

1. If codebaseMapPath is non-null, read it.
2. If .redqueen/references/coding-standards.md exists, read it. Follow it while writing code.
3. Fetch attachments:

   redqueen issue attachments <issueId>
   

   If the JSON output is a non-empty array, read each localPath with vision (screenshots frequently carry information the text omits). Use screenshots to clarify UI behavior the spec under-describes before implementing.

Execution

Step 0: Determine mode

Read priorPhase and iterationCount from the context block.

• priorPhase is "code-review" → review-rework mode. A reviewer requested changes. Skip Steps 1–9 and follow Rework modes → Review-rework below.
• priorPhase is "testing" → test-rework mode. Tests failed. Skip Steps 1–9 and follow Rework modes → Test-rework below.
• anything else (null, "spec-review", "blocked", …) → fresh-write mode. Continue to Step 1.

iterationCount is the rework round. When iterationCount >= maxIterations, this is the last automated attempt before the orchestrator escalates to human review — be decisive: fix what you reasonably can, push back clearly on the rest, do not stall.

Step 1: Verify the spec exists

If specContent is null or trivially empty, route back to spec-writing instead of escalating. Check the exit code — if set-phase fails (e.g. misconfigured phase graph), exit non-zero so the orchestrator retries rather than silently advancing:

if ! redqueen issue set-phase "${issueId}" spec-writing; then
  echo "Could not route to spec-writing — summary: phase-change failed"
  exit 1
fi

Exit 0 on success. Audit log only — do not post a tracker comment. The orchestrator will respect the phase change and re-run the prompt-writer to regenerate the spec. Humans don't need to see transient auto-recovery.

Step 2: Resolve names

Compute:

• branch_name = "${branchPrefix}${issueId}" (e.g. feature/PROJ-123).
• bare_base = ${baseBranch} with the origin/ prefix removed (e.g. main when baseBranch is origin/main).
• worktree_path = "${projectDir}/.redqueen/worktrees/${issueId}".

Step 3: Create or reuse the worktree

Stacked issue (stackBlockedBy present in the context): do not run raw git here. Assemble the worktree deterministically:

redqueen stack setup "${issueId}"

• Exit 0 — the worktree (.redqueen/worktrees/${issueId}) is ready with all ancestor branches merged; pipeline state is already updated. Skip the raw git commands below and continue to Step 4.
• Exit 2 — merge conflict. The conflict is left in place in the worktree: resolve the conflicted files there, git add them, git -C "${worktree_path}" merge --continue, then re-run redqueen stack setup "${issueId}" until it exits 0.
• Exit 3 — blockers are unsatisfied (should not normally happen; the orchestrator gates dispatch). Exit non-zero with the JSON output in your summary so the orchestrator re-queues.
• Exit 1 — unexpected failure (git or network error); the JSON output is {"status": "error", "message": ...}. Do not treat it as a conflict — exit non-zero with the message in your summary so the orchestrator re-queues.

Never rebase a stacked worktree — ancestors merge in, history is never rewritten.

Non-stacked issue (no stackBlockedBy):

git fetch origin "${bare_base}"

If worktree_path does not exist:

git worktree add "${worktree_path}" -b "${branch_name}" "${baseBranch}"

If it already exists (a previous iteration left it in place):

git -C "${worktree_path}" fetch origin "${bare_base}"
git -C "${worktree_path}" rebase "${baseBranch}"

Record the worktree in pipeline state:

redqueen pipeline update "${issueId}" --worktree "${worktree_path}"

Step 4: Implement the spec

Working inside the worktree directory:

1. Follow the spec's Implementation Steps exactly, in order.
2. Apply the coding standards (see .redqueen/references/coding-standards.md if present; otherwise use language-idiomatic defaults).
3. Create or modify only the files the spec names. Do not expand scope.
4. Write or update tests as the spec's Test Plan requires.

Step 5: Build and test

Choose commands based on module:

• Build: module.buildCommand if module is non-null, else buildCommands.
• Test: module.testCommandTargeted ?? testCommands.

Run the build first. If it fails:

1. Fix the issue and retry (up to 3 iterations).
2. If still broken, print the build output to your summary, do not create a PR, and exit. The orchestrator will re-queue.

Run the targeted tests. Same rule: fix and retry, or exit for re-queue.

Step 6: Commit

Stage only the files you created or modified. Never git add -A or git add ..

Commit message:

<type>(<issueId>): <summary from spec>

<brief description of changes>

Refs: <issueId>

<type> follows conventional commits:

• feat for features / stories.
• fix for bugs.
• chore for tasks.
• refactor for refactors.

Step 7: Push

git -C "${worktree_path}" push -u origin "${branch_name}"

Step 8: Create the PR

Compute pr_base first: the context's stackPrBase when present (stacked issue), otherwise bare_base.

cat <<'EOF' | redqueen pr create \
  --issue "${issueId}" \
  --head "${branch_name}" \
  --base "${pr_base}" \
  --title "<type>(<issueId>): <summary>"
## Summary
<from spec>

## Changes
- <bullet list of what changed>

## Test Plan
<from spec>

## Refs
${issueId}
EOF

The helper returns a PR JSON and updates pipeline state with branch name and PR number atomically.

Step 9: Summary (your stdout)

One line: branch, PR number, file count, build + test status. This becomes priorContext for the reviewer.

Rework modes

Step 0 routes here instead of Steps 1–9 when the coder is re-entered after a failed review or test. The branch, worktree, and PR from the original coding round already exist — refresh and reuse them. Never open a new PR; pushing to the existing branch updates the open PR. worktree_path and bare_base are computed exactly as in Step 2.

Review-rework (priorPhase is code-review)

A reviewer requested changes. Address them.

1. Refresh the worktree. Stacked issue (stackBlockedBy present): run redqueen stack setup "${issueId}" instead of the commands below — merge-based, absorbs ancestor updates, never rebases; on exit 2 resolve the conflict as in Step 3. Non-stacked:

   git -C "${worktree_path}" fetch origin "${bare_base}"
   git -C "${worktree_path}" rebase "${baseBranch}"
   

2. Fetch the latest review and read its body (the reviewer's report, with a ## Critical Issues (Blockers) section):

   redqueen pr reviews "${prNumber}" --latest
   

3. For each blocker, do exactly one of:

   • Fix it (the default) — make the change the reviewer asked for.
   • Push back — only when the blocker is wrong: it demands defensive code for a case that cannot occur, a hypothetical-future abstraction, or a style change that contradicts .redqueen/references/coding-standards.md or CLAUDE.md. Never silently ignore a blocker.

   Apply non-blocking improvements only when quick and clearly correct.

4. If you pushed back on anything, post one PR comment summarizing it so the next review pass and the human gate see your reasoning:

   cat <<'EOF' | redqueen pr comment "${prNumber}"
   ## Rework response
   Addressed: <blockers fixed>.
   Pushed back: <blocker> — <why>.
   EOF
   

5. Build, test, commit, and push as in Steps 5–7. Do not create a PR.

6. Your stdout summary: blockers fixed, blockers pushed back, build + test status. Exit 0.

Test-rework (priorPhase is testing)

Tests failed in the tester phase. Reproduce locally — your local run is authoritative — then fix.

1. Refresh the worktree (same as Review-rework step 1, including the stacked-issue conditional).

2. Re-run the build and targeted tests locally:

   • Build: module.buildCommand if module is non-null, else buildCommands.
   • Test: module.testCommandTargeted ?? testCommands.

   The failure the tester reported should reproduce. Failures that reach you are real and reproducible — the tester routes infrastructure and flaky failures to Blocked, not to coding.

3. Fix the cause. Re-run build + targeted tests until both are green.

4. Commit and push as in Steps 6–7. Do not create a PR.

5. Your stdout summary: what failed, what you changed, build + test status. Exit 0.

Blocked path

Trigger Blocked when:

• Git conflict you cannot resolve mechanically (e.g. incompatible parallel changes on baseBranch).
• Build or test failure that depends on infrastructure (missing migration, environment variable, external service).
• Spec contradicts itself or reality (a named file does not exist, an unchangeable constraint blocks the approach).

Steps:

1. Post the block reason to the tracker. Pipe the body via a heredoc so it is never empty — redqueen issue comment rejects an empty body, and this comment is the only place the human sees why the ticket is blocked. Use the same reason text you put in your stdout summary:

   cat <<'EOF' | redqueen issue comment "${issueId}"
   Blocked during coding.
   
   What I completed: <concrete list>.
   What blocks: <specific cause>.
   What is needed: <what the human must do>.
   EOF
   

2. If a PR exists, also redqueen pr review <prNumber> --verdict request-changes with the same text so the human sees it from either place.

3. Move the issue into the Blocked human-gate so the orchestrator stops advancing the pipeline and assigns the reporter. Exit non-zero on failure so the orchestrator doesn't advance normally:

   if ! redqueen issue set-phase "${issueId}" blocked; then
     echo "Could not route to blocked — summary: phase-change failed"
     exit 1
   fi
   

4. Exit. Include "Blocked — " in your stdout summary.

Important rules

• Always work in the worktree, never the main project directory.
• The spec is your single source of truth — implement exactly what it says.
• If you deviate from the spec, note the deviation in the PR body.
• Do not modify files outside the scope the spec defines.
• Do not commit secrets, generated artifacts, or unrelated fix-ups.
• Standard markdown only in tracker output. PR bodies and tracker comments render as markdown. Use backticks for inline code, fenced code blocks, **bold**, - bullet, [text](url). Never emit Jira wiki syntax like {{text}}, {code}…{code}, or h1..