roast-ai 0.3.1 → 0.4.1

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/apply_diff_demo/README.md

@@ -0,0 +1,58 @@
+# Apply Diff Demo
+
+This example demonstrates the `apply_diff` tool, which shows users a colored diff of proposed changes and applies them only after user confirmation.
+
+## What this workflow does
+
+1. **Creates a sample file** - Generates `hello.txt` with simple text content
+2. **Applies a simple change** - Uses `apply_diff` to modify the greeting and ask for user confirmation
+
+## Key features demonstrated
+
+- **Interactive approval** - The `apply_diff` tool shows a clear, colored diff and waits for user confirmation
+- **Safe modifications** - Changes are only applied when the user explicitly approves them
+- **Colored visualization** - Diff format shows exactly what will be changed with:
+  - **Red** lines starting with `-` for removed content
+  - **Green** lines starting with `+` for added content  
+  - **Cyan** line numbers and context (`@@` lines)
+  - **Bold** diff headers
+- **Optional descriptions** - You can provide context about why a change is being made
+
+## Running the workflow
+
+```bash
+bin/roast examples/apply_diff_demo/workflow.yml
+```
+
+## Expected interaction
+
+When you run this workflow, you'll see:
+
+1. The workflow creates a simple `hello.txt` file
+2. It proposes changing "Hello World!" to "Hello, Apply Diff Demo!"
+3. It shows you a colored diff of the proposed change:
+   ```
+   📝 Proposed change for hello.txt:
+   Description: Update greeting to be more specific to the demo
+   
+   diff --git a/hello.txt b/hello.txt
+   index 1234567..abcdefg 100644
+   --- a/hello.txt
+   +++ b/hello.txt
+   @@ -1,3 +1,3 @@
+   -Hello World!
+   +Hello, Apply Diff Demo!
+    This is a demo file.
+    We will modify this file in the next step.
+   ```
+4. It asks for your confirmation: `Apply this change? (y/n)`
+5. If you say "y", it applies the change; if "n", it cancels
+6. Finally, it reads the file again to show the result
+
+## Tools used
+
+- `Roast::Tools::WriteFile` - Creates the initial sample file
+- `Roast::Tools::ReadFile` - Reads files to show results
+- `Roast::Tools::ApplyDiff` - Shows colored diffs and applies changes with user confirmation
+
+This pattern is useful for any workflow where you want to make targeted changes to files but give users control over what actually gets applied.

data/examples/apply_diff_demo/apply_simple_change/prompt.md

@@ -0,0 +1,13 @@
+# Apply Simple Change
+
+Now use the apply_diff function to modify the `hello.txt` file. Let's change the greeting from "Hello World!" to "Hello, Apply Diff Demo!".
+
+Use the apply_diff function with:
+- `file_path`: "hello.txt"
+- `old_content`: "Hello World!"
+- `new_content`: "Hello, Apply Diff Demo!"
+- `description`: "Update greeting to be more specific to the demo"
+
+This will show the user a colored diff of the proposed change and ask for their confirmation before applying it.
+
+After the change is applied (or declined), read the file again to show the final result.

data/examples/apply_diff_demo/create_sample_file/prompt.md

@@ -0,0 +1,11 @@
+# Create Sample File
+
+Create a simple text file called `hello.txt` with the following content:
+
+```
+Hello World!
+This is a demo file.
+We will modify this file in the next step.
+```
+
+Use the write_file function to create this file.

data/examples/apply_diff_demo/workflow.yml

@@ -0,0 +1,24 @@
+# Apply Diff Demo
+#
+# This workflow demonstrates the apply_diff tool which shows users a diff
+# and applies changes based on their confirmation. It's useful for making
+# targeted changes to files with user approval.
+
+name: Apply Diff Demo
+model: gpt-4o-mini
+
+tools:
+  - Roast::Tools::WriteFile
+  - Roast::Tools::ReadFile
+  - Roast::Tools::ApplyDiff
+
+steps:
+  - create_sample_file
+  - apply_simple_change
+
+# Step configurations
+create_sample_file:
+  print_response: false
+
+apply_simple_change:
+  print_response: true

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/context_management_demo/README.md

@@ -0,0 +1,43 @@
+# Context Management Demo
+
+This example demonstrates Roast's automatic context management feature, which helps prevent workflow failures when conversation history exceeds the LLM's context window.
+
+## Features Demonstrated
+
+1. **Automatic Token Tracking**: Monitors token usage throughout workflow execution
+2. **Configurable Thresholds**: Set when to trigger warnings or compaction
+3. **Context Preservation**: Specify critical steps to retain during compaction
+
+## Configuration
+
+```yaml
+context_management:
+  enabled: true          # Enable context management
+  strategy: auto         # Compaction strategy (auto, summarize, prune, none)
+  threshold: 0.8         # Trigger at 80% of context window
+  max_tokens: 10000      # Override default limit (for demo purposes)
+  retain_steps:          # Steps to always keep in full
+    - analyze_requirements
+    - generate_summary
+```
+
+## Running the Demo
+
+```bash
+roast execute context_management_demo
+```
+
+The workflow intentionally generates verbose responses to demonstrate how context management handles large amounts of text without failing.
+
+## What to Observe
+
+1. **Token Usage Warnings**: Watch for warnings as the context approaches limits
+2. **Automatic Handling**: The workflow continues even with large outputs
+3. **Preserved Context**: Critical steps remain accessible throughout execution
+
+## Customization
+
+Try modifying the configuration:
+- Lower `max_tokens` to trigger compaction sooner
+- Change `strategy` to test different compaction approaches
+- Add more steps to `retain_steps` to preserve additional context

data/examples/context_management_demo/workflow.yml

@@ -0,0 +1,42 @@
+name: Context Management Demo
+tools:
+  - Roast::Tools::ReadFile
+  - Roast::Tools::WriteFile
+
+# Context management configuration
+context_management:
+  enabled: true
+  strategy: auto
+  threshold: 0.8  # Trigger compaction at 80% of context window
+  max_tokens: 10000  # Demo with smaller limit for testing
+  retain_steps:
+    - analyze_requirements
+    - generate_summary
+
+steps:
+  - analyze_requirements: |
+      Analyze this text and list the key requirements:
+      
+      We need a system that can:
+      1. Process customer orders
+      2. Track inventory levels
+      3. Generate reports
+      4. Handle refunds
+      5. Integrate with payment systems
+      
+  - expand_details: |
+      For each requirement from the previous step, provide detailed implementation notes,
+      technical considerations, and potential challenges. Be very thorough and verbose
+      to help test the context management system.
+      
+  - generate_more_context: |
+      Now describe the database schema needed for this system. Include all tables,
+      relationships, indexes, and data types. Be extremely detailed.
+      
+  - add_api_design: |
+      Design a complete REST API for this system. Include all endpoints, request/response
+      formats, authentication, and error handling. Provide examples for each endpoint.
+      
+  - generate_summary: |
+      Create a concise executive summary of the system design. Focus on the key decisions
+      and trade-offs made during the design process.

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/interpolation/workflow.yml

@@ -1,5 +1,5 @@
 name: interpolation_example
-model: anthropic:claude-3-7-sonnet
+model: gpt-4o-mini
 
 tools:
   - Roast::Tools::ReadFile

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:

data/examples/iteration/update_fix_count/prompt.md

@@ -2,19 +2,19 @@ I'll update the count of fixes that have been successfully applied.
 
 Current fix count: 
 ```
-{{output.update_fix_count || 0}}
+<%= output.update_fix_count || 0 %>
 ```
 
 Verification result from the previous step:
 ```json
-{{output.verify_fix}}
+<%= output.verify_fix %>
 ```
 
 I'll increment the fix count if the verification was successful or partial, but not if it failed.
 
 ```javascript
-let currentCount = parseInt({{output.update_fix_count || 0}});
-let verificationStatus = "{{output.verify_fix.status}}";
+let currentCount = parseInt(<%= output.update_fix_count || 0 %>);
+let verificationStatus = "<%= output.verify_fix.status %>";
 
 if (verificationStatus === "success" || verificationStatus === "partial") {
   currentCount += 1;

data/examples/iteration/verify_fix/prompt.md

@@ -2,17 +2,17 @@ I'll verify that the fix implemented in the previous step correctly addresses th
 
 Here are the details of the issue that was fixed:
 ```json
-{{output.select_next_issue}}
+<%= output.select_next_issue %>
 ```
 
 And here is the implementation of the fix:
 ```json
-{{output.implement_fix}}
+<%= output.implement_fix %>
 ```
 
 Now I'll read the updated file to verify the changes:
 ```ruby
-{{read_file(output.select_next_issue.file_path)}}
+<%= read_file(output.select_next_issue.file_path) %>
 ```
 
 I'll evaluate the fix based on these criteria: