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)
