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>
ralph-workplan
A Claude Code skill that starts a Ralph Loop tied to a workplan file. The loop retires automatically when all tasks in the workplan are done — no external services required.
What it does
/ralph-workplan workplans/WP-0001-my-feature.md
/ralph-workplan workplans/WP-0001-my-feature.md --max-iterations 15
On each iteration, Claude:
- Re-reads the workplan file and checks task statuses
- If all tasks are
doneand workplanstatus: done→ outputs<promise>HEUREKA</promise>and the loop stops - Otherwise → continues implementing, marking tasks done as it goes
Before starting, the skill guards against running on an already-completed workplan.
Requirements
- Claude Code with the
ralph-loopplugin installed - Bash (macOS or Linux)
No other dependencies. No external services.
Install
git clone <this-repo> ~/ralph-workplan
cd ~/ralph-workplan
./install.sh
# restart Claude Code
To uninstall:
./install.sh --uninstall
Workplan format
A workplan is a Markdown file with YAML frontmatter and task blocks:
---
id: WP-0001
title: "Build a REST API"
status: active
---
Build a simple REST API with CRUD endpoints for a todo list.
## Task: Set up project structure
```task
id: T-01
status: todo
priority: high
```
## Task: Implement endpoints
```task
id: T-02
status: todo
priority: high
```
## Task: Write tests
```task
id: T-03
status: todo
priority: medium
```
See workplan-spec.md for the full format reference.
How completion works
The loop is entirely file-driven. As Claude completes tasks it edits the workplan file:
status: todo → status: in_progress → status: done
When every task is done, Claude also updates the workplan frontmatter to
status: done. The ralph loop detects this on the next iteration and stops.
No state hub, no HTTP calls, no external coordination needed.
Why not just use /ralph-loop directly?
/ralph-loop with a static prompt has no awareness of completion state — it
loops forever (or until --max-iterations) even if the work is already done.
/ralph-workplan ties the loop lifecycle to the workplan file, so it:
- Refuses to start if the workplan is already done
- Self-retires the moment all tasks are complete
- Always sets
--completion-promise HEUREKAand a bounded iteration count