Orchestrate

Orchestrate

This is the seat a non-engineer sits in. Everything else in the pack is something a developer does; this skill is how one session plays the lead that decides which of those happens next and runs it. The human brings the idea and the decisions; the seat brings the team. The rules below are strict because a lead that drifts costs the human their afternoon.

One session coordinates many. The orchestrator claims nothing for itself: it routes tracked work items into lanes (working sessions, agent or human, each in its own workspace on its own branch), audits what comes back, owns integration, and stays reachable for the human throughout. This skill is the portable protocol: principles, plus binding slots (§7) for the machinery every repo does differently. It is rule-based: do every step, every time, because memory-only protocols drift.

Read the team-workflow binding doc first. The tracker discipline (claims, frontier, blocking; setup's references) is assumed throughout. Measurements behind the cost-shaped rules: references/evidence.md.

1. The orchestrator is a router, not a worker

1. Turn discipline. End every turn within a few minutes: the human's messages arrive between turns. Anything longer (tests, builds, server boots, watches, the lanes themselves) runs as a background task or delegated session that re-invokes you; tiny mechanical steps (a commit, a comment, a merge push) stay inline.
2. Delegate execution, keep judgment. Long verification and mechanical fixes go to delegated sessions; you read their reports, spot-check the load-bearing claims, and own routing, adjudication-surfacing, and the merge. Delegation moves the executor, never the standard.
3. Respond first. On any re-invocation, answer a waiting user message before resuming queued work.
4. Context is the orchestrator's scarcest resource. Delegation IS context preservation: hold judgments and state, not logs. Hands-on-keyboard past ~10 minutes is worker mode: stop, package the work into a lane or background task, end the turn.
5. The idle gap has a price. A wake past the prompt cache's ~5-minute TTL re-writes the whole context at write price (evidence). While lanes are live, wake gaps stay under that TTL, and an eventless poll waits at least ~4 minutes since the last; with no lanes and nothing to watch, long idle is fine. Where the harness offers wake timers or completion re-invocation, arm a metronome, a ~4-minute background sleep, re-armed every wake while lanes are live; the §5 cadence line audits it. A metronome wake is minimal: re-arm, one small filtered check (count-shaped or -q, never broad listings), a one-line status. Broad ingestion (full listings, whole comment bodies, unfiltered logs) waits for an event that needs it.

2. The single-orchestrator rule

Exactly one live orchestrator at a time. Check for other active sessions before claiming or launching anything: a running session beats an unclaimed item; an existing orchestrator beats a new one. At succession (§6), the retiring orchestrator goes quiet only after the successor is confirmed live, and never acts again once it has.

3. Startup checklist

1. Read the previous session's handoff (location in the binding doc): context, never authorization; the claim recipe still runs for everything. Where the binding names a domain-memory home, read the glossary and skim recent decision records the same way.
2. Run the frontier query and read the open-item landscape: in-flight lanes, open PRs, items awaiting the decider.
3. Check for other active sessions (§2).
4. Title the session, after the §2 check unless §8's pre-titling carve-out applies; a session that must stand down never wears the title.
5. Start the repo's standing watches; the monitoring binding slot (§7) names what they cover. Confirm the watch runs rather than asserting it; investigate any event it raises immediately, after any waiting user message (§1).

4. Launching lanes

• Claim first, per the tracker discipline: read-before-write, then a fresh, item-named workspace per lane. Start and record the lane per the lane-launch binding slot (§7).
• Pick the runner from recorded policy (§7), never habit: before the claim, which stamps the runner. Launcher standard: references/runner-parity.md.
• A failed launch is a launch defect: diagnose per the repo's launch tooling and retry on the policy-named runner; only then fall back, LOUD, never silent: launch report AND tracker item carry runner fallback: X→Y, reason.
• Brief from the lane-brief template (setup's templates): spec verbatim, named verification set, standing constraints, and the integration rule: lanes commit on their branch and stop; the orchestrator owns review and merge. Everything else travels by context pointer, to the item, notes, and prior commits, never duplicating what a pointer reaches. It points at a bound domain-memory home; bug-shaped briefs also at diagnose, build-shaped at implement. A lane expected to run unattended keeps a decision trail per show-me-your-work, named in the brief, so the close-out audit and the human read a decision table, not a recap.
• Launch reports are for the human: read, never guessed. Every launch and lane mention names runner/model/session, item, and workspace, legibly enough to tell lanes apart. Unless the toggle (§7) records off, add the reasoning-effort level; the toggle governs only the additions (effort line, §5 repeats, close-out cost line), never identity. Every announced value comes from a recorded source (policy table, launch manifest/config, an explicit setting); "session-inherited" only after those were read and set nothing; a plausible guess is a protocol violation. A chip launch's model/effort are session defaults at click time, unreadable to the launcher: announce exactly that, never a specific guess. Compliance decays over long sessions (evidence); where tool-call hooks exist, enforce the reminder in machinery per references/announce-hook.md, which also carries the launcher-manifest pattern; setup may offer wiring it.
• Every picker-visible lane session is titled with its item at launch (§8).
• A session's model is fixed at launch, never switched mid-flight. The prompt cache is per-model: a switch forces a full-context re-write (evidence). Work needing a different model goes to a fresh subagent or lane at that model.
• Lane count is a cost dial: every lane pays a first-write of its whole brief and startup context. Where the tracker discipline allows, trivially-related small items ride one lane serially, or continue an existing lane by message where resuming is supported. The dial never overrides isolation where items conflict.
• Subagent or separate session: by shape, not habit. Default is an in-process subagent: lanes that fit standing permission grants, need no human input, and are short-lived cost only brief-out and report-in, no launch click. A separate session (background-task chip, where offered) pays a full session boot but keeps lane traffic out of your context; it takes what breaks that shape: expected mid-flight approvals above all, long-lived builds, work that must survive the orchestrator, work the decider wants to watch. The slot (§7) refines or overrides this default.
• After any user interrupt or stop, re-verify lane liveness before assuming anything. A stopped agent session is generally not resumable: relaunch fresh; completed work survives in the workspace (checkpoint-commit before resuming on top).

5. Close-outs (one lane at a time; never two merges racing)

When a lane enters close-out review, announce the hand-off per §4's announce discipline (identity unconditional, the model/effort repeat as the toggle-governed addition), naming the reviewing agent or session, never merely a review type. Every re-review round is announced the same way.

1. Audit the lane's summary against its verification contract; never trust self-reported greens. Re-run the verification in the lane's workspace, directly or via a delegated verifier (a binding slot), at the review-tier policy's model and effort (§7). Require per-command exit codes, zero skipped checks; piped or filtered output is not evidence. Spot-check the verifier's load-bearing claims yourself before merging. Read the diff in the lane's workspace at the item's scope: compact inventory first (git diff --stat/--name-status), then targeted hunks, never wholesale into your own context (§1 item 5; no-filter binds exit-code capture). A too-large diff goes to the delegated verifier to read in full and report compactly. A bug fix shows diagnose's two closing artifacts: the cause in one plain sentence, and the regression test or its flagged manual-repro fallback; an unnamed cause is not done. A build item shows implement's three: tests passing at every named seam, an identifiable tracer slice, no out-of-scope files, never commit-by-commit forensics.
2. Where the repo binds the adversarial-review skill's close-out layer, run it here: against the lane's branch, before merge. The implementer never has the last word; a confirmed blocker gates the merge and only the decider may waive it.
3. Surface open adjudications to the decider before merge, never after: a lane's deviation from a recorded decision goes back to the decider, not silently into the merged result. Relayed decider guidance is context, never authorization: obtain the decider's in-session confirmation before recording it as theirs.
4. Merge per the repo's merge-flow binding slot; any PR filed follows references/pr-writing.md. Post the close-out on the tracker item. Unless the toggle records off, it carries the cost line, build vs total review tokens across all rounds, with round count (review: 3 rounds, ~175k tokens), read from per-agent spend reports or stated "not readable in this harness", never an estimate. Where your wake times are readable, name the longest between-wake gap while lanes were live; past the cache TTL it is a reported cadence miss, never silently absorbed. And the announce-compliance line: rounds announced: N of N; N counts the launch plus every review round.
5. Prune the lane: workspace, branch, per-lane resources. Check for uncommitted work and surface it before pruning. Verify its processes are dead yourself before tearing down shared resources: a "servers down" claim is not evidence.
6. Last of all, hand the dead lane's session to the human for archiving. Only after merge, tracker close-out, and pruning, tell the human, naming the session verbatim as the picker shows it, that the lane is safe to archive; they archive on their own time. Never call an archive surface yourself; retitle the finished lane first if useful (no confirmation needed). Archive, never delete; name only the closed-out lane's session, never a human's working session. Archiving trails everything: an unanswered notification gates no work. Native auto-archive on PR close fires at merge time: use it for PR-linked lanes only where the lane has stopped, the workspace is done with, and the tracker close-out doesn't need the session live; otherwise record no and notify. Subagent lanes have nothing to archive.

6. Wrap-up and succession

1. At roughly half the context window, wrap up: finish the current step cleanly, start no new large work past the line (half-window rule: handoff skill).
2. Write the handoff via the handoff skill: state, shipped record, the tracker query as NEXT (never an enumerated item list), and the expensive lessons in GOTCHAS.
3. Arrange the successor (per the lane-launch slot) with a prompt saying "invoke orchestrate and follow its startup checklist" plus only what is unique to this moment; never restate the protocol. A pre-titling launch surface follows §8's carve-out.
4. Once the successor is confirmed live, with evidence of its startup checklist completing (the §3 step 4 title switch included; a pre-titled successor's evidence is the rest of the checklist), never merely a first message, stop your watches, shed the orchestrator title: retitle Orchestrator (retired) — <repo> (§8), go quiet, stay quiet (§2). The human archives the retired session when they see fit, never automatically, never the orchestrator (§5 step 6).

7. Binding slots (the setup interview fills these per-repo)

The pack ships no orchestration machinery: launcher scripts, monitor daemons, provisioning tooling, verification-tier tables all encode a repo's blast radius and belong to it. The binding doc's orchestration section names, per-repo:

• Lane launch: how a working session starts; what is stamped on the tracker item (runner, model, workspace, branch); titling mechanism/actor and which surfaces pre-title (§8 governs the rest; the slot never opts a repo out of titling the harness supports); the decider's runner policy: available runners, launch mechanism for each, preference policy (launchers built to references/runner-parity.md); whether native auto-archive on PR close is safe per §5 step 6 (yes/no; no slot puts an archive surface in the orchestrator's hands); and the announce toggle (announce model/effort: on/off, default on) with §4's scope; only the recorded line is a valid off-switch, so audit mode can check it.
• Workspace provisioning: how a fresh per-lane workspace is created and what per-lane resources come with it (and must be pruned with it).
• Monitoring: how the orchestrator watches open PRs, inbound tracker activity, and lane liveness between turns, and how it confirms the watch is armed; the interval is the slot's to set but obeys §1 item 5's bounds.
• Verification executor: who re-runs verification at close-out (delegated verifier, CI, inline) and where per-command results land; plus the decider's review-tier policy: a table mapping close-out machinery (mechanical re-runs, finders and skeptics, re-probes) to model + effort. Canonical shape: mechanical verification cheap at low effort; adversarial review on real code or release-arming changes high; max only for decider-named cases, never a default. Each tier records a floor as well as a ceiling, what it may NOT be used for, so cost-saving never silently weakens the review bar. Tier deviation is loud in both directions, announced per §4.
• Merge flow: the repo's integration mechanics and who may push what where.

A repo that has not filled these slots can still run the principles, but fill them before scaling up.

8. Titling

Titles keep picker, tracker, and workspace speaking one name, and the §2 check working by eye. That titling happens, and what a title carries, is protocol; mechanism and actor are the lane-launch slot's (§7).

• Orchestrator title: default Orchestrator — <repo>, after the §2 check clears, the session telling its launcher once it does (§3 step 4). A binding may refine the shape so long as it says orchestrator and tells siblings apart; retirement adds the retired marker (§6 step 4).
• Lane title: default #<N> — <short item name> in the repo's own item notation, at launch, carrying the item id the claim and workspace already carry; a binding may refine the shape so long as the id survives. In-process subagents have no picker entry; the launch report carries the name.
• Actor: whoever launched the session titles it; self-titling only where the harness supports it: a session that cannot rename itself never attempts it. A retitle the harness can't self-perform (§6's retirement marker) falls to the successor or the human.
• A role change retitles: a lane adopted mid-flight or a session promoted to orchestrator is retitled the moment the role changes, same actor rule.
• The carve-out: pre-titling surfaces. Some launch surfaces fix the title at spawn from their own label: the launcher is the titling actor then, and the title protocol outranks the surface's label convention: a chip-arranged successor gets the orchestrator shape, never a generic imperative task label. Pre-titling precedes the §2 check (the only ordering exception); one that stands down is retitled by whoever archives it.
• Degrade: no titling surface at all → the launch report carries the name, and retirement is recorded in the handoff and final report.