Swarm Dispatcher

Overview

Route swarm requests to the appropriate pattern skill. Read the preset config, determine the pattern, and follow the corresponding skill.

Goal Slug Generation

When pattern skills create team names, they use the format

swarm-{pattern}-{goal-slug}-{timestamp}

. Generate the goal slug from the user's goal description

• Lowercase only
• Replace spaces and special characters with hyphens
• Remove all characters except

  a-z

  ,

  0-9

  , and

  -

• Collapse consecutive hyphens into one
• Truncate to 30 characters maximum
• Strip leading and trailing hyphens
• Abort if empty: if the slug is empty after all transformations (e.g., goal was all special characters), abort with: "Could not generate a valid team name from the provided goal."

Examples

• "PR review" →

  pr-review

• "Security audit of auth module" →

  security-audit-of-auth-module

• "Fix the OAuth2/OIDC integration!!!" →

  fix-the-oauth2-oidc-integrat

Pass the goal slug through to the pattern skill along with the goal, target, and preset.

Stale Worktree Cleanup

Before starting any swarm, check for leftover worktrees from previous sessions

git worktree list

If worktrees exist that are not associated with the current session (stale branches from crashed or abandoned swarms), offer the user two options

1. Remove stale worktrees:

   git worktree remove <path>

   for each stale entry. This reclaims disk space but the branches persist and can still be merged
2. Keep them: the user may want to inspect or recover work

Only worktrees whose branch names match the

swarm-*

naming convention should be flagged. Non-swarm worktrees are outside this plugin's scope.

Steps

1. Identify goal and target from the user's request. If unclear, ask

2. Read roles config from

   $CLAUDE_PLUGIN_ROOT/config/swarm-roles.yaml

3. Select preset or roles using the same priority as v1. When resolving roles, check for inline definitions in the preset first (entries with a

   name

   and

   prompt

   field), then fall back to global role names in the

   roles:

   section
   • User specifies a preset name -> use it
   • User specifies individual role names -> use those (fan-out)
   • User describes what they want -> match to preset/roles
   • Default for "review" ->

     pr-review

     preset

4. Validate config — check the resolved preset and roles for structural problems before routing to a pattern skill. Abort or warn as indicated

   Required role fields

   Every role referenced by the preset (whether global or inline) must have

   • prompt

     — non-empty. An inline role missing

     prompt

     means the agent would be spawned with no instructions. Abort

   • subagent_type

     — must be one of

     Explore

     or

     general-purpose

     . Missing or unrecognized values (typos like

     Explorer

     ) cause opaque spawn failures. Abort

   Isolation consistency

   If a role specifies

   isolation: worktree

   but its

   subagent_type

   is not

   general-purpose

   , warn that

   subagent_type

   will be overridden to

   general-purpose

   at spawn time (worktree isolation requires write access). This is not an error — pattern skills handle the override — but the role definition is internally inconsistent and should be fixed.

   Numeric fields

   worker_count

   (swarm) and

   approach_count

   (speculative) must be positive integers when present. Non-numeric values, zero, or negative values are invalid. Abort

   Topology-pattern agreement

   The preset's declared

   pattern

   must match the topology keys present in the preset config:

   Pattern	Expected keys	Unexpected keys
   fan-out	roles	stages , nodes
   pipeline	stages or nodes	bare roles
   task-graph	nodes	stages without depends_on
   map-reduce	map_role , reduce_role	roles , stages
   speculative	approach_role , judge_role	roles , stages
   swarm	worker_role	roles , stages

   If unexpected keys are present, warn that the declared pattern may not match the intended topology. Ask the user to confirm.

   Watchdog prerequisite

   If the preset has

   watchdog: true

   , verify that the

   monitor

   role exists in the global

   roles:

   section. If missing, abort — the watchdog cannot be spawned without a role definition.

   Deprecated preset completeness

   If the preset has

   deprecated: true

   but no

   successor

   field, warn that no replacement can be suggested. The user can still proceed.

   Reserved names

   If any role name in the preset matches

   monitor

   or

   judge

   , warn that these names have special behavior in hooks (exemption from quality gates, speculative gate branching). Using them as regular specialist names will cause incorrect gate logic.

5. Determine pattern from the selected preset's

   pattern

   field. If absent, default to

   fan-out

   . If the preset has

   deprecated: true

   , warn the user and suggest the

   successor

   preset instead. Proceed only if the user confirms

6. Route to pattern skill — read and follow the corresponding skill

   Pattern	Skill
   fan-out (or absent)	swarm-fan-out
   swarm	swarm-swarm
   pipeline	swarm-pipeline
   task-graph	swarm-pipeline
   map-reduce	swarm-map-reduce
   speculative	swarm-speculative

   Read the skill file and follow its checklist from step 1. Pass through: goal, target, selected roles/preset, and any user context.

7. Watchdog modifier — if the preset has

   watchdog: true

   , the lead must spawn a monitor agent immediately after creating the team (the pattern skill's "Create Team" step). Spawn it BEFORE spawning any specialist/worker agents.

   Use the

   monitor

   role from

   $CLAUDE_PLUGIN_ROOT/config/swarm-roles.yaml

   .

   Read

   monitor_cron_interval_seconds

   from

   $CLAUDE_PLUGIN_ROOT/.claude-plugin/settings.json

   (default: 60). Include the resolved interval in the monitor's spawn prompt.

   • name

     :

     monitor

   • subagent_type

     : from the monitor role config (typically

     Explore

     )

   • run_in_background

     :

     true

   • prompt

     :
     • Identity: "Your name is monitor. You are part of team {team_name}."
     • Immediately send a "Monitoring started" message to the team lead via SendMessage (this satisfies the idle hook gate)
     • Call CronCreate with:

       • intervalSeconds

         : {monitor_cron_interval_seconds} (read from

         $CLAUDE_PLUGIN_ROOT/.claude-plugin/settings.json

         , default 60)

       • prompt

         : "Check TaskList for anomalies: tasks stuck in_progress, idle workers without findings, failed or blocked tasks. Send a SendMessage alert to the team lead for each anomaly found. Do not intervene directly — report only."
     • Do not intervene directly — report to the lead

   The monitor does not get its own task — it observes and reports. Include the monitor in shutdown (send

   shutdown_request

   to it).

   Pattern skills do NOT spawn the monitor. This section is the single source of truth for monitor spawning.