---
name: claude-orchestrator
description: >
  Claude Code-only orchestration workflow: keeps the main thread on a fast,
  steerable Sonnet driver as the human communications channel, checks whether
  the user's current model and effort level match the task, routes multi-phase
  epics to right-sized subagents (Opus for deep architecture/research, Sonnet
  and Haiku for execution/fan-out) via Agent tool overrides or custom agent
  profiles, enforces strict worker caps, and uses artifact-first handoffs to
  eliminate token duplication and preserve prompt caching. Triggers:
  claude-orchestrator, claude orchestrate, orchestrate with claude,
  sub-orchestrate.
---

# Claude Orchestrator (`claude-orchestrator`)

Claude Code-only orchestration workflow. Keeps the human-facing main thread
thin, fast, and interruptible while delegating deep architectural thinking and
bounded execution to right-sized Claude subagents with strict quota and
prompt-cache discipline.

Loading or installing this skill does not by itself spawn subagents. Ordinary
small tasks stay inline (Tier 0).

---

## 1. Roles, Models & Effort Levels

Claude Code supports pinning subagent `model` and `effort` both **dynamically**
via the `Agent` tool parameters and **statically** via `~/.claude/agents/*.md`
frontmatter (`model:` + `effort:`), with `CLAUDE_CODE_SUBAGENT_EFFORT` available
as an environment ceiling.

| Role | Default Model / Effort | Escalation / Alternative | Responsibility |
| :--- | :--- | :--- | :--- |
| **Communications Driver** *(Main Thread)* | `sonnet` (`low` or `medium`) | Keep main thread light; never park on `opus (high/max)` for routine chat | Talk with the human, catch voice-to-text/intent issues, run pre-flight checks, dispatch and steer subagents, present concise summaries. |
| **Architect / Deep Research Subagent** | `opus` (`high`) | `opus` (`xhigh`) *(hard security invariants, greenfield system design)* | Deep codebase research, trade-off & threat modeling, multi-file plans. Writes full plan to an artifact file; returns only a 5–10 line summary + decisions. |
| **Builder Subagent** | `sonnet` (`medium`) | `sonnet` (`high`) *(cross-layer debugging, tricky refactors)* | Reads the plan file + bounded paths, implements changes, runs targeted tests/verification, reports concise outcome. |
| **Scout / Fast Worker** | `haiku` (`low`/`medium`) or `sonnet` (`low`) | — | Fast read-only codebase searches, log skimming, mechanical edits, verification sweeps. |

---

## 2. Quota & Efficiency Guardrails (Hard Rules)

* **Protect Opus quota:** Never run routine file searches, formatting, or test loops on `opus`. Reserve `opus (high/xhigh)` strictly for one-shot design, architecture, security reviews, and deadlocks where `sonnet` stalled.
* **Concurrency cap:** Cap parallel subagents at **≤ 3 concurrent workers** unless the user explicitly requests wider fan-out.
* **Respect Claude's prompt-cache TTL (5 min / 1 hr sliding) — Clean Switch Rule:**
  * KV caches are tied to a model's weights. **Never advise switching models mid-thread** (e.g., planning on `Opus` and then flipping that same thread to `Sonnet`), which causes a **100% hard cache miss** on the entire conversation history.
  * Offer a `/model` switch only on **Turn 1** (before context builds). Mid-thread, keep the main thread on the same model (stepping effort only when warranted). When transitioning from a heavy planning phase (`Opus`) to execution (`Sonnet`/`Haiku`), **never tell the user to flip the current thread's model**—save the plan to a file on disk and either dispatch a **fresh subagent** or tell the user to **open a brand-new thread** on the target model with a **ready-to-paste starter prompt** referencing that plan file. Work in focused bursts and `/compact` or start fresh between unrelated tasks.
* **No recursive nesting:** Claude Code subagents should stay flat (Main Thread → Specialized Subagents) rather than nesting subagents inside subagents.

---

## 3. User-Only Pre-Flight Check (Main Thread Only)

Run only on the human-facing main thread—never inside subagents:

1. **Model & Effort Fit Check:**
   * If the current model/effort is visible and mismatched to the task (e.g., `Opus High` on a trivial one-liner, or `Sonnet Low` on a deep security/architecture review that won't be delegated), briefly offer either the `/model` / effort switch or to keep the main thread on `Sonnet` and delegate the heavy pass to an `Opus (High)` subagent.
   * Never nag on routine turns or silently mutate global settings.
2. **Voice-to-Text & Ambiguity Guard:**
   * Before spawning `Opus` or multiple parallel `Builder` subagents, check for likely dictation misspellings or high-cost ambiguity and confirm in 1–2 lines if anything looks off.

---

## 4. Complexity Router (3 Tiers)

| Tier | Task Shape | Action |
| :--- | :--- | :--- |
| **Tier 0 — Inline** | Quick Q&A, single-file edit, short command | Execute directly in the main thread. Zero subagent overhead. |
| **Tier 1 — Single Subagent** | Self-contained research, test sweep, single-module change | Spawn one right-sized subagent (`haiku`/`sonnet` for scout/build, `opus` for design). |
| **Tier 2 — Multi-Phase Epic** | Research → plan → multi-module implementation | Run the 3-phase flow below (≤ 3 concurrent subagents). |

### Tier 2 Flow
1. **Plan (`opus`, `effort: high`):** Spawn a single fresh architect subagent to research and write the full plan to a scratch/plan file on disk (never committed to product repos). It returns only a 5–10 line summary, file path, and open decisions.
2. **Human Checkpoint (Main Thread):** Present the summary + artifact link + decisions to the user for steering or approval.
3. **Execute & Verify (`sonnet` `medium` / `haiku`):** Spawn up to 3 bounded subagents passing **only the plan file path + target files**, never the main thread's conversation history. Reconcile results and report concisely.

---

## 5. Artifact-First Handoff Contract

Every subagent prompt **must** include:
* **Write full output to disk:** Save complete plans, audit tables, and lengthy diagnostics to a scratch/artifact file on disk.
* **Return a compact payload:** Reply to the main thread with **only**:
  1. **Summary** (5–10 lines max)
  2. **File path**
  3. **Decisions / Blockers** requiring human input
* **Never duplicate full transcripts:** Downstream subagents start clean and read the artifact file directly.
