rich-parallel-agents 0.1.0

package/skills/rpa/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: rpa
+description: >-
+  Use the `rpa` verification gate on top of Orca orchestration. worker_done is a
+  claim, not acceptance. Use when coordinating parallel Orca workers whose
+  changes must pass task verify before merge, when the user says "rpa",
+  "rich parallel agents", "verification gate", "claim then verify", or
+  "don't trust worker_done". Prefer this over treating Orca worker_done as
+  done. Use the orchestration skill to create/dispatch workers; use rpa to
+  claim, verify, retry, integrate, resume, and clean.
+---
+
+# RPA verification gate
+
+Orca owns terminals, worktrees, tasks, and `worker_done`.
+RPA owns the gate: claim → verify → accepted SHA only → integrate.
+
+Do not treat `orca orchestration` `worker_done` as merge-ready.
+Do not merge worker worktrees by hand. Do not skip verify.
+
+If `rpa` is missing from PATH, stop and tell the human to run
+`pnpm rpa skill --install` from the rich-parallel-agents checkout
+(or `rpa skill --install` if the binary already exists).
+
+Load this guide from the binary when possible so it cannot drift:
+
+```bash
+rpa skill
+```
+
+## Coordinator loop
+
+```bash
+# 1. Start a run in the repo that has rpa.yaml
+rpa init --config rpa.yaml --repo <repo>
+# or: rpa run --plan plan.json --plan-only
+
+# 2. Dispatch workers with Orca (not rpa)
+orca orchestration task-create --spec "<task>" --task-title "<id>" --json
+orca orchestration worker-start --task <orca_task_id> --worktree <selector> --agent <agent> --json
+
+# 3. On worker_done, record a claim — this is NOT accepted
+rpa claim --task <id> --worktree <path> --orca-task <orca_task_id> --dispatch <dispatch_id> --agent <agent>
+# outcome=failed → blocked, skip verify:
+# rpa claim --task <id> --worktree <path> --outcome failed
+
+# 4. Task verify. Pass → accepted. Fail → retrying/blocked.
+rpa verify --task <id>
+rpa retry --task <id>            # optional: --orca to worker-start --retry-of
+
+# 5. Merge accepted SHAs only, then integration verify
+rpa integrate --into <integration_worktree>
+rpa status
+rpa report
+```
+
+`--json` on every agent call.
+
+## Worker contract
+
+Workers still finish through Orca (`worker_done` / escalation).
+They must commit (clean HEAD) before claiming done.
+They must not integrate, force-push onto the integration branch, or mark the RPA task accepted.
+
+## Status meanings
+
+| status | meaning |
+|---|---|
+| claimed | worker asserted done |
+| accepted | task verify passed |
+| integrated | SHA merged into `--into` |
+| retrying | verify failed, retries remain |
+| blocked | failed claim, max retries, merge conflict, or no-retry error class |
+
+`rpa retry --task` on a merge-blocked task returns it to `accepted` for another integrate.
+
+## Config
+
+Repo-root `rpa.yaml` (see `rpa.example.yaml`):
+
+```yaml
+verify:
+  task:
+    - name: test
+      command: pnpm test
+      required: true
+  integration:
+    - name: test
+      command: pnpm test
+      required: true
+retry:
+  max: 1
+```
+
+Unknown / credential / environment / permission failures are blocked without retry.
+
+## Cleanup
+
+Only RPA-owned resources. Expired leases are investigate signals, not delete permission.
+Worktrees stay unless `--worktrees --force`.
+
+```bash
+rpa resume <run-id>          # optional --orca to reconcile worker-list
+rpa clean                    # dry for worktrees
+rpa history --stats
+```