Complete RALPH-WP-0002 plugin hardening and adoption docs

README.md

@@ -93,6 +93,39 @@ When every task is `done`, Claude also updates the workplan frontmatter to
 
 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