|
| 1 | +--- |
| 2 | +name: ny-orchestrate-subagents |
| 3 | +description: "Use when a request contains several independent pieces of work, when work can keep flowing while earlier work is still running, or when you want to stay responsive to new instructions instead of blocking on one long task. Trigger phrases include `do these in parallel`, `while that runs, also…`, `manage this as subagents`, `ทำหลายอย่างพร้อมกัน`, `ระหว่างรอ…ทำอย่างอื่นต่อ`." |
| 4 | +--- |
| 5 | + |
| 6 | +# ny-orchestrate-subagents |
| 7 | + |
| 8 | +## Overview |
| 9 | + |
| 10 | +You (Claude **Opus**) are the **orchestrator**: you never block. You evaluate |
| 11 | +each incoming piece of work, route it to the cheapest subagent that can do it |
| 12 | +well (**Haiku → Sonnet → Opus**), dispatch it to run in the background, and keep |
| 13 | +accepting new work while it runs. When a subagent reports back, you fold its |
| 14 | +result in and report to the user — without ever having stopped listening. |
| 15 | + |
| 16 | +**Core principle:** the orchestrator's job is *judgment and flow*, not doing the |
| 17 | +work itself. Decide tier, dispatch async, stay free, collect, report. |
| 18 | + |
| 19 | +## When to use |
| 20 | + |
| 21 | +- A request decomposes into ≥2 independent units (different files, lookups, checks). |
| 22 | +- Work arrives faster than any one task finishes, or the user says "while X runs, also do Y". |
| 23 | +- A task is long-running and the user wants to keep giving instructions meanwhile. |
| 24 | +- You want cost/latency efficiency: route mechanical work to Haiku, keep Opus for judgment. |
| 25 | + |
| 26 | +**When NOT to use:** |
| 27 | +- A single sequential task with no parallelism → just do it (or one foreground subagent). |
| 28 | +- Steps that depend on each other's output → pipeline them, don't fan out blindly. |
| 29 | +- Tasks that mutate the same files concurrently → serialize those (they conflict). |
| 30 | + |
| 31 | +## The capability ladder (who gets what) |
| 32 | + |
| 33 | +The orchestrator (you, Opus) evaluates every task and picks the **lowest tier |
| 34 | +that will succeed**, escalating only when judgment is required. |
| 35 | + |
| 36 | +| Tier | Route here when the task is… | Examples | |
| 37 | +|---|---|---| |
| 38 | +| **Haiku** | mechanical, fully specified, low-judgment, easily verifiable | renames, boilerplate, formatting, simple lookups/extraction, "list all X", mechanical edits | |
| 39 | +| **Sonnet** | standard implementation/integration, bounded scope, clear spec | implement one planned task, write tests for a function, summarize a file, a focused review | |
| 40 | +| **Opus** | ambiguous, architectural, cross-cutting, or final judgment | design decisions, resolving conflicting findings, synthesis across subagent outputs, evaluating subagent results, the orchestration itself | |
| 41 | + |
| 42 | +Default to Sonnet when unsure between Sonnet and Haiku; default to Opus only when |
| 43 | +real judgment or design is at stake. **You (Opus) always do the evaluating, |
| 44 | +routing, conflict-resolution, and final report** — never delegate that. |
| 45 | + |
| 46 | +```dot |
| 47 | +digraph tier { |
| 48 | + "New task" [shape=box]; |
| 49 | + "Needs design / judgment / synthesis?" [shape=diamond]; |
| 50 | + "Mechanical + fully specified + easy to verify?" [shape=diamond]; |
| 51 | + "Opus subagent (or keep it yourself)" [shape=box]; |
| 52 | + "Haiku subagent" [shape=box]; |
| 53 | + "Sonnet subagent" [shape=box]; |
| 54 | + "New task" -> "Needs design / judgment / synthesis?"; |
| 55 | + "Needs design / judgment / synthesis?" -> "Opus subagent (or keep it yourself)" [label="yes"]; |
| 56 | + "Needs design / judgment / synthesis?" -> "Mechanical + fully specified + easy to verify?" [label="no"]; |
| 57 | + "Mechanical + fully specified + easy to verify?" -> "Haiku subagent" [label="yes"]; |
| 58 | + "Mechanical + fully specified + easy to verify?" -> "Sonnet subagent" [label="no"]; |
| 59 | +} |
| 60 | +``` |
| 61 | + |
| 62 | +## The multitask mechanism (don't block) |
| 63 | + |
| 64 | +Use the **Agent tool** with two levers: |
| 65 | + |
| 66 | +- `model: "haiku" | "sonnet" | "opus"` — sets the subagent's tier per the ladder. |
| 67 | +- `run_in_background: true` — the subagent runs detached; **you get control back |
| 68 | + immediately** and are notified when it finishes. This is what lets you accept |
| 69 | + more work while it runs. |
| 70 | + |
| 71 | +Rules of flow: |
| 72 | + |
| 73 | +1. **Dispatch async, return to the user.** For anything non-trivial, launch with |
| 74 | + `run_in_background: true` and immediately tell the user it's running. Do not |
| 75 | + sit blocked on the result. |
| 76 | +2. **Fan out concurrently.** Independent tasks → launch them in a **single |
| 77 | + message with multiple Agent calls** so they run at once. |
| 78 | +3. **Keep the floor open.** While background agents run, accept and route new |
| 79 | + instructions. Maintain a short mental (or TodoWrite) ledger of what's in |
| 80 | + flight and who owns it. |
| 81 | +4. **Collect on notify.** When a background agent completes, the harness re-invokes |
| 82 | + you with its result. Integrate it, then report to the user. Resolve any |
| 83 | + cross-agent conflicts yourself (Opus judgment). |
| 84 | +5. **Serialize conflicts only.** Before every fan-out, run the conflict-detection |
| 85 | + heuristic below. Conflicting tasks serialize (or isolate); everything else |
| 86 | + stays parallel. |
| 87 | + |
| 88 | +> Foreground (blocking) dispatch is for the rare case where you genuinely cannot |
| 89 | +> proceed without the result AND have nothing else to do. The default is background. |
| 90 | +
|
| 91 | +## Conflict detection (run before every fan-out) |
| 92 | + |
| 93 | +Decide parallel-vs-serialize mechanically, not by gut. For each pending task, |
| 94 | +derive two sets, then check overlap: |
| 95 | + |
| 96 | +- **write-set** — resources the task may MUTATE (files it edits/creates/deletes, |
| 97 | + output dirs it builds, shared singletons it changes). |
| 98 | +- **read-set** — resources it only READS. |
| 99 | + |
| 100 | +**The rule:** |
| 101 | +- `write(A) ∩ write(B) ≠ ∅` → **conflict** (write–write). |
| 102 | +- `write(A) ∩ read(B) ≠ ∅` (either direction) → **conflict** (read–write race). |
| 103 | +- read-only ∩ read-only → **always safe**, parallelize freely. |
| 104 | +- **Unknown or open-ended write-set → assume conflict** (default to caution). |
| 105 | + |
| 106 | +Treat a directory in a set as covering everything under it: `write(src/)` |
| 107 | +conflicts with `read|write(src/foo.ts)`. A glob conflicts with anything it matches. |
| 108 | + |
| 109 | +**Fast conflict signals** (any one ⇒ treat as conflicting until proven otherwise): |
| 110 | + |
| 111 | +| Signal | Why it conflicts | |
| 112 | +|---|---| |
| 113 | +| Same file path in two briefs | direct write–write / read–write | |
| 114 | +| One task's dir contains another's file | dir-level mutation overlaps the file | |
| 115 | +| Both build/install to the same output | `dist/`, `target/`, `node_modules/`, `.next/` clobber each other | |
| 116 | +| Shared singletons | lockfile, DB/migrations/schema, global config, a fixed port, the same git branch/index | |
| 117 | +| Both run codegen/format/rename over overlapping paths | each rewrites the other's inputs | |
| 118 | +| A task scoped "across the repo / everywhere / refactor X" | write-set is unbounded → conflicts with all | |
| 119 | +| One task's OUTPUT is another's INPUT | not a race — it's a **dependency**: chain, don't fan out | |
| 120 | + |
| 121 | +**Resolve a detected conflict** (pick the cheapest that works): |
| 122 | +1. **Serialize** — chain the conflicting tasks; keep all non-conflicting ones parallel. |
| 123 | +2. **Isolate** — give each its own sandbox so write-sets stop overlapping: separate |
| 124 | + git worktree, separate `--out-dir`, separate port, separate temp dir. |
| 125 | +3. **Narrow** — tighten the briefs so their write-sets no longer intersect |
| 126 | + (e.g. assign disjoint file lists), then parallelize. |
| 127 | + |
| 128 | +Only the conflicting pairs serialize; the rest of the batch still fans out. Build |
| 129 | +the write/read-sets from the briefs you're about to send — if you can't state a |
| 130 | +task's write-set, that itself is the "unknown ⇒ serialize/isolate" trigger. |
| 131 | + |
| 132 | +```dot |
| 133 | +digraph conflict { |
| 134 | + "Pair of tasks" [shape=box]; |
| 135 | + "Write-sets known?" [shape=diamond]; |
| 136 | + "write∩write or write∩read?" [shape=diamond]; |
| 137 | + "Output of one = input of other?" [shape=diamond]; |
| 138 | + "Parallel (background)" [shape=box]; |
| 139 | + "Serialize / isolate / narrow" [shape=box]; |
| 140 | + "Chain (dependency)" [shape=box]; |
| 141 | + "Pair of tasks" -> "Write-sets known?"; |
| 142 | + "Write-sets known?" -> "Serialize / isolate / narrow" [label="no (assume conflict)"]; |
| 143 | + "Write-sets known?" -> "Output of one = input of other?" [label="yes"]; |
| 144 | + "Output of one = input of other?" -> "Chain (dependency)" [label="yes"]; |
| 145 | + "Output of one = input of other?" -> "write∩write or write∩read?" [label="no"]; |
| 146 | + "write∩write or write∩read?" -> "Serialize / isolate / narrow" [label="yes"]; |
| 147 | + "write∩write or write∩read?" -> "Parallel (background)" [label="no"]; |
| 148 | +} |
| 149 | +``` |
| 150 | + |
| 151 | +## Briefing a subagent |
| 152 | + |
| 153 | +The subagent has **no memory of this conversation**. Each dispatch must be |
| 154 | +self-contained: |
| 155 | + |
| 156 | +- **Task** — exactly what to do, pasted in full (don't point at "the plan"). |
| 157 | +- **Context** — the minimum scene-setting + paths/values it needs. |
| 158 | +- **Done criteria** — what "complete" looks like; what to return (and in what shape). |
| 159 | +- **Escalate list** — when to stop and report back instead of guessing. |
| 160 | + |
| 161 | +Ask for a structured final line so collection is trivial, e.g. `DONE | BLOCKED:<why> |
| 162 | +| NEEDS_CONTEXT:<question>`. The subagent's final message is the only thing you |
| 163 | +get back — tell it the final message IS the deliverable. |
| 164 | + |
| 165 | +## Quick reference |
| 166 | + |
| 167 | +| Situation | Action | |
| 168 | +|---|---| |
| 169 | +| 3 unrelated checks | one message, 3 background Agent calls (tier each) | |
| 170 | +| "while that builds, also draft X" | leave the build agent running; route X to its own agent | |
| 171 | +| long mechanical sweep | Haiku, background; you keep taking work | |
| 172 | +| subagent returns BLOCKED twice | re-dispatch FRESH with a new approach, or take it yourself (Opus) | |
| 173 | +| two agents disagree | you (Opus) adjudicate; don't average | |
| 174 | +| same file, two edits | serialize them | |
| 175 | + |
| 176 | +## Common mistakes |
| 177 | + |
| 178 | +- **Blocking on a foreground subagent** when you could have backgrounded it and stayed responsive. Default to `run_in_background: true`. |
| 179 | +- **Over-routing to Opus.** Most implementation is Sonnet; most mechanical work is Haiku. Reserve Opus for judgment. |
| 180 | +- **Thin briefs.** The subagent can't see this chat — a vague brief returns vague work. Include task + context + done-criteria + escalate. |
| 181 | +- **Fanning out dependent tasks.** If B needs A's output, don't launch them together — chain them. |
| 182 | +- **Fanning out without checking write-sets.** Run the conflict-detection heuristic first; concurrent writers to the same file/dir/singleton conflict — serialize or isolate them. |
| 183 | +- **Delegating the judgment.** Routing, conflict-resolution, synthesis, and the final report stay with you (Opus). |
| 184 | +- **Re-running a failed approach.** A second BLOCKED on the same cause means the approach is wrong — change it, don't retry verbatim. |
| 185 | + |
| 186 | +## Real-world shape |
| 187 | + |
| 188 | +Partner: "Audit these 3 modules for security, and while that runs, rename `foo`→`bar` everywhere, and figure out the caching design." |
| 189 | +You: route security audit → 3 Sonnet agents (one per module, background); rename → 1 Haiku agent (background); caching design → keep yourself / Opus agent. Report "4 agents dispatched" immediately. As each returns, integrate and report; you (Opus) synthesize the security findings and decide the caching design. |
0 commit comments