12# Flow Nexus Swarm & Workflow Orchestration
13
14Deploy and manage cloud-based AI agent swarms with event-driven workflow automation, message queue processing, and intelligent agent coordination.
15
16## 📋 Table of Contents
17
181. [Overview](#overview)
192. [Swarm Management](#swarm-management)
203. [Workflow Automation](#workflow-automation)
214. [Agent Orchestration](#agent-orchestration)
225. [Templates & Patterns](#templates--patterns)
236. [Advanced Features](#advanced-features)
247. [Best Practices](#best-practices)
25
26## Overview
27
28Flow Nexus provides cloud-based orchestration for AI agent swarms with:
29
30- **Multi-topology Support**: Hierarchical, mesh, ring, and star architectures
31- **Event-driven Workflows**: Message queue processing with async execution
32- **Template Library**: Pre-built swarm configurations for common use cases
33- **Intelligent Agent Assignment**: Vector similarity matching for optimal agent selection
34- **Real-time Monitoring**: Comprehensive metrics and audit trails
35- **Scalable Infrastructure**: Cloud-based execution with auto-scaling
36
37## Swarm Management
38
39### Initialize Swarm
40
41Create a new swarm with specified topology and configuration:
42
43```javascript
44mcp__flow-nexus__swarm_init({
45 topology: "hierarchical", // Options: mesh, ring, star, hierarchical
46 maxAgents: 8,
47 strategy: "balanced" // Options: balanced, specialized, adaptive
48})
49```
50
51**Topology Guide:**
52- **Hierarchical**: Tree structure with coordinator nodes (best for complex projects)
53- **Mesh**: Peer-to-peer collaboration (best for research and analysis)
54- **Ring**: Circular coordination (best for sequential workflows)
55- **Star**: Centralized hub (best for simple delegation)
56
57**Strategy Guide:**
58- **Balanced**: Equal distribution of workload across agents
59- **Specialized**: Agents focus on specific expertise areas
60- **Adaptive**: Dynamic adjustment based on task complexity
61
62### Spawn Agents
63
64Add specialized agents to the swarm:
65
66```javascript
67mcp__flow-nexus__agent_spawn({
68 type: "researcher", // Options: researcher, coder, analyst, optimizer, coordinator
69 name: "Lead Researcher",
70 capabilities: ["web_search", "analysis", "summarization"]
71})
72```
73
74**Agent Types:**
75- **Researcher**: Information gathering, web search, analysis
76- **Coder**: Code generation, refactoring, implementation
77- **Analyst**: Data analysis, pattern recognition, insights
78- **Optimizer**: Performance tuning, resource optimization
79- **Coordinator**: Task delegation, progress tracking, integration
80
81### Orchestrate Tasks
82
83Distribute tasks across the swarm:
84
85```javascript
86mcp__flow-nexus__task_orchestrate({
87 task: "Build a REST API with authentication and database integration",
88 strategy: "parallel", // Options: parallel, sequential, adaptive
89 maxAgents: 5,
90 priority: "high" // Options: low, medium, high, critical
91})
92```
93
94**Execution Strategies:**
95- **Parallel**: Maximum concurrency for independent subtasks
96- **Sequential**: Step-by-step execution with dependencies
97- **Adaptive**: AI-powered strategy selection based on task analysis
98
99### Monitor & Scale Swarms
100
101```javascript
102// Get detailed swarm status
103mcp__flow-nexus__swarm_status({
104 swarm_id: "optional-id" // Uses active swarm if not provided
105})
106
107// List all active swarms
108mcp__flow-nexus__swarm_list({
109 status: "active" // Options: active, destroyed, all
110})
111
112// Scale swarm up or down
113mcp__flow-nexus__swarm_scale({
114 target_agents: 10,
115 swarm_id: "optional-id"
116})
117
118// Gracefully destroy swarm
119mcp__flow-nexus__swarm_destroy({
120 swarm_id: "optional-id"
121})
122```
123
124## Workflow Automation
125
126### Create Workflow
127
128Define event-driven workflows with message queue processing:
129
130```javascript
131mcp__flow-nexus__workflow_create({
132 name: "CI/CD Pipeline",
133 description: "Automated testing, building, and deployment",
134 steps: [
135 {
136 id: "test",
137 action: "run_tests",
138 agent: "tester",
139 parallel: true
140 },
141 {
142 id: "build",
143 action: "build_app",
144 agent: "builder",
145 depends_on: ["test"]
146 },
147 {
148 id: "deploy",
149 action: "deploy_prod",
150 agent: "deployer",
151 depends_on: ["build"]
152 }
153 ],
154 triggers: ["push_to_main", "manual_trigger"],
155 metadata: {
156 priority: 10,
157 retry_policy: "exponential_backoff"
158 }
159})
160```
161
162**Workflow Features:**
163- **Dependency Management**: Define step dependencies with depends_on
164- **Parallel Execution**: Set parallel: true for concurrent steps
165- **Event Triggers**: GitHub events, schedules, manual triggers
166- **Retry Policies**: Automatic retry on transient failures
167- **Priority Queuing**: High-priority workflows execute first
168
169### Execute Workflow
170
171Run workflows synchronously or asynchronously:
172
173```javascript
174mcp__flow-nexus__workflow_execute({
175 workflow_id: "workflow_id",
176 input_data: {
177 branch: "main",
178 commit: "abc123",
179 environment: "production"
180 },
181 async: true // Queue-based execution for long-running workflows
182})
183```
184
185**Execution Modes:**
186- **Sync (async: false)**: Immediate execution, wait for completion
187- **Async (async: true)**: Message queue processing, non-blocking
188
189### Monitor Workflows
190
191```javascript
192// Get workflow status and metrics
193mcp__flow-nexus__workflow_status({
194 workflow_id: "id",
195 execution_id: "specific-run-id", // Optional
196 include_metrics: true
197})
198
199// List workflows with filters
200mcp__flow-nexus__workflow_list({
201 status: "running", // Options: running, completed, failed, pending
202 limit: 10,
203 offset: 0
204})
205
206// Get complete audit trail
207mcp__flow-nexus__workflow_audit_trail({
208 workflow_id: "id",
209 limit: 50,
210 start_time: "2025-01-01T00:00:00Z"
211})
212```
213
214### Agent Assignment
215
216Intelligently assign agents to workflow tasks:
217
218```javascript
219mcp__flow-nexus__workflow_agent_assign({
220 task_id: "task_id",
221 agent_type: "coder", // Preferred agent type
222 use_vector_similarity: true // AI-powered capability matching
223})
224```
225
226**Vector Similarity Matching:**
227- Analyzes task requirements and agent capabilities
228- Finds optimal agent based on past performance
229- Considers workload and availability
230
231### Queue Management
232
233Monitor and manage message queues:
234
235```javascript
236mcp__flow-nexus__workflow_queue_status({
237 queue_name: "optional-specific-queue",
238 include_messages: true // Show pending messages
239})
240```
241
242## Agent Orchestration
243
244### Full-Stack Development Pattern
245
246```javascript
247// 1. Initialize swarm with hierarchical topology
248mcp__flow-nexus__swarm_init({
249 topology: "hierarchical",
250 maxAgents: 8,
251 strategy: "specialized"
252})
253
254// 2. Spawn specialized agents
255mcp__flow-nexus__agent_spawn({ type: "coordinator", name: "Project Manager" })
256mcp__flow-nexus__agent_spawn({ type: "coder", name: "Backend Developer" })
257mcp__flow-nexus__agent_spawn({ type: "coder", name: "Frontend Developer" })
258mcp__flow-nexus__agent_spawn({ type: "coder", name: "Database Architect" })
259mcp__flow-nexus__agent_spawn({ type: "analyst", name: "QA Engineer" })
260
261// 3. Create development workflow
262mcp__flow-nexus__workflow_create({
263 name: "Full-Stack Development",
264 steps: [
265 { id: "requirements", action: "analyze_requirements", agent: "coordinator" },
266 { id: "db_design", action: "design_schema", agent: "Database Architect" },
267 { id: "backend", action: "build_api", agent: "Backend Developer", depends_on: ["db_design"] },
268 { id: "frontend", action: "build_ui", agent: "Frontend Developer", depends_on: ["requirements"] },
269 { id: "integration", action: "integrate", agent: "Backend Developer", depends_on: ["backend", "frontend"] },
270 { id: "testing", action: "qa_testing", agent: "QA Engineer", depends_on: ["integration"] }
271 ]
272})
273
274// 4. Execute workflow
275mcp__flow-nexus__workflow_execute({
276 workflow_id: "workflow_id",
277 input_data: {
278 project: "E-commerce Platform",
279 tech_stack: ["Node.js", "React", "PostgreSQL"]
280 }
281})
282```
283
284### Research & Analysis Pattern
285
286```javascript
287// 1. Initialize mesh topology for collaborative research
288mcp__flow-nexus__swarm_init({
289 topology: "mesh",
290 maxAgents: 5,
291 strategy: "balanced"
292})
293
294// 2. Spawn research agents
295mcp__flow-nexus__agent_spawn({ type: "researcher", name: "Primary Researcher" })
296mcp__flow-nexus__agent_spawn({ type: "researcher", name: "Secondary Researcher" })
297mcp__flow-nexus__agent_spawn({ type: "analyst", name: "Data Analyst" })
298mcp__flow-nexus__agent_spawn({ type: "analyst", name: "Insights Analyst" })
299
300// 3. Orchestrate research task
301mcp__flow-nexus__task_orchestrate({
302 task: "Research machine learning trends for 2025 and analyze market opportunities",
303 strategy: "parallel",
304 maxAgents: 4,
305 priority: "high"
306})
307```
308
309### CI/CD Pipeline Pattern
310
311```javascript
312mcp__flow-nexus__workflow_create({
313 name: "Deployment Pipeline",
314 description: "Automated testing, building, and multi-environment deployment",
315 steps: [
316 { id: "lint", action: "lint_code", agent: "code_quality", parallel: true },
317 { id: "unit_test", action: "unit_tests", agent: "test_runner", parallel: true },
318 { id: "integration_test", action: "integration_tests", agent: "test_runner", parallel: true },
319 { id: "build", action: "build_artifacts", agent: "builder", depends_on: ["lint", "unit_test", "integration_test"] },
320 { id: "security_scan", action: "security_scan", agent: "security", depends_on: ["build"] },
321 { id: "deploy_staging", action: "deploy", agent: "deployer", depends_on: ["security_scan"] },
322 { id: "smoke_test", action: "smoke_tests", agent: "test_runner", depends_on: ["deploy_staging"] },
323 { id: "deploy_prod", action: "deploy", agent: "deployer", depends_on: ["smoke_test"] }
324 ],
325 triggers: ["github_push", "github_pr_merged"],
326 metadata: {
327 priority: 10,
328 auto_rollback: true
329 }
330})
331```
332
333### Data Processing Pipeline Pattern
334
335```javascript
336mcp__flow-nexus__workflow_create({
337 name: "ETL Pipeline",
338 description: "Extract, Transform, Load data processing",
339 steps: [
340 { id: "extract", action: "extract_data", agent: "data_extractor" },
341 { id: "validate_raw", action: "validate_data", agent: "validator", depends_on: ["extract"] },
342 { id: "transform", action: "transform_data", agent: "transformer", depends_on: ["validate_raw"] },
343 { id: "enrich", action: "enrich_data", agent: "enricher", depends_on: ["transform"] },
344 { id: "load", action: "load_data", agent: "loader", depends_on: ["enrich"] },
345 { id: "validate_final", action: "validate_data", agent: "validator", depends_on: ["load"] }
346 ],
347 triggers: ["schedule:0 2 * * *"], // Daily at 2 AM
348 metadata: {
349 retry_policy: "exponential_backoff",
350 max_retries: 3
351 }
352})
353```
354
355## Templates & Patterns
356
357### Use Pre-built Templates
358
359```javascript
360// Create swarm from template
361mcp__flow-nexus__swarm_create_from_template({
362 template_name: "full-stack-dev",
363 overrides: {
364 maxAgents: 6,
365 strategy: "specialized"
366 }
367})
368
369// List available templates
370mcp__flow-nexus__swarm_templates_list({
371 category: "quickstart", // Options: quickstart, specialized, enterprise, custom, all
372 includeStore: true
373})
374```
375
376**Available Template Categories:**
377
378**Quickstart Templates:**
379- full-stack-dev: Complete web development swarm
380- research-team: Research and analysis swarm
381- code-review: Automated code review swarm
382- data-pipeline: ETL and data processing
383
384**Specialized Templates:**
385- ml-development: Machine learning project swarm
386- mobile-dev: Mobile app development
387- devops-automation: Infrastructure and deployment
388- security-audit: Security analysis and testing
389
390**Enterprise Templates:**
391- enterprise-migration: Large-scale system migration
392- multi-repo-sync: Multi-repository coordination
393- compliance-review: Regulatory compliance workflows
394- incident-response: Automated incident management
395
396### Custom Template Creation
397
398Save successful swarm configurations as reusable templates for future projects.
399
400## Advanced Features
401
402### Real-time Monitoring
403
404```javascript
405// Subscribe to execution streams
406mcp__flow-nexus__execution_stream_subscribe({
407 stream_type: "claude-flow-swarm",
408 deployment_id: "deployment_id"
409})
410
411// Get execution status
412mcp__flow-nexus__execution_stream_status({
413 stream_id: "stream_id"
414})
415
416// List files created during execution
417mcp__flow-nexus__execution_files_list({
418 stream_id: "stream_id",
419 created_by: "claude-flow"
420})
421```
422
423### Swarm Metrics & Analytics
424
425```javascript
426// Get swarm performance metrics
427mcp__flow-nexus__swarm_status({
428 swarm_id: "id"
429})
430
431// Analyze workflow efficiency
432mcp__flow-nexus__workflow_status({
433 workflow_id: "id",
434 include_metrics: true
435})
436```
437
438### Multi-Swarm Coordination
439
440Coordinate multiple swarms for complex, multi-phase projects:
441
442```javascript
443// Phase 1: Research swarm
444const researchSwarm = await mcp__flow-nexus__swarm_init({
445 topology: "mesh",
446 maxAgents: 4
447})
448
449// Phase 2: Development swarm
450const devSwarm = await mcp__flow-nexus__swarm_init({
451 topology: "hierarchical",
452 maxAgents: 8
453})
454
455// Phase 3: Testing swarm
456const testSwarm = await mcp__flow-nexus__swarm_init({
457 topology: "star",
458 maxAgents: 5
459})
460```
461
462## Best Practices
463
464### 1. Choose the Right Topology
465
466```javascript
467// Simple projects: Star
468mcp__flow-nexus__swarm_init({ topology: "star", maxAgents: 3 })
469
470// Collaborative work: Mesh
471mcp__flow-nexus__swarm_init({ topology: "mesh", maxAgents: 5 })
472
473// Complex projects: Hierarchical
474mcp__flow-nexus__swarm_init({ topology: "hierarchical", maxAgents: 10 })
475
476// Sequential workflows: Ring
477mcp__flow-nexus__swarm_init({ topology: "ring", maxAgents: 4 })
478```
479
480### 2. Optimize Agent Assignment
481
482```javascript
483// Use vector similarity for optimal matching
484mcp__flow-nexus__workflow_agent_assign({
485 task_id: "complex-task",
486 use_vector_similarity: true
487})
488```
489
490### 3. Implement Proper Error Handling
491
492```javascript
493mcp__flow-nexus__workflow_create({
494 name: "Resilient Workflow",
495 steps: [...],
496 metadata: {
497 retry_policy: "exponential_backoff",
498 max_retries: 3,
499 timeout: 300000, // 5 minutes
500 on_failure: "notify_and_rollback"
501 }
502})
503```
504
505### 4. Monitor and Scale
506
507```javascript
508// Regular monitoring
509const status = await mcp__flow-nexus__swarm_status()
510
511// Scale based on workload
512if (status.workload > 0.8) {
513 await mcp__flow-nexus__swarm_scale({ target_agents: status.agents + 2 })
514}
515```
516
517### 5. Use Async Execution for Long-Running Workflows
518
519```javascript
520// Long-running workflows should use message queues
521mcp__flow-nexus__workflow_execute({
522 workflow_id: "data-pipeline",
523 async: true // Non-blocking execution
524})
525
526// Monitor progress
527mcp__flow-nexus__workflow_queue_status({ include_messages: true })
528```
529
530### 6. Clean Up Resources
531
532```javascript
533// Destroy swarm when complete
534mcp__flow-nexus__swarm_destroy({ swarm_id: "id" })
535```
536
537### 7. Leverage Templates
538
539```javascript
540// Use proven templates instead of building from scratch
541mcp__flow-nexus__swarm_create_from_template({
542 template_name: "code-review",
543 overrides: { maxAgents: 4 }
544})
545```
546
547## Integration with Claude Flow
548
549Flow Nexus swarms integrate seamlessly with Claude Flow hooks:
550
551```bash
552# Pre-task coordination setup
553npx claude-flow@alpha hooks pre-task --description "Initialize swarm"
554
555# Post-task metrics export
556npx claude-flow@alpha hooks post-task --task-id "swarm-execution"
557```
558
559## Common Use Cases
560
561### 1. Multi-Repo Development
562- Coordinate development across multiple repositories
563- Synchronized testing and deployment
564- Cross-repo dependency management
565
566### 2. Research Projects
567- Distributed information gathering
568- Parallel analysis of different data sources
569- Collaborative synthesis and reporting
570
571### 3. DevOps Automation
572- Infrastructure as Code deployment
573- Multi-environment testing
574- Automated rollback and recovery
575
576### 4. Code Quality Workflows
577- Automated code review
578- Security scanning
579- Performance benchmarking
580
581### 5. Data Processing
582- Large-scale ETL pipelines
583- Real-time data transformation
584- Data validation and quality checks
585
586## Authentication & Setup
587
588```bash
589# Install Flow Nexus
590npm install -g flow-nexus@latest
591
592# Register account
593npx flow-nexus@latest register
594
595# Login
596npx flow-nexus@latest login
597
598# Add MCP server to Claude Code
599claude mcp add flow-nexus npx flow-nexus@latest mcp start
600```
601
602## Support & Resources
603
604- **Platform**: https://flow-nexus.ruv.io
605- **Documentation**: https://github.com/ruvnet/flow-nexus
606- **Issues**: https://github.com/ruvnet/flow-nexus/issues
607
608---
609
610**Remember**: Flow Nexus provides cloud-based orchestration infrastructure. For local execution and coordination, use the core claude-flow MCP server alongside Flow Nexus for maximum flexibility.
611