home / skills / richtabor / agent-skills / ralph-json-start-loop

ralph-json-start-loop skill

This skill runs the Ralph autonomous loop to execute prds using git worktrees, coordinating progress and dependencies.

npx playbooks add skill richtabor/agent-skills --skill ralph-json-start-loop

Review the files below or copy the command above to add this skill to your agents.

Files (3)

SKILL.md

1.7 KB

---
name: ralph-json-start-loop
description: Runs the Ralph autonomous loop. Executes stories from prds/*.json using git worktrees.
disable-model-invocation: true
argument-hint: "[iterations] [project-name]"
---

# Ralph

Run the autonomous loop to execute features from `prds/` directory.

## Usage

```
/ralph              # Run next available project (respects dependencies)
/ralph 25           # Run with 25 iterations
/ralph auth-flow    # Run specific project
```

## Process

Run the loop script in background mode:

```bash
~/.claude/skills/ralph/ralph.sh [iterations] [project-name]
```

Use `run_in_background: true` to prevent timeout. After starting, tell the user to check progress with `tail -f <worktree>/.ralph-progress.txt`.

### What It Does

1. Shows dependency graph, finds next available project
2. Creates git worktree at `../{repo}-{feature}/`
3. For each iteration:
   - Picks first story where `passes: false`
   - Implements it, runs quality checks
   - Commits: `feat: [id] - [title]`
   - Updates JSON, syncs back to main repo
4. When all stories pass, outputs `<promise>COMPLETE</promise>`

### Dependencies

Ralph reads `dependsOn` from each PRD and enforces ordering:

```json
{
  "projectName": "Dashboard",
  "dependsOn": ["auth-flow", "user-profile"]
}
```

Projects with incomplete dependencies are blocked. Ralph picks the first ready project alphabetically.

## Prerequisites

1. At least one `.json` PRD file in `.claude/plans/`, `plans/`, or `prds/`
2. Use plan mode to create a plan, then run `/ralph-json-create-issues` to convert it

## Notes

- Run multiple Ralphs in parallel on independent projects (separate terminals)
- Each works in its own worktree, no conflicts

Overview

This skill runs the Ralph autonomous loop to execute feature stories defined in prds/*.json and manage feature work using git worktrees. It automates selecting ready projects, implementing stories, running checks, committing changes, and syncing updates back to the main repo. It is designed for repeated, unattended iterations and can run in background mode.

How this skill works

The script inspects PRD JSON files for story status and dependency metadata, builds a dependency graph, and selects the next available project alphabetically when ready. For each iteration it creates a git worktree, picks the first story with passes: false, implements changes, runs quality checks, commits with a standardized message, updates the JSON, and syncs results back to the main repository. Run it in background mode and monitor progress via the worktree .ralph-progress.txt file.

When to use it

Automating incremental development of feature stories defined in prds/*.json
Running long or repeated implementation iterations without manual supervision
Enforcing project ordering through declared dependsOn relationships
Working on multiple independent projects in parallel using separate terminals
Converting planned stories into commits and synced PRDs after plan creation

Best practices

Keep PRD JSON files in .claude/plans/, plans/, or prds/ with proper dependsOn fields
Start the script with run_in_background: true to avoid timeouts
Run one Ralph per independent project in its own terminal to avoid worktree overlap
Name projects and dependencies clearly; Ralph picks the first ready project alphabetically
Use plan mode first and run /ralph-json-create-issues to convert plans before execution

Example use cases

Run /ralph to automatically pick the next ready project and execute until completion
Run /ralph 25 to run 25 iterations on the selected project
Run /ralph auth-flow to target a specific project by name
Monitor progress with tail -f <worktree>/.ralph-progress.txt while Ralph runs in background
Run multiple terminals for parallel work on independent projects, each using its own worktree

FAQ

How does Ralph enforce project order?

Ralph reads dependsOn arrays in each PRD and blocks projects with incomplete dependencies. It will only pick projects whose dependencies are complete.

Where should PRD files live?

Place at least one .json PRD in .claude/plans/, plans/, or prds/ so Ralph can discover and run them.

How do I monitor progress after starting Ralph?

Start the script with run_in_background: true and check progress by tailing <worktree>/.ralph-progress.txt.