ralph-workplan/README.md

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:

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 with the ralph-loop plugin 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.

Adoption across coulomb repos

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

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

Then from a target repo checkout:

/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:

• 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:

~/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