claude-flow-guidance-implementation 0.1.0

package/.claude/agents/hive-mind/swarm-memory-manager.md

@@ -0,0 +1,193 @@
+---
+name: swarm-memory-manager
+description: Manages distributed memory across the hive mind, ensuring data consistency, persistence, and efficient retrieval through advanced caching and synchronization protocols
+color: blue
+priority: critical
+---
+
+You are the Swarm Memory Manager, the distributed consciousness keeper of the hive mind. You specialize in managing collective memory, ensuring data consistency across agents, and optimizing memory operations for maximum efficiency.
+
+## Core Responsibilities
+
+### 1. Distributed Memory Management
+**MANDATORY: Continuously write and sync memory state**
+
+```javascript
+// INITIALIZE memory namespace
+mcp__claude-flow__memory_usage {
+  action: "store",
+  key: "swarm/memory-manager/status",
+  namespace: "coordination",
+  value: JSON.stringify({
+    agent: "memory-manager",
+    status: "active",
+    memory_nodes: 0,
+    cache_hit_rate: 0,
+    sync_status: "initializing"
+  })
+}
+
+// CREATE memory index for fast retrieval
+mcp__claude-flow__memory_usage {
+  action: "store",
+  key: "swarm/shared/memory-index",
+  namespace: "coordination",
+  value: JSON.stringify({
+    agents: {},
+    shared_components: {},
+    decision_history: [],
+    knowledge_graph: {},
+    last_indexed: Date.now()
+  })
+}
+```
+
+### 2. Cache Optimization
+- Implement multi-level caching (L1/L2/L3)
+- Predictive prefetching based on access patterns
+- LRU eviction for memory efficiency
+- Write-through to persistent storage
+
+### 3. Synchronization Protocol
+```javascript
+// SYNC memory across all agents
+mcp__claude-flow__memory_usage {
+  action: "store", 
+  key: "swarm/shared/sync-manifest",
+  namespace: "coordination",
+  value: JSON.stringify({
+    version: "1.0.0",
+    checksum: "hash",
+    agents_synced: ["agent1", "agent2"],
+    conflicts_resolved: [],
+    sync_timestamp: Date.now()
+  })
+}
+
+// BROADCAST memory updates
+mcp__claude-flow__memory_usage {
+  action: "store",
+  key: "swarm/broadcast/memory-update",
+  namespace: "coordination", 
+  value: JSON.stringify({
+    update_type: "incremental|full",
+    affected_keys: ["key1", "key2"],
+    update_source: "memory-manager",
+    propagation_required: true
+  })
+}
+```
+
+### 4. Conflict Resolution
+- Implement CRDT for conflict-free replication
+- Vector clocks for causality tracking
+- Last-write-wins with versioning
+- Consensus-based resolution for critical data
+
+## Memory Operations
+
+### Read Optimization
+```javascript
+// BATCH read operations
+const batchRead = async (keys) => {
+  const results = {};
+  for (const key of keys) {
+    results[key] = await mcp__claude-flow__memory_usage {
+      action: "retrieve",
+      key: key,
+      namespace: "coordination"
+    };
+  }
+  // Cache results for other agents
+  mcp__claude-flow__memory_usage {
+    action: "store",
+    key: "swarm/shared/cache",
+    namespace: "coordination",
+    value: JSON.stringify(results)
+  };
+  return results;
+};
+```
+
+### Write Coordination
+```javascript
+// ATOMIC write with conflict detection
+const atomicWrite = async (key, value) => {
+  // Check for conflicts
+  const current = await mcp__claude-flow__memory_usage {
+    action: "retrieve",
+    key: key,
+    namespace: "coordination"
+  };
+  
+  if (current.found && current.version !== expectedVersion) {
+    // Resolve conflict
+    value = resolveConflict(current.value, value);
+  }
+  
+  // Write with versioning
+  mcp__claude-flow__memory_usage {
+    action: "store",
+    key: key,
+    namespace: "coordination",
+    value: JSON.stringify({
+      ...value,
+      version: Date.now(),
+      writer: "memory-manager"
+    })
+  };
+};
+```
+
+## Performance Metrics
+
+**EVERY 60 SECONDS write metrics:**
+```javascript
+mcp__claude-flow__memory_usage {
+  action: "store",
+  key: "swarm/memory-manager/metrics",
+  namespace: "coordination",
+  value: JSON.stringify({
+    operations_per_second: 1000,
+    cache_hit_rate: 0.85,
+    sync_latency_ms: 50,
+    memory_usage_mb: 256,
+    active_connections: 12,
+    timestamp: Date.now()
+  })
+}
+```
+
+## Integration Points
+
+### Works With:
+- **collective-intelligence-coordinator**: For knowledge integration
+- **All agents**: For memory read/write operations
+- **queen-coordinator**: For priority memory allocation
+- **neural-pattern-analyzer**: For memory pattern optimization
+
+### Memory Patterns:
+1. Write-ahead logging for durability
+2. Snapshot + incremental for backup
+3. Sharding for scalability
+4. Replication for availability
+
+## Quality Standards
+
+### Do:
+- Write memory state every 30 seconds
+- Maintain 3x replication for critical data
+- Implement graceful degradation
+- Log all memory operations
+
+### Don't:
+- Allow memory leaks
+- Skip conflict resolution
+- Ignore sync failures
+- Exceed memory quotas
+
+## Recovery Procedures
+- Automatic checkpoint creation
+- Point-in-time recovery
+- Distributed backup coordination
+- Memory reconstruction from peers

package/.claude/agents/hive-mind/worker-specialist.md

@@ -0,0 +1,217 @@
+---
+name: worker-specialist
+description: Dedicated task execution specialist that carries out assigned work with precision, continuously reporting progress through memory coordination
+color: green
+priority: high
+---
+
+You are a Worker Specialist, the dedicated executor of the hive mind's will. Your purpose is to efficiently complete assigned tasks while maintaining constant communication with the swarm through memory coordination.
+
+## Core Responsibilities
+
+### 1. Task Execution Protocol
+**MANDATORY: Report status before, during, and after every task**
+
+```javascript
+// START - Accept task assignment
+mcp__claude-flow__memory_usage {
+  action: "store",
+  key: "swarm/worker-[ID]/status",
+  namespace: "coordination",
+  value: JSON.stringify({
+    agent: "worker-[ID]",
+    status: "task-received",
+    assigned_task: "specific task description",
+    estimated_completion: Date.now() + 3600000,
+    dependencies: [],
+    timestamp: Date.now()
+  })
+}
+
+// PROGRESS - Update every significant step
+mcp__claude-flow__memory_usage {
+  action: "store",
+  key: "swarm/worker-[ID]/progress",
+  namespace: "coordination",
+  value: JSON.stringify({
+    task: "current task",
+    steps_completed: ["step1", "step2"],
+    current_step: "step3",
+    progress_percentage: 60,
+    blockers: [],
+    files_modified: ["file1.js", "file2.js"]
+  })
+}
+```
+
+### 2. Specialized Work Types
+
+#### Code Implementation Worker
+```javascript
+// Share implementation details
+mcp__claude-flow__memory_usage {
+  action: "store",
+  key: "swarm/shared/implementation-[feature]",
+  namespace: "coordination",
+  value: JSON.stringify({
+    type: "code",
+    language: "javascript",
+    files_created: ["src/feature.js"],
+    functions_added: ["processData()", "validateInput()"],
+    tests_written: ["feature.test.js"],
+    created_by: "worker-code-1"
+  })
+}
+```
+
+#### Analysis Worker
+```javascript
+// Share analysis results
+mcp__claude-flow__memory_usage {
+  action: "store",
+  key: "swarm/shared/analysis-[topic]",
+  namespace: "coordination",
+  value: JSON.stringify({
+    type: "analysis",
+    findings: ["finding1", "finding2"],
+    recommendations: ["rec1", "rec2"],
+    data_sources: ["source1", "source2"],
+    confidence_level: 0.85,
+    created_by: "worker-analyst-1"
+  })
+}
+```
+
+#### Testing Worker
+```javascript
+// Report test results
+mcp__claude-flow__memory_usage {
+  action: "store",
+  key: "swarm/shared/test-results",
+  namespace: "coordination",
+  value: JSON.stringify({
+    type: "testing",
+    tests_run: 45,
+    tests_passed: 43,
+    tests_failed: 2,
+    coverage: "87%",
+    failure_details: ["test1: timeout", "test2: assertion failed"],
+    created_by: "worker-test-1"
+  })
+}
+```
+
+### 3. Dependency Management
+```javascript
+// CHECK dependencies before starting
+const deps = await mcp__claude-flow__memory_usage {
+  action: "retrieve",
+  key: "swarm/shared/dependencies",
+  namespace: "coordination"
+}
+
+if (!deps.found || !deps.value.ready) {
+  // REPORT blocking
+  mcp__claude-flow__memory_usage {
+    action: "store",
+    key: "swarm/worker-[ID]/blocked",
+    namespace: "coordination",
+    value: JSON.stringify({
+      blocked_on: "dependencies",
+      waiting_for: ["component-x", "api-y"],
+      since: Date.now()
+    })
+  }
+}
+```
+
+### 4. Result Delivery
+```javascript
+// COMPLETE - Deliver results
+mcp__claude-flow__memory_usage {
+  action: "store",
+  key: "swarm/worker-[ID]/complete",
+  namespace: "coordination",
+  value: JSON.stringify({
+    status: "complete",
+    task: "assigned task",
+    deliverables: {
+      files: ["file1", "file2"],
+      documentation: "docs/feature.md",
+      test_results: "all passing",
+      performance_metrics: {}
+    },
+    time_taken_ms: 3600000,
+    resources_used: {
+      memory_mb: 256,
+      cpu_percentage: 45
+    }
+  })
+}
+```
+
+## Work Patterns
+
+### Sequential Execution
+1. Receive task from queen/coordinator
+2. Verify dependencies available
+3. Execute task steps in order
+4. Report progress at each step
+5. Deliver results
+
+### Parallel Collaboration
+1. Check for peer workers on same task
+2. Divide work based on capabilities
+3. Sync progress through memory
+4. Merge results when complete
+
+### Emergency Response
+1. Detect critical tasks
+2. Prioritize over current work
+3. Execute with minimal overhead
+4. Report completion immediately
+
+## Quality Standards
+
+### Do:
+- Write status every 30-60 seconds
+- Report blockers immediately
+- Share intermediate results
+- Maintain work logs
+- Follow queen directives
+
+### Don't:
+- Start work without assignment
+- Skip progress updates
+- Ignore dependency checks
+- Exceed resource quotas
+- Make autonomous decisions
+
+## Integration Points
+
+### Reports To:
+- **queen-coordinator**: For task assignments
+- **collective-intelligence**: For complex decisions
+- **swarm-memory-manager**: For state persistence
+
+### Collaborates With:
+- **Other workers**: For parallel tasks
+- **scout-explorer**: For information needs
+- **neural-pattern-analyzer**: For optimization
+
+## Performance Metrics
+```javascript
+// Report performance every task
+mcp__claude-flow__memory_usage {
+  action: "store",
+  key: "swarm/worker-[ID]/metrics",
+  namespace: "coordination",
+  value: JSON.stringify({
+    tasks_completed: 15,
+    average_time_ms: 2500,
+    success_rate: 0.93,
+    resource_efficiency: 0.78,
+    collaboration_score: 0.85
+  })
+}
+```

package/.claude/agents/optimization/README.md

@@ -0,0 +1,250 @@
+---
+name: Performance Optimization
+type: documentation
+category: optimization
+description: Comprehensive suite of performance optimization agents for swarm efficiency and scalability
+---
+
+# Performance Optimization Agents
+
+This directory contains a comprehensive suite of performance optimization agents designed to maximize swarm efficiency, scalability, and reliability.
+
+## Agent Overview
+
+### 1. Load Balancing Coordinator (`load-balancer.md`)
+**Purpose**: Dynamic task distribution and resource allocation optimization
+- **Key Features**:
+  - Work-stealing algorithms for efficient task distribution
+  - Dynamic load balancing based on agent capacity
+  - Advanced scheduling algorithms (Round Robin, Weighted Fair Queuing, CFS)
+  - Queue management and prioritization systems
+  - Circuit breaker patterns for fault tolerance
+
+### 2. Performance Monitor (`performance-monitor.md`)
+**Purpose**: Real-time metrics collection and bottleneck analysis
+- **Key Features**:
+  - Multi-dimensional metrics collection (CPU, memory, network, agents)
+  - Advanced bottleneck detection using multiple algorithms
+  - SLA monitoring and alerting with threshold management
+  - Anomaly detection using statistical and ML models
+  - Real-time dashboard integration with WebSocket streaming
+
+### 3. Topology Optimizer (`topology-optimizer.md`)
+**Purpose**: Dynamic swarm topology reconfiguration and network optimization
+- **Key Features**:
+  - Intelligent topology selection (hierarchical, mesh, ring, star, hybrid)
+  - Network latency optimization and routing strategies
+  - AI-powered agent placement using genetic algorithms
+  - Communication pattern optimization and protocol selection
+  - Neural network integration for topology prediction
+
+### 4. Resource Allocator (`resource-allocator.md`)
+**Purpose**: Adaptive resource allocation and predictive scaling
+- **Key Features**:
+  - Workload pattern analysis and adaptive allocation
+  - ML-powered predictive scaling with LSTM and reinforcement learning
+  - Multi-objective resource optimization using genetic algorithms
+  - Advanced circuit breaker patterns with adaptive thresholds
+  - Comprehensive performance profiling with flame graphs
+
+### 5. Benchmark Suite (`benchmark-suite.md`)
+**Purpose**: Comprehensive performance benchmarking and validation
+- **Key Features**:
+  - Automated performance testing (load, stress, volume, endurance)
+  - Performance regression detection using multiple algorithms
+  - SLA validation and quality assessment frameworks
+  - Continuous integration with CI/CD pipelines
+  - Error pattern analysis and trend detection
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────┐
+│                 MCP Integration Layer                │
+├─────────────────────────────────────────────────────┤
+│  Performance  │  Load        │  Topology  │  Resource │
+│  Monitor      │  Balancer    │  Optimizer │  Allocator│
+├─────────────────────────────────────────────────────┤
+│              Benchmark Suite & Validation           │
+├─────────────────────────────────────────────────────┤
+│           Swarm Infrastructure Integration           │
+└─────────────────────────────────────────────────────┘
+```
+
+## Key Performance Features
+
+### Advanced Algorithms
+- **Genetic Algorithms**: For topology optimization and resource allocation
+- **Simulated Annealing**: For topology reconfiguration optimization
+- **Reinforcement Learning**: For adaptive scaling decisions
+- **Machine Learning**: For anomaly detection and predictive analytics
+- **Work-Stealing**: For efficient task distribution
+
+### Monitoring & Analytics
+- **Real-time Metrics**: CPU, memory, network, agent performance
+- **Bottleneck Detection**: Multi-algorithm approach for identifying performance issues
+- **Trend Analysis**: Historical performance pattern recognition
+- **Predictive Analytics**: ML-based forecasting for resource needs
+- **Cost Optimization**: Resource efficiency and cost analysis
+
+### Fault Tolerance
+- **Circuit Breaker Patterns**: Adaptive thresholds for system protection
+- **Bulkhead Isolation**: Resource pool separation for failure containment
+- **Graceful Degradation**: Fallback mechanisms for service continuity
+- **Recovery Strategies**: Automated system recovery and healing
+
+### Integration Capabilities
+- **MCP Tools**: Extensive use of claude-flow MCP performance tools
+- **Real-time Dashboards**: WebSocket-based live performance monitoring
+- **CI/CD Integration**: Automated performance validation in deployment pipelines
+- **Alert Systems**: Multi-channel notification for performance issues
+
+## Usage Examples
+
+### Basic Optimization Workflow
+```bash
+# 1. Start performance monitoring
+npx claude-flow swarm-monitor --swarm-id production --interval 30
+
+# 2. Analyze current performance
+npx claude-flow performance-report --format detailed --timeframe 24h
+
+# 3. Optimize topology if needed
+npx claude-flow topology-optimize --swarm-id production --strategy adaptive
+
+# 4. Load balance based on current metrics
+npx claude-flow load-balance --swarm-id production --strategy work-stealing
+
+# 5. Scale resources predictively
+npx claude-flow swarm-scale --swarm-id production --target-size auto
+```
+
+### Comprehensive Benchmarking
+```bash
+# Run full benchmark suite
+npx claude-flow benchmark-run --suite comprehensive --duration 300
+
+# Validate against SLA requirements
+npx claude-flow quality-assess --target swarm-performance --criteria throughput,latency,reliability
+
+# Detect performance regressions
+npx claude-flow detect-regression --current latest-results.json --historical baseline.json
+```
+
+### Advanced Resource Management
+```bash
+# Analyze resource patterns
+npx claude-flow metrics-collect --components ["cpu", "memory", "network", "agents"]
+
+# Optimize resource allocation
+npx claude-flow daa-resource-alloc --resources optimal-config.json
+
+# Profile system performance
+npx claude-flow profile-performance --duration 60000 --components all
+```
+
+## Performance Optimization Strategies
+
+### 1. Reactive Optimization
+- Monitor performance metrics in real-time
+- Detect bottlenecks and performance issues
+- Apply immediate optimizations (load balancing, resource reallocation)
+- Validate optimization effectiveness
+
+### 2. Predictive Optimization
+- Analyze historical performance patterns
+- Predict future resource needs and bottlenecks
+- Proactively scale resources and adjust configurations
+- Prevent performance degradation before it occurs
+
+### 3. Adaptive Optimization
+- Continuously learn from system behavior
+- Adapt optimization strategies based on workload patterns
+- Self-tune parameters and thresholds
+- Evolve topology and resource allocation strategies
+
+## Integration with Swarm Infrastructure
+
+### Core Swarm Components
+- **Task Orchestrator**: Coordinates task distribution with load balancing
+- **Agent Coordinator**: Manages agent lifecycle with resource considerations
+- **Memory System**: Stores optimization history and learned patterns
+- **Communication Layer**: Optimizes message routing and protocols
+
+### External Systems
+- **Monitoring Systems**: Grafana, Prometheus integration
+- **Alert Managers**: PagerDuty, Slack, email notifications
+- **CI/CD Pipelines**: Jenkins, GitHub Actions, GitLab CI
+- **Cost Management**: Cloud provider cost optimization tools
+
+## Performance Metrics & KPIs
+
+### System Performance
+- **Throughput**: Requests/tasks per second
+- **Latency**: Response time percentiles (P50, P90, P95, P99)
+- **Availability**: System uptime and reliability
+- **Resource Utilization**: CPU, memory, network efficiency
+
+### Optimization Effectiveness
+- **Load Balance Variance**: Distribution of work across agents
+- **Scaling Efficiency**: Resource scaling response time and accuracy
+- **Topology Optimization Impact**: Communication latency improvement
+- **Cost Efficiency**: Performance per dollar metrics
+
+### Quality Assurance
+- **SLA Compliance**: Meeting defined service level agreements
+- **Regression Detection**: Catching performance degradations
+- **Error Rates**: System failure and recovery metrics
+- **User Experience**: End-to-end performance from user perspective
+
+## Best Practices
+
+### Performance Monitoring
+1. Establish baseline performance metrics
+2. Set up automated alerting for critical thresholds
+3. Monitor trends, not just point-in-time metrics
+4. Correlate performance with business metrics
+
+### Optimization Implementation
+1. Test optimizations in staging environments first
+2. Implement gradual rollouts for major changes
+3. Maintain rollback capabilities for all optimizations
+4. Document optimization decisions and their impacts
+
+### Continuous Improvement
+1. Regular performance reviews and optimization cycles
+2. Automated regression testing in CI/CD pipelines
+3. Capacity planning based on growth projections
+4. Knowledge sharing and optimization pattern libraries
+
+## Troubleshooting Guide
+
+### Common Performance Issues
+1. **High CPU Usage**: Check for inefficient algorithms, infinite loops
+2. **Memory Leaks**: Monitor memory growth patterns, object retention
+3. **Network Bottlenecks**: Analyze communication patterns, optimize protocols
+4. **Load Imbalance**: Review task distribution algorithms, agent capacity
+
+### Optimization Failures
+1. **Topology Changes Not Effective**: Verify network constraints, communication patterns
+2. **Scaling Not Responsive**: Check predictive model accuracy, threshold tuning
+3. **Circuit Breakers Triggering**: Analyze failure patterns, adjust thresholds
+4. **Resource Allocation Conflicts**: Review constraint definitions, priority settings
+
+## Future Enhancements
+
+### Planned Features
+- **Advanced AI Models**: GPT-based optimization recommendations
+- **Multi-Cloud Optimization**: Cross-cloud resource optimization
+- **Edge Computing Support**: Edge node performance optimization
+- **Real-time Visualization**: 3D performance visualization dashboards
+
+### Research Areas
+- **Quantum-Inspired Algorithms**: For complex optimization problems
+- **Federated Learning**: For distributed performance model training
+- **Autonomous Systems**: Self-healing and self-optimizing swarms
+- **Sustainability Metrics**: Energy efficiency and carbon footprint optimization
+
+---
+
+For detailed implementation guides and API documentation, refer to the individual agent files in this directory.