Ralph Autonomous Agent Loop

---
name: ralph-autonomous-agent-loop
description: Ralph is an autonomous AI agent loop that runs AI coding tools (Amp or Claude Code) repeatedly until all PRD items are complete, with memory persisting via git history, progress.txt, and prd.json.
triggers:
  - "set up ralph for my project"
  - "run ralph agent loop"
  - "automate my PRD with ralph"
  - "create a prd.json for ralph"
  - "use ralph to implement features autonomously"
  - "configure ralph with claude code"
  - "convert my PRD to ralph format"
  - "run autonomous coding agent on my tasks"
---

# Ralph Autonomous Agent Loop

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

Ralph is an autonomous AI agent loop that spawns fresh instances of AI coding tools (Amp or Claude Code) repeatedly until all items in a `prd.json` task list are marked complete. Memory between iterations persists via git history, `progress.txt`, and `prd.json`. Based on [Geoffrey Huntley's Ralph pattern](https://ghuntley.com/ralph/).

---

## How Ralph Works

Each iteration of the loop:
1. Reads `prd.json` and picks the highest-priority story where `passes: false`
2. Spawns a **fresh AI instance** (Amp or Claude Code) with a prompt describing that story
3. The AI implements the story, runs quality checks (typecheck, tests), and commits
4. Updates `prd.json` to mark the story `passes: true`
5. Appends learnings to `progress.txt`
6. Repeats until all stories pass or max iterations are reached

When all stories are complete, the AI outputs `<promise>COMPLETE</promise>` and the loop exits.

---

## Prerequisites

- **Amp CLI** (default): Install from [ampcode.com](https://ampcode.com)
- **OR Claude Code**: `npm install -g @anthropic-ai/claude-code`
- `jq` installed: `brew install jq` (macOS) or `apt install jq`
- A git repository for your project

---

## Installation

### Option 1: Copy scripts into your project

```bash
# From your project root
mkdir -p scripts/ralph

# Copy the shell loop
cp /path/to/ralph/ralph.sh scripts/ralph/

# Copy prompt template for your tool:
cp /path/to/ralph/prompt.md scripts/ralph/prompt.md     # For Amp
# OR
cp /path/to/ralph/CLAUDE.md scripts/ralph/CLAUDE.md     # For Claude Code

chmod +x scripts/ralph/ralph.sh

Option 2: Install Amp skills globally

cp -r skills/prd ~/.config/amp/skills/
cp -r skills/ralph ~/.config/amp/skills/

Option 3: Claude Code Marketplace

/plugin marketplace add snarktank/ralph
/plugin install ralph-skills@ralph-marketplace

Available skills after install:

• /prd — Generate a Product Requirements Document
• /ralph — Convert a PRD markdown file to prd.json

Workflow: Step by Step

Step 1 — Generate a PRD

Using the installed skill in your AI coding tool:

Load the prd skill and create a PRD for [your feature description]

The skill asks clarifying questions and saves output to tasks/prd-[feature-name].md.

Step 2 — Convert PRD to prd.json