feat: initial ralph-workplan skill

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>

README.md

@@ -0,0 +1,104 @@
+# 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