orchestrate

name

orchestrate

description

Execute tasks of any complexity by delegating granular work to subagents, with the main session acting as the orchestrator the user interacts with. Use when carrying out coding tasks: delegate mechanical implementation, verification, and search to subagents on models strictly smaller than the current one, keeping planning, ideation, conversation, and anything needing the current model in the main session.

Orchestrate

The main session is an intermediary between the user and subagents. It plans, decides, reviews, and talks to the user; subagents do the granular work. Subagent reports are invisible to the user, so the orchestrator relays whatever matters.

Division of labor

Keep in the main session (never delegate):

• Planning, ideation, architecture and design decisions
• Anything needing user input; all conversation with the user
• Reviewing subagent output; committing
• Judgment calls that change scope mid-task

Delegate to subagents:

• Mechanical coding: implementing an already-specified change, bulk edits, migrations, boilerplate, renames
• Verification: running tests/lint/build and reporting output, reproducing bugs, driving UI checks
• Research: locating code, summarizing files, gathering facts (use the Explore agent for read-only searches)
• Any granular, self-contained subtask with clear success criteria

Model selection

Only delegate to models smaller than the session's current model. Work that needs the current model's capability stays in the main session — never spawn a subagent at the same tier or higher, and never omit model to inherit.

Tiers, smallest first: haiku → sonnet → opus.

• haiku: searches, file summaries, trivially mechanical edits, running checks and reporting raw output
• sonnet: standard implementation work, multi-file mechanical changes, verification needing some judgment
• Needs the current model (subtlety, or a wrong result is expensive to detect): do it in the main session

So a session on opus may delegate to sonnet or haiku; a session on sonnet may delegate only to haiku; a session on haiku does not delegate coding work at all — it does the work itself. Always pass model explicitly on every delegation.

If a subtask is too subtle for the largest model you're allowed to delegate to, either decompose it until the mechanical parts fit a smaller model, or keep it in the main session. Do not delegate it anyway and hope.

Send independent delegations in a single message so they run in parallel. Use isolation: "worktree" when parallel agents mutate files.

Karpathy guidelines

Decide per task:

• Complex or ambiguous task: invoke the karpathy-guidelines skill in the orchestrator before planning.
• Simple task: skip the skill entirely.
• Mechanical coding delegation: always paste the block below into the subagent's prompt (sections 1-3). Section 4 (goal-driven execution) stays with the orchestrator, which owns success criteria and the verify loop.

Guidelines for this task:
1. Think before coding: state assumptions explicitly; if the spec is
   ambiguous or something is confusing, stop and report back instead of
   guessing silently.
2. Simplicity first: minimum code that solves the problem. No speculative
   features, abstractions for single-use code, unrequested configurability,
   or error handling for impossible scenarios.
3. Surgical changes: touch only what the task requires. Don't improve
   adjacent code, comments, or formatting; match existing style. Remove
   only imports/variables YOUR changes orphaned. Every changed line must
   trace to the task.

Delegation prompt shape

Every delegated prompt includes:

• Exact scope: files, symbols, and the expected change
• What NOT to touch
• Success criteria the agent can check itself before returning
• What to return: raw facts (diff summary, test output, file:line locations), not prose

Loop

1. Clarify and plan with the user (main session; use karpathy-guidelines if complex).
2. Break the work into self-contained subtasks with verifiable outcomes.
3. Delegate, parallelizing independent subtasks.
4. Review each result; verify with a verification subagent or directly.
5. Report the outcome to the user; commit only after review.