address

name	address
description	Drive one unit of work — a GitHub issue, a pull request, or a free-form prompt — from intake to a review-ready pull request in one continuing session; plan and pause for human approval, implement and verify, request the independent review, and address its findings. `continue` resumes a paused run or takes over a /handoff package.
when_to_use	Invoke when the human asks to deliver a unit of work end-to-end through the plan, code, review delivery loop — "address issue 42", "deliver this", "pick up PR 57" — or to resume one with `continue` (approving a paused plan, restarting a stuck tail, or taking over a handoff package in a fresh session). Do not invoke for quick questions, small ad-hoc edits, or reviews that do not need the full delivery workflow.
argument-hint	<issue-or-pr number/URL | free-form prompt | continue>
user-invocable	true

You are the /address driver. Take one unit of work — a GitHub issue, a pull request, or a free-form prompt — from intake to a review-ready pull request inside this single continuing session.

Target: $ARGUMENTS

Make all GitHub reads and writes per the project's GitHub operation guidelines: the built-in mcp__github__* tools, acting as the operator @axross, with a <!-- address-agent --> marker on every comment you post so /address continue never mistakes your own output for human input. Follow the project's development guidelines and the Response Approach workflow inside every phase.

Execution Model

You are the only long-lived actor. Advance the work as far as you can autonomously within each phase, and stop the turn whenever the next step needs a human. (A fresh-session take-over is not a resume — it creates a run from a handoff package, then follows this same model; see Take Over a Handoff.) A stopped run is resumed by one of:

• A machine event that completes on its own — CI, or the independent review this flow requests (see Independent Review). Schedule your own wake-up with send_later and poll until it resolves (see CI and Review Tail); only when a machine event is stuck do you record state, end the turn, and wait for /address continue.

• The mandatory plan-approval gate — after the plan is written the run always stops for the human to verify it before any implementation (see Phase 1). Record the plan in the issue, mark the status block awaiting plan approval, end the turn, and wait; the human resumes by sending /address continue in this same session once the plan checks out.

• A human decision with options — a Phase 1 must-ask clarification, an ambiguous review finding, or a conflict judgment call — asked inline through the dedicated question UI, with the answer returned in the same turn (see Asking the Human). A question-tool error is not a reason to end the turn: re-present the decision in text and ask again, holding for the human.

• MUST poll autonomously ONLY for machine events (CI, the review workflow); never keep a session alive polling for a human.

• MUST stop the turn and wait for /address continue at the plan-approval gate, and whenever a machine event is stuck; resolve every other human decision inline through the question UI, re-presenting and asking again if it errors (see Asking the Human). Never schedule a wake-up to re-check for human input.

• MUST clear the Phase 1 clarify-before-building gate before writing the plan, and the mandatory plan-approval gate before implementing: surface every spec ambiguity that needs a human decision and get it answered, and get the finished plan approved, rather than coding against an unstated assumption or an unreviewed plan.

• The running session is the primary state store; a run resumes with its context intact. Write durable status to GitHub as a safety net (see GitHub as Lightweight State), not as the mechanism of record.

• Keep each externally observable step idempotent, so a re-run of /address continue re-reads state and continues rather than duplicating work.

Asking the Human

Every human-gated decision with options in this flow — a Phase 1 must-ask, an ambiguous review finding, a conflict-resolution judgment call, or a take-over decision (which package, a zip↔inventory mismatch, a diverged precondition) — is asked through the AskUserQuestion tool where the session supports it: Claude Code's dedicated question UI renders your options as selectable choices in the chat and returns the answer inline, so the run continues in the same turn instead of ending. (The mandatory plan-approval gate is not one of these — it is a full plan the human reads and verifies at their own pace, so it ends the turn and waits for /address continue rather than asking through the question UI; see Phase 1.)

• MUST prefer AskUserQuestion when it is available: frame the decision as concrete options (2–4), state the default you would otherwise take and mark it recommended, and rely on the tool's built-in "Other" choice for anything unanticipated. Never bury a decision in prose or silently assume an answer.
• AskUserQuestion needs no settings permission — no allow-list grants it, so a closed or errored call is not proof the surface lacks the UI. On a remote or cloud session the permission stream can close transiently — no client was synchronously attached at that instant — even though the human is reachable and will answer once you ask again. The harness returns the same error for that transient case and for a genuinely headless run with no human, so you cannot tell them apart from the error alone: MUST NOT diagnose the client surface, or assert the UI is unavailable, from a single stream-close. Treat the error as a signal to re-present and ask again (next bullet), never to route around the human.
• MUST, when the AskUserQuestion call errors (or a synchronous answer is otherwise unavailable), re-present the decision and wait — never route around the human. Show the decision in plain text first — background, the question, and the numbered options with the recommended default marked — then call AskUserQuestion again with those same options and hold for the answer. Do NOT post a marked GitHub "decision recorded here" comment, and do NOT end the turn as if blocked-with-a-breadcrumb. This holds whether or not the run is anchored yet: before any GitHub thread exists (e.g. a pre-anchor take-over question), state the question in the turn output and wait just the same. A closed or errored stream means re-present and wait, not fall back and end the turn.
• MUST make that plain-text presentation offer the same options, in the same order, with the same recommended default as the AskUserQuestion call. Numbering that drifts between the text and the tool ask would map a bare answer token (e.g. 2) to a different branch with no error — so mirror the ask exactly.
• MUST, on the next turn, reconcile a bare answer — an option number, an option label, or free-form Other text — against the still-open question, mapping it to the options shown in that plain-text presentation rather than reading it as a new instruction or a reason to restart the run. A transiently-closed stream often means the human's answer arrives on the following turn; treat that answer as the response to the pending decision and continue from where the run paused.
• MUST keep the run's status block (see ) current with any open question — the decision and its options — so a session reclaimed mid-wait can recover and re-present it. This breadcrumb records state for a reclaim; it is not a fallback channel for answering, and it does not replace re-presenting the question in-session.

Argument Resolution

Resolve $ARGUMENTS first, then enter the matching phase.

Argument	Meaning	Entry
Issue number / URL	Plan and deliver the issue	Plan
Pull request number / URL	Resume delivery of an open pull request	Address / tail
Free-form prompt	Ad-hoc task with no issue yet	Open a tracking issue, then Plan
continue (bare token)	Resume the in-session run — or, when there is none, take over a human-provided /handoff package	Three-way precedence below: resume, Take Over a Handoff, or ask

• For a free-form prompt, open a tracking issue capturing the request before planning, so the run is issue-anchored and /address continue can reconstruct it.
• continue matches the bare token only; an argument that merely starts with the word (e.g. continue the migration work) is a free-form prompt. For bare continue, MUST resolve the invocation to exactly one of three outcomes — in this precedence order, before any other action:
  1. This session holds an /address run (paused at the plan-approval gate, paused on a stuck machine event, or reclaimed with its context thinned) → resume it: re-read the target's current state — the plan recorded in the issue, the open pull request, its CI status, the independent review's comments, unresolved threads, and the run's status block — before acting, and resume the single pending step rather than restarting. When the pending step is plan approval, treat the bare continue as that approval and proceed to Code (if the human instead requested changes, revise the plan and re-present it for approval). A handoff package already ingested by this session is part of that run — MUST NOT re-ingest it.
  2. No in-session run, and the human provided a handoff package this session (handoff-<unix epoch>.md, optionally with a matching zip) → enter Take Over a Handoff.
  3. Neither → state that there is nothing to resume and ask what was meant (see Asking the Human). MUST NOT start new work from a bare continue.
• Run full-auto within each phase, but two gates always stop the run for the human before Code: the Phase 1 clarify-before-building gate (unresolved product, UX, scope, or edge-case decisions, asked inline) and the mandatory plan-approval gate after the plan is written (end the turn, wait for /address continue). See Phase 1. Never proceed to Code on an unstated assumption or an unapproved plan.

Take Over a Handoff

The /handoff skill suspends another session's in-progress work into a self-contained handoff-<unix epoch>.md document plus an optional same-epoch handoff-<unix epoch>.zip of supporting files (the package contract is defined there). When /address continue runs in a fresh-context session with such a package, this section rebuilds the suspended state and hands the work to the normal phase flow — the handoff document replaces the session context that an in-session resume would have had.

Locate and ingest the package

• Find the handoff document the human attached or uploaded to this session. A package merely found on disk — especially one tracked by git, which the wrap-up rules in the /handoff skill forbid committing — is NOT the human's package: MUST confirm it with the human (see Asking the Human) before ingesting it. When several candidates exist, propose the newest epoch and confirm the choice; when none is found, ask the human to provide it — MUST NOT guess or reconstruct a handoff from thin air.
• MUST read the entire document before taking any action. Extract the companion zip (matching epoch) into a scratch location outside the repository checkout, verify its inventory there, and apply entries deliberately per the document's Precondition section (patches via git apply / git am, other files copied individually) only after the Verify preconditions gate below clears — never unzip directly into the working tree.
• MUST check the zip's contents against the document's Precondition inventory and treat any mismatch — a missing entry, an unexpected extra — as a question for the human (see Asking the Human), never something to silently ignore.

Verify preconditions

• MUST verify every item in the document's Precondition section against reality — right repository and branch, expected HEAD, patches apply cleanly, tools and environment available — and resolve, or have the human waive, every divergence BEFORE the first repository mutation.
• When state has diverged — the branch moved, a patch conflicts, a required credential is missing — surface the divergence and ask how to proceed (see Asking the Human) rather than forcing a resolution.

Resume the work

• Adopt the document's Goal as the success criteria and its Concerns and/or blockers as live risks.
• Trust - [x] items as done — spot-check cheaply where practical, but do not redo them — and resume at the first - [ ] item, using History/transition to avoid re-treading recorded dead ends.
• MUST report a short takeover summary — what the handoff says, what was verified, and the plan — before editing anything, so the human can catch a misreading early.
• Then re-enter the normal flow: when the handoff names a GitHub issue or pull request, resume the phase matching the work's current state (Plan, Code, Address, or the CI/review tail); when it names none, search for an existing tracking issue first (the predecessor may have opened one without recording it in the package), and only then open one capturing the handoff's Goal and remaining to-dos — the same issue-anchoring as a free-form prompt — and continue from there. From this point the run is ordinary /address work: follow the project's development guidelines, the Response Approach workflow, and every skill whose routing condition matches the surface being changed. If the takeover lands before or during Plan, the mandatory plan-approval gate still applies.
• Once anchored to an issue or pull request, MUST create or update the status block (see GitHub as Lightweight State) recording the takeover — the package epoch, the verified HEAD, and the to-do resumed — so a later resume, or a second would-be successor, can see the package was already consumed. MUST treat an existing takeover record for the same epoch as a stop-and-ask (see Asking the Human), never a second takeover.

Phase 1 — Plan

Turn the target into a buildable specification recorded in the issue.

• Read the issue (or the tracking issue opened for a prompt) and its full thread, classify the work — UI-bearing, implementation-only, exploratory, or mixed — per the Response Approach, and investigate the smallest useful code and documentation context before proposing a plan. Consult every project skill whose routing condition matches the surface, and research current external docs per the project's development guidelines (current-docs lookup rules) when behavior depends on Next.js, React, Vercel, Playwright, Vitest, or Biome.

• Clarify before building — required gate. Investigation resolves how to build; it does not resolve what the product should do. Before finalizing the plan and entering Code, list every open question the spec leaves and sort each one:

  • Settle-and-note — anything code, project conventions, or docs can answer: decide it and record the choice as a stated assumption in the plan.
  • Must-ask — anything needing human judgment: a product outcome, a UX or interaction choice, a scope boundary or non-goal, empty/error/edge-case behavior, a data-model or persistence/migration decision, or anything privacy-, platform-, or compatibility-sensitive that the issue and its thread do not pin down.

  If any must-ask question remains, you MUST NOT start implementing — ask them through the dedicated question UI (see Asking the Human), each framed as options with the default you would otherwise assume marked recommended, then use the answers to finalize the plan. Ask only genuine spec gaps, never what local investigation already answers; but when a detail is genuinely ambiguous, asking is required, not optional. Prefer batching related questions into one prompt over dribbling them out across rounds.

• Rewrite the issue body into a comprehensive plan with these sections, omitting any that genuinely do not apply and saying why, per the project's product-requirement guidelines: (1) Product requirement — the user-facing outcome and constraints; (2) UI design — hierarchy, states, responsive and accessibility intent, and copy constraints, when UI-bearing (per the project's React guidelines); (3) System design / architecture — data flow, state, routes, module placement, when applicable (per the project's project-structure guidelines); (4) Testing strategy — the E2E and unit coverage to add or update (per the project's end-to-end testing guidelines and the project's unit-test guidelines); (5) Acceptance criteria — a plain bullet list (not GitHub - [ ] checkboxes, which nothing checks and so read as perpetually incomplete) the reviewer can verify against the finished pull request.

Phase 2 — Code + Verify

• Choose the working location before touching files. In a Claude Code cloud environment the session already runs in an isolated, ephemeral checkout, so implement directly — a separate worktree would add nothing. Anywhere else (a local session sharing the human's working tree), implement on a separate git worktree so the run never blocks the human's own working copy — the one exception is when the human explicitly asked to work in the current (non-worktree) checkout. Either way, work on a claude/issue-<n> branch; never push to main.
• Implement strictly from the approved plan, keeping edits within the smallest surface that satisfies the acceptance criteria.
• Follow every project skill whose routing condition matches the changed files, and add or update the E2E and unit coverage the plan named.
• Run the verification the changed surface requires — npm run format and npm run lint after any edit; npm run typecheck for type or signature changes; npm run test:unit, and npm run test:e2e for UI-output or e2e-coverage changes; npm run build for route, metadata, runtime-config, dependency, or signature changes — per the project's development guidelines (verification requirements), and record the evidence in the pull request body.
• Do a reviewer-mode reset and fix obvious Critical/Major issues before opening the pull request (a self-check to avoid trivial hand-backs per the project's code-review guidelines); this is NOT the authoritative review — that is the independent reviewer in Phase 3.

Phase 3 — Request Independent Review

Review is not done by you. It runs as a separate Claude Code session on a GitHub-hosted runner — different session, different infrastructure, a bot identity distinct from the operator — via the claude-review.yaml workflow, which runs the repo's code-review practice (REVIEW.md). That separation is the whole point: the code's author never certifies its own work.

• Open the pull request in draft with Closes #<n>, structured from any repository PR template, summarizing the change, the verification evidence, and the acceptance criteria with their status. Seed the run's status block into the description as an HTML comment at the same time (see GitHub as Lightweight State).
• Request the review by posting a top-level comment whose body is exactly @claude review (plus the <!-- address-agent --> marker line) — nothing else. This fires the review workflow, which submits its findings as a GitHub pull-request review — inline comments anchored to the diff, tagged by severity, with a summary — not as loose conversation comments. Do not repeat the phrase in the status block or any other comment (see GitHub as Lightweight State), or you will fire duplicate reviews.
• The review is a machine event that completes on its own in minutes — poll for it in the tail alongside CI. Do NOT review the diff yourself in place of it.

Phase 4 — Address

• When the independent review's comments land, read them (their author is the review bot, not you and not a human) together with merge-checks CI status.
• Address and resolve each blocking finding (Important / Critical / Major) and every unmet acceptance criterion, pushing fixes to the same branch and re-running the relevant verification after each batch.
• For every review comment a commit resolves, reply on that comment's thread with a marked comment (the <!-- address-agent --> marker line, then a line beginning Resolved in <short-hash> — the 7-character hash of the commit that fixed it — followed by a one-sentence summary of what changed), then resolve the thread. When one commit resolves several comments, reference that same hash on each. This ties each resolution to the exact commit for the reviewer and for /address continue. (These review-thread replies are the run's only comments besides the review request — they are not status or attention pings.)
• Re-request review by posting @claude review again after a batch of fixes, and repeat up to the 8-round cap (see Termination Guard).
• Keep the branch mergeable into its base. When the base branch has moved and the pull request conflicts (GitHub marks it not mergeable, or an update/rebase fails), bring main into the branch and resolve the conflicts, then re-run the verification the touched surface requires and note it in the pull request. Resolve mechanical conflicts yourself — imports, independent or adjacent edits, regenerated lockfiles — but when the correct resolution is genuinely unclear (both sides changed the same logic on purpose, or keeping both sides matters and how to reconcile them is a judgment call), ask @axross how to reconcile it through the dedicated question UI (see Asking the Human) rather than guessing.
• Escalate through the dedicated question UI (see Asking the Human) when a finding or human comment is ambiguous or needs a product or architecture decision, rather than guessing.
• Gate the draft→ready flip on a clean independent review (no blocking findings) plus green CI — never on your own assessment of your code. On convergence, flip the pull request to ready for review, update the status block, and state the ready-for-review outcome in the turn output. Merging remains the human's decision.
• When a human leaves comments on a ready pull request, treat /address continue as the resume: re-read the new threads, address or escalate each, convert back to draft if needed, request a fresh @claude review, and re-enter this loop as a new round.

CI and Review Tail

After you push and request review, two machine events run on their own: merge-checks CI (.github/workflows/merge-checks.yaml: lint + unit tests) and the independent review (claude-review.yaml). Poll for both — nothing wakes this session when they finish, so schedule a wake-up with send_later (the claude-code-remote MCP server), which delivers a message back into this same session and survives container reclaim.

Cadence. The prompt cache has a ~5-minute TTL, so a wake-up under five minutes resumes cache-warm and cheap; one past it pays a full cache miss. send_later is minute-granular, so the closest warm value is four minutes — five is the worst choice, paying the cache miss without buying a longer wait.

• Poll at a 4-minute cadence (delay_minutes: 4) for the first ~15 minutes, then back off to a 10-minute cadence while still pending.
• MUST stop autonomous polling after 2 hours with no result — a check still pending at two hours is stuck or badly queued and needs a human. On the cap, update the status block to note what is stuck, state it in the turn output, and end the turn; the run goes dormant until /address continue.
• Reset the 2-hour budget when a check produces a result and a new push or @claude review starts a fresh run; the cap governs a single uninterrupted wait, not the run's whole lifetime.
• On green CI plus a clean review, flip the pull request to ready, update the status block, state the outcome in the turn output, and end the turn. On review findings or red CI, enter Address (Phase 4). On only some checks resolved, keep polling for the rest.

GitHub as Lightweight State

State lives in this running session; GitHub carries a thin, human-invisible breadcrumb so a resumed or reclaimed session can recover. The run posts no status or attention comments — the only comments it authors are the dedicated review request (Phase 3) and the marked review-thread replies that tie each resolved finding to its commit (Phase 4).

• Keep the run's state in a single status block: an HTML comment (<!-- ... -->) embedded in the pull request description — invisible in the rendered GitHub UI, present in the raw markdown. Before the pull request exists (Plan phase, or a handoff take-over anchored only to an issue), keep the same block in the issue body. Record the current phase, the review-round count, what the run is waiting on, and any open question. Update it in place when you edit the description or issue body; never post a separate status comment, and never @mention the maintainer for attention — convey ready-to-merge, dormancy, and non-convergence in the turn output instead.
• Never write the literal @claude review phrase in the status block or any comment other than the dedicated review request — the review workflow fires on that phrase appearing anywhere in a comment body, so embedding it even in prose spuriously starts a review (and muddies the run). Refer to it as "the independent review" everywhere except the request itself, per the project's GitHub operation guidelines.
• On an in-session /address continue resume, reconstruct state from GitHub before acting — the plan in the issue, the open pull request, its CI status, the independent review's comments, unresolved threads, and the status block — and resume the one pending step the block names, not restart from Plan. (A fresh-session take-over reconstructs from the handoff package instead — see Take Over a Handoff.)
• Labels are optional and purely informational; the run does not depend on a label state machine.

Termination Guard

• Cap the address↔review loop at 8 rounds; on non-convergence, record what still fails in the status block, state the summary in the turn output, end the turn, and wait for /address continue.
• Cap autonomous polling at 2 hours per wait and go dormant rather than poll indefinitely.
• End the turn (never loop-block) whenever waiting on a human — the plan-approval gate, a stuck machine event, or a dormancy cap — so an idle run consumes nothing.

Project Skills to Follow

/address orchestrates existing project skills; it does not restate their rules. Beyond the phase links above, follow the project's GitHub operation guidelines for every GitHub read/write, and the verification the changed surface requires per the project's development guidelines (verification requirements). The independent reviewer applies the project's code-review guidelines in its own session; you consult it only for the Phase 2 self-check. Keep edits to the smallest surface that satisfies the acceptance criteria; never push to main; never merge the pull request.