orchestrate
/orchestrate
Orchestrate one natural-language goal into parallel tmux Claude Code sessions. It decomposes the goal (with your approval), plans each task with wiki-plan, implements and reviews, runs an integration test, and merges after your confirmation. Use to build a goal across multiple sessions. For a single task, use loop-implement instead.
- Author
- choiyounggi ↗
- Repository
- dev-loop ↗
- Licence
- MIT
- Last repository change
- 23.10.2026
Assessment and security
- Files in this package
- 28
- Scripts
- 24
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 23.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 24 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/ask-coordinator.sh, scripts/collect-status.sh, scripts/escalation-dir.sh, scripts/graph-add.sh, scripts/graph-drop.sh, scripts/install-permission-rules.sh, scripts/launch-session.sh, scripts/orca-detect.sh, scripts/orca-spawn.sh, scripts/orca-wait.sh, scripts/orca-worker-stalled.sh, scripts/orca-worker-start.sh, scripts/orca-worktree-alive.sh, scripts/ready-set.sh, scripts/resolve-escalati
What it does and when to use it
Orchestrate one natural-language goal into parallel tmux Claude Code sessions. It decomposes the goal (with your approval), plans each task with wiki-plan, implements and reviews, runs an integration test, and merges after your confirmation. Use to build a goal across multiple sessions. For a single task, use loop-implement instead.
Arguments
/orchestrate [goal or parent issue]
Original author description
Orchestrate one natural-language goal into parallel tmux Claude Code sessions. It decomposes the goal (with your approval), plans each task with wiki-plan, implements and reviews, runs an integration test, and merges after your confirmation. Use to build a goal across multiple sessions. For a single task, use loop-implement instead.
How it works
- Asking the user — every question is a chooser (REQUIRED)
- Tool profile
- Coordinator token budget
- Preflight
- Phase 0 — Intake + Clarify
- Phase 1 — Environment branch
- Phase 2 — Decompose
- 🚦 Gate 1 — task-split approval (REQUIRED)
- Phase 3 — Launch + plan (dispatch loop)
- Phase 4 — Implement + review (max 3 rework)
SKILL.md preview
---
name: orchestrate
effort: high
argument-hint: "[goal or parent issue]"
description: Orchestrate one natural-language goal into parallel tmux Claude Code sessions. It decomposes the goal (with your approval), plans each task with wiki-plan, implements and reviews, runs an integration test, and merges after your confirmation. Use to build a goal across multiple sessions. For a single task, use loop-implement instead.
---
# orchestrate — multi-session orchestrator
You are the orchestrator. **You do not implement — sessions do.** You clarify,
decompose, distribute, review, integrate, and merge. Autonomy lives inside the
implementation loop; two human gates bracket it (task-split, pre-merge).
Scripts referenced below live in `${CLAUDE_PLUGIN_ROOT}/skills/orchestrate/scripts/`.
Communication: session→orchestrator via each worker's OWN worktree-local
`.orchestration/status/<task>.json` (never the coordinator's checkout — a
worker writing there can hit a guardrails permission prompt no human is
watching, issue #167), collected into the canonical `.orchestration/status/`
by `scripts/collect-status.sh` (Phase 3 step 1, and automatically each poll
via `watch-status.sh` — see **Session knobs**); orchestrator→session via
`launch-session.sh` (the first prompt) then `send-prompt.sh` (every later
one), carrying templates/session-prompt.md §1–§4 on tmux, or the Task `--spec`
(same file, §O1–§O4) on Orca.
## Asking the user — every question is a chooser (REQUIRED)
Every question this skill puts to the **user** is delivered with the
**AskUserQuestion** tool, so they answer by selecting an option instead of typing
a reply. Prose in the turn is the *briefing* (task list, graph, slot count, cost
note, diff); the *decision* is always the tool call. This covers Phase 0 frontier
rounds, Gate 1 (task split **and** substrate), Gate 2, a Phase 3 deadlock, and any
worker escalation that needs a human verdict.
**Required shape**
- One call per round, up to 4 questions in it. A frontier wider than 4 → back-to-back
calls of ≤4 questions, numbering continuous across them; never one question per turn.
- Each question carries 2–4 options; the **recommended answer is option 1**, its
label suffixed `(Recommended)`. `header` ≤12 chars.
- Options are the concrete outcomes ("approve as proposed", "drop task 3", "Orca"),
not a yes/no restatement of the prose.
- `multiSelect: true` when the items are independent (e.g. which optional tasks to include).
- Free-text is already available to the user as "Other" — never author an "Other" option.
**Predicate-keyed**
| Situation | Ask |
|---|---|
| Phase 0, frontier of open decisions | one question per frontier item, ≤4 per call, each with its recommended answer |
| Gate 1, `orca-detect.sh` non-zero (no Orca) | Q1 task split: approve as proposed / revise / abort. Say nothing about substrates |
| Gate 1, `orca-detect.sh` exit 0 (Orca present) | the SAME call carries Q1 task split **and** Q2 substrate: Orca / tmux |
| Gate 2, after showing the integration diff | Q1: merge / send back for rework / abort |
| Phase 3 deadlock, or an escalation needing a human | options = the concrete resolutions available, not "how should I proceed?" |
| You are a **worker** session (templates/session-prompt.md) | never AskUserQuestion — escalate via `ask-coordinator.sh`; only the coordinator asks the user |
**Pre-send check** — before ending any turn that asks the user something: does this
turn contain an AskUserQuestion call? Is the recommended option first and labelled?
If the turn instead ends with a question in prose, delete that prose question and
re-send it as the tool call. Enforcement is machine-side too: the
`orchestrate-ask-gate.sh` PreToolUse hook denies `launch-session.sh` /
`orca-worker-start.sh` / `orca-spawn.sh` until this session's transcript shows the
AskUserQuestion (and, when Orca is detected, one naming the substrate choice).
## Tool profile
Resolve the pluggable tool profile once up front:
`sh ${CLAUDE_PLUGIN_ROOT}/scripts/resolve-tools.sh --summary`. It maps capability
roles — `intake` (issue-tracker work-list source), `knowledge` (domain/policy),
`tacit` (incidents/danger zones), `verify` (test/build/lint/typecheck/QA
command), `explore` (code search; a fresh graphify graph when Preflight says
so), `design` (visual/UI spec, e.g. Figma), `inspect` (how an existing
product behaves, for a feature that mirrors it — wiki-plan Phase A3) — to
whatever tools this installation has, or to generic defaults when unset (optional,
layered per-user then per-repo; see `references/tool-profile.md`). Use
`knowledge`/`tacit` yourself during Clarify/Decompose, and write each task's
resolved roles into its `<tools_guidance>` brief so worker sessions inherit them
even if they can't re-read the config. A role is a tool injected into one step,
never a loop: do not map a role to an implement/verify-loop tool or another
orchestrator (that nests loops); there is no `implement` role.
## Coordinator token budget
Accumulated context, not turn count, is what drives a run's cost — every call
resends the full history at the cached rate, so cost per turn grows as the run
goes on. Four things the coordinator itself controls:
(a) never `Read` a screenshot or other image directly into this session —
delegate the visual check to a subagent that returns a text verdict instead;
(b) bound every pane capture and status read (`tail -N` on tmux panes, one-line
`jq` filters on status JSON) instead of pulling full output into context;
(c) **say where a `/compact` is safe** — the coordinator cannot compact its own
session, so a human has to be told. The safe points differ in what they hand
back, so they are keyed by predicate:
| At this point | What to say | What gets re-read from disk afterwards |
|---|---|---|
| Gate 1, once the split is approved | a safe `/compact` point, if the run has already gone long | `.orchestration/graph.json` and the briefs |
| **After each merge-on-approval** — once `git merge-base --is-ancestor <branch> <integ>` has confirmed the merge landed (Phase 3 step 5) | a safe `/compact` point | `.orchestration/graph.json`, `.orchestration/status/*.json`, and the brief + plan of whatever `ready-set.sh` dispatches next |
| Gate 2, with the integration diff shown | a safe `/compact` point | the integration diff, re-read with `git diff` |
Gate 2's full-diff read is the LAST one of a run, not a recurring cost: Phase
5's integration review now runs on the `integration-reviewer` agent's own
fresh context, so this coordinator session itself never reads the full
integration diff until this final gate. Per-task diffs are read by the
`task-reviewer` agent at Phase 4 the same way, so this session reads no
worktree diff at all before Gate 2. Per-task plans are written and re-planned
on the `task-planner` agent at Phase 3 step 2a the same way, so this session
holds no plan body either (Phase A on the `task-analyst` agent, Phase B and
C on `task-planner`).
The middle row is the one that matters. Gate 1 and Gate 2 are the *first* and
*last* things a run does, so on their own they leave the long autonomous middle
— where essentially all of the context accumulates — with no sanctioned
checkpoint; one measured run peaked at **613,698** context, more than 2x
`token-report.sh`'s own warn threshold, and was told about it only after
teardown. That boundary is safe for exactly the reason **Re-entry** gives:
nothing unrecoverable is held there, because the graph, every task's phase and
`.attempt`, the briefs, the plans, the reviews and the merged commits are all
already on disk. It also recurs once per approved task rather than twice per
run.
(d) **measure it during the run, not only after it.** At that same
merge-on-approval boundary, before offering the `/compact`, read this
coordinator session's own peak context. Target the newest transcript in the
project's mapped directory, not the directory: the teardown form
(`--cwd <root> .`) reports every past session for this project, while the newest
transcript is this live session, since it is the only one being written during
the run.
```sh
d="$HOME/.claude/projects/$(printf '%s' "$PWD" | tr '/.' '-')"
newest=$(ls -t "$d"/*.jsonl | head -1)
sh {SKILL}/scripts/token-report.sh "$newest"
```
That prints a two-row table, plus one `warn: peak context …` line on stderr once
peak passes `LO_CTX_WARN` (default 300000). Pass the warn line to the user along
with the compact offer. The End-of-run contract runs the same script over the
whole run; this is that measurement taken while it can still change something.
**Known amplifier — the re-plan loop.** When a worker reports the plan is
contradictory or under-decided (Phase 3 step 2a), every round used to append
permanently to coordinator context: the worker's gap report, the coordinator's
verification of it against the code, the plan patch, and the re-send. One
measured run did eleven of them. The verification and the patch now run on the
same task-planner agent that wrote the plan — forward the gap report verbatim
with SendMessage; its transcript still holds the plan — so what this session
keeps per round is the one-line forward and the short re-send: the worker
re-reads `{ORCH_DIR}/plans/<task>.md` from disk anyway, so send `plan patched at
§N — re-read it from disk and re-run the adoption check` instead of restating
the fix in the prompt.
**Re-plan ladder — bound the loop.** Track each task's round count in your head
from the review/patch history already on disk (no new state file). Route each
gap report by what it faults. A gap in the analysis (`analysis.md`'s
requirements, ground truth, or constraints) goes to the same `task-analyst`
first — SendMessage it the gap report, wait for its fresh ANALYSIS REPORT, and
re-run gate-A yourself — and then to the same task-planner agent with
"analysis.md changed — re-check the plan against it". Any other gap goes to
the same task-planner agent only. Rounds 1–2 on a task are SCOPED PATCHES: the
planner patches only the reported gap, then the cheap re-send above. Round 3
is ONE full re-plan and goes through the two-stage handshake again, in this
order:
1. SendMessage the same `task-analyst` the gap report and "round 3 — re-run
Phase A wholesale"; wait for its ANALYSIS REPORT and re-run gate-A yourself.
2. SendMessage the same task-planner agent "round 3 — analysis rewritten": it
deletes its stale `review-verdict.md`, rewrites `plans/<task>.md` wholesale
from the new `analysis.md`, and STOPs with a fresh STOP REPORT instead of a
FINAL REPORT.
3. Run `plan-reviewer` again on the redesigned `design.md` before the planner
emits gate-B, exactly as in the first handshake.
A full re-plan replaces patching a single section because a third scoped
patch is the signal the section-level fixes aren't converging. A task that still
reports a plan gap after its round-3 full re-plan is a deadlock-grade
escalation to the user: report it and get a human decision, same as a Phase 3
step 1 exit-3 DEADLOCK. There is never a round 4.
Basis:
`wiki/infrastructure/agent-orchestration/session-context-token-budget.md`
(directives 2–4), plus this skill's own **Re-entry** guarantee for the
merge-on-approval row.
## Preflight
Run `${CLAUDE_PLUGIN_ROOT}/hooks/preflight.sh` to resolve git/tmux/jq paths and
surface any missing CLI. **git, tmux, and jq are all required** — if any is
missing, stop and ask the user to install it (the SessionStart preflight hook is
advisory only; this skill must hard-require them). For a missing tmux: with the
user's consent, install it (macOS: `brew install tmux`; otherwise advise) before
launching sessions. Never auto-install without consent.
**Code-graph freshness (optional `explore` lead).** Run
`sh ${CLAUDE_PLUGIN_ROOT}/scripts/graph-freshness.sh <root>` once, bare (read
its exit code on the next line, never in a pipe). It never runs graphify
itself. Branch on the code: **0** (`fresh`) — set `explore` to graphify for
this run and write the row from Phase 3 step 2 into every brief; **2**
(`stale <N>`) — ask ONE chooser (§ Asking the user): "graphify graph is stale
(<N> files changed since it was built) — run `graphify update <root>` now
(AST-only, seconds, no LLM), or continue without the graph?" with *update* as
the recommended answer; run the update only on an explicit yes and re-run the
freshness check afterwards; **3**/**4** (`absent` / `cannot-evaluate <reason>`)
— print one line saying the graph is not in use and continue exactly as
before. The coordinator never runs a full `/graphify` build and never loads
the graphify skill document: the CLI is the whole interface
(`graphify --help`). Basis:
`wiki/infrastructure/agent-orchestration/code-graph-as-orientation-layer.md`.
**Coordinator permissions (tmux substrate).** `launch-session.sh` starts each
worker as `claude --permission-mode bypassPermissions` — the exact surface an
auto-mode permission classifier hard-flags as privilege escalation. It cannot
see the context that makes this safe (each worker worktree carries a guardrails
deny-net that still blocks dangerous commands in bypass mode and escalates
`ask` rules to you), so under an auto-mode coordinator the launch may be
DENIED. Handle this at onboarding, not at the first failure:
1. **Probe once, read-only**, during Preflight:
`sh {SKILL}/scripts/install-permission-rules.sh --check` — exit 0 rules
present (nothing to do), **4** absent, 3 the settings file is malformed
(surface that to the user; fix before anything else).
2. **On 4, ask the user — never install silently.** One question: "orchestrate's
tmux workers launch with permission prompts off (guardrails-sandboxed);
pre-approve the four worker-management scripts in ~/.claude/settings.json?"
Show what it adds (the snippet below) — this also covers the exit-5
escalation recovery path (`resolve-escalation.sh`), executable by an
auto-mode coordinator without any bare `rm`. A plugin that widens permissions
without a fresh explicit yes is the supply-chain pattern guardrails exists
to stop — and the fresh consent is also what lets the classifier pass the
write at all.
3. **On an explicit yes**, run `sh {SKILL}/scripts/install-permission-rules.sh`
(idempotent; backs up, refuses a malformed target, atomic write). On no —
or if the installer itself is classifier-blocked — fall back to showing the
snippet for the user to paste themselves, then continue; the launch will
simply prompt (default mode) or deny (auto mode) until it lands.
4. If a launch is DENIED later anyway: do **not** work around the block — an
agent widening its own permissions on its own initiative is itself
classifier-blocked, by design. Re-offer step 2 and stop until the user
decides.
What the installer adds (equivalently pasteable into
`.claude/settings.local.json` per-project, or `~/.claude/settings.json`
globally; `safe-cleanup.sh` is deliberately absent so destructive verbs keep
their normal review):
```json
{
"permissions": { "allow": [
"Bash(sh /Users/<you>/.claude/plugins/cache/*/dev-loop/*/skills/orchestrate/scripts/launch-session.sh *)",
"Bash(sh /Users/<you>/.claude/plugins/cache/*/dev-loop/*/skills/orchestrate/scripts/send-prompt.sh *)",
"Bash(sh /Users/<you>/.claude/plugins/cache/*/dev-loop/*/skills/orchestrate/scripts/watch-status.sh *)",
"Bash(sh /Users/<you>/.claude/plugins/cache/*/dev-loop/*/skills/orchestrate/scripts/resolve-escalation.sh *)"
]},
"autoMode": { "allow": [
"$defaults",
"Running the dev-loop orchestrate plugin's worker-management scripts (launch-session.sh, send-prompt.sh, watch-status.sh, resolve-escalation.sh) is allowed, including launch-session.sh starting a tmux worker with `claude --permission-mode bypassPermissions` and resolve-escalation.sh clearing a guardrails escalation record and delivering the coordinator's verdict to the waiting worker: the user sanctioned this orchestration workflow, and each worker worktree is sandboxed by groundwork guardrails, which still blocks dangerous commands in bypass mode and escalates `ask` rules to the coordinator. This does NOT extend to safe-cleanup.sh or other destructive commands, which keep their normal review."
]}
}
```
The path rules cover full-path invocations; the `autoMode.allow` rule teaches
the classifier the context so variable-form invocations (`sh $SKILL/scripts/…`)
pass too. The Orca substrate does not spawn through `launch-session.sh`, but
its worker terminals embed the same flag — if a classifier flags those, the
same `autoMode.allow` rule is the fix.
## Phase 0 — Intake + Clarify
Two ways the work-list arrives:
- **`intake` role configured** (e.g. an issue tracker) → if the user names a parent
issue (key/URL), use the intake tool to read it and its children: the parent gives
the overall goal/architecture, each child becomes a candidate task. Extract the
issue key from a URL (last path segment). This is the "Jira-style" entry — only
taken when `intake` is set *and* the user supplies an issue; otherwise:
- **`intake` unset, or a free-text goal** → the natural-language path (default):
decompose the goal yourself in Phase 2.
**Already-done children (partial resume):** treat a child as *completed* if the user
says so (by key) or — when intake exposes status — its tracker status is Done. A
completed child is **not** decomposed into a task (no session/worktree), but it is
**not silently dropped** either: record what it produced as a **base output** — the
exact exposed signature (function/type/component/endpoint). Any task that depends on
it then still gets that contract injected (Phase 2/3). If the user names a completed
key without the signature, read it from the integration branch / its merged code
rather than re-creating it. This is how "one sub-issue already done, do the rest"
works safely.
Either way, map open decisions as a **design tree** — each decision branches into
the decisions that hang off it — then run **frontier rounds**:
- A decision belongs in the **frontier** when its prerequisites are already
settled; a decision whose answer depends on another still-open decision waits
for a later round.
- A fact the environment can answer (repo state, config, docs) is the
orchestrator's job to look up — never asked of the user; only genuine
decisions go to the user.
- Each round, ask the WHOLE frontier at once — as **AskUserQuestion** questions
(§ Asking the user), one per frontier item, each a **question + a recommended
answer** (never a bare open question, never prose the user must type back).
Repeat rounds until the frontier is empty — goal / scope / constraints / done
criteria clear enough to decompose. Don't start until they are.
## Phase 1 — Environment branch
- **git repo present** → create a feature (integration) branch + one worktree per
task. Determine base via `gh repo view --json defaultBranchRef` (fallback: the
current branch) — measure, don't assume.
- **no git repo** → run `scripts/safe-cleanup.sh init-check <workdir>`. Only if it
returns ok, `git init` (add a `.gitignore` incl. `.orchestration/` first), then
proceed as above. If it REFUSEs (nested repo / secrets), stop and report.
- Create `.orchestration/notes/` and `touch` an empty `notes/decisions.md` —
the blackboard (append-only) lives there; see **Blackboard** below. Without
this, the first worker to reach the implement phase's read checkpoint reads
a file that does not exist yet.
## Phase 2 — Decompose
Get the task set: use the `intake` children as candidate tasks if Phase 0 read an
issue, otherwise split the goal into independent tasks yourself. **Drop the
completed children (Phase 0) from the task set** — but seed the dependency graph
with their base outputs (already-satisfied), so their dependents still resolve and
get the signature injected, while no session is spawned for them. Then, the same way
for both, for each *remaining* task extract **affected files**, **outputs** (what it newly
creates — component/schema/endpoint/type), and **consumes** (another task's output
it depends on). Build a conflict/dependency matrix from those and topologically sort
into Waves (`conflict-matrix.md`): a dependency edge `A → B` means B consumes A's
output, so A's Wave precedes B's. Detect duplicate outputs and assign a single
producer; others consume (add a dependency edge). **Mark shared surfaces** while
you do this: any output that lands in one task's `outputs` and at least one other
task's `consumes` is a shared surface — the conflict matrix already computes this
exact edge, so no extra pass is needed. Phase 3 step 0 commits a contract stub for
each one before its producer is dispatched (see Contract-first dispatch below).
Write BOTH artifacts: `conflict-matrix.md` for humans and
`.orchestration/graph.json` for the scheduler. A markdown table is not machine
readable.
**Graph leads (only when Preflight set `explore` to graphify).** For each
candidate task, run `graphify explain "<Symbol>" --graph
<root>/graphify-out/graph.json | head -40` on the symbols the task names, and
`graphify path "<A>" "<B>" --graph <root>/graphify-out/graph.json` for a
suspected edge between two tasks. The printed connections seed the task's
affected files and its shared surfaces; the disjointness test in the conflict
matrix runs on the confirmed sets, never on the graph's guesses. A graph hit is
a lead, not evidence: every file it suggests is confirmed by a search before it
enters `files`, and the record pairs both in one line —
`graphify explain <Symbol> -> <N> connections; grep -rn <Symbol> src -> <n> hits`.
Ask symbol-anchored questions only; a free-text `graphify query` is for
orientation (`--budget 800`) and never derives a file set. Any assumption taken
from the graph and not confirmed is recorded on the blackboard as
`graph-derived: <assumption>`.
```json
{ "tasks": [
{ "id": "t1", "deps": [], "files": ["src/auth/token.ts"], "outputs": ["AuthToken"], "risk": "R3", "risk_basis": ["path:auth", "shared-surface"] },
{ "id": "t3", "deps": ["t1"], "files": ["src/api/client.ts", "src/api/routes.ts", "src/api/errors.ts"], "consumes": ["AuthToken"], "risk": "R1", "risk_basis": ["files:3"] }
] }
```
**Risk tier (issue #192).** Every task node carries risk (exactly one of R0, R1,
R2, R3) and risk_basis (array of signal tokens from the table below, or
`["none"]`). The scheduler ignores both fields — ready-set.sh reads only id and
deps and graph-add.sh validates only id, deps, split_of, outputs, so no script
changes — and every node added later with graph-add.sh carries them too.
| Signal | Source | Token | Floor |
|---|---|---|---|
| files match an auth, authorization, secrets, or payment path | Phase 2 affected files | path:auth path:secrets path:payment | R3 |
| DB schema or migration files | affected files | path:schema | R3 |
| destructive or irreversible action (delete, drop, force, revoke) | plan deliverables | destructive | R3 |
| public API contract or deploy pipeline files (.github/workflows, Dockerfile) | affected files | path:public-api path:pipeline | R2 |
| shared-surface producer (another task consumes its output) | conflict matrix | shared-surface | R2 |
| new external dependency | plan | new-dependency | R2 |
| the task mirrors a behavior of an existing third-party product and the Phase 2 reference study returned one or more rows | Phase 2 reference study report | reference-study | R2 |
| concurrency or multi-object write | lens 4 signal | concurrency | R2 |
| two or more dependents in graph.json | graph reverse lookup | fan-out:<n> | R2 |
| wiki-plan Size verdict large | step 2a | size:large | R2 |
| one or more [no-wiki] decisions | step 2a | no-wiki:<n> | R1 |
| more than two affected files (a `**` glob counts as more than two) | Phase 2 affected files, re-read at step 2a from the plan | files:<n> | R1 |
| more than one task in the wiki-plan task table | step 2a | tasks:<n> | R1 |
| no signal and Size verdict small | — | none | R0 |
The tier is the max-of-signals: the highest Floor any single signal sets is
the tier; signals are never summed, because a sum lets several low signals
dilute one payment-path hit into R1.
Phase 2 sets the initial tier from the file and graph signals; step 2a
re-reads the four plan-derived signals (size:large, no-wiki:<n>, files:<n>, tasks:<n>) and may only
RAISE the tier — record each raise on the blackboard as
`- [<task>] Ruling: risk <old>-><new> — <signal> — <cost if wrong>` and
rewrite graph.json; a tier is LOWERED only by the user at Gate 1 answering
revise.
**Reference study (the `inspect` role).** When a task mirrors a behavior an
existing product already has and the goal or issue names that product as the
reference, run the study now, before Gate 1, so its tier and licence outcome
sit on the Gate 1 risk table. Write the brief (the product — name, version,
where it runs — and the behaviors to observe, one line each with its oracle
question) to `{ORCH_DIR}/reference/<product-slug>-brief.md` and run, in the
background, `sh ${CLAUDE_PLUGIN_ROOT}/scripts/reference-study.sh --brief <that
abs path> --slug <product-slug>`: with the `inspect` role unset (`default`)
the script starts a headless study session whose only MCP server is the pinned
REA, so nothing is registered and this session never loads the tool; it
supplies the rest of the study brief from
`${CLAUDE_PLUGIN_ROOT}/references/tool-profile.md` (`### inspect`) — the
absolute path of the licence table
`${CLAUDE_PLUGIN_ROOT}/wiki/qa/exploratory/behavioral-spec-from-a-reference-product.md`,
whose row is settled BEFORE the first capture (no matching row, or a row that
forbids a driven browser or capture tooling: capture nothing, return
`licence: unresolved` with `rows: 0`); the trail dir
`<checkout>/.claude/tmp/reference/<product-slug>/` once `git check-ignore -q
.claude/tmp` exits 0 (else pass `--out <abs dir in the session scratchpad>`),
one study per product shared by every task that mirrors it, holding the
captures, the trail (tool calls, files read, product version, licence outcome,
`## Fingerprints`) and `rows.md` in the `### Reference study` table format of
`templates/analysis.md`; and the fixed report it prints: `product: <name
version>` / `licence: <table-row outcome | unresolved>` / `tool: <tool used |
none (black-box)>` / `rows: <n>` / `unknowns: <n>` / `rows file: <abs path>` /
`trail dir: <abs path>`. When the role is configured to an MCP you registered
yourself, spawn one fresh-context `general-purpose` Agent per product with the
full brief instead — it inherits this session's MCP tools and you never call
them yourself. A `rows: 0` report, `licence: unresolved`, a script exit of 3,
4 or 5, or `tool: none` with a configured role (the MCP was not connected at
session start) is a Gate 1 question, not a silent drop. On one or more rows, add
`reference-study` to each consuming task's `risk_basis` (floor R2) and keep the
report beside the task on the blackboard; at step 2a pass the rows file to the
task-analyst as a pointer file — the analyst copies the rows into
`### Reference study` and never calls the tool; at Phase 4 the task reviewer's
brief carries the report's `trail dir` for the fingerprint grep
(`wiki/infrastructure/agent-orchestration/reference-study-in-a-plan.md`).
**Tier to pipeline profile.**
| | R0 trivial | R1 normal | R2 high | R3 critical |
|---|---|---|---|---|
| planning | wiki-plan lite | full A/B/C | full A/B/C, plan-reviewer required | R2 plus a second plan-reviewer call with the Agent model override `fable` |
| analysis agent — wiki-plan Phase A, claude-fable-5-1 | `task-analyst-r1` (high) | `task-analyst-r1` (high) | `task-analyst` (xhigh) | `task-analyst` (xhigh) |
| design agent — wiki-plan Phase B+C, claude-opus-5-5 | `task-planner-r1` (high) | `task-planner-r1` (high) | `task-planner` (high) | `task-planner` (high) |
| worker model (DEV_LOOP_WORKER_MODEL) | claude-sonnet-5-5 | claude-opus-5-5 | claude-opus-5-5 | claude-opus-5-5 |
| worker effort (DEV_LOOP_WORKER_EFFORT) | high | high | high | high |
| QA agents — task review and coordinator auditor cross-call, claude-fable-5-1 | `task-reviewer-r1` (high) | `task-reviewer-r1`, `test-quality-auditor-r1` (high) | `task-reviewer`, `test-quality-auditor` (high) | `task-reviewer`, `test-quality-auditor` (high) |
| final review agent — Phase 5, claude-fable-5-1, picked by the run's highest task tier | `integration-reviewer-r1` (xhigh) | `integration-reviewer-r1` (xhigh) | `integration-reviewer` (max) | `integration-reviewer` (max) |
| brief effort_level | simple | medium | complex | complex |
| review lenses | 1, 3 and 6 only | 1-4 and 6 | 1-6 | 1-6 plus the adversarial-change-review techniques recorded under lens 5 |
| coordinator auditor cross-call | none (floor only) | when tests look weak | mandatory | mandatory |
| rework budget | 1 | 3 | 3 | 3 |
| human gates | Gate 1 and 2 | Gate 1 and 2 | Gate 1 and 2 | Gate 1 and 2 (a per-task pre-merge gate is deferred, issue #192 section 9 question 1) |
R0 reuses wiki-plan lite mode as its definition — no new concept; every
number above lives only in this table and the prose cites the table. The
"coordinator auditor cross-call" row states only Phase 4's cross-call
obligation on the coordinator side — the worker's own step 6.5 auditor call
is unchanged at every tier.
Each agent row names the file to call; the parenthesis is the effort its
frontmatter pins, next to the model it pins. Effort lives only in an agent's
frontmatter — the Agent tool overrides `model` per call, never `effort` — so
each role has a base file (R3 and R2) and a generated `-r1` copy one effort
step lower (R1 and R0); edit only the base file and re-run
`scripts/gen-agent-tier-variants.sh`. **Floor:** every analysis, design, and
QA agent — `plan-reviewer` included, which pins claude-opus-5-5 at high —
runs at claude-opus-5-5 or claude-fable-5-1 and at high effort or above at
every tier, so an `-r1` copy never steps below high and the worker effort
stays high, the level its step 6.5 self-audit inherits. The launch scripts
hand the worker its effort as `CLAUDE_CODE_EFFORT_LEVEL`, not `--effort`,
because a skill's `effort` frontmatter (loop-implement pins `high`) overrides
`--effort` but not that variable. The variable also outranks every subagent's frontmatter, so
the worker's own step 6.5 self-audit — the base `test-quality-auditor`, the
one agent the worker prompt names — runs at the worker's level, which is the
QA row's level at every tier; the `-r1` auditor is the coordinator's
cross-call.
**A 429 is not a verdict.** When any of these agent calls fails with an HTTP
429 naming a model limit (e.g. a Fable limit), re-run the same agent with the
Agent tool's `model` override set to whichever of `opus` and `fable` the 429
does not name, and escalate to the user when that also fails — never retry on
`sonnet`, which is below the floor. The override changes the model only; the
agent file's effort still applies.
For the same reason as the worker's variable, start the coordinator with
`CLAUDE_CODE_EFFORT_LEVEL` unset: set there, it flattens every agent's pinned
effort to one level.
Waves are **an illustration in the Gate 1 report, not an execution unit.**
Execution is decided by `ready-set.sh`: a task runs as soon as its dependencies
are `approved` and a slot is free. Still topologically sort — the result shows
the user the expected flow — but nothing waits on a Wave boundary.
**Propose the slot count.** Pick the number from the task count, their size, and
their risk, and **say what the number protects**: this cap guards **coordinator attention** and **API usage/budget**, not machine resources. Neither is
queryable, which is why it is a judgement rather than a computation. A slot is
held from dispatch until the task reaches a terminal state — `plan_ready` and
`impl_done` (review pending) count as held, because a pile of unreviewed tasks
next to a stream of new ones makes the cap meaningless. When `LO_MAX_SESSIONS`
is set it is an upper bound and overrides the proposal.
After writing it, run `scripts/ready-set.sh <graph> <status-dir> <cap>` once and
confirm it does **not** exit 4 — malformed JSON, a missing `.tasks` array, and a
dependency naming an undefined task are all caught here.
**Visual spec (`design` role).** While extracting the above, flag each task that is
UI-facing *and* whose source issue references a design (e.g. a Figma link). If the
`design` role is configured, pull that task's spec with it (don't guess from the
link) and carry it into the brief's `<design_spec>` (Phase 3 step 2). Backend-only
tasks, or any task with no design reference, skip this. With `design` unset, ignore
design links entirely — the original behavior.
## 🚦 Gate 1 — task-split approval (REQUIRED)
Report the task list, the dependency graph (showing the expected flow as Waves is
fine), the proposed **slot count with its rationale and what it protects**, and a
rough cost note. The briefing also carries the risk table, one row per task with
exactly the columns | task | risk | basis | profile (plan depth / worker model /
review lenses) | rework budget |, filled from the Tier to pipeline profile
table (a `reference-study` basis cell also names the product and version, the
licence-table outcome and the row count); this adds no AskUserQuestion question — a tier change is requested
through the existing revise answer. That report is the briefing; the approval itself is **one
AskUserQuestion call** (§ Asking the user) in the same turn — Q1 the task split
(approve as proposed / revise / abort). Bundle every remaining open decision
(task-set options, substrate choice) into that same call as further questions,
each with a recommended answer — never a separate turn per decision, never a
prose question. **Wait for the user's approval** before launching anything.
**Substrate — ask here, in this same turn.** Before writing that report, run
`scripts/orca-detect.sh`. Non-zero (no Orca): tmux, silently — say nothing about
substrates. Exit 0: report that Orca was detected and carry the choice as a
**question in the same AskUserQuestion call** as the split approval, options
— **Orca**: native trust-screen handling, event-driven waits, native
liveness; **tmux**: mid-flight steering via `send-prompt.sh`, no extra dependency. **Wait
for the user's answer**; their answer decides, and you carry it into Phase 3. A
detected Orca always asks — there is no default, no remembered choice, no
environment override. Launch nothing until both the split and the substrate are
answered.
## Phase 3 — Launch + plan (dispatch loop)
**Phases 3–4 are one dispatch loop, not a per-Wave repeat.** Each round:
1. First `scripts/collect-status.sh .orchestration/graph.json .orchestration/status
.worktrees` (pulls in any worker-local record `watch-status.sh` has not yet
polled since the last round — `ready-set.sh` reads the status dir directly, it
does not poll). Then `scripts/ready-set.sh .orchestration/graph.json .orchestration/status <cap>`
→ **0** dispatch the printed ids, **2** nothing dispatchable but work is in
flight (go wait for an event), **3** **DEADLOCK** — a failed dependency or a
cycle: **do not wait**, report it and get a human decision (with no worker
running, no event can ever arrive); after the human intervenes, return to
step 1 to re-run the check, **4** the graph or status could not be read —
refuse, do not guess; fix the error then re-run step 1, **5** every task is
in a terminal state → go to Phase 5.
2. For each dispatched task (`<N>` = the number of tasks in this round):
- tmux: **0** (Preceding-interface injection) + steps **1–3** below (setup,
brief, launch, watch plan_ready). Orca: **O1–O5**.
- **1** `scripts/setup-worktrees.sh <integ> <root> <base> <branch>...` then
verify with `git worktree list`.
- **2** Per task: write `briefs/<task>.md` (templates/brief.md) — fill
`<tools_guidance>` and `<design_spec>` — then launch session and watch
until `plan_ready` (step 3 below). **Write the brief at dispatch time.**
It only needs the signatures this task consumes, and by then those are
`approved`, so they're settled. When `explore` is graphify, the
`<tools_guidance>` row is: `explore: graphify — graphify explain
"<Symbol>" --graph <main-root>/graphify-out/graph.json | head -40 (lead,
not evidence; the graph reflects the integration base, and a worktree
carries no graphify-out)` with `<main-root>` the absolute main-checkout
path.
- **3** Collect `plans/<task>.md` when each session reaches `plan_ready`.
3. For each planned task, deliver §2 (implement) with `scripts/send-prompt.sh
send lo-<n> "<prompt>"` (tmux, see Phase 4 for exit-code branch logic), or
`orca orchestration task-create` the implement Task then
`scripts/orca-worker-start --task <impl_task> --terminal <handle> --worktree
id:<repoId>::<path>` (Orca; a bare `--terminal` with no `--worktree` is
rejected — `terminal_worktree_mismatch`, see O3).
On delivery failure, re-run step 3 after fixing the error.
4. Wait for event. tmux: `scripts/watch-status.sh --tasks <running ids>
<status-dir> impl_done <N>` — without `--tasks` the tasks approved in
earlier rounds satisfy `expected=<N>` immediately and the wait spins. Orca:
`scripts/orca-wait.sh` with the implement Task ids, already event-driven.
5. On wake, handle that task: run the Phase 4 review — `test-floor.sh`, then
the `task-reviewer` agent — and read the verdict line of
`reviews/<task>-rN.md` (`head -1`). If tests weak, audit with
`test-quality-auditor`. **On
approval, merge before you loop (issue #90):** fast-forward first —
`git fetch . <branch>:<integ>` (no checkout needed, works while the main
worktree sits on another branch) — and only fall back to
`scripts/safe-cleanup.sh merge <root> <integ> <branch>` when that is not
fast-forwardable (that verb DOES check out `<integ>` in the main worktree).
Either way, verify the merge landed with `git merge-base --is-ancestor
<branch> <integ>` before dispatching any dependent — that exit code is the
evidence, not the merge command's own chatter. Then append one line to the
blackboard with the shell append primitive, never Write/Edit — see
**Blackboard** below: `printf '%s\n' '- [<task>] merged: <outputs> now on
<integ>' >> .orchestration/notes/decisions.md`. Then return to step 1:
whatever dependency it released shows up in the next
`ready-set.sh` round already merged, and the freed slot refills immediately.
On rework needed, run
the Phase 4 rework sequence — `status-update.sh <task> rework`, read the
new `.attempt`, write `reviews/<task>-rN.md`, re-deliver with
`send-prompt.sh send` (or a new Orca Task on the same terminal). The
rework budget is `ready-set.sh`'s job (`LO_MAX_REWORK`); exhaustion
surfaces as exit-3 DEADLOCK, handled at step 1.
When `ready-set.sh` returns **5**, go to Phase 5.
**Session knobs (tmux substrate, set once per run):** `export LO_RUN_ID=<short-run-id>`
so every `launch-session.sh` gets a collision-proof name `lo-<n>-<run-id>` (reuse that
exact name for later `send-prompt.sh`); the script also exports the guardrails
escalation env into each worker. Every `watch-status.sh` call pulls each worker's
worktree-local `.orchestration/status` (and `questions/`) records into the
canonical dir automatically, once per poll (issue #167 — workers never write into
this checkout). It reads `LO_GRAPH` and `LO_WORKTREES_ROOT`; when either is unset
or empty it derives the default from the status dir — `<status-dir>/../graph.json`
and `<status-dir>/../../.worktrees` (issue #277) — and uses it when that path
exists, so exporting `LO_GRAPH=.orchestration/graph.json
LO_WORKTREES_ROOT=<root>/.worktrees` once per run is optional, and an exported
value always wins over the derived one. When a default path is missing, the watch
prints one `collection off` warning line on stderr at start-up and runs without
collection: treat that line as a wrong status-dir argument or a missing graph or
worktrees path, not as a slow worker. It also collects
`blocked/` records (the `worker-blocked-signal.sh` hook) the same way, except a
canonical `blocked/<task>.json` is pruned once its worker-side copy is gone —
see exit 8 below. `ready-set.sh` reads the
status dir directly and does not poll, so before every `ready-set.sh` round also
run `scripts/collect-status.sh .orchestration/graph.json .orchestration/status
.worktrees` yourself (Phase 3 step 1). Trust-screen wording drifts between CLI releases —
if a launch hangs, set `LO_READY_EXTRA` (substring) or `LO_READY_TIMEOUT`; for a
screen that needs an answer, set `LO_TRUST_EXTRA` (a substring of that screen) and
`LO_TRUST_KEYS` (the keys sent when it matches, space-separated, from `Up Down Left
Right Enter Escape Tab Space 0-9 y n`; default `Enter`; any other key is refused with
exit 2). Keep the default `Enter` only for a screen whose highlighted default is safe:
on a screen highlighting "No, exit" or an option that changes a user setting, Enter
quits the worker or picks that option, so set `LO_TRUST_KEYS` to the keys that reach
the safe option. `LO_PASTED_TAIL_LINES` (default 40) is `send-prompt.sh`'s
fallback pasted-marker window, scanned only when it cannot locate the input box
in the pane capture — raise it if a CLI release changes the input-box chrome so
the box stops being locatable. `send-prompt.sh send` pastes any payload of
`LO_PASTE_THRESHOLD` bytes or more (default 800) as one bracketed tmux paste
and waits `LO_PASTE_SETTLE` seconds (default 2) before the submit key; after a
delivered verdict it confirms receipt against the worker's newest transcript
for up to `LO_RECEIPT_TIMEOUT` seconds (default 10; 0 disables) —
`LO_TRANSCRIPT_DIR` overrides the derived `~/.claude/projects/<mapped worktree
path>` location — and `state`/`send` recognise a mid-turn worker by
`LO_BUSY_REGEX` (default: the CLI's elapsed-time spinner suffix or the legacy
`esc to interrupt`) plus the optional fixed-string `LO_BUSY_PATTERN`.
`status-update.sh` resolves the status file's `session` field
from `tmux display-message -p '#S'` only when the caller is itself inside tmux
(`$TMUX` set) — a coordinator-side call (this shell, not a worker's tmux pane)
must pass `STATUS_SESSION=<lo-n-runid>` explicitly, or the record's `session`
field is left absent rather than guessed from whatever tmux session happens to
be active.
`watch-status.sh` now exits **5** on a pending guardrails escalation, one line per
record naming its `recorded <ts>` next to the task's current `phase @<updatedAt>` —
triage from that line alone: if the phase transition is LATER than the record, the
worker already moved on by bypassing the denial, so `rm` the record WITHOUT
delivering an answer (nothing is waiting for it). Otherwise the worker is still
waiting: approve/deny, then `sh {SKILL}/scripts/resolve-escalation.sh <escdir>
<task> lo-<n> "approved — re-run: <cmd>, then continue"` (or `"denied —
<alternative>"`) — it clears the record(s) and delivers in one pre-approved
call; the guardrails deny message told the worker the orchestrator would
re-run it, so a cleared escalation without a delivered answer leaves it
waiting forever. On exit 6, retry delivery directly with
`scripts/send-prompt.sh send lo-<n> "<same message>"` — then relaunch. Exits **3** on a failed
OR a *dead* worker (a non-terminal task whose tmux session vanished — recorded via
the status file's `session` field) — both abort fast instead of waiting the
timeout. It also exits **6** on a pending worker question, **7** on a live worker
whose pane is stalled, and **8** on a blocked worker (a
`.orchestration/blocked/<task>.json` record from the
`worker-blocked-signal.sh` hook, confirmed by a pane that stayed unchanged
across two polls) — playbooks in Phase 3 step 3. It presses Enter itself
when a worker's input box holds an unsubmitted paste on two consecutive
polls, unless `LO_AUTO_RECOVER` is `0`, `off`, or `false`;
`LO_AUTO_RECOVER_MAX` (default 3) bounds those presses per session per watch
process, and a malformed value is refused with **exit 4**. Give each
phase its own deadline with one exported
`LO_PHASE_TIMEOUTS="plan_ready=900,impl_done=3600,done=1800"`, keyed on the TARGET
phase of each wait: precedence is an explicit `[timeout-sec]` argument, then the
matching entry, then the 3600s default. A malformed entry (no `=`, non-numeric,
`<= 0`, or an unknown phase name) is refused with **exit 4**, never silently
defaulted; the effective budget and its source are printed before the wait.
`LO_MAX_REWORK` (default 3) is the rework budget `ready-set.sh` enforces —
same validation as `LO_MAX_SESSIONS` (empty/non-numeric/`<= 0` refused with
**exit 4**).
**The coordinator shell may be zsh:** zsh (the macOS default) does not
word-split unquoted parameter expansions the way bash does, so a bash-style
loop such as `for pair in "$name $task"; do launch-session.sh $pair; done`
silently passes the whole `"name task"` string as one argument instead of
splitting it into two. Launch each task with its own explicit
`launch-session.sh` call, arguments spelled out per task, never through a
splitting loop. `launch-session.sh` now fails fast against exactly this class
of bug: it exits **2** before any tmux call when the final session name
(after the `LO_RUN_ID` suffix) is empty or contains a character outside
`[A-Za-z0-9_-]`, when the worktree argument is not a git work-tree root, or
when exactly one of `LO_STATUS_DIR`/`LO_TASK_ID` is set (set-but-empty counts
as unset). A malformed caller now gets an immediate exit 2 instead of a
silently launched broken worker.
**Substrate (the user decided at Gate 1 — do not re-decide here):** the answer was
Orca or tmux. **Orca** → spawn **and supervise** workers through it, not raw tmux:
it resolves the trust/TUI screen, gives native liveness, and pushes worker events to
you instead of making you poll. Replace steps 1–3 below with O1–O5:
- **O1 — bind the Run once per orchestration run.**
`orca orchestration run-create --objective "<goal>" --json` → keep `run_id` for the
whole run (on re-entry, `orca orchestration run-use --id <run_id> --json` instead).
- **O2 — one Task per task-*phase*.**
`orca orchestration task-create --spec "<the prompt>" --task-title "<short>" --json`
→ `task_id`. Use `templates/session-prompt.md` §O1–§O4 as the `--spec` body; the
tmux §1–§4 one-liners are for `send-keys` and say "wait", which is wrong here.
A `worker_done` settles a Task exactly once, so plan / implement / rework are
separate Tasks. **You sequence them yourself** — dispatch phase N+1 only after
phase N reads `completed`. Do *not* chain with `--deps`: it takes a JSON array
(`--deps '["task_x"]'`; a bare id errors), and even then a task created that way
came back `task_not_startable` with its dependency already `completed`
(isolated: an identical task with no deps started fine on the same terminal).
- **O3 — start the worker.** First make sure the integration branch exists in the
main repo (`git branch <integ> <base>` if it does not) — the tmux path gets this
from `setup-worktrees.sh` step 1, this path does not. Then create the Orca
worktree **from that branch**: `orca worktree create --repo id:<repoId>
--name <task> --base-branch <integ> --no-parent --setup run --json` → copy the
whole `worktree.id`. `--base-branch` is **not optional here**: omit it and Orca
branches from the repo default (its documented fallback), so a Wave-2 task would
not build on Wave 1's merged output and Phase 6's merge would drag in unrelated
default-branch drift. Then scope guardrails inside it — **required, not a
nicety** — with `scripts/worker-guardrails.sh <worktree-path>`, the same
single-source script `setup-worktrees.sh` calls on the tmux path. Skip it and
the worker inherits the *repo/global* rules instead of the sandbox ones, so
routine in-worktree work (`rm -rf ./build`, `git checkout .`) turns into a
`deny` + escalation and the worker stalls on the coordinator for every one of
them. Then, with the escalation env exported:
`GROUNDWORK_ESCALATION_DIR=<abs> GROUNDWORK_TASK_ID=<task>
DEV_LOOP_WORKER_MODEL=<id from the profile table> DEV_LOOP_WORKER_EFFORT=<level from the profile table>
scripts/orca-worker-start.sh --task <task_id> --worktree id:<repoId>::<path>
--agent claude` → prints `dispatch=<id>` and `handle=<agent-handle>`. For this
task's **next** phase pass `--terminal <handle>` **together with** `--worktree
id:<repoId>::<path>` instead, so the session keeps its context — a bare
`--terminal` with no `--worktree` is rejected with `terminal_worktree_mismatch`,
because Orca resolves a bare terminal handle against the *caller's* own
checkout, not the worker's (measured: run_08cb6f65cbfa, 2026-08-29, and one
prior run). `worker-start --agent` alone cannot carry environment variables, so with
the escalation env set the script creates the agent terminal itself
(`terminal create --command`, the escalation contract + `--permission-mode`) and
binds the Dispatch to it; that is why the worktree must exist first and why
`new-child` / `new-top-level` are refused in this mode.
Bare `worktree create` leaves one unused fallback shell beside the agent
(measured: 3 workers → 4 terminals). After the worker is up, confirm with
`orca terminal list --worktree id:<...> --json` that the extra handle is an idle
shell — not a configured default tab — and close just that one with
`orca terminal close --terminal <handle> --json`.
A `worker-start` that fails **spends the Task**: it goes to `status=failed` and
every later attempt on it returns `task_not_startable`. Do not retry the same
Task — create a fresh one with the same spec. (Seen with `runtime_unavailable`,
which is what you get when that terminal is still busy with another Dispatch.)
The **not-spent exception**: `terminal_worktree_mismatch` (above) fires
*before* dispatch — Orca rejects the bad `--terminal`/`--worktree` pair before
ever handing the Task to a worker — so the Task stays `ready`, not `failed`,
and MAY be retried on the same Task with corrected args. The spent rule
applies to failures at or after dispatch (e.g. `runtime_unavailable`).
- **O4 — wait on pushed mail, not on a timer.** Workers on this substrate also
write status worker-locally (issue #167) — Orca's own mailbox is not that
channel, so after EVERY `orca-wait.sh` return, before acting on the events,
run `scripts/collect-status.sh .orchestration/graph.json .orchestration/status
.worktrees` to pull those records into the canonical dir.
`GROUNDWORK_ESCALATION_DIR=<abs> scripts/orca-wait.sh [--until-all] <timeout-ms>
[<task_id,task_id,...>]` → **0** completions arrived (acked — process them),
**2** window elapsed *or* the ack did not land (checkpoint, just re-run), **3** a
worker reported failure, **4** the runtime itself did not answer (`ok:false`, a
nonzero status, or a connection lost mid-wait) — an **outage, not a checkpoint**:
run `orca status --json` before waiting again, and restart nothing on this code
alone, because a dead runtime does not stop a worker session (measured: workers
kept committing and pushing while the runtime was down), **5** escalation
pending (approve/deny, then **`sh {SKILL}/scripts/resolve-escalation.sh
.orchestration/escalations <task>`** — no delivery args on the Orca path,
since answers go through orca, not send-prompt.sh; use the 2-arg form — then
re-run — like watch-status, code 5 recurs while a record is still on disk,
by design), **6** question pending
(`orca orchestration reply --id <msg_id> --body "<answer>" --json`, re-run).
**Always pass this Wave's task ids — that is correctness, not a progress
nicety.** Heartbeats reach this mailbox despite `--types`, and so do completions
from an earlier Wave or an unrelated Task; without the ids none of that can be
told apart from your own work. With them, exit 0 means a *successful
`worker_done` for one of your ids* and the `completed=<c>/<n>` line is scoped to
this Wave. Add `--until-all` to keep consuming batches until every listed id is
completed, so one Wave costs one coordinator turn instead of one per batch; it
still returns immediately on 3/4/5/6. Codes 3/5/6 leave the batch unread on
purpose, so an unhandled event is never silently dropped — which also means
delivery is **at-least-once**: a replayed batch must be processed idempotently
(key off `taskId`, never off a local counter). `ORCA_WAIT_RECHECK_MS` (default
15000) slices the wait so a guardrails record written *while* you are blocked
surfaces within one interval instead of one full `<timeout-ms>`. When polling
ANY inbox on this substrate, diff the SET of message ids you have already
processed, never the count — a new message can arrive in the same interval
another one leaves, leaving the count unchanged while the content changed.
- **O5 — liveness, in two questions.** `scripts/orca-worktree-alive.sh <wt>`
(0 alive / 1 dead / 2 unknown — treat unknown as *not* dead) replaces watch's
tmux check. It only asks whether a terminal is attached, which a wedged worker
passes: measured, three workers sat on an interactive CLI prompt for 75 minutes,
ALIVE the whole time, Tasks still `dispatched`, no escalation, diffs unchanged.
So also run `scripts/orca-worker-stalled.sh <wt>` (0 progressing / 1 stalled /
2 unknown — treat unknown as *not* stalled; `ORCA_STALL_MS`, default 600000).
A stall is not a failure to act on blindly: read the worker's screen
(`orca orchestration worker-read --dispatch <id> --limit 40 --json`) before you
decide, because "wedged on a prompt" and "finished but never reported" look the
same from the outside and need opposite responses. When the screen shows the
worker parked on a permission dialog, `orca terminal send --terminal <handle>
--text "2" --enter` clears it — decline (2) is the safe answer; granting the
permission on the user's behalf is not something the coordinator does
unattended.
**You cannot steer a running worker.** `orchestration send --to dispatch:<id>`
lands in the worker's mailbox, which a Claude worker never polls, and a new
Dispatch cannot be delivered while the current one runs (that is O2's
`runtime_unavailable`). So a mid-flight correction does not arrive: the supported
path is the Phase-4 review/rework round. (If you do send one, omit `--type` —
`note`/`guidance`/`message`/`info` are all rejected as `invalid_argument`.)
**Worker protocol on this substrate — put this in every `--spec` you dispatch.**
The worker still calls `status-update.sh` at each phase (the status files remain the
durable re-entry state); on top of that it must:
1. report the phase exactly once — `orca orchestration send --type worker_done
--subject "<status>" --body "<what changed, what remains>" --task-id <task_id>
--dispatch-id <dispatch_id> --outcome succeeded|failed --files-modified "a,b" --json`
(a failure is `--outcome failed`, never failure encoded only in prose);
2. forward a guardrails escalation instead of stalling on it — when a command is
denied with an escalation notice, `orca orchestration send --type escalation
--subject "guardrails <rule>" --body "<command + why>" --task-id <task_id>
--dispatch-id <dispatch_id> --json`;
3. use `orca orchestration ask --question "<q>" --timeout-ms <n> --json` for a
blocking question, and then end its turn — and if that window expires, resume the
same question with `ask --resume <message_id>` rather than deciding it or asking
it again. A timeout leaves the question pending; it is not an answer. Measured on
a 3-worker run: at 600s and 900s both workers instead "proceeded on a conservative
assumption" and reported the guess after the fact.
Step 2 is the *fast* path for a guardrails block — it arrives with the worker's own
context. It is not the only one: `orca-wait.sh` pre-checks
`GROUNDWORK_ESCALATION_DIR` before it blocks, so a guardrails record still surfaces
when the worker never sends the message (it died, or it is not a Claude session).
Export that dir for both scripts and the file stays the safety net the tmux path
already relied on.
If the user chose tmux at Gate 1 (or `orca-detect.sh` was non-zero), use the tmux
`launch-session.sh` + `watch-status.sh` path below, unchanged. Always verify each
Orca `--json` result before relying on its fields (`worker-start` returns
`.result.dispatchId`, and the agent handle as the `role:"agent"` entry in
`.result.effects[]`). `orca-spawn.sh`
remains only for a worker needing custom agent argv (e.g. codex `--model` /
reasoning-effort flags) that `worker-start` cannot express.
0. **Preceding-interface injection (Wave 2+, and completed base outputs):** before
launching this Wave, fill each task's brief `<dependencies>` with the **exact
signatures** of (a) the approved preceding Wave and (b) any completed (partial-
resume) child it depends on — the real signature, not a paraphrase. This is the
contract the downstream session plans against; loose text invites drift. Wave 1
with no completed dependencies skips this.
**What a `deps` edge delivers, and what it does not (issue #90).**
`graph.json` `deps` gate DISPATCH on the dependency's approval, and this step
injects its SIGNATURE — never its merged CODE. Merged code reaches a task's
worktree only through the merge-on-approval rule (step 5 below): a new
worktree branches from the integration branch's tip at the moment
`setup-worktrees.sh` runs (step 1), so it contains a dependency's code only
if that dependency was already approved and merged by then. A task that must
read merged results directly — realigning docs against another task's actual
diff, asserting an invariant that spans two tasks' code — cannot rely on the
signature alone: give it `deps` on every producer it reads, so it is not
dispatched until each producer is approved and merged.
**Contract-first dispatch (shared surfaces) — ordering exception.** A task
that PRODUCES a shared surface (Phase 2) reorders its own steps so the stub
it commits can quote a real signature and land before its own worktree
exists: run step 2a's `wiki-plan` invocation for this task FIRST (on the
`task-analyst` agent, then the `task-planner` agent) — it writes `plans/<task>.md`, but do not launch yet
— then commit the stub below, THEN
step 1 (`setup-worktrees.sh`, whose worktree now branches from a tip that
already contains the stub), then step 2 (write the brief, referencing the
already-written plan) and launch. A consumer task needs no reordering of its
own: by round/dependency ordering its step 1 always runs after the
producer's stub commit has landed, so its worktree inherits the contract
normally.
Commit the stub in a temp integ worktree: `git worktree add
.worktrees/integ-stubs <integ>`, write the stub file(s) at the plan-named
repo-relative paths — the exact signature `plans/<task>.md` step 2a just
decided, plus a `// contract: <task> owns the implementation` marker comment
(in the stub language's comment syntax), never implementation — commit
`chore(orchestrate): contract stubs for <task>`, then `git worktree remove
.worktrees/integ-stubs`. The producer's brief says it IMPLEMENTS the stub in
place, not create it fresh. A producer that must change a committed stub's
signature reports that as a plan gap: you re-decide, recommit the stub, and
notify every consumer via the blackboard (append-only, shell `>>` primitive
— see **Blackboard** below).
1. `scripts/setup-worktrees.sh <integ> <root> <base> <branch>...` — each worktree
is created AT DISPATCH TIME, branched from the integration branch's CURRENT
tip; n
[…] pełny plik w paczce .zip
Files in this package (28)
- SKILL.md 99 KB
- scripts/ask-coordinator.sh 2 KB
- scripts/collect-status.sh 7 KB
- scripts/escalation-dir.sh 1 KB
- scripts/graph-add.sh 5 KB
- scripts/graph-drop.sh 4 KB
- scripts/install-permission-rules.sh 5 KB
- scripts/launch-session.sh 20 KB
- scripts/orca-detect.sh 1 KB
- scripts/orca-spawn.sh 7 KB
- scripts/orca-wait.sh 14 KB
- scripts/orca-worker-stalled.sh 5 KB
- scripts/orca-worker-start.sh 18 KB
- scripts/orca-worktree-alive.sh 1 KB
- scripts/ready-set.sh 7 KB
- scripts/resolve-escalation.sh 3 KB
- scripts/safe-cleanup.sh 23 KB
- scripts/send-prompt.sh 28 KB
- scripts/setup-worktrees.sh 3 KB
- scripts/status-update.sh 3 KB
- scripts/test-floor.sh 9 KB
- scripts/tmux-worker-stalled.sh 6 KB
- scripts/token-report.sh 8 KB
- scripts/watch-status.sh 25 KB
- scripts/worker-guardrails.sh 10 KB
- templates/brief.md 6 KB
- templates/review-report.md 2 KB
- templates/session-prompt.md 18 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · choiyounggi/dev-loop | 91 | MIT |
| kriegcloud/beep-effect | 100 | Apache-2.0 |
| zahidakhyar/skills | 100 | MIT |
| jkaloger/lazyspec | 100 | MIT |
| superset-sh/superset | 100 | MIT |
| boshu2/agentops | 100 | Apache-2.0 |
| Ovich/charrette | 100 | MIT |
| matthew-eth724/orchestrate | 100 | MIT |
| nickthelegend/nick-skills | 100 | MIT |
Database snapshot: 13.11.2026 · package version e12f38e65d62 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100boss
Use ONLY when the user explicitly asks to orchestrate parallel external agents (Codex or Claude Code) in tmux sessions via tp (tmux-pilot). Or when a user tells you that you're the boss or orchestrator. You can also use this if you are an operclaw agent. NEVER auto-invoke for a… - 100agentrc
Orchestrate multiple Claude Code workers in tmux panes. Use when the user wants to run parallel tasks, dispatch workers, or manage a multi-agent workflow. - 100plan-orchestrate
读取计划文档,将其分解为步骤,从 ECC 目录中为每个步骤设计智能体链,并生成可直接粘贴的 /orchestrate 自定义提示。仅生成 —— 从不调用 /orchestrate 本身。当用户有多个步骤的计划并希望通过 orchestrate 驱动而无需手动组合链时使用。 - 100parallel-work
Splits a request into independent tasks, runs them in parallel worker sessions (each edit task in its own git worktree), then collects the reports and, after confirmation, commits, merges, runs the integrated check and cleans up. Use for "run these in parallel", "split these… - 100loop
Orchestrate a goal through subagent iterations. Use when the user gives a goal to run "the loop" on — decomposes the goal, dispatches one subagent per iteration with fresh context, verifies each result before memory is committed. - 100tabs
Use when the user asks to "list my claude sessions", "which windows are waiting", "/ar:tabs". Discovers Claude sessions across tmux windows and reports which need attention.