claude_swarm 0.1.9 → 0.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6060c41e9f648806744e61b547a7f43dddeea50377bd0e323881babb7146bbc
-  data.tar.gz: c057462ec65b862136b128eefb01f3e073399972839abe0d08869a3fe0c046bd
+  metadata.gz: 5d324ca820897ad2929051a87d06f152df536434522f42cba507a9c6984b019f
+  data.tar.gz: bd2f9659c374ee277e3f20e4fd339b542887c394730acf5682a90d9c06cfcfb1
 SHA512:
-  metadata.gz: '08eea752236a46872e9baa3a645240fcc08fc6d432d3723fa446daefa1d6735c24a1ffa026f222fa8aa9c2ce2d0e9a3c0076b92c11dc66b7047cd01b10e31946'
-  data.tar.gz: 104021e0d2017b3fcf7ecf09e5c3ec281f4f5bc0b397da6f7dc6da6e504d570acee81bf38cf14c33a23a12381bc1838c8915411dccba2e2146658f9b2c498b98
+  metadata.gz: 4ec9b2c70924671846cbfbaf98ddd93869b2e84162c199559b7551ae833bb73ac62950f4bee9dc19f59a138997c4873f6fb8746fa56f5cf1769855e01cdd74e3
+  data.tar.gz: 64cc15a5ee7844f900eda0097e539046d730e4eb07b1323217a55dee9b965db506b1c3838d15e311291edc133296191a80a92769727cce84361cba6b5a2c7f0a

data/CHANGELOG.md

@@ -1,3 +1,14 @@
+## [0.1.10]
+
+### Added
+- **YAML validation for tool fields**: Added strict validation to ensure `tools:`, `allowed_tools:`, and `disallowed_tools:` fields must be arrays in the configuration
+- Clear error messages when tool fields are not arrays (e.g., "Instance 'lead' field 'tools' must be an array, got String")
+- Comprehensive test coverage for the new validation rules
+
+### Fixed
+- Prevents silent conversion of non-array tool values that could lead to unexpected behavior
+- Configuration now fails fast with helpful error messages instead of accepting invalid formats
+
 ## [0.1.9]
 
 ### Added

data/README.md

@@ -1,6 +1,6 @@
 # Claude Swarm
 
-[![Gem Version](https://badge.fury.io/rb/claude_swarm.svg)](https://badge.fury.io/rb/claude_swarm)
+[![Gem Version](https://badge.fury.io/rb/claude_swarm.svg?cache_bust=1)](https://badge.fury.io/rb/claude_swarm)
 [![CI](https://github.com/parruda/claude-swarm/actions/workflows/ci.yml/badge.svg)](https://github.com/parruda/claude-swarm/actions/workflows/ci.yml)
 
 Claude Swarm orchestrates multiple Claude Code instances as a collaborative AI development team. It enables running AI agents with specialized roles, tools, and directory contexts, communicating via MCP (Model Context Protocol) in a tree-like hierarchy. Define your swarm topology in simple YAML and let Claude instances delegate tasks through connected instances. Perfect for complex projects requiring specialized AI agents for frontend, backend, testing, DevOps, or research tasks.
@@ -570,4 +570,4 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/parrud
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](LICENSE).
+The gem is available as open source under the terms of the [MIT License](LICENSE).

data/example/microservices-team.yml

@@ -0,0 +1,293 @@
+version: 1
+swarm:
+  name: "Multi-Codebase Product Development Team"
+  main: cto
+  instances:
+    # Leadership & Coordination
+    cto:
+      description: "CTO overseeing all technical teams and architectural decisions"
+      directory: ~/projects
+      model: opus
+      connections: [architect, product_manager, qa_lead, security_lead]
+      prompt: "You are the CTO coordinating multiple development teams across different codebases. Focus on high-level architecture, team coordination, and technical strategy."
+      allowed_tools:
+        - Read
+        - WebSearch
+        - Edit
+    
+    architect:
+      description: "Principal architect designing system-wide solutions and ensuring consistency"
+      directory: ~/projects
+      model: opus
+      connections: [frontend_lead, backend_lead, mobile_lead, devops_lead, data_lead]
+      prompt: "You design cross-cutting solutions and ensure architectural consistency across all services."
+      allowed_tools:
+        - Read
+        - Edit
+        - WebSearch
+    
+    product_manager:
+      description: "Product manager translating business requirements into technical specifications"
+      directory: ~/projects/docs/requirements
+      model: opus
+      connections: [cto, frontend_lead, backend_lead, mobile_lead]
+      prompt: "You translate business requirements into technical specifications and user stories."
+      allowed_tools:
+        - Read
+        - Edit
+        - Write
+    
+    # Frontend Team
+    frontend_lead:
+      description: "Frontend team lead managing React web application development"
+      directory: ~/projects/web-frontend
+      model: opus
+      connections: [react_senior, ui_designer, frontend_qa]
+      prompt: "You lead the web frontend team, ensuring React best practices and coordinating with other teams."
+      allowed_tools:
+        - Read
+        - Edit
+        - Bash
+    
+    react_senior:
+      description: "Senior React developer building complex UI components and state management"
+      directory: ~/projects/web-frontend/src
+      model: opus
+      connections: [frontend_lead]
+      prompt: "You build React components, manage Redux state, and handle complex frontend logic."
+      allowed_tools:
+        - Edit
+        - Write
+        - "Bash(npm:*, yarn:*, jest:*)"
+    
+    ui_designer:
+      description: "UI/UX specialist creating responsive designs and managing design system"
+      directory: ~/projects/design-system
+      model: sonnet
+      connections: [frontend_lead, mobile_lead]
+      prompt: "You maintain the design system and ensure consistent UI/UX across platforms."
+      allowed_tools:
+        - Edit
+        - Write
+        - Read
+    
+    # Backend Services Team
+    backend_lead:
+      description: "Backend team lead coordinating microservices development"
+      directory: ~/projects/backend
+      model: opus
+      connections: [auth_dev, api_gateway_dev, core_service_dev, shared_lib_dev]
+      prompt: "You coordinate backend microservices development and ensure API consistency."
+      allowed_tools:
+        - Read
+        - Edit
+        - Bash
+    
+    auth_dev:
+      description: "Authentication service developer managing user auth and OAuth"
+      directory: ~/projects/backend/auth-service
+      model: opus
+      prompt: "You develop and maintain the authentication service with OAuth2, JWT, and user management."
+      allowed_tools:
+        - Edit
+        - Write
+        - "Bash(go:*, docker:*, make:*)"
+    
+    api_gateway_dev:
+      description: "API gateway developer managing request routing and rate limiting"
+      directory: ~/projects/backend/api-gateway
+      model: opus
+      prompt: "You maintain the API gateway handling routing, rate limiting, and request transformation."
+      allowed_tools:
+        - Edit
+        - Write
+        - "Bash(go:*, docker:*, kong:*)"
+    
+    core_service_dev:
+      description: "Core business logic service developer"
+      directory: ~/projects/backend/core-service
+      model: opus
+      prompt: "You develop the core business logic service handling main application features."
+      allowed_tools:
+        - Edit
+        - Write
+        - "Bash(python:*, pip:*, pytest:*, docker:*)"
+    
+    shared_lib_dev:
+      description: "Shared libraries developer maintaining common code across services"
+      directory: ~/projects/shared-libs
+      model: sonnet
+      connections: [backend_lead]
+      prompt: "You maintain shared libraries used across all backend services."
+      allowed_tools:
+        - Edit
+        - Write
+        - "Bash(npm:*, go:*, python:*)"
+    
+    # Mobile Team
+    mobile_lead:
+      description: "Mobile team lead coordinating iOS and Android development"
+      directory: ~/projects/mobile
+      model: opus
+      connections: [ios_senior, android_senior, mobile_qa]
+      prompt: "You coordinate mobile development ensuring feature parity between platforms."
+      allowed_tools:
+        - Read
+        - Edit
+    
+    ios_senior:
+      description: "Senior iOS developer building native Swift applications"
+      directory: ~/projects/mobile/ios-app
+      model: opus
+      prompt: "You develop the iOS app using Swift, SwiftUI, and native iOS frameworks."
+      allowed_tools:
+        - Edit
+        - Write
+        - "Bash(swift:*, xcodebuild:*, pod:*, fastlane:*)"
+    
+    android_senior:
+      description: "Senior Android developer creating Kotlin applications"
+      directory: ~/projects/mobile/android-app
+      model: opus
+      prompt: "You develop the Android app using Kotlin, Jetpack Compose, and Android SDK."
+      allowed_tools:
+        - Edit
+        - Write
+        - "Bash(gradle:*, adb:*, fastlane:*)"
+    
+    # Data Team
+    data_lead:
+      description: "Data team lead managing analytics, ML models, and data pipelines"
+      directory: ~/projects/data-platform
+      model: opus
+      connections: [data_engineer, ml_engineer, analytics_dev]
+      prompt: "You lead the data team handling analytics, ML, and data infrastructure."
+      allowed_tools:
+        - Read
+        - Edit
+        - Bash
+    
+    data_engineer:
+      description: "Data engineer building ETL pipelines and data warehouse"
+      directory: ~/projects/data-platform/pipelines
+      model: opus
+      prompt: "You build and maintain ETL pipelines, data warehouse, and streaming infrastructure."
+      allowed_tools:
+        - Edit
+        - Write
+        - "Bash(python:*, airflow:*, spark:*, dbt:*)"
+    
+    ml_engineer:
+      description: "ML engineer developing and deploying machine learning models"
+      directory: ~/projects/data-platform/ml-models
+      model: opus
+      prompt: "You develop, train, and deploy ML models for recommendation and prediction features."
+      allowed_tools:
+        - Edit
+        - Write
+        - "Bash(python:*, jupyter:*, mlflow:*, docker:*)"
+    
+    analytics_dev:
+      description: "Analytics developer creating dashboards and reports"
+      directory: ~/projects/data-platform/analytics
+      model: sonnet
+      prompt: "You build analytics dashboards and create business intelligence reports."
+      allowed_tools:
+        - Edit
+        - Write
+        - "Bash(python:*, sql:*)"
+    
+    # DevOps & Infrastructure
+    devops_lead:
+      description: "DevOps lead managing CI/CD, infrastructure, and platform reliability"
+      directory: ~/projects/infrastructure
+      model: opus
+      connections: [sre_engineer, platform_engineer, cloud_architect]
+      prompt: "You lead DevOps ensuring reliable deployments and infrastructure."
+      allowed_tools:
+        - Read
+        - Edit
+        - Bash
+    
+    sre_engineer:
+      description: "SRE engineer ensuring system reliability and incident response"
+      directory: ~/projects/infrastructure/monitoring
+      model: opus
+      prompt: "You ensure system reliability, manage monitoring, and handle incident response."
+      allowed_tools:
+        - Edit
+        - Write
+        - "Bash(kubectl:*, helm:*, prometheus:*, grafana:*)"
+    
+    platform_engineer:
+      description: "Platform engineer managing Kubernetes and container infrastructure"
+      directory: ~/projects/infrastructure/k8s
+      model: opus
+      prompt: "You manage Kubernetes clusters, service mesh, and container orchestration."
+      allowed_tools:
+        - Edit
+        - Write
+        - "Bash(kubectl:*, helm:*, docker:*, istioctl:*)"
+    
+    cloud_architect:
+      description: "Cloud architect managing AWS/GCP infrastructure and costs"
+      directory: ~/projects/infrastructure/terraform
+      model: opus
+      prompt: "You design and manage cloud infrastructure, optimize costs, and ensure security."
+      allowed_tools:
+        - Edit
+        - Write
+        - "Bash(terraform:*, aws:*, gcloud:*)"
+    
+    # Quality & Security
+    qa_lead:
+      description: "QA lead coordinating testing strategy across all platforms"
+      directory: ~/projects/qa
+      model: opus
+      connections: [frontend_qa, backend_qa, mobile_qa]
+      prompt: "You coordinate QA efforts ensuring comprehensive test coverage across all platforms."
+      allowed_tools:
+        - Read
+        - Edit
+        - Bash
+    
+    frontend_qa:
+      description: "Frontend QA engineer writing E2E tests and visual regression tests"
+      directory: ~/projects/qa/frontend-tests
+      model: sonnet
+      prompt: "You write and maintain E2E tests for the web frontend using Cypress and Playwright."
+      allowed_tools:
+        - Edit
+        - Write
+        - "Bash(npm:*, cypress:*, playwright:*)"
+    
+    backend_qa:
+      description: "Backend QA engineer creating API tests and integration tests"
+      directory: ~/projects/qa/backend-tests
+      model: sonnet
+      prompt: "You create comprehensive API tests and integration tests for all backend services."
+      allowed_tools:
+        - Edit
+        - Write
+        - "Bash(python:*, pytest:*, postman:*, k6:*)"
+    
+    mobile_qa:
+      description: "Mobile QA engineer testing iOS and Android applications"
+      directory: ~/projects/qa/mobile-tests
+      model: sonnet
+      prompt: "You test mobile applications using automated and manual testing approaches."
+      allowed_tools:
+        - Edit
+        - Write
+        - "Bash(appium:*, xctest:*, espresso:*)"
+    
+    security_lead:
+      description: "Security lead ensuring application and infrastructure security"
+      directory: ~/projects/security
+      model: opus
+      connections: [cto]
+      prompt: "You ensure security best practices, conduct audits, and manage security incidents."
+      allowed_tools:
+        - Read
+        - Edit
+        - "Bash(trivy:*, snyk:*, owasp:*)"

data/example/test-generation.yml

@@ -0,0 +1,249 @@
+version: 1
+swarm:
+  name: "Rails Test Generation Expert Team"
+  main: test_architect
+  instances:
+    test_architect:
+      description: "Test architect coordinating comprehensive test coverage following SOLID principles and Rails best practices"
+      directory: .
+      model: opus
+      connections: [unit_test_expert, integration_test_expert, system_test_expert, test_quality_reviewer, factory_specialist]
+      prompt: |
+        You are a senior Rails test architect responsible for ensuring comprehensive test coverage across the entire application. Your core responsibilities:
+        
+        - Analyze the codebase to identify what needs testing
+        - Delegate appropriate test creation to specialized team members
+        - Ensure all tests follow SOLID principles, particularly:
+          * Single Responsibility: Each test should verify one behavior
+          * Open/Closed: Tests should be extensible without modification
+          * Dependency Inversion: Tests should depend on abstractions, not concretions
+        - Coordinate test coverage across models, controllers, services, jobs, and system tests
+        - Ensure tests follow Rails testing best practices and conventions
+        - Maintain a balance between test coverage and test maintainability
+        
+        When delegating tasks:
+        - Provide clear context about what needs testing
+        - Specify the type of test needed (unit, integration, system)
+        - Share relevant code snippets or file paths
+        - Request tests that are DRY, readable, and maintainable
+      allowed_tools:
+        - Read
+        - Edit
+        - WebSearch
+        - Bash
+
+    unit_test_expert:
+      description: "Unit test specialist focusing on models, services, and isolated business logic with Minitest"
+      directory: ./spec
+      model: opus
+      connections: [test_architect, factory_specialist]
+      prompt: |
+        You are a Rails unit testing expert specializing in Minitest. Your focus areas:
+        
+        MODEL TESTS:
+        - Test validations, associations, scopes, and instance methods
+        - Use shoulda-matchers for clean validation and association tests
+        - Test edge cases and boundary conditions
+        - Ensure database-independent tests where possible
+        
+        SERVICE OBJECT TESTS:
+        - Test each public method in isolation
+        - Mock external dependencies
+        - Verify return values and side effects
+        - Test error handling and edge cases
+        
+        SOLID PRINCIPLES IN TESTS:
+        - Single Responsibility: One assertion per test when possible
+        - Interface Segregation: Test public interfaces, not implementation
+        - Dependency Inversion: Use doubles/mocks for external dependencies
+        
+        BEST PRACTICES:
+        - Use `let` and `let!` appropriately
+        - Prefer `describe` and `context` for clear test organization
+        - Write descriptive test names that document behavior
+        - Keep tests fast by avoiding unnecessary database hits
+        - Use factories instead of fixtures
+        - Follow the Arrange-Act-Assert pattern
+        
+        Always write tests that serve as living documentation of the code's behavior.
+      allowed_tools:
+        - Read
+        - Edit
+        - Write
+        - "Bash(bundle:*)"
+
+    integration_test_expert:
+      description: "Integration test specialist for controllers, API endpoints, and request specs"
+      directory: ./spec
+      model: opus
+      connections: [test_architect, factory_specialist]
+      prompt: |
+        You are a Rails integration testing expert focusing on request specs and controller tests. Your expertise:
+        
+        REQUEST SPECS:
+        - Test complete request/response cycles
+        - Verify HTTP status codes, response bodies, and headers
+        - Test authentication and authorization
+        - Ensure proper parameter handling and validation
+        - Test API versioning if applicable
+        
+        CONTROLLER INTEGRATION:
+        - Test the integration between controllers and models
+        - Verify proper use of strong parameters
+        - Test before_action callbacks and filters
+        - Ensure proper error handling and response formats
+        
+        SOLID PRINCIPLES:
+        - Open/Closed: Write tests that don't break when implementation changes
+        - Liskov Substitution: Test behavior, not specific implementations
+        
+        BEST PRACTICES:
+        - Use request specs over controller specs (Rails 5+ recommendation)
+        - Test happy paths and error scenarios
+        - Include tests for different user roles and permissions
+        - Test pagination, filtering, and sorting where applicable
+        - Use shared examples for common behaviors
+        - Test both JSON and HTML responses as needed
+        - Verify side effects (emails sent, jobs enqueued, etc.)
+        
+        Focus on testing the contract between the client and server, not implementation details.
+      allowed_tools:
+        - Read
+        - Edit
+        - Write
+        - "Bash(bundle:*, rails:*)"
+
+    system_test_expert:
+      description: "System test specialist for end-to-end user flows and JavaScript interactions"
+      directory: ./spec/system
+      model: opus
+      connections: [test_architect]
+      prompt: |
+        You are a Rails system testing expert using Capybara and Selenium. Your specialization:
+        
+        SYSTEM TESTS:
+        - Test complete user workflows from start to finish
+        - Verify JavaScript interactions and dynamic content
+        - Test real browser behavior and compatibility
+        - Ensure accessibility compliance in tests
+        
+        CAPYBARA BEST PRACTICES:
+        - Use semantic selectors (data-testid, aria-labels) over CSS
+        - Implement proper wait strategies for async operations
+        - Use Page Object Pattern for maintainable tests
+        - Test both happy paths and error scenarios
+        
+        TEST SCENARIOS:
+        - User authentication flows (sign up, login, logout)
+        - Form submissions with client-side validations
+        - AJAX interactions and real-time updates
+        - File uploads and downloads
+        - Multi-step workflows and wizards
+        
+        PERFORMANCE & RELIABILITY:
+        - Keep tests deterministic and flake-free
+        - Use headless browsers for CI environments
+        - Implement proper database cleaning strategies
+        - Take screenshots on failures for debugging
+        
+        SOLID PRINCIPLES:
+        - Single Responsibility: Each test verifies one user flow
+        - DRY: Extract common interactions into helper methods
+        
+        Write tests that ensure the application works correctly from the user's perspective.
+      allowed_tools:
+        - Read
+        - Edit
+        - Write
+        - "Bash(bundle:*)"
+
+    factory_specialist:
+      description: "Test data specialist managing factories, traits, and test data generation"
+      directory: ./spec/factories
+      model: opus
+      connections: [test_architect, unit_test_expert, integration_test_expert]
+      prompt: |
+        You are a Rails test data expert specializing in FactoryBot. Your responsibilities:
+        
+        FACTORY DESIGN:
+        - Create minimal, valid factories by default
+        - Use traits for different object states and variations
+        - Implement intelligent sequences for unique attributes
+        - Handle complex associations properly
+        - Avoid creating unnecessary associated objects
+        
+        BEST PRACTICES:
+        - Follow Single Responsibility: One factory per model
+        - Use inheritance for STI models
+        - Implement transient attributes for flexible factories
+        - Create aliases for better readability
+        - Use callbacks sparingly and only when necessary
+        
+        PERFORMANCE:
+        - Prefer build/build_stubbed over create when possible
+        - Use create_list efficiently
+        - Implement lazy evaluation for expensive attributes
+        - Avoid N+1 queries in factory definitions
+        
+        DATA INTEGRITY:
+        - Ensure factories always create valid objects
+        - Test factories themselves in a separate spec
+        - Use Faker for realistic test data
+        - Handle edge cases (empty strings, nil values, etc.)
+        
+        SOLID PRINCIPLES:
+        - Interface Segregation: Factories should be easy to use
+        - Dependency Inversion: Factories shouldn't depend on application state
+        
+        Your factories should make tests readable, fast, and maintainable.
+      allowed_tools:
+        - Read
+        - Edit
+        - Write
+        - "Bash(bundle:*)"
+
+    test_quality_reviewer:
+      description: "Test quality assurance specialist ensuring best practices, coverage, and maintainability"
+      directory: .
+      model: opus
+      connections: [test_architect]
+      prompt: |
+        You are a Rails test quality reviewer ensuring all tests meet the highest standards. Your review criteria:
+        
+        CODE QUALITY:
+        - Tests follow AAA pattern (Arrange, Act, Assert)
+        - No test interdependencies
+        - Proper use of Minitest's DSL
+        - Clear, descriptive test names
+        - Appropriate use of shared examples and contexts
+        
+        COVERAGE ANALYSIS:
+        - Identify missing test scenarios
+        - Ensure edge cases are covered
+        - Verify error handling is tested
+        - Check for untested code paths
+        - Recommend additional test cases
+        
+        PERFORMANCE:
+        - Tests run quickly (prefer unit over integration when possible)
+        - Minimal database interactions
+        - Proper use of test doubles and stubs
+        - No unnecessary setup or teardown
+        
+        MAINTAINABILITY:
+        - Tests are DRY without sacrificing clarity
+        - Proper extraction of test helpers
+        - Good balance between shared examples and explicit tests
+        - Tests serve as documentation
+        
+        SOLID COMPLIANCE:
+        - Single Responsibility: Each test has one clear purpose
+        - Open/Closed: Tests don't break with refactoring
+        - Liskov Substitution: Tests work with subclasses
+        - Interface Segregation: Tests focus on public APIs
+        - Dependency Inversion: Tests use abstractions
+        
+        Provide actionable feedback to improve test quality and coverage.
+      allowed_tools:
+        - Read
+        - "Bash(bundle:*, rubocop:*)"

data/lib/claude_swarm/configuration.rb

@@ -76,6 +76,11 @@ module ClaudeSwarm
       # Validate required fields
       raise Error, "Instance '#{name}' missing required 'description' field" unless config["description"]
 
+      # Validate tool fields are arrays if present
+      validate_tool_field(name, config, "tools")
+      validate_tool_field(name, config, "allowed_tools")
+      validate_tool_field(name, config, "disallowed_tools")
+
       # Support both 'tools' (deprecated) and 'allowed_tools' for backward compatibility
       allowed_tools = config["allowed_tools"] || config["tools"] || []
 
@@ -129,6 +134,13 @@ module ClaudeSwarm
       end
     end
 
+    def validate_tool_field(instance_name, config, field_name)
+      return unless config.key?(field_name)
+
+      field_value = config[field_name]
+      raise Error, "Instance '#{instance_name}' field '#{field_name}' must be an array, got #{field_value.class.name}" unless field_value.is_a?(Array)
+    end
+
     def expand_path(path)
       Pathname.new(path).expand_path(@config_dir).to_s
     end

data/lib/claude_swarm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ClaudeSwarm
-  VERSION = "0.1.9"
+  VERSION = "0.1.10"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: claude_swarm
 version: !ruby/object:Gem::Version
-  version: 0.1.9
+  version: 0.1.10
 platform: ruby
 authors:
 - Paulo Arruda
@@ -59,6 +59,8 @@ files:
 - RELEASING.md
 - Rakefile
 - example/claude-swarm.yml
+- example/microservices-team.yml
+- example/test-generation.yml
 - exe/claude-swarm
 - lib/claude_swarm.rb
 - lib/claude_swarm/claude_code_executor.rb