BjornMelin/dev-skills / plugins/claude-core/skills/fan-out
fan-out
VerifiedDelegates work to bounded subagents and synthesizes their evidence. Use when asked to delegate, fan out, parallelize, or spawn subagents, or when a task splits into 2-5 independent subtasks such as multi-area code search or parallel review. You stay the planner and read every result.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.3 KB |
| references/agent-templates.md | markdown | 2.0 KB |
SKILL.md
View on GitHub---
name: fan-out
description: "Delegates work to bounded subagents and synthesizes their evidence. Use when asked to delegate, fan out, parallelize, or spawn subagents, or when a task splits into 2-5 independent subtasks such as multi-area code search or parallel review. You stay the planner and read every result."
license: MIT
---
# Fan-out
Bounded subagent delegation and evidence-first synthesis for Claude Code. You stay the planner and
the single decision-maker; subagents do scoped work and hand back evidence you merge.
## When to fan out (and when not to)
Spawn only if at least one is true:
- The user explicitly asked to delegate / parallelize / spawn subagents.
- The task splits into **2-5 genuinely independent** subtasks (no shared mutable state).
- Independent work would otherwise pollute the main context (large reads, broad searches).
Otherwise keep it local. Do **not** rationalize a spawn for work that is sequential, tiny, or shares
write surface — coordination overhead and edit collisions cost more than they save.
## Mechanism selection
| Situation | Use |
|---|---|
| One bounded subtask, keep main context clean | a single `Task` call |
| 2-5 independent subtasks, need all results together | **batch `Task` calls in one message** (they run concurrently) |
| Dependent / multi-stage / DAG-shaped batch | the dynamic **Workflow** tool (`pipeline`/`parallel`/`agent` stages) |
| Genuinely long-running, parent must stay responsive | **background Bash task** (`run_in_background`) + `TaskGet`/`TaskStop` |
Default to batched `Task` calls. Reach for Workflow only when stages depend on each other or you need
loop/fan-out control flow; reach for background tasks only for true async.
## Spawn contract (every subagent prompt)
```
TASK: <one concrete outcome>
SCOPE: <paths / area to look at; what is out of bounds>
MODE: read-only | edit ONLY <named files>
CONTEXT: <self-contained — subagents inherit NO parent transcript>
RETURN: <exact shape: status, evidence (file:line), commands run, findings + confidence, risks>
```
Subagents start fresh with no conversation history — never reference "the above" or prior turns.
## Roles & model policy
- Pick a custom `.claude/agents/<role>.md` when one matches; else `general-purpose`.
- **Opus** for hard reasoning, review, debugging, planning; inherit (or Sonnet) for read-heavy scans
and inventories. Pin `model:` in the agent file, or omit to inherit the session model.
- Default subagents to **read-only** (no `Edit`/`Write` in their tool scope) unless they own a
disjoint, named write surface.
## Rendezvous & async discipline
- Synchronous `Task` batches block until every subagent returns — **read all results** before the
next substantive step; never act on a partial mental model.
- Background tasks: account for every one via `TaskGet`; `TaskStop` anything stale or superseded.
## Limits & edit safety
- Prefer 2-5 agents; more dilutes synthesis. No nested subagents unless the user asks.
- Parallel edit-workers must own **disjoint files**. Tell each: "you are not alone in this repo — do
not revert or restage another worker's changes." The parent serializes commits.
## Escalation
If a subagent underfits, tighten its scope and return contract and re-run **only that one** on a
stronger (Opus) role. Never blanket-escalate the whole batch.
## Synthesis & conflict ledger
Merge and dedupe returns; lead with the highest-signal evidence. When subagents disagree, record it
and resolve in the parent:
```
CONFLICT: <claim>
- agent A: <evidence>
- agent B: <evidence>
RESOLUTION: <which wins + why, or the remaining uncertainty>
```
## Verification
Any proposed edit ships with tests/checks actually run, or a concrete command-level verification plan
the parent (or a final verify subagent) executes.
## Failure modes
| Symptom | Fix |
|---|---|
| Subagent overscoped / wandered | tighter SCOPE + RETURN contract |
| Weak / unusable output | specify exact return shape + evidence format |
| Parent acted on partial results | wait for all returns before deciding |
| Forgot a background task | reconcile every task via `TaskGet` |
| Edit collision | disjoint write surfaces; parent serializes commits |
| Role underfit | re-run only that agent on Opus |
| Too many agents | collapse to 2-5 with broader scopes |
See `references/agent-templates.md` for copyable role stubs and a Workflow skeleton.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |