Better Ralph – One Iteration (OpenClaw)

Execute one iteration of the Better Ralph workflow: pick the next PRD story, implement it, run quality checks, commit, update the PRD, and append progress. Uses only standard tools (read_file, write_file, edit, exec, git). No external runner or Aether-Claw required.

When to Use

• User says: "run better ralph", "do one better ralph iteration", "next prd story", "ralph loop", "implement next story from prd".
• Project has a prd.json in the workspace root (see Output Format below for schema).

One-Iteration Workflow

Do these steps in order. Use only your standard file, exec, and git tools.

1. Read state

• Read prd.json (workspace root). Parse the JSON.
• Read progress.txt if it exists. If it has a section ## Codebase Patterns near the top (up to the next ## or end of file), use that as context for implementation patterns. Otherwise proceed without it.

2. Pick the next story

• From prd.json.userStories, find all with passes === false.
• Sort by priority ascending (lower number = higher priority).
• Take the first (highest priority incomplete story).
• If every story has passes === true, reply: "All PRD stories are complete. Nothing left to do." and stop.

3. Ensure git branch

• Check current git branch (e.g. run git branch --show-current or use your git tool).
• If prd.json has a branchName and it differs from the current branch, checkout or create that branch (e.g. git checkout -b <branchName> or git checkout <branchName>).

4. Implement the story

• Story = the one you picked. It has: id, title, description, acceptanceCriteria, priority, passes.
• Implement the story: write or edit code so that every item in acceptanceCriteria is satisfied.
• Work on this story only. Do not start the next story.

5. Run quality checks

• Run the project’s quality commands (e.g. npm test, npm run lint, npm run typecheck, or whatever the project uses).
• If any check fails, do not commit. Tell the user what failed and stop. Do not update prd.json or progress.txt for a failed story.

6. Commit (only if checks passed)

• Stage all changes (e.g. git add -A or your git tool’s equivalent).
• Commit with message exactly: feat: [Story ID] - [Story Title]
  Example: feat: US-002 - Display priority on task cards

7. Mark story passed in prd.json

• Read prd.json again (in case it changed).
• Find the user story with the same id you just completed. Set its passes to true.
• Write the full updated prd.json back (preserve structure and other fields; only change that story’s passes).

8. Append progress to progress.txt

• Append (do not overwrite) a new block to progress.txt with this format: