AAWEA.ORG

Manual start

↓

1

Read state

Read .ralph/prd.json and .ralph/progress.md. Resume any story marked inProgress, else pick the lowest-priority story with passes: false.
2

Implement one story

Implement exactly one user story with minimal scope. Mark it inProgress in prd.json before coding.
3

Run backpressure

Run the project's test, lint, and build commands from AGENTS.md. Fix failures before committing.

> npm test && npm run lint && npm run build
4

Commit and record

Commit with a story-scoped message. Set passes: true in prd.json and append learnings to progress.md.

↓

✓

Exit condition: manual

All stories in prd.json have passes: true

> cat .ralph/prd.json | grep -c '"passes": false' || true

📦 Install Files

These files are included when you download the loop.

📄 .ralph/prd.json

{
  "stories": [
    {
      "id": "story-1",
      "title": "Example user story",
      "description": "Replace with your first atomic task",
      "priority": 1,
      "passes": false,
      "inProgress": false
    }
  ]
}

📄 .ralph/progress.md

# Ralph progress

Append one short learning per iteration. The next fresh context reads this file first.

## Iteration log

📄 .ralph/guardrails.md

# Guardrails

Signs learned from failures. The agent must read this before each story.

- Run tests before every commit.
- One story per iteration — no scope creep.

📄 .cursor/loops/ralph-story-executor/README.md

# Ralph Story Executor

Filesystem-backed Ralph loop. Each /ralph-loop or kickoff iteration implements one story.

## Files
- `.ralph/prd.json` — task list with passes/inProgress flags
- `.ralph/progress.md` — iteration learnings
- `.ralph/guardrails.md` — failure signs

Inspired by Geoffrey Huntley's Ralph pattern and fresh-context agent loops.

📊 Flow Diagram

flowchart TD Start(["Manual start"]) Start --> S0 S0("Read state") S1("Implement one story") S0 --> S1 S2("Run backpressure") S1 --> S2 S3("Commit and record") S2 --> S3 Exit{"All stories in prd.json have passes: true"} S3 --> Exit Exit -- "No" --> S0 Exit -- "Yes" --> Done(["Success"]) style Exit fill:#fffbeb,stroke:#f59e0b,stroke-width:2px,color:#92400e style Done fill:#ecfdf5,stroke:#10b981,stroke-width:2px,color:#065f46

Kickoff prompt

Start the "Ralph Story Executor" loop.

Goal: every story in .ralph/prd.json has passes: true
Max iterations: 20
Between iterations run: npm test && npm run lint && npm run build
Exit when: no stories remain with passes: false (respond "ALL STORIES ARE COMPLETE")

Step 1: Read .ralph/prd.json and .ralph/progress.md. Pick one incomplete story, implement it, run backpressure checks, commit, update prd.json and progress.md, then stop this iteration.

Self-pace this loop. Each iteration does exactly one story. State lives on disk, not in chat history.

Anti-gaming rules

Rules the agent must follow so it cannot cheat the exit condition.

Do not modify the check command or exit criteria to force success
Do not skip, disable, or bypass checks to pass the exit condition
If stuck after several iterations, stop and report blockers instead of gaming metrics