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 \x3CbranchName> or git checkout \x3CbranchName>).

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