ralph-loop

name

ralph-loop

description

This skill should be used when the user wants to set up an automated Claude agent loop that works through a list of tasks iteratively. It scaffolds a ralph loop — a bash-driven harness that runs Claude repeatedly, picking up the next work item each iteration until all items are complete. Triggers on "set up a ralph loop", "create an agent loop", "ralph", "loop through tasks", "automate this work", or when the user has a list of items they want Claude to work through autonomously.

Ralph Loop

Overview

Ralph Loop is a task automation pattern: a bash script runs Claude in agent mode repeatedly, each iteration picking the next unfinished item from a source-of-truth document, doing the work, updating a progress file, and continuing until everything is done.

The pattern works for any list of discrete work items: bug fixes, PRD sections, Sentry issues, feature implementations, content generation, migrations, etc.

Setup Workflow

Follow these steps in order when setting up a new ralph loop.

Step 1: Understand the Goal

Ask the user:

1. What is the goal of this loop? (e.g., fix a list of bugs, implement features from a PRD, process Sentry issues)
2. Where should the loop files be scaffolded? (default: current working directory)

Step 2: Source of Truth

Ask the user if they already have a document listing the work items. This could be:

• A PRD broken into sections/tasks
• A list of Sentry issues (possibly generated by fetching from Sentry)
• A list of Jira tickets
• A feature spec with discrete deliverables
• Any markdown document with identifiable work items

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

Asset	Purpose
assets/ralph.sh	The loop harness script — runs Claude iteratively, checks for completion
assets/prompt-template.md	Structural reference for generating tailored prompts
assets/items-template.md	Example formats for different source-of-truth documents
assets/progress-template.md	Standardized progress tracking format