Bernd Worsch
9d57ce430f
workplan-spec.md: - Task Close Gate: when marking a task done in the file, also call update_task_status(state_hub_task_id, "done") in the State Hub - HEUREKA Completion Sequence: before HEUREKA, for hub-integrated workplans: update all tasks, update_workstream_status → done, add_progress_event milestone, then set status: done and output HEUREKA plugin/ralph-workplan.md: - Added State-Hub Integration Notes section injected via stop-hook prompt so the worker follows Task Close Gate and HEUREKA Completion Sequence Resolves: state-hub progress event 1e73441e (2026-03-16) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
101 lines
3.2 KiB
Markdown
101 lines
3.2 KiB
Markdown
---
|
||
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.
|