Issue implementer

Issue Implementer

This is the implementation half of the workflow. Planning (the issue-planner skill) has already produced and the human has approved a plan for each issue you handle here. You (the main session) are the orchestrator: you delegate code-writing to the implementer subagent (agents/implementer.md), one dispatch per issue. After it completes and the mechanical checks pass, a verifier subagent (agents/verifier.md) adversarially reviews the diff against the plan and acceptance criteria before anything is pushed or a PR exists — failures are kicked back to the implementer (max 2 kickbacks), so the PR the human reviews is already verifier-clean.

This skill is project-agnostic: conventions, the verification commands that define "done", how dependencies are installed, and schema/migration rules all come from the repo's CLAUDE.md, read by the subagent at the start of every task (see the plugin README's "CLAUDE.md contract"). The end state for each issue is an open PR awaiting review — the merge boundary is stated once under "Hard rules" below.

Labels involved

• plan-approved — the trigger. Set by the human after reviewing the plan.
• pr-open — set by this skill once a PR is open (removes the issue from the queue).
• impl-blocked — set by this skill if implementation hits a blocker (removes it from the queue; the human removes this label to retry).

Hard rules

• Sequential by default. In the shared working tree, never dispatch more than one implementer subagent at a time — they would corrupt each other's work. The ONLY exception is "Worktree-parallel mode" below (full mechanics in references/worktree-mode.md).
• Never merge in this skill and never push to the default branch. One issue → one claude/<n>-<slug> branch → one PR. Merging belongs to the human — or, where CLAUDE.md defines a merge autonomy policy and the human has lifted the default gh pr merge deny, to the issue-cycle skill's merge pass, the sole place any harness merge authority exists.
• The subagent writes code; you do every git and gh command. This holds after a verifier fail and after red CI, too: you never edit a source, test, or doc file yourself to resolve a finding or a CI failure — you re-dispatch the implementer (step 2e), and once the kickback budget is spent, the issue takes the blocked path (step 2f). Your own edits are harness bookkeeping only — .claude/LESSONS.md, the PR body, and issue comments.
• A dirty working tree is only recoverable when it's clearly the harness's own — step 0 has the full rule; never risk clobbering uncommitted human work.
• No Bash command may wrap another command's output inline (backticks or dollar-paren substitution) — the permission matcher can't approve a composite like that, so under an unattended session it degrades silently instead of failing loudly. Run the inner command on its own, then paste its literal result into the next call (step 2e's collapse is the worked example).

Resilient dispatch

Every subagent dispatch in this skill — and, by citation, in issue-planner and issue-cycle — follows this contract, defined once here.

Retry ladder

Attempt 1 is the initial dispatch. On a retryable failure, back off and retry: 30s → attempt 2; 60s → attempt 3; 120s → attempt 4; 240s → attempt 5. After attempt 5 fails, STOP retrying — escalate the stage as failed into the run report (issue number, stage, attempts used, last error); never advance to the next issue without a recorded row. Use sleep <seconds> for the wait; if sleep is denied, perform at most ONE immediate retry, then escalate with "backoff unavailable — grant Bash(sleep:*)".

Retryable: a tool-level dispatch error; an API 429/500/529; a dispatch that returns nothing or no parseable report — including a transient subagent death: re-dispatch per the ladder, not as a special case; only repeated identical deaths through attempt 5 become the escalation above.

Not retryable — different paths: a well-formed status: blocked report (the blocked path, step 2f) or a verifier fail verdict (the kickback loop, step 2e, its own max-2 limit). The ladder never composes with the kickback loop into more than 3 implementer attempts per verification round, plus the ladder's own retries within each attempt. State the attempt number in every dispatch prompt ("Dispatch attempt: <k>", starting at 1) so the subagent's echoed status line carries the right retries value.

Status line

Every planner, implementer, and verifier report ends with one machine-readable line:

<!-- harness-status: stage=<planner|implementer|verifier|merge> issue=<n> outcome=<slug> retries=<k> [deploy=<verified|pending|failed>] -->

• stage — the pipeline stage (merge has no agent; the orchestrator emits its line directly — see issue-cycle's merge guards); issue — the GitHub issue number.
• outcome — per-stage vocabulary: planner plan-posted|plan-revised|incomplete|died; implementer complete|blocked|incomplete|died; verifier pass|fail|incomplete|died; merge merged|merge-blocked|not-eligible|merge-unconfirmed.
• retries — k-1, where k is the dispatch attempt number stated in the prompt; agents echo it back, defaulting to 0 when the prompt is silent.
• deploy — optional, valid only with stage=merge: emitted by the cycle's merge pass when the repo declares post-merge verification (issue-cycle's merge-pass guard (e)), values as in the grammar line above.

The orchestrator emits this line itself, on the stage's behalf, whenever a stage died or never reported, and always for merge — keeping issue-cycle's ledger reconciliation checkable.

WIP checkpoint vocabulary

All checkpoints keep the wip: prefix so branch classification (step 2b) stays a simple grep:

• wip: checkpoint <stage> (#<n>) — a stage-boundary checkpoint (after the implementer returns complete, after each kickback round, after the CI-fix dispatch).
• wip: <stage> died (#<n>) — a hard death: the retry ladder exhausted with no usable report.
• wip: context exhausted (#<n>) — a clean early exit (status: incomplete).
• wip: interrupted run (#<n>) — pre-flight crash recovery (step 0).
• wip: blocked — <short reason> (#<n>) — the blocked path (step 2f).

Classification rule (used by step 2b): when every unique commit on a claude/<n>-* branch is a wip: commit, look at the newest one. Newest = wip: blocked — … → reset fresh. Newest = anything else (checkpoint, died, context exhausted, or interrupted run) → resume: the branch carries real, preserved partial work and must be continued, not discarded.

Invariant this rule depends on: a blocked branch always ends with a wip: blocked — … commit, never a leftover checkpoint/death/exhausted one — step 2f guarantees this via an empty commit rather than silently skipping, even over an already-checkpointed tree. Preserve this on any future change to step 2f's commit, or a blocked branch would misclassify as resume.

Death / incomplete-exit checkpoint and resume brief

Whenever a dispatch dies with no usable report, or returns status: incomplete, the orchestrator WIP-commits the tree before doing anything else — git add -A && git commit -m "wip: <stage> died (#<n>)" or ... "wip: context exhausted (#<n>)" respectively (skip if nothing changed) — then builds a resume brief and relaunches, bounded by a cap.

A resume brief has exactly five elements: issue number, branch, last WIP commit SHA, what was completed, and what remains. Clean exit — copy the agent's own ## Resume brief section verbatim, plus the WIP SHA just created. Hard death — reconstruct it: git diff <default-branch>...<wip-sha> --stat lists the files touched; walk the plan's Implementation steps and Affected areas against that list to infer "completed" vs. "remains", labelled best-effort so the implementer re-checks rather than trusts it.

Relaunch instruction (verbatim, adapted per stage): "This branch already contains partial work from a previous attempt at commit <sha>. Continue from it — do not revert it, do not redo completed steps, and do not restart the stage from scratch." For the planner and verifier stages there is no commit to checkpoint: the orchestrator retains the last completed artifact instead — the prior <!-- planner-plan --> comment, or the prior verdict — relaunching with it as the resume brief and adapting the instruction to "this plan/verdict is partial — continue it, do not restart."

Cap: at most 2 resume relaunches per issue per run (3 implementer contexts total), independent of the 2-kickback limit. Exceeding it routes to the blocked path (step 2f) — the work is preserved either way.

Procedure

0. Pre-flight (once, before any issue)

gh auth status                 # must be authenticated
git status --porcelain         # see the dirty-tree rules below
git fetch origin

Determine the repo's default branch (e.g. via gh repo view --json defaultBranchRef); use it everywhere this doc says "the default branch".

Dirty tree → crash recovery or stop. If git status --porcelain is non-empty (ignoring .claude/LESSONS.md, harness bookkeeping):

• On a claude/<n>-* branch → a previous run died mid-issue. Recover mechanically: git add -A && git commit -m "wip: interrupted run (#<n>)", comment on issue <n> that a previous run was interrupted and work is preserved, check out the default branch, and continue — do NOT label impl-blocked; step 2b's classification rule resumes or resets it. Note the recovery in your summary.
• Anywhere else → STOP and tell the user. That's uncommitted human work; never yours to move.

Stale worktrees → sweep, before the hygiene run below (a stale worktree can block cleanup-after-merge.sh from deleting a merged branch it still holds), in both modes:

git worktree prune                # forget registrations whose directory is gone
git worktree list --porcelain     # what is still attached, and to which branch

For each surviving worktree named <repo-dirname>-wt-<number> (the name step b of references/worktree-mode.md's Swarm procedure creates): if git -C <path> status --porcelain is non-empty (needs the v1.8.1 -C grants — see that file's step e), preserve the work — git -C <path> add -A && git -C <path> commit -m "wip: interrupted run (#<number>)" — comment on the issue that its worktree was cleared and anything committed remains on the branch, then git worktree remove <path> (--force over untracked/ignored files like node_modules; tracked work is already committed). A path that is not one of ours is never yours to remove — leave it; if it holds a branch this batch needs, skip that issue and tell the human. Report every sweep in the summary.

Sync & hygiene: run cleanup-after-merge.sh --fix (fast-forwards the default branch when checked out — check it out first if you aren't on it and the tree is clean; prunes merged claude/* branches; repairs stale pr-open labels with audited comments).

Baseline refresh. Read .claude/BASELINE.md (machine-local: a - commit: line with the last known-green default-branch SHA, plus per-command results). If missing, warn the user to run the harness-setup skill and proceed — CLAUDE.md's verification commands still apply. If the default branch tip now differs from the recorded commit, re-establish it before implementing anything: on the clean default branch, run the project's verification commands from CLAUDE.md.

Green → rewrite .claude/BASELINE.md with the new commit SHA, today's date, and each command's outcome (e.g. "pytest: 631 passed"). Red → STOP the whole run and report prominently; fixing main is the human's call.

Then install dependencies using the project's setup command from CLAUDE.md (e.g. pnpm install); skip if the project has no dependency step.

1. Find the work

Run find-implementation-work.sh (on PATH via the plugin's bin/) — returns JSON { ready: [...], counts: {...} }. Report the ready issues to the user (number + title). If empty, say so and stop.

2. For each ready issue, IN SEQUENCE

a. Fetch the issue and its approved plan (gh issue view <number> --json number,title,body,url,comments). Find the latest comment containing the <!-- planner-plan --> marker — the approved plan. If none, skip and warn (labelled approved but has no plan). Also read every comment posted after the plan: human comments there are binding context — restate them as RESOLVED: decisions below; machine-posted comments opening with <!-- verifier-verdict --> are the orchestrator's own archive (step 2e), never binding human context. If one contradicts the plan outright, treat the issue as mislabelled and ask the human instead of dispatching.

b. Branch off a fresh default branch:

git checkout <default-branch>
git pull --ff-only

Build a slug from the title (lowercase; non-alphanumerics → hyphens; trim; ~40 chars max), then git checkout -b "claude/<number>-<slug>".

If a claude/<number>-* branch already exists, decide by what's on it (git log <default-branch>..<branch> --format=%s), applying the classification rule from "Resilient dispatch":

• Every unique commit is a wip: commit, and the newest is wip: blocked — … → leftovers of a blocked attempt (findings live in the issue's comments — carry them in). Delete it (git branch -D <branch>) and create the branch fresh. Say so in the summary.
• Every unique commit is a wip: commit, and the newest is anything else → resume: git checkout "claude/<number>-<slug>" (do NOT delete or recreate it), capture the WIP SHA (git rev-parse HEAD), build the resume brief per "Resilient dispatch", and dispatch the implementer with it, carrying forward the issue's prior-attempt comments too. Do not rebase or re-cut the branch. If checkout fails because the branch is checked out in another worktree, sweep it per step 0's stale-worktree sweep, then retry. Say so in the summary.
• Any non-wip commit → real prior work. If an OPEN PR exists, skip and warn (the pr-open label was probably removed by mistake). Otherwise stop and warn — reusing or discarding committed work is the human's call.

c. Dispatch the implementer subagent (Task tool). It starts from a fresh context and sees only what you send, so the prompt must carry every decision and verified fact — it should never exercise design judgment or re-derive codebase facts. Include:

• the issue number, title, and body;
• the full approved plan, including its "Verified facts" section;
• resolved answers to ALL open questions — the human's answer for each BLOCKING question, and each ADVISORY question's accepted default (or override), restated as RESOLVED: decisions, not questions (plan-carried RESOLVED (orchestrator-proposed): items pass through as-is);
• relevant entries from .claude/LESSONS.md (if the project has one);
• the standing caveat "Line numbers and code excerpts in the plan are from when it was written — verify locally; if the code has drifted, trust the live code and note the drift in your report."
• the instruction "Implement this approved plan on the current branch following your process and constraints. Return your report."
• the dispatch attempt number ("Dispatch attempt: <k>", starting at 1). If a BLOCKING question has no answer anywhere in the thread, do NOT dispatch — treat the issue as mislabelled and ask the human. If the dispatch itself fails, retry per the "Resilient dispatch" ladder rather than treating it as a blocker.

Checkpoint on status: complete: before anything else, git add -A && git commit -m "wip: checkpoint implementer (#<n>)" (skip if nothing changed) — makes the verifier's diff (step 2e) non-empty and correct.

On status: incomplete or a hard death: checkpoint immediately, build the resume brief per "Resilient dispatch", and relaunch — bounded by the resume cap, consuming neither a kickback nor a ladder retry. Record the relaunch count for the summary table.

d. On status: complete: independently re-run the project's verification commands (from CLAUDE.md) as the authoritative gate — the subagent may be mistaken. If they fail, treat it as a blocker (step f). Compare against .claude/BASELINE.md: every check green at baseline must still be green, and counts must not drop without explanation (usually deleted/skipped tests — investigate; a legitimate drop must be explained by the plan or the report).

e. Dispatch the verifier subagent (Task tool, agents/verifier.md) — the semantic gate the mechanical checks can't provide, retried per the "Resilient dispatch" ladder if the dispatch itself fails. Its prompt must contain: the issue, the full approved plan (Acceptance criteria

• Verified facts + RESOLVED: decisions), the implementer's report, the dispatch attempt number, git diff <default-branch>...HEAD --stat (three-dot, from the merge base; non-empty because of step 2c's checkpoint), the declared autonomy reserve globs — pasted one per line from CLAUDE.md's ## Autonomy reserve fenced block, or the literal none declared — plus the plan's "Reserve touch list" (or that it has none), which feed the verifier's ## Reserve touch check, and "Verify this implementation against the plan and acceptance criteria following your process. Return your verdict."

• Verdict pass: archive it first, then carry it. Archive: gh issue comment <number> --body-file <tempfile>, whose temp file's first line is exactly <!-- verifier-verdict --> and second line is exactly <!-- verifier-verdict-branch: claude/<number>-<slug> --> (this PR's head branch, from step 2b — the key the merge floor matches on, so a multi-PR issue's slices don't shadow each other), followed by the verdict verbatim (including its closing status line). Do this after every verifier pass — this one and any CI-fix re-verification below, not just the first — because the merge floor matches the latest archived comment for this head branch against the PR body. Then carry its closing status line — verbatim — a Mutation probe: line carrying its ## Mutation probe content, and its "Notes for the PR reviewer" into the PR body's verification section, proceed to commit (next step).

• Verdict fail: kick back. Re-dispatch the implementer (per the ladder if the dispatch fails) with: the full approved plan, its own previous report, and the verifier's findings verbatim, plus "Fix ONLY these verification findings. Do not expand scope. Return your report." On return, checkpoint: git add -A && git commit -m "wip: checkpoint kickback (#<n>)" (skip if nothing changed). Re-run the mechanical checks and re-dispatch the verifier (include its prior findings so it confirms each is resolved). Maximum 2 kickbacks (3 implementer attempts total). Still failing → blocked path (step f), with the latest findings as the blocker explanation. Record verification rounds and ladder retries used for the summary table.

• Once the verifier passes, collapse this run's WIP checkpoints so the PR carries one clean commit instead of the checkpoint trail. Per "Hard rules", do this as two separate Bash calls, never one command with the merge base substituted in: first git merge-base <default-branch> HEAD, read the SHA from that call's result; then git reset --soft <sha> with the SHA pasted in as a literal. Reset to the merge base, not the default branch's tip (a resumed branch may be behind it — resetting to a moved tip would fold other people's commits in as a revert); reset --soft only moves HEAD, so the implemented tree stays fully staged. If the grants aren't available, skip it and add the feat: commit on top of the WIP trail instead (note it in the summary; squash-merging repos are unaffected).

  Stage and sanity-check before committing:

git add -A
git status --porcelain   # review this list

 Every staged path must be accounted for by the report's "Files changed" list (or an obvious
 consequence, e.g. a lockfile — `.claude/LESSONS.md` always counts). Unstage and investigate
 anything unexpected (`git restore --staged <path>`); if it can't be explained, treat the
 issue as blocked rather than commit files the report can't account for. Once clean, commit,
 push, open the PR, and label the issue:

git commit -m "feat: <concise title> (#<number>)"   # use the project's commit convention
git push -u origin "claude/<number>-<slug>"
gh pr create --title "<concise title> (#<number>)" --body-file <tempfile>
gh issue edit <number> --add-label pr-open

 The PR body (the temp file) must include: a one-paragraph summary; `Closes #<number>`; the
 files changed; the verification results; **the verifier's own closing status line, pasted
 verbatim — never one you compose on its behalf** —
 `<!-- harness-status: stage=verifier issue=<number> outcome=pass retries=<k> -->` — from the
 verdict that reviewed the **final** tree, after the last kickback (a kickback round's `fail`
 line is replaced, not appended — and so is a CI-fix round's fresh line below: never leave a
 superseded one in the body); a `Mutation probe:` line carrying that same verdict's
 `## Mutation probe` content (the `k/n killed; survivors: …` form, or its skip reason); the
 implementer's Evidence block condensed to its **Claims swept** and **Mutation checks**
 lines, copied from the report; any schema changes needing application; and the reviewer
 notes from the subagent's report. **Exception — a PR that delivers only part of an issue**
 (a deliberately multi-PR split): write `Part of #<number>` (plus `PR <k> of <m>` when the
 total is known) instead of a closing keyword, so `cleanup-after-merge.sh` leaves the issue
 open after this slice merges; only the PR that finishes the issue carries `Closes
 #<number>`. A human who plans the split up front can put `<!-- harness-multi-pr -->` in the
 issue body or a comment as the same opt-out.

 **File the plan's follow-ups.** File each entry whose justification names a concrete failure
 a user of this software would experience — `gh issue create --label no-auto-approve`, with
 the body opening `<!-- harness-follow-up: PR #<pr-number> -->`, then that justification
 quoted and a reference to this PR; then refresh the PR body: rewrite the body you composed
 above with the new issue numbers added, and apply it with `gh pr edit --body-file
 <tempfile>` — arg-less, from the issue's branch, resolves the PR from the branch, or pass
 the URL `gh pr create` printed if you're not on it — and note the numbers in your summary
 too. Nobody human wrote these, so the label keeps their plans out of auto-approval until a
 human removes it, and the marker is what `cleanup-after-merge.sh` matches to quarantine them
 if this PR is later closed unmerged. An entry whose justification names a capability wish or
 a drift risk nobody would notice rather than a concrete failure is yours to decline — don't
 file it; record the decline in the PR body (title plus one line of why) so the judgement
 reaches the reviewer instead of becoming an issue nobody triages.

 **Watch CI** so a red run doesn't sit unnoticed (`gh pr checks "claude/<number>-<slug>"
 --watch`); record the outcome (pass / fail / no checks configured) for the summary table.

 **Red CI → one bounded fix attempt** (as safe as the kickback loop; the PR isn't merged
 yet). Classify the failure first (`gh run view <run-id> --log-failed`):
 - **Caused by this PR** → re-dispatch the **implementer** (per the ladder if the dispatch
   fails) with the plan, its report, the failing log excerpt, and *"Fix ONLY this CI failure.
   Do not expand scope. Return your report."* On return, checkpoint: `git add -A && git
   commit -m "wip: checkpoint ci-fix (#<n>)"` (skip if nothing changed). Re-run the
   mechanical checks, re-dispatch the **verifier** (scope: the fix); once it confirms,
   archive its fresh verdict the same way as any other pass (above), then refresh the PR
   body — rewrite it with the fresh verdict's closing status line and `Mutation probe:` line
   replacing the superseded ones — and apply it with `gh pr edit --body-file <tempfile>`, so
   the body describes the tree the head commit actually carries. A permission-denied `gh pr
   edit` is never routed around: report it loudly in the run summary with the exact command,
   and flag the PR as needing a manual body update before it can qualify for autonomous
   merge. Amend the ci-fix checkpoint if one was created (`git commit --amend -m "fix: <what>
   (CI, #<number>)"`), otherwise commit empty instead (`git commit --allow-empty -m "fix:
   <what> (CI, #<number>)"`) — never amend the already-pushed `feat:` commit (force-push is
   denied, so the push would be rejected). Push — CI re-runs; watch again. **Maximum ONE
   CI-fix attempt per issue** (not counted toward the kickback limit). Still red → note it
   and let the human decide.
 - **Not caused by this PR** (infra flake, unrelated breakage, quota) → don't burn the
   attempt; note it and let the human decide.

 **Distill the lesson:** a gotcha the subagent couldn't have known, once traced, gets
 appended to `.claude/LESSONS.md` (1–3 lines, dated, as an instruction) and included in every
 subsequent dispatch this run. Then return to the default branch (`git checkout
 <default-branch>`).

f. On status: blocked (or failed mechanical checks, or a verifier fail that survived 2 kickbacks): do NOT push or open a PR. Preserve the work for inspection on a local branch, flag the issue, and reset the tree:

git add -A
if git diff --cached --quiet; then
  git commit --allow-empty -m "wip: blocked — <short reason> (#<number>)"   # tree was already checkpointed — empty commit still marks it blocked
else
  git commit -m "wip: blocked — <short reason> (#<number>)"                # local only, not pushed
fi
gh issue comment <number> --body-file <tempfile>            # blocker explanation (incl. verifier findings, if any)
gh issue edit <number> --add-label impl-blocked
git checkout <default-branch>

g. Move to the next issue (back to step 2a).

3. Summarise

Report a table: issue number, title, outcome (PR opened → link / blocked → branch name), verification rounds (1 = clean; 2–3 = kickbacks — say what the verifier caught), retries (ladder retries per stage, resume relaunches out of the cap of 2), CI status (pass / fixed after 1 attempt / fail / no checks), and any issues skipped and why — a stage with no recorded outcome is a gap to report, never a silent skip. This is the human-facing form of the dispatch ledger issue-cycle maintains across a full pass; build it the same way standalone. Also note: any crash recovery or wip-branch resume/reset (say which), whether the baseline was refreshed (and its new numbers), and whether discovery reported truncated: true (run again after this batch).

Worktree-parallel mode (optional)

When 2+ ready issues have approved plans with pairwise disjoint "Affected areas" (production AND test files, including shared fixtures like a conftest), you may implement them in parallel via git worktrees instead of sequentially, up to 4 implementer dispatches in flight. Any overlap, doubt, or plan missing an Affected areas section → sequential.

Before entering the mode, Read references/worktree-mode.md (it sits next to this SKILL.md) and follow it; do not attempt the mode from memory — it holds the supervisor loop, the swarm procedure, and every worktree-specific git command, all built on the budgets and vocabulary defined above in "Resilient dispatch". A sequential run never needs that file.

Notes

• After the human merges, or a PR is closed without merging: nothing manual is required — step 0's cleanup-after-merge.sh --fix and baseline refresh cover branch sync, stale pr-open label repair, and re-verifying merged main; step 2b's classification rule decides the old branch's fate. Running cleanup-after-merge.sh by hand is still fine (idempotent).
• Schema changes: if the subagent created one, the PR body must say so — it has NOT been applied to any database; applying it is a human step, per CLAUDE.md.
• Branch protection on the default branch (require a PR) is the real safeguard against accidental direct pushes; recommend it if missing. Commit messages follow whatever convention CLAUDE.md specifies (the feat: examples above assume Conventional Commits).