state-hub/dashboard/src/docs/ralph-workplan.md

title

title
Ralph Workplan — Reference

Ralph Workplan — Reference

/ralph-workplan is a Claude Code skill that starts a self-managing Ralph Loop tied to a specific workplan file. The loop retires automatically when all tasks in the workplan are done — no external services required.

---

Why use it instead of /ralph-loop

/ralph-loop with a static prompt has no awareness of completion state. It loops until --max-iterations is reached, even if the work is already done.

/ralph-workplan:

• Refuses to start if the workplan status is already done
• Self-retires — re-reads the workplan file every iteration; outputs <promise>HEUREKA</promise> the moment all tasks are done
• Always sets --completion-promise HEUREKA and a bounded iteration count

---

Installation

The skill lives in its own repository: coulomb/ralph-workplan on Gitea.

git clone http://92.205.130.254:32166/coulomb/ralph-workplan.git ~/ralph-workplan
cd ~/ralph-workplan && ./install.sh
# restart Claude Code

Prerequisite: the ralph-loop plugin must be installed first. Install it from within Claude Code: /install ralph-loop (or via the plugin marketplace).

To update to the latest version:

cd ~/ralph-workplan && git pull && ./install.sh

To uninstall:

cd ~/ralph-workplan && ./install.sh --uninstall

---

Usage

/ralph-workplan <workplan-file> [--max-iterations N]

Argument	Required	Default	Description
<workplan-file>	yes	—	Path to the workplan .md file
--max-iterations N	no	20	Maximum loop iterations before stopping

Examples:

/ralph-workplan workplans/MRKD-WP-0001-core-pipeline.md
/ralph-workplan workplans/MRKD-WP-0001-core-pipeline.md --max-iterations 15

---

What happens when you invoke it

1. Validates the workplan file exists
2. Reads the frontmatter — extracts id, title, status
3. Guards — if status: done, stops immediately with a message
4. Shows current task summary (done / in progress / todo counts)
5. Writes .claude/ralph-loop.local.md — the ralph state file containing a workplan-aware prompt
6. The loop begins — on every iteration Claude:
   • Re-reads the workplan file
   • If all tasks are done and frontmatter status: done → outputs <promise>HEUREKA</promise> and the loop stops
   • Otherwise → continues implementation, marking tasks done as it goes

---

Workplan file format

---
id: WP-0001
title: "Build a thing"
status: ready
---

Optional description.

## Task: Do the first thing

​```task
id: T-01
status: todo
priority: high
​```

## Task: Do the second thing

​```task
id: T-02
status: todo
priority: medium
​```

Frontmatter fields:

Field	Values	Description
id	string	Unique workplan identifier
title	string	Human-readable name
status	proposed | ready | active | blocked | backlog | finished | archived	Workplan lifecycle state

Task block fields:

Field	Values	Description
id	string	Unique task identifier
status	todo | in_progress | done	Task state
priority	high | medium | low	Execution order hint

---

How Claude updates task status

As Claude completes tasks it edits the workplan file directly:

status: todo  →  status: in_progress   (when starting)
status: in_progress  →  status: done   (when verified complete)

When every task is done, Claude also updates the frontmatter:

status: active  ->  status: finished

The loop detects this on the next iteration and stops.

---

Naming convention for custodian-family projects

Projects tracked in the State Hub use the prefix <DOMAIN>-WP-NNNN:

Domain	Prefix	Example file
markitect / marki-docx	MRKD-WP	workplans/MRKD-WP-0001-core-pipeline.md
ops-bridge	BRIDGE-WP	workplans/BRIDGE-WP-0004-catalog.md
railiance	RAIL-WP	workplans/RAIL-WP-0001-infra.md
custodian	CUST-WP	workplans/CUST-WP-0011-goals.md

The skill works with any filename — the prefix is a convention, not a requirement.

---

Using ralph-workplan on COULOMBCORE

The skill is already installed on COULOMBCORE. No additional setup needed.

Open a Claude Code session in the target repository on COULOMBCORE and invoke the skill exactly as you would locally:

/ralph-workplan workplans/MRKD-WP-0001-my-feature.md

The skill is fully self-contained — it reads and writes only the workplan file. It does not call the State Hub API or require network access.

If the project also integrates with the State Hub (via the MCP tunnel), the agent can additionally report progress and mark workstream tasks done through the MCP tools during the loop — but this is optional and independent of the ralph-workplan lifecycle.

---

Stopping a running loop

The loop stops automatically when the completion promise is detected. To stop it manually:

/cancel-ralph

This removes .claude/ralph-loop.local.md, which the stop hook checks on every exit attempt. The current iteration completes before the loop stops.

---

Source

Repository: coulomb/ralph-workplan on Gitea Install path: ~/.claude/plugins/ralph-workplan/ Full spec: ~/ralph-workplan/workplan-spec.md (after cloning)