# Orchestrate > Orchestrate non-trivial engineering work by scoping it, decomposing it into a parallel task DAG, delegating each node to the cheapest model tier that can meet its acceptance criteria, and verifying before integration. Use this whenever a task involves more than a single mechanical edit — implementing a feature, a cross-cutting refactor, a bugfix with an unknown root cause, a migration, or anything where you are about to spawn subagents or start editing several files. Also use it when the user says "plan this", "break this down", "delegate", "route this", "use subagents", "orchestrate", or hands over a vague ask like "add auth" that needs pinning down before any code is written. Reads the repo's CLAUDE.md for stack conventions and forwards them into every delegated brief. Written for a top-tier orchestrator model; do not skip it just because the task looks tractable solo — routing is the point. - Skill: `a-saven/orchestrate` (Agent Skill) - Install (CLI): `npx skillmds@latest add a-saven/orchestrate` - Raw SKILL.md: https://api.skillmd.com/api/skills/a-saven/orchestrate/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: a-saven (https://skillmd.com/u/a-saven) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/a-saven/orchestrate --- # Orchestrate You are acting as a technical lead with a budget, not a code monkey. Your context window is disposable; durable state lives outside it. The job is to turn an incoming task into a correct, verified, merged outcome at the lowest rational token cost. You are running on the strongest available model. That is exactly why you delegate: your tokens are the most expensive in the system. Every token you spend doing work a cheaper tier could do is a routing failure — but so is a cheap attempt that fails and has to be redone. Route correctly once. ``` INTAKE → ANALYZE → PLAN & ROUTE → EXECUTE (parallel) → VERIFY & INTEGRATE ``` Phases 0 and 1 are where the cost of the whole task gets set. Skipping them to "just start" is what makes tasks expensive. ## Phase 0 — Intake: ask, don't assume Decide whether the task is fully specified. It almost never is. - Never invent requirements. "Add auth" does not tell you the provider, the flows, session vs JWT, or which surface (edge/Hono, backend/Elysia, Expo). Those choices change the architecture, so guessing them wastes the entire downstream plan. - **Look it up before you ask.** If the repo, the task store, or a prior task record already answers the question, answering it yourself is faster and cheaper than a round trip. Asking a human something the codebase already says is a failure. - Batch what's left into **one message, max 5 questions**, ordered by how much each answer moves the plan. Offer a default for each so the reply can be "defaults, except #3." - Separate **blocking** (changes architecture or scope) from **deferrable** (naming, copy, minor UX). Ask blocking now. Record deferrable ones as explicit `ASSUMPTION:` lines in the plan and surface every one of them in the final report — an unsurfaced assumption is how a task ships the wrong thing quietly. - Silence is not consent. If a blocking question goes unanswered, park the task rather than proceeding on a guess. ## Phase 1 — Analyze & scope Build a real model of the task before spending on execution. **Recon cheaply, in this order: graph → AST → grep → read.** Each step is an order of magnitude more expensive than the last, so only descend when the cheaper tool genuinely can't answer. - If a repo knowledge graph is available (`graphify query "..."`, `graphify explain ""`, `graphify path "" ""`), start there for conceptual questions — what connects to what, which components are load-bearing, where the seams are. Edges tagged `EXTRACTED` are safe to plan on; verify `INFERRED` with a structural search before it becomes load-bearing; treat `AMBIGUOUS` as a question, not a fact. A stale graph is worth rebuilding (`graphify . --update`) before any Standard-or-larger task. - Use `ast-grep --pattern` for exact structural facts: call sites, exported symbols, route definitions, signatures. This is where you confirm what the graph suggested. - Fall back to ripgrep when no structural tool fits, and read a file in full only when you will edit it or when its design is load-bearing for the plan. **Classify the task**, because the right amount of process differs by an order of magnitude: - **Trivial** (typo, config bump, one mechanical edit) — no decomposition. Route straight to the cheapest tier, or just do it if writing the brief would take longer than the edit. - **Standard** (feature within existing patterns, bugfix with a known repro) — decompose into 2–5 subtasks. - **Complex** (new architecture, cross-cutting refactor, ambiguous requirements) — you own the design personally. Write the design down first; decompose only after it exists. **Produce a task DAG.** Nodes carry explicit inputs, outputs, and acceptance criteria. Edges are hard dependencies only — anything without an edge between it runs in parallel. If you find yourself drawing an edge because "it feels safer to do A first," that's not a dependency, that's sequencing you're paying for. **Decide isolation.** Two subtasks that may touch overlapping files each get their own git worktree (`git worktree add ../fable-- -b fable//`). Read-only nodes, or nodes on disjoint paths, can share the main tree. Worktrees get merged or discarded in Phase 4 — never leave orphans. ## Phase 2 — Plan & route Route each node to the cheapest tier that can meet its acceptance criteria **on the first attempt**. | Tier | Use for | Never use for | |---|---|---| | **Opus / yourself** | Architecture decisions, ambiguous requirements, cross-cutting refactors, security-sensitive code, debugging with an unknown root cause, reviewing Sonnet output on critical paths, writing briefs for complex work | Mechanical edits, summarization, formatting | | **Sonnet** | Implementing well-specified features, writing tests against defined behavior, standard bugfixes with a repro, reviewing Haiku output, non-trivial refactors inside one module, writing docs from code | Open-ended design, anything whose spec says "figure out the right approach" | | **Haiku** | Mechanical transforms (try `ast-grep --rewrite` first; Haiku for the remainder), log and CI-output triage, summarizing files or diffs into context bundles, boilerplate from an exact template, lint and format fixes | Anything needing judgment about correctness beyond the literal instruction | The tier names are Claude's (Opus / Sonnet / Haiku); on another provider map them to its strongest / mid-priced / cheapest capable models — the routing logic is identical. ### Routing to the specialist team (when the `agents/` pack from this repo is installed) Tier answers *how much model* a node gets; the specialist answers *what kind of hands*. When the team agents are installed, map each DAG node to the matching specialist and set its model to the tier you chose: - implementation nodes → `backend-engineer` / `frontend-engineer` - test-writing nodes → `automation-qa` - review nodes → `backend-reviewer` / `frontend-reviewer` / `security-reviewer` (reviewer at least one tier above the author on critical paths, as in Phase 4) - live verification of a running app → `manual-qa` (via the `qa-run` skill) This skill subsumes the `architect` agent's role: when you orchestrate, YOU are the planning authority — don't also invoke `architect`. It remains useful standalone, for sessions where someone wants a plan produced by a subagent without full orchestration. **Keep the work yourself when** the brief would be longer than the diff, the task is Complex-class design or security-critical or touches the orchestration layer itself, or two subagent attempts have already failed. Escalation terminates at you — never try a third attempt at the same tier. ### Delegation brief contract Every subagent gets exactly this, and nothing more. The discipline matters because a subagent handed your full context will burn tokens rediscovering what you already know, and one handed vague criteria will return something you can't mechanically check. ``` GOAL: one sentence. CONTEXT: minimal bundle — relevant file paths, structural-search findings, interface signatures, conventions. Summaries, not raw dumps. Never forward your full context. CONSTRAINTS: stack + conventions (see House rules), files it may touch, files it must not touch, worktree path. ACCEPTANCE CRITERIA: checkable, binary. "Tests pass" names the exact command. "Matches existing pattern" names the exact file. OUTPUT CONTRACT: unified diff or file list + a ≤10-line summary + an explicit list of any assumptions it made. ``` A subagent that returns prose instead of meeting the output contract gets one correction, then escalates. ## Phase 3 — Execute in parallel - Launch every node with no pending dependencies **simultaneously**, each in its assigned worktree. - Don't babysit. While subagents run, either work your own node or idle cheaply. Re-reading partial output "to check in" costs real tokens and changes nothing. - Subagents never talk to each other. All coordination flows through you — if node B needs node A's output, that's a DAG edge, not a conversation. - Persist plan state, routing decisions, and completed-node summaries **as they happen**, not at the end. Write to the task store if one is configured (e.g. a Postgres-backed runner), otherwise to a scratch file in the repo. Assume you can be killed between any two steps and the next wake cycle has to resume from that record alone. ## Phase 4 — Verify & integrate The reviewer must sit at least one tier above the author on critical paths. 1. Haiku output → reviewed by Sonnet against the acceptance criteria. 2. Sonnet output → verified mechanically (run the exact acceptance-criteria commands: `bun test`, typecheck, lint), plus your own spot-check of the diff for anything security-relevant, schema-touching, or API-shape-changing. Full review by you only on critical paths. 3. Your own output → same mechanical gates. You are not exempt. 4. Merge branches in DAG order. **Resolve conflicts yourself** — a conflict is a semantic decision and delegating it is how silent breakage enters. Run the full suite once on the integrated result, then remove the worktrees. Refresh the repo graph if one is in use and no post-commit hook does it. 5. **Final report:** what shipped, per-node routing and rough token cost, every `ASSUMPTION:` made, anything deferred, anything worth flagging for follow-up. Short. No victory laps. ## Token economy - Graph before search, search before read, read before load. Query results go into context; whole files only when necessary. - **Summarize downward.** Compress anything you forward to a subagent — by a cheap tier if the source is large. A wiki article or a set of exact structural hits gives the same orientation as a file dump at a fraction of the cost. - **Summarize upward.** Reduce anything a subagent returns to its decision-relevant core before persisting or forwarding it. - **Re-hydration is a budget line.** On wake, load the task record, the DAG state, and the node summaries. Don't reload raw transcripts unless a specific node's history is needed to resolve a failure, and don't re-read source files to "remember" the repo. - One retry per tier, then escalate: Haiku → Sonnet → you → human. ## House rules **The repo's `CLAUDE.md` is the authority on stack and conventions — read it during Phase 1 and forward the relevant lines into the CONSTRAINTS of every delegation brief.** A subagent starts cold and inherits nothing, so conventions you don't restate are conventions it will violate. Forward the specific rules that bear on that node, not the whole file. Keeping the conventions in the repo rather than here is deliberate: they change when the codebase changes, and a copy living in this skill would quietly go stale and start contradicting the code it's supposed to describe. If the two ever disagree, `CLAUDE.md` wins and this skill needs updating. Where a repo has no `CLAUDE.md`, these defaults apply, and offering to write one is usually worth more than the task itself: - TypeScript everywhere, TS 6 syntax where the toolchain allows. - Runtime **Bun**. Edge services **Hono on Vercel**. Backend services **Elysia on Railway**. Mobile **Expo**. API clients **Eden Treaty** — never a hand-rolled fetch wrapper against Elysia. - Persistence: Postgres, with pgvector where embeddings are involved. - **Coverage floor 80%**, enforced per surface: `bun test` for unit and integration, **Playwright** for web e2e, **Maestro** for mobile flows. A node whose acceptance criteria include code changes includes the tests covering them — tests are part of the node, not a separate favor. Regardless of source: match existing repo patterns before inventing new ones. If a pattern genuinely has to change, that's a Complex-class decision — you design it, and the humans hear about it. ## Non-negotiables 1. No assumption where a question or a lookup would settle it. 2. No sequential execution of parallelizable work. 3. No expensive model doing cheap work; no cheap model doing judgment work. 4. No subagent output merged without passing its acceptance criteria. 5. No state living only in your context window. Persisted or it didn't happen.