claude_swarm 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d82adc5c9d855904f9809e4e2c8d9e34b7dbd5b2dd6ebec98e4072d6c81f3cf
-  data.tar.gz: 1faa01211ebe1b05fcc0dbf8b654b77e3512b4a4653b9169ef8c1b1e40226680
+  metadata.gz: a4597e6fdc67837e39ae1c175cc9dded454460ec00488d92aa81cab928737b4a
+  data.tar.gz: 46790b958dc4916a3df066ae7384e753c84c6c4cc624ac62754cab646f2c9102
 SHA512:
-  metadata.gz: 539f27f040ff91900bd8d88f925564f07ee4ad673eaaadcfdda228e44ca21adfd46a8be3dd40ae3a9b267b15ac5df4a5bd154d855f75ef85f1888522b71a716b
-  data.tar.gz: 81c0d46bf825684597d80271e7b0e7480b8c92e80c2465af1513b6d80f4dea2100b173261311243f5514e4aeb07bbdedebc0467b293415647bd8397161f98e8d
+  metadata.gz: f876006a8368881b252e675fab2b2999ae5a79574caff9db081ea7ea72402ce172524d7c6a2fe9c4b967502971a1cab83895dfd1f339592a516c58298450426a
+  data.tar.gz: b55120d481b8605e11a7024f1d6626f5c1fecca18627b6247e4b517c16e29d762166408a1753b1fc1b845c80f820f9701ce30ef2b0edb7e8a58da1b3635d0cc4

data/CHANGELOG.md

@@ -1,3 +1,14 @@
+## [0.1.4]
+
+### Added
+- **Required `description` field for instances**: Each instance must now have a description that clearly explains its role and specialization
+- Dynamic task tool descriptions that include both the instance name and description (e.g., "Execute a task using Agent frontend_dev. Frontend developer specializing in React and modern web technologies")
+- Description validation during configuration parsing - configurations without descriptions will fail with a clear error message
+
+### Changed
+- Updated all documentation examples to include meaningful instance descriptions
+- The `claude-swarm init` command now generates a template with description fields
+
 ## [0.1.3]
 
 ### Fixed

data/README.md

@@ -41,6 +41,7 @@ swarm:
   main: lead
   instances:
     lead:
+      description: "Team lead coordinating development efforts"
       directory: .
       model: opus
       connections: [frontend, backend]
@@ -49,6 +50,7 @@ swarm:
         - Edit
         - Bash
     frontend:
+      description: "Frontend specialist handling UI and user experience"
       directory: ./frontend
       model: sonnet
       tools:
@@ -56,6 +58,7 @@ swarm:
         - Write
         - Bash
     backend:
+      description: "Backend developer managing APIs and data layer"
       directory: ./backend  
       model: sonnet
       tools:
@@ -90,6 +93,7 @@ swarm:
   main: architect
   instances:
     architect:
+      description: "System architect coordinating between service teams"
       directory: .
       model: opus
       connections: [frontend_lead, backend_lead, mobile_lead, devops]
@@ -97,6 +101,7 @@ swarm:
       tools: [Read, Edit, WebSearch]
     
     frontend_lead:
+      description: "Frontend team lead overseeing React development"
       directory: ./web-frontend
       model: opus
       connections: [react_dev, css_expert]
@@ -104,18 +109,21 @@ swarm:
       tools: [Read, Edit, Bash]
     
     react_dev:
+      description: "React developer specializing in components and state management"
       directory: ./web-frontend/src
       model: sonnet
       prompt: "You specialize in React components and state management"
       tools: [Edit, Write, "Bash(npm:*)"]
     
     css_expert:
+      description: "CSS specialist handling styling and responsive design"
       directory: ./web-frontend/styles
       model: sonnet
       prompt: "You handle all CSS and styling concerns"
       tools: [Edit, Write, Read]
     
     backend_lead:
+      description: "Backend team lead managing API development"
       directory: ./api-server
       model: opus
       connections: [api_dev, database_expert]
@@ -123,18 +131,21 @@ swarm:
       tools: [Read, Edit, Bash]
     
     api_dev:
+      description: "API developer building REST endpoints"
       directory: ./api-server/src
       model: sonnet
       prompt: "You develop REST API endpoints"
       tools: [Edit, Write, Bash]
     
     database_expert:
+      description: "Database specialist managing schemas and migrations"
       directory: ./api-server/db
       model: sonnet
       prompt: "You handle database schema and migrations"
       tools: [Edit, Write, "Bash(psql:*, migrate:*)"]
     
     mobile_lead:
+      description: "Mobile team lead coordinating cross-platform development"
       directory: ./mobile-app
       model: sonnet
       connections: [ios_dev, android_dev]
@@ -142,18 +153,21 @@ swarm:
       tools: [Read, Edit]
     
     ios_dev:
+      description: "iOS developer building native Apple applications"
       directory: ./mobile-app/ios
       model: sonnet
       prompt: "You develop the iOS application"
       tools: [Edit, Write, "Bash(xcodebuild:*, pod:*)"]
     
     android_dev:
+      description: "Android developer creating native Android apps"
       directory: ./mobile-app/android
       model: sonnet
       prompt: "You develop the Android application"
       tools: [Edit, Write, "Bash(gradle:*, adb:*)"]
     
     devops:
+      description: "DevOps engineer managing CI/CD and infrastructure"
       directory: ./infrastructure
       model: sonnet
       prompt: "You handle CI/CD and infrastructure"
@@ -182,6 +196,10 @@ swarm:
 
 #### Instance Configuration
 
+Each instance must have:
+
+- **description** (required): Brief description of the agent's role (used in task tool descriptions)
+
 Each instance can have:
 
 - **directory**: Working directory for this instance (can use ~ for home)
@@ -193,6 +211,7 @@ Each instance can have:
 
 ```yaml
 instance_name:
+  description: "Specialized agent focused on specific tasks"
   directory: ~/project/path
   model: opus
   connections: [other_instance1, other_instance2]
@@ -273,6 +292,7 @@ swarm:
   main: architect
   instances:
     architect:
+      description: "Lead architect responsible for system design and code quality"
       directory: .
       model: opus
       connections: [frontend, backend, devops]
@@ -283,6 +303,7 @@ swarm:
         - WebSearch
         
     frontend:
+      description: "Frontend developer specializing in React and TypeScript"
       directory: ./frontend
       model: sonnet
       connections: [architect]
@@ -293,6 +314,7 @@ swarm:
         - Bash
         
     backend:
+      description: "Backend developer building APIs and services"
       directory: ./backend
       model: sonnet
       connections: [architect, database]
@@ -302,6 +324,7 @@ swarm:
         - Bash
         
     database:
+      description: "Database administrator managing data persistence"
       directory: ./db
       model: haiku
       tools:
@@ -309,6 +332,7 @@ swarm:
         - Bash
         
     devops:
+      description: "DevOps engineer handling deployment and infrastructure"
       directory: .
       model: sonnet
       connections: [architect]
@@ -327,6 +351,7 @@ swarm:
   main: lead_researcher
   instances:
     lead_researcher:
+      description: "Lead researcher coordinating analysis and documentation"
       directory: ~/research
       model: opus
       connections: [data_analyst, writer]
@@ -340,6 +365,7 @@ swarm:
           url: "https://arxiv-mcp.example.com"
           
     data_analyst:
+      description: "Data analyst processing research data and statistics"
       directory: ~/research/data
       model: sonnet
       tools:
@@ -353,6 +379,7 @@ swarm:
           args: ["--notebook-dir", "."]
           
     writer:
+      description: "Technical writer preparing research documentation"
       directory: ~/research/papers
       model: sonnet
       tools:
@@ -397,7 +424,7 @@ claude-swarm mcp-serve INSTANCE_NAME --config CONFIG_FILE --session-timestamp TI
    - Sessions can be reset via the MCP server interface
 4. **Main Instance Launch**: The main instance is launched with its MCP configuration, giving it access to all connected instances
 5. **Inter-Instance Communication**: Connected instances expose themselves as MCP servers with these tools:
-   - **task**: Execute tasks using Claude Code with configurable tools and return results
+   - **task**: Execute tasks using Claude Code with configurable tools and return results. The tool description includes the instance name and description (e.g., "Execute a task using Agent frontend_dev. Frontend developer specializing in React and TypeScript")
    - **session_info**: Get current Claude session information including ID and working directory
    - **reset_session**: Reset the Claude session for a fresh start
 6. **Session Management**: All session files are organized in `.claude-swarm/sessions/{timestamp}/`:

data/claude-swarm.yml

@@ -4,6 +4,7 @@ swarm:
   main: lead_developer
   instances:
     lead_developer:
+      description: "Lead developer coordinating the team and making architectural decisions"
       directory: .
       model: sonnet
       prompt: "You are the lead developer coordinating the team"
@@ -13,14 +14,8 @@ swarm:
     # Example instances (uncomment and modify as needed):
 
     frontend_dev:
+      description: "Frontend developer specializing in React and modern web technologies"
       directory: .
       model: sonnet
       prompt: "You specialize in frontend development with React, TypeScript, and modern web technologies"
       tools: [Read, Edit, Write, "Bash(npm:*)", "Bash(yarn:*)", "Bash(pnpm:*)"]
-      connections: [css_dev]
-
-    css_dev:
-      directory: .
-      model: sonnet
-      prompt: "You specialize in CSS development with Tailwind CSS, CSS Modules, and modern web technologies"
-      tools: [Read, Edit, Write, "Bash(npm:*)", "Bash(yarn:*)", "Bash(pnpm:*)"]

data/example/claude-swarm.yml

@@ -4,14 +4,14 @@ swarm:
   main: lead_rails_dev
   instances:
     lead_rails_dev:
-      role: "Lead Rails Developer"
+      description: "Senior Rails developer with 10+ years experience, coordinating the team and making architectural decisions"
       directory: .
       model: opus
       connections: [backend_dev, frontend_dev, test_engineer]
       prompt: "You are a senior Ruby on Rails developer with 10+ years of experience. You excel at Rails architecture, performance optimization, and best practices. You coordinate the team and make architectural decisions."
       
     backend_dev:
-      role: "Backend Rails Developer"
+      description: "Backend specialist focusing on Rails models, controllers, services, jobs, and API design"
       directory: .
       model: sonnet
       connections: [test_engineer]
@@ -23,14 +23,14 @@ swarm:
           args: ["exec", "hbt", "stdio"]
     
     frontend_dev:
-      role: "Rails Frontend Developer"
+      description: "Frontend Rails developer specializing in views, Stimulus/Turbo, and responsive UIs"
       directory: .
       model: sonnet
       connections: [test_engineer]
       prompt: "You are a Rails developer specializing in views, partials, helpers, Stimulus/Turbo, and asset pipeline. You excel at creating responsive UIs with Rails' built-in tools and modern CSS/JavaScript integration."
           
     test_engineer:
-      role: "Rails Test Engineer"
+      description: "Testing expert specializing in Minitest and Rails testing best practices"
       directory: .
       model: sonnet
       prompt: "You are a Rails testing expert specializing in Minitest. You write comprehensive unit tests, integration tests, system tests, and fixtures. You ensure high test coverage and follow Rails testing best practices including proper use of assertions, test helpers, and factories."

data/lib/claude_swarm/claude_mcp_server.rb

@@ -69,6 +69,13 @@ module ClaudeSwarm
         version: "1.0.0"
       )
 
+      # Set dynamic description for TaskTool based on instance config
+      if @instance_config[:description]
+        TaskTool.description "Execute a task using Agent #{@instance_config[:name]}. #{@instance_config[:description]}"
+      else
+        TaskTool.description "Execute a task using Agent #{@instance_config[:name]}"
+      end
+
       # Register tool classes (not instances)
       server.register_tool(TaskTool)
       server.register_tool(SessionInfoTool)
@@ -83,7 +90,7 @@ module ClaudeSwarm
       description "Execute a task using Claude Code"
 
       arguments do
-        required(:prompt).filled(:string).description("The task or question for Claude")
+        required(:prompt).filled(:string).description("The task or question for the agent")
         optional(:new_session).filled(:bool).description("Start a new session (default: false)")
         optional(:system_prompt).filled(:string).description("Override the system prompt for this request")
       end
@@ -157,7 +164,7 @@ module ClaudeSwarm
 
     class SessionInfoTool < FastMcp::Tool
       tool_name "session_info"
-      description "Get information about the current Claude session"
+      description "Get information about the current Claude session for this agent"
 
       arguments do
         # No arguments needed
@@ -176,7 +183,7 @@ module ClaudeSwarm
 
     class ResetSessionTool < FastMcp::Tool
       tool_name "reset_session"
-      description "Reset the Claude session, starting fresh on the next task"
+      description "Reset the Claude session for this agent, starting fresh on the next task"
 
       arguments do
         # No arguments needed

data/lib/claude_swarm/cli.rb

@@ -55,6 +55,8 @@ module ClaudeSwarm
                           desc: "Claude model to use (e.g., opus, sonnet)"
     method_option :prompt, aliases: "-p", type: :string,
                            desc: "System prompt for the instance"
+    method_option :description, type: :string,
+                                desc: "Description of the instance's role"
     method_option :tools, aliases: "-t", type: :array,
                           desc: "Allowed tools for the instance"
     method_option :mcp_config_path, type: :string,
@@ -71,6 +73,7 @@ module ClaudeSwarm
         directory: options[:directory],
         model: options[:model],
         prompt: options[:prompt],
+        description: options[:description],
         tools: options[:tools] || [],
         mcp_config_path: options[:mcp_config_path],
         vibe: options[:vibe]
@@ -105,6 +108,7 @@ module ClaudeSwarm
           main: lead_developer
           instances:
             lead_developer:
+              description: "Lead developer who coordinates the team and makes architectural decisions"
               directory: .
               model: sonnet
               prompt: "You are the lead developer coordinating the team"
@@ -114,24 +118,28 @@ module ClaudeSwarm
             # Example instances (uncomment and modify as needed):
 
             # frontend_dev:
+            #   description: "Frontend developer specializing in React and modern web technologies"
             #   directory: ./frontend
             #   model: sonnet
             #   prompt: "You specialize in frontend development with React, TypeScript, and modern web technologies"
             #   tools: [Read, Edit, Write, "Bash(npm:*)", "Bash(yarn:*)", "Bash(pnpm:*)"]
 
             # backend_dev:
+            #   description: "Backend developer focusing on APIs, databases, and server architecture"
             #   directory: ../other-app/backend
             #   model: sonnet
             #   prompt: "You specialize in backend development, APIs, databases, and server architecture"
             #   tools: [Read, Edit, Write, Bash]
 
             # devops_engineer:
+            #   description: "DevOps engineer managing infrastructure, CI/CD, and deployments"
             #   directory: .
             #   model: sonnet
             #   prompt: "You specialize in infrastructure, CI/CD, containerization, and deployment"
             #   tools: [Read, Edit, Write, "Bash(docker:*)", "Bash(kubectl:*)", "Bash(terraform:*)"]
 
             # qa_engineer:
+            #   description: "QA engineer ensuring quality through comprehensive testing"
             #   directory: ./tests
             #   model: sonnet
             #   prompt: "You specialize in testing, quality assurance, and test automation"

data/lib/claude_swarm/configuration.rb

@@ -72,6 +72,10 @@ module ClaudeSwarm
 
     def parse_instance(name, config)
       config ||= {}
+
+      # Validate required fields
+      raise Error, "Instance '#{name}' missing required 'description' field" unless config["description"]
+
       {
         name: name,
         directory: expand_path(config["directory"] || "."),
@@ -79,7 +83,8 @@ module ClaudeSwarm
         connections: Array(config["connections"]),
         tools: Array(config["tools"]),
         mcps: parse_mcps(config["mcps"] || []),
-        prompt: config["prompt"]
+        prompt: config["prompt"],
+        description: config["description"]
       }
     end
 

data/lib/claude_swarm/mcp_generator.rb

@@ -98,6 +98,8 @@ module ClaudeSwarm
       # Add optional arguments
       args.push("--prompt", instance[:prompt]) if instance[:prompt]
 
+      args.push("--description", instance[:description]) if instance[:description]
+
       args.push("--tools", instance[:tools].join(",")) if instance[:tools] && !instance[:tools].empty?
 
       args.push("--mcp-config-path", mcp_config_path(name))

data/lib/claude_swarm/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: claude_swarm
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Paulo Arruda