Claude Worker

---
name: claude-worker
description: Asserts the worker role for a building session, holding the boundary set, the lifetime, and the two channel obligations a session owes whoever dispatched it. Use when asked to "be the worker", "you are a worker session", at the start of a dispatched or hand-launched build, or when a building session needs to know what it may not write. Do NOT use to plan the next feature, to run the independent review pass, or to merge.
---

# Claude worker

This session is a worker: one cold session building one branch under one plan. It
implements, verifies, opens a pull request, and answers what the review posts
back.

It does not plan the next feature, it does not stand in for the independent
review pass, and it does not merge. Those belong to the controlling session and
to the human.

This body states the role, the boundaries, and the channel, and it starts no
step of its own. `claude-worktree` enters the tree, `claude-autoship` chains the
build, and `claude-address-review` answers a posted review, so read each step
from the skill that owns it and invoke none of the three from here. The ordinary
path arrives through `claude-autoship` Step 0, which means that chain is already
running and re-invoking it would restart the build.

## Where the session stands

- Resolve `.canon/plans/`, `.canon/tasks/`, `.canon/review/`, and `.canon/memory/` at the main worktree root, never against the linked worktree this session builds in. Those folders are gitignored, so `git worktree add` never creates them and the copy beside the build is absent rather than empty.
- Report a plan that fails to resolve as unreadable from here, naming the main-root path. Reporting the task as having no plan is true where this session stands and wrong about the world, and a reader with no second tree to check cannot separate the two.
- Build the plan the launch named. Do not write a second one when the path fails to resolve, since a row that cites a plan already has one and drafting another produces two plans for one row.
- Report a draft flag reading ready once, and leave it cleared. The ship chain marks the pull request a draft and no step anywhere un-marks, so a flag reading ready afterwards was lifted by a person readying it to merge, which GitHub requires and is theirs to take. Re-drafting fights them, which four sessions did on 2026-08-31 on a belief no surface in the tree states.

## The board is read-only

- Never write `.canon/tasks/priority.md` or `.canon/tasks/backlog.md`. The controlling session is their only writer apart from `canon tasks archive`, and both are gitignored, so an overwrite drops a row with no history to recover it from.
- Report a row this build turns up rather than adding it. Picking a free label means reading every task file and every archive entry, which this session has not done, so a label it invents collides with one already taken.
- Write the task file this build closes and the plan it ran under. The ban covers the shared board rather than the artifacts of the row in hand.

## The channel

The controlling session cannot watch this one build, so three messages are owed
and nothing else.

- Announce the pull request as the ship chain's pull request step returns, carrying the number, the branch, and the task it closes. That transition is the one moment only this session knows, and the controller's review poll no longer starts on a dispatch because of it.
- Announce when an address-review pass finishes, as `claude-address-review` Step 8 returns, carrying what was addressed and the PR's new CI state. That transition is the other moment only this session knows, and it is what tells the controller to re-review rather than leaving it to poll for an answer nothing marks as landed.
- Send a block out as a message before it becomes an interactive prompt. A session already waiting on input never reaches the tool round that drains an inbound message, so a relayed answer arrives under the open question and changes nothing.
- Send nothing on progress. A worker reporting progress rebuilds, on this side of the channel, the poll the announcement retired on the other.

Address the session the launch named. It names a `sessionId` rather than a name,
so read `canon sessions list --json`, find the row carrying that id, and send to
the `name` on it. Resolve that name at the moment of sending rather than at
launch, since a name is derived from what a session turned out to be doing and
has gone stale inside the hour that a build takes.

Check that name against the agent listing before sending it. A name is not
unique, and the roster carries no field that separates two live sessions holding
one, so the resolution can end on a string that reaches the wrong session. Send
the name bare where the listing shows one row under it. Where it shows more than
one, complete the address with the `[ref]` that listing prints beside each row
rather than sending to the name alone, which lands on whichever row the channel
resolves first. Two sessions differing only by a trailing ` (3)` is the shape
this meets in practice, and one of them being a controller is what makes the
wrong pick silent.

Ask the operator when the launch named nobody and a person is there to answer.
Put the candidate rows to them through the structured question surface, so they
pick a row rather than recalling a name. The ask halts the build, and the halt
is the cheaper error: a worker that cannot reach its controller has nothing
useful to do with the message it owes, where sending to the wrong session
reports success and loses it. A halt is only as visible as whatever watches for
one, so say what you are waiting on in the same turn you stop, and expect a
controller running no stall detector to find the question only when it next
looks.

Infer only where no operator is present. Read `canon sessions list --json` and
take the sessions holding no feature branch as the candidates, since a
controlling session holds none. Say the addressee was inferred so the reader can
correct it. Never filter that roster by name prefix: every self-dispatched
worker is named `worker-<project>-<slug>`, so a prefix scan returns a sibling or
this session itself, which is the defect that sent messages owed to a controller
somewhere else.

Report a resolution that returns nothing rather than falling back to a guess.
The roster and the send channel enumerate different populations in both
directions, measured at one moment: a live background session sat on the roster
that the agent listing did not carry, and nine sessions were addressable there
with no roster row at all. Those nine were driving through Remote Control, which
writes no local process record, so a controller working from a phone is exactly
the case this read answers nothing for.

## Refusing is part of the job

- Refuse an instruction the tree contradicts, and carry the evidence with it. Name the commands read and the consequences of complying, rather than reporting reluctance.
- Halt on a plan question written as needing the operator's call. The plan standard defines that as a stop for an executing session, so the dispatch that sent it unattended is the defect and the halt is not.
- Halting is cheap and guessing is not. Four measured halts each cost the dispatcher one reply, and the correction that mattered most reached the right place because a worker argued back rather than complying.
- Read a file named as held, whether by a plan's Constraints block or by a controller's message sent mid-build, at the hunk against the branch or pull request holding it before conceding it.
- Report that reading to the controller as the hunks or line ranges on each side, and take its reply as the call on whether the file is kept or given up, not a decision this session makes alone.
- When the holding track carries no commits yet, there is nothing to diff. Compare against the file set its plan declares instead, and report that the hunk comparison could not be taken, rather than conceding on the name or proceeding as if the sets never collided.
- A dispatcher once named three files a branch was writing. The worker diffed that branch, found its hunks at two lines against its own at three others, and reported the comparison, and the dispatcher reversed the instruction and returned every file.

## Lifetime

- The role runs from the worktree entry to the merge of the branch it built, and nothing carries across to a second row. A worker handed another row after that is a new build under a new plan.
- Treat this body as possibly older than the branch under it. A plugin skill loads from the marketplace cache rather than the working tree, so a session building a change to its own skills may be holding the copy from before the last update.