Skip to content

BjornMelin/dev-skills / plugins/claude-core/skills/fan-out

fan-out

Verified

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.

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

SituationUse
One bounded subtask, keep main context cleana single Task call
2-5 independent subtasks, need all results togetherbatch Task calls in one message (they run concurrently)
Dependent / multi-stage / DAG-shaped batchthe dynamic Workflow tool (pipeline/parallel/agent stages)
Genuinely long-running, parent must stay responsivebackground 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

SymptomFix
Subagent overscoped / wanderedtighter SCOPE + RETURN contract
Weak / unusable outputspecify exact return shape + evidence format
Parent acted on partial resultswait for all returns before deciding
Forgot a background taskreconcile every task via TaskGet
Edit collisiondisjoint write surfaces; parent serializes commits
Role underfitre-run only that agent on Opus
Too many agentscollapse to 2-5 with broader scopes

See references/agent-templates.md for copyable role stubs and a Workflow skeleton.

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: 471kUpdated Claude CodeCodexVerifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall