swarm-orchestration
ruvnet/ruflo
Multi-agent swarm coordination for complex tasks across multiple files and modules.
What is swarm-orchestration?
Orchestrates specialized agents in a hierarchical topology to break down and execute complex work spanning 3+ files. Use for feature implementation, cross-module refactoring, API changes, security updates, and performance optimization. Skip for single-file edits, simple bug fixes, and documentation updates.
- Initialize swarms with hierarchical topology to prevent drift across agents
- Route tasks to appropriate agent types based on task description
- Spawn specialized agents (coder, analyzer, etc.) for specific work
- Monitor real-time swarm status and active agent count
- Orchestrate parallel or adaptive task execution across multiple agents
- Store and retrieve successful patterns from memory
How to install swarm-orchestration
npx skills add https://github.com/ruvnet/ruflo --skill swarm-orchestration- Node.js and npm installed
- @claude-flow/cli package available
- Project with 3+ files to coordinate changes across
How to use swarm-orchestration
- 1.Run `npx @claude-flow/cli swarm init --topology hierarchical --max-agents 8 --strategy specialized` to initialize
- 2.Use `npx @claude-flow/cli hooks route --task "[description]"` to route your task to appropriate agents
- 3.Spawn specific agents with `npx @claude-flow/cli agent spawn --type [type] --name [name]` if needed
- 4.Monitor progress with `npx @claude-flow/cli swarm status --verbose`
- 5.Orchestrate execution with `npx @claude-flow/cli task orchestrate --task "[task]" --strategy adaptive`
- 6.Check `npx @claude-flow/cli agent list --filter active` to see current agents
Use cases
- Implementing OAuth2 authentication flow across multiple modules with tests
- Refactoring an auth module with coordinated changes across 4+ files
- Database schema migration with corresponding model and API updates
- Security patch deployment requiring changes to multiple services
- Performance optimization across codebase with benchmarking and validation
- Backend engineers managing large refactors
- Teams implementing cross-cutting features
- Developers optimizing performance across multiple modules
- Engineers handling security-related changes requiring coordination
swarm-orchestration FAQ
Use swarm orchestration when 3+ files need coordinated changes, such as feature implementation, refactoring, or API changes. For single-file edits or simple 1-2 line bug fixes, use standard single-agent editing.
The skill supports hierarchical topology (recommended for coordination and anti-drift) and other topologies documented in docs/topology.md.
Yes, use the `--max-agents` flag when initializing (e.g., `--max-agents 6`) to limit concurrent agents based on your task complexity.
Use `npx @claude-flow/cli swarm status --verbose` for real-time status, or run the `swarm-monitor` script at `.agents/scripts/swarm-monitor.sh` for a dashboard.
Store successful patterns in memory after completion using the built-in memory system, so the swarm can reuse them for similar future tasks.
Full instructions (SKILL.md)
Source of truth, from ruvnet/ruflo.
name: swarm-orchestration description: > Multi-agent swarm coordination for complex tasks. Uses hierarchical topology with specialized agents to break down and execute complex work across multiple files and modules. Use when: 3+ files need changes, new feature implementation, cross-module refactoring, API changes with tests, security-related changes, performance optimization across codebase, database schema changes. Skip when: single file edits, simple bug fixes (1-2 lines), documentation updates, configuration changes, quick exploration.
Swarm Orchestration Skill
Purpose
Multi-agent swarm coordination for complex tasks. Uses hierarchical topology with specialized agents to break down and execute complex work across multiple files and modules.
When to Trigger
- 3+ files need changes
- new feature implementation
- cross-module refactoring
- API changes with tests
- security-related changes
- performance optimization across codebase
- database schema changes
When to Skip
- single file edits
- simple bug fixes (1-2 lines)
- documentation updates
- configuration changes
- quick exploration
Commands
Initialize Swarm
Start a new swarm with hierarchical topology (anti-drift)
npx @claude-flow/cli swarm init --topology hierarchical --max-agents 8 --strategy specialized
Example:
npx @claude-flow/cli swarm init --topology hierarchical --max-agents 6 --strategy specialized
Route Task
Route a task to the appropriate agents based on task type
npx @claude-flow/cli hooks route --task "[task description]"
Example:
npx @claude-flow/cli hooks route --task "implement OAuth2 authentication flow"
Spawn Agent
Spawn a specific agent type
npx @claude-flow/cli agent spawn --type [type] --name [name]
Example:
npx @claude-flow/cli agent spawn --type coder --name impl-auth
Monitor Status
Check the current swarm status
npx @claude-flow/cli swarm status --verbose
Orchestrate Task
Orchestrate a task across multiple agents
npx @claude-flow/cli task orchestrate --task "[task]" --strategy adaptive
Example:
npx @claude-flow/cli task orchestrate --task "refactor auth module" --strategy parallel --max-agents 4
List Agents
List all active agents
npx @claude-flow/cli agent list --filter active
Scripts
| Script | Path | Description |
|---|---|---|
swarm-start | .agents/scripts/swarm-start.sh | Initialize swarm with default settings |
swarm-monitor | .agents/scripts/swarm-monitor.sh | Real-time swarm monitoring dashboard |
References
| Document | Path | Description |
|---|---|---|
Agent Types | docs/agents.md | Complete list of agent types and capabilities |
Topology Guide | docs/topology.md | Swarm topology configuration guide |
Best Practices
- Check memory for existing patterns before starting
- Use hierarchical topology for coordination
- Store successful patterns after completion
- Document any new learnings
Related skills
More from ruvnet/ruflo and the wider catalog.
V3 CLI Modernization
CLI modernization and hooks system enhancement for claude-flow v3. Implements interactive prompts, command decomposition, enhanced hooks integration, and intelligent workflow automation.
V3 Core Implementation
Core module implementation for claude-flow v3. Implements DDD domains, clean architecture patterns, dependency injection, and modular TypeScript codebase with comprehensive testing.
V3 DDD Architecture
Domain-Driven Design architecture for claude-flow v3. Implements modular, bounded context architecture with clean separation of concerns and microkernel pattern.
V3 Deep Integration
Deep agentic-flow@alpha integration implementing ADR-001. Eliminates 10,000+ duplicate lines by building claude-flow as specialized extension rather than parallel implementation.
V3 MCP Optimization
MCP server optimization and transport layer enhancement for claude-flow v3. Implements connection pooling, load balancing, tool registry optimization, and performance monitoring for sub-100ms response times.
V3 Memory Unification
Unify 6+ memory systems into AgentDB with HNSW indexing for 150x-12,500x search improvements. Implements ADR-006 (Unified Memory Service) and ADR-009 (Hybrid Memory Backend).