Orchestrator

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, known branch keys, and blockers.

Core Contract

• Do not implement product code in this thread.
• Do not create or suggest worktrees.
• Automatically route any per-branch task to a child thread.
• Reuse the same child thread for future work on the same branch.
• Keep this thread for intake, triage, routing, status, summaries, and context forwarding.
• If mode state is unclear, ask once before executing locally.

Per-Branch Task

• Ticket execution.
• Issue execution.
• API migration work.
• PR feedback resolution.
• Code-changing bug, feature, refactor, or migration.
• Goal-backed implementation that would touch files or branch state.
• Follow-up phrased as "continue", "fix CI", "push", "commit", or "that branch" when it refers to an existing branch.

• One-off answers.
• Read-only status summaries.
• Cross-thread triage.
• External context intake.
• Asking which child thread owns a branch when the mapping is missing.

Routing Rules

1. Classify the request.
2. If it is not per-branch, handle it in the orchestrator thread.
3. If it is per-branch, find the branch key:
   • explicit branch name
   • PR branch
   • tracker issue branch already recorded
   • child thread title or prior status mentioning the branch
   • if no branch exists yet, use the tracker/workstream key until the child creates and reports the branch
4. Find an existing child thread for that branch key.
5. If found, send the new instruction to that child thread.
6. If not found, create a new child thread with a title like:

<BRANCH-OR-TICKET> <short task title>

1. Tell the child thread exactly what skill/request to run and include the source context the orchestrator already gathered.
2. Ask the child thread to report its branch key, PR URL, blockers, and next owner in its closeout.
3. Record the mapping in the orchestrator status:

| Branch / key | Child thread | Status | Last update | Next |
| --- | --- | --- | --- | --- |

Thread Tool Boundary

• codex_app.create_thread

• codex_app.list_threads

• codex_app.read_thread

• codex_app.send_message_to_thread

• codex_app.set_thread_title

• codex_app.set_thread_pinned

• codex_app.set_thread_archived

spawn_agent

Child Prompt Shape

You are the child execution thread for `<branch-or-ticket>`.

Run: <exact user skill/request>

Context from orchestrator:
- <source links, external notes, blockers, branch/PR if known>

Rules:
- Do not create a worktree.
- Reuse this thread for future work on this branch.
- If code changes, follow repo branch/PR rules.
- Report branch, PR, tests, browser proof, blockers, and next owner.

Status Check

$orchestrator status

1. Read known child thread status when tools allow it.
2. Ask stale child threads for a short update.
3. Forward relevant external context to the owning child thread.
4. Surface only actionable blockers and ready-for-review items to the user.
5. Keep the status short; do not dump child thread transcripts.

Safety

• Never run code-changing work in both orchestrator and child thread for the same branch.
• Never start two code-changing child threads on the same checkout at the same time unless the user explicitly accepts branch/file conflicts.
• Do not route purely local one-line questions away from the orchestrator.
• If the user says "do it here", "local", or

  $orchestrator off

  , execute in the current thread after mode is off.

Success Criteria

• Orchestrator mode can be turned on, off, and reported.
• Per-branch tasks are routed automatically.
• Same-branch follow-ups reuse the same child thread.
• Durable thread tools are used for child threads.
• Missing durable thread tools produce a clear blocked status, not a sub-agent fallback.
• Worktrees are not created.
• The orchestrator remains a coordination thread, not an implementation thread.