ralph-loop-template

Input

$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.

Search for agent/project configuration files

in the following priority order:

CLAUDE.md

(Claude Code)

.cursorrules

(Cursor)

.windsurfrules

(Windsurf)

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

. 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

{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")