claude_swarm 0.1.17 → 0.1.19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3f0ab99665f31bddf2d3641525481ce2df55e910950af03290137246847bf70d
-  data.tar.gz: 2435170f5b61604c3131b1680f60ed8727795c58432806d9b61007813d4f5ce3
+  metadata.gz: ecbec0c31b9252f826e28978e871cdc0003644d691a541906a8c36ae60c717f6
+  data.tar.gz: 9d88ab7118d614108adcd2995b270f3c223e08a0a7ccd8768136f362f9f002d6
 SHA512:
-  metadata.gz: ee74c188f6cc7fd31bb8705661f0913674bb687fd1eae6c2973728d2418f62bbad86054a89bd150965f39ec0bbd37ac04b2413dd22340311afd03cd5ec9d5424
-  data.tar.gz: a6c5fb7db4a8659619c9c7b5de000303ce91b046b85d635381f437adc92b4fd739e8d2142f0e65323346d1ba4d2607bf2b90c7d76fcf7c119bf6b9d5c431a7fc
+  metadata.gz: 66783c2bc619846d7ce78b33e290d34b414946a5e66714f0528ef312a1e641cc9c6950e30d492e1f428374da391f39e11556bffaa68ced4b4cda726987ea4a8c
+  data.tar.gz: f04e7f694fb8f151c5ccfa4bd145a2184cb7674b78a1c3af414704664b6efadd5887d9f78e3ad8da4d7f41a25bdfb8e23d355eb79c4bb7675aebb79424995a59

data/CHANGELOG.md

@@ -1,3 +1,53 @@
+## [0.1.19]
+
+### Added
+- **Interactive configuration generator**: New `claude-swarm generate` command launches Claude to help create swarm configurations
+  - Runs Claude in interactive mode with an initial prompt to guide configuration creation
+  - Customizable output file with `-o/--output` option
+  - When no output file is specified, Claude names the file based on the swarm's function (e.g., web-dev-swarm.yml, data-pipeline-swarm.yml)
+  - Model selection with `-m/--model` option (default: sonnet)
+  - Checks for Claude CLI installation and provides helpful error message if not found
+  - Includes comprehensive initial prompt with Claude Swarm overview, best practices, and common patterns
+  - Full README content is included in the prompt within `<full_readme>` tags for complete context
+  - Examples: 
+    - `claude-swarm generate` - Claude names file based on swarm function
+    - `claude-swarm generate -o my-team.yml --model opus` - Custom file and model
+
+### Fixed
+- **ps command path display**: The `claude-swarm ps` command now shows expanded absolute paths instead of raw YAML values
+  - Relative paths like `.` are expanded to their full absolute paths (e.g., `/Users/paulo/project`)
+  - Multiple directories are properly expanded and displayed as comma-separated values
+  - Worktree directories are correctly shown when sessions use worktrees (e.g., `/path/to/repo/.worktrees/feature-branch`)
+  - Path resolution uses the start_directory from session metadata for accurate expansion
+
+## [0.1.18]
+
+### Added
+- **Before commands**: Execute setup commands before launching the swarm
+  - New `before` field in swarm configuration accepts an array of commands
+  - Commands are executed in sequence before any Claude instances are launched
+  - All commands must succeed (exit code 0) for the swarm to launch
+  - Commands are only executed on initial launch, not when restoring sessions
+  - Output is logged to the session log file
+  - Useful for installing dependencies, starting services, or running setup scripts
+  - Example: `before: ["npm install", "docker-compose up -d"]`
+
+- **Git worktree support**: Run instances in isolated Git worktrees
+  - New `--worktree [NAME]` CLI option creates worktrees for all instances
+  - Worktrees are created inside each repository at `.worktrees/NAME`
+  - Each worktree gets its own branch (not detached HEAD) for proper Git operations
+  - Auto-generated names use session ID: `worktree-SESSION_ID`
+  - Per-instance worktree configuration in YAML:
+    - `worktree: true` - Use shared worktree name
+    - `worktree: false` - Disable worktree for this instance
+    - `worktree: "branch-name"` - Use custom worktree name
+  - Session restoration automatically restores worktrees
+  - Cleanup preserves worktrees with uncommitted changes or unpushed commits
+  - Warnings displayed when worktrees are preserved: "⚠️ Warning: Worktree has uncommitted changes"
+  - Multiple directories per instance work seamlessly with worktrees
+  - `.gitignore` automatically created in `.worktrees/` directory
+  - Example: `claude-swarm --worktree feature-branch`
+
 ## [0.1.17]
 
 ### Added

data/CLAUDE.md

@@ -39,6 +39,47 @@ bundle exec rake release    # Release gem to RubyGems.org
 rake                  # Runs both tests and RuboCop
 ```
 
+## Git Worktree Support
+
+Claude Swarm supports launching instances in Git worktrees to isolate changes:
+
+### CLI Usage
+```bash
+# Create worktrees with custom name
+claude-swarm --worktree feature-branch
+
+# Create worktrees with auto-generated name (worktree-SESSION_ID)
+claude-swarm --worktree
+
+# Short form
+claude-swarm -w feature-x
+```
+
+### Per-Instance Configuration
+Instances can have individual worktree settings that override CLI behavior:
+
+```yaml
+instances:
+  main:
+    worktree: true         # Use shared worktree name (from CLI or auto-generated)
+  testing:
+    worktree: false        # Don't use worktree for this instance
+  feature:
+    worktree: "feature-x"  # Use specific worktree name
+  default:
+    # No worktree field - follows CLI behavior
+```
+
+### Worktree Behavior
+- Worktrees are created inside each repository in a `.worktrees/` directory
+- A `.gitignore` file is automatically created inside `.worktrees/` to ignore all contents
+- Each unique Git repository gets its own worktree with the same name
+- All instance directories are mapped to their worktree equivalents
+- Worktrees are automatically cleaned up when the swarm exits
+- Session metadata tracks worktree information for restoration
+- Non-Git directories are used as-is without creating worktrees
+- Existing worktrees with the same name are reused
+
 ## Architecture
 
 The gem is fully implemented with the following components:
@@ -49,6 +90,7 @@ The gem is fully implemented with the following components:
 - **ClaudeSwarm::Configuration** (`lib/claude_swarm/configuration.rb`): YAML parser and validator for swarm configurations
 - **ClaudeSwarm::McpGenerator** (`lib/claude_swarm/mcp_generator.rb`): Generates MCP JSON configurations for each instance
 - **ClaudeSwarm::Orchestrator** (`lib/claude_swarm/orchestrator.rb`): Launches the main Claude instance with proper configuration
+- **ClaudeSwarm::WorktreeManager** (`lib/claude_swarm/worktree_manager.rb`): Manages Git worktrees for isolated development
 
 ### Key Features
 
@@ -58,6 +100,7 @@ The gem is fully implemented with the following components:
 4. **Multiple MCP Types**: Supports both stdio and SSE MCP server types
 5. **Automatic MCP Generation**: Creates `.claude-swarm/` directory with MCP configs
 6. **Custom System Prompts**: Each instance can have a custom prompt via `--append-system-prompt`
+7. **Git Worktree Support**: Run instances in isolated Git worktrees with per-instance configuration
 
 ### How It Works
 
@@ -77,16 +120,20 @@ swarm:
   main: lead
   instances:
     lead:
+      description: "Lead developer coordinating the team"
       directory: .
       model: opus
       connections: [frontend, backend]
       prompt: "You are the lead developer coordinating the team"
       tools: [Read, Edit, Bash]
+      worktree: true  # Optional: use worktree for this instance
     frontend:
+      description: "Frontend developer specializing in React"
       directory: ./frontend
       model: sonnet
       prompt: "You specialize in frontend development with React"
       tools: [Edit, Write, Bash]
+      worktree: false  # Optional: disable worktree for this instance
 ```
 
 ## Testing
@@ -98,6 +145,7 @@ The gem includes comprehensive tests covering:
 - CLI command functionality
 - Session restoration
 - Vibe mode behavior
+- Worktree management and per-instance configuration
 
 ## Dependencies
 

data/README.md

@@ -1,10 +1,30 @@
 # Claude Swarm
 
-[![Gem Version](https://badge.fury.io/rb/claude_swarm.svg?cache_bust=0.1.15)](https://badge.fury.io/rb/claude_swarm)
+[![Gem Version](https://badge.fury.io/rb/claude_swarm.svg?cache_bust=0.1.17)](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.
 
+## Table of Contents
+
+- [Installation](#installation)
+- [Prerequisites](#prerequisites)
+- [Usage](#usage)
+  - [Quick Start](#quick-start)
+  - [Configuration Format](#configuration-format)
+  - [MCP Server Types](#mcp-server-types)
+  - [Tools](#tools)
+  - [Examples](#examples)
+  - [Command Line Options](#command-line-options)
+  - [Session Monitoring](#session-monitoring)
+  - [Session Management and Restoration](#session-management-and-restoration-experimental)
+- [How It Works](#how-it-works)
+- [Troubleshooting](#troubleshooting)
+- [Architecture](#architecture)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
 ## Installation
 
 Install the gem by executing:
@@ -35,7 +55,7 @@ bundle install
 
 ### Quick Start
 
-1. Run `claude-swarm init` or create a `claude-swarm.yml` file in your project:
+1. Run `claude-swarm init` to create a basic template, or use `claude-swarm generate` for an interactive configuration experience with Claude's help. You can also manually create a `claude-swarm.yml` file in your project:
 
 ```yaml
 version: 1
@@ -191,6 +211,10 @@ version: 1  # Required, currently only version 1 is supported
 swarm:
   name: "Swarm Name"  # Display name for your swarm
   main: instance_key  # Which instance to launch as the main interface
+  before:  # Optional: commands to run before launching the swarm
+    - "echo 'Setting up environment...'"
+    - "npm install"
+    - "docker-compose up -d"
   instances:
     # Instance definitions...
 ```
@@ -211,6 +235,7 @@ Each instance can have:
 - **mcps**: Array of additional MCP servers to connect
 - **prompt**: Custom system prompt to append to the instance
 - **vibe**: Enable vibe mode (--dangerously-skip-permissions) for this instance (default: false)
+- **worktree**: Configure Git worktree usage for this instance (true/false/string)
 
 ```yaml
 instance_name:
@@ -428,6 +453,42 @@ When using multiple directories:
 - Additional directories are accessible via the `--add-dir` flag in Claude
 - All directories must exist or the configuration will fail validation
 
+#### Before Commands
+
+You can specify commands to run before launching the swarm using the `before` field:
+
+```yaml
+version: 1
+swarm:
+  name: "Development Environment"
+  main: lead_developer
+  before:
+    - "echo '🚀 Setting up development environment...'"
+    - "npm install"
+    - "docker-compose up -d"
+    - "bundle install"
+  instances:
+    lead_developer:
+      description: "Lead developer coordinating the team"
+      directory: .
+      model: opus
+      allowed_tools: [Read, Edit, Write, Bash]
+```
+
+The `before` commands:
+- Are executed in sequence before launching any Claude instances
+- Must all succeed for the swarm to launch (exit code 0)
+- Are only executed on initial swarm launch, not when restoring sessions
+- Have their output logged to the session log file
+- Will abort the swarm launch if any command fails
+
+This is useful for:
+- Installing dependencies
+- Starting required services (databases, Docker containers, etc.)
+- Setting up the development environment
+- Running any prerequisite setup scripts
+
+
 #### Mixed Permission Modes
 
 You can have different permission modes for different instances:
@@ -459,6 +520,72 @@ swarm:
       allowed_tools: []  # Tools list ignored when vibe: true
 ```
 
+#### Git Worktrees
+
+Claude Swarm supports running instances in Git worktrees, allowing isolated work without affecting your main repository state. Worktrees are created inside each repository in a `.worktrees/` directory following Git best practices.
+
+**Example Structure:**
+```
+my-repo/
+├── .git/
+├── .worktrees/        (created by Claude Swarm)
+│   ├── .gitignore     (auto-created, contains "*")
+│   └── feature-x/     (worktree for feature-x branch)
+├── src/
+└── tests/
+```
+
+**CLI Option:**
+```bash
+# Create worktrees with auto-generated name (worktree-SESSION_ID)
+claude-swarm --worktree
+
+# Create worktrees with custom name
+claude-swarm --worktree feature-branch
+
+# Short form
+claude-swarm -w
+```
+
+**Per-Instance Configuration:**
+```yaml
+version: 1
+swarm:
+  name: "Worktree Example"
+  main: lead
+  instances:
+    lead:
+      description: "Lead developer"
+      directory: .
+      worktree: true  # Use shared worktree name from CLI (or auto-generate)
+      
+    testing:
+      description: "Test developer"  
+      directory: ./tests
+      worktree: false  # Don't use worktree for this instance
+      
+    feature_dev:
+      description: "Feature developer"
+      directory: ./features
+      worktree: "feature-x"  # Use specific worktree name
+```
+
+**Worktree Behavior:**
+- `worktree: true` - Uses the shared worktree name (from CLI or auto-generated)
+- `worktree: false` - Disables worktree for this instance
+- `worktree: "name"` - Uses a specific worktree name
+- Omitted - Follows CLI behavior (use worktree if `--worktree` is specified)
+
+**Notes:**
+- Worktrees are created inside each repository in a `.worktrees/` directory
+- Auto-generated worktree names use the session ID (e.g., `worktree-20241206_143022`)
+- This makes it easy to correlate worktrees with their Claude Swarm sessions
+- A `.gitignore` file is automatically created inside `.worktrees/` to ignore all worktree contents
+- All worktrees are automatically cleaned up when the swarm exits
+- Worktrees with the same name across different repositories share that name
+- Non-Git directories are unaffected by worktree settings
+- Existing worktrees with the same name are reused
+
 ### Command Line Options
 
 ```bash
@@ -480,6 +607,20 @@ claude-swarm --prompt "Fix the bug in the payment module"
 claude-swarm --session-id 20241206_143022
 claude-swarm --session-id ~/path/to/session
 
+# Run all instances in Git worktrees
+claude-swarm --worktree                  # Auto-generated name (worktree-SESSION_ID)
+claude-swarm --worktree feature-branch   # Custom worktree name
+claude-swarm -w                          # Short form
+
+# Initialize a new configuration file
+claude-swarm init
+claude-swarm init --force  # Overwrite existing file
+
+# Generate configuration interactively with Claude's help
+claude-swarm generate                       # Claude names file based on swarm function
+claude-swarm generate -o my-swarm.yml       # Custom output file
+claude-swarm generate --model opus          # Use a specific model
+
 # Show version
 claude-swarm version
 

data/claude-swarm.yml

@@ -1,26 +1,64 @@
 version: 1
 swarm:
-  name: "Swarm Name"
-  main: claude_swarm_architect
+  name: "Codex CLI Integration Team"
+  main: claude_swarm_developer
   instances:
-    claude_swarm_architect:
-      description: "Lead architect"
-      directory:
-        - .
-        - /Users/paulo/src/github.com/shopify-playground/claudeception
+    claude_swarm_developer:
+      description: "Claude Swarm developer implementing Codex CLI integration to enable OpenAI model support"
+      directory: .
       model: opus
-      prompt: "You are an expert in Claude swarm architecture"
       vibe: true
-      connections: [claudeception_architect]
+      connections: [codex_cli_expert]
+      prompt: |
+        You are an expert Claude Swarm developer responsible for integrating Codex CLI functionality into Claude Swarm to enable the use of OpenAI models alongside Claude models.
 
-    # Example instances (uncomment and modify as needed):
+        Your primary objectives:
+        1. Work closely with the codex_cli_expert to understand how Codex CLI works
+        2. Design and implement the integration of Codex CLI into Claude Swarm
+        3. Ensure seamless interoperability between Claude and OpenAI models in swarm configurations
+        4. Extend the YAML configuration format to support OpenAI model specifications
+        5. Implement the necessary Ruby code to launch and manage Codex CLI instances
+        6. Ensure proper session management and MCP communication for Codex instances
+        7. Update documentation and examples to showcase the new capabilities
 
-    claudeception_architect:
-      description: "You are an expert in Claudeception architecture"
-      directory:
-        - .
-        - /Users/paulo/src/github.com/shopify-playground/claudeception
+        When working on this integration:
+        - First, consult with the codex_cli_expert to understand Codex CLI's architecture, API, and usage patterns
+        - Identify the key integration points and design patterns needed
+        - Implement the changes incrementally, testing as you go
+        - Consider backward compatibility with existing Claude Swarm configurations
+        - Think about how users will specify OpenAI models in their swarm configurations
+
+        For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.
+
+        Start by asking the codex_cli_expert for a comprehensive overview of how Codex CLI works, its command-line interface, configuration format, and any relevant APIs or extension points.
+
+    codex_cli_expert:
+      description: "Codex CLI expert providing detailed information about Codex CLI architecture and integration points"
+      directory: /Users/paulo/src/github.com/openai/codex
       model: opus
-      prompt: "You are an expert in Claudeception architecture"
       vibe: true
+      prompt: |
+        You are an expert on the Codex CLI codebase with deep knowledge of its architecture, implementation, and usage patterns. Your role is to help understand how Codex CLI works so they can integrate it into Claude Swarm.
+
+        Your responsibilities:
+        1. Analyze and explain the Codex CLI codebase structure and architecture
+        2. Document the command-line interface, flags, and configuration options
+        3. Identify key APIs, interfaces, and extension points that could be used for integration
+        4. Explain how Codex CLI manages sessions, contexts, and model interactions
+        5. Provide code examples and usage patterns
+        6. Suggest integration strategies based on your understanding of both systems
+        7. Answer any technical questions about Codex CLI implementation details
+
+        When analyzing the codebase:
+        - Start with a high-level overview of the project structure
+        - Examine the main entry points and command processing logic
+        - Look for configuration file formats and parsing logic
+        - Understand how Codex CLI communicates with OpenAI models
+        - Identify any MCP or similar protocol support
+        - Look for session management and state persistence features
+        - Look for logging output, log streams, log to a file, JSON logs, verbose mode, etc.
+        - Check for any existing integration or extension mechanisms
+
+        For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.
 
+        Be proactive in providing comprehensive information. Don't wait to be asked for every detail - anticipate what the claude_swarm_developer will need to know for a successful integration.

data/examples/with-before-commands.yml

@@ -0,0 +1,30 @@
+version: 1
+swarm:
+  name: "Development Environment"
+  main: lead_developer
+  before:
+    - "echo '🚀 Setting up development environment...'"
+    - "echo '📦 Installing dependencies...'"
+    - "echo '🐳 Starting Docker containers...'"
+  instances:
+    lead_developer:
+      description: "Lead developer who coordinates the team"
+      directory: .
+      model: sonnet
+      prompt: "You are the lead developer coordinating the team"
+      allowed_tools: [Read, Edit, Bash, Write]
+      connections: [frontend_dev, backend_dev]
+    
+    frontend_dev:
+      description: "Frontend developer specializing in React"
+      directory: ./frontend
+      model: sonnet
+      prompt: "You specialize in frontend development with React"
+      allowed_tools: [Read, Edit, Write]
+    
+    backend_dev:
+      description: "Backend developer focusing on APIs"
+      directory: ./backend
+      model: sonnet
+      prompt: "You specialize in backend development and APIs"
+      allowed_tools: [Read, Edit, Write, Bash]

data/lib/claude_swarm/cli.rb

@@ -26,6 +26,9 @@ module ClaudeSwarm
                           desc: "Enable debug output"
     method_option :session_id, type: :string,
                                desc: "Resume a previous session by ID or path"
+    method_option :worktree, type: :string, aliases: "-w",
+                             desc: "Create instances in Git worktrees with the given name (auto-generated if true)",
+                             banner: "[NAME]"
     def start(config_file = nil)
       # Handle session restoration
       if options[:session_id]
@@ -54,7 +57,8 @@ module ClaudeSwarm
                                         vibe: options[:vibe],
                                         prompt: options[:prompt],
                                         stream_logs: options[:stream_logs],
-                                        debug: options[:debug])
+                                        debug: options[:debug],
+                                        worktree: options[:worktree])
         orchestrator.start
       rescue Error => e
         error e.message
@@ -147,6 +151,10 @@ module ClaudeSwarm
         swarm:
           name: "Swarm Name"
           main: lead_developer
+          # before:  # Optional: commands to run before launching swarm (executed in sequence)
+          #   - "echo 'Setting up environment...'"
+          #   - "npm install"
+          #   - "docker-compose up -d"
           instances:
             lead_developer:
               description: "Lead developer who coordinates the team and makes architectural decisions"
@@ -192,6 +200,37 @@ module ClaudeSwarm
       say "Edit this file to configure your swarm, then run 'claude-swarm' to start"
     end
 
+    desc "generate", "Launch Claude to help generate a swarm configuration interactively"
+    method_option :output, aliases: "-o", type: :string,
+                           desc: "Output file path for the generated configuration"
+    method_option :model, aliases: "-m", type: :string, default: "sonnet",
+                          desc: "Claude model to use for generation"
+    def generate
+      # Check if claude command exists
+      unless system("which claude > /dev/null 2>&1")
+        error "Claude CLI is not installed or not in PATH"
+        say "To install Claude CLI, visit: https://docs.anthropic.com/en/docs/claude-code"
+        exit 1
+      end
+
+      # Read README for context about claude-swarm capabilities
+      readme_path = File.join(__dir__, "../../README.md")
+      readme_content = File.exist?(readme_path) ? File.read(readme_path) : ""
+
+      # Build the pre-prompt
+      preprompt = build_generation_prompt(readme_content, options[:output])
+
+      # Launch Claude in interactive mode with the initial prompt
+      cmd = [
+        "claude",
+        "--model", options[:model],
+        preprompt
+      ]
+
+      # Execute and let the user take over
+      exec(*cmd)
+    end
+
     desc "version", "Show Claude Swarm version"
     def version
       say "Claude Swarm #{VERSION}"
@@ -241,7 +280,7 @@ module ClaudeSwarm
         end
       end
 
-      say "Cleaned #{cleaned} stale session#{cleaned == 1 ? "" : "s"}", :green
+      say "Cleaned #{cleaned} stale session#{"s" unless cleaned == 1}", :green
     end
 
     desc "watch SESSION_ID", "Watch session logs"
@@ -395,6 +434,17 @@ module ClaudeSwarm
 
         config = Configuration.new(config_file, base_dir: Dir.pwd)
 
+        # Load session metadata if it exists to check for worktree info
+        session_metadata_file = File.join(session_path, "session_metadata.json")
+        worktree_name = nil
+        if File.exist?(session_metadata_file)
+          metadata = JSON.parse(File.read(session_metadata_file))
+          if metadata["worktree"] && metadata["worktree"]["enabled"]
+            worktree_name = metadata["worktree"]["name"]
+            say "Restoring with worktree: #{worktree_name}", :green unless options[:prompt]
+          end
+        end
+
         # Create orchestrator with restoration mode
         generator = McpGenerator.new(config, vibe: options[:vibe], restore_session_path: session_path)
         orchestrator = Orchestrator.new(config, generator,
@@ -402,7 +452,8 @@ module ClaudeSwarm
                                         prompt: options[:prompt],
                                         stream_logs: options[:stream_logs],
                                         debug: options[:debug],
-                                        restore_session_path: session_path)
+                                        restore_session_path: session_path,
+                                        worktree: worktree_name)
         orchestrator.start
       rescue StandardError => e
         error "Failed to restore session: #{e.message}"
@@ -425,5 +476,82 @@ module ClaudeSwarm
 
       nil
     end
+
+    def build_generation_prompt(readme_content, output_file)
+      <<~PROMPT
+        You are a Claude Swarm configuration generator assistant. Your role is to help the user create a well-structured claude-swarm.yml file through an interactive conversation.
+
+        ## Claude Swarm Overview
+        Claude Swarm is a Ruby gem that 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).
+
+        Key capabilities:
+        - Define multiple AI instances with different roles and specializations
+        - Set up connections between instances for collaboration
+        - Restrict tools based on each instance's responsibilities
+        - Run instances in different directories or Git worktrees
+        - Support for custom system prompts per instance
+        - Choose appropriate models (opus for complex tasks, sonnet for simpler ones)
+
+        ## Your Task
+        1. Start by asking about the user's project structure and development needs
+        2. Understand what kind of team they need (roles, specializations)
+        3. Suggest an appropriate swarm topology based on their needs
+        4. Help them refine and customize the configuration
+        5. Generate the final claude-swarm.yml content
+        6. When the configuration is complete, save it to: #{output_file || "a descriptive filename based on the swarm's function"}
+
+        ## File Naming Convention
+        #{output_file ? "The user has specified the output file: #{output_file}" : "Since no output file was specified, name the file based on the swarm's function. Examples:\n        - web-dev-swarm.yml for full-stack web development teams\n        - data-pipeline-swarm.yml for data processing teams\n        - microservices-swarm.yml for microservice architectures\n        - mobile-app-swarm.yml for mobile development teams\n        - ml-research-swarm.yml for machine learning teams\n        - devops-swarm.yml for infrastructure and deployment teams\n        Use descriptive names that clearly indicate the swarm's purpose."}
+
+        ## Configuration Structure
+        ```yaml
+        version: 1
+        swarm:
+          name: "Descriptive Swarm Name"
+          main: main_instance_name
+          instances:
+            instance_name:
+              description: "Clear description of role and responsibilities"
+              directory: ./path/to/directory
+              model: sonnet  # or opus for complex tasks
+              prompt: "Custom system prompt for specialization"
+              allowed_tools: [Read, Edit, Write, Bash]
+              connections: [other_instance_names]  # Optional
+        ```
+
+        ## Best Practices to Follow
+        - Use descriptive, role-based instance names (e.g., frontend_dev, api_architect)
+        - Write clear descriptions explaining each instance's responsibilities
+        - Choose opus model for complex architectural or algorithmic tasks and routine development.
+        - Choose sonnet model for simpler tasks
+        - Set up logical connections (e.g., lead → team members, architect → implementers), but avoid circular dependencies.
+        - Always add this to the end of every prompt: `For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.`
+        - Select tools based on each instance's actual needs:
+          - Read: For code review and analysis roles
+          - Edit: For active development roles
+          - Write: For creating new files
+          - Bash: For running commands, tests, builds
+          - MultiEdit: For editing multiple files at once
+          - WebFetch: For fetching information from the web
+          - WebSearch: For searching the web
+        - Use custom prompts to specialize each instance's expertise
+        - Organize directories to match project structure
+
+        ## Interactive Questions to Ask
+        - What type of project are you working on?
+        - What's your project's directory structure?
+        - What are the main technologies/frameworks you're using?
+        - What development tasks do you need help with?
+        - Do you need specialized roles (testing, DevOps, documentation)?
+        - Are there specific areas that need focused attention?
+        - Do you have multiple repositories or services to coordinate?
+
+        <full_readme>
+        #{readme_content}
+        </full_readme>
+
+        Start the conversation by greeting the user and asking: "What kind of project would you like to create a Claude Swarm for?"
+      PROMPT
+    end
   end
 end