| name | ralph |
| description | Use when the user wants to run a Ralph loop: an autonomous, self-referential delivery loop that drives a whole epic through implement, code review, fix, UX review, validate, commit, and merge request, one task per iteration, until a completion promise is emitted (ralph setup, ralph start), or to inspect or stop a running loop (ralph status, ralph cancel). Also supports simple ad-hoc loops that repeat a single prompt until done. Do NOT use to 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 | [setup <epic|--prompt "...">|start|status|cancel] [--max-iterations N] [--completion-promise TEXT] |
Ralph loop
Run an autonomous delivery 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). Implements the Ralph Wiggum technique with an epic step
machine on top.
How the loop works
ralph setup seeds .ralph/{work-id}/ (context + state) and generates
the active loop file .ralph/loop.md — it does NOT start the loop.ralph start verifies the seeded files and executes iteration 1.- The plugin hooks (
hooks/) take over: after every turn, the stop hook
re-feeds the body of .ralph/loop.md; the agent reads its own state and
runs the next step.
- The loop ends when the agent outputs
<promise>TEXT</promise> matching
the configured promise, max_iterations is reached, or the stall guard
detects no state change for 3 consecutive iterations.
The step machine is canonical in
references/loop-protocol.md:
per task implement → review → review_fix → ux_review (UI only) → validate_and_commit → task-progress, then a one-time final phase
(epic review → branch validation → /validate → /merge-request).
Every step runs this repo's skills in a fresh sub-agent.
References
Assets
Router
- Mode:
setup, start, status, or cancel. No default — if the mode
is missing, infer from context: an epic argument implies setup; a bare
/ralph with a seeded .ralph/loop.md implies start; otherwise ask.
- One prompt under prompts/.
setup — prompts/setup.prompt.md. Resolve the
epic (slug, ID, or path per delivery conventions), derive a dependency-safe
task order, resolve the environment, seed .ralph/{epic}/, and generate
.ralph/loop.md. --prompt "..." seeds an ad-hoc loop instead (no step
machine). Never starts the loop.
start — prompts/start.prompt.md. Verify the
seeded loop file (or seed an ad-hoc one from an inline prompt), confirm the
branch, execute iteration 1.
status — prompts/status.prompt.md. Report
iteration, current task and step, budgets used, completed tasks, review
files.
cancel — prompts/cancel.prompt.md. Remove
the active loop file and flags; keep 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.
- Always set
max_iterations (default 50) as a safety net.
- Exactly ONE step per iteration; state lives in files, not in memory.
- Every skill step runs in a fresh sub-agent (Cursor Task tool / Claude Code
agents) — never inline. Context isolation is what keeps iterations sharp.
- All commits target the resolved branch; verify with
git branch --show-current before committing. No Co-authored-by
trailers, no emojis in commits.
- If installed, disable the external
ralph-loop-plugin — this plugin
ships its own hooks and running both would double-fire stop hooks.
