Stats
Actions
Tags
How this command is triggered — by the user, by Claude, or both
Slash command
/ralph-plugin:runThe summary Claude sees in its command listing — used to decide when to auto-load this command
# Ralph Run — Single Iteration Execute one iteration of the Ralph Loop. Pick one spec, do the work, verify it passes, and update `progress.txt`. Then stop — the loop runner will restart for the next iteration. ## Narration As you work, write brief progress lines so the human can follow along in the log. Output one line at each major step — do not wait until the end. Use this format: Keep each line short. One line per step. If tests fail and you're iterating, say so: ## Before starting Run these commands to orient yourself: ## Picking a spec Work through `specs/` in filename ord...
Execute one iteration of the Ralph Loop. Pick one spec, do the work, verify it passes, and update progress.txt. Then stop — the loop runner will restart for the next iteration.
As you work, write brief progress lines so the human can follow along in the log. Output one line at each major step — do not wait until the end. Use this format:
▸ Reading spec: 003-add-search.md
▸ Reading PRD.md
▸ Exploring codebase
▸ Planning approach
▸ Implementing
▸ Running tests
▸ Tests passed — moving spec to done/
▸ Done. Next: 004-pagination.md
Keep each line short. One line per step. If tests fail and you're iterating, say so:
▸ Tests failed — fixing
▸ Running tests again
Run these commands to orient yourself:
cat progress.txt
ls specs/
Work through specs/ in filename order (numerically prefixed). Pick the lowest-numbered spec that exists. Do not skip specs. Do not work on more than one spec per iteration.
PRD.md for project context, tech stack, test commands, and conventionsPRD.mdspecs/done/progress.txtDo not mark a spec done until its acceptance criteria are machine-verified passing. "It looks right" is not verification. Run the commands.
If the superpowers skills are installed, invoke them at the appropriate steps to reinforce discipline. If they are not installed, the built-in steps above provide equivalent guidance.
| Step | Skill to invoke |
|---|---|
| Before step 4 (Plan) | superpowers:brainstorming |
| Before step 5 (Implement) | superpowers:test-driven-development |
| When step 7 reveals persistent failures | superpowers:systematic-debugging |
| Before step 9 (moving spec to done/) | superpowers:verification-before-completion |
The test/build output is your source of truth. Not your judgment about whether the code looks correct. Run the commands, read every line of output, fix what fails.
If the same test keeps failing after 5 genuine attempts with different approaches, write STATUS: NEEDS_HUMAN to progress.txt with a full explanation. Do not loop indefinitely on the same failure.
Overwrite the entire file at the end of every iteration:
LAST_RUN: [ISO timestamp]
ITERATION: [number]
SPEC_COMPLETED: [filename or "none"]
WHAT_WAS_DONE: [one clear sentence]
VERIFICATION: [what commands ran and what they returned — pass/fail]
STATUS: [MORE_WORK | DONE | NEEDS_HUMAN]
NEXT_SPEC: [filename of next spec to work on, or "none"]
NOTES: [anything the next iteration needs to know — assumptions made, gotchas found]
If STATUS: NEEDS_HUMAN, also include:
REASON: [exactly what you need and why you can't proceed without it]
ATTEMPTS: [what you already tried]
progress.txtspecs/done/ralph-loop.sh or PRD.mdspecs/ — the human does that (backlog items go in specs/backlog/)PRD.md provides credentials/configprogress.txt and let the human decidenpx claudepluginhub jwcarman/jwcarman-marketplace --plugin ralph-plugin/runAuto-completes all pending agent-foreman tasks in priority order unattended or a specific task by ID. Loops through fetch, implement, verify, done/fail until complete, with summary.
/runParses and executes legacy inline orchestration workflow syntax supporting raw operators, YAML frontmatter templates, and temporary AI agents with model overrides.