Crate ralph_workflow 

Ralph workflow library for AI agent orchestration.

This crate provides the core functionality for the ralph CLI binary, implementing a reducer-based architecture for orchestrating AI coding agents through development and review cycles.

Quick Start

Ralph is primarily a CLI binary. For library use (integration testing):

[dev-dependencies]
ralph-workflow = { version = "0.6", features = ["test-utils"] }

Architecture

Ralph uses an event-sourced reducer architecture. The core state machine follows the pattern:

State → Orchestrator → Effect → Handler → Event → Reducer → State

Component	Pure?	Role
reducer::PipelineState	Yes	Immutable progress snapshot, doubles as checkpoint
reducer::reduce	Yes	(State, Event) → State
reducer::determine_next_effect	Yes	State → Effect
reducer::EffectHandler	No	Executes effects, produces events

Business logic lives in reducers (pure). I/O lives in handlers (impure).

Two Effect Layers

Ralph has two distinct effect types for different pipeline stages:

Layer	Module	When	Filesystem Access
AppEffect	app	Before repo root known	std::fs directly
Effect	reducer	After repo root known	Via workspace::Workspace

These layers must never mix: AppEffect cannot use Workspace, and Effect cannot use std::fs directly.

I/O Abstractions

All I/O is abstracted through traits for testability:

• workspace::Workspace - Filesystem operations
  • Production: workspace::WorkspaceFs
  • Tests: MemoryWorkspace (with test-utils feature)
• ProcessExecutor - Process spawning
  • Production: RealProcessExecutor
  • Tests: MockProcessExecutor (with test-utils feature)

Feature Flags

• monitoring (default) - Enable streaming metrics and debugging APIs
• test-utils - Enable test utilities (MockProcessExecutor, MemoryWorkspace, etc.)
• hardened-resume (default) - Enable checkpoint file state capture for recovery

Key Modules

Core Architecture:

• reducer - Core state machine with pure reducers and effect handlers
• app - CLI layer operating before repo root is known (AppEffect)
• phases - Pipeline phase implementations (planning, development, review, commit)

I/O Abstractions:

• workspace - Filesystem abstraction (WorkspaceFs production, MemoryWorkspace testing)
• executor - Process execution abstraction for agent spawning

Agent Infrastructure:

• agents - Agent configuration, registry, and CCS (Claude Code Switch) support
• json_parser - NDJSON streaming parsers for Claude, Codex, Gemini, OpenCode
• prompts - Template system for agent prompts

Supporting:

• git_helpers - Git operations using libgit2 (no CLI dependency)
• checkpoint - Pipeline state persistence for --resume support
• config - Configuration loading and verbosity levels

Error Handling

Most functions return anyhow::Result for flexible error handling with context. Use .context() to add context to errors as they propagate.

Re-exports

pub use files::llm_output_extraction::extract_development_result_xml;

pub use files::llm_output_extraction::extract_fix_result_xml;

pub use files::llm_output_extraction::extract_issues_xml;

pub use files::llm_output_extraction::validate_development_result_xml;

pub use files::llm_output_extraction::validate_fix_result_xml;

pub use files::llm_output_extraction::validate_issues_xml;

pub use executor::AgentChild;

pub use executor::AgentChildHandle;

pub use executor::AgentCommandResult;

pub use executor::AgentSpawnConfig;

pub use executor::ProcessExecutor;

pub use executor::ProcessOutput;

pub use executor::RealAgentChild;

pub use executor::RealProcessExecutor;

Modules

agents

Agent Abstraction Module

app

Application entrypoint and pipeline orchestration.

banner

Banner and UI output utilities.

checkpoint

Pipeline checkpoint system for resume functionality.

cli

CLI argument parsing and command-line interface definitions.

common

Common utility functions shared across the crate.

config

Configuration Module

diagnostics

System and agent diagnostics.

executor

Process execution abstraction for dependency injection.

files

File management utilities for Ralph’s agent files.

git_helpers

Git Helper Functions

guidelines

Language-Specific Review Guidelines Module

interrupt

Interrupt signal handling for graceful checkpoint save.

json_parser

JSON Stream Parsing Module

language_detector

Language and Stack Detection Module

logger

Logging and progress display utilities.

logging

phases

Pipeline Phase Orchestration Module

pipeline

Pipeline Execution Module

platform

Platform detection and installation guidance

prompts

Prompt Templates Module

reducer

Reducer-based pipeline architecture.

rendering

Rendering subsystem for user-facing display output.

review_metrics

Review Quality Metrics Module

templates

Prompt template management module.

workspace

Workspace filesystem abstraction for explicit path resolution.

Macros

assert_template_exists

Macro to verify a template file exists and contains expected content.

assert_template_has_variable

include_template

Macro to verify that a string comes from a template file.