enhance_swarm 2.0.0 → 2.1.1

data/README.md

@@ -18,6 +18,7 @@ EnhanceSwarm transforms Claude into a sophisticated development team that works
 ### Installation
 ```bash
 gem install enhance_swarm
+# Version 2.1.0+ required for critical fixes and detached mode
 ```
 
 ### Initialize in Your Project
@@ -27,13 +28,27 @@ enhance-swarm init
 ```
 
 ### Run Intelligent Multi-Agent Development
+
+**Recommended: Detached Mode (Non-blocking)**
 ```bash
-# Orchestrate a complete feature with specialized agents
-enhance-swarm orchestrate "Add user authentication with email verification"
+# Start orchestration in background - returns immediately
+enhance-swarm orchestrate "Create a Contact management system with CRUD operations" --detached
+
+# Monitor progress
+enhance-swarm status
+
+# Check logs
+tail -f .enhance_swarm/logs/orchestration.log
+```
 
-# Or use the enhanced ENHANCE protocol
+**Alternative: Interactive Mode**
+```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"
 ```
 
 ## 🎯 How It Works
@@ -100,6 +115,38 @@ enhance-swarm doctor
 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
@@ -189,6 +236,44 @@ resources:
 - Comprehensive security testing framework
 - Production validation and deployment readiness
 
+## 📊 Monitoring & Status
+
+### Check Orchestration Progress
+```bash
+# Check if orchestration is running
+enhance-swarm status
+
+# Monitor logs in real-time
+tail -f .enhance_swarm/logs/orchestration.log
+
+# View specific agent output
+cat .enhance_swarm/logs/backend_output.log
+```
+
+### Understanding Output
+```bash
+🎯 Starting intelligent multi-agent orchestration
+🚀 Orchestration started in detached mode
+📁 Check .enhance_swarm/logs/ for progress updates
+
+# Status responses:
+📊 Orchestration running (PID: 12345)
+Status: RUNNING
+✅ Status: COMPLETED  
+❌ Status: FAILED: <error message>
+```
+
+### Log Structure
+```
+.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
+```
+
 ## 🎯 Real-World Examples
 
 ### Add Authentication System
@@ -242,6 +327,47 @@ enhance-swarm status
 ENHANCE_SWARM_DEBUG=true enhance-swarm orchestrate "your task"
 ```
 
+## 📚 Quick Reference
+
+### Essential Commands
+```bash
+# Setup
+gem install enhance_swarm && enhance-swarm init
+
+# Start orchestration (recommended)
+enhance-swarm orchestrate "Your task description" --detached
+
+# Monitor progress  
+enhance-swarm status
+tail -f .enhance_swarm/logs/orchestration.log
+
+# Alternative: Interactive mode
+enhance-swarm enhance
+```
+
+### Command Options
+```bash
+--detached          # Run in background (recommended)
+--background        # Run with periodic updates
+--follow            # Stream live output (blocking)
+--coordination      # Enable task coordination (default: true)
+```
+
+### Common Tasks
+```bash
+# Full-stack features
+enhance-swarm orchestrate "Create user registration with email verification" --detached
+
+# CRUD systems  
+enhance-swarm orchestrate "Build inventory management with categories and search" --detached
+
+# API development
+enhance-swarm orchestrate "Add REST API with JWT authentication" --detached
+
+# UI components
+enhance-swarm orchestrate "Create responsive dashboard with charts" --detached
+```
+
 ## 🤝 Contributing
 
 EnhanceSwarm is designed for production use and community contributions:

data/lib/enhance_swarm/agent_spawner.rb

@@ -255,15 +255,17 @@ module EnhanceSwarm
         ## Your Task:
         #{base_prompt}
         
-        ## Important Instructions:
-        1. Stay focused on your role as a #{role} specialist
-        2. Follow the project's code standards and conventions
-        3. Work autonomously but consider integration with other agents
-        4. Create high-quality, production-ready code
-        5. Include comprehensive tests where appropriate
-        6. Document your changes and decisions
-        7. If you encounter permission issues, provide detailed implementation plans instead
-        8. Always output what you would implement, even if file operations fail
+        ## Critical Instructions:
+        1. YOU MUST ACTUALLY IMPLEMENT CODE - Use Read, Edit, Write, and Bash tools to create real files
+        2. Stay focused on your role as a #{role} specialist
+        3. Follow the project's code standards and conventions  
+        4. Work autonomously - DO NOT ASK FOR PERMISSION, JUST IMPLEMENT
+        5. Create high-quality, production-ready code with proper validations
+        6. 🚨 FOR BULLET TRAIN PROJECTS: ALWAYS use Super Scaffolding - NEVER create manual models!
+        7. 🎨 FOR BULLET TRAIN PROJECTS: ALWAYS use Tailwind CSS - NEVER Bootstrap or custom CSS!
+        8. Use Bash tool to run Rails generators, database migrations, and tests
+        9. Commit your changes when complete using Git commands
+        10. If you encounter any issues, fix them and continue until task is complete
         
         ## Available Tools:
         You have access to all Claude Code tools for file editing, terminal commands, and project analysis.
@@ -275,7 +277,14 @@ module EnhanceSwarm
     end
 
     def get_role_description(role)
-      case role.to_s.downcase
+      config = EnhanceSwarm.configuration
+      project_analyzer = ProjectAnalyzer.new
+      project_context = project_analyzer.generate_smart_defaults
+      
+      # Check if this is a Bullet Train project
+      is_bullet_train = has_bullet_train_stack?(config, project_context)
+      
+      base_description = case role.to_s.downcase
       when 'backend'
         'You specialize in server-side logic, APIs, database design, models, and business logic implementation.'
       when 'frontend'
@@ -291,6 +300,203 @@ module EnhanceSwarm
       else
         "You are a #{role} specialist agent focusing on your area of expertise."
       end
+      
+      # Add Bullet Train specific instructions if this is a BT project
+      if is_bullet_train
+        base_description + get_bullet_train_role_enhancement(role)
+      else
+        base_description
+      end
+    end
+    
+    def has_bullet_train_stack?(config, project_context)
+      # Check Gemfile for bullet_train gems
+      return true if File.exist?('Gemfile') && File.read('Gemfile').include?('bullet_train')
+      
+      # Check technology stack
+      tech_stack = config.technology_stack || project_context[:technology_stack] || []
+      tech_stack.include?('Bullet Train')
+    rescue
+      false
+    end
+    
+    def get_bullet_train_role_enhancement(role)
+      case role.to_s.downcase
+      when 'backend'
+        <<~BT_ENHANCEMENT
+        
+        
+        ## 🚅 BULLET TRAIN BACKEND SPECIALIZATION:
+        
+        **CRITICAL: Use Super Scaffolding for ALL model generation**
+        - NEVER create models manually - always use: rails generate super_scaffold ModelName Team field:field_type
+        - Use bin/resolve ClassName --eject --open before modifying any existing models
+        - ALL models must inherit team-scoped architecture: belongs_to :team
+        
+        **Model Structure (EXACT pattern):**
+        ```ruby
+        class Contact < ApplicationRecord
+          include Contacts::Base  # Gem concern with core logic
+          include Webhooks::Outgoing::TeamSupport
+          # 🚅 add concerns above.
+          
+          # 🚅 add belongs_to associations above.
+          # 🚅 add has_many associations above.
+          # 🚅 add scopes above.
+          # 🚅 add validations above.
+          # 🚅 add callbacks above.
+          # 🚅 add methods above.
+        end
+        ```
+        
+        **🚨 MANDATORY EXECUTION SEQUENCE - NO EXCEPTIONS:**
+        1. FIRST: Use Super Scaffolding with non-interactive mode:
+           ```bash
+           # For Contact model:
+           printf "y\\ncontacts\\nti-address-book\\n" | bundle exec rails generate super_scaffold Contact Team name:text_field email:email_field phone:phone_field company:text_field
+           
+           # For Project model:
+           printf "y\\nprojects\\nti-view-grid\\n" | bundle exec rails generate super_scaffold Project Team title:text_field description:trix_editor status:buttons due_date:date_field
+           
+           # Template for any model:
+           printf "y\\n[plural_slug]\\n[icon_name]\\n" | bundle exec rails generate super_scaffold [ModelName] Team [field:type ...]
+           ```
+           - Auto-answers: navbar=yes, slug=[plural_slug], icon=[icon_name]
+           - Common icons: ti-address-book, ti-view-grid, ti-users, ti-folder, ti-calendar
+        2. THEN: bundle exec rails db:migrate
+        3. THEN: bundle exec rails test (to verify everything works)
+        4. ONLY IF NEEDED: bin/resolve Projects::Base --eject --open (for customization)
+        5. Configure config/models/roles.yml with proper permissions
+        
+        **🚨 CRITICAL: You MUST actually run these commands using the Bash tool - not just describe them!**
+        **🚨 DO NOT create manual Rails models/controllers - ONLY use Super Scaffolding!**
+        **🚨 NEVER skip step 1 - Super Scaffolding is MANDATORY for Bullet Train projects!**
+        **🚨 ALWAYS use printf with proper answers for interactive prompts!**
+        
+        **API Routes (add to config/routes/api/v1.rb):**
+        ```ruby
+        namespace :api do
+          namespace :v1 do
+            shallow do
+              resources :teams do
+                resources :contacts
+              end
+            end
+          end
+        end
+        ```
+        BT_ENHANCEMENT
+      when 'frontend'
+        <<~BT_ENHANCEMENT
+        
+        
+        ## 🚅 BULLET TRAIN FRONTEND SPECIALIZATION:
+        
+        **CRITICAL: Customize generated views, don't create from scratch**
+        - Super Scaffolding generates account/contacts/* views automatically
+        - Use bin/resolve account/contacts/_form --eject for view customization
+        - All views follow account-scoped pattern: app/views/account/contacts/
+        
+        **Required View Structure:**
+        - app/views/account/contacts/index.html.erb (team-scoped listing)
+        - app/views/account/contacts/show.html.erb (individual contact)
+        - app/views/account/contacts/_form.html.erb (create/edit form)
+        - Use Bullet Train themes and components
+        
+        **🎨 STYLING: Use Tailwind CSS (Bullet Train Default)**
+        - ALWAYS use Tailwind CSS classes (bg-blue-500, text-white, etc.)
+        - NEVER use Bootstrap or custom CSS - BT uses Tailwind by default
+        - Use BT's Tailwind theme tokens and design system
+        - Follow BT responsive patterns: sm:, md:, lg: breakpoints
+        - Use BT component classes: .btn, .card, .form-control (Tailwind-based)
+        
+        **Navigation Integration:**
+        - Add to account navigation (usually in app/views/account/shared/_menu.html.erb)
+        - Use BT icon helpers and Tailwind styling patterns
+        - Ensure mobile-responsive with Tailwind responsive classes
+        
+        **Commands:**
+        1. bin/resolve account/contacts --eject (to customize views)
+        2. bin/resolve shared/fields --open (for field customization)
+        3. Use existing BT theme patterns and components
+        BT_ENHANCEMENT
+      when 'qa'
+        <<~BT_ENHANCEMENT
+        
+        
+        ## 🚅 BULLET TRAIN QA SPECIALIZATION:
+        
+        **CRITICAL: Test team-scoped behavior and permissions**
+        - Test models with proper team association and scoping
+        - Validate role-based permissions from config/models/roles.yml
+        - Test API endpoints with proper authentication and authorization
+        
+        **Required Test Structure:**
+        ```ruby
+        # spec/models/contact_spec.rb
+        require 'rails_helper'
+        
+        RSpec.describe Contact, type: :model do
+          let(:team) { create(:team) }
+          let(:contact) { create(:contact, team: team) }
+          
+          it "belongs to team" do
+            expect(contact.team).to eq(team)
+          end
+          
+          it "validates required fields" do
+            # Test BT field validations
+          end
+          
+          it "respects team scoping" do
+            # Test team isolation
+          end
+        end
+        ```
+        
+        **API Testing:**
+        - spec/requests/api/v1/contacts_spec.rb with proper authentication
+        - Test team-scoped API access and permissions
+        - Validate webhook payload generation
+        
+        **Commands:**
+        1. bundle exec rspec spec/models/contact_spec.rb
+        2. bundle exec rspec spec/requests/api/v1/contacts_spec.rb
+        3. Test with different user roles and team memberships
+        BT_ENHANCEMENT
+      when 'scaffolding'
+        <<~BT_ENHANCEMENT
+        
+        
+        ## 🚅 BULLET TRAIN SCAFFOLDING MASTER PROTOCOL:
+        
+        **🚨 MANDATORY EXECUTION SEQUENCE (MUST RUN THESE EXACT COMMANDS) - NO EXCEPTIONS:**
+        1. bundle exec rails generate super_scaffold Contact Team name:text_field email:email_field phone:phone_field company:text_field
+        2. bundle exec rails db:migrate
+        3. bundle exec rails test (verify everything works)
+        4. Configure roles in config/models/roles.yml
+        5. Add API routes to config/routes/api/v1.rb
+        6. bundle exec rails test (final verification)
+        
+        **🚨 YOU MUST USE THE BASH TOOL TO ACTUALLY EXECUTE THESE COMMANDS - NOT JUST WRITE CODE FILES!**
+        **🚨 FAILURE TO RUN SUPER_SCAFFOLD COMMAND IS A CRITICAL ERROR!**
+        **🚨 DO NOT CREATE MANUAL MODELS/CONTROLLERS - BULLET TRAIN REQUIRES SUPER SCAFFOLDING!**
+        
+        **POST-SCAFFOLDING OPTIMIZATION:**
+        - bin/resolve Contacts::Base --eject --open (for model customization)
+        - bin/resolve account/contacts/_form --eject (for view customization)
+        - Add custom validations and business logic
+        - Configure webhooks and integrations
+        
+        **TEAM ARCHITECTURE VERIFICATION:**
+        - Ensure all models use team-scoped ownership
+        - Validate proper role inheritance in config/models/roles.yml
+        - Test API endpoints respect team boundaries
+        - Confirm webhook payloads include team context
+        BT_ENHANCEMENT
+      else
+        ''
+      end
     end
 
     def create_agent_script(prompt, role, working_dir)
@@ -323,9 +529,9 @@ module EnhanceSwarm
           #{prompt}
           EOF
           
-          # Run Claude with the prompt
+          # Run Claude with the prompt in interactive mode with full permissions
           echo "Executing Claude for #{role} agent..."
-          claude --print < "$PROMPT_FILE"
+          claude --dangerously-skip-permissions < "$PROMPT_FILE"
           
           # Cleanup
           rm -f "$PROMPT_FILE"

data/lib/enhance_swarm/cli.rb

@@ -2,6 +2,7 @@
 
 require 'thor'
 require 'colorize'
+require 'timeout'
 require_relative 'web_ui'
 require_relative 'session_manager'
 require_relative 'task_coordinator'
@@ -84,18 +85,73 @@ module EnhanceSwarm
     desc 'orchestrate TASK_DESC', 'Intelligent multi-agent orchestration with smart coordination'
     option :coordination, type: :boolean, default: true, desc: 'Enable intelligent task coordination'
     option :follow, type: :boolean, default: false, desc: 'Stream live output from all agents'
+    option :background, type: :boolean, default: false, desc: 'Run orchestration in background (non-blocking)'
+    option :detached, type: :boolean, default: false, desc: 'Run completely detached and return immediately'
     def orchestrate(task_desc)
       say "🎯 Starting intelligent multi-agent orchestration", :blue
       say "Task: #{task_desc}", :white
       
       begin
         coordinator = TaskCoordinator.new
-        coordinator.coordinate_task(task_desc)
+        
+        if options[:detached]
+          # Run completely detached - spawn background process and return immediately
+          spawn_detached_orchestration(task_desc, coordinator)
+          say "🚀 Orchestration started in detached mode", :green
+          say "📁 Check .enhance_swarm/logs/ for progress updates", :blue
+          return
+        elsif options[:background]
+          # Run in background with periodic status updates
+          run_background_orchestration(task_desc, coordinator)
+        else
+          # Run normally (blocking)
+          coordinator.coordinate_task(task_desc)
+        end
         
         say "✅ Multi-agent orchestration completed successfully!", :green
+      rescue Timeout::Error => e
+        say "⏰ Orchestration timed out: #{e.message}", :red
+        say "Consider breaking down the task into smaller parts", :yellow
+      rescue SystemExit, Interrupt
+        say "🛑 Orchestration interrupted by user", :yellow
       rescue StandardError => e
         say "❌ Orchestration failed: #{e.message}", :red
         say "Debug info: #{e.backtrace.first(3).join("\n")}", :yellow
+        say "Run 'enhance-swarm doctor' to check system health", :blue
+      end
+    end
+
+    desc 'status', 'Check status of running orchestration'
+    def status
+      if File.exist?('.enhance_swarm/logs/orchestration.pid')
+        pid = File.read('.enhance_swarm/logs/orchestration.pid').strip
+        
+        begin
+          Process.getpgid(pid.to_i)
+          say "🔄 Orchestration running (PID: #{pid})", :blue
+          
+          if File.exist?('.enhance_swarm/logs/orchestration_status.txt')
+            status = File.read('.enhance_swarm/logs/orchestration_status.txt').strip
+            say "Status: #{status}", :yellow
+          end
+          
+          # Show recent log entries
+          if File.exist?('.enhance_swarm/logs/orchestration.log')
+            logs = File.readlines('.enhance_swarm/logs/orchestration.log').last(5)
+            say "\nRecent activity:", :white
+            logs.each { |log| say "  #{log.strip}", :light_black }
+          end
+          
+        rescue Errno::ESRCH
+          say "💤 No orchestration currently running", :yellow
+          
+          if File.exist?('.enhance_swarm/logs/orchestration_status.txt')
+            status = File.read('.enhance_swarm/logs/orchestration_status.txt').strip
+            say "Last status: #{status}", :light_black
+          end
+        end
+      else
+        say "💤 No orchestration currently running", :yellow
       end
     end
 
@@ -572,6 +628,79 @@ module EnhanceSwarm
 
     private
 
+    def spawn_detached_orchestration(task_desc, coordinator)
+      require 'fileutils'
+      
+      # Ensure logs directory exists
+      FileUtils.mkdir_p('.enhance_swarm/logs')
+      
+      # Create status files
+      File.write('.enhance_swarm/logs/orchestration_status.txt', 'STARTING')
+      
+      # Log the start
+      File.write('.enhance_swarm/logs/orchestration.log', 
+        "#{Time.now}: Starting detached orchestration\nTask: #{task_desc}\n", 
+        mode: 'a')
+      
+      # Spawn background process using Ruby Process.spawn
+      pid = Process.spawn(
+        {
+          'ENHANCE_SWARM_DETACHED' => 'true',
+          'ENHANCE_SWARM_TASK' => task_desc
+        },
+        'ruby', '-e', <<~RUBY,
+          require '#{File.expand_path('../../enhance_swarm', __FILE__)}'
+          
+          task_desc = ENV['ENHANCE_SWARM_TASK']
+          working_dir = '#{Dir.pwd}'
+          
+          begin
+            Dir.chdir(working_dir)
+            
+            File.write("\#{working_dir}/.enhance_swarm/logs/orchestration_status.txt", 'RUNNING')
+            File.write("\#{working_dir}/.enhance_swarm/logs/orchestration.log", 
+              "\#{Time.now}: Coordinator starting in \#{working_dir}\\n", mode: 'a')
+            
+            coordinator = EnhanceSwarm::TaskCoordinator.new
+            coordinator.coordinate_task(task_desc)
+            
+            File.write("\#{working_dir}/.enhance_swarm/logs/orchestration_status.txt", 'COMPLETED')
+            File.write("\#{working_dir}/.enhance_swarm/logs/orchestration.log", 
+              "\#{Time.now}: Orchestration completed successfully\\n", mode: 'a')
+              
+          rescue => e
+            File.write("\#{working_dir}/.enhance_swarm/logs/orchestration_status.txt", "FAILED: \#{e.message}")
+            File.write("\#{working_dir}/.enhance_swarm/logs/orchestration.log", 
+              "\#{Time.now}: ERROR: \#{e.message}\\n\#{e.backtrace.first(3).join('\\n')}\\n", mode: 'a')
+          end
+        RUBY
+        chdir: Dir.pwd,
+        out: File.join(Dir.pwd, '.enhance_swarm/logs/orchestration.log'),
+        err: File.join(Dir.pwd, '.enhance_swarm/logs/orchestration.log')
+      )
+      
+      # Store PID and detach
+      File.write('.enhance_swarm/logs/orchestration.pid', pid.to_s)
+      Process.detach(pid)
+      
+      File.write('.enhance_swarm/logs/orchestration.log', 
+        "#{Time.now}: Orchestration PID: #{pid}\n", mode: 'a')
+    end
+
+    def run_background_orchestration(task_desc, coordinator)
+      thread = Thread.new do
+        coordinator.coordinate_task(task_desc)
+      end
+      
+      # Monitor with periodic updates
+      while thread.alive?
+        say "⏳ Orchestration running... (#{Time.now.strftime('%H:%M:%S')})", :blue
+        sleep(30)
+      end
+      
+      thread.value # Wait for completion
+    end
+
     def spawn_with_streaming(task_desc, role = nil)
       orchestrator = Orchestrator.new
       agent_role = role || options[:role] || 'general'