claude_swarm 1.0.4 → 1.0.6

data/lib/swarm_sdk/swarm.rb

@@ -4,25 +4,10 @@ module SwarmSDK
   # Swarm orchestrates multiple AI agents with shared rate limiting and coordination.
   #
   # This is the main user-facing API for SwarmSDK. Users create swarms using:
-  # - Direct API: Create Agent::Definition objects and add to swarm
-  # - Ruby DSL: Use Swarm::Builder for fluent configuration
-  # - YAML: Load from configuration files
-  #
-  # ## Direct API
-  #
-  #   swarm = Swarm.new(name: "Development Team")
-  #
-  #   backend_agent = Agent::Definition.new(:backend, {
-  #     description: "Backend developer",
-  #     model: "gpt-5",
-  #     system_prompt: "You build APIs and databases...",
-  #     tools: [:Read, :Edit, :Bash],
-  #     delegates_to: [:database]
-  #   })
-  #   swarm.add_agent(backend_agent)
-  #
-  #   swarm.lead = :backend
-  #   result = swarm.execute("Build authentication")
+  # - Ruby DSL: SwarmSDK.build { ... } (Recommended)
+  # - YAML String: SwarmSDK.load(yaml, base_dir:)
+  # - YAML File: SwarmSDK.load_file(path)
+  # - Direct API: Swarm.new + add_agent (Advanced)
   #
   # ## Ruby DSL (Recommended)
   #
@@ -39,14 +24,36 @@ module SwarmSDK
   #   end
   #   result = swarm.execute("Build authentication")
   #
-  # ## YAML API
+  # ## YAML String API
   #
-  #   swarm = Swarm.load("swarm.yml")
+  #   yaml = File.read("swarm.yml")
+  #   swarm = SwarmSDK.load(yaml, base_dir: "/path/to/project")
+  #   result = swarm.execute("Build authentication")
+  #
+  # ## YAML File API (Convenience)
+  #
+  #   swarm = SwarmSDK.load_file("swarm.yml")
+  #   result = swarm.execute("Build authentication")
+  #
+  # ## Direct API (Advanced)
+  #
+  #   swarm = Swarm.new(name: "Development Team")
+  #
+  #   backend_agent = Agent::Definition.new(:backend, {
+  #     description: "Backend developer",
+  #     model: "gpt-5",
+  #     system_prompt: "You build APIs and databases...",
+  #     tools: [:Read, :Edit, :Bash],
+  #     delegates_to: [:database]
+  #   })
+  #   swarm.add_agent(backend_agent)
+  #
+  #   swarm.lead = :backend
   #   result = swarm.execute("Build authentication")
   #
   # ## Architecture
   #
-  # All three APIs converge on Agent::Definition for validation.
+  # All APIs converge on Agent::Definition for validation.
   # Swarm delegates to specialized concerns:
   # - Agent::Definition: Validates configuration, builds system prompts
   # - AgentInitializer: Complex 5-pass agent setup
@@ -96,39 +103,14 @@ module SwarmSDK
       def apply_mcp_logging_configuration
         return if @mcp_logging_configured
 
+        SwarmSDK::MCP.lazy_load
+
         RubyLLM::MCP.configure do |config|
           config.log_level = @mcp_log_level
         end
 
         @mcp_logging_configured = true
       end
-
-      # Load swarm from YAML configuration file
-      #
-      # @param config_path [String] Path to YAML configuration file
-      # @return [Swarm] Configured swarm instance
-      def load(config_path)
-        config = Configuration.load(config_path)
-        swarm = config.to_swarm
-
-        # Apply hooks if any are configured (YAML-only feature)
-        if hooks_configured?(config)
-          Hooks::Adapter.apply_hooks(swarm, config)
-        end
-
-        # Store config reference for agent hooks (applied during initialize_agents)
-        swarm.config_for_hooks = config
-
-        swarm
-      end
-
-      private
-
-      def hooks_configured?(config)
-        config.swarm_hooks.any? ||
-          config.all_agents_hooks.any? ||
-          config.agents.any? { |_, agent_def| agent_def.hooks&.any? }
-      end
     end
 
     # Initialize a new Swarm
@@ -433,7 +415,7 @@ module SwarmSDK
     # @return [Array<Hash>] Array of warning hashes from all agent definitions
     #
     # @example
-    #   swarm = Swarm.load("config.yml")
+    #   swarm = SwarmSDK.load_file("config.yml")
     #   warnings = swarm.validate
     #   warnings.each do |warning|
     #     puts "⚠️  #{warning[:agent]}: #{warning[:model]} not found"

data/lib/swarm_sdk/tools/delegate.rb

@@ -43,8 +43,8 @@ module SwarmSDK
         @delegate_target = delegate_name.to_s
       end
 
-      # Build description dynamically based on delegate
-      description do
+      # Override description to return dynamic string based on delegate
+      def description
         "Delegate tasks to #{@delegate_name}. #{@delegate_description}"
       end
 

data/lib/swarm_sdk/tools/scratchpad/scratchpad_list.rb

@@ -12,8 +12,29 @@ module SwarmSDK
 
         description <<~DESC
           List all entries in scratchpad with their metadata.
-          Shows path, title, size, and last updated time for each entry.
-          Use this to discover what's stored in the scratchpad.
+
+          ## When to Use ScratchpadList
+
+          Use ScratchpadList to:
+          - Discover what content is available in the scratchpad
+          - Check what other agents have stored
+          - Find relevant entries before reading them
+          - Review all stored outputs and analysis
+          - Check entry sizes and last update times
+
+          ## Best Practices
+
+          - Use this before ScratchpadRead if you don't know what's stored
+          - Filter by prefix to narrow down results (e.g., 'notes/' lists all notes)
+          - Shows path, title, size, and last updated time for each entry
+          - Any agent can see all scratchpad entries
+          - Helps coordinate multi-agent workflows
+
+          ## Examples
+
+          - List all entries: (no prefix parameter)
+          - List notes only: prefix='notes/'
+          - List analysis results: prefix='analysis/'
         DESC
 
         param :prefix,

data/lib/swarm_sdk/tools/scratchpad/scratchpad_read.rb

@@ -12,8 +12,29 @@ module SwarmSDK
 
         description <<~DESC
           Read content from scratchpad.
-          Use this to retrieve temporary notes, results, or messages stored by any agent.
-          Any agent can read any scratchpad content.
+
+          ## When to Use ScratchpadRead
+
+          Use ScratchpadRead to:
+          - Retrieve previously stored content and outputs
+          - Access detailed analysis or results from earlier steps
+          - Read messages or notes left by other agents
+          - Access cached computed data
+          - Retrieve content that was too long for direct responses
+
+          ## Best Practices
+
+          - Any agent can read any scratchpad content
+          - Content is returned with line numbers for easy reference
+          - Use ScratchpadList first if you don't know what's stored
+          - Scratchpad data is temporary and lost when swarm ends
+          - For persistent data, use MemoryRead instead
+
+          ## Examples
+
+          - Read status: file_path='status'
+          - Read analysis: file_path='api_analysis'
+          - Read agent notes: file_path='notes/backend'
         DESC
 
         param :file_path,

data/lib/swarm_sdk/tools/scratchpad/scratchpad_write.rb

@@ -13,12 +13,29 @@ module SwarmSDK
 
         description <<~DESC
           Store content in scratchpad for temporary cross-agent communication.
-          Use this for quick notes, intermediate results, or coordination messages.
-          Any agent can read this content. Data is lost when the swarm ends.
 
-          For persistent storage that survives across sessions, use MemoryWrite instead.
+          ## When to Use Scratchpad
 
-          Choose a simple, descriptive path. Examples: 'status', 'result', 'notes/agent_x'
+          Use ScratchpadWrite to:
+          - Store detailed outputs, analysis, or results that are too long for direct responses
+          - Share information that would otherwise clutter your responses
+          - Store intermediate results during multi-step tasks
+          - Leave coordination messages for other agents
+          - Cache computed data for quick retrieval
+
+          ## Best Practices
+
+          - Choose simple, descriptive paths: 'status', 'result', 'notes/agent_x'
+          - Use hierarchical paths for organization: 'analysis/step1', 'analysis/step2'
+          - Keep entries focused - one piece of information per entry
+          - Any agent can read scratchpad content
+          - Data is lost when the swarm ends (use MemoryWrite for persistent storage)
+          - Maximum 1MB per entry
+
+          ## Examples
+
+          Good paths: 'status', 'api_analysis', 'test_results', 'notes/backend'
+          Bad paths: 'scratch/temp/file123.txt', 'output.log'
         DESC
 
         param :file_path,

data/lib/swarm_sdk/tools/stores/storage.rb

@@ -14,11 +14,11 @@ module SwarmSDK
       # - Search capabilities: Glob patterns and grep-style content search
       # - Thread-safe: Mutex-protected operations
       class Storage
-        # Maximum size per entry (1MB)
-        MAX_ENTRY_SIZE = 1_000_000
+        # Maximum size per entry (3MB)
+        MAX_ENTRY_SIZE = 3_000_000
 
-        # Maximum total storage size (100MB)
-        MAX_TOTAL_SIZE = 100_000_000
+        # Maximum total storage size (100GB)
+        MAX_TOTAL_SIZE = 100_000_000_000
 
         # Represents a single storage entry with metadata
         Entry = Struct.new(:content, :title, :updated_at, :size, keyword_init: true)

data/lib/swarm_sdk/tools/think.rb

@@ -82,7 +82,10 @@ module SwarmSDK
         required: true
 
       def execute(**kwargs)
-        "Thought noted."
+        <<~RESP
+          Thought noted.
+        RESP
+        # <system-reminder>The user cannot see your thoughts. You MUST NOT stop without giving the user a response.</system-reminder>
       end
 
       private

data/lib/swarm_sdk/tools/todo_write.rb

@@ -8,17 +8,17 @@ module SwarmSDK
     # Each agent maintains its own independent todo list.
     class TodoWrite < RubyLLM::Tool
       description <<~DESC
-        Use this tool to create and manage a structured task list for your current coding session. This helps you track progress, organize complex tasks, and demonstrate thoroughness to the user.
+        Use this tool to create and manage a structured task list for your current work session. This helps you track progress, organize complex tasks, and demonstrate thoroughness to the user.
         It also helps the user understand the progress of the task and overall progress of their requests.
 
         ## When to Use This Tool
         Use this tool proactively in these scenarios:
 
         **CRITICAL**: Follow this workflow for multi-step tasks:
-        1. FIRST: Analyze the task scope (search files, read code, understand requirements)
-        2. SECOND: Create a COMPLETE todo list with ALL known tasks BEFORE starting implementation
+        1. FIRST: Analyze the task scope (gather information, understand requirements)
+        2. SECOND: Create a COMPLETE todo list with ALL known tasks BEFORE starting work
         3. THIRD: Execute tasks, marking in_progress → completed as you work
-        4. ONLY add new todos if unexpected work is discovered during implementation
+        4. ONLY add new todos if unexpected work is discovered during execution
 
         Use the todo list when:
         1. Complex multi-step tasks - When a task requires 3 or more distinct steps or actions
@@ -27,7 +27,7 @@ module SwarmSDK
         4. User provides multiple tasks - When users provide a list of things to be done (numbered or comma-separated)
         5. After receiving new instructions - After analyzing scope, create complete todo list before starting work
         6. When you start working on a task - Mark it as in_progress BEFORE beginning work. Ideally you should only have one todo as in_progress at a time
-        7. After completing a task - Mark it as completed and add any new follow-up tasks discovered during implementation
+        7. After completing a task - Mark it as completed and add any new follow-up tasks discovered during execution
 
         ## When NOT to Use This Tool
 
@@ -73,9 +73,21 @@ module SwarmSDK
           - Create specific, actionable items
           - Break complex tasks into smaller, manageable steps
           - Use clear, descriptive task names
-          - Always provide both forms:
-            - content: "Fix authentication bug"
-            - activeForm: "Fixing authentication bug"
+          - Always provide both forms (content and activeForm)
+
+        ## Examples
+
+        **Coding Tasks**:
+        - content: "Fix authentication bug in login handler"
+        - activeForm: "Fixing authentication bug in login handler"
+
+        **Non-Coding Tasks**:
+        - content: "Analyze customer feedback from Q4 survey"
+        - activeForm: "Analyzing customer feedback from Q4 survey"
+
+        **Research Tasks**:
+        - content: "Research best practices for API rate limiting"
+        - activeForm: "Researching best practices for API rate limiting"
 
         When in doubt, use this tool. Being proactive with task management demonstrates attentiveness and ensures you complete all requirements successfully.
       DESC

data/lib/swarm_sdk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SwarmSDK
-  VERSION = "2.1.1"
+  VERSION = "2.1.3"
 end