claude_swarm 1.0.0 → 1.0.2

data/examples/learning-assistant/assistant.md

@@ -0,0 +1,7 @@
+---
+name: assistant
+description: An assistant that learns and builds knowledge over time
+model: sonnet
+---
+
+You are an assistant.

data/examples/learning-assistant/example-memories/concept-example.md

@@ -0,0 +1,90 @@
+---
+type: concept
+domain: programming/ruby
+confidence: high
+last_verified: 2025-01-15
+tags: [ruby, classes, oop, inheritance, objects]
+related:
+  - memory://memory/concepts/programming/ruby/modules.md
+  - memory://memory/concepts/programming/oop/inheritance.md
+  - memory://memory/skills/programming/ruby/create-class.md
+source: documentation
+---
+
+# Ruby Classes
+
+## Definition
+
+Classes are blueprints for creating objects in Ruby. They define both the structure (instance variables) and behavior (methods) that objects created from the class will have.
+
+## Core Syntax
+
+```ruby
+class Person
+  # Constructor
+  def initialize(name, age)
+    @name = name  # Instance variable
+    @age = age
+  end
+
+  # Instance method
+  def introduce
+    "Hi, I'm #{@name} and I'm #{@age} years old"
+  end
+
+  # Class method
+  def self.species
+    "Homo sapiens"
+  end
+end
+
+# Usage
+person = Person.new("Alice", 30)
+person.introduce           # => "Hi, I'm Alice and I'm 30 years old"
+Person.species            # => "Homo sapiens"
+```
+
+## Key Characteristics
+
+1. **Instantiation**: Create objects with `.new`
+2. **Instance variables**: Start with `@`, unique per instance
+3. **Instance methods**: Define object behavior
+4. **Class methods**: Shared across all instances (use `self.`)
+5. **Inheritance**: Single inheritance with `<`
+6. **Visibility**: public (default), private, protected
+
+## Inheritance
+
+```ruby
+class Employee < Person
+  def initialize(name, age, role)
+    super(name, age)  # Call parent constructor
+    @role = role
+  end
+
+  def introduce
+    super + " and I work as a #{@role}"
+  end
+end
+```
+
+## When to Use
+
+- Modeling real-world entities (User, Product, Order)
+- Need multiple instances with shared behavior
+- Building reusable, stateful components
+- Implementing object-oriented patterns
+
+## Relationships
+
+- **Similar to**: Modules (but modules can't be instantiated)
+- **Part of**: Object-Oriented Programming paradigm
+- **Used with**: Inheritance, Mixins, Composition
+- **Differs from**: Structs (simpler, less flexible)
+
+## Common Patterns
+
+1. **Encapsulation**: Hide internal state with private methods
+2. **Delegation**: Forward calls to composed objects
+3. **Factory pattern**: Class methods that return instances
+4. **Template method**: Parent class defines structure, children implement details

data/examples/learning-assistant/example-memories/experience-example.md

@@ -0,0 +1,66 @@
+---
+type: experience
+category: success
+domain: swarm/memory
+date: 2025-01-15
+tags: [learning, first-success, memory-system, milestone]
+related:
+  - memory://memory/skills/swarm/scratchpad-write.md
+  - memory://memory/concepts/swarm/scratchpad-system.md
+source: experimentation
+---
+
+# First Successful Memory Write
+
+## Context
+
+This was my first attempt at using the memory system. I needed to store knowledge about how to use the MemoryWrite tool.
+
+## What I Did
+
+1. Chose appropriate path: `memory/skills/swarm/scratchpad-write.md`
+2. Created YAML frontmatter with all required fields
+3. Wrote structured markdown with examples
+4. Successfully stored the entry
+5. Verified by reading it back with MemoryRead
+
+## Challenges Faced
+
+- Initially unsure about path structure (should it be `skills/swarm/` or `swarm/skills/`)
+- Wasn't sure how detailed the frontmatter should be
+- Questioned whether to use `.md` extension
+
+## What Worked
+
+- Following the memory schema from system prompt
+- Using kebab-case for paths
+- Including concrete examples in the content
+- Marking confidence honestly (medium at first)
+
+## Outcome
+
+Successfully created my first memory entry. I can now read it back and use it as a template for future entries.
+
+## Lesson Learned
+
+**Key insight**: The memory system works best when you:
+1. Follow the schema strictly (don't improvise paths)
+2. Write immediately after learning (don't batch)
+3. Include rich frontmatter (makes searching easier)
+4. Use examples (makes recall more useful)
+
+## Apply This Pattern When
+
+- Starting to use any new tool or system
+- Building a new skill
+- Need to remember a process
+- Want to capture a lesson learned
+
+## Evolution
+
+This entry will serve as a template and reminder for how to use the memory system effectively. As I gain more experience, I'll update it with additional insights.
+
+## Confidence Growth
+
+- **Day 1** (2025-01-15): confidence: medium - First attempt, learning
+- **Future**: Will increase to high after 5+ successful uses

data/examples/learning-assistant/example-memories/fact-example.md

@@ -0,0 +1,76 @@
+---
+type: fact
+domain: people
+confidence: high
+last_verified: 2025-01-15
+tags: [user, paulo, preferences, communication]
+source: user
+---
+
+# User: Paulo
+
+## Role & Context
+
+- **Primary user** and project owner
+- **Working on**: SwarmSDK and SwarmCLI Ruby gems
+- **Project location**: `/Users/paulo/src/github.com/parruda/claude-swarm`
+- **Platform**: macOS (Darwin 24.6.0)
+- **Ruby version**: 3.4.2
+
+## Communication Preferences
+
+### Style
+- Prefers **direct, concise** communication
+- Values **professional, clean** code
+- Appreciates **thorough explanations** when asked
+- Likes when I explain my reasoning
+
+### Expectations
+- **Production-ready** implementations (not prototypes)
+- **Comprehensive testing** (all tests must pass)
+- **Clean code** (RuboCop compliance)
+- **Proper documentation** (accurate, current)
+
+### Work Style
+- Asks **clarifying questions** when unsure
+- Provides **specific feedback** on implementations
+- Iterates quickly - makes decisions and moves forward
+- Values **best practices** and **maintainability**
+
+## Project Context
+
+### SwarmSDK
+- Building next-generation multi-agent orchestration framework
+- Focuses on single-process execution using RubyLLM
+- Clean separation between SDK (lib/swarm_sdk/) and CLI (lib/swarm_cli/)
+- Strong emphasis on testing and code quality
+
+### Development Practices
+- Uses Zeitwerk for autoloading
+- Follows Ruby/RuboCop conventions
+- Comprehensive test coverage required
+- Documentation must reflect code reality (no "New!" announcements)
+
+## How to Work with Paulo
+
+1. **Be direct** - No fluff, get to the point
+2. **Be thorough** - Complete implementations, not partial
+3. **Ask when unsure** - Don't guess architectural decisions
+4. **Test everything** - All tests must pass before completion
+5. **Document accurately** - Docs describe current state, not history
+
+## Things Paulo Cares About
+
+- **Separation of concerns** - SDK vs CLI code must never mix
+- **Professional code quality** - This is open source, must look great
+- **No slop** - No methods that exist only for tests
+- **Proper delegation** - Consult experts via MCP tools
+- **Breaking changes** - Be explicit about them
+
+## Things to Avoid
+
+- Creating unnecessary files (especially markdown/README files proactively)
+- Using emojis unless explicitly requested
+- Making assumptions about architecture without asking
+- Mixing SDK and CLI code
+- Incomplete implementations

data/examples/learning-assistant/example-memories/memory-index.md

@@ -0,0 +1,78 @@
+---
+type: index
+last_updated: 2025-01-15
+total_entries: 8
+---
+
+# Memory Index
+
+My current knowledge base as of 2025-01-15.
+
+## Quick Stats
+- **Concepts**: 2
+- **Facts**: 3
+- **Skills**: 2
+- **Experiences**: 1
+
+## Expertise Areas
+
+### Strong (5+ entries)
+- Ruby programming (3 concepts + 2 skills)
+
+### Developing (2-4 entries)
+- User context (3 facts)
+
+### Learning (1 entry)
+- Testing practices (1 experience)
+
+## Recent Activity (Last 7 Days)
+
+- **2025-01-15**: Learned Minitest testing → skills/programming/ruby/minitest-testing.md
+- **2025-01-15**: Understood user preferences → facts/people/paulo.md
+- **2025-01-15**: Discovered project structure → facts/environment/project-structure.md
+- **2025-01-14**: Learned about Ruby classes → concepts/programming/ruby/classes.md
+- **2025-01-14**: Mastered MemoryWrite → skills/swarm/scratchpad-write.md
+
+## Knowledge Gaps (To Explore)
+
+Questions I need to answer:
+- How does the SwarmSDK delegation system work?
+- What are the best practices for organizing large memory hierarchies?
+- How should I handle conflicting information from different sources?
+
+## Category Breakdown
+
+### Concepts
+- `concepts/programming/ruby/` (2 entries)
+  - classes.md
+  - modules.md
+
+### Facts
+- `facts/people/` (1 entry)
+  - paulo.md
+- `facts/environment/` (2 entries)
+  - project-structure.md
+  - preferences.md
+
+### Skills
+- `skills/programming/ruby/` (1 entry)
+  - minitest-testing.md
+- `skills/swarm/` (1 entry)
+  - scratchpad-write.md
+
+### Experience
+- `experience/successes/` (1 entry)
+  - 2025-01-15-first-memory-write.md
+
+## Memory Health
+
+- **Total Size**: ~50KB / 100MB (0.05% used)
+- **Organization**: Good - clear hierarchy
+- **Cross-references**: 8 links across entries
+- **Confidence Distribution**: High: 6, Medium: 2, Low: 0
+
+## Next Session Goals
+
+1. Learn more about the SwarmSDK agent system
+2. Build skills in file operations (Read, Write, Edit)
+3. Understand the user's current project goals

data/examples/learning-assistant/example-memories/skill-example.md

@@ -0,0 +1,168 @@
+---
+type: skill
+domain: swarm/memory
+difficulty: beginner
+confidence: high
+last_verified: 2025-01-15
+prerequisites: []
+tags: [swarm, scratchpad, memory, learning]
+related:
+  - memory://memory/concepts/swarm/scratchpad-system.md
+  - memory://memory/skills/swarm/scratchpad-read.md
+source: experimentation
+---
+
+# Writing to Memory Memory
+
+## What This Does
+
+Stores knowledge in the Memory memory system for later retrieval. This is how you persist everything you learn.
+
+## When to Use
+
+- **Immediately** after learning something new
+- When user provides information
+- After solving a problem
+- When discovering how something works
+- After experimenting with tools
+
+## Steps
+
+1. **Determine the category**: concept/fact/skill/experience
+2. **Choose the path**: Follow memory hierarchy conventions
+3. **Prepare content**: YAML frontmatter + markdown body
+4. **Write**: Use MemoryWrite tool
+5. **Verify**: Optionally read back to confirm
+
+## Tool Signature
+
+```
+MemoryWrite(
+  file_path: "memory/{category}/{domain}/{name}.md",
+  content: "{yaml-frontmatter}\n\n{markdown-content}",
+  title: "{Brief descriptive title}"
+)
+```
+
+## Example: Storing a Concept
+
+```
+MemoryWrite(
+  file_path: "memory/concepts/programming/ruby/classes.md",
+  content: "---
+type: concept
+domain: programming/ruby
+confidence: high
+last_verified: 2025-01-15
+tags: [ruby, classes, oop]
+related: []
+source: documentation
+---
+
+# Ruby Classes
+
+Classes are blueprints for objects...
+",
+  title: "Ruby Classes Concept"
+)
+```
+
+## Example: Storing a Fact
+
+```
+MemoryWrite(
+  file_path: "memory/facts/people/paulo.md",
+  content: "---
+type: fact
+domain: people
+confidence: high
+last_verified: 2025-01-15
+tags: [user, preferences]
+source: user
+---
+
+# User: Paulo
+
+## Role
+Primary user and project owner
+
+## Preferences
+- Direct communication
+- Clean code
+",
+  title: "User Paulo Profile"
+)
+```
+
+## Common Patterns
+
+### Learning from User
+```
+User tells you something
+→ Categorize it (usually 'fact')
+→ Choose domain (people/environment/technical)
+→ Write immediately
+→ Mark source: user, confidence: high
+```
+
+### Learning from Experimentation
+```
+You discover how a tool works
+→ Category: skill or concept
+→ Domain: the tool's domain
+→ Write with examples
+→ Mark source: experimentation
+→ Mark confidence: medium (until verified multiple times)
+```
+
+### Learning from Documentation
+```
+You fetch documentation with WebFetch
+→ Extract key information
+→ Write as concept or fact
+→ Mark source: documentation, confidence: high
+→ Include cross-references
+```
+
+## Best Practices
+
+1. **Write immediately** - Don't wait until end of task
+2. **Complete frontmatter** - All fields matter
+3. **Descriptive titles** - Make entries discoverable
+4. **Rich content** - Include examples, context, relationships
+5. **Update index** - After 5-10 new writes
+6. **Verify paths** - Use kebab-case, lowercase, specific domains
+
+## Common Mistakes to Avoid
+
+❌ **Vague paths**: `memory/ruby.md` (too general)
+✅ **Specific paths**: `memory/concepts/programming/ruby/classes.md`
+
+❌ **Missing frontmatter**: Just markdown content
+✅ **Complete frontmatter**: All metadata fields
+
+❌ **Batching**: Learning 10 things, writing at end
+✅ **Immediate**: Learn one thing, write immediately
+
+❌ **Generic titles**: "Information about Ruby"
+✅ **Specific titles**: "Ruby Classes Concept"
+
+## Troubleshooting
+
+**Problem**: Entry too large (>1MB)
+- **Solution**: Break into multiple related entries
+
+**Problem**: Don't know where to store something
+- **Solution**: Think about type first (concept/fact/skill/experience), then domain
+
+**Problem**: Duplicate knowledge exists
+- **Solution**: Search first with Glob/Grep, then decide to update or create new
+
+## Success Indicators
+
+You're doing it right when:
+- ✅ You can answer questions from memory without re-learning
+- ✅ Your memory/index.md accurately reflects what you know
+- ✅ You find relevant entries quickly with Glob/Grep
+- ✅ Knowledge builds on previous knowledge (cross-references work)
+- ✅ You become faster at familiar tasks over time

data/examples/learning-assistant/learning_assistant.rb

@@ -0,0 +1,34 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "swarm_sdk"
+
+# Example: Learning Assistant with Persistent Memory
+#
+# This demonstrates a continuously learning agent that:
+# - Starts with zero knowledge
+# - Learns through tools and user interaction
+# - Stores knowledge in organized memory
+# - Recalls from memory in future sessions
+# - Evolves and improves over time
+
+SwarmSDK.build do
+  name("Learning Assistant")
+  lead(:assistant)
+  use_scratchpad(true) # default
+
+  # Load agent from markdown file (includes system prompt with memory schema)
+  agent(:assistant, File.read("examples/learning-assistant/assistant.md")) do
+    # Configure persistent memory for learning
+
+    memory do
+      adapter :filesystem # default, can omit
+      directory ".swarm/learning-assistant"
+    end
+
+    # Memory tools will be automatically added because memory is configured
+    # Default tools are still available: Read, Grep, Glob, WebFetch, Think, TodoWrite
+    # Scratchpad tools are available: ScratchpadWrite, ScratchpadRead, ScratchpadList
+  end
+end

data/examples/learning-assistant/learning_assistant.yml

@@ -0,0 +1,20 @@
+version: 2
+
+swarm:
+  name: Learning Assistant
+  lead: assistant
+  use_scratchpad: true  # default
+
+  agents:
+    assistant:
+      description: An assistant that learns and builds knowledge over time
+      agent_file: examples/learning-assistant/assistant.md
+
+      # Configure persistent memory for learning
+      memory:
+        adapter: filesystem  # default, can omit
+        directory: .swarm/learning-assistant
+
+      # Memory tools automatically added because memory is configured
+      # Default tools: Read, Grep, Glob, WebFetch, Think, TodoWrite
+      # Scratchpad tools: ScratchpadWrite, ScratchpadRead, ScratchpadList

data/examples/v2/dsl/01_basic.rb

@@ -0,0 +1,44 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Manual Test 1: Basic Swarm Configuration
+#
+# Tests: name, lead, basic agent with minimal config
+#
+# Run: bundle exec ruby -Ilib lib/swarm_sdk/examples/dsl/01_basic.rb
+
+require "swarm_sdk"
+require_relative "../../../swarm_sdk/swarm_builder"
+require_relative "../../../swarm_sdk/agent_builder"
+
+ENV["OPENAI_API_KEY"] = "test-key"
+
+swarm = SwarmSDK.build do
+  name("Basic Test Swarm")
+  lead(:simple_agent)
+
+  agent(:simple_agent) do
+    model("gpt-5-nano")
+    provider("openai")
+    system_prompt("You are a simple test agent. Answer questions concisely.")
+    description("Simple agent for basic DSL testing")
+    tools(:Read)
+  end
+end
+
+puts "✅ Swarm built successfully!"
+puts "Name: #{swarm.name}"
+puts "Lead: #{swarm.lead_agent}"
+puts "Agents: #{swarm.agent_names.join(", ")}"
+puts ""
+puts "Running test query..."
+
+result = swarm.execute("What is 2 + 2?")
+
+puts ""
+puts "Result: #{result.content}"
+puts "Success: #{result.success?}"
+puts "Duration: #{result.duration}s"
+puts "Cost: $#{result.total_cost}"
+puts ""
+puts "✅ Basic configuration works!"

data/examples/v2/dsl/02_core_parameters.rb

@@ -0,0 +1,59 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Manual Test 2: All Core Agent Parameters
+#
+# Tests: model, provider, base_url, api_version, context_window, system_prompt, description
+#
+# Run: bundle exec ruby -Ilib lib/swarm_sdk/examples/dsl/02_core_parameters.rb
+
+require "swarm_sdk"
+require_relative "../../../swarm_sdk/swarm_builder"
+require_relative "../../../swarm_sdk/agent_builder"
+
+ENV["OPENAI_API_KEY"] = "test-key"
+
+swarm = SwarmSDK.build do
+  name("Core Parameters Test")
+  lead(:full_config_agent)
+
+  agent(:full_config_agent) do
+    # Core LLM configuration
+    model("gpt-5-nano")
+    provider("openai")
+    api_version("v1/responses")
+    context_window(200_000)
+
+    # Agent identity
+    system_prompt("You are testing all core configuration parameters. Be concise.")
+    description("Agent testing all core configuration parameters")
+
+    # Minimal tool for testing
+    tools(:Read)
+  end
+end
+
+puts "✅ Swarm with all core parameters built!"
+puts "Testing configuration..."
+puts ""
+
+agent_def = swarm.agent_definition(:full_config_agent)
+
+puts "Configuration Verification:"
+puts "  model: #{agent_def.model}"
+puts "  provider: #{agent_def.provider}"
+puts "  base_url: #{agent_def.base_url}"
+puts "  api_version: #{agent_def.api_version}"
+puts "  context_window: #{agent_def.context_window}"
+puts "  description: #{agent_def.description}"
+puts "  system_prompt length: #{agent_def.system_prompt.length} chars"
+puts ""
+
+puts "Running test query..."
+result = swarm.execute("Say 'core params work'")
+
+puts ""
+puts "Response: #{result.content}"
+puts "Success: #{result.success?}"
+puts ""
+puts "✅ All core parameters work correctly!"