ralph-loop

Files (1)

• SKILL.md

SKILL.md (first lines)

# Ralph Loop (Training Loop)

## Quick Reference

For tasks too large for one context window: decompose into stories, generate prd.json, activate the Stop hook loop, and iterate inside the current session until all stories pass.

## When to Use

ALL of these must be true:
- Scope exceeds one context window
- Work decomposes into independent, verifiable stories
- Each story has pass/fail acceptance criteria
- Clean iteration boundaries exist (one story per iteration)

## When NOT to Use

- Task fits in one session (use `executing-plans`)
- Work can't be decomposed into independent stories
- Stories don't have objective pass/fail criteria
- User prefers manual step-by-step execution

## How It Works

The ralph loop uses Claude Code's Stop hook to keep the session alive:

1. Claude writes `.claude/ralph-loop.local.md` (state file with loop prompt)
2. Claude works on the first story in prd.json
3. When the session tries to end, the Stop hook fires
4. The hook reads prd.json — if all stories pass, it allows exit
5. Otherwise, it re-injects the prompt and Claude continues with the next story
6. No external scripts, no subprocess — the same interactive session continues

This is fully automatic. The planning chain activates it when scope demands it.

## Core Process

### Step 1: Detection

During `writing-plans`, assess whether the task triggers ralph-loop conditions:

| Signal | Threshold |
|--------|-----------|
| Estimated stories | 4+ independent stories |
| Estimated changes | 500+ lines across 10+ files |
| Context window fit | Plan + implementation won't fit in one session |
| Story independence | Each story is verifiable in isolation |

If ALL signals fire, propose the training loop to the user.

### Step 2: Prepare Artifacts

Chain to `story-decomposition` then `prd-generator`. This generates in `.claude/plugin/ralph/`:

- **`prd.json`** — stories with `passes: false` initially
- **`progress.txt`** — human-readable progress log
- **`notes/`** — per-story implementation notes (written during iterations)

### Step 3: Propose to User

Present the decomposition and ask for approval before activating:

```
This task would benefit from a ralph loop.

**Stories**: N stories, max 20 iterations
**Mechanism**: Stop hook — runs inside this session, fully interactive
**Completion**: Automatic when all prd.json stories pass

Stories:
1. [Title] — [one-line goal]
2. [Title] — [one-line goal]
...

Ready to start? I'll activate the loop now.
```

**Do not activate without user approval.**

### Step 4: Activate the Loop

After approval, write the state file `.claude/ralph-loop.local.md`:

```markdown
---
active: true
iteration: 1
session_id: <CLAUDE_CODE_SESSION_ID>
max_iterations: 20
prd_path: .claude/plugin/ralph/prd.json
started_at: "<current ISO 8601 timestamp>"
---

Read .claude/plugin/ralph/prd.json. Find the first story where passes is false.
Check its dependencies are met (all dependency story IDs must have passes: true).
Implement the story following its acceptance criteria. Run the verification
command. If it passes, update prd.json (set passes: true, increment
completedStories) and progress.txt (mark [x]). Write implementation notes to
.claude/plugin/ralph/notes/story-<id>.md. One story per iteration.

If you are stuck on a story after 3 attempts, or blocked on something requiring
human input, delete .claude/ralph-loop.local.md and explain what happened.
```

Write this file using the Write tool. The `session_id` should be read from the `CLAUDE_CODE_SESSION_ID` environment variable via Bash. The `max_iterations` defaults to 20 but can be adjusted based on story count or user preference.

Then immediately begin working on the first story.

### Step 5: Per-Iteration Behavior

Each iteration (after the Stop hook re-injects the prompt):

1. **Read prd.json** — find the first story where `passes` is `false`
2. **Check dependencies** — if a dependency story has `passes: false`, skip to the next eligible story
3. **Implement** — follow the story's acceptance criteria
4. **Verify** — run the story's verification command
5. **Update on success**:
   - Set `passes: true` in prd.json for this story
   - Increment `completedStories` in prd.json
   - Mark `[x]` in progress.txt

From thesyntaxninja/syntaxninja-dojo, MIT.

More from thesyntaxninja/syntaxninja-dojo