ralph

Iterative task completion loop driven by a user-confirmed Definition of Done. Combines the Ralph Wiggum technique (prompt re-injection on stop) with DoD-based independent verification.

How it works:

1. You propose DoD criteria based on the user's request
2. User confirms/modifies via AskUserQuestion
3. You work on the task
4. When you try to stop, the Stop hook checks the DoD checklist:
   • If unchecked items remain → blocks exit, re-injects original prompt + remaining items
   • If all items checked → allows exit
5. Loop continues until all DoD items verified or circuit breaker (max 10 iterations)

---

Phase 1: DoD Collection

Build a Definition of Done through interactive confirmation before starting work.

Step 1 — Analyze & Propose

Read the user's request carefully. Based on the task, propose 3–7 concrete, verifiable DoD criteria.

Good criteria (binary, independently verifiable):

• "All unit tests pass (npm test exits 0)"
• "New function parseConfig() exists in src/config.ts"
• "No TypeScript errors (tsc --noEmit exits 0)"

Bad criteria (vague, subjective):

• "Code is clean" → reword to "No lint warnings (eslint . exits 0)"
• "Works correctly" → reword to specific test or behavior check

Present as a numbered markdown checklist:

Based on your request, here's my proposed Definition of Done:

1. [concrete criterion 1]
2. [concrete criterion 2]
3. [concrete criterion 3]
...

Each item will be independently verified before the task is considered complete.

Step 2 — User Confirmation

Use AskUserQuestion to confirm:

"Here are the proposed DoD criteria. You can:

• Accept as-is
• Add criteria (tell me what to add)
• Remove criteria (tell me which to remove)
• Modify criteria (tell me what to change)

Also, set max iterations (default: 10) if you want to limit the loop."

Loop until the user accepts. Parse their response for:

• Additions, removals, or modifications
• Custom max_iterations (default 10 if not specified)

Step 3 — State Initialization

After user confirms, initialize the loop state and write the DoD file.

Write DoD file — create the checklist as a markdown file:

Bash: SESSION_ID="[session ID from hook]" && mkdir -p "$HOME/.hoyeon/$SESSION_ID/files" && cat > "$HOME/.hoyeon/$SESSION_ID/files/ralph-dod.md" << 'DODEOF'
# Definition of Done

- [ ] [criterion 1]
- [ ] [criterion 2]
- [ ] [criterion 3]
...
DODEOF

Write state — store the original prompt and configuration for the Stop hook:

Bash: SESSION_ID="[session ID from hook]" && PROMPT=$(cat << 'PROMPTEOF'
[The user's ORIGINAL request/prompt — exactly as they typed it, before any processing]
PROMPTEOF
) && hoyeon-cli session set --sid "$SESSION_ID" --json "$(jq -n \
  --arg prompt "$PROMPT" \
  --arg dod_file "$HOME/.hoyeon/$SESSION_ID/files/ralph-dod.md" \
  --arg created_at "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  '{ralph: {prompt: $prompt, iteration: 0, max_iterations: 10, dod_file: $dod_file, created_at: $created_at}}')"

Replace max_iterations: 10 with the user's chosen value if they specified one.

Display confirmation:

## Ralph Loop Initialized

**Task**: [summary of what you'll do]
**DoD**: [N] criteria
**Max iterations**: [max_iterations]

Starting work. The loop will verify each DoD item independently before allowing completion.

---

Phase 2: Work Execution

Now do the actual work. Focus on completing the task to satisfy all DoD criteria.

Rules during work:

• Do NOT read or modify the DoD file (ralph-dod.md) — it's guarded by the system
• Do NOT try to check off DoD items yourself — the Stop hook handles verification
• Focus purely on the task described in the user's original request
• Work thoroughly — the loop will catch anything you miss

When you believe the work is complete, simply finish your response normally. The Stop hook will:

1. Check the DoD file for unchecked items
2. If items remain: block exit, re-inject the original prompt in reason, list remaining items in systemMessage
3. If all items checked: allow exit

On re-entry (after Stop hook blocks):

• You will receive the original prompt again as your task
• The systemMessage will instruct you to spawn a ralph-verifier agent

Verification via separate agent (context isolation):

1. Spawn ralph-verifier agent with subagent_type="ralph-verifier" in FOREGROUND (do NOT use run_in_background=true)
   • Background spawn causes the main agent to stop → Stop hook fires → loop breaks
   • Pass the DoD file path and original prompt
2. The verifier runs in a fresh context — no bias from the work phase
3. Parse the verifier's JSON results:
   • PASS items → change - [ ] to - [x] in the DoD file
   • FAIL items → fix the underlying issue in this iteration
4. If FAIL items were fixed, the next Stop hook will trigger another verification round

Why a separate agent? The agent that wrote the code should NOT verify its own work. The verifier agent starts clean, reads actual files/tests, and judges objectively.

---

Prompt Hardening

• Store the original prompt in state.json via heredoc to prevent shell injection
• The Stop hook re-injects the prompt via jq JSON construction (safe)
• DoD file is guarded during work phase — only editable during verification
• Circuit breaker at max_iterations prevents infinite loops