--- name: "subagent_orchestration" description: "How an agent fans work out to subagents, tracks them, reconciles their results, and decides when to do work inline vs delegate. Use when planning multi-step work where delegation might help, e.g. 'I need 4 research threads done in parallel' or 'should I do this myself or hand it to a subagent'." metadata: { "includeInPrompt": true } --- # Subagent Orchestration ## Purpose Every multi-step job forces one choice: do it yourself or hand it to a subagent. Get it wrong and you burn your context budget on work a child could have done, or you scatter work across agents that come back with unverified claims you cannot stand behind. Delegation buys parallelism and failure isolation. One bad thread can die without killing the run. It costs you coordination overhead and a verification duty on everything that comes back. This skill gives you the decision rule, the briefing format, the tracking habit, and the merge step that makes delegation safe. ## Workflow ### 1. Decide: inline vs delegate Delegate when at least two of these hold: - **Independent threads.** The work splits into pieces that do not need each other's intermediate output. Four separate research topics, three independent file audits, two API checks against different endpoints. - **Long and boring.** Expected wall time is long relative to what it needs from you. A 20-minute scrape, a slow transcription, a wait on an external process. You sit idle while it runs. - **Failure isolation matters.** The thread might blow up, hit rate limits, or wander. A child failing is cheap. You failing mid-run costs the whole plan. - **Context budget.** The thread will generate a lot of intermediate noise you do not want in your own context: log streams, raw page dumps, iterative drafts. The child absorbs the noise and returns a summary. Do inline when: - The task is short, under a few minutes, and needs judgment at every step. - The result needs to land directly in your answer with no synthesis step, like reading one file to quote one line. - Splitting it would cost more words in briefing than the work itself. - You need to verify something a child claimed. Verification is your job. Do not delegate the check to another child. Heuristic: if the brief you would write is longer than the work, do it yourself. ### 2. Write self-contained briefs A child starts with none of your context. The brief is the whole job. Every brief carries: - **Goal.** One sentence, concrete and checkable. "Find the three most-starred open-source projects that do X, with links and star counts" beats "research X". - **Constraints.** Time budget, sources to use or avoid, style rules, hard don'ts. Include the style bans you live under (no em dashes, no filler phrasing). - **Output format.** Exact shape of the report: what sections, what fields, what counts as done. If you need evidence, say so explicitly: "cite the URL and timestamp for every factual claim". - **What NOT to do.** The boundaries the child must not cross: no publishing, no external sends, no touching production, no retrying a blocked call. Name the stop conditions. - **Success and failure signals.** What "done" looks like and what to do when blocked: report the blocker, do not invent a workaround. Bad brief: "Look into the new API." Good brief: "Goal: document the rate limits and auth flow of the X API from its public docs. Constraints: read docs only, no signups, no guessing. Output: a table of endpoint, limit, window, plus the auth section quoted. Evidence: cite the docs URL per row. Do not test the API live. If docs are unreachable, report that and stop." ### 3. Track in-flight subagents Spawn, then manage the clock. - **Poll on a schedule.** Check each running agent at intervals matched to its expected duration. A 5-minute task gets a check at 5 and 10 minutes. A 30-minute render gets checks every 10. - **Timeouts are decisions.** Set a deadline before you spawn. When it passes, do not stack retries on the same approach. Either kill it and redo with a narrower brief, or pull what it has and finish inline. - **A stale agent is a signal.** No output for double the expected duration usually means the task was underspecified, the target moved, or the agent is stuck in a retry loop. Read its last output, then kill or re-brief. Silence is data. - **One owner per thread.** Never spawn two agents on the same work "just in case". The duplicate burns budget and the conflict resolution costs more than the safety was worth. Pick one, track it, move on. - **Keep a roster.** While running, hold a short live list: agent, task, spawned at, deadline, status. When you report progress, this list is the facts. Do not summarize from memory. ### 4. Reconcile results A child's report is a lead, not a fact. Merge with a verification pass: - **Evidence first.** For every factual claim, the child should have cited its source: post id, API result, URL, timestamp. No citation, no claim. Claims without evidence get marked unverified, never quoted as fact. - **Verify external effects against the live source.** If the child says it posted, sent, deleted, or changed something, check the actual surface before you repeat it. "The task said so" is not confirmation. If you cannot verify, say so plainly. - **"Not found" needs a direct lookup.** A child reporting "it didn't happen" or "no results" based on a feed window or a search page is not proof of absence. Confirm with a direct id or query lookup before you state a negative. - **Watch for smooth sentences.** Children write confident prose over thin evidence. Read for what is asserted versus what is shown. Flat and true beats polished and guessed. - **Fold, don't paste.** Your final answer is yours. Synthesize the verified pieces into one coherent answer with evidence citations. Do not paste the child's report verbatim and call it done. One coordinator owns the final answer: that is you. ## Output Contract **Delegation plan output.** A short plan you can act on, shaped like this: ``` Threads: 1. Brief: . Constraints: . Output: . Deadline: . Stop if: . 2. Brief: ... Merge rule: Inline work: ``` **Reconciliation output.** For each thread, one of: - **Verified:** claim restated with its evidence citation (URL, id, timestamp, tool result). - **Unverified:** claim restated, flagged as unverified, with what is missing. - **Contradicted:** claim checked against the live source and found wrong, with the correction. Then the synthesized final answer: your words, only verified claims, evidence attached. Anything you could not verify is labeled as such or left out. ## Operating Rules 1. **Every subagent report is a lead, not a fact.** Nothing from a child enters your answer until you have checked its evidence. 2. **Verify external effects yourself.** Posted, sent, deleted, published, paid: confirm against the live source before reporting. Never delegate verification. 3. **Never run two agents on the same work.** One owner per thread. Duplicates waste budget and create merge conflicts. 4. **Kill stuck agents, do not stack retries.** A timeout means re-brief narrower or finish inline, not "try again". 5. **Briefs carry the whole job.** Goal, constraints, output format, evidence requirements, and explicit don'ts. A child with a thin brief will fill the gaps with guesses. 6. **Style rules flow downhill.** Your bans on em dashes and filler phrasing go in every brief, or the child will write in the default voice and you will rewrite it. 7. **One coordinator owns the final answer.** Children gather and draft. You verify, synthesize, and sign it. If it is wrong, that is on you. 8. **A child never expands its own task.** Briefs are scoped. If new work appears mid-thread, it comes back to you for a new decision, not a freelance pivot. 9. **Track the roster, report from the roster.** Status updates come from the live list of agents and deadlines, never from memory of what you think they are doing. 10. **Budget the coordination.** Spawning four threads to save ten minutes of inline work is a loss. Count the briefing, polling, and verification time before you delegate. ## Brief Template Copy, fill, send. Keep the whole thing under 150 words. ``` GOAL: CONSTRAINTS: