roast-ai 0.3.1 → 0.4.1

data/README.md

@@ -82,13 +82,13 @@ steps:
 
 ## Try it
 
-If you don't have one already, get an OpenAI key from [here](https://platform.openai.com/settings/organization/api-keys). You will need an account with a credit card, make sure that a basic completion works.
+If you don’t have one already, get an OpenAI key from [here](https://platform.openai.com/settings/organization/api-keys). You will need an account with a credit card and credits applied to the associated project. Make sure that a basic completion works:
 
 ```bash
 export OPENAI_API_KEY=sk-proj-....
 
 curl -H "Content-Type: application/json" \
-    -H "Authorization: Bearer $API_TOKEN" \
+    -H "Authorization: Bearer $OPENAI_API_KEY" \
     -d '{"model":"gpt-4.1-mini","messages":[{"role":"user","content":"What is 1+1?"}]}' \
     https://api.openai.com/v1/chat/completions
 ```
@@ -270,6 +270,45 @@ Roast supports several types of steps:
    ```
    This creates a simple prompt-response interaction without tool calls or looping. It's detected by the presence of spaces in the step name and is useful for summarization or simple questions at the end of a workflow.
 
+8. **Agent step**: Direct pass-through to coding agents (e.g., Claude Code)
+   ```yaml
+   steps:
+     - ^fix_linting_errors                                    # File-based agent prompt
+     - ^Review the code and identify any performance issues   # Inline agent prompt
+     - regular_analysis                                       # Normal step through LLM
+   ```
+   Agent steps are prefixed with `^` and send the prompt content directly to the CodingAgent tool without LLM translation. This is useful when you want to give precise instructions to a coding agent without the intermediate interpretation layer. Agent steps support both file-based prompts (`fix_linting_errors/prompt.md`) and inline prompts (text with spaces).
+
+9. **Input step**: Interactive prompts for user input during workflow execution
+   ```yaml
+   steps:
+     - analyze_code
+     - get_user_feedback:
+         prompt: "Should we proceed with the refactoring? (yes/no)"
+         type: confirm
+     - review_changes:
+         prompt: "Enter your review comments"
+         type: text
+     - select_strategy:
+         prompt: "Choose optimization strategy"
+         type: select
+         options:
+           - "Performance optimization"
+           - "Memory optimization"
+           - "Code clarity"
+     - api_configuration:
+         prompt: "Enter API key"
+         type: password
+   ```
+   
+   Input steps pause workflow execution to collect user input. They support several types:
+   - `text`: Free-form text input (default if type not specified)
+   - `confirm`: Yes/No confirmation prompts
+   - `select`: Choice from a list of options
+   - `password`: Masked input for sensitive data
+   
+   The user's input is stored in the workflow output using the step name as the key and can be accessed in subsequent steps via interpolation (e.g., `{{output.get_user_feedback}}`).
+
 #### Step Configuration
 
 Steps can be configured with various options to control their behavior:
@@ -366,6 +405,72 @@ For typical AI workflows, the continuous conversation history provides seamless
 - `-c, --concise`: Use concise output templates (exposed as a boolean flag on `workflow`)
 - `-v, --verbose`: Show output from all steps as they execute
 - `-r, --replay STEP_NAME`: Resume a workflow from a specific step, optionally with a specific session timestamp
+- `-f, --file-storage`: Use filesystem storage for sessions instead of SQLite (default: SQLite)
+
+#### Workflow Validation
+
+Roast provides a `validate` command to check workflow configuration files for errors and potential issues before execution:
+
+```bash
+# Validate a specific workflow
+roast validate workflow.yml
+
+# Validate a workflow in a subdirectory
+roast validate my_workflow
+
+# Validate with strict mode (treats warnings as errors)
+roast validate workflow.yml --strict
+```
+
+The validator checks for:
+- YAML syntax errors
+- Missing required fields
+- Invalid step references
+- Circular dependencies
+- Tool availability
+- Prompt file existence
+- Configuration consistency
+
+This helps catch configuration errors early and ensures workflows will run smoothly.
+
+#### Session Storage and Management
+
+Roast uses SQLite by default for session storage, providing better performance and advanced querying capabilities. Sessions are automatically saved during workflow execution, capturing each step's state including conversation transcripts and outputs.
+
+**Storage Options:**
+
+```bash
+# Use default SQLite storage (recommended)
+roast execute workflow.yml
+
+# Use legacy filesystem storage
+roast execute workflow.yml --file-storage
+
+# Set storage type via environment variable
+ROAST_STATE_STORAGE=file roast execute workflow.yml
+```
+
+**Session Management Commands:**
+
+```bash
+# List all sessions
+roast sessions
+
+# Filter sessions by status
+roast sessions --status waiting
+
+# Filter sessions by workflow
+roast sessions --workflow my_workflow
+
+# Show sessions older than 7 days
+roast sessions --older-than 7d
+
+# Clean up old sessions
+roast sessions --cleanup --older-than 30d
+
+# View detailed session information
+roast session <session_id>
+```
 
 #### Session Replay
 
@@ -379,14 +484,14 @@ roast execute workflow.yml -r step_name
 roast execute workflow.yml -r 20250507_123456_789:step_name
 ```
 
-Sessions are automatically saved during workflow execution. Each step's state, including the conversation transcript and output, is persisted to a session directory. The session directories are organized by workflow name and file, with timestamps for each run.
-
 This feature is particularly useful when:
 - Debugging specific steps in a long workflow
 - Iterating on prompts without rerunning the entire workflow
 - Resuming after failures in long-running workflows
 
-Sessions are stored in the `.roast/sessions/` directory in your project. Note that there is no automatic cleanup of session data, so you might want to periodically delete old sessions yourself.
+**Storage Locations:**
+- SQLite: `~/.roast/sessions.db` (configurable via `ROAST_SESSIONS_DB`)
+- Filesystem: `.roast/sessions/` directory in your project
 
 #### Target Option (`-t, --target`)
 
@@ -658,6 +763,52 @@ tools:
 
 Custom descriptions help the LLM understand when and how to use each command, making your workflows more effective.
 
+### Step-Level Tool Filtering
+
+You can restrict which tools are available to specific steps using the `available_tools` configuration:
+
+```yaml
+# Define all tools globally
+tools:
+  - Roast::Tools::Grep
+  - Roast::Tools::ReadFile
+  - Roast::Tools::WriteFile
+  - Roast::Tools::Cmd:
+      allowed_commands:
+        - pwd
+        - ls
+        - echo
+
+# Configure steps with specific tool access
+explore_directory:
+  available_tools:
+    - pwd
+    - ls
+
+analyze_files:
+  available_tools:
+    - grep
+    - read_file
+
+write_summary:
+  available_tools:
+    - write_file
+    - echo
+```
+
+This feature provides:
+- **Security**: Each step only has access to the tools it needs
+- **Performance**: Reduces the tool list sent to the LLM
+- **Clarity**: Makes tool usage explicit for each step
+
+Key points:
+- Use snake_case tool names (e.g., `read_file` for `Roast::Tools::ReadFile`)
+- For `Cmd` tool, use the specific command names (e.g., `pwd`, `ls`)
+- When `available_tools` is not specified, all tools remain available (backward compatible)
+- Empty array (`available_tools: []`) means no tools for that step
+
+See the [available_tools_demo](examples/available_tools_demo/) for a complete example.
+
 #### ReadFile
 
 Reads the contents of a file from the filesystem.
@@ -836,14 +987,14 @@ tools:
   - Documentation:
       url: https://gitmcp.io/myorg/myrepo/docs
       env:
-        - "Authorization: Bearer {{env.API_TOKEN}}"
+        - "Authorization: Bearer {{ENV['API_TOKEN']}}"
 
   # MCP tools with stdio
   - GitHub:
       command: npx
       args: ["-y", "@modelcontextprotocol/server-github"]
       env:
-        GITHUB_PERSONAL_ACCESS_TOKEN: "{{env.GITHUB_TOKEN}}"
+        GITHUB_PERSONAL_ACCESS_TOKEN: "{{ENV['GITHUB_TOKEN']}}"
       only:
         - search_repositories
         - get_issue
@@ -872,7 +1023,7 @@ Connect to local processes implementing the MCP protocol:
     command: docker
     args: ["run", "-i", "--rm", "ghcr.io/example/mcp-server"]
     env:
-      API_KEY: "{{env.API_KEY}}"
+      API_KEY: "{{ENV['API_KEY']}}"
 ```
 
 See the [MCP tools example](examples/mcp/) for complete documentation and more examples.

data/bin/console

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 require "bundler/setup"
 

data/bin/roast

@@ -8,7 +8,7 @@
 # this file is here to facilitate running it.
 #
 
-ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../.ruby-lsp/Gemfile", __dir__)
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
 
 bundle_binstub = File.expand_path("bundle", __dir__)
 

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.