jpicklyk/task-orchestrator/run-wave

run-wave — Multi-Item Run Plan Front Door

This skill resolves a frontier of ready (and resumable) MCP work items into a run plan — a deterministic set of per-item seat stages derived from each item's resolved schema — opens a server run over those items, and executes the plan either through the Workflow tool (Method A) or through direct Agent dispatch (Method B, the fallback when Workflow is unavailable or the server doesn't yet serve enough capability data for Method A). Both methods execute the same run plan and the same seat prompts — Method B reuses the Method A core byte-for-byte (see references/method-b.md).

The skill itself does no planning arithmetic. All frontier resolution, edge classification, stage derivation and the exact server ops are produced by a pure Node helper (scripts/run-planner.mjs / run-planner-lib.mjs / run-exec-lib.mjs). This skill's job is: call the helper with the right inputs, show the human the plan, send the ops the helper renders, launch, and drive post-run verification and advancement. Side effects (MCP calls, token files, git worktree add, Workflow/Agent dispatch) stay in this prose, never in the helper. The Workflow runtime has no MCP access: every runs_write, runs_read and coordinator advance call is yours.

Do not attempt to replicate the helper's algorithm in your head. If a helper call fails or its output looks wrong, report the raw stderr/stdout rather than improvising a plan by reading MCP responses directly — the whole point of the helper split is that frontier/edge/stage logic is fixture-tested, not reasoned about fresh each run.

The server run

A run-wave run is a server run (current/docs/api-reference.md → "Category: Runs"). Two ids name it:

• the plan id runId (r-…), from plan: the scratchpad directory, the plan document's

args.runId, the provenance run= field and the run's label;

• the server run id (a UUID), from runs_write open: bound into the plan with bind-run as

args.serverRunId and passed as runId to every runs_write/runs_read call.

The run view (runs_read get, frontier, seats) is the run's state: there is no plan or state document on the server. The local scratch files (<scratchpad>/run-wave/<runId>/plan.json, state.json, result.json) hold what the helper reads.

Tokens. open answers a coordinatorToken once (a keyed replay omits it); assign answers each seat's seatToken once. Write each seat token, and nothing else, as one line to the token file run-ops assign names (<scratchpad>/run-wave/<runId>/tokens/<short>.<seat>.token); the seat prompt names that path and the seat reads it. Write the coordinator token the same way, as one line to the tokenFile that run-ops --phase open names (tokens/coordinator.token), so a restart, --resume or compaction can read it back; pass it as seatToken from that file, and delete tokens/ at close. Never put a token in a prompt, a note, a log line, a commit, the plan or a helper input, and never echo one back to the user. A lost coordinator token (no file, or the file's token is refused) cannot be recovered: close the run on the director connection (no seatToken) or with a human credential, and open another.

A seat envelope is stripped before it is persisted: any seatToken or coordinatorToken key is removed at any depth in both methods, and Method B's stage-result also redacts every value read from the run's token files. Method A strips by key only (the Workflow sandbox cannot read token files), so a token echoed under another key is not caught there. The coordinator token file sits in the same tokens/ directory, so Method B redacts its value too.

Which token goes on a call. Every coordinator call (update, assign, close, the coordinator advance calls, withdraw of a decision this run raised, and every notes_write upsert to an orchestrator-seat key of a run member while the run is open: post-run Step 3 and the Step 5 pointer) carries the coordinator token as the top-level seatToken; end_seat carries the seat's own token; open carries none.

RESULTS. A write tool answers data.results[i], one entry per ops[] element: read each element's own ok and data.results[i].error (code, detail, fix). A call-level partial_failure only means "an element failed, look per element" and carries no detail. The exception is an atomic batch (atomic: true): it answers only the failing element's own error with error.index, and nothing was written.

Retry classes the coordinator meets.

Decisions. A writing seat that needs a ruling raises runs_write raise {class: "deviation", block: true, dedupeKey, question, options, recommended, itemId} under its own token and stops with reason: "awaiting_decision" and the decisionId. A raise with block: true blocks the item; an answer never resumes it, and a blocked item allows only resume and cancel. The coordinator withdraws (runs_write withdraw {decisionId}, coordinator token as seatToken, sent on the mcp-task-orchestrator-director connection or REST POST /api/v1/ops/runs_write: withdraw exists only in the director profile) only decisions it or its seats raised that went stale — never a server-raised run-budget or attempt-cap decision. A stall is never a reason to raise: see Stalled seats below. Answered decisions are resumed here, at Step 2 (before the snapshot) and at post-run Step 6, by the rule in status-progression/references/decisions.md: never while the decision is open.

Reporting. A coordinator reports to the director (or shows the user, when none runs this skill) on exactly four events: planned (end of Step 5a; for a tier-2 coordinator, its return), decision (a stage stopped awaiting_decision, or this skill raised one), paused (run_paused, a paused:{decisionId} success, or a stalled seat whose re-assign hit the attempt cap) and closed (any close). Send only the block node "<helper>" report --plan <plan.json> --event <e> [--result F] [--run F] [--close F] [--needs TEXT] prints, never a hand-written one and never note text, diffs or a token. Contract, addressing and the brief: skills/director/references/coordinator-tiers.md. After decision or paused, wait for the answer; never answer a decision yourself.

Helper resolution

Every helper call in this skill (and in the references) is of the form:

node "<helper>" <cmd> --in <scratchpad>/run-wave/<runId>/<file>

Resolve <helper> once, at the start of Step 0, and reuse the same resolved path for every later call in this run (record it as state.helper):

1. Try ${CLAUDE_PLUGIN_ROOT}/scripts/run-planner.mjs. ${CLAUDE_PLUGIN_ROOT} substitutes

inside plugin skill bodies (the same mechanism the code-modernization plugin's commands rely on) — confirm the literal string ${CLAUDE_PLUGIN_ROOT} did not survive into the command you are about to run, and that probe (see F0 below) exits 0.

1. If the literal survived, or probe exits non-zero, fall back to the dev-checkout path

<git toplevel>/claude-plugins/task-orchestrator/scripts/run-planner.mjs, when that path exists. Set state.helperFallback: true and add helper-fallback to meta.degradations — under this fallback, probe's phase0Hooks reflects the checkout, not the installed plugin cache, so Step 0 F4 will read entryMode: pre-entered even when the installed cache actually has Phase 0 hooks. Report this degradation rather than silently trusting the pre-entered path.

1. If neither resolves, stop and tell the user to refresh the plugin cache (see

claude-plugins/CLAUDE.md → "Plugin Discovery and Cache Refresh") — do not attempt a manual plan. While the plugin version is unchanged, every plugin file (workflows, skills, references, hooks, agents) reaches the installed cache only through the forced refresh in claude-plugins/CLAUDE.md "Plugin Discovery and Cache Refresh".

Step 0 — Capability check and fallbacks

Run every check below before touching MCP state. Each row's fallback is a rule for THIS run — re-probe every invocation (capabilities can change between sessions). F3 and F7 need a rootId before Step 1 runs, so resolve it first by Step 1's rule (session context, then the Config: file, then .taskorchestrator/config.yaml).