Ralph Crispies: daily driver for the QRDS-PI cycle. Reads the bead graph, reports state, presents structure for review, handles iteration (send feedback through another pass). Triggers on: rc-next, rc next, what's next, continue, pick up, resume.
Read the bead graph and advance the QRDS-PI cycle.
Epic input: $ARGUMENTS
This is the daily driver. Every invocation:
bd CLI installed (bd --version >= 1.0.0).beads/ workspace initialized in the current projectIf $ARGUMENTS contains an epic ID, use that.
If no argument provided, find all epics (including closed ones):
bd list --type epic --json
Include closed epics — the user may want to iterate on a completed cycle. Sort by most recently updated.
If exactly one epic, use it automatically.
If multiple epics, present the list and ask which one:
"Found these epics:"
<id>: <title> — <status> "Which one?"
If none found:
"No epics found. Start with:
rc-questions <task description>"
bd children <epic-id> --json
bd gate list --json
bd ready --json
Parse phase beads. Check for child beads under research (mitosis):
bd children <research-bead-id> --json 2>/dev/null
Walk the phase chain and handle the appropriate case:
Case: questions bead is open
"Epic
<id>: Questions phase." "Runrc-questionsto start the interview."
Case: questions closed, R-D-S in progress or ready
Show progress:
"Epic
<id>: Autonomous QRDS in progress."
- Research: [status] [child bead count if any]
- Design: [status]
- Design-review: [status]
- Structured-outline: [status]
[if research is ready and loop hasn't started]: "Start the loop:
ralph-loop <epic-id> --worktree"
Case: all phase beads closed (cycle complete)
This is the main interaction point. The QRDS cycle finished. Read the structure document and present it for review.
bd show <structure-bead-id>
bd show <design-bead-id>
bd show <design-review-bead-id>
Present the full structure outline:
"Epic
<id>: QRDS cycle complete. Structure ready for review."Design approach: <extract approach summary from design bead>
Review findings: <extract issues/verdict from design-review bead>
Structure outline: <show the FULL structure outline from the structure bead>
"If you approve, PI starts next.
plan-researchwill write a checked-in ExecPlan underplans/, thenexpandwill slice implementation beads from that plan."
Then present options using AskUserQuestion:
Question: "QRDS cycle complete. Structure is ready for review. What would you like to do?" Header: "Plan review" Options:
Case: human says "approve"
The structured outline is accepted. The PI (Plan + Implement) pipeline beads already exist (stamped by the formula). Close the gate to unblock them.
Find the open gate:human bead (not gate:human-merge) under this epic:
bd children <epic-id> --json
Find the bead whose title starts with gate:human (not gate:human-merge)
and status is open. Close it:
bd close <gate-bead-id>
This unblocks the plan-research bead, which was already stamped by the formula.
"Plan approved. PI pipeline is unblocked:" "plan-research → plan-review → expand → expand-review → convention-audit → adversarial-review → epilogue → gate:human-merge"
"Run:
ralph-loop <epic-id>" "Expected artifact flow:plan-researchwritesplans/<epic-slug>.md,plan-reviewaudits that ExecPlan, thenexpandstamps implementation beads from it.""When the loop finishes, run
rc-nextto review the diff, the ExecPlan-backed implementation, and merge."
Case: human says "iterate" or provides feedback
This is the iteration flow. The human has feedback on the structure document. Start a new QRDS pass that builds on the existing one.
bd reopen <epic-id>
"What needs to change? I'll read the existing plan and your feedback, then run another R-D-S pass. Tell me everything — what's wrong, what's missing, what should be different."
bd create --parent <epic-id> --title "questions-v2: <name>" \
--description "<feedback + reference to existing structure bead>" \
--type task
bd create --parent <epic-id> --title "research-v2: <name>" \
--deps "<questions-v2-id>" \
--description "<enriched research instructions referencing both the v1 structure and the feedback>" \
--type task
bd create --parent <epic-id> --title "design-v2: <name>" \
--deps "<research-v2-id>" \
--description "<enriched design instructions>" \
--type task
bd create --parent <epic-id> --title "design-review-v2: <name>" \
--deps "<design-v2-id>" \
--description "<enriched review instructions>" \
--type task
bd create --parent <epic-id> --title "structured-outline-v2: <name>" \
--deps "<design-review-v2-id>" \
--description "<enriched structured-outline instructions — must produce UPDATED outline incorporating feedback>" \
--type task
Use plain bead IDs in --deps. blocks:X means X blocks me, which reverses
the intended chain in these examples.
Enrich the new bead descriptions with concrete IDs — the v2 research bead should read BOTH the v1 structure bead AND the v2 questions (feedback) bead. The v2 design bead reads v2 research. And so on.
Write feedback into the v2 questions bead and close it:
bd update <questions-v2-id> --description "<human's feedback + what to change>"
bd close <questions-v2-id>
"Iteration beads stamped. The v2 pass will build on the existing plan with your feedback." "Run:
ralph-loop <epic-id> --worktree"
The ralph-loop will pick up the v2 beads (the v1 beads are already closed, so they won't be picked again). The v2 structured-outline bead produces an UPDATED outline.
Case: expand bead exists (implementation pipeline stamped)
The expand bead or implementation beads are in progress.
Read the plan bead too so you can surface the current ExecPlan path when present:
bd show <plan-research-bead-id>
bd children <epic-id> --json
Look for beads with titles starting with "expand:", "implement:", or "epilogue:".
"Epic
<id>: Implementation in progress." "Current implementation contract: <ExecPlan path from the plan-research bead, if present; otherwise say the plan is still bead-only untilplan-researchwrites it.>"
Show implementation bead status:
| Bead | Status |
|---|---|
| expand: create implementation beads | [closed/in_progress] |
| implement: <file1> | [closed/open/in_progress] |
| implement: <file2> | [closed/open/in_progress] |
| ... | |
| epilogue: review and verify | [blocked/open] |
Progress: X/Y implementation beads complete. [if loop is not running]: "Continue:
ralph-loop <epic-id> --worktree"
Case: epilogue bead is closed
Check if the epilogue found issues (discovery beads).
bd children <epic-id> --json
Look for beads with type "bug" or titles starting with "fix:" — these are discoveries from the epilogue.
Check for worktree branch:
git rev-parse --verify ralph-loop/<epic-id> 2>/dev/null
If the branch exists, present a structured review before the AskUserQuestion:
1. Diff summary (what changed):
git diff --stat main...ralph-loop/<epic-id>
Output as:
Changes on branch
ralph-loop/<epic-id>:<git diff --stat output>
2. Key changes (actual code, not just file names):
Run:
git diff main...ralph-loop/<epic-id>
Pick the 3–5 most significant hunks — prefer new functions, changed logic, or deleted code over whitespace and import changes. Excerpt them inline:
Key changes:
path/to/file.ext— <one-line description of what changed><hunk excerpt>(repeat for each key change)
3. Epilogue verification findings:
bd show <epilogue-bead-id>
Extract the verdict and any issues found:
Epilogue verdict: <pass / issues found> <brief summary of what the epilogue checked and found>
4. Structure outline (reference):
bd show <structure-bead-id>
Show the outline title and first few lines only — this is a reference anchor, not the focus:
Plan reference (
<structure-bead-id>): <structure bead title> (Full outline available viabd show <structure-bead-id>)
Then present options using AskUserQuestion:
If discoveries exist:
Question: "Implementation complete. Epilogue found N issues. How do you want to proceed?" Header: "Next step" Options:
If no discoveries:
Question: "Implementation complete. Clean epilogue. How do you want to proceed?" Header: "Next step" Options:
If NO worktree branch exists (legacy runs without --worktree):
Present options using AskUserQuestion:
Question: "Implementation complete. Clean epilogue. Ready to create PR?" Header: "Next step" Options:
Case: human says "create PR"
Create a PR from the current branch with a summary drawn from the epic's beads.
git add -A
git commit -m "[ralph-crispies] <epic-title>"
gh pr create --title "<epic-title>" --body "$(cat <<'PR_EOF'
## Summary
<summarize from structure bead — what was built and why>
## Implementation
<list of files created/modified from implementation beads>
## Review Notes
<epilogue findings, if any>
## Test Plan
<acceptance criteria from structure bead>
Generated by Ralph Crispies QRDS-PI cycle.
Epic: <epic-id>
PR_EOF
)"
"PR created: <url>" "If review feedback comes back, run
rc-next <epic-id>and choose iterate with the feedback."
Case: human says "merge to main"
Merge the worktree branch and create a PR.
git merge ralph-loop/<epic-id>
Case: human says "view full diff"
Show the full diff:
git diff main...ralph-loop/<epic-id>
Then re-present the same AskUserQuestion options (minus "View full diff").
Case: human provides PR review feedback
Same as the "iterate" case — but the feedback source is PR review comments rather than structure doc review. The v2 questions bead should reference the PR URL and specific review comments.
Always end with the current bead graph:
bd list --parent <epic-id>
bd close or bd gate resolve manually.