Orchestrate

---
name: orchestrate
description: "Run one session as the lead developer of an agent team: it takes tracked work, routes it into parallel lanes, audits what comes back, and owns the merge, so the human brings decisions and never implements. Use when the user says \"orchestration mode\", asks one session to coordinate several lanes/sessions, or hands over an orchestrator role."
---

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

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, and owns integration. It is rule-based: do every step, every time.

Read the team-workflow binding doc first. The tracker discipline (claims, frontier, blocking; [setup's references](../../orient/setup/references/tracker-discipline.md)) is assumed throughout. Measurements behind the cost-shaped rules: [references/evidence.md](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.** Hold judgments and state, not logs. Hands-on-keyboard past ~10 minutes is worker mode: package the work into a lane or background task.
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](references/evidence.md)). 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. A metronome wake is minimal: one small filtered check (count-shaped or `-q`), 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](../../orient/domain-memory/SKILL.md) 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](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: launch report AND tracker item carry `runner fallback: X→Y, reason`.
- **Brief from the lane-brief template** ([setup's templates](../../orient/setup/references/templates/lane-brief.md)): spec verbatim, named verification set, standing constraints, and the integration rule: lanes commit on their branch, catch up, and stop. 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](../../orient/domain-memory/SKILL.md) home; bug-shaped briefs also at [diagnose](../diagnose/SKILL.md), build-shaped at [implement](../implement/SKILL.md). A lane expected to run unattended keeps a decision trail per [show-me-your-work](../show-me-your-work/SKILL.md), named in the brief, so the close-out audit and the human read a decision table, not a recap.
- **Lanes catch up before handing back**: a lane updates its branch from its **merge target** (the default branch, or the spec's integration branch, §7) per the brief's catch-up constraint, re-runs verification, and names the target commit in its summary. If the target moves again before you merge, update the branch yourself where that applies cleanly and re-run verification; only a conflict goes back to the lane.
- **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 chip launch's model/effort are session defaults at click time, unreadable to the launcher: announce exactly that. Compliance decays over long sessions ([evidence](references/evidence.md)); where tool-call hooks exist, enforce the reminder in machinery per [references/announce-hook.md](references/announce-hook.md), which also carries the launcher-manifest pattern; setup may offer wiring it.
- **A session's model is fixed at launch.** The prompt cache is per-model: a switch forces a full-context re-write ([evidence](references/evidence.md)). 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)

When a lane enters close-out review, announce the hand-off per §4's announce discipline, 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 per the verification-executor 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. A summary without a catch-up line (§4) goes back to the lane. 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](../diagnose/SKILL.md)'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](../implement/SKILL.md)'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](../adversarial-review/SKILL.md) close-out layer, run it here**: against the lane's branch. 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**: 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 [pr-writing](../pr-writing/SKILL.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. 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**: 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. 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, start no new large work past the line (half-window rule: [handoff skill](../handoff/SKILL.md)).
2. Write the handoff via the handoff skill: state, shipped record, the tracker query as NEXT, 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.
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), stop your watches, **shed the orchestrator title**: retitle `Orchestrator (retired) — <repo>` (§8), and go quiet (§2). The human archives the retired session when they see fit, never automatically (§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 decider's **runner policy**: available runners, launch mechanism for each, preference policy; whether native auto-archive on PR close is safe per §5 step 6 (`yes`/`no`); 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. Optionally, a per-spec **integration branch** the decider opts into: [references/integration-branch.md](references/integration-branch.md).

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>`, the session telling its launcher once the §2 check clears (§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; 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 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 title protocol outranks the surface's label convention: a chip-arranged successor gets the orchestrator shape. 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.

## Attribution

This skill is the repo's own. It credits Matt Pocock's [`implement-spec`](https://github.com/mattpocock/skills/tree/main/skills/engineering/implement-spec) (MIT) for borrowed rules: briefing by context pointer, lane catch-up (§4), and the integration branch idea (§7). The per-spec opt-in is ours; his integration branch is always on.

<!-- lineage: own -->