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:

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
Use the plan discussed in the current conversation context.
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.

If
CLAUDE.md
exists: Read it and 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
```
{CLAUDE_MD_RULES}
```
, max 3)

If
CLAUDE.md
does not exist: 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. Processing 2+ phases is strictly forbidden.
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
`{CLAUDE_MD_RULES}`	Step 2 (CLAUDE.md rules)	Omit entire line if no CLAUDE.md
`{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")