Ralph Loop

If they have a document: Read it, understand the structure, and use it as items.md.

If they don't have a document: Help them create one. Interview them about the work items and generate items.md following the format in assets/items-template.md. Each item needs at minimum: an identifier, a title/description, and enough context for Claude to act on it.

Step 3: Determine Workflow Options

Ask the user about their specific workflow needs:

1. Validation commands — What commands must pass after each work item? (e.g., pnpm build, pytest, cargo test). If none, skip validation.
2. PR creation — Should each work item (or group of related items) produce a draft PR? If yes, what branch naming convention? (e.g., fix/ISSUE-ID-description, feat/prd-section-name)
3. Grouping — Can related items be bundled into a single iteration? (e.g., bugs with the same root cause → one PR)
4. Agent strategy — Should the agent use sub-agents (opus) to study the codebase before acting? (recommended for code changes, not needed for content generation)
5. TDD — Should the agent write a failing test before implementing? (recommended for bug fixes, optional otherwise)

Step 4: Scaffold the Loop

Copy the following assets into the target directory and customize them based on the answers from Steps 1-3:

1. Copy assets/ralph.sh to the target directory. Make it executable. The script is ready to use as-is — it points to prompt.md in the same directory.

2. Generate prompt.md — Do NOT copy the template verbatim. Generate a tailored prompt based on the user's goal and workflow options. Use assets/prompt-template.md as structural inspiration but write instructions specific to their use case. The prompt must include:

   • One item per iteration — The prompt MUST instruct the agent to handle exactly one work item per iteration, then stop. The loop harness manages iteration — the agent must not continue to the next item. Reinforce this at the top of the prompt and in the stop/completion section.
   • Reference to items.md as the source of truth
   • Reference to progress.md for tracking
   • The completion signal: <promise>COMPLETE</promise>
   • Validation commands (if any)
   • PR workflow (if applicable)
   • Grouping rules (if applicable)
   • Any domain-specific instructions

3. Place items.md — either the user's existing document or the one generated in Step 2.

4. Create progress.md — initialize an empty progress file using the standardized format from assets/progress-template.md. Adapt the column headers to match the use case.

Step 5: Review and Run

Present the user with a summary of what was scaffolded:

ralph-loop/
  ralph.sh      — loop harness (run with: ./ralph.sh <iterations>)
  prompt.md     — agent instructions (tailored to your use case)
  items.md      — source of truth (N items)
  progress.md   — progress tracker (empty, ready to go)

Remind the user:

• Run with ./ralph.sh 10 (or however many iterations they want)
• The loop stops early if all items are complete
• Progress is saved between iterations — safe to stop and resume
• Review progress.md to see what was done

File Reference