Orchestra

---
name: orchestra
description: "Run an oversized task as a parallel multi-session sprint: one conductor, several work managers in dedicated git worktrees, a file-based mailbox for coordination, watchdog supervision, and a clean teardown. Trigger: /orchestra <mission> for a new sprint, /orchestra resume to warm-boot into a running one."
---

# orchestra: conducting a parallel multi-session sprint

This playbook was distilled from two real sprints (see `case-study.md`): a single conductor
plus five parallel work managers per sprint (10 sessions total) built two complete systems
in one day, going from 0 to 298 tests with zero merge conflicts. Nothing here is
project-specific. The templates in `templates/` carry the structure; the conductor fills
them in rather than inventing process on the fly.

Entry modes: `/orchestra <mission>` starts a new sprint (run sequence in section 9).
`/orchestra resume` warm-boots into an existing sprint (section 3) without replanning.

---

## 1. When to use it, when not to

Use orchestra when all three hold: (a) the mission splits into 3 or more areas with
separable file ownership; (b) there is a shared contract you can freeze up front, or
synchronize through a gate board; (c) the scope is hours of work or more. Otherwise a
single agent wins: coordination overhead is real (multi-agent work burns roughly 15x the
tokens of a plain chat), so the mission has to earn it.

### 1b. Mission archetypes

The archetype determines how to phrase the opening request and what task tree the
conductor builds:

| Archetype | Recommended split | What the opening request must state | Main risk |
|---|---|---|---|
| **Green-field (from scratch)** | Vertical streams per subsystem; frozen contract or gate board at the center | Goal, hard constraints, quality bar, owner decision points | Contract changing mid-flight |
| **Extension of an existing system** | Prime Directive "the existing system stays green"; streams per feature | What must not break (current test count is the baseline), what is experimental and spike-gated | Silent regression in the old code |
| **Cross-cutting migration / refactor** | Discovery stage builds the site list, then horizontal split by file groups; mostly low effort | Exact scope (in and out), per-site verification rule | Odd sites missing from the list; non-modular boundaries causing conflicts |
| **Complex third-party integration** | Mandatory spike first (fixtures against the live tool plus stop conditions); one stream owns the protocol, the rest consume it through a contract | Pinned tool version, working auth, explicit kill criteria | Docs contradicting reality (reality wins); auth expiry |
| **Read-only audit / research** | Fan out by area, no write ownership; conductor synthesizes | The research question, finding format, evidence bar | Silent partial coverage (no merge step to catch it) |

---

## 2. Roles and effort allocation

- **Owner.** The single source of authority: makes irreversible calls, acts as the final
  quality gate (a gate closes only on a screenshot or a live run in front of the owner),
  serves as the emergency channel when the conductor goes dark, and sets effort levels
  wherever there is no programmatic control.
- **Conductor.** One senior instance (strongest model, high effort). Plans by delegation,
  builds the sensitive core personally, launches the streams, supervises, **is the only
  one who merges**, centralizes contract changes, runs the review, closes the sprint.
- **Work manager.** A separate instance in its own worktree: exclusive owner of one file
  domain, works through a TASKS file with evidence, reports to the mailbox. Effort is
  assigned by **sensitivity, not size**: one High for the most delicate stream
  (concurrency, security, hand-rolled protocol), Medium for most, Low for mechanical work.
- **Subagent.** A cheap short-lived instance. Best uses: parallel research and planning
  during the planning phase (including an **adversarial critic** that attacks the whole
  approach) and critique passes. Not for building the core.

> **Subagent threshold (mandatory in every launch prompt):** "you may use subagents" on
> its own does nothing; in practice 8 of 10 work managers launched zero. Spell out when
> to launch one: more than 2 independent tasks queued, a critique pass, a large corpus to
> read, a wide search. And when not to: iterative work against a live process, or a small
> well-bounded domain.

---

## 3. Lifecycle

**Plan, foundation, launch, supervise, rolling merge, adversarial review, teardown.**

- **Plan:** delegate research and planning to parallel subagents plus an adversarial
  critic; collect owner decisions; run hardening rounds until the owner signs off; write
  the master plan (`templates/master-plan.md`), per-stage TASKS files
  (`templates/tasks.md`), and copy `templates/sprint-checklist.md` into the project.
- **Foundation:** the conductor personally builds the safety layer, the
  spikes-against-reality, and the frozen contract or sensitive core.
- **Launch, two valid approaches:**
  1. **Foundation first** (safer): contract frozen and ready, then launch. Fits when the
     contract is small and clear.
  2. **Launch first** (faster): streams start on spikes and foundation-independent work
     while the conductor builds the foundation. Only valid with a gate board
     (`templates/foundation-board.md`), a "local types plus TODO-contract" convention, a
     conductor commitment to adopt stream-authored shapes as-is, and an integration merge
     after every green gate.
- **Supervise:** scan rounds plus the watchdog (section 5). The conductor answers
  requests, centralizes contract changes into a single additive contract commit, and
  fixes cross-stream integration bugs personally, once, instead of letting each stream
  rediscover them.
- **Rolling merge:** conductor only, serially, in dependency order; full green gate after
  **every** merge.
- **Review:** a blocking adversarial review (section 6).
- **Teardown, in this exact order:** (1) full sign-off plus lessons journals; (2)
  **archive the mailbox before deleting anything** (the mailbox is the sprint's evidence;
  we learned this the hard way); (3) closing PR with review, including the version bump
  **and the lockfile**; (4) after merge: remove worktrees with force plus prune (not one
  by one), delete stream branches, archive the manager sessions, remove temporary
  launchers; (5) final check: main green, `git worktree list` clean, `git branch` clean.

### Resume / warm boot (`/orchestra resume`)

All sprint state lives in files, so a crashed or compacted conductor session is not a
crashed sprint. On resume, **skip planning and foundation** and do this:
1. Open `sprint-checklist.md` and the TASKS files; find where the sprint stopped.
2. **Verify against reality, not memory:** `git worktree list`, `git log` per stream
   branch, `git status`. An intermediate session may have moved past what the files claim.
3. Scan every stream's status block plus any DONE / BLOCKED accumulated while you were out.
4. Restart the watchdog timer, answer pending requests, and pick up supervision exactly
   where it left off.

---

## 4. Collision prevention, environment isolation, circuit breaker

### Ownership and merging
- **Exclusive file ownership** per stream, with explicit allowed **and** forbidden lists.
  A change outside your domain is a mailbox request, not a quiet edit.
- **Flagged exception protocol:** when the ownership rule blocks critical progress (a
  foundation bug in someone else's file), prove it locally with a temporary workaround,
  flag it explicitly in the commit and the mailbox with a ready diff, and leave the
  canonical fix to the conductor. Do not fake paralyzed compliance and do not fix it
  silently.
- **Only the conductor merges into the integration branch and main.** Contract changes
  are centralized with the conductor and are **additive only**. (The reverse direction,
  a stream pulling the integration branch *into* its own branch after a green gate or on
  the conductor's instruction, is allowed and encouraged.)
- Merge in dependency order; full test gate after every merge; **reinstall dependencies**
  (npm ci or equivalent) after any merge that pulls another stream's dependency.
- A shared append-only file (lessons journal and the like) is a guaranteed conflict
  magnet: give each stream its own zone or make it conductor-owned.

### Environment isolation: the worktree isolates files; everything else needs an allocation
**The principle:** anything outside the worktree (a port, a database, a device, a screen,
a global cache, a secret, an external API) needs a row in the master plan's resource
allocation table and a concrete value in the launch prompt. The ten classes:
1. **Ports** (dev server, HMR, debugger, CDP): a deterministic formula such as
   `BASE + stream_number * 100`, injected via ENV, or port 0 where supported.
2. **Databases:** separate DB or schema per stream (`app_w3`), separate Redis index,
   separate docker-compose project name; migrations and seeds only against the stream's DB.
3. **ENV files:** a per-worktree `.env.local` with the allocated values, created during
   the foundation phase.
4. **Secrets:** sensitive files outside git (`.env`, keys) **do not appear automatically
   in a fresh worktree**, so streams fail at runtime on a missing key. The conductor
   verifies a valid base secrets file and copies it (or symlinks it when live updates
   matter) into every worktree **before** launch; the copies never get committed (check
   gitignore); redact secrets from logs and the mailbox, since a pasted secret poisons
   the archive.
5. **Warm global caches up front:** browser installs, tool downloads, the first
   dependency install; once, during foundation, to avoid a parallel download stampede.
6. **Single-owner resources:** an emulator, USB, serial port, or an app's
   single-instance lock; assign to exactly one stream, or serialize through a gate.
7. **The user's global config:** `~/.gitconfig`, `~/.npmrc`, keychain, OS settings; on
   every stream's forbidden list.
8. **Shared external APIs:** a shared sandbox or quota; one owning stream per resource,
   or serialize through a gate.
9. **Machine load:** N builds plus E2E at once will thrash the box; heavy E2E or
   real-window runs go one at a time through a gate, everything else headless.
10. **Test artifacts at fixed paths:** screenshots, coverage, temp files; keep them inside
    the worktree or put the stream id in the path.

### Circuit breaker: a hard stop rule for every stream
**Three consecutive failures of the same action** (same test, same build, same fix) **or
about 30 minutes without measurable progress** on one problem means: stop trying, write
`BLOCKED` to the mailbox (what was tried, the full error, hypotheses ruled out), move to
an independent task if one exists, otherwise wait. A failure streak is a genuine signal
that outside intervention is needed, not that one more attempt will do it. **Conductor
side:** supervision handles `BLOCKED` first; answer in `conductor-to-*` or escalate to
the owner.

---

## 5. Communication

- **Two channels from minute one:** the file channel (the mailbox,
  `templates/mailbox-readme.md`) is the **source of truth** that streams pull on their
  own; the cross-session message channel is a **ping only** that points at a file. The
  message channel is asynchronous and queue-bound (a message lands only when the target's
  turn queue drains), so never use it for urgent coordination.
- **Mailbox path: absolute, outside the repo,** stated explicitly in the launch prompt
  ("not part of any PR"). A relative path once sent a stream writing to a local mailbox
  nobody was reading; it nearly vanished from supervision.
- **A uniform launch prompt** (`templates/launch-prompt.md`, 8 sections): stream
  identity, environment, read-first list, ownership, tasks plus verification, mailbox
  protocol, quality rules, definition of done. Include pre-solved answers to known
  pitfalls and the subagent threshold.
- **Paste-ready requests:** a stream asking for a contract change writes the exact
  solution (names, signatures, a code block), not just the problem. The conductor's merge
  becomes mechanical.
- **Status states:** `WORKING` / `BLOCKED` (circuit breaker fired) / `DONE` (finished,
  with evidence) / `PAUSE` (conductor's instruction under quota pressure).
- **Status compaction (context hygiene):** `<stream>-status.md` holds a **current-state
  block of at most 15 lines** (state, current task, last milestone with evidence, open
  requests). History gets pushed to `<stream>-status-archive.md`, which the conductor
  **does not read** except during incident investigation. The conductor scans status
  blocks only; the sprint's central state lives on the gate board and in TASKS, not in
  anyone's context window.

### Watchdog: the mandatory fallback for the message channel
The conductor **never relies solely on receiving a ping**. A stream that finishes while
its message sits in a queue is a deadlock; in one real sprint the owner spent 2.5 hours
acting as a human watchdog. At launch, start a **proactive wake-up timer** using whatever
primitive the session has (check at runtime): a background shell command
(`sleep 1800; echo WATCHDOG` run in the background, whose completion wakes you), a
Monitor-style tool with an until-condition on the mailbox files, or a scheduled wakeup.
Interval: 20-30 minutes; renew on every scan while streams are alive. **Every wake-up
does a full proactive sweep:** every stream's status block, DONE and BLOCKED files, and
`git log` per stream branch. A suspiciously silent stream (no status and no commits for
over an hour) gets a direct ping; no answer means escalate to the owner.

---

## 6. Verification discipline

- **Green before commit:** the test suite plus typecheck plus build (plus E2E where
  relevant) all green before every commit, in every stream. No commit without evidence.
- **The evidence rule:** a `[x]` in a TASKS file closes **only** with an evidence line:
  "verified <date> (stream, commit)" plus a test count, hash, live-run description, or
  "owner screenshot". "I wrote it" is not "it works".
- **Fixtures against reality:** before writing any adapter, run a spike against the live
  tool and record secret-scrubbed fixtures at a pinned version, including error-path
  fixtures. When docs and reality disagree, reality wins and gets written down. **Every
  spike carries an explicit stop condition** ("if X does not hold, stop and report before
  going further").
- **Live end-to-end verification** (E2E against a real window or environment) as a merge
  condition for the critical stream. It catches environment pitfalls that silent build
  failures never surface; a real foundation bug once passed every build gate and only
  showed up live.
- **Owner gates:** a visual or UX gate closes only on a screenshot or a run in front of
  the owner.
- **Blocking adversarial review** (`templates/review-prompt.md`): a separate reviewer
  (ideally a different model or tool), read-only, with a locked output format
  (`[Pn] file:line` plus `VERDICT`). Findings get published verbatim. **The conductor
  personally verifies every number and date against git before accepting or rejecting a
  finding.** The revise loop runs until clean or until the **round cap (3), at which
  point it goes to the owner; never an autonomous call**. A review that will not converge
  (the same finding returning round after round) means switch to a root-cause or
  defense-in-depth fix instead of another patch. Run the review even on a "trivial" PR:
  documentation drift (numbers written from memory) has only ever been caught there.

---

## 7. Resources, budget, and effort

### Resource rules
- **Staggered launch:** not every stream in the same minute (token buckets and
  acceleration limits punish bursts).
- **Concurrency cap sized to the quota:** limits are per organization, one shared pool
  for all sessions; a model family is a separate bucket, so routing mechanical streams to
  a cheaper family genuinely raises the ceiling.
- **Output tokens per minute is the usual bottleneck:** thinking counts as output, so
  lowering effort on mechanical streams directly relieves the quota.
- **Health check before any long real run** (a minimal run plus auth validity). An auth
  expiry mid-sprint once froze supervision for hours; renew auth proactively before a
  long sprint.
- **Storm procedure:** on 429, honor `retry-after`, back off with jitter, at most 4
  retries. On 529 (provider side), pause rather than retry-storm. A sustained storm
  means a file-based `PAUSE` instruction to low-priority streams and **the owner as the
  declared fallback channel**.

### The conductor's effort guide

**Decision table, task type to level** (from the official guidance; matched what worked
in practice: one High, three Medium, one Low):

| Stream task type | Level |
|---|---|
| Architecture, concurrency, hand-rolled protocol, security-sensitive code | high, then xhigh; max only when stuck or truly frontier |
| Core agentic coding, long-horizon work (over 30 minutes) | high (the default) or xhigh when quality is critical |
| Routine refactor or migration, structured output | medium (max causes overthinking on structured tasks) |
| Mechanical edits, mechanical UI, scoped scouts and subagents | low |

**Calibration facts:** effort controls all output tokens (tool calls included), not just
thinking; the gap between low and max can be roughly 10x in time and tokens; max hits
diminishing returns on most workloads; and **"effort amplifies good context, it does not
compensate for bad context"**, so the conductor's scoping matters more than the level.
Levels can be raised mid-flight; the change takes effect from the instance's next turn.

**Mechanics per launch surface. This is a snapshot (mid-2026); check the live tool schema
before relying on it:**

| Surface | Mechanism |
|---|---|
| Desktop-app background session / task spawner | If the spawn tool exposes effort or model parameters, use them; if not, ask the owner to set it in the UI per session (takes effect next turn: "raise it, then send a lone `.`") |
| Claude Code session | `/effort low\|medium\|high\|xhigh\|max` plus `/model` |
| Headless (`claude -p`) | `--effort` / `--model` flags |
| Agent SDK | `options.effort`; mid-run: `applyFlagSettings({effortLevel})`, `setModel` |
| Subagent (Agent/Workflow call) | `effort` / `model` per call, or the agent definition's frontmatter |
| Direct API | `output_config.effort` (newer models keep adaptive thinking always on; thinking bills as output) |

> **Dynamic capability check:** capabilities get verified at runtime, never assumed from
> memory. Before launching, inspect the tool schemas actually available right now; if the
> spawn tool has grown new parameters, use them. The table above is a snapshot, not a
> contract.

---

## 8. Pitfall checklist

The conductor walks this list **before launch** and **before teardown**. Every item
traces back to a real failure (see `case-study.md`):

**Communication:** 1. Message channel is a ping only; critical content goes to a file.
2. Mailbox path absolute and outside the repo. 3. Assume streams are progressing on
their own; never assume they are waiting for you. 4. DONE files plus a watchdog instead
of waiting for a message. 5. Status at start and at every milestone, never batched at
the end. 6. Capped status block plus a separate archive.

**Ownership and merging:** 7. Allowed and forbidden lists for every stream; shared files
belong to the conductor. 8. Unavoidable violations go through the flagged exception
protocol. 9. Reinstall dependencies after any merge that pulls another stream's
dependency. 10. A cross-stream foundation bug gets one conductor fix plus distribution,
not a fix per stream.

**Environment:** 11. All ten isolation classes (section 4) filled in the allocation
table. 12. Secrets copied into every worktree before launch. 13. Do not launch the
target app from a packaged-agent context when the owner needs to see the evidence:
package virtualization can show two different disks at the same path; provide a
standalone launcher and verify the real write path from both contexts. 14. Make sure no
manual instance is alive before automation gates (single-instance locks).

**Process:** 15. Launch-before-foundation only with a full gate board (section 3).
16. Circuit breaker active in every stream. 17. Review round cap goes to the owner;
non-convergence means a root-cause fix. 18. No number or date from memory; everything
from git; version bumps include the lockfile. 19. A subagent threshold in every launch
prompt. 20. Metadata written to a system boundary: verify the identity fields, not just
that the record exists. 21. An explicit stream-to-worktree-to-branch-to-TASKS mapping key
in the prompt (an off-by-one once confused a stream). 22. Critical state in files, so it
survives compaction. 23. Teardown in order, mailbox archived before deletion.

---

## 9. Run sequence (new sprint)

1. **Research:** launch parallel research subagents (existing code, domain, tools) plus a
   planning agent plus an **adversarial critic**. Identify the archetype (section 1b).
2. **Owner decisions:** collect the open calls into direct questions; get a direction
   sign-off.
3. **Hardening:** critique rounds on the plan until the owner approves.
4. **Documents:** write the master plan from `templates/master-plan.md` (including the
   resource allocation table and the ownership map), a TASKS file per stage from
   `templates/tasks.md`, and copy `templates/sprint-checklist.md` into the project.
5. **Foundation:** personally build the sensitive core plus spikes; prepare a frozen
   contract or a gate board (`templates/foundation-board.md`).
6. **Sprint infrastructure:** create worktrees and branches, the mailbox at an absolute
   path (drop in `mailbox-readme.md`), copy secrets, allocate ports and databases, warm
   the caches.
7. **Launch:** check actual tool capabilities; launch staggered, one filled
   `templates/launch-prompt.md` per stream (effort per section 7); **start the watchdog
   timer**.
8. **Supervise:** scan rounds (status blocks, DONE/BLOCKED, `git log`); answer requests;
   centralize contract changes; tick the sprint checklist as you go.
9. **Rolling merge:** dependency order, green gate after every merge.
10. **End-to-end:** real runs in front of the owner; evidence into the checkboxes.
11. **Review:** blocking adversarial review (`templates/review-prompt.md`); revise loop;
    merge to main.
12. **Teardown:** the mandatory order in section 3, until `git worktree list` is empty
    and main is green.