/ralph

name: ralph
description: |
  Iterative task completion loop with Definition of Done verification.
  Combines the Ralph Wiggum technique (prompt re-injection via Stop hook) with
  DoD-based independent verification. Claude proposes DoD criteria, user confirms,
  then Claude works autonomously. Stop hook re-injects the original prompt and
  blocks exit until all DoD items are independently verified.
  "/ralph", "ralph loop", "ralph 루프", "반복 작업", "DoD 루프",
  "완료 검증 루프", "task loop", "keep going until done"
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash
  - Write
  - Edit
  - Agent
  - AskUserQuestion
validate_prompt: |
  Must contain Phase 1 (DoD Collection) and Phase 2 (Work Execution).
  Must use AskUserQuestion for DoD confirmation.
  Must write state via hoyeon-cli session set with .ralph namespace.
  Must write DoD file to session files directory.
  Must include prompt storage for Stop hook re-injection.

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 fi