roast-ai 0.3.1 → 0.4.1

data/docs/AGENT_STEPS.md

@@ -0,0 +1,288 @@
+# 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.
+
+## Agent Step Configuration Options
+
+Agent steps support two special configuration options:
+
+### `continue` (boolean, default: false)
+When set to `true`, the agent continues from its previous session instead of starting fresh. This is useful for iterative development where you want the agent to maintain context across multiple steps.
+
+### `include_context_summary` (boolean, default: false)
+When set to `true`, the agent receives an AI-generated summary of the workflow context as a system directive. This summary is intelligently tailored to the agent's upcoming task, including only relevant information from previous steps. The summary is generated by analyzing:
+- The agent's prompt to understand what context would be helpful
+- Previous step outputs and their relevance to the current task
+- Workflow description and configuration
+- Current working directory
+
+This helps the agent understand what has been done so far without overwhelming it with irrelevant details. NOTE: Without this option, the agent relies solely on what it is instructed to do either by the prompt or your specific step instructions.
+
+```yaml
+steps:
+  - analyze_code
+  - implement_fix: ^Fix the issues identified in the analysis
+  - add_tests: ^Prepare and publish PR
+
+implement_fix:
+  include_context_summary: true  # Include a summary of the workflow context so far
+
+add_tests:
+  continue: true # does not need context since is continuing from the previous step
+```
+
+## 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. Create a new migration 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
+```
+
+This is better as an agent step because:
+- The instructions are precise and technical
+- No interpretation needed - just execution of steps known beforehand
+
+### 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
+   ```
+
+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.
+
+The `continue` and `include_context_summary` options make agent steps even more powerful for iterative development workflows where maintaining context is important.
+
+Choose agent steps when precision matters more than interpretation. Choose regular steps when context and judgment are important.

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