ralph-autonomous-agent-loop

What this skill does

```markdown
---
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

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

### Option 3: Claude Code Marketplace

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

```
Load the ralph skill and convert tasks/prd-my-feature.md to prd.json
```

This creates `prd.json` structured for autonomous execution.

### Step 3 — Run Ralph

```bash
# Default: Amp, 10 iterations
./scripts/ralph/ralph.sh

# With explicit iteration count
./scripts/ralph/ralph.sh 20

# Using Claude Code
./scripts/ralph/ralph.sh --tool claude

# Using Claude Code with custom iteration count
./scripts/ralph/ralph.sh --tool claude 15

# Using Amp explicitly
./scripts/ralph/ralph.sh --tool amp 10
```

---

## `prd.json` Format

This is the core task list Ralph reads and updates.

```json
{
  "branchName": "feature/user-dashboard",
  "projectContext": "A Next.js SaaS app using Prisma, tRPC, and Tailwind.",
  "userStories": [
    {
      "id": "story-1",
      "title": "Add avatar column to users table",
      "priority": 1,
      "passes": false,
      "description": "Add an optional avatarUrl string column to the User model via Prisma migration.",
      "acceptanceCriteria": [
        "Migration file created and applied",
        "User model updated in schema.prisma",
        "TypeScript types regenerated",
        "Existing tests still pass"
      ]
    },
    {
      "id": "story-2",
      "title": "Display avatar in profile header",
      "priority": 2,
      "passes": false,
      "description": "Show the user's avatar image in the top-right profile header component.",
      "acceptanceCriteria": [
        "Avatar renders when avatarUrl is set",
        "Fallback initials shown when avatarUrl is null",
        "Verify in browser using dev-browser skill"
      ]
    }
  ]
}
```

**Key fields:**
| Field | Type | Purpose |
|---|---|---|
| `branchName` | string | Git branch Ralph creates/works on |
| `projectContext` | string | Shared context injected into every iteration prompt |
| `userStories[].id` | string | Unique identifier |
| `userStories[].priority` | number | Lower = higher priority (1 is first) |
| `userStories[].passes` | boolean | `false` = not done, `true` = complete |
| `userStories[].acceptanceCriteria` | string[] | What the AI must verify before marking done |

---

## Key Files Reference

| File | Purpose |
|---|---|
| `ralph.sh` | Bash loop spawning fresh AI instances |
| `prompt.md` | Prompt template injected into each Amp iteration |
| `CLAUDE.md` | Prompt template for Claude Code iterations |
| `prd.json` | Live task list with `passes` status |
| `prd.json.example` | Reference example of the PRD format |
| `progress.txt` | Append-only learnings across iterations |
| `skills/prd/` | Skill: generate PRD markdown |
| `skills/ralph/` | Skill: convert PRD to `prd.json` |
| `.claude-plugin/` | Plugin manifest for Claude Code marketplace |

---

## Inspecting State

```bash
# Which stories are done vs pending?
cat prd.json | jq '.userStories[] | {id, title, passes}'

# What has Ralph learned so far?
cat progress.txt

# Recent commits from Ralph iterations
git log --oneline -10

# Count remaining stories
cat prd.json | jq '[.userStories[] | select(.passes == false)] | length'
```

---

## Customizing the Prompt Templates

After copying `prompt.md` or `CLAUDE.md` to your project, edit it to add:

```markdown
## Project-Specific Quality Checks
- Run `npm run typecheck` — must pass with 0 errors
- Run `npm test -- --passWithNoTests` — must not regress
- Run `npm run lint` — must pass

## Stack Conventions
- This project uses tRPC for API routes — do not create REST endpoints
- Database access only through Prisma — do not use raw SQL
- All new components go in `src/components/` and must be typed

## Common Gotchas
- Always run `npx prisma generate` after schema changes
- Environment variables must be added to both `.env.example` and Zod schema in `src/env.js`
```

---

## Configuring Amp Auto-Handoff (Recommended)

Add to `~/.config/amp/settings.json` to handle stories that exceed one context window:

```json
{
  "amp.experimental.autoHandoff": { "context": 90 }
}
```

When context reaches 90%, Amp automatically hands off to a fresh instance, which Ralph's loop structure handles gracefully.

---

## Writing Good User Stories for Ralph

### ✅ Right-sized stories (one context window)

```json
{ "title": "Add `stripeCustomerId` column to users table via Prisma migration" }
{ "title": "Add a loading skeleton to the /dashboard page" }
{ "title": "Filter the orders list by `status` query param" }
{ "title": "Send welcome email via Resend when user signs up" }
```

### ❌ Too large (split these up)

```json
{ "title": "Build the entire authentication system" }
{ "title": "Refactor the API layer" }
{ "title": "Add the full onboarding flow" }
```

**Rule of thumb:** If a human developer couldn't comfortably implement it in 1–2 hours with full context, split it.

---

## `progress.txt` Pattern

Ralph appends learnings after each iteration. Future iterations read this file for context. Example content:

```
[2026-01-15 story-1] Prisma migration applied successfully. Note: must run
`npx prisma generate` AND restart the dev serve