ralph-loop-template

# Ralph Loop Template ## Input ```text $ARGUMENTS ``` ## Instructions ### Step 1: Gather Plan **If an argument is provided**: Read the file to understand the plan content. **If no argument**: Search for a plan in the following order: 1. Search for plan files in the project root: `PLAN.md`, `plan.md`, `PLAN-*.md`, `plan-*.md`, `TODO.md`, `prd.md`, `PRD.md` - 1 found → Use it (inform the user which file was detected) - Multiple found → Present the list and ask for selection - 0 found → Proceed to next step 2. Use the plan discussed in the current conversation context. 3. If no plan exists in the conversation context, ask the user to describe the plan. ### Step 2: Identify Project Environment Collect project-specific information to embed in the PROMPT file. **Search for agent/project configuration files** in the following priority order: 1. `CLAUDE.md` (Claude Code) 2. `.cursorrules` (Cursor) 3. `.windsurfrules` (Windsurf) 4. `AGENTS.md`, `COPILOT.md`, `GEMINI.md` If a config file is found, extract: - Verification commands: Combine build, test, lint into a single chain (e.g., `npm run lint && npm run build && npm test`) - Key code style rules (items to insert into the PROMPT's absolute rules `{AGENT_RULES}`, max 3) **If no config file is found**: Infer from project structure: - `package.json` → npm/yarn commands - `Makefile` / `Justfile` → make/just commands - `Cargo.toml` → cargo commands - `pyproject.toml` / `setup.py` → python toolchain - If undetectable, ask the user for build/test commands ### Step 3: Analyze Plan Extract the following from the plan: - **Goal**: What is being built - **Non-goals**: What will NOT be done in this task (to prevent Feature Invention) - **Phase list**: Ordered implementation steps - **Key content per phase**: Files to change, implementation details - **Reference docs/files**: Pattern references, design document paths - **Completion criteria**: Criteria for determining the entire task is complete Completion criteria **must be mechanically verifiable** (e.g., command execution returns exit code 0). Do not use subjective criteria like "works well" or "looks clean". ### Step 4: Phase Splitting Split the plan into phases suitable for Ralph Loop iterations. **Splitting principles**: - **One iteration = exactly one phase.** Two phases in one iteration means a verification failure can't be traced to the phase that caused it, and the next iteration resumes from an unclear state. - When a phase is completed, immediately end the iteration. The next phase is handled in the next iteration. - Each phase must be the **minimum unit that can independently pass verification**. - Split phases that are too large, merge phases that are too small. **Size guideline** (reference, not absolute): - If description needs 3+ sentences → candidate for splitting - If it's a single-line change to one file → candidate for merging with adjacent phase - The appropriate size is one the agent can implement + verify within a single context **max-iterations calculation**: `number of phases + 2` - +1: Buffer for automatic retry on verification failure - +1: Buffer for promise output iteration after final phase completion ### Step 5: Generate PROMPT File Use `references/prompt-template.md` as the base template and `references/iteration-procedure.md` as the iteration procedure block to generate the PROMPT file. Create a `PROMPT-{kebab-case-name}.md` file in the project root. **Placeholder mapping**: | Placeholder | Source | Fallback | |-------------|--------|----------| | `{goal title}` | Step 3 | Ask user | | `{project name}` | Project directory name or CLAUDE.md | Ask user | | `{goal}` | Step 3 | Ask user | | `{AGENT_RULES}` | Step 2 (agent config rules) | Omit entire line if no config file | | `{non-goals}` | Step 3 + non-goal writing rules for inference | Min 2 items | | `{reference doc rows}` | Step 2-3 | Omit entire reference docs section if 0 docs | | `{iteration procedure}` | Entire `references/iteration-procedure.md` | — | | `{checklist}` | Step 4 phase splitting result | — | | `{verification command}` | Step 2 (project detection) | Ask user | | `{COMPLETION_PROMISE}` | COMPLETION_PROMISE generation rules | — | **Note**: Example text that uses curly braces (such as the recording format for out-of-scope findings) should be left as-is without substitution. ### Step 6: Output Result Provide the generated PROMPT file path and output the `/ralph-loop` command in the following format: ``` ### Generated File `{PROMPT file path}` > Review the generated PROMPT file before execution. Check the verification commands and phase structure in particular. ### Ralph Loop Execution Command /ralph-loop "Read {PROMPT file path} and implement the next unchecked phase. Always read the file first to find the first phase with [ ] items." --max-iterations {number of phases + 2} --completion-promise "{COMPLETION_PROMISE}" ``` Output the command block above so it can be copied and used directly. --- ## Generation Rules ### Checklist Writing Rules - **Phase = iteration unit**: A single `### Phase N` block is processed in one iteration - **Sub-items = detailed tasks within a phase**: Place 2-5 `- [ ]` sub-items under each Phase - Sub-items should specify files to change and implementation details - Verification is not a checklist item — it runs automatically in STEP 4 of the iteration procedure. Use the project's build/test commands detected in Step 2 ### Non-Goal Writing Rules In addition to items explicitly excluded by the plan, infer and add: - Refactoring outside the plan's scope - Unrequested test/documentation/configuration changes - Existing API or interface changes (if not specified in the plan) ### COMPLETION_PROMISE Generation Rules - Uppercase English, space-separated - Briefly summarize the goal (e.g., "HELP OVERLAY COMPLETE", "AUTH REFACTOR DONE")