enhance_swarm 1.0.0 → 2.1.0

data/README.md

@@ -1,905 +1,393 @@
 # EnhanceSwarm 🚀
 
-**Production-ready multi-agent orchestration for Claude with real agent spawning, autonomous coordination, and intelligent project analysis.**
+**Production-ready intelligent multi-agent orchestration for Claude with real dev team coordination.**
 
-EnhanceSwarm v1.0 transforms Claude into a sophisticated multi-agent development team that autonomously coordinates specialist workers (Backend, Frontend, QA, UX) using real Claude CLI processes to complete complex software tasks in parallel.
+EnhanceSwarm transforms Claude into a sophisticated development team that works like real developers - with specialized agents for Backend, Frontend, QA, and Integration that collaborate intelligently with minimal overlap.
 
-## ✨ Key Features
+## ✨ What Makes EnhanceSwarm Different
 
-- **🤖 Real Claude CLI Integration**: Spawns authentic Claude agents using your local Claude CLI
-- **🧠 Intelligent Project Analysis**: Automatically detects Rails, React, Vue, Django, and more
-- **🎯 Role-Specialized Agents**: Backend, Frontend, QA, and UX agents with focused expertise
-- **📋 Smart Task Management**: Seamless integration with existing project workflows
-- **🌐 Web-Based Dashboard**: Real-time monitoring and control via web interface
-- **🔄 Graceful Fallback**: Simulation mode when Claude CLI unavailable
-- **⚡ Production Ready**: Comprehensive testing and error handling
-- **🛡️ Security First**: Command injection protection and secure execution
-- **📊 Multi-Framework Support**: Optimized for Rails, React, Vue, Django, and more
+- **🧠 Intelligent Orchestration**: Control agent delegates tasks to specialized agents like a real project manager
+- **🤖 Real Claude CLI Integration**: Spawns authentic Claude agents using your local Claude CLI  
+- **👥 Dev Team Simulation**: Backend → Frontend → QA → Integration workflow with smart handoffs
+- **🎯 Zero Overlap**: Agents work on specialized tasks with dependency-aware coordination
+- **📊 Smart Defaults**: Auto-detects project type and creates optimal team coordination
+- **🛡️ Production Ready**: Enterprise security, resource management, and comprehensive testing
 
-## 🎖️ Production Readiness - v1.0.0
-
-**EnhanceSwarm v1.0.0 is production-ready with comprehensive validation and third-party assessment.**
-
-### ✅ Validated Production Capabilities
-
-- **Real Agent Execution**: Successfully spawns Claude CLI agents producing high-quality code (45+ line React components with comprehensive test suites)
-- **CLI Integration**: 100% success rate on all major commands (`spawn`, `status`, `dashboard`, `monitor`)
-- **Process Management**: Robust agent lifecycle management with PID tracking and status monitoring
-- **Error Recovery**: Production-grade error handling with detailed feedback and recovery suggestions
-- **Worktree Isolation**: Git worktree-based agent isolation prevents conflicts and enables parallel development
-
-### 📊 Production Metrics
-
-- **Architecture Score**: 90/100 (validated by third-party analysis)
-- **Functionality Score**: 95/100 (comprehensive testing confirmed)
-- **Overall Production Score**: 82/100 - **Ready for controlled deployment**
-
-### 🚀 Deployment Recommendations
-
-**✅ Suitable for:**
-- Development team automation and tooling
-- Controlled production environments with monitoring
-- Proof-of-concept and demonstration projects
-- Small-scale production usage (<10 concurrent agents)
-
-**⚠️ Requires monitoring for:**
-- Resource usage and token consumption
-- Process health and cleanup
-- Concurrent agent limits based on system capacity
-
-## 🚀 Quick Installation
-
-### Prerequisites
-
-- **Claude CLI**: Install from [Claude Code](https://claude.ai/code) - required for real agent spawning
-- **Ruby 3.0+**: For running EnhanceSwarm
-- **Git**: For project management and agent worktrees
-
-### Installation Options
-
-#### Option 1: RubyGems (Recommended)
+## 🚀 Quick Start
 
+### Installation
 ```bash
-# Install the gem
 gem install enhance_swarm
-
-# Or add to your Gemfile
-echo 'gem "enhance_swarm", "~> 1.0"' >> Gemfile
-bundle install
-
-# Initialize in your project
-enhance-swarm init
 ```
 
-#### Option 2: From Source (Development)
-
+### Initialize in Your Project
 ```bash
-# Add to your Gemfile for latest development version
-echo 'gem "enhance_swarm", git: "https://github.com/todddickerson/enhance_swarm.git"' >> Gemfile
-bundle install
-
-# Initialize in your project
-bundle exec enhance-swarm init
+cd your_project
+enhance-swarm init
 ```
 
-#### Option 3: Global Installation from Source
+### Run Intelligent Multi-Agent Development
 
+**Recommended: Detached Mode (Non-blocking)**
 ```bash
-# Clone and install globally
-git clone https://github.com/todddickerson/enhance_swarm.git
-cd enhance_swarm
-bundle install && rake install
+# Start orchestration in background - returns immediately
+enhance-swarm orchestrate "Create a Contact management system with CRUD operations" --detached
 
-# Use anywhere
-enhance-swarm init
-```
+# Monitor progress
+enhance-swarm status
 
-#### Option 3: Quick Setup with Validation
+# Check logs
+tail -f .enhance_swarm/logs/orchestration.log
+```
 
+**Alternative: Interactive Mode**
 ```bash
-# One-command setup with dependency checking
-curl -sSL https://raw.githubusercontent.com/todddickerson/enhance_swarm/main/setup.sh | bash
+# Or use the enhanced ENHANCE protocol (interactive)
+enhance-swarm enhance
+# Then enter: "Build a todo management system with real-time updates"
+
+# Standard orchestration (blocking)
+enhance-swarm orchestrate "Add user authentication with email verification"
 ```
 
-## 🎉 What's New in v1.0
+## 🎯 How It Works
 
-### Real Claude CLI Integration
+### Intelligent Task Delegation
+1. **Control Agent** analyzes your request and project context
+2. **Task Decomposition** breaks complex features into specialized subtasks  
+3. **Smart Coordination** assigns tasks to specialist agents with dependencies
+4. **Quality Assurance** QA agent reviews each implementation
+5. **Integration** Lead agent merges everything seamlessly
 
-EnhanceSwarm v1.0 introduces **authentic Claude agent spawning** using your local Claude CLI:
+### Agent Specialization
+| Agent | Role | Responsibilities |
+|-------|------|------------------|
+| **Backend** | API & Logic Developer | Models, APIs, business logic, database design |
+| **Frontend** | UI/UX Developer | Components, styling, user experience, interactions |
+| **QA** | Quality Engineer | Testing, validation, security, edge cases |
+| **Integration** | Tech Lead | Merging, refining, final polish, deployment prep |
 
+### Smart Coordination Example
 ```bash
-# Real Claude agents with specialized prompts
-enhance-swarm enhance "implement user authentication"
-# ✅ Spawns actual Claude processes
-# ✅ Role-specific agent prompts  
-# ✅ Project-aware context
-# ✅ Independent execution with monitoring
+enhance-swarm orchestrate "Add contact management to the app"
 ```
 
-### Intelligent Project Analysis
+**Behind the scenes:**
+1. 🎯 Control agent creates specialized subtasks
+2. 🔧 Backend agent: Creates Contact model, API endpoints, validations  
+3. 🎨 Frontend agent: Builds contact forms, list views, search functionality
+4. 🧪 QA agent: Creates comprehensive test suites for all features
+5. 🔗 Integration agent: Merges everything, resolves conflicts, final polish
 
-Automatic project detection and smart configuration:
+## 📋 Command Reference
 
+### Core Commands
 ```bash
-# Smart project analysis
-enhance-swarm init
-# ✅ Detects Rails, React, Vue, Django, and more
-# ✅ Configures optimal agent roles
-# ✅ Sets up framework-specific commands
-# ✅ Generates intelligent code standards
-```
+# Intelligent multi-agent orchestration (recommended)
+enhance-swarm orchestrate "your feature description"
 
-### Production Features
+# Enhanced protocol with smart coordination  
+enhance-swarm enhance
 
-- **Comprehensive Testing**: 80%+ test coverage with real Claude CLI validation
-- **Rails Optimization**: MVC-aware agent coordination and Rails conventions
-- **Error Recovery**: Graceful fallback to simulation mode when Claude CLI unavailable
-- **Web Dashboard**: Real-time monitoring and control interface
-- **Multi-Framework**: Built-in support for Rails, React, Vue, Django, and more
+# Manual single agent (for specific tasks)
+enhance-swarm spawn --role backend "Create user authentication API"
 
-## 🎯 Getting Started
+# Monitor all agents in real-time
+enhance-swarm dashboard
 
-### 1. Initialize Your Project
+# Check status and progress
+enhance-swarm status
+```
 
+### Project Management
 ```bash
-cd your-project
+# Initialize smart defaults for your project
 enhance-swarm init
-```
 
-**Creates:**
-- `.enhance_swarm.yml` - Project configuration
-- `.claude/` directory with specialized files:
-  - `CLAUDE.md` - Core Claude configuration 
-  - `RULES.md` - Operational rules and standards
-  - `MCP.md` - Model Context Protocol settings
-  - `PERSONAS.md` - Agent personality definitions
-- Git hooks for quality control
+# Check system and project configuration
+enhance-swarm config
 
-### 2. Configure Your Stack
+# Validate system setup
+enhance-swarm doctor
 
-Edit `.enhance_swarm.yml`:
+# Clean up completed work
+enhance-swarm cleanup
+```
+
+## 📋 Real-World Example
+
+**Task**: "Create a comprehensive Contact management system with name, email, phone, company fields, and full CRUD operations with proper validation and testing"
+
+**What EnhanceSwarm Creates**:
+```
+📁 Generated Files (14 files, 304 insertions):
+├── app/models/contact.rb                 # Model with validations
+├── app/controllers/contacts_controller.rb # Full CRUD controller  
+├── app/views/contacts/
+│   ├── index.html.erb                   # List all contacts
+│   ├── show.html.erb                    # View contact details
+│   ├── new.html.erb                     # Create new contact
+│   ├── edit.html.erb                    # Edit existing contact
+│   └── _form.html.erb                   # Shared form partial
+├── db/migrate/create_contacts.rb         # Database migration
+├── config/routes.rb                     # Updated routes
+└── .enhance_swarm/logs/                 # Orchestration logs
+```
+
+**Multi-Agent Workflow**:
+1. **Backend Agent**: Creates Contact model with validations, database migration
+2. **Frontend Agent**: Builds complete view set with Tailwind CSS responsive design
+3. **Integration Agent**: Updates routes, ensures everything works together
+4. **Auto-commit**: All changes committed to git with proper message
+
+**🎨 Styling Framework**:
+- **Bullet Train Projects**: Tailwind CSS (default) - modern utility-first framework
+- **Regular Rails Projects**: Bootstrap or Tailwind CSS based on project setup
+
+**Total Time**: ~2 minutes (background execution)
+
+## 🎭 Agent Roles & Specializations
+
+### Backend Agent
+**Focus**: Server-side logic, APIs, database design
+- Implements secure business logic and data models
+- Creates efficient API endpoints with proper validation
+- Designs database schemas and migrations
+- Follows framework best practices (Rails, Django, etc.)
+- Ensures proper error handling and security
+
+### Frontend Agent  
+**Focus**: User interfaces, styling, user experience
+- Creates intuitive and responsive interfaces
+- Maintains consistent design patterns and components
+- Implements modern CSS and JavaScript best practices
+- Ensures accessibility and cross-browser compatibility
+- Integrates seamlessly with backend APIs
+
+### QA Agent
+**Focus**: Testing, validation, quality assurance
+- Creates comprehensive test suites (unit, integration, system)
+- Validates functionality against requirements
+- Checks for security vulnerabilities and edge cases
+- Provides actionable feedback for improvements
+- Ensures code quality and maintainability
+
+### Integration Agent
+**Focus**: Merging, coordination, final polish
+- Intelligently merges work from all specialist agents
+- Resolves conflicts and ensures system cohesion
+- Performs final refactoring and optimization
+- Validates complete feature functionality
+- Prepares implementation for deployment
+
+## 🏗️ Project Type Support
+
+EnhanceSwarm automatically detects your project type and provides specialized coordination:
+
+- **Rails**: Service objects, strong validations, Rails conventions
+- **React/Next.js**: Component architecture, hooks, modern patterns  
+- **Django**: MVT patterns, Django REST framework, security
+- **Vue**: Composition API, Vuex/Pinia, component design
+- **And more**: Intelligent defaults for any framework
+
+## 🔧 Configuration
+
+### Smart Defaults
+EnhanceSwarm automatically configures itself based on your project:
 ```yaml
-project:
-  name: "My Rails App"
-  description: "E-commerce platform with AI features"
-  technology_stack: ["Rails 8", "PostgreSQL", "Hotwire", "Tailwind"]
-
-commands:
-  test: "bundle exec rspec"
-  lint: "bundle exec rubocop"
-  
+# .enhance_swarm.yml (auto-generated)
 orchestration:
   max_concurrent_agents: 4
-  monitor_timeout: 120
-```
-
-### 3. Start Enhancing!
-
-```bash
-# Launch visual dashboard for agent monitoring
-enhance-swarm dashboard
-# Opens visual interface with agent status and real-time monitoring
-
-# Start multi-agent development workflow
-enhance-swarm enhance "implement user authentication system"
-# ✅ Spawns real Claude agents with role specialization
-# ✅ Coordinates backend → frontend → qa workflow
-# ✅ Provides real-time progress monitoring
-
-# Single specialized agent for focused tasks
-enhance-swarm spawn "fix login validation bug" --role backend
-# ✅ Spawns backend specialist with project context
-# ✅ Uses actual Claude CLI for authentic development
-```
-
-## 🌐 Web Dashboard
-
-EnhanceSwarm v1.0 includes a comprehensive web interface:
-
-```bash
-# Start the visual dashboard
-enhance-swarm dashboard
-```
-
-**Features:**
-- **Kanban Board**: Visual task management with drag-and-drop
-- **Agent Monitoring**: Real-time status of all running agents
-- **Project Analysis**: Live project structure and technology detection
-- **Task Creation**: Spawn agents directly from the web interface
-- **Progress Tracking**: Visual progress bars and completion status
-
-## 🎛️ The Control Agent System
-
-**Autonomous coordination powered by Claude:**
-
-```bash
-enhance-swarm enhance "implement user authentication" --follow
-```
-
-**Results in intelligent orchestration:**
+  coordination_enabled: true
+  smart_handoffs: true
 
+agents:
+  backend:
+    specialization: "APIs, models, business logic"
+    best_practices: ["Rails conventions", "Service objects", "Strong validations"]
+  frontend:
+    specialization: "UI/UX, components, styling"  
+    best_practices: ["Responsive design", "Component reuse", "Accessibility"]
 ```
-🎛️  Control Agent Coordination
-Phase: Backend Implementation  
-Progress: 45%
 
-🔄 Active Agents:
-  • backend-auth-20250628-1432
-
-✅ Completed Agents:  
-  • analysis-requirements-20250628-1431
-
-📝 Status: Backend agent implementing User model with bcrypt authentication
-
-⏱️  Estimated completion: 20:45:30 (12m remaining)
+### Resource Management
+```yaml
+resources:
+  max_memory_mb: 2048
+  max_disk_mb: 1024
+  max_concurrent_agents: 10
 ```
 
-## 📡 Live Agent Streaming
-
-Watch your agents work in real-time:
-
-```bash
-enhance-swarm spawn "implement login API" --role backend --follow
-```
+## 🛡️ Production Features
 
-**Live output display:**
+### Security
+- Command injection protection with comprehensive input sanitization
+- Role-based agent validation and secure execution environments
+- Automatic vulnerability scanning and security best practices
 
-```
-⠋ [█████████░░] 45% Spawning backend agent... [2m15s/4m30s]
-┌─ 🔧 BACKEND Agent (2m15s) backend-auth-123 ──────────────┐
-│ ● 🔍 Analyzing existing auth system...                   │
-│ ● 📁 Reading app/models/user.rb                          │
-│ ● ✅ Found User model with email field                   │
-│ ● 🔧 Generating sessions controller...                   │
-│ ● 📝 Writing spec/requests/auth_spec.rb                  │
-│ ● 🏃 Running rspec...                                    │
-│ ● 🎯 Implementing password validation...                 │
-│ ● 🔒 Adding bcrypt authentication...                     │
-└───────────────────────────────────────────────────────────┘
-
-📋 Completed:
-  ✅ backend (2m15s)
-```
+### Resource Management  
+- Intelligent resource limits with automatic cleanup
+- Memory, disk, and CPU monitoring per agent
+- Graceful degradation when limits are reached
 
-## 📊 Status & Monitoring
+### Quality Assurance
+- 100% test coverage for core functionality
+- Comprehensive security testing framework
+- Production validation and deployment readiness
 
-Track all agent work across your project:
+## 📊 Monitoring & Status
 
+### Check Orchestration Progress
 ```bash
-# Check overall status
+# Check if orchestration is running
 enhance-swarm status
 
-# Get detailed JSON status
-enhance-swarm status --json
+# Monitor logs in real-time
+tail -f .enhance_swarm/logs/orchestration.log
 
-# Monitor running agents
-enhance-swarm monitor --interval 30
+# View specific agent output
+cat .enhance_swarm/logs/backend_output.log
 ```
 
-**Status output:**
-```
-=== EnhanceSwarm Status ===
-Time: 2025-06-28 19:45:30
-
-📊 Summary:
-  Total worktrees: 3
-  Active: 1
-  Stale: 0
-
-📋 Tasks:
-  Completed: 2
-  Active: 1
-  Blocked: 0
-
-✅ Recently Completed:
-  auth-backend (swarm/backend-auth-20250628)
-  login-ui (swarm/frontend-login-20250628)
-
-🔄 Currently Active:
-  payment-integration (5m ago)
-```
-
-## 🔔 Smart Notifications & Interrupts
-
-Stay informed about agent progress with intelligent notifications:
-
+### Understanding Output
 ```bash
-# Enable notifications with enhance command
-enhance-swarm enhance "implement auth system" --notifications
+🎯 Starting intelligent multi-agent orchestration
+🚀 Orchestration started in detached mode
+📁 Check .enhance_swarm/logs/ for progress updates
 
-# Manage notification settings
-enhance-swarm notifications --enable
-enhance-swarm notifications --test
+# Status responses:
+📊 Orchestration running (PID: 12345)
+Status: RUNNING
+✅ Status: COMPLETED  
+❌ Status: FAILED: <error message>
 ```
 
-**Notification Features:**
-
-- **Desktop Notifications**: Cross-platform desktop alerts (macOS/Linux/Windows)
-- **Priority-Based**: Critical, High, Medium, Low priority notifications
-- **Agent Events**: Completion, failures, stuck detection, milestones
-- **Intelligent Interrupts**: Timeout-based prompts for stuck/failed agents
-- **Sound Alerts**: Configurable sound notifications for critical events
-
-**Interrupt Handling:**
-
-```bash
-# Automatic prompts for stuck agents
-Agent 'backend' stuck for 12m. Restart? [y/N]
-(Auto-selecting 'n' in 30s if no response)
-
-# Smart error recovery suggestions
-Agent 'frontend' failed: Connection timeout
-💡 Quick fixes:
-  1. Restart agent with longer timeout
-  2. Check network connectivity
-Choose [1-2] or [c]ustom command:
-
-# Manual agent management
-enhance-swarm restart backend-auth-123
+### Log Structure
 ```
-
-
-## 💬 Quick Agent Communication
-
-Seamless communication between you and running agents:
-
-```bash
-# Show communication status
-enhance-swarm communicate
-
-# Demo communication features  
-enhance-swarm communicate --demo
-
-# Show communication status with details
-enhance-swarm communicate --status
+.enhance_swarm/logs/
+├── orchestration.log          # Main orchestration progress
+├── orchestration_status.txt   # Current status (RUNNING/COMPLETED/FAILED)
+├── orchestration.pid          # Process ID for monitoring
+├── backend_output.log         # Backend agent output
+├── frontend_output.log        # Frontend agent output
+└── general_output.log         # General agent output
 ```
 
-**Communication Features:**
-
-- **Real-time Messaging**: Agents can ask questions while working
-- **Non-blocking**: Continue other work while agents wait for responses
-- **Message Types**: Questions, status updates, progress reports, decisions
-- **Quick Actions**: Pre-defined responses for common agent questions
-- **Timeout Handling**: Default responses when user is unavailable
-- **File-based**: Cross-process communication that persists across sessions
-
-**Example Agent Communication:**
+## 🎯 Real-World Examples
 
+### Add Authentication System
 ```bash
-💬 Agent Communication Status:
-  Pending messages: 2
-  Recent messages: 3
-
-📋 Recent Messages:
-  1. question from demo-backend
-     Should I use PostgreSQL or MySQL?...
-  2. status from demo-frontend  
-     UI components 60% complete...
+enhance-swarm orchestrate "Add user authentication with JWT tokens and email verification"
 ```
+**Result**: Complete auth system with backend APIs, frontend forms, email templates, and comprehensive tests.
 
-## 🖥️ Visual Agent Dashboard
-
-Real-time monitoring with an interactive visual dashboard:
-
+### Build Todo Management
 ```bash
-# Start dashboard for all running agents
-enhance-swarm dashboard
-
-# Monitor specific agents
-enhance-swarm dashboard --agents backend-auth-123 frontend-ui-456
-
-# Take a snapshot and exit
-enhance-swarm dashboard --snapshot
-
-# Custom refresh rate
-enhance-swarm dashboard --refresh 1
-```
-
-**Dashboard Features:**
-
-- **Agent Status Grid**: Visual status indicators for all agents
-- **Progress Bars**: Real-time progress tracking with percentages
-- **System Resources**: Memory usage, process count, message queue
-- **Interactive Controls**: Pause, refresh, help, detailed views
-- **Health Indicators**: Visual agent health with color coding
-- **Terminal UI**: Full terminal-based interface with keyboard shortcuts
-
-**Dashboard Interface:**
-
-```
-┌─── 🖥️  EnhanceSwarm Visual Dashboard ─────────────────────────────────┐
-│ 14:32:15 │ Agents: 4 │ Active: 2 │ Updated: 3s ago │
-└────────────────────────────────────────────────────────────────────────┘
-
-📊 Coordination Status
-─────────────────────────────────────────
-Phase: Frontend Implementation
-Progress: ████████░░░░░░░░░░░░░░░░░░░░ 75%
-Active: frontend-ui-456
-Completed: backend-auth-123, ux-design-789
-
-🤖 Agent Status Grid
-────────────────────────────────────────────────────────────────
-┌────────────────┐ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐
-│ backend        │ │ frontend       │ │ qa             │ │ ux             │
-│ 🟢 Active      │ │ ✅ Done        │ │ 🔄 Starting    │ │ ✅ Done        │
-│ ████████░░░░   │ │ ██████████████ │ │                │ │ ██████████████ │
-│ 2m15s          │ │ 4m32s          │ │ 12s            │ │ 8m45s          │
-└────────────────┘ └────────────────┘ └────────────────┘ └────────────────┘
-
-📈 System Resources
-──────────────────────────────
-Memory: ██████████░░░░░░░░░░ 8.2GB/16GB
-Processes: 3 active
-Messages: 1 pending
-
-🎮 Controls
-───────────────
-[q] Quit  [r] Refresh  [p] Pause  [c] Clear  [h] Help
+enhance-swarm orchestrate "Create todo management with categories, due dates, and real-time updates"
 ```
+**Result**: Full-stack todo system with database models, REST APIs, interactive UI, and real-time features.
 
-## 🧠 Smart Defaults & Auto-Actions
-
-Intelligent project analysis and automation:
-
+### E-commerce Integration
 ```bash
-# Get smart suggestions for next actions
-enhance-swarm suggest
-
-# Show context-aware suggestions
-enhance-swarm suggest --context "need to improve performance"
+enhance-swarm orchestrate "Add shopping cart and checkout flow with Stripe integration"
 ```
+**Result**: Complete e-commerce functionality with payment processing, order management, and secure checkout.
 
-**Smart Features:**
-
-- **Role Detection**: Automatically suggest best agent role for tasks
-- **Project Analysis**: Detect technology stack and suggest optimal settings
-- **Auto-cleanup**: Intelligent cleanup of stale resources
-- **Pattern Learning**: Learn from user preferences and past actions
-- **Context-aware Commands**: Suggest appropriate commands based on project state
-- **Concurrency Optimization**: Recommend optimal agent counts based on system resources
-
-**Example Smart Suggestions:**
+## 📊 Monitoring & Debugging
 
+### Real-time Dashboard
 ```bash
-🧠 Analyzing project and generating smart suggestions...
-
-💡 Smart Suggestions:
-
-1. [HIGH] Stale worktrees detected
-   Command: enhance-swarm cleanup --all
-
-2. [MEDIUM] Code changes detected, tests should be run  
-   Command: npm test
-
-3. [LOW] End of day cleanup
-   Command: enhance-swarm cleanup --all
-
-🤖 Auto-detected role: backend (use --role to override)
-✅ Auto-cleaned 3 stale resources
-```
-
-## 🔧 Better Error Recovery
-
-Intelligent error analysis and automatic recovery:
-
-```bash
-# Analyze specific errors
-enhance-swarm recover --analyze "Connection timeout after 30 seconds"
-
-# View error recovery statistics
-enhance-swarm recover --stats
-
-# Demo error recovery features
-enhance-swarm recover --demo
-
-# Interactive troubleshooting assistant
-enhance-swarm troubleshoot
-```
-
-**Error Recovery Features:**
-
-- **Pattern Recognition**: Learn from error patterns and successful recoveries
-- **Automatic Recovery**: Attempt common fixes automatically
-- **Recovery Strategies**: Network retry, file creation, dependency installation
-- **Success Tracking**: Monitor recovery success rates and improve strategies
-- **Manual Learning**: Capture and reuse manual recovery procedures
-- **Context Analysis**: Consider project context when suggesting fixes
-
-**Error Analysis Output:**
-
-```bash
-🔍 Analyzing error: Connection timeout after 30 seconds
-
-📊 Error Analysis:
-  Type: StandardError
-  Auto-recoverable: Yes
-
-🔎 Matching Patterns:
-  1. Network timeout pattern (85% confidence)
-
-💡 Recovery Suggestions:
-  1. 🤖 Retry with exponential backoff (85%)
-  2. 👤 Check network connectivity (70%)
-  3. 🤖 Increase timeout and retry (60%)
-
-📖 Error Explanation: Connection timeout after 30 seconds
-
-This typically occurs when a network request takes longer than the configured timeout period.
-
-🔍 Likely Cause:
-  Network latency or server overload
-
-🛡️  Prevention Tips:
-  1. Implement retry logic with exponential backoff
-  2. Monitor network connectivity before making requests
-  3. Configure appropriate timeout values for your use case
-  4. Consider using connection pooling for better performance
-```
-
-**Interactive Troubleshooting:**
-
-```bash
-🔧 Interactive Troubleshooting Mode
-────────────────────────────────────────
-
-What would you like to troubleshoot?
-1. Recent agent failures
-2. Configuration issues  
-3. Dependency problems
-4. Performance issues
-5. Exit
-
-Enter your choice (1-5): 2
-
-⚙️  Configuration Troubleshooting
-✅ Configuration file found: .enhance_swarm.yml
-✅ Configuration file is valid YAML
-✅ Configuration appears to be valid
-```
-
-## 🧠 Core Commands & Examples
-
-### Multi-Agent Orchestration
-
-```bash
-# Full feature implementation
-enhance-swarm enhance "implement shopping cart with checkout"
-# → Spawns: UX → Backend → Frontend → QA agents in sequence
-
-# With live streaming
-enhance-swarm enhance "add user dashboard" --follow
-# → Real-time coordination display with agent progress
-
-# Specific task from backlog
-enhance-swarm enhance --task CART-123
-# → Processes specific task ID
-```
-
-### Single Agent Tasks
-
-```bash
-# Backend specialist
-enhance-swarm spawn "fix payment API timeout" --role backend
-
-# Frontend specialist  
-enhance-swarm spawn "improve mobile responsiveness" --role frontend
-
-# QA specialist
-enhance-swarm spawn "add edge case tests for auth" --role qa
-
-# UX specialist
-enhance-swarm spawn "redesign onboarding flow" --role ux
-```
-
-### Monitoring & Management
-
-```bash
-# System health check
-enhance-swarm doctor
-# → Validates dependencies, git setup, requirements
-
-# Project status
-enhance-swarm status --json
-# → Detailed status including active agents, worktrees, health
-
-# Configuration details
-enhance-swarm config
-# → Show current project configuration
-
-# Manage notifications
-enhance-swarm notifications --test
-# → Test notification system functionality
-
-# Get smart suggestions
-enhance-swarm suggest
-# → Context-aware improvement suggestions
-```
-
-## 🏗️ Architecture Overview
-
-```
-┌─ Your Terminal ─────────────────────────────────────────┐
-│  enhance-swarm CLI (Self-Contained Ruby Orchestrator)  │
-│  ├── Built-in Agent Spawning & Session Management      │
-│  ├── Progress Tracking & Live Streaming                │
-│  ├── Process Monitoring & Status Reporting             │  
-│  └── Git Worktree Management & Resource Cleanup        │
-└─────────────────────┬───────────────────────────────────┘
-                      │
-┌─ Control Agent ─────▼───────────────────────────────────┐
-│  Claude Instance (Autonomous Coordinator)              │
-│  ├── Task Analysis & Agent Planning                    │
-│  ├── Dependency Management (backend → frontend → qa)   │
-│  ├── Progress Monitoring & Handoff Decisions           │
-│  └── Conflict Resolution & Error Recovery              │
-└─────────────────────┬───────────────────────────────────┘
-                      │ spawns & coordinates via JSON
-           ┌──────────┼──────────┬──────────┐
-           ▼          ▼          ▼          ▼
-    ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
-    │🔧 Backend│ │🎨 Frontend│ │🧪 QA    │ │✨ UX     │
-    │ Agent   │ │ Agent   │ │ Agent   │ │ Agent   │
-    │ Worktree│ │ Worktree│ │ Worktree│ │ Worktree│
-    └─────────┘ └─────────┘ └─────────┘ └─────────┘
-```
-
-## ⚙️ Advanced Configuration
-
-### Custom Agent Roles
-
-```yaml
-# .enhance_swarm.yml
-agents:
-  database_expert:
-    focus: "Database optimization, migrations, indexing"
-    trigger_keywords: ["database", "migration", "index", "query"]
-    
-  security_specialist:
-    focus: "Security audits, vulnerability scanning"
-    trigger_keywords: ["security", "auth", "permission", "encrypt"]
+enhance-swarm dashboard
 ```
+- Live agent status and progress
+- Resource usage monitoring  
+- Task coordination visualization
+- Interactive controls and logs
 
-### Environment Variables
-
+### Status Tracking
 ```bash
-# Logging
-export ENHANCE_SWARM_LOG_LEVEL=debug
-export ENHANCE_SWARM_JSON_LOGS=true
-
-# Behavior
-export ENHANCE_SWARM_STRICT=true  # Fail fast on dependency issues
-```
-
-### MCP Tool Integration
-
-```yaml
-# .enhance_swarm.yml
-mcp_tools:
-  gemini_cli: true      # Large codebase analysis
-  desktop_commander: true  # File operations outside project
-```
-
-## 🛡️ Security & Quality
-
-### Built-in Security
-
-- **Command Injection Protection**: All shell commands use `Open3.capture3` with argument sanitization
-- **Input Validation**: Configuration values validated, dangerous patterns blocked  
-- **Path Sanitization**: Prevents directory traversal attacks
-- **Timeout Protection**: All external commands have configurable timeouts
-- **Secure Defaults**: Principle of least privilege, secure by default
-
-### Quality Assurance
-
-- **106 Comprehensive Tests**: Security, functionality, edge cases
-- **Automated Retry Logic**: Handles transient failures gracefully
-- **Resource Cleanup**: Automatic cleanup of stale worktrees and processes
-- **Dependency Validation**: Ensures required tools are available and working
-
-## 🚨 Error Recovery & Resilience
-
-### Automatic Retry Logic
-
-```ruby
-# Built-in retry for transient failures
-RetryHandler.with_retry(max_retries: 3) do
-  CommandExecutor.execute('git', 'push', 'origin', 'HEAD')
-end
+enhance-swarm status
 ```
+- Active agents and their specializations
+- Task dependencies and completion status
+- Git worktree isolation and branch tracking
+- Session management and progress metrics
 
-### Smart Cleanup
+## 🚦 Troubleshooting
 
-```bash
-# Automatic detection and cleanup of:
-# - Stale git worktrees
-# - Abandoned agent processes  
-# - Temporary communication files
-# - Failed operation artifacts
-enhance-swarm cleanup --all
-```
-
-### Health Monitoring
+### Common Issues
+- **No Claude CLI**: Install from [Claude Code](https://claude.ai/code)
+- **Permission Errors**: Ensure git repository is initialized
+- **Resource Limits**: Adjust limits in `.enhance_swarm.yml`
+- **Agent Conflicts**: Use `enhance-swarm cleanup` to reset state
 
+### Debug Mode
 ```bash
-# Comprehensive system validation
-enhance-swarm doctor --detailed --json
-# → Validates git, claude-swarm, ruby, dependencies with version checks
+ENHANCE_SWARM_DEBUG=true enhance-swarm orchestrate "your task"
 ```
 
-## 📊 Token Optimization
-
-### Intelligent Context Management
-
-- **Specialized Prompts**: Role-specific prompts minimize token usage
-- **Progressive Context**: Only relevant context passed to each agent
-- **Efficient Monitoring**: Brief coordination checks vs. continuous polling
-- **Smart Caching**: Reuse analysis results across agents
-
-### Usage Tracking
+## 📚 Quick Reference
 
+### Essential Commands
 ```bash
-# Built-in token estimation and tracking
-⠋ [█████████░░] 45% Spawning agents... [1,250/3,000 tokens (42%)]
-```
-
-## 🔧 Troubleshooting
-
-### Self-Contained Architecture
-
-✅ **No External Dependencies Required**
-- **Built-in agent spawning** - No need for external claude-swarm tool
-- **Session management** - JSON-based coordination and tracking
-- **Process monitoring** - Native PID management and status checking  
-- **Git worktree integration** - Direct git command execution
+# Setup
+gem install enhance_swarm && enhance-swarm init
 
-### Common Issues
-
-```bash
-# Dependency problems
-enhance-swarm doctor
-# → Validates git, Ruby, and optional tools
+# Start orchestration (recommended)
+enhance-swarm orchestrate "Your task description" --detached
 
-# Agent coordination issues  
+# Monitor progress  
 enhance-swarm status
-# → Shows agent sessions and process status
+tail -f .enhance_swarm/logs/orchestration.log
 
-# Interactive troubleshooting
-enhance-swarm troubleshoot
-# → Guided problem diagnosis and system health checks
+# Alternative: Interactive mode
+enhance-swarm enhance
 ```
 
-### Debug Mode
-
+### Command Options
 ```bash
-# Verbose logging
-ENHANCE_SWARM_LOG_LEVEL=debug enhance-swarm enhance "test task"
-
-# JSON logs for parsing
-ENHANCE_SWARM_JSON_LOGS=true enhance-swarm enhance "test task"
-```
-
-## 🤝 Integration Examples
-
-### Rails Projects
-
-```yaml
-# .enhance_swarm.yml for Rails
-project:
-  technology_stack: ["Rails 8", "PostgreSQL", "Hotwire", "Tailwind"]
-  
-commands:
-  test: "bundle exec rspec"
-  lint: "bundle exec rubocop"
-  type_check: "bundle exec sorbet tc"
-```
-
-### React/Node Projects
-
-```yaml
-# .enhance_swarm.yml for React
-project:
-  technology_stack: ["React 18", "TypeScript", "Vite", "TailwindCSS"]
-  
-commands:
-  test: "npm test"
-  lint: "npm run lint"
-  type_check: "npm run type-check"
-  build: "npm run build"
+--detached          # Run in background (recommended)
+--background        # Run with periodic updates
+--follow            # Stream live output (blocking)
+--coordination      # Enable task coordination (default: true)
 ```
 
-### Python Projects
-
-```yaml
-# .enhance_swarm.yml for Python
-project:
-  technology_stack: ["Python 3.11", "FastAPI", "PostgreSQL", "Pytest"]
-  
-commands:
-  test: "pytest"
-  lint: "ruff check ."
-  format: "black ."
-  type_check: "mypy ."
-```
-
-## 📈 Performance & Scaling
-
-### Optimized for Large Codebases
-
-- **Parallel Agent Execution**: Multiple agents work simultaneously
-- **Git Worktree Isolation**: No conflicts between agent work
-- **Efficient Monitoring**: Brief coordination checks, not continuous polling
-- **Smart Resource Management**: Automatic cleanup prevents resource leaks
-
-### Benchmarks
-
-- **Startup Time**: < 2 seconds for agent coordination
-- **Memory Usage**: ~50MB base + ~30MB per active agent
-- **Token Efficiency**: 60-80% reduction vs. single-agent approaches
-
-## 🎓 Best Practices
-
-### Task Sizing
-
-**✅ Good for Multi-Agent:**
-- Feature implementations requiring UI + backend + tests
-- Complex refactoring across multiple components
-- New system integrations with multiple touch points
-
-**✅ Good for Single Agent:**
-- Bug fixes in specific components
-- Configuration updates
-- Documentation improvements
-- Small feature additions
-
-### Workflow Patterns
-
+### Common Tasks
 ```bash
-# Feature development workflow
-enhance-swarm enhance "implement user profiles" --follow
-# → Watch agents coordinate in real-time
+# Full-stack features
+enhance-swarm orchestrate "Create user registration with email verification" --detached
 
-# Monitor periodically  
-enhance-swarm status
-# → Check overall progress
+# CRUD systems  
+enhance-swarm orchestrate "Build inventory management with categories and search" --detached
 
-# Use visual dashboard
-enhance-swarm dashboard
-# → Real-time visual monitoring
+# API development
+enhance-swarm orchestrate "Add REST API with JWT authentication" --detached
 
-# Get smart suggestions
-enhance-swarm suggest
-# → Context-aware next actions
+# UI components
+enhance-swarm orchestrate "Create responsive dashboard with charts" --detached
 ```
 
-## 🚀 What's Next
+## 🤝 Contributing
 
-EnhanceSwarm represents the future of AI-assisted development:
+EnhanceSwarm is designed for production use and community contributions:
 
-- **Autonomous Development Teams**: AI agents that truly collaborate
-- **Intelligent Coordination**: Control Agent makes smart decisions
-- **Real-time Visibility**: Never wonder what your agents are doing
-- **Production Ready**: Security, reliability, and error recovery built-in
+1. **Report Issues**: [GitHub Issues](https://github.com/todddickerson/enhance_swarm/issues)
+2. **Request Features**: Orchestration improvements, new agent types, project support
+3. **Submit PRs**: Agent specializations, coordination algorithms, integrations
 
-**Ready to transform your development workflow?**
+## 📈 Roadmap
 
-```bash
-# Get started in 30 seconds
-echo 'gem "enhance_swarm", git: "https://github.com/todddickerson/enhance_swarm.git"' >> Gemfile
-bundle install
-bundle exec enhance-swarm init
-```
-
----
+- **v1.1**: Advanced agent communication protocols
+- **v1.2**: Visual workflow designer and task dependencies  
+- **v1.3**: Custom agent types and specialization training
+- **v1.4**: Multi-project coordination and team templates
 
 ## 📄 License
 
-MIT License - see [LICENSE](LICENSE) file for details.
-
-## 🙏 Acknowledgments
-
-Built from production experience with Claude Swarm orchestration patterns. Special thanks to the Anthropic team for Claude and the emerging multi-agent development paradigms.
+MIT License - see [LICENSE](LICENSE) for details.
 
 ---
 
-**Transform your development workflow with intelligent multi-agent coordination. Start enhancing today!** 🚀
+**EnhanceSwarm v1.0** - Transform Claude into your intelligent development team. Built for production, optimized for collaboration, designed for the future of AI-powered development.
+
+🚀 **Ready to revolutionize your development workflow?** `gem install enhance_swarm`