ralph-workplan/README.md

# ralph-workplan

A Claude Code skill that starts a [Ralph Loop](https://github.com/anthropics/claude-code)
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:
1. Re-reads the workplan file and checks task statuses
2. If all tasks are `done` and workplan `status: done` → outputs `<promise>HEUREKA</promise>` and the loop stops
3. Otherwise → continues implementing, marking tasks done as it goes

Before starting, the skill guards against running on an already-completed workplan.

## Requirements

- [Claude Code](https://claude.ai/code) with the `ralph-loop` plugin installed
- Bash (macOS or Linux)

No other dependencies. No external services.

## Install

```bash
git clone <this-repo> ~/ralph-workplan
cd ~/ralph-workplan
./install.sh
# restart Claude Code
```

To uninstall:
```bash
./install.sh --uninstall
```

## Workplan format

A workplan is a Markdown file with YAML frontmatter and task blocks:

```markdown
---
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](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.

## Adoption across coulomb repos

Use ralph-workplan in any repo that already follows ADR-001 workplan files:

```bash
git clone forgejo-remote:coulomb/ralph-workplan.git ~/ralph-workplan
cd ~/ralph-workplan && ./install.sh
# restart Claude Code
```

Then from a target repo checkout:

```bash
/ralph-workplan workplans/CUST-WP-0056-daily-todo-md-stale-review.md
/ralph-workplan workplans/MY-WP-0003-feature.md --max-iterations 15
```

**Workplan requirements** — see [workplan-spec.md](workplan-spec.md):

- YAML frontmatter with `id`, `title`, `status` (`active` while in progress; `done`/`finished` when complete)
- One or more fenced ` ```task ` blocks with `id`, `status`, optional `priority`
- For State Hub–integrated repos: include `state_hub_workstream_id` and per-task `state_hub_task_id`; mark tasks `done` in the file **and** call `update_task_status` in the hub

**`check-done.sh` behavior** — pre-start guard exits 0 only when frontmatter status is `done`/`finished` **and** every task is `done` or `cancel`. Otherwise the skill refuses to start (or continues the loop).

**`--max-iterations`** — default 20. Use 10–15 for small workplans; raise only when tasks are large and file-driven progress is slow. The loop always sets completion promise `HEUREKA`.

Manual check without starting a loop:

```bash
~/ralph-workplan/plugin/scripts/check-done.sh workplans/MY-WP-0001.md && echo complete || echo incomplete
```

## 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 HEUREKA` and a bounded iteration count