Orchestrator

Orchestrator

Use this skill when the user wants the current thread to act as a chief-of-staff thread: route work, keep context, supervise child threads, arbitrate conflicts, and avoid doing implementation locally.

Commands

• $orchestrator on: activate orchestration-only mode for this thread.
• $orchestrator off: return this thread to normal local execution.
• $orchestrator status: report mode, active child threads, checkout slots, branches, ports, data strategies, blockers, and push state.

Routing is automatic while orchestrator mode is on. Do not invent a manual routing command.

Mode And Claim Discipline

Worktrees alone are not orchestrator mode.

The parent may create worktrees, copy ignored environment files, install dependencies, and serialize PR or merge work as setup. That is direct-worktree coordination until durable child threads are created or reused and implementation instructions are sent to them.

Before code-changing work starts under an orchestrator claim:

1. Record orchestrator mode: on in the active plan or status.
2. Find the durable Codex thread tools.
3. Create or reuse one child thread per checkout or workstream key.
4. Record the child thread id, checkout path, branch, port, data strategy, and conflict group.
5. Send implementation instructions before the child mutates code.

A durable child thread id belongs to a visible Codex thread created or found through thread-management tools. A hidden sub-agent, worker id, nickname, or submission id is not a durable child thread id.

If the child thread is attached to the root project but assigned to a manual sibling worktree, every apply_patch target must be absolute under the assigned worktree. Bare relative patches may hit the root checkout. The parent prompt must state this, and the child must audit after its first edit that the root checkout was not modified. If work leaks into the root checkout, stop before review, push, or PR; recreate or move the work into the assigned worktree and remove only the accidental root changes.

If durable thread tools are unavailable, record orchestrator blocked: durable thread tools unavailable and stop unless the user explicitly allows a non-orchestrated fallback. Never execute locally and still call the run orchestrated.

Do not use hidden workers, temporary sub-agents, or non-sidebar delegation tools for orchestrator child execution, status, review, or PR closeout. If one was started by mistake, pause it, park its work, record the workflow miss, and move the lane to a durable Codex child thread before review, push, PR, or the next implementation lane.

Core Contract

When orchestrator mode is on:

• Do not implement product code in the parent thread.
• Route code-changing work to durable child threads automatically.
• Reuse the same child thread for the same checkout slot or workstream.
• Keep the parent for intake, triage, routing, status, summaries, context forwarding, conflict arbitration, push serialization, merge coordination, and closeout.
• Keep the root checkout for coordination and repo-owned planning or agent guidance unless the repo explicitly assigns another parent-only surface.
• If implementation or PR work is already on the root checkout, stop before review, push, or PR. Move or recreate it in a disposable worktree branch from main and keep the root as scheduler.
• For every implementation or PR branch, create or reuse a durable child thread first, then assign a disposable worktree with a short-lived branch from main, even when work is serial.
• Fan out independently runnable packets across separate worktrees. Expected merge conflicts are not enough to serialize; record a conflict group and resolve conflicts when they become real.
• Open ready PRs back to main after repo-required checks and relevant proof pass. Merge when repository policy and the hosting service allow it.
• After merge and tracker or handoff closure, delete the disposable worktree, archive the finished child thread, and release its slot unless a recorded blocker still owns it.
• If mode state is unclear for implementation work, find or create the child thread before executing.

Implementation Work

Implementation work is any task expected to create, modify, review, or continue product code, tests, migrations, issue-linked docs, a runtime plan, a branch, or a PR.

Examples:

• Ticket or issue execution.
• API or data migration work.
• PR feedback resolution.
• Code-changing bugs, features, refactors, or upgrades.
• Goal-backed work that touches files or checkout state.
• Follow-ups such as continue, fix CI, push, commit, that slot, or that checkout when they refer to code-changing work.

Not implementation work by default:

• One-off answers.
• Read-only status summaries or reviews.
• Cross-thread triage.
• External context intake.
• Parent-owned plans or agent guidance that repo instructions keep on main.
• Asking which child owns a checkout when the mapping is missing.

Workspace Modes

Choose the lightest honest mode:

• parent-root: coordination, non-mutating triage, merge arbitration, and parent-owned planning or agent guidance. It is not an implementation or PR review checkout.
• single-worktree: serial implementation when packets have a true hard conflict, such as the same migration, generated artifact, config contract, security policy, records, or unmergeable file lines.
• same-checkout: non-mutating child coordination only. Never let two child threads mutate the same checkout concurrently.
• worktree: every implementation packet and PR branch. Each worktree has a unique short-lived branch based on main and a PR back to main.

Nearby components, the same product area, or a few expected merge conflicts are not hard conflicts.

main Policy

• main is the default integration branch and PR target.
• Base every child branch on current main.
• Before opening or updating a PR, fetch origin main when it exists, integrate origin/main using the repo's required strategy, rerun required checks and proof, then push the short-lived branch.
• PRs are ready unless the user or repo instructions require draft state.
• Merge into main when checks pass and repository policy allows it.
• Never force push.
• If integration conflicts are non-trivial, the child reports them to the parent instead of widening scope.
• The parent serializes push, PR, merge, and cleanup when concurrent lanes could race.
• After merge and release, return main to the root checkout. Do not leave a disposable scheduler worktree as the long-lived owner of main.
• Never hide active run deliverables in a stash just to switch the root checkout. Park them on an explicit branch or report the blocker.

Data And Runtime Policy

• Shared local data is acceptable for read-only work or clearly disjoint writes.
• Use a per-slot database or data fixture for schema work, migrations, seeds, destructive cleanup, broad mutation tests, or overlapping record writes.
• If shared-data conflict risk appears mid-run, pause the packet and ask the parent to serialize it or move it to isolated data.
• Runtime ownership must be explicit. A parent-owned runtime cannot be killed or reused by a child without reassignment.
• Each runtime-owning child gets a unique port and explicit stop condition.