Use when writing PRD.md or PROMPT.md files for use with gralph ralph loops — iterative Claude Code automation driven by a checklist-based PRD and per-iteration prompt
A ralph loop drives Claude Code through a PRD checklist one item at a time:
gralph --prompt-md PROMPT.md --prd-md PRD.md
Two files drive every loop:
These are NOT traditional documents. PRD.md is a checklist. PROMPT.md is a loop procedure, not a one-shot implementation prompt.
A gralph-processable checklist. Each unchecked item (- [ ]) is processed in order. Gralph marks items - [x] (complete) or - [~] (abandoned after max iterations).
See templates/PRD-template.md for the full template.
Section order:
The opening italicized note is required — it orients Claude on how gralph processes the document.
Every cycle under ## Implementation Plan must have all six fields:
- [ ] **Cycle N - <short title>**: <one-sentence description>.
- Agent: `<agent-name>`
- Files: `<file1>`, `<file2>`
- Steps:
- <atomic action>
- <atomic action>
- Verify: `<runnable command that exits 0 on success>`
- Done: <observable exit condition tied to the Verify command>
| Field | Rules |
|---|---|
| Agent | Use exact subagent name available in the repo |
| Files | Every file the cycle creates or modifies |
| Steps | Imperative, one atomic action per line |
| Verify | Copy-pasteable command; must exit 0 on success |
| Done | Concrete observable state — not a restatement of Steps |
Per-iteration instructions. Claude reads this at the start of every gralph invocation, selects the first unchecked PRD cycle, executes it, verifies, commits, updates the PRD, and stops.
See templates/PROMPT-template.md for the full template.
Section order:
| Section | What to change |
|---|---|
| Inputs | Set paths to PRD.md, progress.txt, key design docs |
| Repo-Specific Rules | Language, toolchain, build path |
| Step 5 Verify | Add baseline checks for the tech stack |
The Non-Negotiable Rules and 8-step procedure structure stay the same across projects.
| Mistake | Fix |
|---|---|
PRD with no - [ ] markers | gralph only processes these markers — every cycle must have one |
| Done = restatement of Steps | Done must be tied to the Verify command output |
| PROMPT.md as one-shot generator | Must say "complete exactly one cycle" and include the 8-step procedure |
| Cycles that are too large | If a cycle takes multiple gralph runs to finish, split it |
| No Verify command | Every cycle needs a runnable command exiting 0 on success |
| Vague agent name | Use the exact subagent name registered in the repo |
| Missing progress log path in PROMPT.md | Claude needs to know where to append the progress entry |