Skip to main content
Documentation
DOCS · CLI REFERENCE

Core Concepts

Understand the key concepts behind Ralph Workflow - pipelines, phases, checkpoints, and agent orchestration.

Core Concepts

Ralph Workflow is built around a few key concepts that make AI-assisted development reliable and predictable.

The Pipeline

Every Ralph workflow runs through a structured pipeline with distinct phases:

PROMPT.md -> Planning -> Development -> Review -> Commit

This structure ensures that:

  • Work is planned before execution begins
  • Changes are reviewed before committing
  • Each phase can be checkpointed and resumed

Pipeline Phases

1. Planning Phase

Ralph analyzes your PROMPT.md and generates a structured plan in PLAN.md. This plan includes:

  • Steps to accomplish the task
  • Files that will be modified
  • Potential risks or considerations

Review the Plan

You can review PLAN.md before proceeding. If the plan looks wrong, edit your prompt and regenerate.

2. Development Phase

AI agents execute the plan iteratively. Each iteration:

  1. Analyzes the current state
  2. Makes targeted changes
  3. Verifies the changes work
  4. Decides if more iterations are needed

Ralph limits iterations to prevent runaway execution (configurable via max_dev_continuations).

3. Review Phase

An independent AI review checks the changes for:

  • Bugs or logic errors
  • Security issues
  • Code style violations
  • Missing tests or documentation

Issues are recorded in ISSUES.md. If issues are found, Ralph can attempt automatic fixes.

4. Commit Phase

Ralph generates an appropriate commit message based on the changes made. The message follows conventional commit format and summarizes what was done.

Checkpoints

Ralph saves progress at key points:

Checkpoint Saved After
planning_complete Plan generated
iteration_N Each development iteration
review_complete Review finished
commit_ready Commit message generated

Checkpoints are stored in .agent/checkpoint.json. To resume:

$ ralph --resume

Agent Orchestration

Ralph coordinates multiple AI agents with fallback logic:

[developer]
fallback_chain = ["opencode", "ccs"]

[reviewer]
fallback_chain = ["ccs", "opencode"]

If the first agent fails (rate limit, auth error, etc.), Ralph automatically tries the next agent in the chain.

Supported Agents

Agent Role Notes
opencode Developer, Reviewer General-purpose coding agent
ccs Developer, Reviewer Claude Code Selector

Artifacts

Ralph creates several artifacts during execution:

.agent/
  checkpoint.json    # Pipeline state
  tmp/
    plan.xml         # Structured plan data
    issues.xml       # Review findings
    commit_message.xml # Generated commit message
  logs/
    run-2026-02-11/  # Per-run logs

These artifacts help with debugging and auditing workflow runs.

Next Steps

Loading…