| name | ralph-loop |
| description | Use to start, inspect, or stop a Ralph loop: an autonomous self-referential loop where a stop hook re-feeds the same prompt every turn until a completion promise is emitted or a safety rail fires (ralph-loop start, ralph-loop status, ralph-loop cancel). Works for any repeating multi-step job via presets, including full epic delivery through implement, review, validate, and merge request. Do NOT use to seed or configure a loop (ralph-loop-setup), implement a single task once (implement), review a diff (code-review), or sign off an epic (validate) — the loop orchestrates those skills.
|
| license | MIT |
| allowed-tools | ["Read","Write","Glob","Grep","Shell"] |
| argument-hint | [start|status|cancel] [--prompt "..."] [--max-iterations N] [--completion-promise TEXT] |
| metadata | {"author":"Carinya Parc","version":"1.0","review_cadence":"as-needed","owner":"web-development","work_shape":"orchestrate-delivery","output_class":"applied-change"} |
Ralph loop
Run an autonomous loop. The plugin's stop hook re-feeds the loop prompt after
every turn, the agent executes exactly one step per iteration, and the loop
ends only when the completion promise is genuinely true or a safety rail
fires.
Seeding is a separate skill: ralph-loop-setup.
This skill assumes a seeded loop, except for a quick inline ad-hoc start.
How the loop works
/web-development:ralph-loop-setup resolves configuration and runs
scripts/seed-ralph-loop.sh, which writes {base}/active.md plus a run
directory. {base} is .claude/loop or .cursor/loop, resolved from the
agent, with no pointer file./web-development:ralph-loop start verifies the seeded files and executes iteration 1.- The plugin hooks take over. After every turn the stop hook re-feeds the body
of
active.md; the agent reads its own state and runs the next step.
- The loop ends when the agent emits
<promise>TEXT</promise> matching the
configured promise, max_iterations is reached, the 200-iteration hard
ceiling is hit, or the stall guard sees no state change for 3 consecutive
iterations.
Safety rails
| Rail | Default | Enforced by |
|---|
| max_iterations | 50 | stop hook, from frontmatter |
| hard ceiling | 200 | stop hook, applies even when unlimited |
| stall guard | 3 unchanged iterations | stop hook, watches the state file |
| session isolation | owning session only | stop hook, from session_id |
| fix budgets | per preset | loop state counters |
Exhausting a budget never fails the loop: the step advances and the unresolved
findings are recorded under ## Notes so a human sees them.
References
Assets
Router
Mode is start, status, or cancel. If no mode is given: a seeded
{base}/active.md implies start; otherwise say the loop needs seeding and
point at /web-development:ralph-loop-setup.
start — prompts/start.prompt.md. Verify the
seeded loop, confirm the branch where the preset needs one, execute iteration
- With
--prompt "..." and no seeded loop, seed an ad-hoc loop first.
status — prompts/status.prompt.md. Report
iteration, current step, budgets used, completed items, and artefacts.
Read-only.
cancel — prompts/cancel.prompt.md. Stop the
loop and archive the run directory as a record.
Ground rules
- Only output
<promise>TEXT</promise> when the statement is completely and
genuinely true. Never to escape the loop, never because progress is slow.
- Exactly ONE step per iteration. State lives in files, not in memory.
- Every skill step runs in a fresh sub-agent. Context isolation per step is
what keeps a long run sharp.
- Where a preset commits, verify the branch with
git branch --show-current
first. No Co-authored-by trailers, no emojis in commits.
- If the external
ralph-loop-plugin is installed, disable it. This plugin
ships its own hooks and running both double-fires the stop hook.
