Ralph: Autonomous AI Loop to Implement PRD Stories via Git

Ralph is an autonomous loop that spawns fresh AI instances to implement PRD user stories until tests and typechecks pass. State is preserved through git history, prd.json, and progress.txt, and it supports Amp CLI or Claude Code.

Ralph: Autonomous AI Loop to Implement PRD Stories via Git

TL;DR

  • Each iteration is a fresh AI instance; persistent state stored in git history, progress.txt, and prd.json.
  • Supported tools: Amp CLI (default) — https://ampcode.com, Claude Code — https://docs.anthropic.com/en/docs/claude-code; requires jq and a git repo; skills can be installed into Amp/Claude skill dirs; main runner scripts/ralph/ralph.sh.
  • PRD -> workflow: generate PRD (skills/prd to tasks/prd-[feature].md), convert to prd.json via ralph skill, run loop ./scripts/ralph/ralph.sh [max_iterations] or --tool claude [max_iterations].
  • Single-story iteration: create feature branch, pick highest-priority story with passes: false, implement, run typechecks and tests, commit if checks pass, mark passes: true, append learnings to progress.txt.
  • Reliability rules: right-sized stories to fit one context window, robust typechecks/tests/CI to prevent compounding failures, AGENTS.md updated each iteration, frontend acceptance should include browser verification via dev-browser skill.
  • Visualization & debugging: interactive flowchart — https://snarktank.github.io/ralph/, inspect prd.json with jq, view progress.txt and recent commits, runs archived under archive/YYYY-MM-DD-feature-name/.

The open-source project Ralph takes a pragmatic approach to autonomous AI coding: treat AI agents as disposable and use git as the system of record.

Ralph repeatedly drives AI coding tools to implement user stories from a PRD until all quality checks pass. Each iteration runs in a fresh AI instance, with progress preserved only through git commits, a structured prd.json, and an append-only progress.txt. The result is an incremental, auditable workflow that feels closer to traditional software development—just automated.

How the loop works

Ralph is orchestrated by a shell script that resumes purely from repository state:

  1. Create a feature branch defined in the PRD
  2. Select the highest-priority story with passes: false
  3. Implement the story using an AI coding tool
  4. Run type checks and tests
  5. Commit on success
  6. Mark the story as passing in prd.json
  7. Append learnings to progress.txt

The loop continues until all stories pass or a maximum iteration count is reached.

Because no AI context is reused, failures are visible and debuggable—nothing is hidden in agent memory.

Tooling and setup

Ralph currently supports two AI coding backends:

The main runner lives at:

scripts/ralph/ralph.sh

Usage examples:

# Amp (default)
./scripts/ralph/ralph.sh [max_iterations]

# Claude Code
./scripts/ralph/ralph.sh --tool claude [max_iterations]

From PRD to executable plan

The workflow starts with planning:

  1. Generate a markdown PRD using the prd skill
  2. Convert it into a machine-readable prd.json
  3. Let Ralph execute each story, one at a time

Stories are intentionally small and right-sized, ensuring each fits within a single AI context window.

Why stateless agents matter

A core design choice is that every iteration starts with a brand-new AI instance. Anything worth remembering must be written down—in code, tests, progress.txt, or the auto-updated AGENTS.md.

That constraint makes runs predictable, debuggable, and easy to audit, while preventing subtle failures from compounding across iterations.

Continue the conversation on Slack

Did this article spark your interest? Join our community of experts and enthusiasts to dive deeper, ask questions, and share your ideas.

Join our community