diff --git a/dashboard/observablehq.config.js b/dashboard/observablehq.config.js index 54e316a..74f9c59 100644 --- a/dashboard/observablehq.config.js +++ b/dashboard/observablehq.config.js @@ -56,6 +56,7 @@ export default { { name: "Live Data", path: "/docs/live-data" }, { name: "Overview", path: "/docs/overview" }, { name: "Progress Log", path: "/docs/progress-log" }, + { name: "Ralph Workplan", path: "/docs/ralph-workplan" }, { name: "Reference & Context Help", path: "/docs/reference" }, { name: "Repo Integration", path: "/docs/repo-integration" }, { name: "Repos", path: "/docs/repos" }, diff --git a/dashboard/src/docs/ralph-workplan.md b/dashboard/src/docs/ralph-workplan.md new file mode 100644 index 0000000..832594b --- /dev/null +++ b/dashboard/src/docs/ralph-workplan.md @@ -0,0 +1,208 @@ +--- +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 + `HEUREKA` 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 [--max-iterations N] +``` + +| Argument | Required | Default | Description | +|----------|----------|---------|-------------| +| `` | 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 + `HEUREKA` 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: active +--- + +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` | `active` \| `done` \| `paused` | 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: done +``` + +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 `-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) diff --git a/dashboard/src/reference.md b/dashboard/src/reference.md index ef28788..36eccf7 100644 --- a/dashboard/src/reference.md +++ b/dashboard/src/reference.md @@ -45,4 +45,5 @@ convention used in the Custodian State Hub. | Topic | What it covers | |-------|---------------| +| [Ralph Workplan](/docs/ralph-workplan) | `/ralph-workplan` skill — installation, usage, workplan format, COULOMBCORE setup | | [Reference & Context Help](/docs/reference) | How reference pages work; the ? context-help button |