Fan-Out Orchestration

Overview

This skill is invoked by the

swarm

dispatcher. You should already have the goal, target, and selected roles from the dispatcher. If invoked directly, start from step 1.

Orchestrate parallel specialist agents for concurrent analysis of code, PRs, or topics. You become the team lead, spawn read-only specialists, collect their findings, and synthesize a unified report.

Core principle: Fan-out N specialists, collect findings, synthesize, present. No file edits, no implementation — analysis only.

When to Use

• User asks for review from multiple angles
• User wants parallel independent analysis
• User explicitly asks for "swarm" or "team review"
• Task benefits from diverse concurrent specialist perspectives

When NOT to Use

• Single-perspective tasks (use a regular agent instead)
• Sequential dependencies between workers
• Simple questions or explorations
• Tasks requiring file edits without

  isolation: worktree

  configured on the role
• A team already exists in the current session

Checklist

You MUST complete these steps in order:

1. Identify goal and target
2. Select roles
3. Check for existing team
4. Confirm with user
5. Create team and tasks
6. Spawn specialists
7. Collect findings
8. Synthesize and present report
9. Await user instructions
10. Shutdown and cleanup (when user says done)

Step 1: Identify Goal and Target

Determine from the user's request:

• Goal: What is being reviewed/analyzed? (e.g., "security review", "PR review", "codebase audit")
• Target: Which files, PR, or scope? (e.g., "src/auth/", "PR #42", "the entire API layer")

If unclear, ask the user. Do not guess scope.

Step 2: Select Roles

Roles come from

$CLAUDE_PLUGIN_ROOT/config/swarm-roles.yaml

.

Read the config file to get available roles and presets.

Selection priority:

1. User specifies a preset name → use that preset's roles
2. User specifies individual role names → use those
3. User describes what they want → match to appropriate roles
4. Default for "review" requests → use

   pr-review

   preset

If the user requests roles not in the config, tell them what's available and ask for clarification. Do not invent roles on the fly.

Validation

The dispatcher has already validated config shape (role existence, required fields,

subagent_type

values). The checks below cover fan-out-specific semantics.

• Non-empty roles: the

  roles

  list must contain at least 1 entry. If empty or missing, report the error and abort.
• No duplicates: warn the user if the same role appears more than once in the list.
• Single-role warning: if the

  roles

  list contains exactly 1 role, warn the user that fan-out orchestration adds overhead with no parallelism benefit. Offer to run a single agent directly instead.

Step 3: Check for Existing Team

Only one team can exist per session. Before creating a new team, check if one already exists.

If a team exists:

• Active swarm: warn the user that a swarm is already running and offer to shut it down first (

  TeamDelete

  ).
• Orphaned team (from a crashed session or

  /resume

  ): agents from the previous session are gone but the team and task list persist. Offer the user two options:
  1. Delete and restart:

     TeamDelete

     the orphaned team, then proceed with a fresh swarm.
  2. Salvage completed work: check

     TaskList

     for completed tasks, synthesize any available findings from completed tasks, then

     TeamDelete

     and optionally re-run incomplete tasks.

Step 4: Confirm with User

Present the dispatch plan using

AskUserQuestion

:

I'll dispatch a swarm with these specialists:
- security-reviewer: Review for vulnerabilities
- performance-reviewer: Analyze performance issues
- quality-reviewer: Code quality and maintainability

Target: [files/PR/scope]

Proceed?

Do NOT spawn anything until the user confirms. No surprise token costs.

Step 5: Create Team and Tasks

Team Naming

Use format:

swarm-fan-out-{goal-slug}-{timestamp}

Example:

swarm-fan-out-pr-review-1708200000

Generate the timestamp from the current date/time as a Unix epoch.

Create Team

TeamCreate with team_name: "swarm-fan-out-{goal-slug}-{timestamp}"

Create Tasks

One task per role via

TaskCreate

:

• subject

  : imperative title (e.g., "Review authentication module for security vulnerabilities")

• description

  : detailed scope, target files, reporting expectations

• activeForm

  : present-continuous spinner label (e.g., "Reviewing authentication security")

All tasks are independent — no

blocks

/

blockedBy

dependencies in v1.

Step 6: Spawn Specialists

For each role, spawn one teammate via

Agent

with:

• team_name

  : the team name from step 5

• name

  : the role name (e.g.,

  security-reviewer

  )

• subagent_type

  : from the role config (typically

  Explore

  )

• model

  : from the role config (if specified)

• isolation

  : from the role config (if specified)

• run_in_background

  :

  true

• prompt

  : composed from three parts (see below)

Isolation Handling

Before spawning, check each role's

isolation

field:

• If

  isolation: worktree

  is set:
  • Override

    subagent_type

    to

    general-purpose

    (even if the role says

    Explore

    or omits the field)
  • Print a note:

    Role {name}: using general-purpose (worktree isolation requires write access)

  • Pass

    isolation: "worktree"

    to the

    Agent

    tool call
• If

  isolation

  is absent: use the role's

  subagent_type

  as-is (default:

  Explore

  ), do not pass

  isolation

  to Agent

Prompt Construction

Each teammate's prompt is composed from:

Part 1: Identity and Instructions

Your name is {name}. You are part of team {team_name}.

Instructions:
- Claim your task from TaskList, mark it in_progress, then completed
  when done.
- Send your findings to the team lead via SendMessage when complete.
- Include a summary field in your message (5-10 words).

Part 2: Role Prompt

The

prompt

field from

swarm-roles.yaml

for this role.

Part 3: Goal and Target Context

## Goal

{goal description from user}

## Target

{target files, PR, scope, or other context}

{any additional context the user provided}

All task-specific context MUST be in the spawn prompt — teammates do not have access to the lead's conversation history.

Step 7: Collect Findings

Teammates send findings via

SendMessage

. Messages are delivered automatically — you do not need to poll.

Normal flow: Wait for all specialists to report. Teammates go idle after sending — this is expected behavior.

Error handling:

• Idle teammate without findings: send a message asking for status
• No response after nudge: note in report, mark task as blocked
• TeamCreate failure: report error to user, do not proceed

Step 8: Synthesize and Present Report

Once all specialists have reported (or you've noted non-reporters):

Synthesize findings into a unified report organized by severity or theme, not by specialist. Cross-reference overlapping findings.

Report Structure

## Swarm Analysis Report

**Goal:** {goal}
**Target:** {target}
**Specialists:** {list of roles that reported}

### Critical Issues
{findings rated critical/high, with file:line references}

### Important Issues
{findings rated medium/important}

### Suggestions
{lower-priority findings and recommendations}

### Summary
{brief overall assessment — 2-3 sentences}

If specialists disagree, note the disagreement rather than silently picking one perspective.

Step 9: Await User Instructions

After presenting the report:

• Do NOT fix issues specialists found
• Do NOT shut down the team automatically
• Do NOT proceed past reporting without user input

Wait for the user to decide next steps. They may:

• Ask for more detail on specific findings
• Ask you to fix issues (you would exit delegate mode for this)
• Say they're done (proceed to step 10)

Step 10: Shutdown and Cleanup

When the user indicates they're done:

1. Send

   shutdown_request

   to each teammate via

   SendMessage

   (include the monitor agent if

   watchdog: true

   was active)
2. Wait for

   shutdown_response

   from each. If an agent does not respond after a reasonable wait, send one nudge message. If still unresponsive, proceed — the agent may have crashed or terminated.
3. Call

   TeamDelete

   to clean up.

   TeamDelete

   is the authoritative cleanup mechanism — it will fail if active agents remain. If it fails, retry after unresponsive agents have timed out.

Design Constraints

• Read-only specialists: v1 uses

  subagent_type: Explore

  — no file edits, no Bash, no Write. This is enforced at the agent-type level.
• One team per session: check before creating.
• No nested teams: teammates cannot spawn their own teams.
• Lead synthesizes: present a unified report, not raw specialist output.
• User controls lifecycle: never auto-shutdown.