tegwick
f3174cebc9
Standalone Claude Code skill that ties a ralph loop to a workplan file. Retires automatically when all tasks are done — no external dependencies. - plugin/ralph-workplan.md skill entrypoint - plugin/scripts/check-done.sh pre-start guard (reads workplan status) - plugin/scripts/setup.sh writes ralph state file with workplan-aware prompt - install.sh copies plugin files to ~/.claude/plugins/ - workplan-spec.md workplan file format reference - README.md Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
105 lines
2.4 KiB
Markdown
105 lines
2.4 KiB
Markdown
# 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.
|
||
|
||
## 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
|