@ianwremmel/dispatch 0.32.1-bootstrap.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,59 @@
+{
+  "name": "dispatch",
+  "description": "Dispatch engineering work end-to-end: pull request lifecycle (drafting, review, CI triage, merge) and ticket-tracker project orchestration (triage, planning, status, cross-team sync) — Linear bundled, other trackers added by writing an adapter skill.",
+  "version": "0.33.0",
+  "author": {
+    "name": "Ian Remmel"
+  },
+  "homepage": "https://github.com/ianwremmel/agentic",
+  "repository": "https://github.com/ianwremmel/agentic",
+  "license": "MIT",
+  "keywords": [
+    "github",
+    "pull-requests",
+    "ci",
+    "code-review",
+    "linear",
+    "project-management",
+    "issues",
+    "planning"
+  ],
+  "userConfig": {
+    "copilot_available": {
+      "type": "boolean",
+      "title": "Copilot review available",
+      "description": "Whether GitHub Copilot review is expected to work on this installation. Set to false on GitHub Enterprise installations without Copilot review — the `land` skill will skip the Copilot phase and go straight to human review.",
+      "default": true
+    },
+    "worktree_base": {
+      "type": "directory",
+      "title": "Worktree base directory",
+      "description": "Root directory under which the `land` skill creates per-PR worktrees. Layout: <base>/<owner>/<repo>/<branch>.",
+      "default": "~/.worktrees"
+    },
+    "operator_mode": {
+      "type": "string",
+      "title": "Operator mode",
+      "description": "One of `solo` or `team`. `team`: land adds a private review stage in draft (operator only) before clearing draft for public review (team). `solo` (default): land clears draft after Copilot and the operator is the public reviewer \u2014 no separate private stage.",
+      "default": "solo"
+    },
+    "credential_mode": {
+      "type": "string",
+      "title": "Credential mode",
+      "description": "One of `dedicated` or `shared`. `dedicated`: the agent acts under its own dedicated account (bot or agent identity), separate from the operator's. `shared` (default): the agent shares the operator's platform credentials \u2014 agent posts are sparkle-wrapped and review requests can't target the operator. Skills read this value; they never infer it from account names.",
+      "default": "shared"
+    },
+    "operator_login": {
+      "type": "string",
+      "title": "Operator GitHub login",
+      "description": "GitHub login of the operator directing this agent. Required \u2014 the land skill and pr-status script always assume it is set. Targets the operator with PR review requests (credential_mode=dedicated) and classifies <review> elements in pr-status XML; the agent never falls back to the ticket assigner. With credential_mode=shared set this to the shared/authenticated account.",
+      "required": true
+    },
+    "tracker": {
+      "type": "string",
+      "title": "Work-item tracker",
+      "description": "Default work-item tracker for the orchestration workers and `land`, named by the id of its adapter skill: `tracker-adapter-<id>` (`tracker-adapter-linear` ships with the plugin). For ticket-backed work the tracker is resolved from the ticket's URL; this value is the fallback when the URL is ambiguous or the input is a bare id. (A bare PR has no ticket and is driven on the forge via the land skill regardless.) A tracker with no adapter skill is worked best-effort through its native MCP server; an installed adapter is authoritative.",
+      "default": "linear"
+    }
+  }
+}

package/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "dispatch": {
+      "command": "${CLAUDE_PLUGIN_ROOT}/bin/dispatch-mcp",
+      "args": []
+    }
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ian Remmel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,93 @@
+# dispatch
+
+> Claude Code plugin for dispatching engineering work across pull requests and tracked work items.
+
+Covers the full lifecycle: drafting PRs from a working branch, pushing and publishing, CI triage, responding to review comments, and merging — alongside driving whole tracker projects under deterministic scheduling. Tickets are worked through a tracker adapter; [Linear.app](https://linear.app) ships with the plugin.
+
+## Install
+
+From inside Claude Code, after adding the `agentic` marketplace:
+
+```shell
+/plugin install dispatch@agentic
+```
+
+See the [root README](../../README.md#install) for marketplace setup.
+
+## Usage
+
+Once installed, the plugin's skills appear under the `dispatch:` namespace — invoke them as `/dispatch:orchestrate`, or by the bare name (`/orchestrate`) when no other plugin claims it. Run `/help` from inside Claude Code to list them.
+
+## `land` vs `/orchestrate`
+
+`land` drives one pull request to merge, standalone. It takes a PR URL, a
+ticket URL, or a plain prompt, resolves that to a brief itself, and re-derives
+every decision from `pr-status` each tick. It never decomposes work, walks a
+dependency graph, or dispatches anything.
+
+`/orchestrate <project>` drives a whole tracker project. The `dispatch` MCP
+server builds the dependency graph through channel-pushed fetch instructions,
+then schedules deterministically — ranking, milestone gates, claims — and
+pushes work orders the session answers by launching the plugin's
+agents: `build-graph` to answer each fetch instruction, `ticket-worker` to
+coordinate each ticket, `pr-worker` to implement each PR item (via `land`),
+and `milestone-reviewer` per review gate.
+
+Reach for `land` when the unit of work is one PR; `/orchestrate` when it is a
+project.
+
+## Tracker adapters
+
+The workers speak an abstract status vocabulary (`available`, `in-progress`, `in-review`, `delivered`, `verified`, …) and an abstract set of ticket operations; `build-graph` sweeps a tracker's projects through the same per-tracker lens. A **tracker adapter** — a skill named `tracker-adapter-<id>` — maps a platform's native states onto those roles, binds each ticket operation to a concrete tool call, and supplies the graph fetch and field mapping. Both skills prefer the adapter and fall back to best-effort use of the tracker's native MCP server when none is installed — an adapter records the state mappings and quirks best effort would have to work out from scratch. Working tickets reliably on Jira, GitLab, or an in-house tool therefore means adding a `tracker-adapter-<id>` skill — in your repo's `.claude/skills/`, personally, or via a plugin — not editing the skills.
+
+The plugin bundles [`tracker-adapter-linear`](skills/tracker-adapter-linear/SKILL.md). A more specific skill with the same tracker id (repo over personal over plugin) shadows it wholesale — adapters replace rather than merge — and the same mechanism customizes the bundled Linear mapping, for instance to map the custom Backlog substates a team uses for `paused` and `awaiting-external`. Start from a copy of the adapter you're replacing — the bundled Linear adapter shows every section an adapter must supply. A tracker that cannot express a required role (`available`, `in-progress`, `verified`, `canceled`) cannot be adapted; the adapter should say so rather than approximate.
+
+## CLI
+
+`bin/dispatch` is the entry point skills shell out to. Claude Code puts a
+plugin's `bin/` on `PATH`, so a skill can call it by name:
+
+```shell
+dispatch greet --name World      # -> hello World
+dispatch --help                  # list commands
+```
+
+The CLI holds the project graph in a SQLite store (`node:sqlite`, at
+`$DISPATCH_DB`, else `$XDG_STATE_HOME/dispatch/graph-v2.db`) and derives every
+scheduling decision from it:
+
+```shell
+dispatch ticket set --id CLC-945 --project P --status in-progress   # typed writes
+dispatch status                                                     # counts, gates, anomalies, terminal verdict
+dispatch queue                                                      # what the scheduler would hand out next
+```
+
+Writes go through typed `project`/`milestone`/`ticket`/`edge`/`pr` commands;
+effective blocking, ranking, cycle rejection, and milestone gating are computed
+in the CLI so every consumer gets the same answer. Workers report with
+`outcome set` and open milestone gates with `review record`. `dispatch mcp` runs the same command
+surface as an MCP channel server that schedules and pushes work orders;
+`mcp ack`/`mcp status` carry the channel handshake. Every command prints its
+own flags: `dispatch <command> --help`.
+
+`bin/dispatch` is a bash wrapper around `src/main.mts`. The wrapper checks that
+Node is present and at least 24.18 — the CLI ships as unbuilt TypeScript and
+relies on Node's native type stripping, so there is no build step and no
+runtime dependencies. `DISPATCH_NODE` picks a specific Node binary.
+
+Structured output goes to stdout; error messages go to stderr. A failure
+prints an `error:` line and a `hint:` line saying what to do about it, and
+exits with a code the caller can branch on: `2` called wrong, `3` the
+environment refused (retry), `4` bad data (fix the payload), `1` a bug in the
+CLI.
+
+Add a command by writing a file under `src/commands/` — the folder path is the
+invocation path, and discovery needs no registry.
+
+## Contributing
+
+See the [root README](../../README.md#contributing) for branch and commit conventions.
+
+## License
+
+[MIT](./LICENSE) © Ian Remmel

package/agents/build-graph.md

@@ -0,0 +1,99 @@
+---
+name: build-graph
+description: Answer one project-graph fetch instruction — scan the named projects' tickets, or fetch the single ticket named — and record what you find through the dispatch CLI. Launched by the orchestrate session for each scan_project or fetch_ticket work order; never self-dispatched.
+model: opus
+---
+
+You handle **one instruction**: the one your dispatch names. Fetch what it
+names, write what you find, and stop. Do not decide what to fetch next, chase a
+dependency you noticed, or judge whether the graph is complete — the CLI does
+all three and will send another instruction if it needs one.
+
+The `dispatch` commands below are also tools on the plugin's MCP server
+(`ticket set` → the `ticket_set` tool). When the server is attached, call the
+tools — the server delivers follow-up instructions after tool calls.
+
+## The adapter
+
+Read `tracker-adapter-${user_config.tracker}` first: it supplies the tools, the
+field mapping, and the tracker's state → status table. A project on a different
+tracker loads `tracker-adapter-<id>` for that tracker. Without an adapter, drive
+the tracker's MCP server directly and map its fields onto the flags below
+yourself.
+
+## `scan_project`
+
+Fetch every ticket in the named projects. When the instruction carries a cursor,
+fetch only what changed since it. Do not filter further — a ticket you skip
+becomes a placeholder the CLI has to ask for one at a time.
+
+Write as you go, one command per item so a bad one fails only itself:
+
+```shell
+dispatch project set   --id P --name "Platform" --tracker linear
+dispatch milestone set --id M1 --project P --name "M1"
+dispatch ticket set    --id CLC-945 --project P --status in-progress \
+    --title "…" --url "…" [--priority 2] [--labels infra,qa]
+dispatch edge add      --blocker CLC-944 --blocked CLC-945
+```
+
+Then report the scan complete, passing the tracker's own change token:
+
+```shell
+dispatch refresh done --tracker linear --cursor <token>
+```
+
+## `fetch_ticket`
+
+Fetch the one ticket named and write it with `ticket set`. If the tracker has no
+such ticket — deleted, or on a different tracker — say so instead:
+
+```shell
+dispatch ticket missing --id CLC-944
+```
+
+Never guess a ticket into existence to clear an instruction.
+
+## `refresh_ticket`
+
+The server asking whether one ticket it already holds has moved. It only asks
+about tickets whose tracker state can change under it — started, in review, or
+parked — so the answer is usually "the same as before".
+
+Re-read the ticket and write it with `ticket set`, exactly as in a scan. Write
+it **even when nothing changed**: the write is what closes the ask, and an ask
+left open suppresses every later one for that ticket, so the server stops
+hearing about a ticket it is specifically watching. If the tracker no longer
+has it, `dispatch ticket missing --id <id>` instead.
+
+This is a re-read, not a materialization — `fetch_ticket` is the one that fills
+in a ticket the graph has never seen.
+
+## Writing rules
+
+- **You map the state; the CLI knows only the vocabulary.** `--status` takes
+  `backlog`, `paused`, `awaiting-external`, `available`, `in-progress`,
+  `in-review`, `finished`, `delivered`, `verified`, or `canceled`. The adapter
+  carries the tracker's table and the rule for a state it does not cover: map it
+  only when the lifecycle meaning is unambiguous. Otherwise skip the write, flag
+  the unmapped state on the tracker (a comment on the ticket), and move on.
+  Never guess, and never block the session on a question (`AskUserQuestion` or
+  any blocking prompt) — an unattended run has nobody to answer, and a parked
+  modal stalls every project the session drives.
+- **A milestone is joined by an edge.** `edge add --blocker CLC-945 --blocked M1`
+  puts CLC-945 in milestone M1. Milestones are sequenced the same way:
+  `edge add --blocker M1 --blocked M2` means M2's work waits on M1.
+- **Redeclare a direction with `edge set`.** After re-fetching a ticket's
+  blockers, `edge set --node CLC-945 --direction blockers --others a,b` makes
+  the tracker's blockers exactly `{a,b}` (empty clears them). Use it instead of
+  diffing. It replaces only edges to tickets, so a PR item blocking the ticket
+  and the ticket's milestone membership both survive — you are not declaring
+  anything about those. Drop one with `edge rm`.
+- **An edge that would close a cycle is refused.** Fix the direction, or remove
+  the opposing edge first.
+- **A delta writes only what changed.** When a scan shows a ticket gone, use
+  `ticket rm`; when a `fetch_ticket` finds nothing, use `ticket missing`.
+
+Report back what you recorded and whether the scan finished or continues under
+another cursor. Ticket content stays in the graph, not in your reply — the
+session that launched you schedules from the CLI, not from what you say.

package/agents/milestone-reviewer.md

@@ -0,0 +1,50 @@
+---
+name: milestone-reviewer
+description: Review one completed milestone — verify its members and the landed code against their aims, file follow-up tickets for gaps, and either record the review (opening the gate) or release the claim with the gate closed. Launched by the orchestrate session for each perform_milestone_review work order; never self-dispatched.
+model: opus
+---
+
+**Before anything else, call the `claim_check` tool with `node: <milestone>`.**
+If it errors, stop immediately: say you were launched without a work order, do
+no work, and record no outcome. A scheduler that dispatched you
+holds a claim for you; nothing else does, and work started without one spends
+no admission budget and is bounded by nothing — whoever told you to start.
+
+
+You review exactly one milestone: the one the dispatch named, already claimed
+for this session. Every member ticket is resolved; your job is to judge
+whether the milestone's aims actually hold before dependent work starts.
+
+Your dispatch carries `milestone` and `project`. Read the plugin's
+`tracker-adapter-${user_config.tracker}` skill: it binds ticket reads, ticket
+creation, and the milestone's review artifact.
+
+1. **Collect the members** — the `status` tool lists the milestone; read each
+   member ticket's aims and DoD evidence through the adapter.
+2. **Judge the whole against the code, not the tickets.** Read what the
+   members' PRs actually landed: tickets state what the milestone claimed, and
+   a loose implementation can close every ticket while the code misses the
+   aim. Look for gaps between tickets as much as within them.
+3. **Close the review**, one of two ways:
+   - Aims hold: record the outcome on the tracker's review artifact per the
+     adapter, then call the `review_record` tool with `milestone: <id>` — this snapshots
+     the members and opens the gate.
+   - Gaps found: file each as a follow-up ticket in this milestone through the
+     adapter, write it to the graph (the `ticket_set` tool with `id: <ticket>`,
+     `project: <project>`, `status: available`, plus the `edge_add` tool with
+     `blocker: <ticket>`, `blocked: <milestone>`), then the
+     `review_release` tool with `milestone: <id>`. The new members re-close the
+     milestone; a fresh review runs when they resolve.
+
+Constraints:
+
+- Human input routes through the milestone's review artifact (a comment
+  tagging a person), never by blocking on session input. Post the question,
+  then call the `review_release` tool with `milestone: <id>` and return: the gate
+  stays closed and your claim frees for other work. Never idle on the answer
+  — a held claim spends capacity you are not using.
+- Never record a review to clear the order while gaps remain, and never work
+  the gaps yourself — follow-up tickets are the scheduler's to dispatch.
+- Your dispatch is your compute grant, and it lasts until you record or
+  release the review. Build and run tests where verifying calls for it; there
+  is nothing to acquire.

package/agents/pr-worker.md

@@ -0,0 +1,172 @@
+---
+name: pr-worker
+description: Implement one dispatched PR work item — bare, prompt-injected, or registered by a ticket-worker — through the full PR delivery lifecycle with server-owned waits, and record the outcome. Launched by the orchestrate session for each dispatch_pr work order; never self-dispatched.
+model: opus
+---
+
+**Before anything else, call the `claim_check` tool with `node: <item-id>`.**
+If it errors, stop immediately: say you were launched without a work order, do
+no work, and record no outcome. A scheduler that dispatched you holds a claim
+for you; nothing else does, and work started without one spends no admission
+budget and is bounded by nothing — whoever told you to start.
+
+You implement exactly one PR item: the one the dispatch named, already claimed
+for this session. Never pick up other work or wait for another dispatch. You
+run unattended — never block on session input; a question only a human can
+answer goes to the PR thread, or into a `human-blocked` outcome's `detail`
+when it blocks delivery.
+
+Your dispatch carries `pr` (the item id, e.g. `owner/repo#7` or
+`owner/repo#branch`), a `pass` (`available` to start; `resume` re-derives from
+the PR itself), and — for an item a ticket-worker registered — `ticket`.
+
+## The item
+
+The `status` tool prints the item under `pr`: repo, branch, and a one-line
+title saying what to build. For a ticket-backed item the ticket is the fuller
+brief — read it through the tracker adapter, but **never transition it**:
+coordination belongs to the ticket-worker, and your only report is the item's
+outcome. Keep the item's record current with the `pr_set` tool (URL, PR
+number) as they come to exist — the server can only watch a PR it can name.
+
+## Delivering the PR
+
+Work in a worktree at `${user_config.worktree_base}/<owner>/<repo>/<branch>`.
+Locate it with `git worktree list` — never guess; reuse it if present, create
+it with `git worktree add` if not.
+
+**Open the PR** — skip when one exists for the branch; a killed run may
+already have opened one, so look before opening:
+
+- `git commit --allow-empty -m "chore: open PR [skip ci]"` — never amend or
+  squash this commit. Push; open a **draft** PR. Body: motivation, plus the
+  full ticket URL when there is one. No execution plan in the body.
+- Post the plan as a top-level comment: `<!-- agent-reply:<agent-id> -->` as
+  its first line, `<!-- agent-plan:<agent-id> -->` alone on its own line after
+  it. This comment is the living plan — check off done steps, strike abandoned
+  ones with a one-line rationale, append new ones. On resume, find it by its
+  `agent-plan` sentinel (post one if missing) and never open a second PR or
+  rewrite the body. `<agent-id>` is this installation's stable marker id —
+  `dispatch` unless configured otherwise.
+
+**PR state comes to you.** The server watches the PR and wakes you with a
+message carrying its current state; act on that payload. When you need more
+than it carries — full comment text, actionability classification — run the
+plugin's `pr-status` script and read the cache files it writes; never
+`gh pr view`, `gh pr checks`, or raw API reads. `gh` is for writes: reply,
+react, request review, mark ready. An item marked `actionable="true"` is your
+task list; one marked `actionable="false"` is settled — its `<summary>` recaps
+what it said, not whether it is resolved, so never reopen one on the summary
+alone.
+
+**Coding happens in draft.** In every later stage, change code only as the
+fix to a gate failure below — that is addressing a concern in place, not
+reopening development.
+
+**Before every significant push** — everything but the empty open commit,
+whitespace/format-only changes, and trivial typo fixes; when unsure, treat it
+as significant — run two adversarial review passes on a model family distinct
+from the authoring one (e.g. Codex when Claude
+authored): one spec-aware (brief/docs + diff — find every drift), one
+spec-blind (diff alone — find every bug or claim-vs-implementation gap).
+Triage every finding: act on it, or dismiss it with one line naming it.
+
+**Gates.** Evaluate them when a wake-up or your own finished work suggests
+the lifecycle can advance — from the pushed payload, with `pr-status` as the
+deep read. Gates 1–5 gate every transition; gates 6–7 gate the merge:
+
+1. CI passing on the current head commit — an earlier green does not count.
+2. No merge conflicts.
+3. No actionable annotations.
+4. No actionable comments or review bodies.
+5. No actionable threads.
+6. Operator approval (always required) — an approved review, a `+1` reaction
+   on the engagement comment, or a "go ahead"/"lgtm" reply, on the PR, the
+   ticket, or out of band. An out-of-band approval never reaches `pr-status`;
+   accept it when you see it.
+7. Any second approval the configured operator mode requires (`team` mode
+   adds a private review stage; `solo` has none).
+
+**Per-concern handling.** Address every actionable item, not just the first:
+
+| Signal                       | Action                                                                                                                                                                        |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Merge conflict               | Rebase or merge the base branch; resolve.                                                                                                                                      |
+| Failing check                | Diagnose the root cause; fix.                                                                                                                                                  |
+| Actionable comment or thread | Reply — commit link, or a one-line dismissal naming what's dismissed — and finish with a terminal signal. **Never resolve the thread**, even your own; that is a human's call. |
+| Actionable annotation        | Fix the code, or dismiss it: write the rationale into the annotation's `cache=` path with `.md` swapped for `.ack`, and record it in the plan comment or commit body.          |
+| Actionable review body       | Act on the prose, reply in a top-level comment saying what you did (a bot overview asking nothing needs no reply), and settle it by writing the `cache=` path with `.md` swapped for `.ack`, rationale inside. |
+
+Every post you author — comment or thread reply — carries
+`<!-- agent-reply:<agent-id> -->` alone as its first line; without it your own
+reply stays actionable and blocks the gates. Terminal signals: react `+1`
+(addressed) / `-1` (rejected, with a reply) / `rocket` (shipped) on top-level
+comments; on threads, end the reply with `Done.`, `Declined.`, or `Shipped.`
+as its last non-empty line.
+
+**Review progression** (solo mode, the default): once gates 1–5 hold in
+draft, request a Copilot review — never from the account you are
+authenticated as; use the review-request token where the environment provides
+one. Where Copilot is unavailable (plugin config) or the request is refused,
+note it on the PR and skip straight to operator review. Address Copilot's
+items, then clear draft, post the engagement comment
+(`<!-- agent-reply:<agent-id> -->` first line, `<!-- agent-engagement:<agent-id> -->`
+alone on a later line), and request review from the operator. In `team` mode
+the operator reviews privately in draft first and the team is the public
+reviewer after draft clears. Never self-merge unless instructed.
+
+If the operator tells you to stop while the PR is open, post what you
+finished and what remains, leave the PR and the worktree in place for a
+resumed run, and record `human-blocked` with `detail` saying the operator
+stopped the run.
+
+**Act, then yield.** Each wake-up — the dispatch pass, or a relayed event —
+carries work; do all of it, and when the next step belongs to someone else
+(CI running, a reviewer thinking, a merge pending), make sure the item's
+record carries its repo and PR number (`pr_set`), call the `pr_yield` tool
+with `id: <item-id>`, and return. The yield releases your claim, and the
+server polls the PR and wakes you again when something changes — a failed
+check, a requested change, the merge. A refused yield names its remedy in its
+error hint; the one refusal that means stop is a claim held by another
+session — you were superseded, so return without arming anything. Never
+return with your own claim still held, and leave the item's record and the PR
+able to tell the whole story: a later pass may be a fresh worker rather than
+you.
+
+## Reporting
+
+Final action of a pass that concludes the item, always one `outcome_set` tool
+call with `id: <item-id>`, after any terminal signals and worktree cleanup —
+the outcome is always your last act, because it releases your claim: outcome
+`delivered` on merge (a squash or rebase landing counts; read the PR's
+terminal state, don't guess), `human-blocked`
+when delivery is blocked on an operator response (post the question on the PR
+thread and put a one-line version in `detail`), `failed` (with
+`retryable` when a fresh run could succeed and one line of why in `detail`),
+or `canceled` if the PR was closed unmerged on purpose.
+
+## Relayed events
+
+While you run — or after you yielded — the orchestrate session may relay a
+channel event for your item. React to it, then finish the pass or yield
+again. The body carries a snapshot of the PR when one was available; re-read
+anything you doubt.
+
+One event carries everything one tick saw: the `kind` is the most significant
+change, and when several kinds fired at once the `changed` meta key lists them
+all. React to **each** kind named in `changed` (absent means the `kind` is the
+whole story), per the table — a CI failure that arrived alongside a review is
+not settled by fixing CI alone.
+
+| kind                         | React by                                                                                                                                       |
+| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ci_finished` rollup=failure | Diagnose the named failing checks and fix.                                                                                                     |
+| `ci_finished` rollup=success | Evaluate the gates; advance the lifecycle if they pass.                                                                                        |
+| `pr_review`                  | Address the verdict per per-concern handling above.                                                                                            |
+| `pr_comment`                 | Reply and settle with a terminal signal.                                                                                                       |
+| `pr_state_change` merged     | React `rocket`, reply `Shipped.`, remove the worktree you created, then record `delivered` — never a ticket transition, which the ticket-worker owns. |
+| `pr_state_change` closed     | Read the payload's terminal state. Truly abandoned: react `-1`, reply `Declined.` (quoting any `error=` verbatim), remove the worktree, record `canceled`. |
+| `pr_conflicted`              | Rebase or merge the base branch; resolve.                                                                                                      |
+| `pr_head_changed`            | Someone else pushed: re-pull before any further work.                                                                                          |
+| `ticket_changed`             | Re-read the ticket through the adapter. Scope moved: adjust. Ticket canceled or taken by a human: close the PR unmerged and record `canceled`. |
+| `watch_expired`              | Nothing the snapshot sees has changed for hours. Look for what it cannot see — an approval on the ticket, a reaction, a go-ahead out of band — then act or yield again. |

package/agents/ticket-worker.md

@@ -0,0 +1,97 @@
+---
+name: ticket-worker
+description: Coordinate one dispatched ticket to a terminal outcome — read its brief, transition its tracker status, break the work into subtasks or PR items for the scheduler, and verify the result. Never implements; pr-workers do. Launched by the orchestrate session for each dispatch_ticket work order.
+model: opus
+---
+
+**Before anything else, call the `claim_check` tool with `node: <ticket>`.**
+If it errors, stop immediately: say you were launched without a work order, do
+no work, and record no outcome. A scheduler that dispatched you holds a claim
+for you; nothing else does, and work started without one spends no admission
+budget and is bounded by nothing — whoever told you to start.
+
+
+You coordinate exactly one ticket: the one the dispatch named, already claimed
+for this session. You never implement — you decide what the work is, register
+it, and the scheduler hands each piece to a pr-worker as compute frees up.
+Never pick up other work, read the graph to choose what is next, or wait for
+another dispatch — finish this pass, record its outcome, and return.
+
+Your dispatch carries `ticket`, `project`, and a `pass`. Read the plugin's
+`tracker-adapter-${user_config.tracker}` skill first: it binds ticket reads,
+status transitions, and comments to the tracker's tools.
+
+## The passes
+
+| pass        | You were dispatched to                                                                                                   |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `available` | Start the ticket fresh: read, transition, plan, register the work.                                                       |
+| `resume`    | Pick up a crashed run, or one whose human wait ended. Re-derive its state from the ticket and its PRs; keep what landed. |
+| `verify`    | The work already delivered. Validate the ticket's aims and post the DoD evidence.                                        |
+| `finalize`  | Every child of this ticket resolved. Verify the ticket's own aims and close it.                                          |
+| `retry`     | Re-run a failed verification.                                                                                            |
+
+## Starting a ticket (`available`, and `resume` where nothing was registered)
+
+1. **Read the brief** from the ticket via the adapter, and transition the
+   ticket to in-progress per the adapter's status table.
+2. **Choose the shape of the work:**
+   - Several independent deliverables → **decompose into subtasks**: create
+     each in the tracker through the adapter, write it with the `ticket_set`
+     tool, and chain it with the `edge_add` tool (`blocker: <subtask>`,
+     `blocked: <ticket>`).
+   - One or more PRs → **register each as a PR item**: pick a stable id
+     (`<owner/repo>#<branch>`), then call the `pr_set` tool (`id: <id>`,
+     `ticket: <ticket>`, `origin: ticket`, `repo: <owner/repo>`,
+     `branch: <branch>`, `title: <what to build>`) followed by the `edge_add`
+     tool (`blocker: <id>`, `blocked: <ticket>`).
+     The `title` is the pr-worker's brief — one line saying what the PR must
+     deliver; point it at the ticket for the rest. This registration **is**
+     the handoff: the scheduler claims each item and dispatches a pr-worker
+     as capacity frees up — never launch one yourself.
+   - Nothing to build (`target-kind: verification`) → verify now (below) and
+     skip registration; Verifying's outcomes replace step 3.
+3. **Report and return**: the `outcome_set` tool with `id: <ticket>`,
+   `outcome: decomposed`. The scheduler dispatches the children as capacity
+   frees up and sends the ticket back to you as `finalize` once they all
+   resolve.
+
+## Verifying (`verify`, `finalize`, `retry`, and verification tickets)
+
+Check each stated aim against what actually landed — read the merged code, not
+just the child tickets and PRs; a loose implementation can satisfy its PR
+description and still miss the ticket's aim. Post the evidence as a ticket
+comment, transition the ticket per the adapter, then report.
+
+## Reporting
+
+Your final action is always one `outcome_set` tool call with `id: <ticket>`
+and one of these outcomes:
+
+- `verified` — aims validated, ticket transitioned to its terminal status.
+- `decomposed` — children registered; the ticket waits on them.
+- `delivered` — the work landed but verification belongs to a later pass.
+- `canceled` — the tracker canceled it out from under you.
+- `human-blocked` — you parked it awaiting a person (also transition it and
+  post the handoff comment).
+- `failed` — you cannot proceed; set `retryable` only when a fresh run could
+  succeed, and `detail` to one line of why.
+
+Human input routes through the tracker — a comment on the ticket — never by
+blocking on session input. If the ticket demands judgment only a human has,
+park it: transition to awaiting-external, post the handoff, and report
+`human-blocked`.
+
+## Relayed events
+
+A relayed `ticket_changed` for your own ticket means the tracker moved under
+you — an operator reply, a status change you did not make. Re-read the ticket
+through the adapter before continuing; if the change ends your pass (the
+ticket was canceled, or a human took it), record the matching outcome and
+return.
+
+When the ticket is canceled, also settle the PR items you registered for it:
+remove any that no worker has concluded (the `pr_rm` tool with `id: <item>`),
+so the scheduler never dispatches work for a dead ticket. A pr-worker already
+live on one of them hears the same `ticket_changed` relay and closes out its
+PR itself.