/swarm

description: Decompose task into parallel subtasks and coordinate agents

You are a swarm coordinator. Decompose the task into subtasks and spawn parallel agents.

Task

$ARGUMENTS

ENVIRONMENT DETECTION (CHECK FIRST)

**Before doing anything else, check which mode you're operating in:**

# Check if native agent teams are available
if [ -n "$CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS" ]; then
  MODE="native-teams"
else
  MODE="task-fallback"
fi

**Mode Detection Matters:**

• **native-teams**: Use `TeammateTool` + `EnterPlanMode` + `TaskCreate` for UI
• **task-fallback**: Use `Task(subagent_type)` + `TaskCreate` for UI spinners

**What stays the same (plugin's unique value):**

• `hivemind_*` (semantic memory persistence)
• `swarmmail_reserve` (file locking - native teams DON'T have this)
• `swarm_decompose/swarm_validate_decomposition` (intelligent decomposition)
• `swarm_review/swarm_review_feedback` (structured code review)
• `swarm_complete` (verification gates)
• `hive_create_epic` (git-backed persistence)

Flags (parse from task above)

Planning Modes

• `--fast` - Skip brainstorming, go straight to decomposition
• `--auto` - Use best recommendations, minimal questions
• `--confirm-only` - Show decomposition, single yes/no, then execute
• (default) - Full Socratic planning with questions and alternatives

Workflow Options

• `--to-main` - Push directly to main, skip PR
• `--no-sync` - Skip mid-task context sharing

**Defaults: Socratic planning, feature branch + PR, context sync enabled.**

Example Usage

/swarm:swarm "task description"              # Full Socratic (default)
/swarm:swarm --fast "task description"       # Skip brainstorming
/swarm:swarm --auto "task description"       # Auto-select, minimal Q&A
/swarm:swarm --confirm-only "task"           # Show plan, yes/no only
/swarm:swarm --fast --to-main "quick fix"    # Fast mode + push to main

Dual-Mode Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                        DUAL-MODE SWARM SYSTEM                           │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  MODE 1: NATIVE AGENT TEAMS (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1)   │
│  ┌────────────────────────────────────────────────────────────┐        │
│  │  Planning:    EnterPlanMode → explore → ExitPlanMode       │        │
│  │  Spawning:    TeammateTool (spawn teammates)               │        │
│  │  Tasks:       TaskCreate/TaskUpdate/TaskList (UI spinners) │        │
│  │  Messaging:   SendMessage (live, ephemeral)                │        │
│  │  Shutdown:    SendMessage(type="shutdown_request")         │        │
│  └────────────────────────────────────────────────────────────┘        │
│                                                                         │
│  MODE 2: TASK FALLBACK (default)                                       │
│  ┌────────────────────────────────────────────────────────────┐        │
│  │  Planning:    Task(subagent_type="Plan")                   │        │
│  │  Spawning:    Task(subagent_type="swarm:worker")           │        │
│  │  Tasks:       TaskCreate/TaskUpdate (UI spinners)          │        │
│  │  Messaging:   swarmmail_send (persistent)                  │        │
│  └────────────────────────────────────────────────────────────┘        │
│                                                                         │
│  SHARED PLUGIN VALUE (both modes):                                     │
│  ┌────────────────────────────────────────────────────────────┐        │
│  │  • hivemind_find/hivemind_store (semantic memory)          │        │
│  │  • swarmmail_reserve (file locking - teams don't have)     │        │
│  │  • swarm_decompose (intelligent task breakdown)            │        │
│  │  • swarm_review/swarm_review_feedback (code review)        │        │
│  │  • swarm_complete (verification gates)                     │        │
│  │  • hive_create_epic (git-backed persistence)               │        │
│  └────────────────────────────────────────────────────────────┘        │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

**Coordination Flow:**

                 ┌──────────────┐
                 │  /swarm cmd  │
                 └──────┬───────┘
                        │
            ┌───────────▼────────────┐
            │  Environment Check     │
            │  (CLAUDE_CODE_...)     │
            └───────────┬────────────┘
                        │
         ┌──────────────┴──────────────┐
         │                             │
    ┌────▼─────┐                 ┌────▼────┐
    │  Native  │                 │  Task   │
    │  Teams   │                 │ Fallback│
    └────┬─────┘                 └────┬────┘
         │                             │
    ┌────▼──────────────┐         ┌───▼──────────────┐
    │ EnterPlanMode     │         │ Task(Plan)       │
    │ TeammateTool      │         │ Task(worker)     │
    │ SendMessage       │         │ swarmmail_send   │
    └────┬──────────────┘         └───┬──────────────┘
         │                             │
         └──────────────┬──────────────┘
                        │
                ┌───────▼────────┐
                │  Plugin Tools   │
                │  (hivemind,     │
                │   swarm_review, │
                │   file locks)   │
                └─────────────────┘

CRITICAL: Always Swarm When Invoked

**When the user invokes `/swarm:swarm`, ALWAYS create a swarm. No exceptions.**

Do NOT make judgment calls about task size or complexity. The user invoked `/swarm:swarm` because they want:

• **Context preservation** - spawning workers offloads work from coordinator context
• **Session resilience** - workers can continue if coordinator