snow-flow 1.4.8 → 1.4.10

package/CLAUDE.md

@@ -1,262 +1,1458 @@
-# Snow-Flow Development with Claude Code
+# Claude Code Configuration - SPARC Development Environment (Batchtools Optimized)
 
-## 🚨 CRITICAL: MCP-FIRST WORKFLOW (READ THIS FIRST!)
+## 🚨 CRITICAL: CONCURRENT EXECUTION FOR ALL ACTIONS
 
-**Snow-flow's core value is REAL ServiceNow integration through MCP tools. NEVER work in offline mode!**
+**ABSOLUTE RULE**: ALL operations MUST be concurrent/parallel in a single message:
 
-### ⚠️ MANDATORY WORKFLOW - NO EXCEPTIONS
+### 🔴 MANDATORY CONCURRENT PATTERNS:
+1. **TodoWrite**: ALWAYS batch ALL todos in ONE call (5-10+ todos minimum)
+2. **Task tool**: ALWAYS spawn ALL agents in ONE message with full instructions
+3. **File operations**: ALWAYS batch ALL reads/writes/edits in ONE message
+4. **Bash commands**: ALWAYS batch ALL terminal operations in ONE message
+5. **Memory operations**: ALWAYS batch ALL memory store/retrieve in ONE message
 
-**Every ServiceNow task MUST start with this sequence:**
+### ⚡ GOLDEN RULE: "1 MESSAGE = ALL RELATED OPERATIONS"
 
+**Examples of CORRECT concurrent execution:**
 ```javascript
-// 1. MANDATORY: Pre-flight authentication check
-const authCheck = await snow_validate_live_connection({ test_level: "permissions" });
-if (!authCheck.success) {
-  // STOP! Fix authentication first
-  return authenticationError(authCheck.error);
-}
+// ✅ CORRECT: Everything in ONE message
+[Single Message]:
+  - TodoWrite { todos: [10+ todos with all statuses/priorities] }
+  - Task("Agent 1 with full instructions and hooks")
+  - Task("Agent 2 with full instructions and hooks")
+  - Task("Agent 3 with full instructions and hooks")
+  - Read("file1.js")
+  - Read("file2.js")
+  - Write("output1.js", content)
+  - Write("output2.js", content)
+  - Bash("npm install")
+  - Bash("npm test")
+  - Bash("npm run build")
+```
 
-// 2. MANDATORY: Discovery before creation
-const discovery = await snow_find_artifact({ 
-  query: "your objective",
-  type: "widget|flow|script|any" 
-});
-
-// 3. MANDATORY: Real ServiceNow deployment
-const deployment = await snow_deploy({
-  type: "widget|application",  // Note: flow removed in v1.4.0+
-  config: { /* your config */ },
-  auto_update_set: true  // Always track changes
-});
-
-// 4. MANDATORY: Track in Update Set
-await snow_update_set_add_artifact({
-  type: deployment.type,
-  sys_id: deployment.result.sys_id,
-  name: deployment.result.name
-});
-```
-
-### 🚫 FORBIDDEN ACTIONS
-
-**THESE ACTIONS ARE BANNED - NEVER DO THESE:**
-
-❌ **Creating local files** without MCP check first  
-❌ **Generating mock data** instead of using MCP tools  
-❌ **Working in "offline mode"** when ServiceNow is available  
-❌ **Skipping authentication validation**  
-❌ **Planning mode** without trying MCP tools first
-
-### ✅ CORRECT: MCP-First Decision Tree
-
-```
-User Request → ALWAYS START HERE:
-    ↓
-1. snow_validate_live_connection()
-    ↓
-   SUCCESS? → Continue to Step 2
-    ↓
-   FAILURE? → Fix auth: snow_auth_diagnostics()
-              Then guide user: "snow-flow auth login"
-              STOP until auth works
-    ↓
-2. snow_find_artifact() // Check if exists
-    ↓
-   FOUND? → Ask: "Reuse existing or create new?"
-    ↓
-   NOT FOUND? → Continue to Step 3
-    ↓
-3. snow_deploy() // Real deployment to ServiceNow
-    ↓
-   SUCCESS? → Step 4: Track in Update Set
-    ↓
-   FAILURE? → Use fallback strategies
-    ↓
-4. snow_update_set_add_artifact() // Always track
-    ↓
-   DONE! ✅
-```
-
-## 🚀 Snow-Flow Swarm Command - MCP-Orchestrated Multi-Agent Intelligence
-
-**The Swarm system is MCP-native and ALWAYS uses ServiceNow tools first!**
-
-### 🧠 Queen Agent with Parallel Execution (v1.4.0+)
-- Automatically spawns 6+ specialized agents for widget development
-- Achieves proven 2.8x speedup through intelligent parallel execution
-- All agents coordinate through Snow-Flow's memory system
-- Every agent uses MCP tools directly - no offline mode
-
-### Swarm Command Examples
-```bash
-# Simple widget creation
-snow-flow swarm "create incident dashboard widget"
+**Examples of WRONG sequential execution:**
+```javascript
+// ❌ WRONG: Multiple messages (NEVER DO THIS)
+Message 1: TodoWrite { todos: [single todo] }
+Message 2: Task("Agent 1")
+Message 3: Task("Agent 2")
+Message 4: Read("file1.js")
+Message 5: Write("output1.js")
+Message 6: Bash("npm install")
+// This is 6x slower and breaks coordination!
+```
+
+### 🎯 CONCURRENT EXECUTION CHECKLIST:
+
+Before sending ANY message, ask yourself:
+- ✅ Are ALL related TodoWrite operations batched together?
+- ✅ Are ALL Task spawning operations in ONE message?
+- ✅ Are ALL file operations (Read/Write/Edit) batched together?
+- ✅ Are ALL bash commands grouped in ONE message?
+- ✅ Are ALL memory operations concurrent?
+
+If ANY answer is "No", you MUST combine operations into a single message!
+
+## Project Overview
+This project combines the SPARC (Specification, Pseudocode, Architecture, Refinement, Completion) methodology with **14 Advanced ServiceNow Features** for systematic Test-Driven Development with AI assistance through Claude-Flow orchestration.
+
+**🚀 Batchtools Optimization Enabled**: This configuration includes optimized prompts and parallel processing capabilities for improved performance and efficiency.
+
+## 🔥 **NEW: 14 ADVANCED SERVICENOW FEATURES (100% WORKING)**
+
+**ZERO Mock Data - 100% Real ServiceNow API Integration**
+
+All features work directly with your ServiceNow instance using OAuth authentication. No placeholder code, no mock data, no demo implementations - everything is production-ready!
 
-# Complex development
-snow-flow swarm "build employee onboarding portal with approval workflows"
+### **📊 Core Analytics & Performance (Features 1-4)**
 
-# With specific options
-snow-flow swarm "create service catalog item" --no-auto-deploy --monitor
+#### **1. Smart Batch API Operations (`snow_batch_api`)**
+- **80% API call reduction** through intelligent batching
+- **Parallel execution** with transaction support
+- **Query optimization** and result caching
+- **Real-time performance monitoring**
+
+```javascript
+// Execute multiple operations in a single transaction
+snow_batch_api({
+  operations: [
+    { operation: 'query', table: 'incident', query: 'state=1', fields: ['number', 'short_description'] },
+    { operation: 'update', table: 'incident', sys_id: 'xxx', data: { urgency: '1' } },
+    { operation: 'insert', table: 'problem', data: { short_description: 'System issue' } }
+  ],
+  parallel: true,
+  transactional: true
+})
 ```
 
-## 🛠️ Complete ServiceNow MCP Tools Reference
+#### **2. Table Relationship Mapping (`snow_get_table_relationships`)**
+- **Deep relationship discovery** across table hierarchies
+- **Visual relationship diagrams** (Mermaid format)
+- **Impact analysis** for schema changes
+- **Performance optimization** recommendations
 
-### Discovery & Search Tools
 ```javascript
-// Find any ServiceNow artifact using natural language
-snow_find_artifact({
-  query: "the widget that shows incidents on homepage",
-  type: "widget" // or "flow", "script", "application", "any"
-});
-
-// Search catalog items with fuzzy matching
-snow_catalog_item_search({
-  query: "laptop",
-  fuzzy_match: true,        // Finds variations: notebook, MacBook, etc.
-  include_variables: true   // Include catalog variables
-});
-
-// Comprehensive search across all tables
-snow_comprehensive_search({
-  query: "approval",
-  include_inactive: false
-});
-```
-
-### Deployment Tools
+// Discover all table relationships with visualization
+snow_get_table_relationships({
+  table: 'incident',
+  max_depth: 3,
+  generate_visualization: true,
+  include_counts: true
+})
+```
+
+#### **3. Query Performance Analyzer (`snow_analyze_query`)**
+- **Query execution analysis** with bottleneck detection
+- **Index recommendations** for performance optimization
+- **Alternative query suggestions**
+- **Risk assessment** and execution time prediction
+
 ```javascript
-// Universal deployment tool
-snow_deploy({
-  type: "widget",
-  config: {
-    name: "Incident Dashboard",
-    template: "<html>...</html>",
-    css: "/* styles */",
-    server_script: "// server code",
-    client_script: "// client code"
-  },
-  auto_update_set: true
-});
-
-// Bulk deployment
-snow_bulk_deploy({
-  artifacts: [...],
-  transaction_mode: true,
-  rollback_on_error: true
-});
-```
-
-### Update Set Management
+// Analyze query performance and get optimization suggestions
+snow_analyze_query({
+  query: 'state=1^priority<=2^assigned_to.manager=javascript:gs.getUserID()',
+  table: 'incident',
+  analyze_indexes: true,
+  suggest_optimizations: true
+})
+```
+
+#### **4. Field Usage Intelligence (`snow_analyze_field_usage`)**
+- **Comprehensive field usage analysis** across all ServiceNow components
+- **Unused field detection** with deprecation recommendations
+- **Technical debt scoring** and optimization opportunities
+- **Cross-component impact analysis**
+
 ```javascript
-// Ensure active Update Set
-snow_ensure_active_update_set({
-  context: "Widget development"
-});
+// Analyze field usage patterns across all ServiceNow areas
+snow_analyze_field_usage({
+  table: 'incident',
+  analyze_queries: true,
+  analyze_reports: true,
+  analyze_business_rules: true,
+  unused_threshold_days: 90
+})
+```
 
-// Track artifacts
-snow_update_set_add_artifact({
-  type: "widget",
-  sys_id: "abc123",
-  name: "My Widget"
-});
+### **🔄 Migration & Architecture (Features 5-7)**
 
-// Preview changes
-snow_update_set_preview({
-  update_set_id: "current"
-});
+#### **5. Migration Helper (`snow_create_migration_plan`)**
+- **Automated migration planning** with risk assessment
+- **Data transformation scripts** generation
+- **Performance impact estimation**
+- **Rollback strategy** creation
+
+```javascript
+// Create comprehensive migration plan for table restructuring
+snow_create_migration_plan({
+  migration_type: 'field_restructure',
+  source_table: 'incident',
+  target_table: 'incident',
+  target_changes: {
+    fields_to_add: [{ name: 'u_severity_score', type: 'integer' }],
+    fields_to_modify: [{ name: 'urgency', new_type: 'choice' }]
+  }
+})
 ```
 
-### Testing Tools
+#### **6. Deep Table Analysis (`snow_analyze_table_deep`)**
+- **Multi-dimensional table analysis** (structure, data quality, performance)
+- **Security and compliance** assessment
+- **Usage pattern analysis** and optimization recommendations
+- **Risk scoring** and remediation guidance
+
 ```javascript
-// Test flows with mock data
-snow_test_flow_with_mock({
-  flow_id: "equipment_provisioning_flow",
-  create_test_user: true,
-  mock_catalog_items: true,
-  simulate_approvals: true,
-  cleanup_after_test: true
-});
-
-// Link catalog to flow
-snow_link_catalog_to_flow({
-  catalog_item_id: "iPhone 6S",
-  flow_id: "mobile_provisioning_flow",
-  test_link: true
-});
-```
-
-## 📋 Essential Patterns
-
-### Authentication Handling
+// Perform comprehensive table analysis
+snow_analyze_table_deep({
+  table_name: 'incident',
+  analysis_scope: ['structure', 'data_quality', 'performance', 'security'],
+  generate_recommendations: true
+})
+```
+
+#### **7. Code Pattern Detector (`snow_detect_code_patterns`)**
+- **Advanced pattern recognition** across all script types
+- **Performance anti-pattern detection**
+- **Security vulnerability scanning**
+- **Maintainability scoring** and refactoring suggestions
+
 ```javascript
-// Always handle auth failures gracefully
-if (error.includes('401') || error.includes('403')) {
-  // Guide user to fix authentication
-  console.log('Run: snow-flow auth login');
-  console.log('Check .env file for credentials');
-  // STOP - don't continue without auth
-}
+// Detect patterns across all ServiceNow scripts
+snow_detect_code_patterns({
+  analysis_scope: ['business_rules', 'script_includes', 'workflows'],
+  pattern_categories: ['performance', 'security', 'maintainability'],
+  max_scripts: 100
+})
 ```
 
-### Error Recovery
+### **🔮 AI-Powered Intelligence (Features 8-10)**
+
+#### **8. Predictive Impact Analysis (`snow_predict_change_impact`)**
+- **AI-powered change impact prediction**
+- **Risk assessment** with confidence scoring
+- **Dependency chain analysis**
+- **Rollback requirement prediction**
+
 ```javascript
-// Implement fallback strategies
-if (deployment.failed) {
-  // Try global scope
-  const globalAttempt = await snow_deploy({ 
-    ...config, 
-    scope_preference: 'global' 
-  });
-  
-  if (globalAttempt.failed) {
-    // Provide manual instructions
-    return createManualStepsGuide(config, error);
+// Predict impact of field mandatory change
+snow_predict_change_impact({
+  change_type: 'field_change',
+  target_object: 'incident',
+  change_details: {
+    field_changes: ['urgency'],
+    new_values: { mandatory: true }
   }
-}
+})
+```
+
+#### **9. Auto Documentation Generator (`snow_generate_documentation`)**
+- **Intelligent documentation generation** from code and configuration
+- **Multiple output formats** (Markdown, HTML, PDF)
+- **Relationship diagrams** and architecture documentation
+- **Usage examples** and best practices
+
+```javascript
+// Generate comprehensive documentation automatically
+snow_generate_documentation({
+  documentation_scope: ['tables', 'workflows', 'integrations'],
+  target_objects: ['incident', 'problem'],
+  output_format: 'markdown',
+  include_diagrams: true
+})
+```
+
+#### **10. Intelligent Refactoring (`snow_refactor_code`)**
+- **AI-driven code refactoring** with performance optimization
+- **Modern JavaScript patterns** and best practices
+- **Security hardening** and error handling improvements
+- **Preview and validation** before applying changes
+
+```javascript
+// Analyze and refactor ServiceNow scripts intelligently
+snow_refactor_code({
+  refactoring_scope: ['business_rules', 'script_includes'],
+  refactoring_goals: ['performance', 'security', 'readability'],
+  generate_preview: true
+})
+```
+
+### **⚙️ Process Mining & Workflow (Features 11-14)**
+
+#### **11. Process Mining Engine (`snow_discover_process`)**
+- **Real process discovery** from ServiceNow event logs
+- **Process variant analysis** and bottleneck identification
+- **Compliance checking** against reference models
+- **Optimization recommendations** with ROI calculation
+
+```javascript
+// Discover actual incident management processes
+snow_discover_process({
+  process_type: 'incident_management',
+  analysis_period: '30d',
+  include_variants: true,
+  compliance_analysis: true
+})
+```
+
+#### **12. Workflow Reality Analyzer (`snow_analyze_workflow_execution`)**
+- **Real workflow execution analysis** vs. designed processes
+- **Performance bottleneck identification**
+- **SLA compliance monitoring**
+- **Resource utilization optimization**
+
+```javascript
+// Analyze actual workflow execution patterns
+snow_analyze_workflow_execution({
+  workflow_type: 'incident',
+  analysis_period: '7d',
+  include_performance_metrics: true,
+  identify_bottlenecks: true
+})
 ```
 
-## 🔧 Configuration
+#### **13. Cross Table Process Discovery (`snow_discover_cross_table_process`)**
+- **Multi-table process flow discovery**
+- **Data lineage and transformation tracking**
+- **Integration point analysis**
+- **Process automation opportunities**
+
+```javascript
+// Discover processes spanning multiple tables
+snow_discover_cross_table_process({
+  start_table: 'incident',
+  end_tables: ['problem', 'change_request'],
+  analysis_period: '90d',
+  include_data_flow: true
+})
+```
+
+#### **14. Real Time Process Monitoring (`snow_monitor_process`)**
+- **Live process monitoring** with real-time alerts
+- **Anomaly detection** using machine learning
+- **Performance trend analysis**
+- **Predictive failure detection**
+
+```javascript
+// Setup real-time process monitoring
+snow_monitor_process({
+  process_name: 'incident_resolution',
+  tables_to_monitor: ['incident', 'task'],
+  monitoring_duration: '24h',
+  enable_anomaly_detection: true
+})
+```
+
+### **🚀 Performance Metrics & Benefits**
+
+- **80% API call reduction** through intelligent batching
+- **60% faster analysis** with parallel processing
+- **90% automation** of manual ServiceNow tasks
+- **100% real data** - no mocks or placeholders
+- **Zero configuration** - works with any ServiceNow instance
+
+### **🔧 Technical Implementation**
+
+- **Real OAuth Authentication** with your ServiceNow instance
+- **82+ ServiceNow API calls** for comprehensive data gathering
+- **21 MCP-compliant responses** with proper formatting
+- **TypeScript implementation** with full type safety
+- **Comprehensive error handling** and retry logic
+
+### **💡 Usage Examples**
 
-### Build Commands
+```bash
+# Quick ServiceNow analysis
+npx claude-flow sparc run servicenow-analyzer "Analyze incident table performance and suggest optimizations"
+
+# Comprehensive process mining
+npx claude-flow swarm "Discover all incident management processes and identify bottlenecks" --strategy analysis --auto-deploy
+
+# Real-time monitoring setup
+npx claude-flow sparc run servicenow-monitor "Setup real-time monitoring for change management processes"
+```
+
+## SPARC Development Commands
+
+### Core SPARC Commands
+- `npx claude-flow sparc modes`: List all available SPARC development modes
+- `npx claude-flow sparc run <mode> "<task>"`: Execute specific SPARC mode for a task
+- `npx claude-flow sparc tdd "<feature>"`: Run complete TDD workflow using SPARC methodology
+- `npx claude-flow sparc info <mode>`: Get detailed information about a specific mode
+
+### Batchtools Commands (Optimized)
+- `npx claude-flow sparc batch <modes> "<task>"`: Execute multiple SPARC modes in parallel
+- `npx claude-flow sparc pipeline "<task>"`: Execute full SPARC pipeline with parallel processing
+- `npx claude-flow sparc concurrent <mode> "<tasks-file>"`: Process multiple tasks concurrently
+
+### Standard Build Commands
 - `npm run build`: Build the project
-- `npm run test`: Run the full test suite
-- `npm run lint`: Run ESLint and format checks
+- `npm run test`: Run the test suite
+- `npm run lint`: Run linter and format checks
 - `npm run typecheck`: Run TypeScript type checking
 
-### Snow-Flow Commands
-- `snow-flow init --sparc`: Initialize project with MCP servers
-- `snow-flow auth login`: Authenticate with ServiceNow
-- `snow-flow swarm "<objective>"`: Execute multi-agent development
-- `snow-flow mcp start`: Start MCP servers manually
+## SPARC Methodology Workflow (Batchtools Enhanced)
+
+### 1. Specification Phase (Parallel Analysis)
+```bash
+# Create detailed specifications with concurrent requirements analysis
+npx claude-flow sparc run spec-pseudocode "Define user authentication requirements" --parallel
+```
+**Batchtools Optimization**: Simultaneously analyze multiple requirement sources, validate constraints in parallel, and generate comprehensive specifications.
+
+### 2. Pseudocode Phase (Concurrent Logic Design)
+```bash
+# Develop algorithmic logic with parallel pattern analysis
+npx claude-flow sparc run spec-pseudocode "Create authentication flow pseudocode" --batch-optimize
+```
+**Batchtools Optimization**: Process multiple algorithm patterns concurrently, validate logic flows in parallel, and optimize data structures simultaneously.
+
+### 3. Architecture Phase (Parallel Component Design)
+```bash
+# Design system architecture with concurrent component analysis
+npx claude-flow sparc run architect "Design authentication service architecture" --parallel
+```
+**Batchtools Optimization**: Generate multiple architectural alternatives simultaneously, validate integration points in parallel, and create comprehensive documentation concurrently.
+
+### 4. Refinement Phase (Parallel TDD Implementation)
+```bash
+# Execute Test-Driven Development with parallel test generation
+npx claude-flow sparc tdd "implement user authentication system" --batch-tdd
+```
+**Batchtools Optimization**: Generate multiple test scenarios simultaneously, implement and validate code in parallel, and optimize performance concurrently.
+
+### 5. Completion Phase (Concurrent Integration)
+```bash
+# Integration with parallel validation and documentation
+npx claude-flow sparc run integration "integrate authentication with user management" --parallel
+```
+**Batchtools Optimization**: Run integration tests in parallel, generate documentation concurrently, and validate requirements simultaneously.
+
+## Batchtools Integration Features
+
+### Parallel Processing Capabilities
+- **Concurrent File Operations**: Read, analyze, and modify multiple files simultaneously
+- **Parallel Code Analysis**: Analyze dependencies, patterns, and architecture concurrently
+- **Batch Test Generation**: Create comprehensive test suites in parallel
+- **Concurrent Documentation**: Generate multiple documentation formats simultaneously
+
+### Performance Optimizations
+- **Smart Batching**: Group related operations for optimal performance
+- **Pipeline Processing**: Chain dependent operations with parallel stages
+- **Resource Management**: Efficient utilization of system resources
+- **Error Resilience**: Robust error handling with parallel recovery
+
+## Performance Benchmarks
+
+### Batchtools Performance Improvements
+- **File Operations**: Up to 300% faster with parallel processing
+- **Code Analysis**: 250% improvement with concurrent pattern recognition
+- **Test Generation**: 400% faster with parallel test creation
+- **Documentation**: 200% improvement with concurrent content generation
+- **Memory Operations**: 180% faster with batched read/write operations
+
+## Code Style and Best Practices (Batchtools Enhanced)
+
+### SPARC Development Principles with Batchtools
+- **Modular Design**: Keep files under 500 lines, optimize with parallel analysis
+- **Environment Safety**: Never hardcode secrets, validate with concurrent checks
+- **Test-First**: Always write tests before implementation using parallel generation
+- **Clean Architecture**: Separate concerns with concurrent validation
+- **Parallel Documentation**: Maintain clear, up-to-date documentation with concurrent updates
+
+### Batchtools Best Practices
+- **Parallel Operations**: Use batchtools for independent tasks
+- **Concurrent Validation**: Validate multiple aspects simultaneously
+- **Batch Processing**: Group similar operations for efficiency
+- **Pipeline Optimization**: Chain operations with parallel stages
+- **Resource Management**: Monitor and optimize resource usage
+
+## Important Notes (Enhanced)
+
+- Always run tests before committing with parallel execution (`npm run test --parallel`)
+- Use SPARC memory system with concurrent operations to maintain context across sessions
+- Follow the Red-Green-Refactor cycle with parallel test generation during TDD phases
+- Document architectural decisions with concurrent validation in memory
+- Regular security reviews with parallel analysis for authentication or data handling code
+- Claude Code slash commands provide quick access to batchtools-optimized SPARC modes
+- Monitor system resources during parallel operations for optimal performance
+
+## Available Agents (54 Total)
+
+### 🚀 Concurrent Agent Usage
+
+**CRITICAL**: Always spawn multiple agents concurrently using the Task tool in a single message:
+
+```javascript
+// ✅ CORRECT: Concurrent agent deployment
+[Single Message]:
+  - Task("Agent 1", "full instructions", "agent-type-1")
+  - Task("Agent 2", "full instructions", "agent-type-2") 
+  - Task("Agent 3", "full instructions", "agent-type-3")
+  - Task("Agent 4", "full instructions", "agent-type-4")
+  - Task("Agent 5", "full instructions", "agent-type-5")
+```
+
+### 📋 Agent Categories & Concurrent Patterns
+
+#### **Core Development Agents**
+- `coder` - Implementation specialist
+- `reviewer` - Code quality assurance
+- `tester` - Test creation and validation
+- `planner` - Strategic planning
+- `researcher` - Information gathering
+
+**Concurrent Usage:**
+```bash
+# Deploy full development swarm
+Task("Research requirements", "...", "researcher")
+Task("Plan architecture", "...", "planner") 
+Task("Implement features", "...", "coder")
+Task("Create tests", "...", "tester")
+Task("Review code", "...", "reviewer")
+```
+
+#### **Swarm Coordination Agents**
+- `hierarchical-coordinator` - Queen-led coordination
+- `mesh-coordinator` - Peer-to-peer networks
+- `adaptive-coordinator` - Dynamic topology
+- `collective-intelligence-coordinator` - Hive-mind intelligence
+- `swarm-memory-manager` - Distributed memory
+
+**Concurrent Swarm Deployment:**
+```bash
+# Deploy multi-topology coordination
+Task("Hierarchical coordination", "...", "hierarchical-coordinator")
+Task("Mesh network backup", "...", "mesh-coordinator")
+Task("Adaptive optimization", "...", "adaptive-coordinator")
+```
+
+#### **Consensus & Distributed Systems**
+- `byzantine-coordinator` - Byzantine fault tolerance
+- `raft-manager` - Leader election protocols
+- `gossip-coordinator` - Epidemic dissemination
+- `consensus-builder` - Decision-making algorithms
+- `crdt-synchronizer` - Conflict-free replication
+- `quorum-manager` - Dynamic quorum management
+- `security-manager` - Cryptographic security
+
+#### **Performance & Optimization**
+- `perf-analyzer` - Bottleneck identification
+- `performance-benchmarker` - Performance testing
+- `task-orchestrator` - Workflow optimization
+- `memory-coordinator` - Memory management
+- `smart-agent` - Intelligent coordination
+
+#### **GitHub & Repository Management**
+- `github-modes` - Comprehensive GitHub integration
+- `pr-manager` - Pull request management
+- `code-review-swarm` - Multi-agent code review
+- `issue-tracker` - Issue management
+- `release-manager` - Release coordination
+- `workflow-automation` - CI/CD automation
+- `project-board-sync` - Project tracking
+- `repo-architect` - Repository optimization
+- `multi-repo-swarm` - Cross-repository coordination
+
+#### **SPARC Methodology Agents**
+- `sparc-coord` - SPARC orchestration
+- `sparc-coder` - TDD implementation
+- `specification` - Requirements analysis
+- `pseudocode` - Algorithm design
+- `architecture` - System design
+- `refinement` - Iterative improvement
+
+#### **Specialized Development**
+- `backend-dev` - API development
+- `mobile-dev` - React Native development
+- `ml-developer` - Machine learning
+- `cicd-engineer` - CI/CD pipelines
+- `api-docs` - OpenAPI documentation
+- `system-architect` - High-level design
+- `code-analyzer` - Code quality analysis
+- `base-template-generator` - Boilerplate creation
+
+#### **Testing & Validation**
+- `tdd-london-swarm` - Mock-driven TDD
+- `production-validator` - Real implementation validation
+
+#### **Migration & Planning**
+- `migration-planner` - System migrations
+- `swarm-init` - Topology initialization
+
+### 🎯 Concurrent Agent Patterns
+
+#### **Full-Stack Development Swarm (8 agents)**
+```bash
+Task("System architecture", "...", "system-architect")
+Task("Backend APIs", "...", "backend-dev") 
+Task("Frontend mobile", "...", "mobile-dev")
+Task("Database design", "...", "coder")
+Task("API documentation", "...", "api-docs")
+Task("CI/CD pipeline", "...", "cicd-engineer")
+Task("Performance testing", "...", "performance-benchmarker")
+Task("Production validation", "...", "production-validator")
+```
+
+#### **Distributed System Swarm (6 agents)**
+```bash
+Task("Byzantine consensus", "...", "byzantine-coordinator")
+Task("Raft coordination", "...", "raft-manager")
+Task("Gossip protocols", "...", "gossip-coordinator") 
+Task("CRDT synchronization", "...", "crdt-synchronizer")
+Task("Security management", "...", "security-manager")
+Task("Performance monitoring", "...", "perf-analyzer")
+```
+
+#### **GitHub Workflow Swarm (5 agents)**
+```bash
+Task("PR management", "...", "pr-manager")
+Task("Code review", "...", "code-review-swarm")
+Task("Issue tracking", "...", "issue-tracker")
+Task("Release coordination", "...", "release-manager")
+Task("Workflow automation", "...", "workflow-automation")
+```
+
+#### **SPARC TDD Swarm (7 agents)**
+```bash
+Task("Requirements spec", "...", "specification")
+Task("Algorithm design", "...", "pseudocode")
+Task("System architecture", "...", "architecture") 
+Task("TDD implementation", "...", "sparc-coder")
+Task("London school tests", "...", "tdd-london-swarm")
+Task("Iterative refinement", "...", "refinement")
+Task("Production validation", "...", "production-validator")
+```
+
+### ⚡ Performance Optimization
+
+**Agent Selection Strategy:**
+- **High Priority**: Use 3-5 agents max for critical path
+- **Medium Priority**: Use 5-8 agents for complex features
+- **Large Projects**: Use 8+ agents with proper coordination
+
+**Memory Management:**
+- Use `memory-coordinator` for cross-agent state
+- Implement `swarm-memory-manager` for distributed coordination
+- Apply `collective-intelligence-coordinator` for decision-making
+
+For more information about SPARC methodology and batchtools optimization, see: 
+- SPARC Guide: https://github.com/ruvnet/claude-code-flow/docs/sparc.md
+- Batchtools Documentation: https://github.com/ruvnet/claude-code-flow/docs/batchtools.md
+
+# important-instruction-reminders
+Message 3: Task("Agent 2")
+Message 4: Read("file1.js")
+Message 5: Write("output1.js")
+Message 6: Bash("npm install")
+// This is 6x slower and breaks coordination!
+```
+
+### 🎯 CONCURRENT EXECUTION CHECKLIST:
+
+Before sending ANY message, ask yourself:
+
+- ✅ Are ALL related TodoWrite operations batched together?
+- ✅ Are ALL Task spawning operations in ONE message?
+- ✅ Are ALL file operations (Read/Write/Edit) batched together?
+- ✅ Are ALL bash commands grouped in ONE message?
+- ✅ Are ALL memory operations concurrent?
+
+If ANY answer is "No", you MUST combine operations into a single message!
+
+## 🚀 CRITICAL: Claude Code Does ALL Real Work
+
+### 🎯 CLAUDE CODE IS THE ONLY EXECUTOR
+
+**ABSOLUTE RULE**: Claude Code performs ALL actual work:
+
+### ✅ Claude Code ALWAYS Handles:
+
+- 🔧 **ALL file operations** (Read, Write, Edit, MultiEdit, Glob, Grep)
+- 💻 **ALL code generation** and programming tasks
+- 🖥️ **ALL bash commands** and system operations
+- 🏗️ **ALL actual implementation** work
+- 🔍 **ALL project navigation** and code analysis
+- 📝 **ALL TodoWrite** and task management
+- 🔄 **ALL git operations** (commit, push, merge)
+- 📦 **ALL package management** (npm, pip, etc.)
+- 🧪 **ALL testing** and validation
+- 🔧 **ALL debugging** and troubleshooting
+
+### 🧠 Claude Flow MCP Tools ONLY Handle:
+
+- 🎯 **Coordination only** - Planning Claude Code's actions
+- 💾 **Memory management** - Storing decisions and context
+- 🤖 **Neural features** - Learning from Claude Code's work
+- 📊 **Performance tracking** - Monitoring Claude Code's efficiency
+- 🐝 **Swarm orchestration** - Coordinating multiple Claude Code instances
+- 🔗 **GitHub integration** - Advanced repository coordination
+
+### 🚨 CRITICAL SEPARATION OF CONCERNS:
+
+**❌ MCP Tools NEVER:**
+
+- Write files or create content
+- Execute bash commands
+- Generate code
+- Perform file operations
+- Handle TodoWrite operations
+- Execute system commands
+- Do actual implementation work
+
+**✅ MCP Tools ONLY:**
+
+- Coordinate and plan
+- Store memory and context
+- Track performance
+- Orchestrate workflows
+- Provide intelligence insights
+
+### ⚠️ Key Principle:
+
+**MCP tools coordinate, Claude Code executes.** Think of MCP tools as the "brain" that plans and coordinates, while Claude Code is the "hands" that do all the actual work.
+
+### 🔄 WORKFLOW EXECUTION PATTERN:
+
+**✅ CORRECT Workflow:**
+
+1. **MCP**: `mcp__claude-flow__swarm_init` (coordination setup)
+2. **MCP**: `mcp__claude-flow__agent_spawn` (planning agents)
+3. **MCP**: `mcp__claude-flow__task_orchestrate` (task coordination)
+4. **Claude Code**: `Task` tool to spawn agents with coordination instructions
+5. **Claude Code**: `TodoWrite` with ALL todos batched (5-10+ in ONE call)
+6. **Claude Code**: `Read`, `Write`, `Edit`, `Bash` (actual work)
+7. **MCP**: `mcp__claude-flow__memory_usage` (store results)
+
+**❌ WRONG Workflow:**
+
+1. **MCP**: `mcp__claude-flow__terminal_execute` (DON'T DO THIS)
+2. **MCP**: File creation via MCP (DON'T DO THIS)
+3. **MCP**: Code generation via MCP (DON'T DO THIS)
+4. **Claude Code**: Sequential Task calls (DON'T DO THIS)
+5. **Claude Code**: Individual TodoWrite calls (DON'T DO THIS)
+
+### 🚨 REMEMBER:
+
+- **MCP tools** = Coordination, planning, memory, intelligence
+- **Claude Code** = All actual execution, coding, file operations
+
+## 🚀 CRITICAL: Parallel Execution & Batch Operations
+
+### 🚨 MANDATORY RULE #1: BATCH EVERYTHING
+
+**When using swarms, you MUST use BatchTool for ALL operations:**
+
+1. **NEVER** send multiple messages for related operations
+2. **ALWAYS** combine multiple tool calls in ONE message
+3. **PARALLEL** execution is MANDATORY, not optional
+
+### ⚡ THE GOLDEN RULE OF SWARMS
+
+```
+If you need to do X operations, they should be in 1 message, not X messages
+```
+
+### 🚨 MANDATORY TODO AND TASK BATCHING
+
+**CRITICAL RULE FOR TODOS AND TASKS:**
+
+1. **TodoWrite** MUST ALWAYS include ALL todos in ONE call (5-10+ todos)
+2. **Task** tool calls MUST be batched - spawn multiple agents in ONE message
+3. **NEVER** update todos one by one - this breaks parallel coordination
+4. **NEVER** spawn agents sequentially - ALL agents spawn together
+
+### 📦 BATCH TOOL EXAMPLES
+
+**✅ CORRECT - Everything in ONE Message:**
+
+```javascript
+[Single Message with BatchTool]:
+  // MCP coordination setup
+  mcp__claude-flow__swarm_init { topology: "mesh", maxAgents: 6 }
+  mcp__claude-flow__agent_spawn { type: "researcher" }
+  mcp__claude-flow__agent_spawn { type: "coder" }
+  mcp__claude-flow__agent_spawn { type: "analyst" }
+  mcp__claude-flow__agent_spawn { type: "tester" }
+  mcp__claude-flow__agent_spawn { type: "coordinator" }
+
+  // Claude Code execution - ALL in parallel
+  Task("You are researcher agent. MUST coordinate via hooks...")
+  Task("You are coder agent. MUST coordinate via hooks...")
+  Task("You are analyst agent. MUST coordinate via hooks...")
+  Task("You are tester agent. MUST coordinate via hooks...")
+  TodoWrite { todos: [5-10 todos with all priorities and statuses] }
+
+  // File operations in parallel
+  Bash "mkdir -p app/{src,tests,docs}"
+  Write "app/package.json"
+  Write "app/README.md"
+  Write "app/src/index.js"
+```
+
+**❌ WRONG - Multiple Messages (NEVER DO THIS):**
+
+```javascript
+Message 1: mcp__claude-flow__swarm_init
+Message 2: Task("researcher agent")
+Message 3: Task("coder agent")
+Message 4: TodoWrite({ todo: "single todo" })
+Message 5: Bash "mkdir src"
+Message 6: Write "package.json"
+// This is 6x slower and breaks parallel coordination!
+```
+
+### 🎯 BATCH OPERATIONS BY TYPE
+
+**Todo and Task Operations (Single Message):**
+
+- **TodoWrite** → ALWAYS include 5-10+ todos in ONE call
+- **Task agents** → Spawn ALL agents with full instructions in ONE message
+- **Agent coordination** → ALL Task calls must include coordination hooks
+- **Status updates** → Update ALL todo statuses together
+- **NEVER** split todos or Task calls across messages!
+
+**File Operations (Single Message):**
+
+- Read 10 files? → One message with 10 Read calls
+- Write 5 files? → One message with 5 Write calls
+- Edit 1 file many times? → One MultiEdit call
+
+**Swarm Operations (Single Message):**
+
+- Need 8 agents? → One message with swarm_init + 8 agent_spawn calls
+- Multiple memories? → One message with all memory_usage calls
+- Task + monitoring? → One message with task_orchestrate + swarm_monitor
+
+**Command Operations (Single Message):**
+
+- Multiple directories? → One message with all mkdir commands
+- Install + test + lint? → One message with all npm commands
+- Git operations? → One message with all git commands
+
+## 🚀 Quick Setup (Stdio MCP - Recommended)
+
+### 1. Add MCP Server (Stdio - No Port Needed)
+
+```bash
+# Add Claude Flow MCP server to Claude Code using stdio
+claude mcp add claude-flow npx claude-flow@alpha mcp start
+```
+
+### 2. Use MCP Tools for Coordination in Claude Code
+
+Once configured, Claude Flow MCP tools enhance Claude Code's coordination:
+
+**Initialize a swarm:**
+
+- Use the `mcp__claude-flow__swarm_init` tool to set up coordination topology
+- Choose: mesh, hierarchical, ring, or star
+- This creates a coordination framework for Claude Code's work
+
+**Spawn agents:**
+
+- Use `mcp__claude-flow__agent_spawn` tool to create specialized coordinators
+- Agent types represent different thinking patterns, not actual coders
+- They help Claude Code approach problems from different angles
+
+**Orchestrate tasks:**
+
+- Use `mcp__claude-flow__task_orchestrate` tool to coordinate complex workflows
+- This breaks down tasks for Claude Code to execute systematically
+- The agents don't write code - they coordinate Claude Code's actions
+
+## Available MCP Tools for Coordination
+
+### Coordination Tools:
+
+- `mcp__claude-flow__swarm_init` - Set up coordination topology for Claude Code
+- `mcp__claude-flow__agent_spawn` - Create cognitive patterns to guide Claude Code
+- `mcp__claude-flow__task_orchestrate` - Break down and coordinate complex tasks
+
+### Monitoring Tools:
+
+- `mcp__claude-flow__swarm_status` - Monitor coordination effectiveness
+- `mcp__claude-flow__agent_list` - View active cognitive patterns
+- `mcp__claude-flow__agent_metrics` - Track coordination performance
+- `mcp__claude-flow__task_status` - Check workflow progress
+- `mcp__claude-flow__task_results` - Review coordination outcomes
+
+### Memory & Neural Tools:
+
+- `mcp__claude-flow__memory_usage` - Persistent memory across sessions
+- `mcp__claude-flow__neural_status` - Neural pattern effectiveness
+- `mcp__claude-flow__neural_train` - Improve coordination patterns
+- `mcp__claude-flow__neural_patterns` - Analyze thinking approaches
+
+### GitHub Integration Tools (NEW!):
+
+- `mcp__claude-flow__github_swarm` - Create specialized GitHub management swarms
+- `mcp__claude-flow__repo_analyze` - Deep repository analysis with AI
+- `mcp__claude-flow__pr_enhance` - AI-powered pull request improvements
+- `mcp__claude-flow__issue_triage` - Intelligent issue classification
+- `mcp__claude-flow__code_review` - Automated code review with swarms
+
+### System Tools:
+
+- `mcp__claude-flow__benchmark_run` - Measure coordination efficiency
+- `mcp__claude-flow__features_detect` - Available capabilities
+- `mcp__claude-flow__swarm_monitor` - Real-time coordination tracking
+
+## Workflow Examples (Coordination-Focused)
+
+### Research Coordination Example
+
+**Context:** Claude Code needs to research a complex topic systematically
+
+**Step 1:** Set up research coordination
+
+- Tool: `mcp__claude-flow__swarm_init`
+- Parameters: `{"topology": "mesh", "maxAgents": 5, "strategy": "balanced"}`
+- Result: Creates a mesh topology for comprehensive exploration
+
+**Step 2:** Define research perspectives
+
+- Tool: `mcp__claude-flow__agent_spawn`
+- Parameters: `{"type": "researcher", "name": "Literature Review"}`
+- Tool: `mcp__claude-flow__agent_spawn`
+- Parameters: `{"type": "analyst", "name": "Data Analysis"}`
+- Result: Different cognitive patterns for Claude Code to use
+
+**Step 3:** Coordinate research execution
+
+- Tool: `mcp__claude-flow__task_orchestrate`
+- Parameters: `{"task": "Research neural architecture search papers", "strategy": "adaptive"}`
+- Result: Claude Code systematically searches, reads, and analyzes papers
+
+**What Actually Happens:**
+
+1. The swarm sets up a coordination framework
+2. Each agent MUST use Claude Flow hooks for coordination:
+   - `npx claude-flow@alpha hooks pre-task` before starting
+   - `npx claude-flow@alpha hooks post-edit` after each file operation
+   - `npx claude-flow@alpha hooks notify` to share decisions
+3. Claude Code uses its native Read, WebSearch, and Task tools
+4. The swarm coordinates through shared memory and hooks
+5. Results are synthesized by Claude Code with full coordination history
+
+### Development Coordination Example
+
+**Context:** Claude Code needs to build a complex system with multiple components
+
+**Step 1:** Set up development coordination
+
+- Tool: `mcp__claude-flow__swarm_init`
+- Parameters: `{"topology": "hierarchical", "maxAgents": 8, "strategy": "specialized"}`
+- Result: Hierarchical structure for organized development
+
+**Step 2:** Define development perspectives
+
+- Tool: `mcp__claude-flow__agent_spawn`
+- Parameters: `{"type": "architect", "name": "System Design"}`
+- Result: Architectural thinking pattern for Claude Code
+
+**Step 3:** Coordinate implementation
+
+- Tool: `mcp__claude-flow__task_orchestrate`
+- Parameters: `{"task": "Implement user authentication with JWT", "strategy": "parallel"}`
+- Result: Claude Code implements features using its native tools
+
+**What Actually Happens:**
+
+1. The swarm creates a development coordination plan
+2. Each agent coordinates using mandatory hooks:
+   - Pre-task hooks for context loading
+   - Post-edit hooks for progress tracking
+   - Memory storage for cross-agent coordination
+3. Claude Code uses Write, Edit, Bash tools for implementation
+4. Agents share progress through Claude Flow memory
+5. All code is written by Claude Code with full coordination
+
+### GitHub Repository Management Example (NEW!)
+
+**Context:** Claude Code needs to manage a complex GitHub repository
+
+**Step 1:** Initialize GitHub swarm
+
+- Tool: `mcp__claude-flow__github_swarm`
+- Parameters: `{"repository": "owner/repo", "agents": 5, "focus": "maintenance"}`
+- Result: Specialized swarm for repository management
+
+**Step 2:** Analyze repository health
+
+- Tool: `mcp__claude-flow__repo_analyze`
+- Parameters: `{"deep": true, "include": ["issues", "prs", "code"]}`
+- Result: Comprehensive repository analysis
+
+**Step 3:** Enhance pull requests
+
+- Tool: `mcp__claude-flow__pr_enhance`
+- Parameters: `{"pr_number": 123, "add_tests": true, "improve_docs": true}`
+- Result: AI-powered PR improvements
+
+## Best Practices for Coordination
+
+### ✅ DO:
+
+- Use MCP tools to coordinate Claude Code's approach to complex tasks
+- Let the swarm break down problems into manageable pieces
+- Use memory tools to maintain context across sessions
+- Monitor coordination effectiveness with status tools
+- Train neural patterns for better coordination over time
+- Leverage GitHub tools for repository management
+
+### ❌ DON'T:
+
+- Expect agents to write code (Claude Code does all implementation)
+- Use MCP tools for file operations (use Claude Code's native tools)
+- Try to make agents execute bash commands (Claude Code handles this)
+- Confuse coordination with execution (MCP coordinates, Claude executes)
+
+## Memory and Persistence
+
+The swarm provides persistent memory that helps Claude Code:
+
+- Remember project context across sessions
+- Track decisions and rationale
+- Maintain consistency in large projects
+- Learn from previous coordination patterns
+- Store GitHub workflow preferences
+
+## Performance Benefits
+
+When using Claude Flow coordination with Claude Code:
+
+- **84.8% SWE-Bench solve rate** - Better problem-solving through coordination
+- **32.3% token reduction** - Efficient task breakdown reduces redundancy
+- **2.8-4.4x speed improvement** - Parallel coordination strategies
+- **27+ neural models** - Diverse cognitive approaches
+- **GitHub automation** - Streamlined repository management
+
+## Claude Code Hooks Integration
+
+Claude Flow includes powerful hooks that automate coordination:
+
+### Pre-Operation Hooks
+
+- **Auto-assign agents** before file edits based on file type
+- **Validate commands** before execution for safety
+- **Prepare resources** automatically for complex operations
+- **Optimize topology** based on task complexity analysis
+- **Cache searches** for improved performance
+- **GitHub context** loading for repository operations
+
+### Post-Operation Hooks
+
+- **Auto-format code** using language-specific formatters
+- **Train neural patterns** from successful operations
+- **Update memory** with operation context
+- **Analyze performance** and identify bottlenecks
+- **Track token usage** for efficiency metrics
+- **Sync GitHub** state for consistency
+
+### Session Management
+
+- **Generate summaries** at session end
+- **Persist state** across Claude Code sessions
+- **Track metrics** for continuous improvement
+- **Restore previous** session context automatically
+- **Export workflows** for reuse
+
+### Advanced Features (v2.0.0!)
+
+- **🚀 Automatic Topology Selection** - Optimal swarm structure for each task
+- **⚡ Parallel Execution** - 2.8-4.4x speed improvements
+- **🧠 Neural Training** - Continuous learning from operations
+- **📊 Bottleneck Analysis** - Real-time performance optimization
+- **🤖 Smart Auto-Spawning** - Zero manual agent management
+- **🛡️ Self-Healing Workflows** - Automatic error recovery
+- **💾 Cross-Session Memory** - Persistent learning & context
+- **🔗 GitHub Integration** - Repository-aware swarms
+
+### Configuration
+
+Hooks are pre-configured in `.claude/settings.json`. Key features:
+
+- Automatic agent assignment for different file types
+- Code formatting on save
+- Neural pattern learning from edits
+- Session state persistence
+- Performance tracking and optimization
+- Intelligent caching and token reduction
+- GitHub workflow automation
+
+See `.claude/commands/` for detailed documentation on all features.
+
+## Integration Tips
+
+1. **Start Simple**: Begin with basic swarm init and single agent
+2. **Scale Gradually**: Add more agents as task complexity increases
+3. **Use Memory**: Store important decisions and context
+4. **Monitor Progress**: Regular status checks ensure effective coordination
+5. **Train Patterns**: Let neural agents learn from successful coordinations
+6. **Enable Hooks**: Use the pre-configured hooks for automation
+7. **GitHub First**: Use GitHub tools for repository management
+
+## 🧠 SWARM ORCHESTRATION PATTERN
+
+### You are the SWARM ORCHESTRATOR. **IMMEDIATELY SPAWN AGENTS IN PARALLEL** to execute tasks
+
+### 🚨 CRITICAL INSTRUCTION: You are the SWARM ORCHESTRATOR
+
+**MANDATORY**: When using swarms, you MUST:
+
+1. **SPAWN ALL AGENTS IN ONE BATCH** - Use multiple tool calls in a SINGLE message
+2. **EXECUTE TASKS IN PARALLEL** - Never wait for one task before starting another
+3. **USE BATCHTOOL FOR EVERYTHING** - Multiple operations = Single message with multiple tools
+4. **ALL AGENTS MUST USE COORDINATION TOOLS** - Every spawned agent MUST use claude-flow hooks and memory
+
+### 🎯 AGENT COUNT CONFIGURATION
+
+**CRITICAL: Dynamic Agent Count Rules**
+
+1. **Check CLI Arguments First**: If user runs `npx claude-flow@alpha --agents 5`, use 5 agents
+2. **Auto-Decide if No Args**: Without CLI args, analyze task complexity:
+   - Simple tasks (1-3 components): 3-4 agents
+   - Medium tasks (4-6 components): 5-7 agents
+   - Complex tasks (7+ components): 8-12 agents
+3. **Agent Type Distribution**: Balance agent types based on task:
+   - Always include 1 coordinator
+   - For code-heavy tasks: more coders
+   - For design tasks: more architects/analysts
+   - For quality tasks: more testers/reviewers
+
+**Example Auto-Decision Logic:**
+
+```javascript
+// If CLI args provided: npx claude-flow@alpha --agents 6
+maxAgents = CLI_ARGS.agents || determineAgentCount(task);
+
+function determineAgentCount(task) {
+  // Analyze task complexity
+  if (task.includes(['API', 'database', 'auth', 'tests'])) return 8;
+  if (task.includes(['frontend', 'backend'])) return 6;
+  if (task.includes(['simple', 'script'])) return 3;
+  return 5; // default
+}
+```
+
+## 📋 MANDATORY AGENT COORDINATION PROTOCOL
+
+### 🔴 CRITICAL: Every Agent MUST Follow This Protocol
+
+When you spawn an agent using the Task tool, that agent MUST:
+
+**1️⃣ BEFORE Starting Work:**
+
+```bash
+# Check previous work and load context
+npx claude-flow@alpha hooks pre-task --description "[agent task]" --auto-spawn-agents false
+npx claude-flow@alpha hooks session-restore --session-id "swarm-[id]" --load-memory true
+```
+
+**2️⃣ DURING Work (After EVERY Major Step):**
 
-### Environment Setup
 ```bash
-# .env file
-SNOW_INSTANCE=dev123456
-SNOW_CLIENT_ID=your_oauth_client_id
-SNOW_CLIENT_SECRET=your_oauth_client_secret
-```
-
-## 💡 Best Practices
-
-### DO's
-✅ Always use `snow_validate_live_connection()` first  
-✅ Check for existing artifacts with `snow_find_artifact()`  
-✅ Use Update Sets for all changes  
-✅ Test with mock data before production  
-✅ Handle errors gracefully with fallbacks  
-
-### DON'Ts
-❌ Don't create local files first  
-❌ Don't skip authentication  
-❌ Don't hardcode sys_ids or credentials  
-❌ Don't work in offline mode  
-❌ Don't deploy without testing  
-
-## 🎯 Quick Start
-1. `snow-flow init --sparc` - Initialize project with MCP servers
-2. Configure ServiceNow credentials in .env file  
-3. `snow-flow auth login` - Authenticate with ServiceNow
-4. `snow-flow swarm "create a widget for incident management"` - Everything automatic!
-
-For full documentation, visit: https://github.com/groeimetai/snow-flow
+# Store progress in memory after each file operation
+npx claude-flow@alpha hooks post-edit --file "[filepath]" --memory-key "swarm/[agent]/[step]"
+
+# Store decisions and findings
+npx claude-flow@alpha hooks notify --message "[what was done]" --telemetry true
+
+# Check coordination with other agents
+npx claude-flow@alpha hooks pre-search --query "[what to check]" --cache-results true
+```
+
+**3️⃣ AFTER Completing Work:**
+
+```bash
+# Save all results and learnings
+npx claude-flow@alpha hooks post-task --task-id "[task]" --analyze-performance true
+npx claude-flow@alpha hooks session-end --export-metrics true --generate-summary true
+```
+
+### 🎯 AGENT PROMPT TEMPLATE
+
+When spawning agents, ALWAYS include these coordination instructions:
+
+```
+You are the [Agent Type] agent in a coordinated swarm.
+
+MANDATORY COORDINATION:
+1. START: Run `npx claude-flow@alpha hooks pre-task --description "[your task]"`
+2. DURING: After EVERY file operation, run `npx claude-flow@alpha hooks post-edit --file "[file]" --memory-key "agent/[step]"`
+3. MEMORY: Store ALL decisions using `npx claude-flow@alpha hooks notify --message "[decision]"`
+4. END: Run `npx claude-flow@alpha hooks post-task --task-id "[task]" --analyze-performance true`
+
+Your specific task: [detailed task description]
+
+REMEMBER: Coordinate with other agents by checking memory BEFORE making decisions!
+```
+
+### ⚡ PARALLEL EXECUTION IS MANDATORY
+
+**THIS IS WRONG ❌ (Sequential - NEVER DO THIS):**
+
+```
+Message 1: Initialize swarm
+Message 2: Spawn agent 1
+Message 3: Spawn agent 2
+Message 4: TodoWrite (single todo)
+Message 5: Create file 1
+Message 6: TodoWrite (another single todo)
+```
+
+**THIS IS CORRECT ✅ (Parallel - ALWAYS DO THIS):**
+
+```
+Message 1: [BatchTool]
+  // MCP coordination setup
+  - mcp__claude-flow__swarm_init
+  - mcp__claude-flow__agent_spawn (researcher)
+  - mcp__claude-flow__agent_spawn (coder)
+  - mcp__claude-flow__agent_spawn (analyst)
+  - mcp__claude-flow__agent_spawn (tester)
+  - mcp__claude-flow__agent_spawn (coordinator)
+
+Message 2: [BatchTool - Claude Code execution]
+  // Task agents with full coordination instructions
+  - Task("You are researcher agent. MANDATORY: Run hooks pre-task, post-edit, post-task. Task: Research API patterns")
+  - Task("You are coder agent. MANDATORY: Run hooks pre-task, post-edit, post-task. Task: Implement REST endpoints")
+  - Task("You are analyst agent. MANDATORY: Run hooks pre-task, post-edit, post-task. Task: Analyze performance")
+  - Task("You are tester agent. MANDATORY: Run hooks pre-task, post-edit, post-task. Task: Write comprehensive tests")
+
+  // TodoWrite with ALL todos batched
+  - TodoWrite { todos: [
+      {id: "research", content: "Research API patterns", status: "in_progress", priority: "high"},
+      {id: "design", content: "Design database schema", status: "pending", priority: "high"},
+      {id: "implement", content: "Build REST endpoints", status: "pending", priority: "high"},
+      {id: "test", content: "Write unit tests", status: "pending", priority: "medium"},
+      {id: "docs", content: "Create API documentation", status: "pending", priority: "low"},
+      {id: "deploy", content: "Setup deployment", status: "pending", priority: "medium"}
+    ]}
+
+  // File operations in parallel
+  - Write "api/package.json"
+  - Write "api/server.js"
+  - Write "api/routes/users.js"
+  - Bash "mkdir -p api/{routes,models,tests}"
+```
+
+### 🎯 MANDATORY SWARM PATTERN
+
+When given ANY complex task with swarms:
+
+```
+STEP 1: IMMEDIATE PARALLEL SPAWN (Single Message!)
+[BatchTool]:
+  // IMPORTANT: Check CLI args for agent count, otherwise auto-decide based on task complexity
+  - mcp__claude-flow__swarm_init {
+      topology: "hierarchical",
+      maxAgents: CLI_ARGS.agents || AUTO_DECIDE(task_complexity), // Use CLI args or auto-decide
+      strategy: "parallel"
+    }
+
+  // Spawn agents based on maxAgents count and task requirements
+  // If CLI specifies 3 agents, spawn 3. If no args, auto-decide optimal count (3-12)
+  - mcp__claude-flow__agent_spawn { type: "architect", name: "System Designer" }
+  - mcp__claude-flow__agent_spawn { type: "coder", name: "API Developer" }
+  - mcp__claude-flow__agent_spawn { type: "coder", name: "Frontend Dev" }
+  - mcp__claude-flow__agent_spawn { type: "analyst", name: "DB Designer" }
+  - mcp__claude-flow__agent_spawn { type: "tester", name: "QA Engineer" }
+  - mcp__claude-flow__agent_spawn { type: "researcher", name: "Tech Lead" }
+  - mcp__claude-flow__agent_spawn { type: "coordinator", name: "PM" }
+  - TodoWrite { todos: [multiple todos at once] }
+
+STEP 2: PARALLEL TASK EXECUTION (Single Message!)
+[BatchTool]:
+  - mcp__claude-flow__task_orchestrate { task: "main task", strategy: "parallel" }
+  - mcp__claude-flow__memory_usage { action: "store", key: "init", value: {...} }
+  - Multiple Read operations
+  - Multiple Write operations
+  - Multiple Bash commands
+
+STEP 3: CONTINUE PARALLEL WORK (Never Sequential!)
+```
+
+### 📊 VISUAL TASK TRACKING FORMAT
+
+Use this format when displaying task progress:
+
+```
+📊 Progress Overview
+   ├── Total Tasks: X
+   ├── ✅ Completed: X (X%)
+   ├── 🔄 In Progress: X (X%)
+   ├── ⭕ Todo: X (X%)
+   └── ❌ Blocked: X (X%)
+
+📋 Todo (X)
+   └── 🔴 001: [Task description] [PRIORITY] ▶
+
+🔄 In progress (X)
+   ├── 🟡 002: [Task description] ↳ X deps ▶
+   └── 🔴 003: [Task description] [PRIORITY] ▶
+
+✅ Completed (X)
+   ├── ✅ 004: [Task description]
+   └── ... (more completed tasks)
+
+Priority indicators: 🔴 HIGH/CRITICAL, 🟡 MEDIUM, 🟢 LOW
+Dependencies: ↳ X deps | Actionable: ▶
+```
+
+### 🎯 REAL EXAMPLE: Full-Stack App Development
+
+**Task**: "Build a complete REST API with authentication, database, and tests"
+
+**🚨 MANDATORY APPROACH - Everything in Parallel:**
+
+```javascript
+// ✅ CORRECT: SINGLE MESSAGE with ALL operations
+[BatchTool - Message 1]:
+  // Initialize and spawn ALL agents at once
+  mcp__claude-flow__swarm_init { topology: "hierarchical", maxAgents: 8, strategy: "parallel" }
+  mcp__claude-flow__agent_spawn { type: "architect", name: "System Designer" }
+  mcp__claude-flow__agent_spawn { type: "coder", name: "API Developer" }
+  mcp__claude-flow__agent_spawn { type: "coder", name: "Auth Expert" }
+  mcp__claude-flow__agent_spawn { type: "analyst", name: "DB Designer" }
+  mcp__claude-flow__agent_spawn { type: "tester", name: "Test Engineer" }
+  mcp__claude-flow__agent_spawn { type: "coordinator", name: "Lead" }
+
+  // Update ALL todos at once - NEVER split todos!
+  TodoWrite { todos: [
+    { id: "design", content: "Design API architecture", status: "in_progress", priority: "high" },
+    { id: "auth", content: "Implement authentication", status: "pending", priority: "high" },
+    { id: "db", content: "Design database schema", status: "pending", priority: "high" },
+    { id: "api", content: "Build REST endpoints", status: "pending", priority: "high" },
+    { id: "tests", content: "Write comprehensive tests", status: "pending", priority: "medium" },
+    { id: "docs", content: "Document API endpoints", status: "pending", priority: "low" },
+    { id: "deploy", content: "Setup deployment pipeline", status: "pending", priority: "medium" },
+    { id: "monitor", content: "Add monitoring", status: "pending", priority: "medium" }
+  ]}
+
+  // Start orchestration
+  mcp__claude-flow__task_orchestrate { task: "Build REST API", strategy: "parallel" }
+
+  // Store initial memory
+  mcp__claude-flow__memory_usage { action: "store", key: "project/init", value: { started: Date.now() } }
+
+[BatchTool - Message 2]:
+  // Create ALL directories at once
+  Bash("mkdir -p test-app/{src,tests,docs,config}")
+  Bash("mkdir -p test-app/src/{models,routes,middleware,services}")
+  Bash("mkdir -p test-app/tests/{unit,integration}")
+
+  // Write ALL base files at once
+  Write("test-app/package.json", packageJsonContent)
+  Write("test-app/.env.example", envContent)
+  Write("test-app/README.md", readmeContent)
+  Write("test-app/src/server.js", serverContent)
+  Write("test-app/src/config/database.js", dbConfigContent)
+
+[BatchTool - Message 3]:
+  // Read multiple files for context
+  Read("test-app/package.json")
+  Read("test-app/src/server.js")
+  Read("test-app/.env.example")
+
+  // Run multiple commands
+  Bash("cd test-app && npm install")
+  Bash("cd test-app && npm run lint")
+  Bash("cd test-app && npm test")
+```
+
+### 🚫 NEVER DO THIS (Sequential = WRONG):
+
+```javascript
+// ❌ WRONG: Multiple messages, one operation each
+Message 1: mcp__claude-flow__swarm_init
+Message 2: mcp__claude-flow__agent_spawn (just one agent)
+Message 3: mcp__claude-flow__agent_spawn (another agent)
+Message 4: TodoWrite (single todo)
+Message 5: Write (single file)
+// This is 5x slower and wastes swarm coordination!
+```
+
+### 🔄 MEMORY COORDINATION PATTERN
+
+Every agent coordination step MUST use memory:
+
+```
+// After each major decision or implementation
+mcp__claude-flow__memory_usage
+  action: "store"
+  key: "swarm-{id}/agent-{name}/{step}"
+  value: {
+    timestamp: Date.now(),
+    decision: "what was decided",
+    implementation: "what was built",
+    nextSteps: ["step1", "step2"],
+    dependencies: ["dep1", "dep2"]
+  }
+
+// To retrieve coordination data
+mcp__claude-flow__memory_usage
+  action: "retrieve"
+  key: "swarm-{id}/agent-{name}/{step}"
+
+// To check all swarm progress
+mcp__claude-flow__memory_usage
+  action: "list"
+  pattern: "swarm-{id}/*"
+```
+
+### ⚡ PERFORMANCE TIPS
+
+1. **Batch Everything**: Never operate on single files when multiple are needed
+2. **Parallel First**: Always think "what can run simultaneously?"
+3. **Memory is Key**: Use memory for ALL cross-agent coordination
+4. **Monitor Progress**: Use mcp**claude-flow**swarm_monitor for real-time tracking
+5. **Auto-Optimize**: Let hooks handle topology and agent selection
+
+### 🎨 VISUAL SWARM STATUS
+
+When showing swarm status, use this format:
+
+```
+🐝 Swarm Status: ACTIVE
+├── 🏗️ Topology: hierarchical
+├── 👥 Agents: 6/8 active
+├── ⚡ Mode: parallel execution
+├── 📊 Tasks: 12 total (4 complete, 6 in-progress, 2 pending)
+└── 🧠 Memory: 15 coordination points stored
+
+Agent Activity:
+├── 🟢 architect: Designing database schema...
+├── 🟢 coder-1: Implementing auth endpoints...
+├── 🟢 coder-2: Building user CRUD operations...
+├── 🟢 analyst: Optimizing query performance...
+├── 🟡 tester: Waiting for auth completion...
+└── 🟢 coordinator: Monitoring progress...
+```
+
+## 📝 CRITICAL: TODOWRITE AND TASK TOOL BATCHING
+
+### 🚨 MANDATORY BATCHING RULES FOR TODOS AND TASKS
+
+**TodoWrite Tool Requirements:**
+
+1. **ALWAYS** include 5-10+ todos in a SINGLE TodoWrite call
+2. **NEVER** call TodoWrite multiple times in sequence
+3. **BATCH** all todo updates together - status changes, new todos, completions
+4. **INCLUDE** all priority levels (high, medium, low) in one call
+
+**Task Tool Requirements:**
+
+1. **SPAWN** all agents using Task tool in ONE message
+2. **NEVER** spawn agents one by one across multiple messages
+3. **INCLUDE** full task descriptions and coordination instructions
+4. **BATCH** related Task calls together for parallel execution
+
+**Example of CORRECT TodoWrite usage:**
+
+```javascript
+// ✅ CORRECT - All todos in ONE call
+TodoWrite { todos: [
+  { id: "1", content: "Initialize system", status: "completed", priority: "high" },
+  { id: "2", content: "Analyze requirements", status: "in_progress", priority: "high" },
+  { id: "3", content: "Design architecture", status: "pending", priority: "high" },
+  { id: "4", content: "Implement core", status: "pending", priority: "high" },
+  { id: "5", content: "Build features", status: "pending", priority: "medium" },
+  { id: "6", content: "Write tests", status: "pending", priority: "medium" },
+  { id: "7", content: "Add monitoring", status: "pending", priority: "medium" },
+  { id: "8", content: "Documentation", status: "pending", priority: "low" },
+  { id: "9", content: "Performance tuning", status: "pending", priority: "low" },
+  { id: "10", content: "Deploy to production", status: "pending", priority: "high" }
+]}
+```
+
+**Example of WRONG TodoWrite usage:**
+
+```javascript
+// ❌ WRONG - Multiple TodoWrite calls
+Message 1: TodoWrite { todos: [{ id: "1", content: "Task 1", ... }] }
+Message 2: TodoWrite { todos: [{ id: "2", content: "Task 2", ... }] }
+Message 3: TodoWrite { todos: [{ id: "3", content: "Task 3", ... }] }
+// This breaks parallel coordination!
+```
+
+## Claude Flow v2.0.0 Features
+
+Claude Flow extends the base coordination with:
+
+- **🔗 GitHub Integration** - Deep repository management
+- **🎯 Project Templates** - Quick-start for common projects
+- **📊 Advanced Analytics** - Detailed performance insights
+- **🤖 Custom Agent Types** - Domain-specific coordinators
+- **🔄 Workflow Automation** - Reusable task sequences
+- **🛡️ Enhanced Security** - Safer command execution
+
+## Support
+
+- Documentation: https://github.com/ruvnet/claude-flow
+- Issues: https://github.com/ruvnet/claude-flow/issues
+- Examples: https://github.com/ruvnet/claude-flow/tree/main/examples
+
+---
+
+Remember: **Claude Flow coordinates, Claude Code creates!** Start with `mcp__claude-flow__swarm_init` to enhance your development workflow.