fan-out

name	fan-out
description	Use whenever the user asks to apply the same operation to many independent files or components — bulk migration, batch refactor across controllers, parallel exploration of unrelated subsystems. Dispatches one subagent per file with a shared prompt template, then collects the results.
when_to_use	Reach for this when an operation is mechanical, idempotent, and the file list has no shared mutable state between items. Do NOT use for sequential pipelines (use `/dispatch` to pick `/worktree-team` instead) or when items depend on each other's output (the parallel runs will race).
disable-model-invocation	true
allowed-tools	["Task","Read","Bash"]
scheduling	a task touches 2+ independent files or subsystems with no shared state and dispatch has classified it as fan-out
structural	["Resolve the explicit file/subsystem list from the plan or prompt","Group into batches of 3-5 (Anthropic multi-agent research limit)","Spawn one subagent per batch with isolated context","Collect results and surface conflicts"]
logical	each batch returns a structured result; merged output identifies any cross-batch conflicts; total subagent count ≤ original list / 3

/fan-out — Parallel Batch Processing

When to Use

• Same operation on multiple independent files (e.g., add auth middleware to 8 controllers)
• Bulk migration (e.g., update import paths across 12 modules)
• Parallel exploration (e.g., search 5 different subsystems for a pattern)

Protocol

Step 1: Define the operation

Describe the operation as a template:

Operation: <what to do>
Files: <list of targets>
Constraints: <what NOT to change>

Step 2: Validate independence

Before fan-out, confirm:

• Each file can be modified independently
• No file depends on changes to another file in this batch
• The operation is the same for each file (parameterized, not custom)

If changes are interdependent → use pipeline instead.

Step 3: Dispatch subagents

Launch subagents with:

• Batch size: 3-5 files per agent (sweet spot for review quality)
• Context: Each agent gets the operation template + its file list
• Isolation: Use isolation: worktree for write operations to prevent conflicts
• Tools: Match to operation type:
  • Read-only exploration: Read, Glob, Grep, Bash
  • Write operations: Read, Write, Edit, Bash, Glob, Grep

Step 4: Synthesize results

After all agents complete:

1. Collect results from each agent
2. Check for conflicts or inconsistencies
3. Present unified summary to user

Execution Checklist

• Step 1 — describe the operation as Operation / Files / Constraints template
• Step 2 — confirm each file is independently modifiable; if not, switch to pipeline
• Step 3 — dispatch subagents in batches of 3–5 with matched tool set (Read-only vs. write); use isolation: worktree for writes
• Step 4 — collect results from each agent, surface conflicts/inconsistencies, present unified summary

Limits

• Max 5 parallel agents (more is hard to review)
• Max 8 files per agent (context quality degrades beyond this)
• Always verify one result manually before trusting the batch

When the independent target list runs to dozens or hundreds and the operation is purely mechanical, this manual 5-agent batching is the wrong tier: hand off to a native dynamic workflow (the ultracode keyword) instead, which orchestrates many more subagents under the runtime with verification built in. Keep /fan-out when per-batch conflict surfacing and isolation: worktree write-isolation matter more than raw scale. Native workflows require a Claude Code build that supports them.