claude_swarm 1.0.9 → 1.0.11

data/docs/v2/guides/complete-tutorial.md

@@ -930,12 +930,12 @@ swarm:
 **How delegation works**:
 1. You send task to `developer`
 2. Developer writes code using Write tool
-3. Developer calls `DelegateTaskToReviewer(task: "Review this code")`
+3. Developer calls `WorkWithReviewer(message: "Review this code")`
 4. Reviewer analyzes code and returns feedback
 5. Developer receives feedback and can iterate
 6. Developer returns final result to you
 
-**The delegation tool**: When you configure `delegates_to: [reviewer]`, the developer automatically gets a `DelegateTaskToReviewer` tool.
+**The delegation tool**: When you configure `delegates_to: [reviewer]`, the developer automatically gets a `WorkWithReviewer` tool.
 
 ### 3.2 Multi-Level Delegation
 
@@ -2858,7 +2858,93 @@ project/
 └── .env                        # API keys
 ```
 
-### 8.3 Testing Strategies
+### 8.3 Reusable Agent Definitions (Global Registry)
+
+For large projects, define agents once and reuse them across multiple swarms.
+
+**Register agents globally:**
+```ruby
+# agents/backend.rb
+SwarmSDK.agent :backend do
+  model "claude-sonnet-4"
+  description "Backend developer"
+  system_prompt "You build APIs and databases"
+  tools :Read, :Edit, :Bash
+  # Note: Don't set delegates_to here - it's swarm-specific!
+end
+
+# agents/database.rb
+SwarmSDK.agent :database do
+  model "claude-sonnet-4"
+  description "Database specialist"
+  system_prompt "You design schemas and write migrations"
+  tools :Read, :Edit
+end
+```
+
+**Reference in swarms (set delegation per-swarm):**
+```ruby
+# Load agent definitions first
+require_relative "agents/backend"
+require_relative "agents/database"
+
+# Reference by name and configure delegation (swarm-specific)
+swarm = SwarmSDK.build do
+  name "Dev Team"
+  lead :backend
+
+  agent :backend do
+    delegates_to :database  # Delegation is swarm-specific
+  end
+  agent :database    # Pulls from registry as-is
+end
+```
+
+**Override other registry settings:**
+```ruby
+swarm = SwarmSDK.build do
+  name "Extended Team"
+  lead :backend
+
+  # Registry config applied first, then override block
+  agent :backend do
+    delegates_to :database, :cache  # Set delegation for this swarm
+    tools :CustomTool               # Adds to registry tools
+    timeout 300                     # Overrides registry timeout
+  end
+end
+```
+
+**Workflow auto-resolution:**
+Agents referenced in workflow nodes automatically resolve from the global registry:
+
+```ruby
+SwarmSDK.workflow do
+  name "Pipeline"
+  start_node :build
+
+  # No need to define :backend here - auto-resolved from registry!
+  node :build do
+    agent(:backend)
+  end
+end
+```
+
+**Testing with registry:**
+```ruby
+# Clear registry between tests
+def setup
+  SwarmSDK.clear_agent_registry!
+end
+```
+
+**Benefits:**
+- **Code reuse**: Define agents once, use in multiple swarms
+- **Separation of concerns**: Agent definitions in dedicated files
+- **Organization**: Large projects with many agents stay manageable
+- **DRY principle**: No duplication of agent configurations
+
+### 8.4 Testing Strategies
 
 **Unit test agents**:
 ```ruby
@@ -2920,7 +3006,7 @@ allow(LLM).to receive(:chat).and_return(
 )
 ```
 
-### 8.4 Performance Optimization
+### 8.5 Performance Optimization
 
 **1. Choose appropriate models**:
 ```ruby
@@ -2993,7 +3079,7 @@ node :summarizer do
 end
 ```
 
-### 8.5 Security Considerations
+### 8.6 Security Considerations
 
 **1. Restrict file access**:
 ```ruby
@@ -3099,7 +3185,7 @@ end
 - **Priority**: Explicit parameter > Global setting > Environment variable > Default (true)
 - **Non-breaking**: Defaults to `true` for backward compatibility
 
-### 8.6 Cost Management
+### 8.7 Cost Management
 
 **Track costs in real-time**:
 ```ruby
@@ -3153,7 +3239,7 @@ end
 - [ ] Batch similar operations
 - [ ] Monitor and set cost alerts
 
-### 8.7 Monitoring and Observability
+### 8.8 Monitoring and Observability
 
 **Structured logging to files**:
 ```ruby
@@ -3205,7 +3291,7 @@ end
 }
 ```
 
-### 8.8 Common Patterns Summary
+### 8.9 Common Patterns Summary
 
 **Pattern: Code Review Workflow**
 ```
@@ -3263,7 +3349,7 @@ You've now learned **100% of SwarmSDK features**:
 
 ✅ **Part 7: Production Features** - Structured logging, token/cost tracking, error handling, validation, document conversion
 
-✅ **Part 8: Best Practices** - Architecture patterns, testing strategies, performance optimization, security, cost management, monitoring
+✅ **Part 8: Best Practices** - Architecture patterns, reusable agent definitions (global registry), testing strategies, performance optimization, security, cost management, monitoring
 
 ## Next Steps
 

data/docs/v2/guides/getting-started.md

@@ -124,10 +124,10 @@ An **agent** is an AI with specific capabilities and constraints:
 
 Delegation is how agents collaborate. When an agent is configured with `delegates_to: [other_agent]`, it gains a special delegation tool.
 
-**Delegation tool naming**: Tools are named `DelegateTaskTo{AgentName}` where AgentName is capitalized. For example:
-- `delegates_to: [reviewer]` → creates `DelegateTaskToReviewer` tool
-- `delegates_to: [backend]` → creates `DelegateTaskToBackend` tool
-- `delegates_to: [qa_tester]` → creates `DelegateTaskToQa_tester` tool
+**Delegation tool naming**: Tools are named `WorkWith{AgentName}` where AgentName is capitalized. For example:
+- `delegates_to: [reviewer]` → creates `WorkWithReviewer` tool
+- `delegates_to: [backend]` → creates `WorkWithBackend` tool
+- `delegates_to: [qa_tester]` → creates `WorkWithQa_tester` tool
 
 **Example flow**:
 1. You send "Build a login page" to the **lead** agent
@@ -192,7 +192,7 @@ Tools are functions agents call to interact with the world. SwarmSDK provides:
 | **Web** | WebFetch | Fetch and process web content |
 | **Task Management** | TodoWrite | Track progress on multi-step tasks |
 | **Shared Scratchpad** | ScratchpadWrite, ScratchpadRead, ScratchpadList | Share work-in-progress between agents (volatile) |
-| **Per-Agent Memory** | MemoryWrite, MemoryRead, MemoryEdit, MemoryMultiEdit, MemoryGlob, MemoryGrep, MemoryDelete | Persistent learning and knowledge storage (opt-in) |
+| **Per-Agent Memory** | MemoryWrite, MemoryRead, MemoryEdit, MemoryGlob, MemoryGrep, MemoryDelete | Persistent learning and knowledge storage (opt-in) |
 | **Reasoning** | Think | Extended reasoning for complex problems |
 
 **Default tools**: Every agent automatically gets **Read, Grep, and Glob** unless you explicitly disable them with `disable_default_tools: true`. Scratchpad tools (ScratchpadWrite, ScratchpadRead, ScratchpadList) are opt-in via `scratchpad: :enabled`.
@@ -750,7 +750,7 @@ swarm = SwarmSDK.load_file('swarm.yml')
 result = swarm.execute("Write a function to validate email addresses and get it reviewed")
 ```
 
-**How delegation works**: The coder writes code, then calls the `DelegateTaskToReviewer` tool to get feedback. The reviewer analyzes and returns suggestions. The coder can iterate based on feedback.
+**How delegation works**: The coder writes code, then calls the `WorkWithReviewer` tool to get feedback. The reviewer analyzes and returns suggestions. The coder can iterate based on feedback.
 
 ### Using Multiple Tools
 
@@ -1026,7 +1026,7 @@ swarm = SwarmSDK.build do
     model "gpt-4"
   end
 end
-# Leader won't have DelegateTaskToHelper tool!
+# Leader won't have WorkWithHelper tool!
 ```
 
 **Solution**:
@@ -1239,6 +1239,8 @@ Congratulations! You've learned the fundamentals of SwarmSDK.
 
 **Agent Delegation Patterns**: Learn advanced collaboration strategies like hierarchical delegation, peer collaboration, and specialist chains.
 
+**Reusable Agent Definitions**: Use the Global Agent Registry (`SwarmSDK.agent`) to define agents once and reuse them across multiple swarms—perfect for large projects with shared agents.
+
 **Permissions System**: Discover how to restrict agents to specific directories, prevent dangerous commands, and create secure multi-agent systems.
 
 **Hooks and Customization**: Master pre/post hooks for tool calls, prompt injection, and workflow automation.
@@ -1412,7 +1414,7 @@ tools :Bash         # Run shell commands
 agent :leader do
   description "Coordinates work"
   model "gpt-4"
-  delegates_to :worker  # Creates DelegateTaskToWorker tool
+  delegates_to :worker  # Creates WorkWithWorker tool
 end
 
 agent :worker do

data/docs/v2/guides/memory-adapters.md

@@ -193,6 +193,47 @@ end
 # MyAdapter.new(namespace: "researcher", table_name: "memory_entries")
 ```
 
+### YAML Configuration
+
+Custom adapters also work seamlessly with YAML configuration. All YAML keys (except `directory`, `adapter`, `mode`) are automatically passed to the adapter constructor:
+
+```yaml
+# swarm.yml
+agents:
+  researcher:
+    memory:
+      adapter: multi_bank_postgres
+      agent_id: researcher
+      discovery_threshold: 0.5
+      discovery_threshold_short: 0.3
+      semantic_weight: 0.6
+      default_bank: working
+      banks:
+        working: { max_size: 10485760 }
+        long_term: { max_size: 52428800 }
+```
+
+This configuration creates an adapter with:
+```ruby
+MultiBankPostgresAdapter.new(
+  agent_id: "researcher",
+  discovery_threshold: 0.5,
+  discovery_threshold_short: 0.3,
+  semantic_weight: 0.6,
+  default_bank: "working",
+  banks: {
+    "working" => { "max_size" => 10485760 },
+    "long_term" => { "max_size" => 52428800 }
+  }
+)
+```
+
+**Benefits:**
+- ✅ No code changes needed for configuration
+- ✅ Per-agent customization via YAML
+- ✅ All options passed directly to adapter
+- ✅ Each adapter validates its own requirements
+
 ---
 
 ## Example: ActiveRecord Adapter (PostgreSQL/Rails)