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 GitHub Operation Guidelines: the harness's sanctioned tool channel, acting as the connected operator (@axross), with the project's agent-comment marker (the single marker string recorded in that skill) on every comment you post so /address continue never mistakes your own output for human input. Follow 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 where the harness provides one (in Claude Code, 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 harness's dedicated question tool where the session supports it (in Claude Code, AskUserQuestion): it 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 the question tool 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.
• A closed or errored question tool 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 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 question tool 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, treat a bare answer token — an option number, an option label, or free-form "Other" text — as answering the still-open question: reconcile it against the options shown in that plain-text presentation and continue from that choice, rather than restarting or re-asking.
• MUST keep the run's status block (see GitHub as Lightweight State) 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 approval of the pending round per the Phase 1 gate rules — for UI-bearing work that means advancing to the next design round when one remains, and to Code once none does (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

/handoff 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 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 per the AGENTS.md skill index, and research current external docs per current-docs.md when behavior depends on a fast-moving framework or platform the project uses.

• 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. One carve-out: the visual presentation direction is never a Must-ask — it is decided through the options exhibit at the plan-approval gate (see the visual-presentation-options bullet below), not through the question UI.

  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 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 UI/component skills); (3) System design / architecture — data flow, state, routes, module placement, when applicable (per the project's structure skill); (4) — the coverage to add or update (per the project's testing skills in the index); (5) — 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 branch under the harness's push-allowed prefix (per GitHub Operation Guidelines, e.g. an agent-namespaced issue-<n> branch); never push to the default branch.
• 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 test coverage the plan named.
• Run the verification the changed surface requires — the commands in the AGENTS.md Verification section, per Development Guidelines › verification — 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 Code Review Guideline); 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 agent session on separate infrastructure — a different session, under a bot identity distinct from the operator — via the claude-review.yaml workflow, which applies the same policy (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. When the plan presented a visual options exhibit, MUST link the chosen design from the description per visual-design-options.md, so humans and AI agents can find the intended design during code review and when debugging preview-environment deployments. 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 the review trigger phrase — @claude review in the example workflow — plus the project's marker line, and nothing else. This fires the review workflow, which submits its findings as 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 the CI status of the merge-checks workflow.
• Address and resolve each blocking finding (Important, or whatever the posted-review policy marks merge-blocking) 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 project's 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 the review trigger phrase 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 the base branch 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 independent 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: the merge-checks CI (merge-checks.yaml: lint + type-check + 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 the harness's scheduled self-wake where it provides one (in Claude Code, send_later from the claude-code-remote MCP server, which delivers a message back into this same session and survives container reclaim); without one, end the turn and wait for /address continue.

• Poll at a 4-minute cadence for the first ~15 minutes, then back off to a 10-minute cadence while still pending. (The 4-minute figure is Claude-Code-specific guidance: its prompt cache has a ~5-minute TTL, so a wake-up under five minutes resumes cache-warm and cheap, and minute-granular scheduling makes four minutes the closest warm value.)
• 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 review request 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 review trigger 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 triggering 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 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 GitHub Operation Guidelines for every GitHub read/write, and the verification the changed surface requires per Development Guidelines › verification. The independent reviewer applies REVIEW.md and Code Review Guideline in its own session; you consult the latter only for the Phase 2 self-check. Keep edits to the smallest surface that satisfies the acceptance criteria; never push to the default branch; never merge the pull request.