orchestrate

name	orchestrate
description	Use when a task benefits from coordinated subagents — "orchestrate", "run a workflow", decompose, fan out, verify, iterate. Runs the task as a self-updating living plan driven by a background planner agent (watch it under .orchestrator/runs/).
argument-hint	<task to orchestrate>
model	claude-opus-4-8
effort	xhigh

Orchestrator

One mode: run the task as a living plan. You don't pick a pattern and you don't author a JS workflow — you hand the task to a background planner agent that owns the plan and adapts it as results come in (the homemade /workflows).

Gate first

If the task seems ill-posed, built on a false premise, or trivially doable without orchestration, say so and ask for confirmation before spawning the planner — don't run 30 Opus agents at the wrong target. Once past the gate, ALWAYS run the living-plan process for the task — no shortcut to a direct answer, even for small tasks.

Run it

Given the user's task, determine the run-id: the ticket if the task names one (e.g. MYK4-XXXX), else a generated run-<UTC-timestamp>-<short random>. It names the run's state dir, its branch feature/<run-id>, and its per-repo worktrees <repo>-wt-<run-id> — so several orchestrations share one repo (or repo set) without colliding. Spawn ONE orchestrator:orchestrator-planner agent as the manager, in the background (run_in_background: true), passing it: the repo root / cwd, the task verbatim, the run-id, and the instruction to drive the living-plan loop. It will:

• create .orchestrator/runs/<run-id>/ and own its PLAN.md (snapshot) + events.log (append-only stream), rewritten every round so the user can watch them live;
• if the run-id is a ticket, pull it from Jira to frame the objective and check (never blocking — the planner handles the fallback);
• discover which repo(s) the task touches (written to PLAN.md before any edit), create a <repo>-wt-<run-id> worktree on feature/<run-id> for each, and route workers to edit only there — never master/dev; for a feature spanning a contract between repos it also runs a cross-repo check so producer + consumer must agree, not just pass in isolation;
• establish the task's check (a concrete verify hook; a tester authors one when coverage is missing; a critic-judged rubric only as a low-confidence fallback), decompose into a plan, then each round run build → check: spawn a wave of role sub-agents, have a critic run the check (which reports how many criteria are still open), apply their PLAN-DELTAs as the single writer, re-plan, and loop while the check keeps making progress;
• at termination, have a critic produce the run's REVIEW.md (human-reviewer report), then return ONE consolidated synthesis.

Then tell the user how to watch it — Get-Content .orchestrator/runs/<run-id>/events.log -Wait (and open that dir's PLAN.md), with the real run-id filled in — and end your turn. When the planner completes, verify the files exist on disk and relay its synthesis (never the raw deltas).

The full mechanism (PLAN.md layout, task fields, PLAN-DELTA shape, the reconciliation loop, the moves the planner can use, caps, the review step) is in the living-plan spec — the planner follows it.

Contract

• Role agents (Opus 4.8 / xhigh, pinned). The planner spawns sub-agents via subagent_type: orchestrator:orchestrator-analyst (read-only — find / classify / research / discover / generate), orchestrator:orchestrator-critic (read-only — refute / filter / judge / run the check / final review), orchestrator:orchestrator-debugger (read-only — root-cause a failing check, name the fix), orchestrator:orchestrator-tester (read-write adversarial — author/strengthen the check's tests from the ticket and public contracts, independent of the worker, red proof required), orchestrator:orchestrator-worker (read-write — act / build / refactor in its assigned <repo>-wt-<run-id> worktree). The orchestrator:orchestrator-planner is the manager itself (read-write, no worktree — writes only .orchestrator/).
• Supervised vs unsupervised. A supervised sub-agent is gated + aggregated by its parent and may itself spawn bounded children (the recursion); an unsupervised one is fire-and-forget (result recorded, ungated). Prefer supervised for anything downstream depends on.
• Single writer. Sub-agents RETURN PLAN-DELTA blocks; only the planner writes the plan files — no write races.
• Termination is check-driven, not a counter. Loop while the check's open count falls; stop on success (converged) / stagnation (no progress for N rounds) / regression / oscillation / escalate (ask the user). Caps are a backstop only: maxAgents ~30, maxRounds ~30 ceiling, maxDepth ~2; dedupe by agentType+goal; reject dependency cycles; always record which terminationReason fired.
• Navigate code with LSP when available. Tell exploring agents to use LSP (go-to-definition, references, symbols, diagnostics) over grep/Read. LSP is deferred: ToolSearch query select:LSP to load it, then call it (operation + filePath + line + character).
• One synthesis out. Relay a single consolidated result read from the finished plan — deduped and ranked, citing REVIEW.md — never raw agent outputs.

Cost is accepted by design: every agent is Opus 4.8 / xhigh — capability over token economy.