when-orchestrating-swarm-use-swarm-orchestration

Swarm Orchestration SOP

Overview

This skill implements complex multi-agent swarm orchestration with intelligent task decomposition, distributed execution, progress monitoring, and result synthesis. It enables coordinated execution of complex workflows across multiple specialized agents.

Agents & Responsibilities

task-orchestrator

Role: Central orchestration and task decomposition Responsibilities:

• Decompose complex tasks into subtasks
• Assign tasks to appropriate agents
• Monitor execution progress
• Synthesize results from multiple agents

hierarchical-coordinator

Role: Hierarchical task delegation and coordination Responsibilities:

• Manage task hierarchy
• Coordinate parent-child task relationships
• Handle task dependencies
• Ensure proper execution order

adaptive-coordinator

Role: Dynamic workload balancing and optimization Responsibilities:

• Monitor agent workloads
• Rebalance task assignments
• Optimize resource allocation
• Adapt to changing conditions

Phase 1: Plan Orchestration

Objective

Analyze complex task requirements and create detailed decomposition plan with dependency mapping.

Evidence-Based Validation

• [ ] Task decomposition tree created
• [ ] Dependencies mapped
• [ ] Agent assignments planned
• [ ] Execution strategy defined

Scripts

# Analyze task complexity
npx claude-flow@alpha task analyze --task "Build full-stack application" --output task-analysis.json

# Generate decomposition tree
npx claude-flow@alpha task decompose \
  --task "Build full-stack application" \
  --max-depth 3 \
  --output decomposition.json

# Visualize decomposition
npx claude-flow@alpha task visualize --input decomposition.json --output task-tree.png

# Store decomposition in memory
npx claude-flow@alpha memory store \
  --key "orchestration/decomposition" \
  --file decomposition.json

# Identify dependencies
npx claude-flow@alpha task dependencies \
  --input decomposition.json \
  --output dependencies.json

# Plan agent assignments
npx claude-flow@alpha task plan \
  --decomposition decomposition.json \
  --available-agents 12 \
  --output execution-plan.json

Task Decomposition Strategy

Level 1: High-Level Goals

{
  "task": "Build full-stack application",
  "subtasks": [
    "Design architecture",
    "Implement backend",
    "Implement frontend",
    "Setup infrastructure",
    "Testing and QA"
  ]
}

Level 2: Component Tasks

{
  "task": "Implement backend",
  "subtasks": [
    "Design API endpoints",
    "Implement authentication",
    "Setup database",
    "Create business logic",
    "API documentation"
  ]
}

Level 3: Atomic Tasks

{
  "task": "Implement authentication",
  "subtasks": [
    "Setup JWT library",
    "Create user model",
    "Implement login endpoint",
    "Implement registration endpoint",
    "Add password hashing",
    "Create auth middleware"
  ]
}

Memory Patterns

# Store orchestration plan
npx claude-flow@alpha memory store \
  --key "orchestration/plan" \
  --value '{
    "totalTasks": 45,
    "levels": 3,
    "estimatedDuration": "2h 30m",
    "requiredAgents": 12
  }'

# Store dependency graph
npx claude-flow@alpha memory store \
  --key "orchestration/dependencies" \
  --value '{
    "task-003": ["task-001", "task-002"],
    "task-008": ["task-003", "task-004"],
    "task-012": ["task-008", "task-009"]
  }'

Validation Criteria

1. Task tree depth ≤ 3 levels
2. All tasks have clear success criteria
3. Dependencies correctly identified
4. No circular dependencies
5. Agent capacity sufficient for load

Phase 2: Initialize Swarm

Objective

Setup swarm infrastructure with appropriate topology and coordinator agents.

Evidence-Based Validation

• [ ] Swarm initialized successfully
• [ ] Topology optimized for workload
• [ ] Coordinator agents active
• [ ] Memory coordination established

Scripts

# Determine optimal topology
TASK_COUNT=$(jq '.totalTasks' decomposition.json)

if [ "$TASK_COUNT" -gt 30 ]; then
  TOPOLOGY="mesh"
elif [ "$TASK_COUNT" -gt 15 ]; then
  TOPOLOGY="hierarchical"
else
  TOPOLOGY="star"
fi

# Initialize swarm with optimal topology
npx claude-flow@alpha swarm init \
  --topology $TOPOLOGY \
  --max-agents 15 \
  --strategy adaptive

# Spawn task orchestrator
npx claude-flow@alpha agent spawn \
  --type coordinator \
  --role "task-orchestrator" \
  --capabilities "task-decomposition,assignment,synthesis"

# Spawn hierarchical coordinator
npx claude-flow@alpha agent spawn \
  --type coordinator \
  --role "hierarchical-coordinator" \
  --capabilities "hierarchy-management,delegation"

# Spawn adaptive coordinator
npx claude-flow@alpha agent spawn \
  --type coordinator \
  --role "adaptive-coordinator" \
  --capabilities "workload-balancing,optimization"

# Verify swarm status
npx claude-flow@alpha swarm status --show-agents --show-topology

MCP Integration

// Initialize swarm
mcp__claude-flow__swarm_init({
  topology: "hierarchical",
  maxAgents: 15,
  strategy: "adaptive"
})

// Spawn coordinators
mcp__claude-flow__agent_spawn({
  type: "coordinator",
  name: "task-orchestrator",
  capabilities: ["task-decomposition", "assignment", "synthesis"]
})

mcp__claude-flow__agent_spawn({
  type: "coordinator",
  name: "hierarchical-coordinator",
  capabilities: ["hierarchy-management", "delegation"]
})

mcp__claude-flow__agent_spawn({
  type: "coordinator",
  name: "adaptive-coordinator",
  capabilities: ["workload-balancing", "optimization"]
})

Memory Patterns

# Store swarm configuration
npx claude-flow@alpha memory store \
  --key "orchestration/swarm" \
  --value '{
    "swarmId": "swarm-12345",
    "topology": "hierarchical",
    "maxAgents": 15,
    "coordinators": ["task-orchestrator", "hierarchical-coordinator", "adaptive-coordinator"]
  }'

Validation Criteria

1. Swarm operational
2. All coordinators active
3. Topology matches requirements
4. Memory coordination functional
5. Health checks passing

Phase 3: Orchestrate Execution

Objective

Coordinate distributed task execution across swarm agents with proper dependency handling.

Evidence-Based Validation

• [ ] All tasks assigned to agents
• [ ] Dependencies respected
• [ ] Execution in progress
• [ ] Progress tracked continuously

Scripts

# Spawn specialized agents based on task requirements
npx claude-flow@alpha agent spawn --type researcher --count 2
npx claude-flow@alpha agent spawn --type coder --count 5
npx claude-flow@alpha agent spawn --type reviewer --count 2
npx claude-flow@alpha agent spawn --type tester --count 2

# Orchestrate task execution
npx claude-flow@alpha task orchestrate \
  --plan execution-plan.json \
  --strategy adaptive \
  --max-agents 12 \
  --priority high

# Alternative: Orchestrate with MCP
# mcp__claude-flow__task_orchestrate({
#   task: "Execute full-stack application build",
#   strategy: "adaptive",
#   maxAgents: 12,
#   priority: "high"
# })

# Monitor orchestration status
npx claude-flow@alpha task status --detailed --json > task-status.json

# Track individual task progress
npx claude-flow@alpha task list --filter "in_progress" --show-timing

# Monitor agent workloads
npx claude-flow@alpha agent metrics --metric tasks --format table

Task Assignment Algorithm

#!/bin/bash
# assign-tasks.sh

# Read decomposition
TASKS=$(jq -r '.tasks[] | @json' decomposition.json)

for TASK in $TASKS; do
  TASK_ID=$(echo $TASK | jq -r '.id')
  TASK_TYPE=$(echo $TASK | jq -r '.type')
  DEPENDENCIES=$(echo $TASK | jq -r '.dependencies[]')

  # Check if dependencies completed
  DEPS_COMPLETE=true
  for DEP in $DEPENDENCIES; do
    DEP_STATUS=$(npx claude-flow@alpha task status --task-id $DEP --format json | jq -r '.status')
    if [ "$DEP_STATUS" != "completed" ]; then
      DEPS_COMPLETE=false
      break
    fi
  done

  # Assign task if dependencies complete
  if [