Shopify/roast

Roast is a Ruby-based workflow orchestration library that structures complex AI interactions and system tasks into modular, reusable components called 'cogs'. It provides a command-line interface to execute workflows composed of atomic units for LLM communication (via Chat and Agent cogs) and system operations (such as command execution and file manipulation). The system supports multi-provider LLM integration, parallel and asynchronous execution, and detailed usage tracking, allowing users to chain, map, and loop over these cogs to build deterministic, multi-turn AI-driven pipelines.

12 changes.

The project underwent a significant infrastructure overhaul, migrating the test suite from RSpec to Minitest and introducing Sorbet for static type checking. A new CLI interface was built using Zeitwerk autoloading, replacing the previous CLI::Kit framework and renaming the gem to roast-ai. This period focused on modernizing the development environment, standardizing tooling, and establishing a robust execution engine for workflows.

29 changes.

This period focused on establishing the core Roast workflow engine, introducing foundational classes for configuration, execution, and registry. It expanded the system with dedicated Agent and Chat cogs supporting multiple LLM providers, alongside new control-flow cogs for calling, mapping, and repeating scopes. The work was complemented by comprehensive testing, Sorbet type definitions, and extensive documentation to support the new capabilities.

The project now includes generated Sorbet RBI files for key dependencies, including Active Support 8.0.2, Addressable 2.8.7, AST 2.4.3, Async 2.34.0, Base64 0.3.0, Benchmark 0.4.1, Faraday, Minitest, Mocha, Rainbow, and Webmock. These annotations provide static type definitions for the gems, enabling Sorbet to perform type checking on the codebase.

sorbet/rbi · high confidence

The examples/demo directory now includes new Ruby files demonstrating the Roast workflow library. local.rb defines a custom workflow-specific cog, while multiloading.rb and simple\_external\_cog.rb illustrate how to use the 'use' syntax to load cogs from external plugin gems (plugin\_gem\_example) and local sources within a single workflow execution.

examples/demo · high confidence

New example files have been added to the repository, including a Ruby plugin gem structure (plugin-gem-example) with sample cogs and a simple prompt template (simple\_prompt.md.erb) for generating playful responses about lakes.

examples/plugin-gem-example, examples/prompts · high confidence

The chat cog has been updated to support OpenAI, Anthropic, Perplexity, and Gemini as API providers, allowing users to switch between different language models. A new environment variable, ROAST\_DEFAULT\_CHAT\_PROVIDER, lets users set a global default provider, which can be overridden by explicit cog configuration. The cog also introduces session management to maintain conversation context across multiple interactions, enabling multi-turn chats without requiring the user to manually pass history.

lib/roast/cogs/chat · high confidence

The examples directory now includes new demonstrations for agent sessions (including multi-prompt agents and Pi provider support), asynchronous command execution, sub-executor invocation with \call\ and \map\, accessing outputs from called scopes via \from\ and \collect\, parallel map execution, loop control with \repeat\, and workflow parameter access.

examples · high confidence

This change introduces the initial configuration for Sorbet type checking and Tapioca RBI generation. A new \sorbet/tapioca/config.yml\ file is added to exclude \yard\ and \yard-sorbet\ gems from RBI generation, as they are unused by the project. Additionally, a \sorbet/tapioca/require.rb\ file is created to explicitly list required libraries (such as \active\_support\, \async\, \rainbow\, and \sqlite3\) to ensure Tapioca generates correct RBI files for these dependencies.

sorbet/tapioca · high confidence

The project now includes a Sorbet configuration file that enables experimental features (requires\_ancestor and RBS comments) and defines directories to ignore (such as .git, test, and vendor) for static type analysis.

sorbet · high confidence

Adds a new agent provider implementation for the Pi coding agent, enabling users to interact with Pi as a cog-based agent. The new \PiInvocation\ class manages the agent's lifecycle, including session handling, prompt execution, and processing of streaming block events (such as message updates and tool executions) to provide real-time feedback and final results.

lib/roast/cogs/agent/providers/pi · high confidence

The Agent cog now supports configurable AI providers (defaulting to Pi, with Claude also available) and allows users to override the default provider via the ROAST\_DEFAULT\_AGENT\_PROVIDER environment variable. Users can send multiple prompts in a single session, enabling complex, multi-turn workflows where subsequent prompts are processed after the agent completes the previous one. The cog also tracks and exposes detailed execution statistics, including duration, conversation turns, token usage, and cost in USD, broken down by model when multiple models are used.

lib/roast/cogs/agent · high confidence

This change establishes the foundational classes for the Roast workflow engine within the \lib/roast/cog\ directory. It adds \Roast::Cog::Config\ to manage cog settings (including async execution and abort-on-failure behavior), \Roast::Cog::Input\ and \Roast::Cog::Output\ to define how data is passed into and retrieved from cogs (with robust JSON and number parsing fallbacks in outputs), and \Roast::Cog::Registry\ to automatically register standard system cogs like \Call\, \Map\, \Repeat\, \Cmd\, \Chat\, \Agent\, and \Ruby\. Additionally, it provides \Stack\ and \Store\ utilities to manage cog execution order and instance storage.

lib/roast/cog · high confidence

Roast now provides a command-line interface (CLI) to run workflows, supporting commands like 'execute', 'version', and 'help'. The system introduces a new execution engine where workflows are defined using 'cogs' (atomic tasks) that can be configured and executed within a structured context. This includes a new event-based logging system that captures stdout/stderr, supports colored output, and allows for workflow-level configuration and parameter access.

lib/roast · high confidence

Added type signatures for \Roast::CogInputContext\, \Roast::ConfigContext\, and \Roast::ExecutionContext\ to improve static analysis of workflow definitions. These shims expose methods for accessing workflow targets (\target!\, \targets\), arguments (\arg?\, \args\), and keyword arguments (\kwarg\, \kwarg!\), as well as configuration options for cogs like \map\, \repeat\, and \agent\ (including parallel execution, async behavior, and agent provider settings). The \ExecutionContext\ shims define the \outputs!\ and \outputs\ blocks for defining scope return values and the \call\, \map\, and \repeat\ cogs for workflow orchestration.

sorbet/rbi/shims/lib/roast · high confidence

This change introduces a new directory for internal documentation comments (\internal/documentation/comments/\) containing guidelines for both user-facing and developer-facing documentation, including architectural notes on the \agent\ vs \chat\ cog distinctions. It also adds a custom RuboCop cop (\Roast/NoTestClassNesting\) to prevent IDE test-discovery issues by enforcing \::\ scoping in test files, and introduces two internal maintenance workflows: one to analyze git diffs for documentation impact and another to update references to deprecated LLM models.

internal · high confidence

This change introduces three new system cogs that allow workflows to invoke named execution scopes with greater control. The \call\ cog executes a single scope and provides its output via the \from\ method. The \map\ cog iterates over a collection, executing the scope for each item with configurable serial or parallel execution modes. The \repeat\ cog loops over a scope until a \break!\ is triggered, passing the output of one iteration as the input to the next, and exposes results from all iterations. These cogs share a common parameter structure for naming and scope identification.

_lib/roast/system\_cog, lib/roast/system\cogs · high confidence

Added a comprehensive, multi-chapter tutorial series (Chapters 1–6) that guides users through creating and running Roast workflows. The tutorials cover core concepts including the \chat\ and \agent\ cogs, chaining steps, passing targets and parameters, configuring models and providers (OpenAI, Anthropic, Perplexity, Gemini), control flow with \skip!\ and \fail!\, and reusable scopes with the \call\ cog. New example workflows demonstrate these features, such as a code security review pipeline and session resumption.

tutorial · high confidence

Added Sorbet RBI type definitions for the \Roast::Cog::Config\ class to enable type-checking of workflow parameter access within configuration blocks. This change exposes methods for retrieving single or multiple targets (\target!\, \targets\), checking for and retrieving flag arguments (\arg?\, \args\), and accessing keyword arguments (\kwarg\, \kwarg!\, \kwargs\), allowing workflows to dynamically configure behavior based on invocation arguments.

sorbet/rbi/shims/lib/roast/cog · high confidence

The Claude agent provider now includes dedicated formatters for tool use requests (such as Bash, Read, Write, Edit, Glob, Grep, and Skills) and their corresponding results. This change improves the user experience by providing structured, human-readable summaries of agent actions and outputs directly in the terminal, rather than raw JSON or unformatted text. The implementation handles various tool types with specific formatting rules, such as truncating long commands or displaying line counts for file operations, and integrates with the existing event logging system to display these formatted messages when progress is enabled.

lib/roast/cogs/agent/providers/claude · high confidence

The \lib/roast/cogs\ area now includes dedicated \Agent\ and \Chat\ cogs to separate local coding tasks from pure LLM interaction. The Agent cog supports Claude and Pi providers, allowing local filesystem access and tool execution, while the Chat cog supports OpenAI, Anthropic, Perplexity, and Gemini providers for cloud-based LLM calls. A key behavioral change in the Chat cog is the detection of max-token truncation, which now raises an error if the response is cut off, ensuring users are aware of incomplete outputs.

lib/roast/cogs · high confidence

The library has replaced the CLI::Kit framework with a custom implementation using Ruby's standard library (optparse) and Zeitwerk for autoloading, removing the previous CLI::Kit dependencies and command registry structure. This change also consolidates third-party gem requirements (such as ActiveSupport, Rainbow, and RubyLLM) into the main entry point and removes legacy command files like 'example' and 'help' that were tied to the old CLI structure.

lib · high confidence

The project has standardized its development environment by upgrading the target Ruby version to 3.4.7, migrating the test suite from RSpec to Minitest, and introducing Sorbet for static type checking. This change updates the Rakefile to include dedicated tasks for Rubocop, Sorbet, and Minitest, configures Rubocop with Sorbet and Shopify plugins, and adds a new \dev.yml\ file to streamline local development commands. Additionally, legacy configuration files like \CLAUDE.md\ have been removed, and the gem name has been corrected to \roast-ai\ in the documentation.

(repo-wide) · high confidence

The Pi agent provider now includes dedicated formatters for tool calls (bash, read, write, edit, grep, find) and their corresponding results. This change introduces concise, human-readable terminal output for agent actions, such as displaying truncated command previews for bash, file paths and line ranges for read/write, and match counts for grep and find, ensuring that complex tool interactions are presented clearly in the UI.

lib/roast/cogs/agent/providers/pi/messages · high confidence

The Claude provider now uses dedicated message classes (AssistantMessage, ResultMessage, SystemMessage, TextMessage, ThinkingMessage, ToolResultMessage, ToolUseMessage, UnknownMessage, and UserMessage) to parse and format incoming data. This change introduces specific handling for different message types, including support for Claude's 'thinking' messages, improved error message extraction in ResultMessage, and explicit field ignoring to clean up internal metadata before processing.

lib/roast/cogs/agent/providers/claude/messages · high confidence

The Claude and Pi agent providers now handle multiple prompts within a single invocation. Instead of processing only the first prompt, the agents iterate through all provided prompts, chaining them together by reusing the session from the previous step (avoiding unnecessary forking for subsequent prompts). Additionally, usage statistics (stats) from all individual prompt invocations are summed and returned in the final result, giving users a complete view of resource consumption across the entire multi-prompt sequence.

lib/roast/cogs/agent/providers · high confidence

The executable now requires the 'roast-ai' library instead of 'roast' and invokes the CLI via Roast::CLI.start(ARGV), replacing the previous ErrorHandler/EntryPoint pattern. This change aligns the entry point with the Thor-based CLI implementation and simplifies execution flow.

exe · high confidence

The bin directory has been updated to include new Bundler-generated binstubs for development tools (rubocop, spoom, srb, srb-rbi, tapioca) and the main application (roast), while removing the custom bin/setup and bin/testunit scripts. The bin/console script has also been refactored to explicitly add the lib directory to the load path before requiring the application, ensuring correct module loading in interactive sessions.

bin · high confidence

Added VCR-based functional test infrastructure for DSL examples; Added comprehensive test coverage for Roast CLI, execution engine, and logging; Added functional tests for Roast example workflows; Added test coverage for Claude agent provider components; Added test coverage for Claude and Pi agent providers; Added test coverage for system cogs; Added test coverage for the Chat cog components; Added test support infrastructure for Minitest assertions and test cogs; Added tests for Claude agent message types; Added tests for Cmd and Ruby cog components; Added tests for Pi agent tool call and result message formatting; Added tests for the NoTestClassNesting RuboCop cop; Added tests for the Pi agent invocation provider; Added unit tests for core Cog components; Migrate test suite to Minitest and modernize test infrastructure.

The gem has been renamed from 'roast' to 'roast-ai' (including the gemspec and Gemfile references), and its runtime dependencies have been updated to use activesupport (\~\> 8.0), async (\>= 2.34), rainbow (\>= 3.0.0), ruby\_llm (\>= 1.13), type\_toolkit (\>= 0.0.5), and zeitwerk (\>= 2.6). Two new example projects have been added: 'examples/demo' which demonstrates using the roast-ai gem, and 'examples/plugin-gem-example' which shows how to create a plugin gem that depends on roast-ai. The main project's development dependencies have also been updated to include guard-minitest, minitest-rg, rubocop-sorbet, simplecov, sorbet, sqlite3, and tapioca.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• First survey — no prior run to compare against. CAI 64.

• Code Health 97
• Architecture 93
• Maturity 57
• Readiness 53
• Security 84

• 300 commits — 277 feature/other, 23 fixes

• lib/roast — 137 commits
• (root) — 45 commits
• test/roast — 39 commits
• dsl/tutorial — 12 commits
• examples/demo — 9 commits
• examples/plugin-gem-example — 8 commits
• sorbet/rbi — 6 commits
• .claude/commands — 4 commits
• internal/documentation — 4 commits
• dsl/repeat_loop_results.rb — 3 commits
• internal/workflows — 3 commits
• test/fixtures — 3 commits
• dsl/demo — 2 commits
• exe/roast — 2 commits
• lib/roast.rb — 2 commits
• test/examples — 2 commits
• .github/CODEOWNERS — 1 commit
• docs/AGENT_STEPS.md — 1 commit
• dsl/async_cogs.rb — 1 commit
• dsl/map.rb — 1 commit

• fix: Fix next! in map and call (#652)
• fix: Fix self: sigs on .rbi shims (#559)
• fix: Fix abort_on_failure handling (#650)
• fix: Fix agent cog not respecting show_progress? config setting (#571)
• fix: Fix blank error message on failed Claude agent runs (#947)
• fix: Fix broken links (#752)
• fix: Fix conflicting implied types (#561)
• fix: Fix dev test (#771)
• fix: Fix duplicate tool result message in claude user message (#634)
• fix: Fix fail_on_error for cmd cog (#651)
• fix: Fix minor tutorial docs mistakes (#866)
• fix: Fix model_finder references check to handle nil references (#989)
• fix: Fix number parsing order (#853)
• fix: Fix requires_ancestor sigs (#549)
• fix: Fix sorbet issue in minitest_coverage_runner (#654)
• fix: Fix stderr display description in README (#865)
• fix: Fix test flakes caused by non-ascii letters in example cog output (#547)
• fix: Fix valid_provider! raising ArgumentError instead of InvalidConfigError (#964)
• fix: Fix versions in demo gem (#673)
• fix: Fix versions to fix CI failures (#666)
• …and 280 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

Shopify/roast was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.