Better Ralph

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:
• ## [Current date/time] - [Story ID]
• What was implemented (1–2 sentences)
• Files changed (list paths)
• **Learnings for future iterations:**
• - Patterns or gotchas (e.g. "this codebase uses X for Y", "remember to update Z when changing W")
• ---
• If progress.txt does not exist, create it with a first line like # Better Ralph Progress then the block above.

9. Report to user

Say which story you completed (ID and title) and that you updated the PRD and progress. If there are still stories with passes === false, say: "Run another iteration to do the next story." If all are complete, say: "All PRD stories are complete."

prd.json format

If the user wants to create a new prd.json (no file yet), create it with this shape: { "project": "ProjectName", "branchName": "ralph/feature-kebab-case", "description": "Short feature description", "userStories": [ { "id": "US-001", "title": "Short title", "description": "As a [role], I want [thing] so that [benefit].", "acceptanceCriteria": [ "Verifiable criterion 1", "Verifiable criterion 2", "Typecheck passes" ], "priority": 1, "passes": false, "notes": "" } ] } priority: Lower number = higher priority. Order by dependency (e.g. schema before UI). passes: Start as false; set to true only after the story is implemented and committed. acceptanceCriteria: Each item must be checkable (e.g. "Typecheck passes", "Tests pass").

Codebase Patterns (progress.txt)

• Optionally keep a Codebase Patterns section at the top of progress.txt so future iterations (or you in the next run) see it first:
• # Better Ralph Progress
• ## Codebase Patterns
• Use X for Y in this codebase
• Always run Z after changing W
• Tests require PORT=3000
• ---
• When you read progress.txt at the start of an iteration, use this section as context. When you discover a reusable pattern, add it here (edit the top of the file and keep the rest intact). Do not put story-specific details in Codebase Patterns.

Rules

One story per invocation. Do not implement multiple stories in one go. Do not commit failing code. Only commit after quality checks pass. Do not mark a story as passed if you did not commit (e.g. checks failed). Append to progress.txt; never replace the whole file (except when creating it for the first time). Keep changes minimal and focused on the current story’s acceptance criteria.

Checklist (one iteration)

Read prd.json and progress.txt (and Codebase Patterns if present) Picked next story (passes=false, lowest priority number) Git branch matches prd.json.branchName Implemented story and satisfied all acceptance criteria Quality checks passed (test/lint/typecheck) Committed with message feat: [ID] - [Title] Set that story’s passes to true in prd.json Appended progress block to progress.txt