/run-wave

name: run-wave
description: "Front door for running a multi-item wave of MCP work items through a generated run plan — resolves a frontier of ready/resumed items, derives per-item seat stages from their resolved schemas, and executes the plan via the Workflow tool (Method A) or direct Agent dispatch (Method B) when Workflow is unavailable. Use when a user says: run the wave, launch the wave, run a wave over <feature>, run these ready items as a wave, run-wave, resume run r-…, or when a task notification arrives from task-orchestrator:implement-wave. NOT for a single Direct-tier fix (use /status-progression or a direct dispatch) and NOT for headless unattended queue draining (use /ralph). Does not itself decide whether to plan or implement — it executes a run plan over items whose specification/task-scope notes already exist."
argument-hint: "[ancestorId | itemIds] [--method A|B] [--mode shared|per-item] [--worktree <path> --branch <name>] [--resume <runId>] [--claim]"

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 — and executes that 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, and stage derivation happens in a pure Node helper (`scripts/run-planner.mjs` / `run-planner-lib.mjs`). This skill's job is: call the helper with the right inputs, show the human the plan, launch it, and drive post-run verification and advancement. Side effects (MCP calls, `git worktree add`, `Workflow`/`Agent` dispatch, `advance_item`) stay in this prose, never in the helper.

**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.

---

Helper resolution

Every helper call in this skill (and in the two 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. 2. 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. 3. 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.

---

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`).

| # | Check | How | Fallback | |---|---|---|---| | F0 | Helper resolvable | `node "<helper>" probe` exits 0 | dev-checkout path (see Helper resolution above); else stop with the cache-refresh pointer | | F1 | `Workflow` tool callable | `Workflow` already in your tool list, or `ToolSearch("select:Workflow")` resolves it | Method B (pass `--method B` to `plan` in Step 3 so the plan document's `meta.method` is `"B"`) | | F2 | Server `features` cover `seats`, `dispatchBySeat`, `rules` | the first `query_items(operation="schema")` response's `features` field, **not** `probe` — `probe` reports plugin/hook capability (version, hooks, allow rules), never the server's schema `features` | missing `features`/`seats` → Method B with implicit per-phase owners (no interim seat map — the planner derives `planner`/`implementer` ownership itself when a schema is seat-less); missing `rules` → **stop, both methods** (the server cannot serve the protocol rules, and `promptRules` in the shared prompt core marks the protocol key fatal for Method B too; upgrade the server) | | F3 | Protocol rules served | `rulesServed` from `query_rules(operation="list")` — the snapshot's own `rulesServed` field — includes `protocol.entry-seat`, `protocol.in-phase-seat`, `protocol.read-only-agent`; **not** `probe`, which carries no `rulesServed` field at all | **stop, both methods**, with: "protocol rules not served for this root". The reason: `promptRules` (`workflows/implement-wave.js`) marks the protocol key fatal, and Method B renders its seat prompts from that same core, so Method B cannot proceed either. Repair, then re-probe F3. (a) REST URL configured: start a new session; config-sync pushes the plugin's `bundled-rules/` at SessionStart to any initialized root that do