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:

  • **Amp CLI** — https://ampcode.com (default)
  • **Claude Code** — https://docs.anthropic.com/en/docs/claude-code

The main runner lives at:

```bash scripts/ralph/ralph.sh ```

Usage examples:

```bash # 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