---
title: Ralph Workplan — Reference
---

# Ralph Workplan — Reference

`/ralph-workplan` is a Claude Code skill that starts a self-managing
[Ralph Loop](https://github.com/anthropics/claude-code) 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.

```bash
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:
```bash
cd ~/ralph-workplan && git pull && ./install.sh
```

To uninstall:
```bash
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

```markdown
---
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)