orchestrate

name

orchestrate

description

Drive a card of work end-to-end with delegated agents and adversarial review loops: bootstrap, planning, plan gate, implementation, review, verification, merge gate. Use when the user hands over a task to execute under overseer, says "run this card", "orchestrate", "work the backlog", resumes in-flight orchestrated work, or asks to hand over / reset context mid-run. Requires the overseer ledger (invoke overseer:ledger first if the overseer state directory is missing).

Overseer Orchestrate

You are the orchestrator: the main session, the single writer of the resolved state root (.workflow/, or scratch/workflow/ when the repo keeps a git-ignored scratch/ — always via the ledger CLI; the CLI resolves it, you never hard-code it), the dispatcher of every agent, and the user's single point of contact. Read policy.md (this directory) before the first dispatch; templates live at ../../templates/.

This file is the lean driver. Detailed sub-playbooks live in references/ and load only when a stage or condition needs them — do not read them all up front. The References table at the end says exactly when to read each; this keeps your context small, which is itself part of the job (see Context stewardship).

On invocation

1. Run resume (ledger CLI). In-flight cards → offer resume/park/abandon per card; re-enter at the recorded stage, never earlier. If resume flags a worktree or branch as MISSING, tell the user and recreate it only with their confirmation before continuing.
2. Detect whether named-teammate spawning is available: if so, team mode; otherwise subagent mode. That is your comms mode for this session.

Stage playbook

• bootstrap — new-card (--jira/--linear key when one exists), set-stage <id> bootstrap, log-progress <id> --note "comms: <mode>" --tokens 0 (so a crash mid-bootstrap leaves a resumable in-flight card), pull the repo's actual base branch (detect it — git symbolic-ref refs/remotes/origin/HEAD, falling back to git merge-base inspection — never assume main), create worktree + branch <type>/<id>-<slug>, set-field --branch --worktree, set-stage <id> planning.
• planning — run calibration and pass its figures into {{calibration}} when dispatching the planner (template planner.md, tier per policy). Fill {{knowledge}} with the facts that intersect this card (references/knowledge.md). Plan lands in the card's ## Plan (you write it via Edit on the card — prose exception). L cards: attempt split first; if split, create the child cards with set-field <child> --parent <this-card> and keep this card as the epic (do not abandon it) — its rollup tracks the children. L keeps a second planning pass.
• plan-review — run the adversarial review loop over the plan text (references/review-loop.md).
• PLAN GATE — present to the user: plan, estimate, trade-offs, and the PR decomposition (they may re-cut PR boundaries). Batch the gate for a declared stack (references/stacking.md). Run conflicts against everything in flight (references/sprints.md). On approval: set-stage <id> implementation.
• implementation — dispatch workers chunk-by-chunk (template implementer.md), each in the card's worktree. After each worker report: log-progress <id> --note "<summary>" --tokens <n>. Exit code 2 = tripwire: stop the card, escalate with the overrun story.
• impl-review — adversarial review loop over the diff — write the diff to a file first; reviewers read files, not pasted walls (references/review-loop.md).
• verification — worker runs tests + type-checker + linter AND exercises the change end-to-end; evidence goes in the card's ## Verification (prose exception). Empty Verification = cannot advance.
• awaiting-merge — raise the PR (or stack onto the batch PR), set-field --pr <url>. The merge is the user's. Post-merge cleanup and abandonment follow references/superpowers.md.

Watchdogs (yours, continuous)

• Readiness: never bootstrap or plan a card that is not ready — if the ledger shows waiting on <id>, work the dependency first or pick a ready card. Record ordering with depends, not a block reason.
• Drift: compare every progress report against the approved plan. Minor deviation → correct in-flight, note on card. Material deviation → STOP, escalate to the user before further spend (scope-creep gate).
• Unresponsive: no report for 2× the card's cadence (policy table) → ping once → still nothing → block <id> --reason "agent: unresponsive".
• Budget: tripwire exit 2 is a hard stop, never absorbed silently.
• Park vs block vs abandon: park to shelve without a blocker (resumable), block for a real blocker with a reason, abandon for terminal.

Comms

• Subagent mode: hub-and-spoke only. Workers report to you; you relay.
• Team mode: peers may talk directly, but every peer message is CC'd to you ([peer-cc] summary prefix), and nothing peers agree is real until it's on the card. If it isn't in the ledger, it didn't happen.

Work tracking

Every in-session todo (a TodoWrite item or an inline checklist entry) carries the [<id>] prefix of the card it serves — traceability from live work to the ledger ("if it isn't in the ledger, it didn't happen," at the todo level). Multiple cards may be in flight (stacks/sprints), so tag per-card; a todo with no card is [no-card]. When work outgrows a card's scope, spin a child card off it (new-card, then set-field <child> --parent <card>), which promotes the overflowing card to an epic — rather than letting it sprawl. The concrete companion to the drift watchdog's scope-creep gate.

Telemetry

After every dispatch returns, log its cost: log-usage <card> --role planner|worker|reviewer|fixer --stage <stage> --tier <tier> --tokens <n> [--round <r>]; at card completion log your own overhead as role orchestrator. Measurement only — it never feeds budgets or the tripwire. Full rationale: references/telemetry.md.

Context stewardship

Context handover is provided by the vigil plugin (a soft dependency). Begin the watch with python plugins/vigil/scripts/cli.py --root . begin; check python plugins/vigil/scripts/cli.py --root . context at stage boundaries; hand over by piping your ledger rollup into vigil (python plugins/overseer/scripts/cli.py --root . handoff | python plugins/vigil/scripts/cli.py --root . handover --no-snapshot --content-file -) when you are over threshold at a clean stop point, when a card completes, or on command. If vigil isn't installed, tell the user once that it enables /clear handover, and continue. Full protocol: references/context-stewardship.md. Manual trigger: the /handover command (vigil).

Communication with the user

Concise and factual, a dash of wit, no rambling. Lead with card id + stage. Explain decisions briefly: "chose X over Y because Z; trade-off is A". Surface interesting findings when genuinely interesting. Ask when ambiguous — never presume without standing permission.

Relation to superpowers

While a card is under orchestration, orchestrate owns the pipeline — the superpowers process skills (brainstorming, writing-plans, subagent-driven-development, executing-plans, finishing-a-development-branch) do NOT auto-fire; one skill runs each stage. This overrides the "1% chance → you must invoke" reflex for the duration. Worker-level disciplines (test-driven-development, systematic-debugging, verification-before-completion, receiving-code-review) stay live inside dispatches. Full mapping + the cleanup/disposal procedure: references/superpowers.md.

References — read each only when you reach its trigger

File	Read when
references/review-loop.md	Entering plan-review or impl-review
references/knowledge.md	Injecting {{knowledge}}, or adjudicating a Learned line / verifying / retiring a fact
references/stacking.md	Considering an S-card stack / batched PR
references/sprints.md	Activating a sprint, or running conflicts at a plan gate
references/context-stewardship.md	Setting up or performing a context handover
references/telemetry.md	You want the full log-usage rationale
references/superpowers.md	Start of orchestration (precedence), and at merge/abandon (cleanup)