roast-ai 0.3.0 → 0.4.0

data/claude-swarm.yml

@@ -0,0 +1,210 @@
+version: 1
+swarm:
+  name: "Roast Development Team"
+  main: lead_developer
+  instances:
+    lead_developer:
+      description: "Lead developer coordinating Roast gem development"
+      directory: .
+      model: opus
+      vibe: true
+      connections: [test_runner, code_quality, raix_expert, solid_critic, github_expert]
+      prompt: |
+        You are the lead developer for Roast, a convention-oriented framework for creating structured AI workflows. You coordinate the development team and make architectural decisions.
+        
+        Your responsibilities:
+        - Coordinate feature development and bug fixes
+        - Review and integrate contributions from team members
+        - Ensure code consistency and project direction
+        - Make architectural decisions
+        - Manage the development workflow
+        
+        You have access to a specialized team:
+        - test_runner: Runs and analyzes test results
+        - code_quality: Ensures code quality standards
+        - raix_expert: Provides expertise on the Raix gem for AI chat completions
+        - solid_critic: Reviews code for SOLID principles compliance
+        - github_expert: Handles all GitHub-related operations
+        
+        When working on tasks:
+        1. Break down complex features into manageable pieces
+        2. Delegate specific aspects to appropriate team members
+        3. Integrate feedback and ensure all changes align with Roast's conventions
+        4. Always ensure tests pass before finalizing changes
+        
+        For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.
+    
+    test_runner:
+      description: "Test execution specialist for running and analyzing test results"
+      directory: .
+      model: sonnet
+      vibe: true
+      prompt: |
+        You are the test execution specialist for the Roast gem. Your role is to run tests, analyze results, and ensure comprehensive test coverage.
+        
+        Your responsibilities:
+        - Run the full test suite using `bundle exec rake test`
+        - Run specific tests when requested
+        - Analyze test failures and provide detailed diagnostics
+        - Identify missing test coverage
+        - Suggest new test cases for edge scenarios
+        - Verify that new features have appropriate tests
+        
+        When analyzing test results:
+        1. Clearly identify which tests are failing and why
+        2. Provide stack traces and relevant error messages
+        3. Suggest fixes for failing tests
+        4. Ensure tests follow RSpec best practices
+        5. Check for test isolation and avoid test interdependencies
+        
+        For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.
+    
+    code_quality:
+      description: "Code quality enforcer ensuring standards and best practices"
+      directory: .
+      model: sonnet
+      vibe: true
+      prompt: |
+        You are the code quality specialist for the Roast gem. Your role is to ensure all code meets high quality standards and follows Ruby best practices.
+        
+        Your responsibilities:
+        - Run RuboCop for style checking: `bundle exec rubocop`
+        - Apply automatic fixes when safe: `bundle exec rubocop -A`
+        - Check for code smells and anti-patterns
+        - Ensure proper documentation with YARD comments
+        - Verify consistent naming conventions
+        - Check for performance issues
+        - Ensure proper error handling
+        
+        Quality standards to enforce:
+        1. Ruby community style guide compliance
+        2. Clear and meaningful variable/method names
+        3. DRY (Don't Repeat Yourself) principle
+        4. Appropriate use of Ruby idioms
+        5. Proper exception handling with meaningful messages
+        6. Comprehensive inline documentation
+        
+        When reviewing code:
+        - Provide specific line numbers for issues
+        - Suggest concrete improvements
+        - Explain why changes improve quality
+        
+        For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.
+    
+    raix_expert:
+      description: "Expert on the Raix gem for AI chat completions integration"
+      directory: ~/src/github.com/OlympiaAI/raix
+      model: opus
+      vibe: true
+      prompt: |
+        You are the Raix gem expert, specializing in AI chat completion integrations. Raix is a Ruby gem that provides a clean interface for AI chat completions, and you have deep knowledge of its architecture and usage patterns.
+        
+        Your expertise includes:
+        - Raix's function dispatch pattern for tools
+        - Chat completion API abstractions
+        - Integration patterns with various AI providers
+        - Best practices for tool definitions
+        - Performance optimization for AI interactions
+        - Error handling in AI contexts
+        
+        When consulted about Roast's AI integration:
+        1. Provide guidance on proper Raix usage patterns
+        2. Suggest optimal ways to structure tool definitions
+        3. Help integrate new AI capabilities using Raix
+        4. Ensure Roast's tools follow Raix conventions
+        5. Optimize AI interaction performance
+        6. Review function definitions for clarity and effectiveness
+        
+        You have access to the Raix source code and can:
+        - Reference specific Raix implementation details
+        - Suggest patterns from Raix that could benefit Roast
+        - Ensure compatibility between Roast and Raix
+        - Provide examples of advanced Raix features
+        
+        For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.
+    
+    solid_critic:
+      description: "SOLID principles expert providing aggressive code critique"
+      directory: .
+      model: opus
+      vibe: true
+      prompt: |
+        You are a SOLID principles expert, channeling the expertise and style of Sandi Metz. You provide aggressive but constructive critique of code to ensure it follows SOLID principles and object-oriented design best practices.
+        
+        Your approach:
+        - Be direct and uncompromising about violations
+        - Provide specific examples of how to improve
+        - Reference Sandi Metz's rules for developers
+        - Focus on practical, maintainable solutions
+        
+        SOLID principles to enforce:
+        1. **Single Responsibility**: Each class should have only one reason to change
+        2. **Open/Closed**: Open for extension, closed for modification
+        3. **Liskov Substitution**: Subtypes must be substitutable for base types
+        4. **Interface Segregation**: Depend on abstractions, not concretions
+        5. **Dependency Inversion**: High-level modules shouldn't depend on low-level modules
+        
+        Sandi Metz's rules to apply:
+        - Classes can be no longer than 100 lines of code
+        - Methods can be no longer than 5 lines of code
+        - Pass no more than 4 parameters into a method
+        - Controllers can instantiate only one object
+        
+        When reviewing code:
+        1. Identify specific SOLID violations with line numbers
+        2. Explain why it's a problem (not just that it violates a rule)
+        3. Provide a refactored version that fixes the issue
+        4. Show how the refactoring improves maintainability
+        5. Be aggressive but educational - every critique should teach
+        
+        Common code smells to attack:
+        - Large classes doing too much
+        - Methods with multiple responsibilities
+        - Tight coupling between classes
+        - Inheritance used inappropriately
+        - Primitive obsession
+        - Feature envy
+        
+        Remember: "The road to programming hell is paved with global variables and side effects."
+        
+        For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.
+    
+    github_expert:
+      description: "GitHub operations specialist using gh CLI"
+      directory: .
+      model: sonnet
+      vibe: true
+      prompt: |
+        You are the GitHub operations specialist for the Roast gem project. You handle all GitHub-related tasks using the `gh` command-line tool.
+        
+        Your responsibilities:
+        - Create and manage issues: `gh issue create`, `gh issue list`
+        - Handle pull requests: `gh pr create`, `gh pr review`, `gh pr merge`
+        - Manage releases: `gh release create`
+        - Check workflow runs: `gh run list`, `gh run view`
+        - Manage repository settings and configurations
+        - Handle branch operations and protection rules
+        
+        Common operations you perform:
+        1. Creating feature branches and PRs
+        2. Running and monitoring CI/CD workflows
+        3. Managing issue labels and milestones
+        4. Creating releases with proper changelogs
+        5. Reviewing and merging pull requests
+        6. Setting up GitHub Actions workflows
+        
+        Best practices to follow:
+        - Always create feature branches for new work
+        - Write clear PR descriptions with context
+        - Ensure CI passes before merging
+        - Use conventional commit messages
+        - Tag releases following semantic versioning
+        - Keep issues organized with appropriate labels
+        
+        When working with the team:
+        - Create issues for bugs found by test_runner
+        - Open PRs for code reviewed by solid_critic
+        - Set up CI to run code_quality checks
+        - Document Raix integration in wiki/docs
+        
+        For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.

data/docs/AGENT_STEPS.md

@@ -0,0 +1,264 @@
+# Agent Steps in Roast
+
+Agent steps provide a way to send prompts directly to a coding agent (like Claude Code) without going through the standard LLM translation layer. This document explains when and how to use agent steps effectively.
+
+## What are Agent Steps?
+
+Agent steps are denoted by prefixing a step name with `^`. They bypass the normal LLM processing and send your prompt content directly to the CodingAgent tool.
+
+```yaml
+steps:
+  # File-based prompts
+  - analyze_code       # Regular step - processed by LLM first
+  - ^implement_fix     # Agent step - direct to CodingAgent
+  
+  # Inline prompts
+  - Analyze the code quality and suggest improvements          # Regular inline
+  - ^Fix all ESLint errors and apply Prettier formatting       # Agent inline
+```
+
+Both file-based prompts (with directories like `implement_fix/prompt.md`) and inline prompts (text with spaces) are supported.
+
+## When to Use Agent Steps
+
+### Use Agent Steps When:
+
+1. **You need precise control over tool usage**
+   - When you want to ensure specific tools are used in a particular way
+   - When the task requires exact file manipulations or code transformations
+
+2. **Complex multi-file operations**
+   - When coordinating changes across multiple files
+   - When the operation requires specific sequencing of edits
+
+3. **Performance optimization**
+   - When you want to skip the LLM interpretation layer
+   - For well-defined tasks that don't need additional context
+
+### Use Regular Steps When:
+
+1. **You need natural language processing**
+   - When the prompt benefits from LLM interpretation
+   - When you want the LLM to add context or reasoning
+
+2. **Flexible, adaptive responses**
+   - When the exact approach might vary based on context
+   - When you want the LLM to make judgment calls
+
+## Practical Examples
+
+### Example 1: Database Migration
+
+**Regular Step (analyze_migration/prompt.md):**
+```markdown
+Look at the user's database schema and determine what migrations might be needed to support the new features they've described. Consider best practices for database design.
+```
+
+This benefits from LLM interpretation because:
+- It needs to understand "best practices" in context
+- It should make judgments about schema design
+- The approach varies based on the specific features
+
+**Agent Step (^apply_migration/prompt.md):**
+```markdown
+Create a new migration file with the following specifications:
+
+1. Use MultiEdit to create file: db/migrate/{{timestamp}}_add_user_preferences.rb
+2. The migration must include:
+   - Add column :users, :preferences, :jsonb, default: {}
+   - Add index :users, :preferences, using: :gin
+   - Add column :users, :notification_settings, :jsonb, default: {}
+3. Ensure proper up/down methods
+4. Follow Rails migration conventions exactly
+
+Required tools: MultiEdit
+Do not use Write tool for migrations.
+```
+
+This is better as an agent step because:
+- It requires specific tool usage (MultiEdit, not Write)
+- The instructions are precise and technical
+- No interpretation needed - just execution
+
+### Example 2: Code Refactoring
+
+**Regular Step (identify_code_smells/prompt.md):**
+```markdown
+Review the provided code and identify any code smells or anti-patterns. Consider things like:
+- Long methods that do too much
+- Duplicated code
+- Poor naming
+- Tight coupling
+- Missing abstractions
+
+Explain why each identified issue is problematic.
+```
+
+This works well as a regular step because it requires judgment and explanation.
+
+**Agent Step (^extract_method/prompt.md):**
+```markdown
+Extract the authentication logic from UserController#create into a separate method:
+
+1. Read file: app/controllers/user_controller.rb
+2. Find the code block from line 15-28 (the authentication logic)
+3. Create a new private method called `authenticate_user_params`
+4. Move the authentication logic to this new method
+5. Replace the original code with a call to the new method
+6. Ensure all variables are properly passed
+
+Use MultiEdit to make all changes in a single operation.
+Preserve exact indentation and formatting.
+```
+
+This is ideal as an agent step because:
+- Specific line numbers and method names
+- Exact refactoring instructions
+- No room for interpretation
+
+### Example 3: Test Generation
+
+**Regular Step (plan_test_coverage/prompt.md):**
+```markdown
+Analyze the {{file}} and determine what test cases would provide comprehensive coverage. Consider:
+- Happy path scenarios
+- Edge cases
+- Error conditions
+- Boundary values
+
+Focus on behavior, not implementation details.
+```
+
+**Agent Step (^implement_tests/prompt.md):**
+```markdown
+Create test file: test/models/user_validator_test.rb
+
+Implement exactly these test cases:
+1. test "validates email format"
+   - Use valid emails: ["user@example.com", "test.user+tag@domain.co.uk"]
+   - Use invalid emails: ["invalid", "@example.com", "user@", "user space@example.com"]
+   
+2. test "validates age is positive integer"
+   - Valid: [18, 25, 100]
+   - Invalid: [-1, 0, 17, 101, "twenty", nil]
+
+3. test "validates username uniqueness"
+   - Create user with username "testuser"
+   - Attempt to create second user with same username
+   - Assert validation error on :username
+
+Use minitest assertion style.
+Each test must be independent.
+Use setup method for common test data.
+```
+
+### Example 4: API Integration
+
+**Regular Step (design_api_client/prompt.md):**
+```markdown
+Design a client for the {{api_name}} API that follows Ruby best practices. Consider:
+- Error handling strategies
+- Rate limiting
+- Authentication patterns
+- Response parsing
+- Testing approach
+
+Suggest an architecture that will be maintainable and extensible.
+```
+
+**Agent Step (^implement_api_client/prompt.md):**
+```markdown
+Implement the API client with this exact structure:
+
+1. Create file: lib/external_apis/weather_api/client.rb
+   ```ruby
+   module ExternalApis
+     module WeatherApi
+       class Client
+         include HTTParty
+         base_uri 'https://api.weather.com/v1'
+         
+         def initialize(api_key)
+           @api_key = api_key
+           @options = { headers: { 'Authorization' => "Bearer #{api_key}" } }
+         end
+         
+         def current_weather(location)
+           response = self.class.get("/current", @options.merge(query: { location: location }))
+           handle_response(response)
+         end
+         
+         private
+         
+         def handle_response(response)
+           raise ApiError, response.message unless response.success?
+           response.parsed_response
+         end
+       end
+     end
+   end
+   ```
+
+2. Create file: lib/external_apis/weather_api/api_error.rb
+   Define custom exception class
+
+3. Update file: config/initializers/weather_api.rb
+   Add configuration for API endpoint and timeout
+
+Use exact module structure and method signatures shown.
+```
+
+## Best Practices
+
+1. **Be explicit about tool usage in agent steps**
+   ```markdown
+   # Good agent step
+   Use MultiEdit tool to update the following files:
+   - app/models/user.rb: Add validation
+   - test/models/user_test.rb: Add test case
+   
+   # Avoid in agent steps
+   Update the user model with better validation
+   ```
+
+2. **Include specific line numbers or code markers when possible**
+   ```markdown
+   # Good agent step
+   In app/controllers/application_controller.rb:
+   - Find method `authenticate_user!` (around line 45)
+   - Add the following before the redirect_to call:
+     session[:return_to] = request.fullpath
+   ```
+
+3. **Specify exact formatting requirements**
+   ```markdown
+   # Good agent step
+   Create method with exactly this signature:
+   def calculate_tax(amount, rate = 0.08)
+   
+   Ensure:
+   - Two-space indentation
+   - No trailing whitespace
+   - Blank line before method definition
+   ```
+
+4. **Chain agent steps for complex operations**
+   ```yaml
+   steps:
+     # First understand the system
+     - analyze_current_architecture
+     
+     # Then execute precise changes
+     - ^create_service_objects
+     - ^update_controllers  
+     - ^add_test_coverage
+     
+     # Finally verify
+     - verify_all_tests_pass
+   ```
+
+## Summary
+
+Agent steps are powerful when you need direct control over tool usage and precise execution of technical tasks. They complement regular steps by handling the implementation details while regular steps handle the analysis and planning.
+
+Choose agent steps when precision matters more than interpretation. Choose regular steps when context and judgment are important.

data/examples/agent_workflow/README.md

@@ -0,0 +1,75 @@
+# Agent Workflow Example
+
+This example demonstrates the practical differences between regular steps and agent steps in Roast workflows.
+
+## What are Agent Steps?
+
+Agent steps are a special type of step that sends prompts directly to the CodingAgent tool (e.g., Claude Code) without going through the normal LLM translation layer. They're denoted by prefixing the step name with `^`.
+
+## When to Use Each Type
+
+### Regular Steps
+Best for tasks that benefit from LLM interpretation:
+- Analysis and judgment tasks
+- Natural language understanding
+- Flexible responses based on context
+- Summary and explanation generation
+
+### Agent Steps
+Best for tasks requiring precise tool control:
+- Exact code refactoring operations
+- Multi-file coordinated changes
+- Specific tool usage requirements
+- Performance-critical operations
+
+## Workflow Structure
+
+This example demonstrates a code refactoring workflow:
+
+1. **identify_code_smells** (Regular Step)
+   - Analyzes code to identify issues
+   - Uses LLM judgment to prioritize problems
+   - Provides contextual explanations
+
+2. **^apply_refactorings** (Agent Step)
+   - Executes precise refactoring operations
+   - Uses specific tools (Read, MultiEdit) directly
+   - Follows exact formatting requirements
+   - No interpretation needed - just execution
+
+3. **summarize_improvements** (Regular Step)
+   - Reviews all changes made
+   - Generates human-friendly summary
+   - Provides recommendations
+
+## Running the Workflow
+
+```bash
+# Run on all Ruby files in current directory
+roast execute examples/agent_workflow/workflow.yml
+
+# Run on specific files
+roast execute examples/agent_workflow/workflow.yml app/models/*.rb
+```
+
+## Key Differences in Practice
+
+### Regular Step Example
+The `identify_code_smells` step benefits from LLM interpretation because:
+- It needs to understand "code smells" in context
+- It makes subjective judgments about code quality
+- It prioritizes issues based on impact
+
+### Agent Step Example
+The `^apply_refactorings` step works better as an agent step because:
+- It requires specific tool usage (MultiEdit, not Write)
+- It needs exact preservation of formatting
+- It follows precise refactoring patterns
+- No interpretation is needed - just execution
+
+## Benefits Demonstrated
+
+1. **Complementary Strengths**: Regular steps handle analysis and planning, agent steps handle precise execution
+2. **Better Performance**: Agent steps skip the LLM layer for well-defined tasks
+3. **Predictable Results**: Agent steps execute exactly as specified
+4. **Tool Control**: Agent steps can enforce specific tool usage patterns

data/examples/agent_workflow/apply_refactorings/prompt.md

@@ -0,0 +1,22 @@
+Based on the code smells identified in the previous step, apply the following refactorings:
+
+For each file that needs changes:
+
+1. Use the Read tool to examine the current implementation
+2. Use MultiEdit to apply all refactorings in a single operation per file
+3. Ensure all changes maintain exact formatting and indentation
+4. Focus on these specific refactorings:
+   - Extract long methods (>15 lines) into smaller, focused methods
+   - Replace magic numbers with named constants
+   - Rename variables/methods that don't clearly express intent
+   - Extract duplicate code into shared methods
+   - Add proper error handling where missing
+
+Important constraints:
+- DO NOT change the public API of any class
+- DO NOT modify test files
+- DO NOT add comments unless replacing unclear code
+- Preserve all existing functionality
+- Use Ruby idioms and conventions
+
+After each file modification, verify the changes maintain the original behavior.

data/examples/agent_workflow/identify_code_smells/prompt.md

@@ -0,0 +1,15 @@
+Analyze the provided Ruby code and identify potential code smells or areas for improvement. Consider:
+
+1. Method complexity and length
+2. Duplicated code patterns
+3. Poor naming conventions
+4. Tight coupling between classes
+5. Missing abstractions or violated SOLID principles
+6. Performance anti-patterns
+
+For each issue found, explain:
+- What the problem is
+- Why it's problematic
+- A general approach to fix it
+
+Focus on the most impactful improvements that would enhance code maintainability and readability.

data/examples/agent_workflow/summarize_improvements/prompt.md

@@ -0,0 +1,18 @@
+Review the refactorings that were applied and provide a comprehensive summary that includes:
+
+1. **Overview of Changes**
+   - Number of files modified
+   - Types of refactorings applied
+   - Overall impact on code quality
+
+2. **Key Improvements**
+   - Most significant refactorings and their benefits
+   - Complexity reductions achieved
+   - Readability enhancements
+
+3. **Recommendations for Future**
+   - Any remaining code smells that require larger architectural changes
+   - Suggested next steps for continued improvement
+   - Areas that would benefit from additional test coverage
+
+Format the summary in a way that would be useful for a code review or team discussion.

data/examples/agent_workflow/workflow.yml

@@ -0,0 +1,16 @@
+description: Example workflow demonstrating agent steps
+
+# Agent steps send prompts directly to CodingAgent (e.g., Claude Code)
+# without the intermediate LLM translation layer
+
+target: "**/*.rb"
+
+steps:
+  # Regular step - goes through LLM first for analysis and judgment
+  - identify_code_smells
+  
+  # Agent step - direct to CodingAgent for precise refactoring
+  - ^apply_refactorings
+  
+  # Regular step - verify changes and provide summary
+  - summarize_improvements

data/examples/available_tools_demo/README.md

@@ -0,0 +1,42 @@
+# Available Tools Demo
+
+This example demonstrates the `available_tools` feature in Roast, which allows you to restrict which tools are available to specific steps in your workflow.
+
+## Overview
+
+The workflow consists of three steps, each with different tool access:
+
+1. **explore_directory**: Can only use `pwd` and `ls` commands
+2. **analyze_files**: Can only use `grep` and `read_file` tools
+3. **write_summary**: Can only use `write_file` and `echo` tools
+
+## Key Features Demonstrated
+
+### Security Through Least Privilege
+Each step only has access to the tools it needs. For example, the exploration step cannot write files, and the summary step cannot read files or explore directories.
+
+### Tool Name Convention
+- For built-in tools: Use snake_case names (e.g., `read_file` for `Roast::Tools::ReadFile`)
+- For Cmd tool: Use the specific command names (e.g., `pwd`, `ls`)
+
+### Configuration Structure
+```yaml
+step_name:
+  available_tools:
+    - tool1
+    - tool2
+```
+
+## Running the Example
+
+```bash
+roast examples/available_tools_demo/workflow.yml
+```
+
+## What Happens
+
+1. The first step explores the current directory using only `pwd` and `ls`
+2. The second step searches for Ruby files and reads one using only `grep` and `read_file`
+3. The final step creates a summary file using only `write_file` and `echo`
+
+Each step is restricted to its specified tools, demonstrating how you can create secure, focused workflows where each step has exactly the capabilities it needs.

data/examples/available_tools_demo/analyze_files/prompt.md

@@ -0,0 +1,6 @@
+Based on the directory listing from the previous step, your task is to:
+
+1. Search for any Ruby files using grep
+2. Read the contents of the first Ruby file you find
+
+Note: You only have access to the `grep` and `read_file` tools for this step. You cannot use commands like `ls` or `pwd`.

data/examples/available_tools_demo/explore_directory/prompt.md

@@ -0,0 +1,6 @@
+You are exploring a new directory. Your task is to:
+
+1. Show the current working directory
+2. List all files and subdirectories
+
+Note: You only have access to the `pwd` and `ls` commands for this step.