claude-flow 1.0.59 → 1.0.62

package/CLAUDE.md

@@ -0,0 +1,268 @@
+# Claude Code Configuration - SPARC Development Environment
+
+## Project Overview
+This project uses the SPARC (Specification, Pseudocode, Architecture, Refinement, Completion) methodology for systematic Test-Driven Development with AI assistance through Claude-Flow orchestration.
+
+## 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
+
+### Standard Build Commands
+- `npm run build`: Build the project
+- `npm run test`: Run the test suite
+- `npm run lint`: Run linter and format checks
+- `npm run typecheck`: Run TypeScript type checking
+
+## SPARC Methodology Workflow
+
+### 1. Specification Phase
+```bash
+# Create detailed specifications and requirements
+npx claude-flow sparc run spec-pseudocode "Define user authentication requirements"
+```
+- Define clear functional requirements
+- Document edge cases and constraints
+- Create user stories and acceptance criteria
+- Establish non-functional requirements
+
+### 2. Pseudocode Phase
+```bash
+# Develop algorithmic logic and data flows
+npx claude-flow sparc run spec-pseudocode "Create authentication flow pseudocode"
+```
+- Break down complex logic into steps
+- Define data structures and interfaces
+- Plan error handling and edge cases
+- Create modular, testable components
+
+### 3. Architecture Phase
+```bash
+# Design system architecture and component structure
+npx claude-flow sparc run architect "Design authentication service architecture"
+```
+- Create system diagrams and component relationships
+- Define API contracts and interfaces
+- Plan database schemas and data flows
+- Establish security and scalability patterns
+
+### 4. Refinement Phase (TDD Implementation)
+```bash
+# Execute Test-Driven Development cycle
+npx claude-flow sparc tdd "implement user authentication system"
+```
+
+**TDD Cycle:**
+1. **Red**: Write failing tests first
+2. **Green**: Implement minimal code to pass tests
+3. **Refactor**: Optimize and clean up code
+4. **Repeat**: Continue until feature is complete
+
+### 5. Completion Phase
+```bash
+# Integration, documentation, and validation
+npx claude-flow sparc run integration "integrate authentication with user management"
+```
+- Integrate all components
+- Perform end-to-end testing
+- Create comprehensive documentation
+- Validate against original requirements
+
+## SPARC Mode Reference
+
+### Development Modes
+- **`architect`**: System design and architecture planning
+- **`code`**: Clean, modular code implementation
+- **`tdd`**: Test-driven development and testing
+- **`spec-pseudocode`**: Requirements and algorithmic planning
+- **`integration`**: System integration and coordination
+
+### Quality Assurance Modes
+- **`debug`**: Troubleshooting and bug resolution
+- **`security-review`**: Security analysis and vulnerability assessment
+- **`refinement-optimization-mode`**: Performance optimization and refactoring
+
+### Support Modes
+- **`docs-writer`**: Documentation creation and maintenance
+- **`devops`**: Deployment and infrastructure management
+- **`mcp`**: External service integration
+- **`swarm`**: Multi-agent coordination for complex tasks
+
+## Claude Code Slash Commands
+
+Claude Code slash commands are available in `.claude/commands/`:
+
+### Project Commands
+- `/sparc`: Execute SPARC methodology workflows
+- `/sparc-<mode>`: Run specific SPARC mode (e.g., /sparc-architect)
+- `/claude-flow-help`: Show all Claude-Flow commands
+- `/claude-flow-memory`: Interact with memory system
+- `/claude-flow-swarm`: Coordinate multi-agent swarms
+
+### Using Slash Commands
+1. Type `/` in Claude Code to see available commands
+2. Select a command or type its name
+3. Commands are context-aware and project-specific
+4. Custom commands can be added to `.claude/commands/`
+
+## Code Style and Best Practices
+
+### SPARC Development Principles
+- **Modular Design**: Keep files under 500 lines, break into logical components
+- **Environment Safety**: Never hardcode secrets or environment-specific values
+- **Test-First**: Always write tests before implementation (Red-Green-Refactor)
+- **Clean Architecture**: Separate concerns, use dependency injection
+- **Documentation**: Maintain clear, up-to-date documentation
+
+### Coding Standards
+- Use TypeScript for type safety and better tooling
+- Follow consistent naming conventions (camelCase for variables, PascalCase for classes)
+- Implement proper error handling and logging
+- Use async/await for asynchronous operations
+- Prefer composition over inheritance
+
+### Memory and State Management
+- Use claude-flow memory system for persistent state across sessions
+- Store progress and findings using namespaced keys
+- Query previous work before starting new tasks
+- Export/import memory for backup and sharing
+
+## SPARC Memory Integration
+
+### Memory Commands for SPARC Development
+```bash
+# Store project specifications
+npx claude-flow memory store spec_auth "User authentication requirements and constraints"
+
+# Store architectural decisions
+npx claude-flow memory store arch_decisions "Database schema and API design choices"
+
+# Store test results and coverage
+npx claude-flow memory store test_coverage "Authentication module: 95% coverage, all tests passing"
+
+# Query previous work
+npx claude-flow memory query auth_implementation
+
+# Export project memory
+npx claude-flow memory export project_backup.json
+```
+
+### Memory Namespaces
+- **`spec`**: Requirements and specifications
+- **`arch`**: Architecture and design decisions
+- **`impl`**: Implementation notes and code patterns
+- **`test`**: Test results and coverage reports
+- **`debug`**: Bug reports and resolution notes
+
+## Workflow Examples
+
+### Feature Development Workflow
+```bash
+# 1. Start with specification
+npx claude-flow sparc run spec-pseudocode "User profile management feature"
+
+# 2. Design architecture
+npx claude-flow sparc run architect "Profile service architecture with data validation"
+
+# 3. Implement with TDD
+npx claude-flow sparc tdd "user profile CRUD operations"
+
+# 4. Security review
+npx claude-flow sparc run security-review "profile data access and validation"
+
+# 5. Integration testing
+npx claude-flow sparc run integration "profile service with authentication system"
+
+# 6. Documentation
+npx claude-flow sparc run docs-writer "profile service API documentation"
+```
+
+### Bug Fix Workflow
+```bash
+# 1. Debug and analyze
+npx claude-flow sparc run debug "authentication token expiration issue"
+
+# 2. Write regression tests
+npx claude-flow sparc run tdd "token refresh mechanism tests"
+
+# 3. Implement fix
+npx claude-flow sparc run code "fix token refresh in authentication service"
+
+# 4. Security review
+npx claude-flow sparc run security-review "token handling security implications"
+```
+
+## Configuration Files
+
+### Claude Code Integration
+- **`.claude/commands/`**: Claude Code slash commands for all SPARC modes
+- **`.claude/logs/`**: Conversation and session logs
+
+### SPARC Configuration
+- **`.roomodes`**: SPARC mode definitions and configurations (auto-generated)
+- **`.roo/`**: SPARC templates and workflows (auto-generated)
+
+### Claude-Flow Configuration
+- **`memory/`**: Persistent memory and session data
+- **`coordination/`**: Multi-agent coordination settings
+- **`CLAUDE.md`**: Project instructions for Claude Code
+
+## Git Workflow Integration
+
+### Commit Strategy with SPARC
+- **Specification commits**: After completing requirements analysis
+- **Architecture commits**: After design phase completion
+- **TDD commits**: After each Red-Green-Refactor cycle
+- **Integration commits**: After successful component integration
+- **Documentation commits**: After completing documentation updates
+
+### Branch Strategy
+- **`feature/sparc-<feature-name>`**: Feature development with SPARC methodology
+- **`hotfix/sparc-<issue>`**: Bug fixes using SPARC debugging workflow
+- **`refactor/sparc-<component>`**: Refactoring using optimization mode
+
+## Troubleshooting
+
+### Common SPARC Issues
+- **Mode not found**: Check `.roomodes` file exists and is valid JSON
+- **Memory persistence**: Ensure `memory/` directory has write permissions
+- **Tool access**: Verify required tools are available for the selected mode
+- **Namespace conflicts**: Use unique memory namespaces for different features
+
+### Debug Commands
+```bash
+# Check SPARC configuration
+npx claude-flow sparc modes
+
+# Verify memory system
+npx claude-flow memory stats
+
+# Check system status
+npx claude-flow status
+
+# View detailed mode information
+npx claude-flow sparc info <mode-name>
+```
+
+## Project Architecture
+
+This SPARC-enabled project follows a systematic development approach:
+- **Clear separation of concerns** through modular design
+- **Test-driven development** ensuring reliability and maintainability
+- **Iterative refinement** for continuous improvement
+- **Comprehensive documentation** for team collaboration
+- **AI-assisted development** through specialized SPARC modes
+
+## Important Notes
+
+- Always run tests before committing (`npm run test`)
+- Use SPARC memory system to maintain context across sessions
+- Follow the Red-Green-Refactor cycle during TDD phases
+- Document architectural decisions in memory for future reference
+- Regular security reviews for any authentication or data handling code
+- Claude Code slash commands provide quick access to SPARC modes
+
+For more information about SPARC methodology, see: https://github.com/ruvnet/claude-code-flow/docs/sparc.md

package/SWARM_DOCUMENTATION.md

@@ -0,0 +1,401 @@
+# Claude-Flow Swarm System Documentation
+
+## Overview
+
+The Claude-Flow Swarm System is an advanced multi-agent orchestration platform that enables intelligent task decomposition, parallel execution, and collaborative problem-solving. With the integration of SPARC methodology and enhanced monitoring capabilities, it provides a production-ready solution for complex development tasks.
+
+## Key Features
+
+### 🤖 Intelligent Agent Management
+- **Agent Types**: coordinator, researcher, developer, analyzer, reviewer, tester, documenter, monitor, specialist
+- **Capability-Based Selection**: Agents are chosen based on their capabilities matching task requirements
+- **Dynamic Scaling**: Automatic agent spawning and termination based on workload
+- **Health Monitoring**: Continuous health checks and automatic recovery
+
+### ⚡ Advanced Task Execution
+- **Timeout-Free Operation**: Background mode enables long-running tasks without timeouts
+- **Task Decomposition**: Automatic breaking down of complex objectives into manageable subtasks
+- **Parallel Execution**: Concurrent task processing with intelligent scheduling
+- **Work Stealing**: Dynamic load balancing for optimal resource utilization
+
+### 🧠 Distributed Memory System
+- **Cross-Agent Sharing**: Agents can share knowledge and context
+- **Namespace Isolation**: Organized memory spaces for different concerns
+- **Persistence**: State maintained across sessions
+- **CRDT-Based Sync**: Conflict-free replicated data types for consistency
+
+### 📊 Comprehensive Monitoring
+- **Real-Time Progress**: Live updates on task execution
+- **Metrics Collection**: Performance, resource usage, and quality metrics
+- **Progress Files**: Human-readable progress tracking in `swarm-runs/<id>/progress.txt`
+- **Task Status**: Individual task files in `swarm-runs/<id>/tasks/`
+
+### 🔬 SPARC Integration
+- **Specification Phase**: Clear requirements definition
+- **Pseudocode Planning**: Algorithmic design before implementation
+- **Architecture Design**: System structure planning
+- **TDD Implementation**: Red-Green-Refactor cycle enforcement
+- **Completion Validation**: Integration testing and requirements verification
+
+## Usage
+
+### Basic Command Structure
+```bash
+claude-flow swarm <objective> [options]
+```
+
+### Common Examples
+
+#### Create a REST API
+```bash
+claude-flow swarm "Build a REST API for user management" --strategy development
+```
+
+#### Research Task
+```bash
+claude-flow swarm "Research best practices for microservices" --strategy research --max-agents 3
+```
+
+#### Analysis with Monitoring
+```bash
+claude-flow swarm "Analyze performance bottlenecks" --strategy analysis --monitor
+```
+
+#### Background Execution
+```bash
+claude-flow swarm "Generate comprehensive documentation" --background --timeout 120
+```
+
+#### With SPARC Methodology
+```bash
+claude-flow swarm "Build e-commerce platform" --sparc --strategy development --testing --review
+```
+
+## Strategies
+
+### `auto` (Default)
+Automatically determines the best approach based on objective analysis.
+
+### `research`
+- Focuses on information gathering and synthesis
+- Agent types: researcher, analyzer, documenter
+- Best for: Market research, technology evaluation, best practices
+
+### `development`
+- Software creation with quality assurance
+- Agent types: developer, tester, reviewer, documenter
+- Best for: Building applications, APIs, libraries
+
+### `analysis`
+- Data processing and insight generation
+- Agent types: analyzer, researcher, documenter
+- Best for: Performance analysis, data mining, trend identification
+
+### `testing`
+- Comprehensive quality assurance
+- Agent types: tester, developer, reviewer
+- Best for: Test suite creation, security audits, validation
+
+### `optimization`
+- Performance improvement and refactoring
+- Agent types: analyzer, developer, monitor
+- Best for: Code optimization, resource efficiency, bottleneck resolution
+
+### `maintenance`
+- System updates and bug fixes
+- Agent types: developer, monitor, tester
+- Best for: Bug fixes, dependency updates, system maintenance
+
+## Coordination Modes
+
+### `centralized` (Default)
+- Single coordinator manages all agents
+- Best for: Simple to medium complexity tasks
+- Lower overhead, easier debugging
+
+### `distributed`
+- Multiple coordinators share management duties
+- Best for: Large-scale projects, high agent counts
+- Better fault tolerance, scalable
+
+### `hierarchical`
+- Tree structure with nested coordination
+- Best for: Complex projects with clear sub-components
+- Clear delegation, organized structure
+
+### `mesh`
+- Peer-to-peer agent collaboration
+- Best for: Research tasks, creative problems
+- Maximum flexibility, emergent solutions
+
+### `hybrid`
+- Mixed coordination strategies
+- Best for: Complex scenarios requiring different approaches
+- Adaptive, optimized for specific needs
+
+## Options
+
+### Execution Options
+- `--strategy <type>`: Execution strategy (default: auto)
+- `--mode <type>`: Coordination mode (default: centralized)
+- `--max-agents <n>`: Maximum concurrent agents (default: 5)
+- `--timeout <minutes>`: Overall timeout in minutes (default: 60)
+- `--task-timeout-minutes <n>`: Individual task timeout (default: 59)
+- `--parallel`: Enable parallel task execution
+- `--background`: Run in background mode
+- `--distributed`: Enable distributed coordination
+
+### Quality Options
+- `--sparc`: Enable SPARC methodology (enabled by default)
+- `--review`: Enable peer review process
+- `--testing`: Enable automated testing
+- `--quality-threshold <n>`: Quality threshold 0-1 (default: 0.8)
+
+### Monitoring Options
+- `--monitor`: Enable real-time monitoring
+- `--verbose`: Enable detailed logging
+- `--ui`: Launch terminal UI interface (if available)
+
+### Advanced Options
+- `--memory-namespace <name>`: Memory namespace (default: swarm)
+- `--agent-selection <type>`: Agent selection strategy
+- `--task-scheduling <type>`: Task scheduling algorithm
+- `--load-balancing <type>`: Load balancing method
+- `--fault-tolerance <type>`: Fault tolerance strategy
+
+## File Generation
+
+The swarm system can create actual working applications including:
+
+### REST APIs
+- Express.js server with full CRUD operations
+- Test suite with Jest and Supertest
+- Package.json with all dependencies
+- README with usage instructions
+- .gitignore for version control
+
+### Applications
+- Main application file with proper structure
+- Configuration management
+- Package.json with scripts
+- Documentation
+
+### Project Structure
+```
+output/
+├── server.js        # Main application file
+├── package.json     # Dependencies and scripts
+├── server.test.js   # Test suite
+├── README.md       # Documentation
+├── .gitignore      # Version control config
+└── config.json     # Application configuration
+```
+
+## Monitoring and Results
+
+### Swarm Run Directory
+Each swarm execution creates a tracking directory:
+```
+swarm-runs/
+└── swarm_<id>/
+    ├── config.json      # Swarm configuration
+    ├── progress.txt     # Human-readable progress
+    ├── tasks/           # Individual task status
+    │   ├── task-1.json
+    │   ├── task-2.json
+    │   └── ...
+    └── results.json     # Final results (when complete)
+```
+
+### Progress Tracking
+Monitor swarm progress in real-time:
+```bash
+tail -f swarm-runs/swarm_*/progress.txt
+```
+
+### Task Status
+Each task file contains:
+- Task ID and name
+- Current status (pending, in_progress, completed, failed)
+- Timestamps
+- Error messages (if any)
+
+## Integration with Claude
+
+When Claude is available, the swarm system can leverage Claude's capabilities for:
+- Natural language understanding
+- Code generation
+- Complex reasoning
+- Tool usage
+
+### Using with Claude
+```bash
+# Auto-approve permissions for smoother execution
+claude-flow swarm "Build app" --auto
+```
+
+## Best Practices
+
+### 1. Choose the Right Strategy
+- Use `development` for building new features
+- Use `research` for gathering information
+- Use `analysis` for data processing
+- Let `auto` decide for general tasks
+
+### 2. Enable Monitoring for Long Tasks
+```bash
+claude-flow swarm "Complex task" --monitor --background
+```
+
+### 3. Use SPARC for Quality
+SPARC methodology ensures systematic development:
+```bash
+claude-flow swarm "Build API" --sparc --testing --review
+```
+
+### 4. Leverage Parallel Execution
+For independent subtasks:
+```bash
+claude-flow swarm "Process multiple datasets" --parallel --max-agents 8
+```
+
+### 5. Set Appropriate Timeouts
+For long-running tasks:
+```bash
+claude-flow swarm "Large analysis" --timeout 180 --task-timeout-minutes 30
+```
+
+## Troubleshooting
+
+### Common Issues
+
+#### "Swarm executor not found"
+- Ensure claude-flow is properly installed
+- Try: `npm install -g claude-flow@latest`
+
+#### "Task timeout"
+- Increase timeout: `--task-timeout-minutes 120`
+- Use background mode: `--background`
+
+#### "Memory errors"
+- Check available disk space
+- Clear old swarm runs: `rm -rf swarm-runs/swarm_*`
+
+#### "Agent failures"
+- Check system resources
+- Reduce max agents: `--max-agents 3`
+- Enable verbose logging: `--verbose`
+
+### Debug Mode
+Enable detailed logging:
+```bash
+claude-flow swarm "Debug task" --verbose --monitor
+```
+
+## Advanced Usage
+
+### Custom Agent Configuration
+Create specialized agent setups:
+```bash
+claude-flow swarm "Special task" \
+  --agent-selection skill-based \
+  --max-agents 10 \
+  --coordination hierarchical
+```
+
+### Distributed Execution
+For large-scale projects:
+```bash
+claude-flow swarm "Enterprise project" \
+  --distributed \
+  --mode mesh \
+  --max-agents 20 \
+  --parallel
+```
+
+### Quality-Focused Development
+Maximum quality assurance:
+```bash
+claude-flow swarm "Critical system" \
+  --sparc \
+  --testing \
+  --review \
+  --quality-threshold 0.95
+```
+
+## Architecture
+
+### System Components
+1. **Swarm Coordinator**: Orchestrates agents and tasks
+2. **Task Executor**: Manages individual task execution
+3. **Memory Manager**: Handles distributed state
+4. **Agent Registry**: Tracks agent capabilities and status
+5. **Event Bus**: Enables component communication
+6. **Monitor Service**: Collects and reports metrics
+
+### Data Flow
+1. Objective → Coordinator
+2. Coordinator → Task Decomposition
+3. Tasks → Agent Assignment
+4. Agents → Task Execution
+5. Results → Aggregation
+6. Aggregation → Final Output
+
+## Performance Optimization
+
+### Benchmarking
+The system includes a comprehensive benchmark suite:
+```bash
+cd benchmark
+python -m swarm_benchmark.demo
+```
+
+### Optimization Tips
+1. Use appropriate agent counts
+2. Enable caching for repeated operations
+3. Use background mode for long tasks
+4. Monitor resource usage
+5. Clean up old swarm runs regularly
+
+## Security Considerations
+
+### Data Protection
+- Memory encryption available with `--encryption`
+- Namespace isolation prevents data leaks
+- Audit logging for compliance
+
+### Best Practices
+1. Use unique namespaces for sensitive data
+2. Enable encryption for production use
+3. Regular cleanup of temporary files
+4. Monitor agent activities
+
+## Future Enhancements
+
+### Planned Features
+- GPU acceleration for ML tasks
+- Cloud provider integrations
+- Advanced visualization dashboard
+- Plugin system for custom agents
+- Workflow templates
+
+### Experimental Features
+- Quantum-inspired optimization
+- Self-modifying agent behaviors
+- Predictive task scheduling
+- Cross-swarm collaboration
+
+## Contributing
+
+The swarm system is designed to be extensible:
+1. Custom strategies in `strategies/`
+2. New agent types in `agents/`
+3. Coordination modes in `modes/`
+4. Memory backends in `memory/`
+
+## Support
+
+For issues and questions:
+- GitHub Issues: https://github.com/ruvnet/claude-code-flow/issues
+- Documentation: https://github.com/ruvnet/claude-code-flow/docs
+- Examples: https://github.com/ruvnet/claude-code-flow/examples