ralph-workplan/plugin/ralph-workplan.md

description, argument-hint, allowed-tools, hide-from-slash-command-tool

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

"${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:

"${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.