Better Ralph , One Iteration

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.

---

intent

better ralph runs a single, focused coding iteration driven by a prd.json file in your workspace root. each iteration picks the next incomplete user story by priority, implements it to satisfy all acceptance criteria, runs quality checks (test/lint/typecheck), commits the code, marks the story as passed in prd.json, and appends a progress entry. use this when you want autonomous, incremental feature delivery with built-in quality gates and audit trail. triggers on phrases like "run better ralph", "do one better ralph iteration", "next prd story", "implement next story from prd", or "ralph loop".

---

inputs

• prd.json (workspace root): JSON file defining the project, target branch, and user stories. required. schema below. if missing, you can create it from scratch using the template provided.

• progress.txt (workspace root, optional): plain text file tracking completed iterations. on first run, created automatically. read the "Codebase Patterns" section (if present near the top, before the first "##" that isn't "## Codebase Patterns") to extract implementation patterns and gotchas for context.

• git repo (workspace): current branch tracked. if prd.json specifies a branchName, you will checkout or create that branch before implementing.

• quality check scripts: project-specific npm/shell commands (e.g. npm test, npm run lint, npm run typecheck). you must run these before committing. project must define these in package.json or equivalent; skill does not auto-detect.

• code editor access: standard read_file, write_file, edit tools to modify source.

• git tools: standard git stage, commit, branch, checkout commands.

---

procedure

1. read state

read prd.json from workspace root and parse the JSON. then read progress.txt if it exists. if progress.txt contains a section labeled "## Codebase Patterns" (starting after that header and ending at the next "##" or end of file), extract and store that text as implementation context for step 4. if no progress.txt exists or no Codebase Patterns section is present, continue without extra context.

inputs: workspace path, prd.json file.
outputs: parsed prd object, extracted codebase patterns (or empty string).

2. pick next story

from prd.json.userStories, filter all stories where passes === false. sort this filtered list by priority ascending (lower number = higher priority). select the first story in the sorted list. this is your target story for this iteration.

edge case: if no stories have passes === false (all stories complete), reply to user "All PRD stories are complete. nothing left to do." and stop. do not proceed to step 3.

inputs: prd.userStories array.
outputs: selected story object (id, title, description, acceptanceCriteria, priority, passes=false), or null if all complete.

3. ensure git branch

run git branch --show-current to get the current branch name. compare it to prd.json.branchName. if they differ, run git checkout <branchName> (or git checkout -b <branchName> if the branch does not exist). if they match, do nothing.

inputs: current git branch, prd.branchName.
outputs: git working directory on the correct branch.

4. implement the story

read the selected story's acceptanceCriteria array. write or edit code (using available source files in the workspace) to satisfy every item in the acceptance criteria list. reference the codebase patterns extracted in step 1 if available. do not start or implement any other story. focus only on the one you selected.

inputs: story object, workspace source files, codebase patterns (optional).
outputs: modified source files in workspace.

5. run quality checks

execute the project's quality check commands. typical examples: npm test, npm run lint, npm run typecheck. the exact command set depends on the project; check package.json, Makefile, or CI config. run all quality checks sequentially. if any check exits with non-zero status or produces errors, stop immediately. do not proceed to step 6.

edge case: if quality checks fail, report the failure details to the user (which command failed, error output). do not mark the story as passed. do not update prd.json or progress.txt. do not commit.

edge case: if quality checks hang or timeout (>60s per check), kill the process and report timeout to user.

inputs: story implementation, quality check commands from project config.
outputs: all checks passed (zero exit codes), or failure reported and iteration halted.

6. commit (only on passing checks)

run git add -A or equivalent to stage all changes. then run git commit -m "feat: [Story ID] - [Story Title]". replace [Story ID] with the story.id value and [Story Title] with the story.title value. example: feat: US-002 - Display priority on task cards.

inputs: staged changes, story id and title.
outputs: commit created on current branch with specified message.

7. mark story passed in prd.json

read prd.json again from disk (in case it changed since step 1). locate the user story with id matching the one you just completed. set its passes field to true. write the full updated prd.json back to disk. preserve all other fields and stories unchanged.

inputs: prd.json (re-read), story id from step 2.
outputs: updated prd.json with target story.passes = true.

8. append progress to progress.txt

append a new progress block to progress.txt (do not overwrite the file). use this format:

## [Current date/time] - [Story ID]
- What was implemented (1, 2 sentences)
- Files changed (list file paths)
- **Learnings for future iterations:**
  - Patterns or gotchas discovered
  - Example: "this codebase uses X for Y", "remember to update Z when changing W"
---

if progress.txt does not exist, create it with header # Better Ralph Progress on line 1, then add the block above.

if you discovered a reusable codebase pattern, edit the "## Codebase Patterns" section at the top of progress.txt (if it exists) to add the pattern. do not add story-specific details there, only reusable patterns.

inputs: story id, title, file changes, implementation notes, progress.txt (if exists).
outputs: progress.txt with new block appended (or created if new).

9. report to user

tell the user which story you completed (id and title). confirm that you updated prd.json and progress.txt. if there are still incomplete stories (passes === false), say "run another iteration to do the next story." if all stories now have passes === true, say "all PRD stories are complete."

inputs: selected story, remaining incomplete stories count.
outputs: user-facing message.

---

decision points

if all stories have passes === true (step 2): report "All PRD stories are complete. nothing left to do." and stop. do not proceed.

if prd.json.branchName differs from current git branch (step 3): checkout or create the specified branch before implementing. do not implement on the wrong branch.

if quality checks fail (step 5): report failure and stop. do not commit, do not update prd.json, do not append progress. user must fix and retry the iteration.

if progress.txt exists and contains "## Codebase Patterns" (step 1): use the extracted patterns as context during implementation (step 4). if no such section exists, proceed without extra context.

if progress.txt does not exist (step 8): create it with a header and then append the progress block.

---

output contract

prd.json: valid JSON file, workspace root, with structure:

{
  "project": "string",
  "branchName": "string (git branch name)",
  "description": "string",
  "userStories": [
    {
      "id": "string (e.g. US-001)",
      "title": "string",
      "description": "string",
      "acceptanceCriteria": ["string", "string"],
      "priority": "number (lower = higher priority)",
      "passes": "boolean",
      "notes": "string"
    }
  ]
}

progress.txt: plain text file, workspace root, with format:

# Better Ralph Progress

## Codebase Patterns
- pattern 1
- pattern 2

---

## [date/time] - [Story ID]
- implementation summary
- files changed
- **Learnings for future iterations:**
  - learning 1
---

## [next date/time] - [next Story ID]
...

git commit: created on current branch with message feat: [Story ID] - [Story Title].

story in prd.json: target story now has passes === true.

---

outcome signal

• user sees the completed story id and title in the confirmation message.
• user sees "update prd.json and progress.txt confirmed" (or similar).
• git log shows a new commit with feat: [Story ID] - [Story Title].
• prd.json now shows passes === true for the completed story.
• progress.txt has a new dated block with implementation details.
• if more stories remain incomplete, user sees "run another iteration to do the next story." if all complete, user sees "all PRD stories are complete."

---

prd.json template (create if missing)

{
  "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 is lower number = higher priority. order stories by dependency (e.g. schema before UI). passes starts false; set true only after implementation + commit. acceptance criteria must be checkable (e.g. "typecheck passes", "tests pass").

---

codebase patterns section (in progress.txt)

optionally maintain a "## Codebase Patterns" section at the top of progress.txt (after the main title) so future iterations 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, extract this section as context. when you discover a reusable pattern, add it here (edit the top of the file, keep the rest intact). do not put story-specific details in codebase patterns.

---

rules

• one story per invocation. do not implement multiple stories at once.
• 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 on first creation.
• keep changes minimal and focused on the current story's acceptance criteria.
• if a quality check hangs beyond 60s, kill it and report to user.
• if prd.json or progress.txt changes during the iteration (external edit), re-read after committing (step 7) to ensure you update the latest version.

---

checklist (one iteration)

• read prd.json and progress.txt; extract codebase patterns if present
• picked next story (passes=false, lowest priority number)
• git branch matches prd.json.branchName (or checked out/created it)
• implemented story, satisfied all acceptance criteria
• quality checks passed (test, lint, typecheck, etc.)
• committed with message feat: [ID] - [Title]
• set story.passes to true in prd.json, wrote updated file
• appended progress block to progress.txt
• reported to user with next action

---

credits: original author austindixson. enriched for implexa quality standards.