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