name

ralph-loop-setup

description

Use when the user wants to set up or run the Ralph autonomous agent loop in a project — bulk scaffolding, multi-task feature builds, "keep going until done" runs — WITH a mandatory L1/L2 review gate. Triggers RU "поставь ralph loop", "настрой ралф", "автономный цикл агента", "гоняй цикл до готового"; EN "set up ralph loop", "ralph autonomous loop", "run ralph until done". Produces a scripts/ralph/ scaffold in the current project and enforces review before merge.

Ralph Loop Setup (with review gate)

Goal

Stand up the Ralph autonomous agent loop inside the current project and run it under a mandatory review gate. Ralph turns a spec into atomic tasks and runs a fresh-context agent per task until every task passes. Each iteration is a new agent that reads only prd.json + progress.txt (not the whole chat), so quality does not decay on long builds. This skill scaffolds the runtime, drives the /prd → /ralph → run workflow, and refuses to call a branch "done" until L1 (agentic code-review) and L2 (independent second model) both sign off.

When NOT to invoke

Anything touching real money, secrets, credentials, or irreversible actions (payments, prod migrations, sending mail, deleting data) — run those supervised, one step at a time, NOT in an autonomous loop.
Tiny one-off edits — a single change does not need a loop; just do it.
The process/spec is not yet verified or the acceptance criteria are vague — write a real PRD first.
A scripts/ralph/ scaffold already exists with an in-flight prd.json for a different feature — archive it before starting a new one.

Requirements

Agent: Claude Code (primary) or Codex CLI.
Tools: jq, git, bash. The project must be a git repo.
Skills: prd and ralph (installed alongside this skill by install.sh).
Optional for L2 review: Codex CLI (codex review) or Gemini CLI — a different provider than the one that wrote the code.

Process

Ensure the helper skills are present. Confirm ~/.claude/skills/prd/SKILL.md and ~/.claude/skills/ralph/SKILL.md exist. If missing, run the package install.sh.
Scaffold the runtime into the current project:
```
mkdir -p scripts/ralph tasks
cp "$RALPH_PKG"/runtime/ralph.sh        scripts/ralph/ralph.sh
cp "$RALPH_PKG"/runtime/prompt-claude.md scripts/ralph/CLAUDE.md
chmod +x scripts/ralph/ralph.sh
```
($RALPH_PKG = the cloned ralph-loop-setup repo. prompt-claude.md becomes scripts/ralph/CLAUDE.md — the per-iteration agent prompt Ralph feeds each fresh instance.)
Write the PRD. Invoke /prd, describe the feature, answer the clarifying questions → tasks/prd-<feature>.md. Keep stories small enough to finish in one context window.
Convert to Ralph format. Invoke /ralph to turn the PRD into scripts/ralph/prd.json (atomic user stories, each passes:false, ordered schema → backend → UI). Review the cut by hand — split anything that cannot be described in 2-3 sentences.
Run the loop:
```
./scripts/ralph/ralph.sh --tool claude 15   # 15 = max iterations
```
Each iteration: fresh agent → picks highest-priority passes:false story → implements → runs checks → commits feat: US-xxx → sets passes:true → appends learnings to progress.txt. Stops at <promise>COMPLETE</promise> or max iterations.
ENFORCE the review gate (below). Do not report the branch as done until it is green.

Review gate (mandatory)

A Ralph branch is NOT "done" on green CI alone. Before merge:

L1 — agentic code-review. A code-reviewer sub-agent checks the branch against the PRD acceptance criteria and project standards, adversarially (no "should work" — show evidence). In Claude Code: the superpowers:code-reviewer agent or /code-review.
L2 — independent second model. A different provider reviews the diff: codex review --base main (or a Gemini review). Catches what the author model is blind to.
Gate rule: merge only when both layers are green, OR every finding is consciously closed with a written "why" in the PR/commit. The orchestrator holds the gate.
Honest metric — cost per ACCEPTED result. Track how many iterations you keep vs discard. If you throw away more than ~40% and redo by hand, the loop is costing more than it saves — tighten the PRD or shrink the stories.

Anti-patterns

❌ Running the loop on money/secret/irreversible flows — that is exactly the class the gate cannot save you from; supervise instead.
❌ Skipping L1/L2 because CI is green — green tests do not equal a correct, in-spec branch.
❌ Oversized stories — the fresh agent runs out of context mid-story and commits broken code.
❌ Not reviewing the prd.json cut before running — bad slicing wastes whole iterations.
❌ Ignoring the accept-rate metric — a loop that produces mostly-discarded output is a net loss, not automation.

Ralph Loop Setup (with review gate)

Goal

When NOT to invoke

Anything touching real money, secrets, credentials, or irreversible actions (payments, prod migrations, sending mail, deleting data) — run those supervised, one step at a time, NOT in an autonomous loop.

Tiny one-off edits — a single change does not need a loop; just do it.

The process/spec is not yet verified or the acceptance criteria are vague — write a real PRD first.

A scripts/ralph/ scaffold already exists with an in-flight prd.json for a different feature — archive it before starting a new one.

Requirements

Agent: Claude Code (primary) or Codex CLI.

Tools: jq, git, bash. The project must be a git repo.

Skills: prd and ralph (installed alongside this skill by install.sh).

Optional for L2 review: Codex CLI (codex review) or Gemini CLI — a different provider than the one that wrote the code.

Process

Ensure the helper skills are present. Confirm ~/.claude/skills/prd/SKILL.md and ~/.claude/skills/ralph/SKILL.md exist. If missing, run the package install.sh.

Scaffold the runtime into the current project:

mkdir -p scripts/ralph tasks
cp "$RALPH_PKG"/runtime/ralph.sh        scripts/ralph/ralph.sh
cp "$RALPH_PKG"/runtime/prompt-claude.md scripts/ralph/CLAUDE.md
chmod +x scripts/ralph/ralph.sh

($RALPH_PKG = the cloned ralph-loop-setup repo. prompt-claude.md becomes scripts/ralph/CLAUDE.md — the per-iteration agent prompt Ralph feeds each fresh instance.)

Write the PRD. Invoke /prd, describe the feature, answer the clarifying questions → tasks/prd-<feature>.md. Keep stories small enough to finish in one context window.

Convert to Ralph format. Invoke /ralph to turn the PRD into scripts/ralph/prd.json (atomic user stories, each passes:false, ordered schema → backend → UI). Review the cut by hand — split anything that cannot be described in 2-3 sentences.

Run the loop:

./scripts/ralph/ralph.sh --tool claude 15   # 15 = max iterations

Each iteration: fresh agent → picks highest-priority passes:false story → implements → runs checks → commits feat: US-xxx → sets passes:true → appends learnings to progress.txt. Stops at <promise>COMPLETE</promise> or max iterations.

ENFORCE the review gate (below). Do not report the branch as done until it is green.

Review gate (mandatory)

A Ralph branch is NOT "done" on green CI alone. Before merge:

L1 — agentic code-review. A code-reviewer sub-agent checks the branch against the PRD acceptance criteria and project standards, adversarially (no "should work" — show evidence). In Claude Code: the superpowers:code-reviewer agent or /code-review.

L2 — independent second model. A different provider reviews the diff: codex review --base main (or a Gemini review). Catches what the author model is blind to.

Gate rule: merge only when both layers are green, OR every finding is consciously closed with a written "why" in the PR/commit. The orchestrator holds the gate.

Honest metric — cost per ACCEPTED result. Track how many iterations you keep vs discard. If you throw away more than ~40% and redo by hand, the loop is costing more than it saves — tighten the PRD or shrink the stories.

Anti-patterns

❌ Running the loop on money/secret/irreversible flows — that is exactly the class the gate cannot save you from; supervise instead.

❌ Skipping L1/L2 because CI is green — green tests do not equal a correct, in-spec branch.

❌ Oversized stories — the fresh agent runs out of context mid-story and commits broken code.

❌ Not reviewing the prd.json cut before running — bad slicing wastes whole iterations.

❌ Ignoring the accept-rate metric — a loop that produces mostly-discarded output is a net loss, not automation.