roast-ai 0.4.0 → 0.4.2

data/docs/VALIDATION.md

@@ -0,0 +1,178 @@
+# Workflow Validation
+
+Roast provides comprehensive validation for workflow configurations to catch errors early and improve the development experience.
+
+## Using the Validation Command
+
+### Validate a Single Workflow
+
+```bash
+# Validate a specific workflow by path
+roast validate path/to/workflow.yml
+
+# Or by workflow name (assumes roast/ directory structure)
+roast validate my_workflow
+```
+
+### Validate All Workflows
+
+```bash
+# Validate all workflows in the roast/ directory
+roast validate
+```
+
+### Strict Mode
+
+Use the `--strict` or `-s` flag to treat warnings as errors:
+
+```bash
+roast validate --strict
+```
+
+## Validation Levels
+
+### 1. Schema Validation
+
+Ensures your workflow conforms to the JSON schema:
+- Required fields (name, tools, steps)
+- Correct data types
+- Valid structure for complex steps (if/then, case/when, each, repeat)
+
+### 2. Dependency Checking
+
+#### Tool Dependencies
+Validates that all declared tools are available:
+- Checks for tool module existence
+- Supports MCP tool configurations
+- Provides helpful suggestions for typos
+
+#### Step References
+Validates that steps referenced in conditions exist:
+- Checks `if`, `unless`, and `case` conditions
+- Distinguishes between step references and expressions
+
+#### Resource Dependencies
+Validates file resources:
+- Warns if target files don't exist (unless using glob patterns)
+- Checks for missing prompt files
+
+### 3. Configuration Linting
+
+#### Naming Conventions
+- Workflows should have descriptive names
+- Step names should use snake_case
+
+#### Complexity Checks
+- Warns about workflows with too many steps (>20)
+- Detects excessive nesting depth (>5 levels)
+
+
+#### Best Practices
+- Warns about missing error handling
+- Detects unused tool declarations
+
+## Error Messages
+
+The validator provides clear, actionable error messages:
+
+```
+Workflow validation failed with 2 error(s):
+
+• Missing required field: 'steps' (Add 'steps' to your workflow configuration)
+• Tool 'Roast::Tools::BashCommand' is not available (Did you mean: Roast::Tools::Bash?)
+```
+
+## Example Workflow
+
+Here's an example of a well-validated workflow:
+
+```yaml
+name: Data Processing Workflow
+tools:
+  - Roast::Tools::Bash
+  - Roast::Tools::ReadFile
+  - Roast::Tools::WriteFile
+
+# Use inputs for sensitive data
+inputs:
+  - api_token: "Enter your API token"
+
+# Enable error handling
+exit_on_error: true
+
+steps:
+  - validate_input
+  - fetch_data
+  - process_data
+  - save_results
+```
+
+## Integration with CI/CD
+
+You can integrate workflow validation into your CI/CD pipeline:
+
+```yaml
+# .github/workflows/validate.yml
+name: Validate Workflows
+on: [push, pull_request]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.0'
+          bundler-cache: true
+      - name: Validate all workflows
+        run: bundle exec roast validate --strict
+```
+
+## Programmatic Usage
+
+You can also use the validator programmatically:
+
+```ruby
+require 'roast'
+
+yaml_content = File.read('workflow.yml')
+validator = Roast::Workflow::Validators::ValidationOrchestrator.new(yaml_content, 'workflow.yml')
+
+if validator.valid?
+  puts "Workflow is valid!"
+  
+  # Check for warnings
+  validator.warnings.each do |warning|
+    puts "Warning: #{warning[:message]}"
+    puts "  → #{warning[:suggestion]}"
+  end
+else
+  # Handle errors
+  validator.errors.each do |error|
+    puts "Error: #{error[:message]}"
+    puts "  → #{error[:suggestion]}"
+  end
+end
+```
+
+## Architecture
+
+The validation system follows SOLID principles with a modular design:
+
+- **ValidationOrchestrator**: Coordinates all validators and aggregates results
+- **SchemaValidator**: Handles YAML parsing and JSON schema validation
+- **DependencyValidator**: Validates tools, step references, and resources
+- **LintingValidator**: Enforces best practices and code quality standards
+- **StepCollector**: Provides efficient caching for step traversal
+
+This architecture makes it easy to extend validation with new rules or customize existing behavior.
+
+## Future Enhancements
+
+The validation system is designed to be extensible. Future enhancements may include:
+
+- Detection of circular dependencies
+- Performance analysis and optimization suggestions
+- Custom validation rules via plugins
+- Integration with language servers for real-time validation

data/examples/agent_continue/add_documentation/prompt.md

@@ -0,0 +1,5 @@
+Add documentation to the refactored code.
+Include:
+- Method documentation
+- Class-level documentation
+- Usage examples where appropriate

data/examples/agent_continue/add_error_handling/prompt.md

@@ -0,0 +1,5 @@
+Enhance the GitHub client with comprehensive error handling:
+- Network errors
+- Authentication failures
+- Rate limit exceeded
+- API validation errors

data/examples/agent_continue/analyze_codebase/prompt.md

@@ -0,0 +1,7 @@
+Analyze this Ruby codebase and identify areas that could benefit from refactoring.
+Focus on:
+- Code duplication
+- Complex methods that could be simplified
+- Missing abstractions
+
+Create a list of suggested improvements.

data/examples/agent_continue/combined_workflow.yml

@@ -0,0 +1,24 @@
+description: Example combining both continue and context summary features
+
+# This example shows how both parameters can work together for complex workflows
+
+steps:
+  # Initial exploration
+  - explore_api
+  
+  # First coding agent task
+  - ^implement_client
+  
+  # Continue with context awareness
+  - ^add_error_handling
+  
+  # Final implementation with full context
+  - ^create_integration_tests
+
+add_error_handling:
+  continue: true  # Continue working on the same client
+  include_context_summary: true  # Include context about what was explored and built
+
+create_integration_tests:
+  continue: true  # Continue in the same session
+  include_context_summary: true  # Full context of implementation

data/examples/agent_continue/continue_adding_features/prompt.md

@@ -0,0 +1,4 @@
+Now add these additional features to the todo list class:
+- Mark items as complete
+- Filter by status (complete/incomplete)
+- Save to and load from a JSON file

data/examples/agent_continue/create_integration_tests/prompt.md

@@ -0,0 +1,3 @@
+Create integration tests for the GitHub client.
+Test all the functionality including error scenarios.
+Use VCR for recording API interactions.

data/examples/agent_continue/document_with_context/prompt.md

@@ -0,0 +1,5 @@
+Based on what has been implemented so far, create a comprehensive README.md file that includes:
+- Overview of the TodoList class
+- All available methods and their usage
+- Code examples
+- Installation instructions

data/examples/agent_continue/explore_api/prompt.md

@@ -0,0 +1,6 @@
+Explore the GitHub API and document:
+- Key endpoints for repository management
+- Authentication requirements
+- Rate limiting considerations
+
+Format as a structured summary.

data/examples/agent_continue/implement_client/prompt.md

@@ -0,0 +1,6 @@
+Create a Ruby client for the GitHub API that includes:
+- Basic authentication
+- Repository listing
+- Repository creation
+
+Use the information from the API exploration.

data/examples/agent_continue/inline_workflow.yml

@@ -0,0 +1,20 @@
+description: Example workflow using inline agent prompts with continuation
+
+# This example demonstrates using inline agent prompts (direct text after ^)
+# combined with the new parameters
+
+steps:
+  # Start with a fresh context
+  - ^Create a simple Ruby class for managing a todo list with add, remove, and list methods
+  
+  # Continue from previous session to add more features
+  - ^continue_adding_features
+  
+  # Use context summary to understand what was built
+  - ^document_with_context
+
+continue_adding_features:
+  continue: true  # This continues from the previous agent session
+
+document_with_context:
+  include_context_summary: true  # This will include context about previous steps

data/examples/agent_continue/refactor_code/prompt.md

@@ -0,0 +1,2 @@
+Now implement the refactoring suggestions you identified.
+Start with the highest priority items.

data/examples/agent_continue/verify_changes/prompt.md

@@ -0,0 +1,6 @@
+Review all the changes made by the coding agent steps.
+Provide a summary of:
+- What was analyzed
+- What refactorings were applied
+- What documentation was added
+- Any potential issues or concerns

data/examples/agent_continue/workflow.yml

@@ -0,0 +1,27 @@
+description: Example workflow demonstrating agent continuation and context summary features
+
+# This example shows how to use the new coding agent parameters:
+# - continue: true - continues from previous agent session
+# - include_context_summary: true - includes workflow context in the prompt
+
+target: "**/*.rb"
+
+steps:
+  # First agent step - starts fresh
+  - ^analyze_codebase
+  
+  # Second agent step - continues from previous session
+  - ^refactor_code
+  
+  # Third agent step - includes context summary from previous steps
+  - ^add_documentation
+  
+  # Final verification step
+  - verify_changes
+
+# Step configurations
+refactor_code:
+  continue: true  # Continue from the previous agent session
+
+add_documentation:
+  include_context_summary: true  # Include workflow context in the prompt

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/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/rb_test_runner

@@ -4,7 +4,7 @@
 require "rubygems"
 require "bundler/setup"
 
-require_relative "../../lib/roast/helpers/minitest_coverage_runner"
+require "roast/helpers/minitest_coverage_runner"
 
 # Suppress fancy minitest reporting
 ENV["RM_INFO"] = "true"

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

@@ -0,0 +1,17 @@
+# No Model Fallback Example
+
+This example demonstrates the issue where workflows without explicit model specification do not properly fall back to a default model.
+
+## Purpose
+
+This workflow is based on the interpolation example but intentionally omits the `model` field to test the fallback behavior.
+
+## Expected Behavior
+
+The workflow should fall back to a default model when no model is specified at the workflow level.
+
+## Usage
+
+```bash
+bin/roast examples/no_model_fallback/workflow.yml --file examples/no_model_fallback/sample.rb
+```

data/examples/no_model_fallback/analyze_file/prompt.md

@@ -0,0 +1 @@
+Analyze the file at: <%= workflow.file %>

data/examples/no_model_fallback/analyze_patterns/prompt.md

@@ -0,0 +1,27 @@
+Extract some patterns about this file and return in json format like this:
+
+<json>
+{
+  "code_patterns": {
+    "class_structure": {
+      "name": "Calculator",
+      "instance_variables": ["@memory"],
+      "method_count": 7,
+      "method_types": {
+        "constructor": ["initialize"],
+        "operations": ["add", "subtract", "multiply", "divide"],
+        "accessors": ["memory"],
+        "utility": ["clear"]
+      }
+    },
+    "error_handling": {
+      "techniques": ["conditional raise", "zero check"],
+      "examples": ["raise \"Division by zero!\" if number.zero?"]
+    },
+    "design_patterns": {
+      "state": "Uses instance variable to maintain calculator state",
+      "command": "Each operation method modifies the internal state"
+    }
+  }
+}
+</json>

data/examples/no_model_fallback/generate_report_for_md/prompt.md

@@ -0,0 +1,10 @@
+Generate a comprehensive report for the markdown file.
+
+File content: {{steps.analyze_file}}
+
+Patterns found: {{steps.analyze_patterns}}
+
+Please create a detailed report that includes:
+1. Summary of the file content
+2. Key patterns identified
+3. Any recommendations or observations

data/examples/no_model_fallback/generate_report_for_rb/prompt.md

@@ -0,0 +1,3 @@
+Generate a nicely formatted report based on the following metadata:
+
+<%= workflow.output[:analyze_patterns] %>