ralph-loop

## Arguments [task description or PRD path] [--completion-promise KEYWORD] # Ralph Wiggum Loop An autonomous coding loop that executes tasks iteratively with **fresh context per iteration**, using the filesystem as memory and `git` for version control. Inspired by the [Ralph Wiggum pattern](https://ghuntley.com/ralph/) — persistent trial-and-error with external state tracking. ## Core Principle **Ralph loop = Fresh context + Filesystem memory + Git versioning** Each iteration starts with a clean context window. Progress is tracked in `PROGRESS.md`, requirements live in `PRD.md`, and every completed task is committed to git. This avoids context pollution and produces reliable results for multi-step work. ## Usage ```bash /ralph-loop "Build the authentication module" /ralph-loop docs/plans/my-plan.md /ralph-loop "finish all slash commands" --completion-promise "DONE" ``` ## Execution Flow ### Phase 0: Planning (if no PRD exists) If the argument is a task description (not a path to an existing PRD or plan file): 1. **Read existing plan files** — Check `docs/plans/` for a relevant plan. If one exists and matches the task, use it as the PRD. 2. **Generate PRD** — If no plan exists, create `PRD.md` in the project root with: - **Goal**: One-sentence summary of what success looks like - **Tasks**: Numbered list of atomic, independently-executable tasks - **Acceptance Criteria**: Testable criteria for each task - **Completion Promise**: The keyword to output when all tasks are done (default: `DONE`) 3. **Generate PROGRESS.md** — Create `PROGRESS.md` in the project root with: ```markdown # Progress ## Status: IN_PROGRESS | # | Task | Status | Notes | |---|------|--------|-------| | 1 | [task name] | PENDING | | | 2 | [task name] | PENDING | | ``` 4. **Commit initial state**: ```bash git add PRD.md PROGRESS.md git commit -m "ralph-loop: initialize PRD and progress tracking" ``` If the argument is a path to a plan file (e.g., `docs/plans/feature.md`), use that as the PRD and generate only `PROGRESS.md` from its tasks. ### Phase 1: Coordination Loop Read `PRD.md` and `PROGRESS.md` to determine the next PENDING task, then execute iterations until all tasks are complete. For **each iteration**: #### Step 1 — Pick Next Task Read `PROGRESS.md` and select the first task with status `PENDING`. If no PENDING tasks remain, go to Phase 2 (Completion). #### Step 2 — Execute Task Spawn a **fresh sub-agent** (via the Task tool) for the selected task. The sub-agent prompt MUST include: ``` You are a Ralph Executor. Complete this single task with fresh context. **Task:** [task description from PRD] **Acceptance Criteria:** [criteria from PRD] Instructions: 1. Read PRD.md and PROGRESS.md for full context 2. Implement the task — write code, create files, run tests 3. Verify your work meets the acceptance criteria 4. Update PROGRESS.md: set this task's status to DONE with brief notes 5. Stage and commit your changes: git add -A git commit -m "ralph-loop: complete task [N] — [brief description]" Do NOT modify other tasks. Do NOT skip testing. One task only. ``` <critical_requirement> Each executor sub-agent runs with **fresh context** — it has no memory of previous iterations. All state comes from the filesystem (PRD.md, PROGRESS.md, existing code, git history). </critical_requirement> #### Step 3 — Verify Completion After the executor sub-agent completes: 1. **Read PROGRESS.md** — Confirm the task status was updated to `DONE` 2. **Quick review** — Spawn a brief reviewer sub-agent to check: - Does the code compile/pass linting? - Were tests added or do existing tests still pass? - Does the change match the acceptance criteria? 3. **If review fails** — Update task status to `FAILED` with notes, then re-attempt. Each task gets up to 3 total attempts (1 initial + 2 retries). After the third failed attempt, mark the task as `BLOCKED` and continue to the next task. 4. **If review passes** — Continue to next iteration (back to Step 1) ### Phase 2: Completion When all tasks in `PROGRESS.md` are `DONE` (or `BLOCKED`): 1. **Update PROGRESS.md** — Set top-level status: - `COMPLETE` if all tasks are DONE - `PARTIAL` if any tasks are BLOCKED 2. **Final commit**: ```bash git add PROGRESS.md git commit -m "ralph-loop: all tasks complete" ``` 3. **Output completion promise** — If `--completion-promise` was provided: ``` <promise>[KEYWORD]</promise> ``` Default keyword is `DONE`. 4. **Summary**: ``` ✓ Ralph Loop Complete Tasks: [N] total, [X] done, [Y] blocked Commits: [Z] commits made PRD: PRD.md Progress: PROGRESS.md Blocked tasks (if any): - Task [N]: [reason] ``` ## Integration with Compound Engineering The ralph-loop skill works with existing CE skills: - **As orchestrator**: Called by `/lfg` and `/slfg` as an optional first step to autonomously execute all workflow commands - **With `/ce-plan`**: Can use plan files from `docs/plans/` as the PRD input - **With `/ce-work`**: Each executor iteration is similar to a focused `/ce-work` session - **With `/ce-review`**: The verification step performs lightweight review; for thorough review use `/ce-review` after the loop completes - **With `/ce-compound`**: After loop completion, run `/ce-compound` to document learnings ## State Files | File | Purpose | Created By | |------|---------|------------| | `PRD.md` | Requirements and task list | Phase 0 (Planning) | | `PROGRESS.md` | Task status tracking | Phase 0, updated each iteration | These files are committed to git and serve as the **filesystem memory** that enables fresh-context execution. ## Design Decisions - **One task per iteration**: Keeps each sub-agent focused and prevents context pollution - **Git commits per task**: Enables rollback of individual tasks and provides audit trail - **3 total attempts per task**: 1 initial attempt + up to 2 retries prevents infinite loops on genuinely broken tasks - **Reviewer sub-agent**: Catches issues before they compound across iterations - **BLOCKED status**: Allows the loop to continue past stuck tasks rather than halting entirely ## Common Mistakes to Avoid | ❌ Wrong | ✅ Correct | |----------|-----------| | Execute multiple tasks in one sub-agent | One task per sub-agent with fresh context | | Skip git commits between tasks | Commit after every completed task | | Carry conversation context across iterations | Each iteration reads state from filesystem | | Retry failed tasks indefinitely | 3 total attempts (1 initial + 2 retries), then mark BLOCKED and continue | | Modify PRD.md during execution | PRD.md is read-only after planning phase |