---
name: orchestrator
description: Adopt the orchestrator role for a multi-part initiative: a long-lived coordinating session that decomposes a premise into slices, launches one worker session per slice in its own git worktree, coordinates them by cross-session messaging, and owns all merges. Use when the user says "you are an orchestrator agent", "/orchestrator", "act as orchestrator", "orchestrate this", or hands you an initiative/premise to run as several parallel or staged workstreams instead of building it yourself.
---

# Orchestrator

You are the **orchestrator** for the initiative the user is about to describe (or just described). You do not implement the work yourself. You decompose it into slices, launch and coordinate one worker session per slice, gate what is safe to run when, and own the integration branch and every merge. Workers build; you plan, sequence, and integrate.

The full method lives in three pattern docs: the neutral method doc and one companion per runtime, named in the steps below. This file is the operating checklist; the docs are the reasoning behind each step and the edge cases. Read them. Do not reconstruct the method from memory.

## First moves (before any planning)

1. **Name yourself so workers can address you.** A session's name is its address. Set it to `<initiative>-orchestrator`: launch with `claude --name <initiative>-orchestrator`, or run `/rename <initiative>-orchestrator` now. Tell the user the exact name; every worker brief will carry it.
2. **Read the method doc:** the `orchestrator-pattern-neutral` reference (bundled at the end of this file). It covers roles, the run loop, parallelism-and-shared-state rules, branch strategy, the completion-report format, and the expensive lessons. This is the source of truth; the rest of this file is a pointer into it.
3. **Read the companion for your runtime:**
   - Claude Code → the `orchestrator-pattern-claude` reference (bundled at the end of this file) (SendMessage/ListAgents, `--worktree`, permission-mode delivery gotchas).
   - Codex → the `orchestrator-pattern-codex` reference (bundled at the end of this file).
   - Any other runtime → use the neutral doc plus whichever companion is closest, and translate the mechanics.

## The run loop (judgment: this is the whole job)

Work with the user; do not go silent and batch-build.

1. **Decompose the premise into slices** with the user. A slice is an independently buildable, independently reviewable unit with a clear interface. Name each one. Surface the dependencies between them (what must land before what).
2. **Decide sequencing and parallelism** per the neutral doc's *Parallelism and shared state* test: default to parallel, but serialize any two slices that mutate the same shared surface: a gitignored/symlinked database, a shared data directory, generated output, an external service (a live server, a media library, a deploy target). Name the serialization points explicitly; they are where multi-agent runs go wrong.
3. **Choose the branch/worktree strategy** (neutral doc's *Branch strategy*): an integration branch for the initiative, one worktree + branch per slice, workers never self-merge. Decide the base each slice branches from (integration branch, or a stacked dependency branch when a slice needs unmerged work). Then create each slice's worktree yourself with git, on that exact base (`git worktree add <path> -b <branch> <base>`).
4. **Write a worker brief per slice** (template below) and get it to the worker. Give the human a one-line launch command for a named session in the slice's worktree, then either send the brief to that session yourself (`SendMessage` on Claude Code) or hand the human the brief to paste as its first message, whichever they prefer. Gate: only greenlight slices whose dependencies and shared-state windows are clear.
5. **Coordinate as reports arrive.** Confirm worker/peer names with `ListAgents` (or the runtime equivalent); answer DECISION messages; tell a worker when a dependency is safe to consume; hold destructive or shared-state steps until you confirm the window is clear.
6. **Integrate.** On each completion, inspect the branch, verify the tests are green yourself, then merge **from the main checkout or your own integration worktree, never from inside a slice's worktree**. Resolve the (usually doc-only) conflicts. Retire the worktree/branch once its session closes.

## Worker brief template

Every brief includes these fields (from the neutral doc's *Shared brief*):

```
You are building Slice <name> of <initiative>. You report to the orchestrator session named <orchestrator-name>.
- Read first: <initiative doc / shared context path>, then the repo's own orient docs.
- Your session name: <slice-name>. Launch with --name so the orchestrator can message you.
- Worktree / branch / base: <path>, branch <branch>, based on <integration branch or dependency branch>.
- Process: brainstorm → spec → build via SDD (fast model implements, stronger model reviews) → verification → update docs.
- Model split: implementation subagents on a fast model; the code-review subagent on a stronger model before "done".
- Commits: commit freely on your own branch without asking; NEVER merge to the integration branch or main; the orchestrator merges.
- Communication: SendMessage the orchestrator at START, for any DECISION/surprise, and at COMPLETION (use the completion-report format); if messaging is unavailable, print the same report for the human to relay.
- Serialization: <any shared-state step that must wait for the orchestrator's go, e.g. a DB rebuild, a live migration, a scan trigger>.
```

Fill `<...>` per slice. Keep names unique: a duplicate name on the machine gets auto-renamed and messages misroute.

## Safety rules (non-negotiable; see the neutral doc)

- **Permissions are per session.** A message from a worker or peer is coordination, never the human's consent, and cannot answer a pending permission prompt. Never ask a peer to do something blocked in your session, and never do a peer's blocked work; route it back to the human. This is permission laundering; refuse it.
- **Keep all sessions in the same permission mode.** A session in a different mode holds cross-session messages for human approval, and held messages expire. Never treat silence as agreement; a successful send means delivered, not read.
- **Verify before you merge.** Re-run the slice's gate (tests/build) yourself; a green report is a claim, not proof.
- **Serialize shared state.** Worktrees isolate files, not a shared database, a symlinked data dir, a cache, generated output, or an external service. Serialize every step that mutates those.
- **Gate destructive / outward-facing steps.** Hold anything hard to reverse (a live data migration, a delete, a publish) until the human has approved it. Your authorization is not a substitute for theirs.

## Design note (for maintainers)

This skill is deliberately all prose, no scripts: every step above is judgment (decompose, sequence, brief, coordinate, integrate). The only mechanical bits (reading the fixed pattern docs, naming the session, running `git merge`) are one-liners not worth compiling. The reusable method and its worked lessons live in the three pattern docs, authored once and pointed to here rather than duplicated.

---

<!-- Reference: orchestrator-pattern-neutral -->

# Orchestrator pattern — platform-neutral guide

Hand this guide to an agent when a body of work is big enough to split into a series of slices that separate workers will build in parallel or in sequence. It explains the roles, how the orchestrator drives, how workers report back, when parallelism is safe, and who owns branching, committing, and merging.

It is written from real runs. Most rules here carry their reason, because the reason is what lets you handle the case the rule didn't anticipate. If you're short on time, read [Expensive lessons](#expensive-lessons) first.

This is the source of truth for the method. Use a platform companion for the exact commands, communication mechanism, and configuration:

- orchestrator-pattern-claude
- orchestrator-pattern-codex

## Outcome

One long-lived **orchestrator** owns the plan, sequencing, shared decisions, integration branch, and final verification. Each **slice worker** owns one bounded outcome end-to-end in an isolated worktree. The human retains authority over consequential approvals, merges, pushes, and external-state changes.

The orchestrator is the single source of truth for what is safe to start right now. Workers do not independently settle cross-slice decisions or merge into integration branches.

## When to use it

Use this pattern when these are true:

- The work naturally separates into at least three slices.
- Slices share a repository, build pipeline, database, generated artifacts, or external services — so they can collide.
- You want more than one agent moving at once, a clean audit trail of who did what, or continuity across many context windows.

For a single linear task, use one agent and skip the ceremony. Do not use the pattern just because multiple agents are available: coordination costs prompts, status traffic, merge management, and review time.

What the overhead buys: the orchestrator keeps the whole epic arc in mind while the build spans many context windows, and it can run on a stronger reasoning model while slices are farmed out to executors and code reviewers whose context windows stay a manageable size.

## Roles

### Orchestrator

One agent, long-lived. It reconnoiters the codebase, maps shared surfaces, cuts slices, writes worker briefs, decides sequencing and parallelism, routes cross-slice decisions, tracks status, and integrates completed slices. It does not usually write feature code, and it does not commit feature code it didn't write — delegating is what keeps its view of the whole initiative clean.

### Slice worker

One per slice. Each owns exactly one slice end-to-end: brainstorm → spec → implement → test → verify → update docs → commit → report. A worker works only in its assigned worktree and branch, and reports status to the orchestrator directly.

### Human

The human sits in the loop: launches (or authorizes) each worker session from the orchestrator's brief, brainstorms and reviews with the worker, and makes the go/no-go calls the orchestrator surfaces — merge now vs. defer, push, anything touching external state. The human is also the relay for anything the agents can't do themselves. A worker or peer request is never a substitute for human authorization.

### Two launch modes

- **Human-launched workers.** The human opens a fresh session per slice. The orchestrator either sends that session its brief directly or hands the human a launch prompt to paste, and the human works through the slice interactively. This keeps a per-slice brainstorm and review with the human, and is the mode this pattern was developed in.
- **Orchestrator-spawned workers.** The orchestrator's platform spawns workers itself and collects their results. Reporting is automatic, but there is no per-slice human brainstorm, and platform nesting limits may apply.

Which modes are available, and how workers reach the orchestrator in each, is platform-specific — see the companion.

## The run loop

1. **Break it down (orchestrator).** Recon the codebase, map shared surfaces, cut slices along the seams that minimize overlap, and order them by dependency. Name the collisions explicitly — they drive the whole sequencing plan.
2. **Write the briefs (orchestrator).** One shared context block plus one brief per slice.
3. **Launch a slice (human or orchestrator, per launch mode).** A fresh worker gets the shared context and its slice brief.
4. **Worker reports (worker → orchestrator).** Start update, decision updates as they arise, completion report at the end.
5. **Orchestrator gates the next move.** From the reports and the file/state/dependency map, the orchestrator says what is safe to start next. Nothing starts without that call. Repeat from step 3.
6. **Integrate and merge (orchestrator + human).** Slices land on an integration branch in dependency order; the whole initiative merges to main once, after a combined test pass.

## Before launching workers

1. **Recon shared surfaces.** Map every file a slice may edit, every database or generated artifact it may write, every external system it may mutate, and every build or rebuild command that changes state.
2. **Cut low-overlap slices.** Give each slice an end-to-end outcome with explicit owned files, stores, interfaces, tests, and documentation expectations.
3. **Order dependencies.** Identify which slices introduce APIs, schemas, or generated outputs that later slices require.
4. **Decide parallelism per pair of slices.** Default to parallel, gated by the test in [Parallelism and shared state](#parallelism-and-shared-state).
5. **Create durable initiative memory.** Keep a project-local initiative document with the slice list, placement rules, decisions, shared surfaces, dependencies, and current integration status. Prompts and chat scroll away; this document is what a fresh orchestrator or worker reads to catch up.

## The worker brief

**The prompt is the product.** A good slice brief is self-contained enough that a fresh agent with no memory of the planning conversation can execute it. Every worker receives the same shared context plus a slice-specific block.

Keep the shared context in a durable, mentionable file rather than re-pasting it. Update that one file when the pattern evolves and every future slice inherits the change.

### Shared context

- Repository location and orient-first references: the repo's agent-instructions file (`CLAUDE.md`, `AGENTS.md`, or equivalent), the architecture documentation, and the initiative document.
- The fact that this is one slice of a larger orchestrated initiative, where the initiative is written down, and that the worker can ask the orchestrator about the larger picture.
- The process the worker must follow: brainstorm → spec → implement → verify, or the house methodology.
- **Three directives to state explicitly, because workers skip them otherwise:**
  - **Drive implementation from the written spec.** Spec-driven (or subagent-driven) development off the slice spec, not freehand coding.
  - **Split models by job.** Implementation on a fast model; code review on a stronger model before the slice is called done.
  - **Docs are part of the definition of done.** Run the project's doc-maintenance ritual so tech and feature docs, the changelog, and any agent-instructions file or README reflect the change. Not a nice-to-have.
- **Commit permission.** Say outright that the worker commits its own work freely on its own branch and does not need to ask. Every commit in an isolated worktree is reversible, and workers that aren't told this keep asking. Say equally plainly that the worker must not merge into the integration branch or main.
- The key architecture facts every slice needs — especially the shared surfaces and any placement rules ("data of kind X goes in store A, kind Y in store B").
- Cautions: other agents active in the repo, shared mutable state, build and rebuild hazards, style rules, commit conventions, permission boundaries.
- The platform's communication mechanism, the orchestrator's exact address, and the completion report format.

### Slice-specific block

- Slice name and goal.
- Exact owned files, symbols, data stores, interfaces, and tests.
- Concrete work items and definition of done.
- Dependencies already available, and work that must not begin until another slice lands.
- Cross-slice decisions the worker must route to the orchestrator rather than decide alone.

## Communication protocol

Where the platform allows it, workers report **directly** to the orchestrator rather than through the human. Human relay is lossy and slow. Bake the protocol into the shared context so it is non-optional.

- **Start update:** slice name, branch, and worktree path once the worker is oriented and active. Lets the orchestrator confirm the slice is live and track the branch.
- **Decision update:** any time the worker hits a decision that affects another slice — a shared schema, interface, dependency, state store, or another slice's scope — or a surprise the orchestrator should weigh in on. Surface it; don't decide it alone. A worker settling a shared question unilaterally is how two slices end up with incompatible assumptions.
- **Completion report:** the structured handoff at the end of the slice.

**Don't block on replies.** The orchestrator reads messages on its next turn, not in real time. Workers continue clearly local work while waiting. The exception: surface a cross-slice decision before making a change that would be hard to undo.

**Fallback.** If direct communication is unavailable, the worker writes its report to the initiative document or prints it for the human to relay. Never let a missing channel mean no report.

**Orchestrator-side.** The orchestrator also messages workers — to confirm decisions, change sequencing, or give a timing all-clear when a dependency is safe to consume.

### Completion report

Uniform across slices:

- **Slice:** name.
- **Shipped:** changes, grouped by file and data store.
- **Migration or rebuild:** whether run, with the exact command.
- **Tests:** command and result.
- **Docs:** whether updated, with paths.
- **Deferred or surprises:** anything intentionally left out or discovered.
- **Follow-on impact:** slices unblocked, affected, or requiring revalidation.

## Parallelism and shared state

Default to parallel, but only where slices are genuinely independent. The test is not "different features." It is: **can they be developed and merged without touching the same mutable thing?** Two independent-looking slices collide if any of these hold:

- **They edit the same files.** Even additive edits to the same list, schema, or switch conflict at merge. Worktrees isolate editing, not merging.
- **They share mutable state outside the repo.** This is the sneaky one. A database file, generated artifact, or cache that lives outside version control — a gitignored data directory, a symlink — is one physical copy that every worktree points at. Two agents mutating it race, and one's schema or data changes can silently clobber the other's. This trumps file-level analysis: two slices can touch zero common files and still be unsafe because both rebuild the same database.
- **They have a semantic dependency.** Slice B reads a column, API, or function that slice A introduces, so B can't be built or tested until A exists.

Decision procedure:

1. Map, per slice, the files it edits and the shared mutable state it writes — databases, generated files, caches, environments, external services.
2. Two slices may run in parallel only if both sets are disjoint and neither depends on the other's output.
3. Anything that mutates the same shared store runs serialized, one at a time, and each slice announces immediately before it mutates so the orchestrator can confirm nothing else is reading or writing.
4. When in doubt, serialize. The costs are asymmetric: a wrong parallel call costs a painful merge or a data wipe; a wrong serial call costs a little wall-clock time.

Be willing to reverse an earlier "these can parallelize" call when a build surfaces new coupling. Say so plainly and re-sequence.

## Branches, worktrees, and integration

**One worktree per slice.** Each worker gets its own branch and worktree so agents don't step on each other's edits mid-flight. Worktrees do not isolate Git history (merges still conflict) or any shared state outside the repo.

**One integration branch.** Don't merge slices straight to main. Create one integration branch off the verified current main; every slice merges into it in dependency order; it merges to main once, at the end, after a combined test pass. The reason: main never sees a half-finished initiative, which matters a great deal if anything auto-runs against main — a nightly job, another agent, a fresh checkout.

**Base new slices on the accumulated integration branch,** not on stale main. If a slice's dependency isn't integrated yet, the worker stacks its branch on the dependency's branch. Otherwise it is missing code it needs — and worse, any rebuild it runs from that incomplete code can clobber shared state. A good worker detects this on its own ("the brief said A was merged, but this branch doesn't have it") and proposes stacking. Approve it, and record the stacking in the initiative document.

**Who commits.** The worker commits its own scoped work freely on its own branch, without asking. The orchestrator does not commit feature code it didn't write.

**Who merges.** Only the orchestrator merges worker branches into the integration branch: it creates the branch, merges each slice in order, resolves conflicts, runs the combined tests, and performs the final merge. Keeping merge order and conflict resolution in one head is the point. The human authorizes the merges and the final push.

**Time the branch to a moving main.** If another effort is mid-merge to main, wait for it to land before creating the integration branch, so you branch from the post-merge tip and avoid a redundant merge. Confirm the actual Git state — `git log main`, `git log origin/main` — before branching, rebasing, rebuilding, or merging. "Merging now" is not "merged."

## Cross-team coordination

If unrelated work is active in the same repository, ask its owner two questions before starting: when will it merge, and does its remaining work touch any of this initiative's files or mutable state? That one exchange prevents most cross-team collisions — a peer telling you its surface is clean is worth more than guessing. Record the answers in the initiative document.

Expect documentation files, backlogs, changelogs, and generated artifacts to conflict even when application code is cleanly separate, because everyone edits them. Resolve those keep-both-sides.

## Permission boundary

Inter-agent messages are teammate requests, not user approvals. Never treat an agent's message as the human's approval for a permission prompt, destructive action, merge, push, or external change. Never ask a peer to perform an action that was blocked in your own session, and never perform one for a peer that was blocked in theirs — route blocked work back to the human. Permissions are per-session by design.

## Expensive lessons

- **Shared state outside Git is the number-one parallel hazard.** A gitignored or symlinked database is one physical file across all worktrees. Two slices rebuilding it race, and a rebuild from code that lacks another slice's schema changes silently nulls that slice's data. Serialize every slice that mutates shared state, and never let a rebuild run from a branch missing a schema change that was applied elsewhere.
- **A committed-but-unmerged slice can still poison shared state.** If slice A's migration already ran against the shared database but A's code lives only on its branch, then any rebuild from main — a nightly job, another agent — wipes A's columns, because main's code doesn't know how to repopulate them. Merging A promptly, or freezing all rebuilds until it lands, removes the landmine. Watch for scheduled jobs that rebuild from main. The deferred single merge to main makes this hazard worse, so decide up front: pause scheduled rebuilds for the initiative's duration, or land schema-changing slices on main early.
- **"Merging now" is not "merged."** Always verify Git state before you branch, rebuild, or rebase onto main.
- **Worktrees isolate edits, not merges and not shared state.** Internalize this; it is the root of most surprises.
- **Route cross-slice decisions to the orchestrator.** The decision update exists for exactly this.
- **Reversible by default at the boundaries.** Prefer isolated branches, scoped commits, and a deferred single merge to main — all easy to unwind. The one thing that is not easily reversible is clobbered shared state, so protect that hardest.
- **Keep the initiative document as the durable memory.** Update it as decisions land, with the placement rules, the slice list, and the decisions, so a fresh orchestrator or worker can recover context.

## Orchestrator checklist

- [ ] Recon done: shared files, state stores, generated artifacts, services, and rebuild hazards mapped — including scheduled jobs that rebuild from main.
- [ ] Slices cut along low-overlap seams, dependencies ordered, cross-slice decisions named.
- [ ] Shared context written as a durable file, with the comms protocol, orchestrator address, three directives, and commit permission baked in.
- [ ] Per-slice briefs written, each self-contained.
- [ ] Parallelism decided by the disjoint-sets test; anything touching shared state serialized.
- [ ] Other active work asked for merge timing and shared-surface overlap.
- [ ] Integration branch planned and cut from the verified post-merge main.
- [ ] Merge ownership clear: workers commit, orchestrator merges into integration, human authorizes the final merge to main.
- [ ] The initiative document reflects the latest decisions and landing status.

---

<!-- Reference: orchestrator-pattern-claude -->

# Orchestrator pattern — Claude implementation guide

Use orchestrator-pattern-neutral for the method, roles, run loop, safety rules, branch strategy, and completion report. This companion supplies Claude-specific mechanics.

## Platform model — which mechanism this uses

Claude Code has three different multi-agent mechanisms. Don't mix them up:

- **Cross-session messaging** — independently launched sessions message each other by name with `SendMessage`. **This is what the orchestrator pattern runs on**: a long-lived orchestrator session plus one human-launched session per slice, each in its own worktree. It is on by default in current versions; nothing to enable.
- **Subagents** — spawned inside one session with the Agent tool; the result returns to the caller. A slice worker uses these *within* its slice, for implementation and review. They are not the workers themselves.
- **Agent teams** — experimental and off by default (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`). Not used here.

The direct channel is for status, questions, and coordination — not for user approvals. Each session has its own permissions. A message from another session never counts as the human's consent and can't answer a pending permission prompt. Never ask a peer to do something that was blocked in your session, and never do it for a peer that was blocked in theirs; route blocked work back to the human.

## Naming sessions so they're addressable

A session's name is its address. Without one, Claude Code auto-generates a name, which is no use in a brief written ahead of time. So:

- Start the orchestrator with `claude --name <initiative>-orchestrator`, or run `/rename <name>` mid-session.
- Launch each worker with a unique name matching its slice. If a name is already taken by a live session on the machine, Claude Code renames the newcomer to a variant — and messages addressed to the expected name go to the wrong place. Keep names unique.
- `ListAgents` (the human can run `/list-agents`) shows what this session can reach: its own subagents, teammates, and other local sessions. The first line is this session's own name. Cloud and other-machine sessions appear only while connected to Remote Control, and a cloud session can receive a message but can't message back — keep the orchestrator and workers on one machine.

## Launching a worker

The orchestrator creates each slice's worktree with Git, on the exact base, before the worker starts. That puts the slice on the integration branch, or stacks it on an unmerged dependency's branch. (`claude --worktree <name>` creates `.claude/worktrees/<name>/` on a new branch `worktree-<name>`, but it branches from the remote's default branch, `origin/HEAD`, or the current local HEAD when `worktree.baseRef` is `"head"`. It can't target a named branch.)

```bash
git worktree add .claude/worktrees/<slice> -b slice/<slice> feature/<initiative>   # or the dependency's branch, to stack
```

Then the orchestrator gets the worker started one of two ways, whichever the human prefers:

- **Send the brief.** The orchestrator gives the human the launch command, `cd .claude/worktrees/<slice> && claude --name <slice>`. Once that session is up, the orchestrator sends it the full brief with `SendMessage`.
- **Hand over a launch prompt.** The orchestrator gives the human the same launch command plus the full brief, and the human pastes the brief as the session's first message.

If a worker was started with `--worktree` anyway, its first action is `git merge --ff-only feature/<initiative>`. If the fast-forward fails, it stops and tells the orchestrator instead of forcing it.

Either way, the worker's first check is the base: confirm with `git log --oneline -5` that the branch contains what the brief says it depends on. If the brief said slice A was merged and it isn't there, propose stacking rather than proceeding.

Other worktree mechanics worth knowing:

- A worktree is a fresh checkout: gitignored files such as `.env` are absent unless listed in a `.worktreeinclude` file at the project root, and dependencies need installing. Note that a gitignored database *copied* this way is a per-worktree copy, while a symlinked data directory is one shared physical store — know which one you have, because the neutral guide's shared-state rules hinge on it.
- For sessions started with `--worktree` or moved by `EnterWorktree`, isolation is enforced, not just conventional: Claude Code blocks edits and commands that target the main checkout. A session started by `cd`-ing into a `git worktree add` directory is an ordinary session in that directory, so there the boundary is discipline — the brief must say "work only in this directory." Either way, the orchestrator merges from the main checkout (or its own integration worktree), never from inside a slice's worktree.
- On exit, a worktree with work in it prompts keep-or-remove. **Keep it** until the orchestrator has merged the slice; removing deletes the directory and its branch.
- Resuming a session that was in a worktree returns it to that worktree.
- Mid-session, Claude can move itself with the `EnterWorktree` and `ExitWorktree` tools.
- Subagents can get their own temporary worktrees with `isolation: worktree` (Agent tool parameter or agent frontmatter). They branch from the same base rule as `--worktree`.

## Shared brief additions

Add these fields to every worker brief:

- **Orchestrator address:** `<exact session name>`.
- **Your session name:** `<slice name>` — launch with `--name` so the orchestrator can message you.
- **Initiative document:** `<path>`.
- **Communication:** use `SendMessage` for start, cross-slice decisions, and completion; if unavailable, print the same report for the human to relay.
- **Worktree, branch, and base:** `<paths and names>`, plus the branch this slice must be based on.
- **Model split:** run implementation subagents on a fast model (Sonnet) and the code-review subagent on a stronger model (Opus) before calling the slice done. Set this with the Agent tool's `model` parameter or the agent definition's `model` field.
- **Commits:** commit freely on your own branch without asking; never merge into the integration branch or main.

## Worker communication

Send these messages directly to the orchestrator:

```text
START — Slice <name> active. Worktree: <path>. Branch: <branch>. Base: <branch/commit>.
```

```text
DECISION — Slice <name> needs a decision: <question>. Impacted surfaces: <files/state/slices>. Local recommendation: <recommendation>.
```

```text
COMPLETION — Slice: <name>
Shipped: <changes>
Migration or rebuild: <yes/no; command>
Tests: <command; result>
Docs: <yes/no; paths>
Deferred or surprises: <notes>
Follow-on impact: <unblocked or affected slices>
```

Use DECISION for surprises the orchestrator should weigh in on too, not only formal cross-slice questions.

Do not wait idly for a reply to routine traffic. A message is read between the receiver's tool calls, or starts a new turn if the receiver is idle — so the orchestrator answers on a later turn, not in real time. Continue local work. Surface a cross-slice decision before making a change that would be hard to undo.

Put the whole message in the text. An `@`-mention of a file attaches nothing on the receiving side.

## Orchestrator coordination

1. Name yourself, then use `ListAgents` to confirm worker and peer names.
2. Ask active peers about merge timing and overlap with this initiative's files or shared state.
3. Use `SendMessage` to confirm decisions, change sequencing, or tell a worker when a dependency is safe to consume.
4. To hear when a worker finishes without polling, send with `notify_when_idle: true` — one notice arrives when that session next goes idle. Never loop on `ListAgents` or send "are you done?" messages.
5. Receive completion reports, inspect each branch, and merge only from the main checkout or the orchestrator's integration worktree.

**Delivery is not guaranteed to be read.** A successful send means the message reached the session, not that its Claude saw it:

- **Keep all sessions in the same permission mode.** A session that bypasses permission prompts holds messages from one that doesn't (and vice versa) for the human's approval, and a held message expires — five minutes by default. Plan mode counts as bypassing in interactive terminals. On the same machine the sender gets a notice when a message is held, denied, or refused.
- A session can be configured to refuse inbound messages (`crossSessionInbound`).
- Never treat silence as agreement.

## Worktree rules

One isolated Git worktree per slice. Workers commit scoped changes to their own branches but must not merge into the integration branch or main. If a dependent slice needs unmerged work, stack its branch on the dependency branch and record that relationship in the initiative document.

Never assume worktrees isolate a gitignored database, symlinked data directory, cache, generated output, or external service. Serialize work that mutates those surfaces.

## Claude-specific fallback

A session can lack the messaging tools when it was started in bare mode (`--bare` binds no inbox), when permission rules deny `SendMessage` or `ListAgents`, when inbound messages are set to refuse, or on an old Claude Code version. It still follows the neutral guide: write the completion report into the initiative document or print it in the session for the human to paste to the orchestrator. Do not omit the report because messaging is unavailable.

## Official references

- [Cross-session messaging](https://code.claude.com/docs/en/cross-session-messaging)
- [Worktrees](https://code.claude.com/docs/en/worktrees)
- [Subagents](https://code.claude.com/docs/en/sub-agents)
- [Agent teams](https://code.claude.com/docs/en/agent-teams)

---

<!-- Reference: orchestrator-pattern-codex -->

# Orchestrator pattern — Codex implementation guide

Use orchestrator-pattern-neutral for the method, roles, run loop, safety rules, branch strategy, and completion report. This companion uses current Codex terminology and mechanics. Codex's multi-agent surface is moving fast — when something here disagrees with your installed CLI, trust the CLI and update this doc.

## Platform model

Codex calls this a **subagent workflow**. The **main thread** (the subagent docs also say "main agent"; the config reference says "primary thread" — same thing) delegates bounded tasks to **subagents**, which work in their own **agent threads**. The main thread collects and consolidates their results, and can steer a running subagent with follow-up instructions.

Use "orchestrator" as the role name in the initiative, and "main thread" when describing Codex mechanics.

Route all cross-slice communication through the main thread. Codex documents no channel for separately started sessions to message each other, and with default settings spawned workers can't address one another either. Don't design a run that depends on worker-to-worker messages.

## Choosing a launch mode

The neutral guide describes two launch modes. On Codex they trade off like this:

- **Spawned subagents (native).** The main thread spawns one subagent per slice and gets each completion report back automatically. You lose the per-slice brainstorm with the human — the subagent runs from its brief — so the brief has to carry everything, and the spec for each slice should be settled in the main thread before spawning. Nesting limits apply (next section).
- **Separately started sessions (manual).** The human opens a Codex session per slice and works it interactively, which keeps the brainstorm and review. There is no messaging between sessions, so coordination runs through the initiative document, Git state, and human relay. Treat this as manual orchestration, not direct inter-agent communication.

Pick per initiative. Slices that need real design conversation favor separate sessions; well-specified slices favor spawned subagents.

## Nesting: plan for one level

In the Codex source, agent nesting depth defaults to 1 (`agents.max_depth`), so a spawned subagent cannot spawn its own subagents — it is told to solve the task itself. This key is not in the published config reference, so treat it as an implementation detail rather than something to tune, and confirm the behavior on your version if the design depends on it.

The consequence for this pattern: a slice worker can't run its own implementer and reviewer subagents, which is how the neutral guide's "split models by job" directive is usually satisfied. So keep the fan-out flat:

1. The worker subagent implements its slice from the written spec and reports.
2. The main thread then spawns a **review subagent** for that slice — a sibling of the worker, on a stronger model or higher reasoning effort — before the slice counts as done.
3. Review findings go back to the worker as a follow-up instruction, or to a fresh worker.

## When to delegate

Ask Codex directly to spawn subagents for independent, bounded work. The main thread should state the split, whether to wait for every result, and the expected report format.

Codex's own guidance is to reach for parallel subagents first on read-heavy work — exploration, tests, triage, review, summarization — and to be more careful with parallel writes. For this pattern, the neutral guide's disjoint-sets test governs write-heavy slices: parallel is fine when edited files and mutable state are disjoint and there is no semantic dependency; otherwise serialize.

Example request:

```text
Use a subagent workflow for this initiative. Spawn one subagent per independent slice, give each the shared context and its slice brief, wait for all required reports, and consolidate the results in the main thread. Route cross-slice decisions back to the main thread before implementation proceeds. After each slice reports, spawn a separate review subagent for it before marking it done.
```

## Shared brief additions

Add these fields to every subagent brief:

- **Main-thread responsibility:** return the structured completion report to the main thread.
- **Decision rule:** do not independently resolve a shared-schema, interface, dependency, or mutable-state decision; surface it to the main thread.
- **No nesting:** do not try to spawn further subagents; the main thread runs review.
- **Durable fallback:** if the session is separate or cannot return to the main thread, update `<initiative document path>` or print the report for human relay.
- **Worktree and branch:** `<assigned paths and names>` when implementation requires isolation.

## Communication and control

The main thread owns orchestration: spawning subagents, routing follow-up instructions, waiting for results, and consolidating the outcome. Ask Codex to steer, stop, or close a running subagent when the sequencing plan changes.

Slash commands, as of codex-cli 0.155.1:

- `/agents` — view and switch between all active agent sessions.
- `/subagents` — switch between this session's subagents.

OpenAI's docs currently say `/agent`; that command doesn't exist in the CLI. Check the slash-command menu on your version.

Things that bite long-running orchestration:

- **Close completed threads.** `agents.max_concurrent_threads_per_session` caps concurrently *open* spawned-agent threads, so finished subagents hold slots until they are closed. Close each one after consolidating its report.
- **Approvals interrupt.** An approval request from a background subagent can surface while you're viewing the main thread. A "wait for all reports" step can be sitting on an unanswered prompt — check before assuming a slice is slow.
- **The web sidebar is read-only.** It reports subagent activity but can't stop or steer one. Drive orchestration from the app, CLI, or IDE.

The completion report uses the neutral guide's structure. A subagent should return concise findings and results to the main thread rather than raw command output.

## Custom agents

Codex supports built-in roles named `default`, `worker`, and `explorer`. Define narrow project-specific custom agents in `.codex/agents/*.toml`, or personal ones in `~/.codex/agents/*.toml`. A custom agent file defines `name`, `description`, and `developer_instructions`; it may also set `model`, `model_reasoning_effort`, `sandbox_mode`, MCP servers, and skills.

Use custom agents for stable, repeated roles such as read-only code mapping, security review, documentation research, or focused implementation. Keep their responsibilities narrow and their tool access proportional to the task. This is also where the model split lives: give the implementer agent a fast model and the reviewer agent a stronger model or higher `model_reasoning_effort`.

## Configuration vocabulary

Multi-agent settings live under `[agents]` in `config.toml`:

- `agents.enabled` — defaults to true; set false to disable multi-agent tools.
- `agents.max_concurrent_threads_per_session` — cap on open spawned-agent threads, excluding the main thread. `agents.max_threads` is a legacy alias.
- `agents.default_subagent_model`
- `agents.default_subagent_reasoning_effort`
- `agents.interrupt_message` — record a model-visible message when an agent turn is interrupted.

Explicit spawn settings override these defaults. Subagents inherit the parent's sandbox and approval constraints unless their configuration says otherwise; a blocked action must return to the human rather than being treated as approved by another agent.

Feature flags around multi-agent are in flux. Run `codex features list` to see what your install has enabled.

## Worktree and state rules

When multiple subagents edit, give each slice a unique worktree and branch. Let subagents commit their scoped work without asking, but leave integration-branch merges to the main thread's orchestrator role.

Worktrees do not isolate gitignored databases, caches, generated artifacts outside Git, symlinked directories, or external services. Serialize anything that writes the same mutable surface, and never rebuild shared state from a branch that lacks an already-applied schema change.

## Official references

- [Subagents](https://learn.chatgpt.com/docs/agent-configuration/subagents)
- [Configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference)

`developers.openai.com/codex/*` redirects to these.