ralph-workplan/plugin/ralph-workplan.md

---
description: "Start a Ralph loop tied to a workplan file — retires automatically when all tasks are done"
argument-hint: "<workplan-file> [--max-iterations N]"
allowed-tools: ["Read", "Bash(${CLAUDE_PLUGIN_ROOT}/scripts/check-done.sh:*)", "Bash(${CLAUDE_PLUGIN_ROOT}/scripts/setup.sh:*)"]
hide-from-slash-command-tool: "true"
---

# Ralph Workplan

Start a ralph loop driven by a workplan file. The loop retires automatically
when all tasks in the workplan are marked done.

## Usage

```
/ralph-workplan workplans/WP-0001-my-task.md
/ralph-workplan workplans/WP-0001-my-task.md --max-iterations 15
```

The workplan file must follow the format described in `workplan-spec.md`
(YAML frontmatter with `id`, `title`, `status` fields; tasks as fenced
`task` code blocks with `id` and `status`).

## Steps

Parse `$ARGUMENTS` to extract:
- `WORKPLAN_FILE` — the positional argument (required)
- `MAX_ITERATIONS` — value after `--max-iterations` (default: 20)

**Step 1 — Validate the workplan file exists**

If the file does not exist:
> "❌ Workplan file not found: $WORKPLAN_FILE"

Stop.

**Step 2 — Read the workplan frontmatter**

Read `$WORKPLAN_FILE`. Extract from the YAML frontmatter:
- `id` — workplan identifier
- `title` — workplan title
- `status` — current status

**Step 3 — Guard: check if already done**

Run:
```bash
"${CLAUDE_PLUGIN_ROOT}/scripts/check-done.sh" "$WORKPLAN_FILE"
```

Exit code 0 means the workplan is already done. If so:
> "✅ Workplan $ID ('$TITLE') is already done — all tasks complete.
>  Nothing to do. No ralph loop started."

Stop.

**Step 4 — Show current task summary**

Count the task blocks in the file (fenced blocks with language tag `task`).
Report:
> "📋 $ID — $TITLE
>  Tasks: X done, Y in progress, Z todo (N total)
>  Starting ralph loop (max $MAX_ITERATIONS iterations)..."

**Step 5 — Start the loop**

Run:
```bash
"${CLAUDE_PLUGIN_ROOT}/scripts/setup.sh" \
  "$WORKPLAN_FILE" "$ID" "$TITLE" "$MAX_ITERATIONS"
```

Then report:
> "🔄 Ralph loop active. The loop will feed the workplan prompt back on every
>  iteration. It retires when all tasks are done and the workplan status is
>  updated to 'done' in the file."

## State-Hub Integration Notes

These notes are injected into the stop-hook prompt so the worker follows the
correct conventions when working on state-hub-integrated workplans.

**Task Close Gate** — When marking a task `done` in the workplan file, if the
task block has a `state_hub_task_id` field, also call `update_task_status` on
that ID in the State Hub. Do this at the same time as editing the file, not
in a batch at the end.

**HEUREKA Completion Sequence** — Before outputting `<promise>HEUREKA</promise>`,
if the workplan frontmatter has `state_hub_workstream_id`:

1. Ensure all `state_hub_task_id` tasks are marked `done` in the hub
   (`update_task_status` — idempotent)
2. Call `update_workstream_status(state_hub_workstream_id, "done")`
3. Call `add_progress_event(summary="<what was delivered>", event_type="milestone",
   topic_id="<from CLAUDE.md>", workstream_id="<state_hub_workstream_id>")`
4. Set workplan frontmatter `status: done`
5. Output `<promise>HEUREKA</promise>`

If the workplan has no `state_hub_workstream_id`, skip all hub calls and go
straight to steps 4–5.