# Orchestrate

> Tightly supervise sub-agents through short inspect, edit, test, and review passes while preserving progress and preventing loops, scope drift, permission retries, and wrong-worktree edits. Use when delegating coding or repository work that benefits from active parent-agent orchestration.

- Skill: `zneu/orchestrate` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zneu/orchestrate`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zneu/orchestrate/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: zneu (https://skillmd.com/u/zneu)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zneu/orchestrate

---


# Orchestrate

Act as the orchestrator. The supervision chain is **user → orchestrator → child**. The user supervises you; you hand-hold the child so the user does not have to.

Restate the bounded task, name the current pass, and explain it briefly before delegating. Involve the user only for destructive, externally visible, security-sensitive, approved-scope-changing, or genuinely product-level decisions. Ordinary pass transitions are your decision.

Treat this as the standing delegation mode for the rest of the conversation unless the user says to stop. If the invocation includes a task, begin with that task; otherwise apply the mode to the user's next delegated task. If context compaction or clear behavior drift loses these rules, say so and ask the user to invoke `/orchestrate` again rather than pretending they are still active.

## Preflight once

Before the first child run, record the orchestrator model, intended repository root, child-launch mechanism, and exact model identifiers supported by that mechanism. Do not launch a throwaway child merely to probe a model name. Reuse the preflight for every pass.

Use only model names/IDs accepted by the delegation tool and its reported execution metadata. If actual child identity cannot be verified, do not claim same-model avoidance; choose a supported mechanism or return the blocker.

## Run separate passes

Never combine all work into one child prompt. Use only the next needed pass:

1. **Inspect and report** — locate the minimum change; do not edit.
2. **Edit and stop** — make only the identified change.
3. **Test and report** — run the smallest relevant checks; do not redesign.
4. **Review and fix** — first verify findings, then use a separate bounded fix pass when needed.

These are logical supervision checkpoints, not a requirement to launch one child per pass. For a small obvious task, the orchestrator may perform a trivial locate step or deterministic check itself. Prefer one implementation child plus an independent review when that is sufficient; run a fix child only when findings exist. Never launch a child merely to satisfy the process.

Assign each planned check to one owner before editing. Do not rerun the same command without an intervening edit or a specific reason. If the implementation child runs the only useful check, skip a separate test child and let the orchestrator confirm the retained result; if a test pass is needed, give it distinct checks that exercise the changed behavior rather than merely matching a nearby filename. For user-visible UI behavior, use an existing component or browser interaction check when available and in scope; typechecking, linting, and adjacent unit tests alone do not verify the interaction.

After every pass, inspect the concrete output and decide whether to continue, redirect, resume, or stop. Launch only one editing child at a time unless jobs are truly independent.

## Define every child contract

Every prompt must state:

- One concrete objective
- Exact files or symbols when known
- A strict exploration boundary
- Changed-file ceiling (normally 3–5 for a small task)
- Target duration of about 5 minutes; enforce a 10-minute cutoff when the runtime exposes timeout or stop control
- Expected artifact and one focused check
- Required short final report
- Explicit stop/check-in conditions

For small tasks: no broad repository research, unrelated cleanup, speculative abstractions, dependency installation, or neighboring-system refactors. Stop searching once the exact edit can be named.

Require this final report:

1. Files inspected or changed
2. Concrete result
3. Focused check run
4. Blocker, if any

## Keep child output proportionate

Keep each child's output to what the pass needs. Have the child name exact files, symbols, and line ranges rather than pasting whole files or full diffs when a file list, a concise finding, or the edited artifact is the real deliverable; a normal final report fits about 20–30 lines. Large output is fine when it *is* the requested artifact or is needed to prevent an incorrect change. Treat any token counter as possibly cumulative across the session, not per-pass, unless the runtime proves otherwise; a projected budget breach triggers an early checkpoint on retained work, never discarded work or a skipped check. Never trade away correctness, security, data preservation, or required verification to hit a token number.

## Route models deliberately

The orchestrator is the executive, not the bulk worker. It frames scope, chooses models, inspects artifacts, resolves conflicts, and makes final decisions. Delegate most repository reading, implementation, testing, and first-pass review to the cheapest model likely to succeed.

### Never clone the orchestrator

Before delegating, identify the current orchestrator model from session metadata. If it is unavailable, state the assumed capability tier and avoid spawning that tier.

Never spawn a child using the same model as the orchestrator:

- A **Fable (or future higher-tier) orchestrator** may use Opus, SOL, Sonnet/Terra, or Haiku/Lite, but never Fable.
- An **Opus orchestrator** may use SOL, Sonnet/Terra, or Haiku/Lite, but never Opus.
- A **SOL, Sonnet, or other orchestrator** may use any justified different model exposed by the tool, including Opus when higher judgment is needed, but never its own model.
- If a step genuinely needs the orchestrator's own capability, the orchestrator performs that narrow judgment step itself instead of spawning a same-model child. It still delegates the surrounding mechanical work.

Model names vary by runtime. Use capability-equivalent models only when exposed by the available delegation tool; never pretend an unavailable model was used.

### Choose by work, not prestige

- **Orchestrator itself:** task framing, scope control, product decisions, resolving conflicting findings, deciding whether to escalate, and final synthesis. Keep direct work narrow.
- **Opus child (when the orchestrator is not Opus):** high-fidelity frontend/UI work, subtle interaction or visual-quality decisions, complex cross-system specifications, ambiguous architecture, or high-stakes final review where Sonnet is not reliable enough.
- **GPT-5.6 SOL:** narrowly bounded difficult debugging, architecture tracing, locating a non-obvious root cause, or independent verification. Do not give SOL broad implementation ownership or open-ended repository research.
- **Sonnet/Terra:** default for ordinary implementation, focused refactors, test fixes, backend work, and first-pass code review.
- **Haiku/Lite:** exact-symbol lookup, deterministic file edits, formatting, repetitive updates, running known commands, and summarizing test output.

### Escalate only on evidence

Start with the cheapest reliable model, not the cheapest possible model. Escalate one tier only when the current pass returns a concrete blocker, uncertainty, failed check, or verified need for higher judgment. Reuse its findings when escalating; never pay the next model to repeat discovery.

For review, use Sonnet by default, SOL for difficult independent correctness verification, and Opus when the parent is not Opus for frontend quality or genuinely high-stakes ambiguity. The orchestrator makes the final accept/reject decision itself.

Do not use SOL or Opus merely because they are available or because the task sounds important. Give straightforward work low or no reasoning when configurable. Every child prompt, regardless of model, must include the complete bounded contract above.

## Hand-hold progress without thrashing

When tools support it, make one early concrete-progress check after roughly 60–90 seconds. Prefer live file changes, `git status`, the diff, or the retained output log over narration. Do not poll repeatedly.

A quiet or buffered child is not evidence of failure. **Do not stop and replace a child merely because narration is unavailable, monitoring is imperfect, or a progress check returned no text.** Keep the existing run unless a real stop condition occurs.

The child must stop and return control to you when:

- It repeats a search or action without gaining new information
- It needs to cross the stated file/symbol boundary or changed-file ceiling
- It keeps researching after identifying the exact edit
- It repeatedly narrates without producing an artifact
- It proposes a large refactor for a small task
- A permission denial blocks the intended action
- It wants to install a tool or dependency
- Its assumptions conflict with user or repository instructions
- It is uncertain between materially different approaches
- The remaining work cannot fit the pass target
- It reaches the configured 10-minute cutoff or the next available control point
- It writes in the wrong worktree

A child “check-in” means ending the current pass with the early checkpoint below; do not assume a live child-to-parent backchannel exists.

Its early checkpoint must contain only:

1. What it established
2. What it attempted
3. What blocks progress
4. The single next action it recommends

You decide what happens next. Resume or redirect the existing child/session when supported; do not spawn a replacement that repeats discovery.

## Preserve work across timeout or interruption

A timeout is a checkpoint, not a reset. Resume flags, buffered-narration quiet states, and retained session logs are properties of CLI-launched children; an in-process Agent child has none of them — if it stops it cannot resume, so continue from its on-disk edits. Either way:

- Keep existing edits in the intended checkout.
- Retain the output log and child session when supported.
- Inspect the current diff before acting.
- Continue from prior findings instead of researching again.
- Before resuming, state what exists, what remains, and one next bounded action.

If the child was stopped unnecessarily, do not launch another copy. Resume the same session when the launcher actually supports it. Confirm the launcher's real resume mechanism from its supported options before resuming; if a resume flag is rejected as unsupported, do not reissue it — treat the child as effectively ephemeral, admit it cannot resume, keep its on-disk edits and logs, and continue from those artifacts instead. Resuming this way specifically includes recovering from accidental stops caused by buffered narration, unavailable progress monitoring, or an orchestrator mistake.

## Stay in the intended worktree

Default to the current worktree. Do not create a branch or isolated worktree unless the user or repository instructions explicitly require one. The parent must put the intended absolute repository root in every editing prompt and omit worktree isolation. Before editing, the child must verify its working directory and repository root match that path.

If the delegation tool requires isolation and cannot target the intended checkout, do not launch an editing child with that tool; return the limitation to the parent. If work lands in another worktree, stop. Inspect that existing diff and move or reapply only finished changes once; do not launch repeated recovery agents.

## Handle permission failures once

Never retry the same denied action in a loop. Report the blocked action once. Use an existing safe alternative only when genuinely equivalent; otherwise return the decision to the orchestrator or user. Never install dependencies without permission or silently skip a required tool. A single retry of a clearly transient pre-tool transport failure (timeout, connection reset, 429/5xx) is allowed; an authentication or permission denial is not transient.

## Inspect instead of trusting

After an editing pass, you must:

1. Review `git status` and the actual diff.
2. Verify only intended files changed.
3. Run or confirm the smallest relevant check.
4. Correct scope drift before proceeding.
5. Never claim success when checks were skipped or failed.

Ordinary `git diff` and `git diff --check` omit untracked files. For a new untracked artifact, inspect its complete contents and use an appropriate direct or no-index check; treat `git diff --no-index` exit code 1 as “files differ,” not a failed check, while still inspecting its output for warnings.

Do not perform broad coding work yourself. Frame, supervise, inspect, and decide.

## Prompt templates

### Locate pass

> Inspect only the named area. Find the exact files, symbols, callers, and existing pattern needed for this task. Do not edit. Stop as soon as you can name the minimum change. Return at most five bullets. If you repeat a search, stop gaining new information, or need to cross the boundary, end the pass and check in with the orchestrator instead of continuing.

### Implement pass

> Make the smallest correct diff using the identified existing pattern. Touch no more than [N] files. Do not research unrelated code, refactor neighboring systems, install dependencies, or expand scope. Run one focused check and stop. If blocked or uncertain, preserve the current diff and return an early checkpoint rather than looping.

### Verify pass

> Review only the current diff and directly affected callers. Try to identify correctness, concurrency and stale-state, data-loss, authorization, persistence, and regression problems. Do not redesign the feature. Return verified findings only. Stop after the bounded review or check in early if the boundary is insufficient.

### Fix pass

> Fix only the verified findings listed below. Do not reopen discovery or change unrelated code. Run the named focused checks and stop. Preserve existing work and return control immediately if a permission, scope, or worktree problem occurs.

Append the objective, exact boundary, file ceiling, time limit, expected artifact, focused check, final-report format, and relevant stop conditions to every template invocation.

## Talk to the user in plain English

Everything the user reads from you — status updates, questions, summaries — must be in plain, everyday English, as if explaining to a smart friend who does not program. No Claudish, no dev shorthand: no "pass", "child", "diff", "worktree", "artifact", "delegation", "blocker" in user-facing text. The technical vocabulary in this file is for running the process and writing child prompts, not for talking to the user.

This is a tone default, not a censorship rule. Real names still appear when they matter — a file name, an error message, a command the user must run — but wrap them in a plain sentence saying what they mean. "The login page wasn't saving your email; I fixed the code that handles that form" beats "Patched the persistence bug in `auth/session.ts`."

Every user-facing update should cover, briefly:

1. **What we're doing** — the current goal in one plain sentence.
2. **What just got done** — what actually changed, described by effect, not by file list ("the settings screen now remembers your choice"). Mention which files changed in passing so the work is traceable.
3. **What was checked** — how we know it works, in plain terms.
4. **Open questions** — anything the user should weigh in on, asked plainly, with your recommended answer.

If there are no open questions, say so and name the next step.

## Return a short orchestrator status

Written in the plain-English style above:

- **What we're doing:**
- **What changed:**
- **How we checked it:**
- **Open questions / next step:**