To Nha Notes | Aug. 6, 2025, 2:11 p.m.
Roast is a Ruby‑based, convention‑oriented workflow framework designed to bring structure, traceability, and reproducibility to AI workflows—especially those involving development tasks like code analysis, test grading, or documentation generation Medium+10Shopify+10X (formerly Twitter)+10.
Convention over configuration: Use a YAML-based workflow.yml plus Markdown (or ERB-templated) prompt files to define each workflow step ainativedev.io+6GitHub+6Shopify+6.
Built-in tools: Includes tools like ReadFile, Grep, UpdateFiles, Cmd, Bash, and a powerful CodingAgent integration with Claude Code for agentic behavior Medium+3GitHub+3Shopify+3.
Context sharing: Each step shares conversation transcripts and output context for smooth, multi-step reasoning.
Step customization and parallelism: Customize models and tools per step, and even run steps in parallel using YAML nested arrays ainativedev.io+3GitHub+3Shopify+3.
Session replay & caching: Rerun workflows from a specific step or cache expensive function results to speed iteration.
Instrumentation: Monitor token usage, tool usage, performance, and execution via ActiveSupport instrumentation GitHub+1.
Define your workflow in workflow.yml:
name: analyze_tests model: gpt-4o-mini tools: - Roast::Tools::ReadFile - Roast::Tools::Grep steps: - read_test_file - analyze_coverage - generate_report analyze_coverage: model: gpt-4‑turbo json: true
Each step is backed by a local prompt.md. You can also define shell steps via $(), inline prompts, or fully custom steps in Ruby via BaseStep subclasses. Shared workflows, validation tools, and conditional step execution make it flexible and production-ready code.dblock.org | tech blog+3GitHub+3Shopify+3.
A key early use case at Shopify: grading the quality of Ruby unit tests at scale. Roast dissects each test file step-by-step—reading file content, analyzing coverage, and generating feedback—using a mix of deterministic logic and LLM-powered analysis code.dblock.org | tech blog+2Shopify+2.
The integrated CodingAgent takes this further by iteratively fixing code, running tests, and refining modifications until desired test quality is reached—an elegant blend of AI autonomy within a structured workflow Shopify+1.
Deterministic AI: By breaking AI workflows into small, explicit steps, Roast ensures reasoning is auditable, reproducible, and version controlled—unlike free-form prompt chains.
Hybrid workflows: Replace early-stage AI-powered steps with deterministic code as your problem understanding matures.
Workflow-first AI: Think of Roast as a CI/CD-like system for AI tasks—a new cornerstone for production-grade, AI-powered development automation Shopify+1.
Ensure you have Ruby 3.0+, an OpenAI or OpenRouter API key.
Install: gem install roast-ai.
Write your workflow.yml and prompt.md files.
Run: roast execute workflow.yml <target-files> or leverage targetless workflows for API/report generation tasks.
Pro tip: using tools like shadowenv and ripgrep (rg) can enhance workflow precision and performance Shopifycode.dblock.org | tech blog+1GitHub+2code.dblock.org | tech blog+2.
Roast is purpose-built for structured, reliable, and versioned AI workflows.
It empowers hybrid automation: AI where needed, deterministic code where possible.
With built‑in instrumentation, caching, and step replay, it's ideal for scalable, production use.
Whether you're building AI‑powered test review tools, documentation generators, or code refactoring agents, Roast gives you the scaffolding to build them with confidence.
Ready to try it out? Dive into the GitHub repository and start building structured AI workflows today.