Orchestration Skill Guidelines

When to Use This Skill

• Parallel multi-agent execution requiring concurrent task processing
• Complex implementation with 6+ independent tasks
• Theater-free development requiring 0% tolerance validation
• Dynamic agent selection from 86+ agent registry
• High-quality delivery needing Byzantine consensus validation

When NOT to Use This Skill

• Single-agent tasks with no parallelization benefit
• Simple sequential work completing in <2 hours
• Planning phase (use research-driven-planning first)
• Trivial changes to single files

Success Criteria

• Agent+skill matrix generated with optimal assignments
• Parallel execution successful with 8.3x speedup achieved
• Theater detection passes with 0% theater detected
• Integration tests pass at 100% rate
• All agents complete with no orphaned workers

Edge Cases to Handle

• Agent failures - Implement agent health monitoring and replacement
• Task timeout - Configure per-task timeout with escalation
• Consensus failure - Have fallback from Byzantine to weighted consensus
• Resource exhaustion - Limit max parallel agents, queue excess
• Conflicting outputs - Implement merge conflict resolution strategy

Guardrails (NEVER Violate)

• NEVER lose agent state - Persist agent progress to memory continuously
• ALWAYS track swarm health - Monitor all agent statuses in real-time
• ALWAYS validate consensus - Require 4/5 agreement for theater detection
• NEVER skip theater audit - Zero tolerance, any theater blocks merge
• ALWAYS cleanup workers - Terminate agents on completion/failure

Evidence-Based Validation

• Check all agent statuses - Verify each agent completed successfully
• Validate parallel execution - Confirm tasks ran concurrently, not sequentially
• Measure speedup - Calculate actual speedup vs sequential baseline
• Audit theater detection - Run 6-agent consensus, verify 0% detection
• Verify integration - Execute sandbox tests, confirm 100% pass rate

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 [ "$DEPS_COMPLETE" = true ]; then
    # Find least loaded agent of required type
    AGENT_ID=$(npx claude-flow@alpha agent list \
      --filter "type=$TASK_TYPE" \
      --sort-by load \
      --format json | jq -r '.[0].id')

    # Assign task
    npx claude-flow@alpha task assign \
      --task-id $TASK_ID \
      --agent-id $AGENT_ID

    echo "Assigned task $TASK_ID to agent $AGENT_ID"
  fi
done

Memory Patterns

# Store task assignments
npx claude-flow@alpha memory store \
  --key "orchestration/assignments" \
  --value '{
    "task-001": {"agent": "agent-researcher-1", "status": "in_progress", "started": "2025-10-30T10:00:00Z"},
    "task-002": {"agent": "agent-coder-1", "status": "in_progress", "started": "2025-10-30T10:01:00Z"}
  }'

# Store execution timeline
npx claude-flow@alpha memory store \
  --key "orchestration/timeline" \
  --value '{
    "started": "2025-10-30T10:00:00Z",
    "tasksCompleted": 12,
    "tasksInProgress": 8,
    "tasksPending": 25
  }'

Validation Criteria

1. All agents assigned tasks
2. No dependency violations
3. Task execution progressing
4. No agent overload
5. Error handling active

Phase 4: Monitor Progress

Objective

Track execution progress, identify blockers, and maintain real-time visibility.

Evidence-Based Validation

• Progress metrics collected
• Blockers identified quickly
• Agents responding properly
• Timeline on track

Scripts

# Start continuous monitoring
npx claude-flow@alpha swarm monitor \
  --interval 10 \
  --duration 3600 \
  --output orchestration-monitor.log &

# Track task completion rate
while true; do
  COMPLETED=$(npx claude-flow@alpha task list --filter "completed" | wc -l)
  TOTAL=$(npx claude-flow@alpha task list | wc -l)
  PROGRESS=$((COMPLETED * 100 / TOTAL))

  echo "Progress: $PROGRESS% ($COMPLETED/$TOTAL tasks)"

  npx claude-flow@alpha memory store \
    --key "orchestration/progress" \
    --value "{\"completed\": $COMPLETED, \"total\": $TOTAL, \"percentage\": $PROGRESS}"

  sleep 30
done &

# Monitor for blocked tasks
npx claude-flow@alpha task detect-blocked \
  --threshold 300 \
  --notify-on-block

# Monitor agent health
npx claude-flow@alpha agent health-check --all --interval 60

# Generate progress report
npx claude-flow@alpha orchestration report \
  --include-timeline \
  --include-agent-metrics \
  --output progress-report.md

Progress Visualization

# Generate Gantt chart
npx claude-flow@alpha task gantt \
  --input task-status.json \
  --output gantt-chart.png

# Generate network diagram
npx claude-flow@alpha task network \
  --show-dependencies \
  --show-progress \
  --output network-diagram.png

Memory Patterns

# Store progress snapshots
npx claude-flow@alpha memory store \
  --key "orchestration/snapshot-$(date +%s)" \
  --value '{
    "timestamp": "'$(date -Iseconds)'",
    "completed": 18,
    "inProgress": 12,
    "pending": 15,
    "blocked": 0,
    "failed": 0
  }'

# Store blocker information
npx claude-flow@alpha memory store \
  --key "orchestration/blockers" \
  --value '{
    "task-015": {"reason": "dependency-failed", "since": "2025-10-30T10:15:00Z"},
    "task-022": {"reason": "agent-unresponsive", "since": "2025-10-30T10:20:00Z"}
  }'

Validation Criteria

1. Progress tracking accurate
2. Blockers detected within 5 minutes
3. No stalled tasks unnoticed
4. Agent failures handled
5. Progress reports generated

Phase 5: Synthesize Results

Objective

Aggregate and synthesize results from all completed tasks into coherent outputs.

Evidence-Based Validation

• All task results collected
• Results synthesized successfully
• Output validated
• Final report generated

Scripts

# Collect all task results
npx claude-flow@alpha task results --all --format json > all-results.json

# Synthesize results by category
npx claude-flow@alpha task synthesize \
  --input all-results.json \
  --group-by category \
  --output synthesized-results.json

# Generate final outputs
npx claude-flow@alpha orchestration finalize \
  --results synthesized-results.json \
  --output final-output/

# Validate outputs
npx claude-flow@alpha orchestration validate \
  --output final-output/ \
  --criteria validation-criteria.json

# Generate final report
npx claude-flow@alpha orchestration report \
  --type final \
  --include-metrics \
  --include-timeline \
  --include-outputs \
  --output final-orchestration-report.md

# Archive orchestration data
npx claude-flow@alpha orchestration archive \
  --output orchestration-archive-$(date +%Y%m%d-%H%M%S).tar.gz

MCP Integration

// Get task results
mcp__claude-flow__task_results({
  taskId: "all",
  format: "detailed"
})

// Check final status
mcp__claude-flow__task_status({
  detailed: true
})

Result Synthesis Strategy

1. Collect Results:

# Get results from each agent type
RESEARCHER_RESULTS=$(npx claude-flow@alpha task results --agent-type researcher --format json)
CODER_RESULTS=$(npx claude-flow@alpha task results --agent-type coder --format json)
REVIEWER_RESULTS=$(npx claude-flow@alpha task results --agent-type reviewer --format json)

2. Aggregate by Phase:

# Architecture phase results
ARCHITECTURE=$(jq '[.[] | select(.phase=="architecture")]' all-results.json)

# Implementation phase results
IMPLEMENTATION=$(jq '[.[] | select(.phase=="implementation")]' all-results.json)

# Testing phase results
TESTING=$(jq '[.[] | select(.phase=="testing")]' all-results.json)

3. Synthesize Final Output:

# Combine all results
jq -s '{
  architecture: .[0],
  implementation: .[1],
  testing: .[2],
  metadata: {
    totalTasks: (.[0] + .[1] + .[2] | length),
    duration: "'$(date -Iseconds)'",
    successRate: 0.98
  }
}' \
  <(echo "$ARCHITECTURE") \
  <(echo "$IMPLEMENTATION") \
  <(echo "$TESTING") \
  > final-synthesis.json

Memory Patterns

# Store final results
npx claude-flow@alpha memory store \
  --key "orchestration/results/final" \
  --file final-synthesis.json

# Store performance metrics
npx claude-flow@alpha memory store \
  --key "orchestration/metrics/final" \
  --value '{
    "totalTasks": 45,
    "completed": 44,
    "failed": 1,
    "duration": "2h 18m",
    "avgTaskTime": "3m 5s",
    "throughput": "0.32 tasks/min"
  }'

Validation Criteria

1. All task results accounted for
2. Synthesis logic correct
3. Outputs validated successfully
4. No data loss
5. Final report comprehensive

Success Criteria

Overall Validation

• Task decomposition accurate
• Swarm orchestration successful
• All tasks completed (≥95%)
• Results synthesized correctly
• Performance targets met

Performance Targets

• Task success rate: ≥95%
• Average task completion time: Within estimates ±20%
• Agent utilization: 70-90%
• Coordination overhead: <15%
• Result synthesis time: <5 minutes

Common Issues & Solutions

Issue: Task Dependencies Not Resolved

Symptoms: Tasks blocked waiting for dependencies Solution: Verify dependency graph, check for circular dependencies

Issue: Agent Overload

Symptoms: Some agents at 100% utilization, others idle Solution: Rebalance task assignments, spawn additional agents

Issue: Task Execution Stalled

Symptoms: Tasks remain in-progress indefinitely Solution: Implement timeout mechanism, restart stuck agents

Issue: Result Synthesis Incomplete

Symptoms: Missing results in final output Solution: Verify all tasks completed, check result collection logic

Best Practices

1. Clear Decomposition: Break tasks into atomic units
2. Explicit Dependencies: Document all task dependencies
3. Progress Tracking: Monitor continuously
4. Error Handling: Implement retry logic
5. Result Validation: Verify outputs at each phase
6. Memory Coordination: Use shared memory for state
7. Agent Specialization: Assign tasks to appropriate agents
8. Performance Monitoring: Track metrics throughout

Integration Points

With Other Skills

• advanced-swarm: For topology optimization
• performance-analysis: For bottleneck detection
• cascade-orchestrator: For workflow chaining
• hive-mind: For collective decision-making

With External Systems

• CI/CD pipelines for automated execution
• Project management tools for tracking
• Monitoring systems for observability
• Storage systems for result archival

Next Steps

After completing this skill:

1. Analyze orchestration metrics
2. Optimize task decomposition strategy
3. Experiment with different topologies
4. Implement custom synthesis logic
5. Create reusable orchestration templates

References

• Claude Flow Documentation
• Task Decomposition Patterns
• Multi-Agent Orchestration Theory
• Distributed Systems Coordination

Core Principles

1. Task Decomposition Drives Efficiency

Breaking complex work into atomic, parallelizable units unlocks the full power of swarm coordination.

In practice:

• Decompose tasks to 3 levels maximum: High-level goals -> Component tasks -> Atomic tasks
• Design atomic tasks to be independent with no shared state dependencies
• Identify explicit dependencies early using dependency graph analysis
• Ensure each task has clear success criteria and estimated duration (30min-2hr per atomic task)
• Validate that parallelizable tasks truly have no hidden dependencies before spawning concurrent agents
• Use task templates for common patterns (API endpoint, database schema, UI component)

2. Memory Coordination as Single Source of Truth

All agents must synchronize state through shared memory to maintain consistency.

In practice:

• Store orchestration state in memory after every phase transition
• Use hierarchical memory keys: orchestration/plan, orchestration/assignments, orchestration/progress
• Implement optimistic locking for concurrent writes with version numbers or timestamps
• Provide memory snapshots at regular intervals (every 30s) for rollback capability
• Design agents to be stateless by persisting all state to memory rather than local variables
• Use memory tags (WHO, WHEN, PROJECT, WHY) for audit trails and debugging

3. Adaptive Coordination Over Fixed Plans

Orchestration must respond to changing conditions rather than rigidly following initial plans.

In practice:

• Monitor agent health continuously with heartbeat checks (every 10s)
• Detect blocked tasks by tracking time-in-progress (alert after 5 minutes without progress)
• Automatically rebalance work by reassigning tasks from overloaded agents to idle agents
• Switch strategies dynamically: sequential -> parallel when agents become available
• Implement circuit breakers that pause orchestration when error rate exceeds 20%
• Provide manual override mechanisms for human intervention when needed

Anti-Patterns

Anti-Pattern	Problem	Solution
Monolithic task decomposition	Large tasks assigned to single agents, no parallelism benefits, long execution times, difficult failure recovery	Break tasks into atomic units (30min-2hr each), identify independent subtasks, spawn multiple agents concurrently, design for parallel execution
Lost orchestration state	Cannot recover from failures, unclear what work completed, duplicated effort, inconsistent final state	Persist orchestration state to memory after every phase, implement checkpoint/resume, track task completion status, log all state transitions
Ignoring agent failures	Failed agents silently disappear, tasks hang indefinitely, partial results with no indication, cascading failures	Monitor agent health with heartbeat checks, detect timeouts (5min), respawn failed agents, implement circuit breakers, track failure patterns
Circular dependencies in task graph	Tasks block waiting for each other, deadlock scenarios, orchestration hangs, no progress possible	Validate dependency graph for cycles before execution, use topological sort to determine valid execution order, fail fast with clear error message
No workload balancing	Some agents overloaded while others idle, poor resource utilization, long tail of slow tasks, uneven completion times	Monitor agent workloads in real-time, dynamically reassign tasks from overloaded agents, spawn additional agents when all highly utilized, implement work stealing

Common Anti-Patterns

Anti-Pattern	Problem	Solution
Monolithic Task Decomposition	Large tasks assigned to single agents with no parallelism benefits, resulting in long execution times and difficult failure recovery from monolithic work units.	Break tasks into atomic units (30min-2hr each). Identify independent subtasks that can run concurrently. Spawn multiple agents in parallel. Design for parallel execution with minimal dependencies.
Lost Orchestration State	Cannot recover from failures, unclear what work completed, duplicated effort after restart, inconsistent final state across distributed agents.	Persist orchestration state to memory after every phase transition. Implement checkpoint/resume capability. Track task completion status explicitly. Log all state transitions with timestamps.
Ignoring Agent Failures	Failed agents silently disappear, tasks hang indefinitely waiting for output, partial results with no indication of failure, cascading failures spread.	Monitor agent health with heartbeat checks (every 10s). Detect timeouts (5min without progress). Respawn failed agents automatically. Implement circuit breakers for systematic failures. Track failure patterns for analysis.

Conclusion

Swarm orchestration represents the pinnacle of multi-agent coordination, enabling complex workflows to be executed with unprecedented speed and reliability through intelligent task decomposition, parallel execution, and adaptive coordination. The power of this approach lies in its ability to transform large, monolithic tasks into atomic units that can be processed concurrently by specialized agents, often achieving 8-10x speedup over sequential execution. However, this power comes with significant complexity in managing dependencies, coordinating state, and handling failures across distributed agents.

The three core principles - task decomposition, memory coordination, and adaptive orchestration - form the foundation of robust swarm systems. Task decomposition unlocks parallelism by identifying independent work units. Memory coordination ensures consistency by providing a single source of truth that all agents reference. Adaptive coordination enables resilience by responding to failures and changing conditions dynamically. Together, these principles create orchestration systems that are not only fast but also reliable and maintainable.

As you implement swarm orchestration, prioritize observability and incremental validation. Start with simple hierarchical topologies before exploring mesh or adaptive patterns. Validate your dependency graph for cycles before spawning agents. Monitor task progress continuously and alert on blockers quickly. Design for failure by implementing automatic retries, circuit breakers, and agent replacement strategies. By following these practices, you can build orchestration systems that harness the full power of multi-agent coordination while maintaining the reliability and debuggability required for production use. Remember: successful swarm orchestration is not about controlling every detail but about creating conditions for autonomous agents to collaborate effectively toward shared goals.