docs(pi): implement milestone M1 - research and shared docs

2026-04-23 15:58:19 -05:00
parent c98f27f461
commit 7ba6f90e14
4 changed files with 258 additions and 0 deletions
@@ -0,0 +1,84 @@
+# PI SUPERPOWERS
+
+## Purpose
+
+The pi workflow variants in this repo depend on two shared pieces of setup:
+
+- Obra Superpowers skills
+- reviewer-runtime helper scripts
+
+This guide documents how to make both available to pi without inventing skill-specific setup instructions in three different workflow docs.
+
+## Superpowers Setup
+
+Pi can load skills from `~/.pi/agent/skills/`, `~/.agents/skills/`, `.pi/skills/`, `.agents/skills/`, package manifests, and settings-defined skill paths. Because of that, there are two supported ways to expose Obra Superpowers to pi.
+
+### Option 1: Reuse `~/.agents/skills/`
+
+If you already expose Superpowers through a shared root such as:
+
+```bash
+~/.agents/skills/superpowers -> ~/.codex/superpowers/skills
+```
+
+pi can discover those skill directories directly. This is only an example path, not a requirement; any shared skill root that pi can read is fine. It is simply the easiest path when Codex and pi share the same machine.
+
+### Option 2: Add An Explicit Pi Settings Entry
+
+If you want pi to load a different path, add it in either `~/.pi/agent/settings.json` or `.pi/settings.json`:
+
+```json
+{
+  "skills": [
+    "~/.agents/skills",
+    "/absolute/path/to/obra/superpowers/skills"
+  ]
+}
+```
+
+Use this when the shared `~/.agents/skills/` root is missing or when you want a pi-specific override.
+
+## Reviewer Runtime Setup
+
+The workflow-heavy pi variants expect the helper scripts from `skills/reviewer-runtime/pi/` to be installed in one of these locations:
+
+1. `.pi/skills/reviewer-runtime/pi/`
+2. `~/.pi/agent/skills/reviewer-runtime/pi/`
+
+Supported helper files:
+
+- `run-review.sh`
+- `notify-telegram.sh`
+
+Example global install:
+
+```bash
+mkdir -p ~/.pi/agent/skills/reviewer-runtime/pi
+cp -R skills/reviewer-runtime/pi/* ~/.pi/agent/skills/reviewer-runtime/pi/
+chmod +x ~/.pi/agent/skills/reviewer-runtime/pi/*.sh
+```
+
+Example project-local install:
+
+```bash
+mkdir -p .pi/skills/reviewer-runtime/pi
+cp -R skills/reviewer-runtime/pi/* .pi/skills/reviewer-runtime/pi/
+chmod +x .pi/skills/reviewer-runtime/pi/*.sh
+```
+
+## Telegram Notifications
+
+If you want pi workflow skills to send completion messages, configure:
+
+- `TELEGRAM_BOT_TOKEN`
+- `TELEGRAM_CHAT_ID`
+
+The shared notification behavior matches the existing repo guidance in [TELEGRAM-NOTIFICATIONS.md](./TELEGRAM-NOTIFICATIONS.md).
+
+## What This Does Not Assume
+
+- pi does not automatically provide Codex `update_plan` semantics
+- pi does not automatically provide plan mode or worktree workflows
+- pi does not require extensions for the base workflow skills in this repo
+
+The pi variants must therefore spell out their workflow steps directly and only rely on dependencies documented here.