roast-ai 0.3.1 → 0.4.0

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.

data/examples/available_tools_demo/workflow.yml

@@ -0,0 +1,32 @@
+model: anthropic:claude-opus-4
+
+tools:
+  - Roast::Tools::Grep
+  - Roast::Tools::ReadFile
+  - Roast::Tools::WriteFile
+  - Roast::Tools::Cmd:
+      allowed_commands:
+        - pwd
+        - ls
+        - echo
+
+steps:
+  - explore_directory
+  - analyze_files
+  - write_summary
+
+# Step-level tool configuration
+explore_directory:
+  available_tools:
+    - pwd
+    - ls
+
+analyze_files:
+  available_tools:
+    - grep
+    - read_file
+
+write_summary:
+  available_tools:
+    - write_file
+    - echo

data/examples/available_tools_demo/write_summary/prompt.md

@@ -0,0 +1,6 @@
+Based on your exploration and analysis, create a summary:
+
+1. Write a brief summary of what you found to a file called `summary.txt`
+2. Echo a completion message
+
+Note: You only have access to the `write_file` and `echo` tools for this step. You cannot read files or use other commands.

data/examples/case_when/detect_language/prompt.md

@@ -9,8 +9,8 @@ Based on the file extension and content, determine the primary programming langu
 
 Return ONLY the language name in lowercase, nothing else.
 
-File: {{ context.resource_uri }}
+File: <%= context.resource_uri %>
 Content:
 ```
-{{ context.resource }}
+<%= context.resource %>
 ```

data/examples/grading/run_coverage.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "open3"
-
 class RunCoverage < Roast::Workflow::BaseStep
   def call
     # Run the test with coverage analysis

data/examples/iteration/analyze_complexity/prompt.md

@@ -1,4 +1,4 @@
-I'll analyze the code complexity of the file {{current_file}}, which I've read in the previous step.
+I'll analyze the code complexity of the file <%= current_file %>, which I've read in the previous step.
 
 I'll examine the following aspects:
 1. Cyclomatic complexity (number of decision paths)
@@ -9,7 +9,7 @@ I'll examine the following aspects:
 6. Opportunities for refactoring
 
 ```ruby
-{{output.read_file}}
+<%= output.read_file %>
 ```
 
 Based on this analysis, I'll provide a structured assessment of the code quality issues found.

data/examples/iteration/generate_recommendations/prompt.md

@@ -1,8 +1,8 @@
-Based on the analysis of complexity for file {{current_file}}, I'll generate specific recommendations for improving code quality.
+Based on the analysis of complexity for file <%= current_file %>, I'll generate specific recommendations for improving code quality.
 
 I'll use the complexity analysis from the previous step:
 ```json
-{{output.analyze_complexity}}
+<%= output.analyze_complexity %>
 ```
 
 For each identified issue, I'll provide detailed, actionable recommendations including:

data/examples/iteration/implement_fix/prompt.md

@@ -2,13 +2,13 @@ I'll implement the fix for the issue selected in the previous step.
 
 Here is the issue to fix:
 ```json
-{{output.select_next_issue}}
+<%= output.select_next_issue %>
 ```
 
 First, I'll read the current file content to understand the context:
 
 ```ruby
-{{read_file(output.select_next_issue.file_path)}}
+<%= read_file(output.select_next_issue.file_path) %>
 ```
 
 Based on the issue description and the recommended changes, I'll implement a fix that:

data/examples/iteration/prioritize_issues/prompt.md

@@ -8,7 +8,7 @@ I'll analyze all the recommendations I've generated across multiple files and pr
 Let me review all the recommendations collected so far:
 
 ```json
-{{outputs_of.generate_recommendations}}
+<%= outputs_of.generate_recommendations %>
 ```
 
 I'll create a comprehensive prioritized list of all issues across files, combining similar issues where appropriate. The prioritized list will include:

data/examples/iteration/prompts/analyze_file.md

@@ -3,10 +3,10 @@
 You are a code analyzer focusing on analyzing Ruby files to count the number of methods defined.
 
 ## Input
-- File path: {{ file_path }}
+- File path: <%= file_path %>
 - File content:
 ```ruby
-{{ tools.read_file.content(file_path) }}
+<%= read_file(file_path) %>
 ```
 
 ## Task

data/examples/iteration/prompts/generate_summary.md

@@ -3,7 +3,7 @@
 You are a report generator responsible for summarizing the method analysis results.
 
 ## Input
-- Report data: {{ report_data }}
+- Report data: <%= report_data %>
 
 ## Task
 1. Parse the report data as JSON

data/examples/iteration/prompts/update_report.md

@@ -3,9 +3,9 @@
 You are a data updater responsible for adding analysis results to a report.
 
 ## Input
-- File path: {{ file_path }}
-- Method count: {{ method_count }}
-- Current report data: {{ current_report }}
+- File path: <%= file_path %>
+- Method count: <%= method_count %>
+- Current report data: <%= current_report %>
 
 ## Task
 1. Parse the current report data as JSON

data/examples/iteration/prompts/write_report.md

@@ -3,8 +3,8 @@
 You are responsible for creating a formatted report file based on the analysis results.
 
 ## Input
-- Report data: {{ report_data }}
-- Summary: {{ summary }}
+- Report data: <%= report_data %>
+- Summary: <%= summary %>
 
 ## Task
 1. Generate a Markdown report that includes:
@@ -16,7 +16,7 @@ You are responsible for creating a formatted report file based on the analysis r
 Return a JSON object with the following structure:
 ```json
 {
-  "report_content": "# Ruby Method Analysis Report\n\n{{ summary }}\n\n## Detailed Results\n\n| File | Method Count | Methods |\n|------|--------------|--------|\n| file1.rb | 5 | method1, method2, ... |\n| file2.rb | 3 | methodA, methodB, ... |\n...",
+  "report_content": "# Ruby Method Analysis Report\n\n<%= summary %>\n\n## Detailed Results\n\n| File | Method Count | Methods |\n|------|--------------|--------|\n| file1.rb | 5 | method1, method2, ... |\n| file2.rb | 3 | methodA, methodB, ... |\n...",
   "report_file_path": "method_analysis_report.md"
 }
 ```

data/examples/iteration/read_file/prompt.md

@@ -1,9 +1,9 @@
-I'll analyze the Ruby file at: {{current_file}}
+I'll analyze the Ruby file at: <%= current_file %>
 
 First, let me read the content of this file.
 
 ```ruby
-{{read_file current_file}}
+<%= read_file(current_file) %>
 ```
 
 I'll store this content for further analysis in the next steps.

data/examples/iteration/select_next_issue/prompt.md

@@ -2,12 +2,12 @@ I'll select the next highest priority issue to fix from our prioritized list.
 
 Here is the current prioritized list of issues:
 ```json
-{{output.prioritize_issues}}
+<%= output.prioritize_issues %>
 ```
 
 And here is the count of fixes we've already applied:
 ```
-{{output.update_fix_count || '0'}}
+<%= output.update_fix_count || '0' %>
 ```
 
 I'll select the highest priority issue that hasn't yet been addressed. I'll consider: