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,82 @@
+# PI
+
+## Purpose
+
+This repo now treats pi as a first-class target alongside Codex, Claude Code, Cursor, and OpenCode.
+
+The pi support surface is built around the same family layout already used elsewhere in this repo:
+
+- `skills/atlassian/pi/`
+- `skills/create-plan/pi/`
+- `skills/do-task/pi/`
+- `skills/implement-plan/pi/`
+- `skills/web-automation/pi/`
+
+Shared pi guidance lives in:
+
+- [PI-RESEARCH.md](./PI-RESEARCH.md)
+- [PI-SUPERPOWERS.md](./PI-SUPERPOWERS.md)
+
+## Support Strategy
+
+### Variant Layout
+
+Each skill family gets a dedicated `pi` variant instead of a pointer-only shim. That keeps pi-specific wording, installation paths, and workflow constraints reviewable in-repo.
+
+### Shared Workflow Guidance
+
+The workflow-heavy skills (`create-plan`, `do-task`, `implement-plan`) refer to [PI-SUPERPOWERS.md](./PI-SUPERPOWERS.md) for:
+
+- exposing Obra Superpowers to pi
+- installing the shared reviewer runtime for pi
+- Telegram notification setup expectations
+
+### Package Strategy
+
+V1 uses one repo-level pi package rather than per-skill packages. The package surface is intentionally narrow:
+
+- only pi skill variants
+- shared pi docs
+- pi reviewer-runtime helper sources
+- a verification script
+
+The package metadata and allowlist live at repo root so `pi install -l /absolute/path/to/ai-coding-skills` works without extra wrapping.
+
+## Install Options
+
+### Local Skill Copy
+
+Copy a single variant into `~/.pi/agent/skills/<skill>/` or `.pi/skills/<skill>/` if you only want one skill.
+
+### Shared Skill Roots
+
+Pi can load from `~/.agents/skills/`, `.agents/skills/`, `.pi/skills/`, `~/.pi/agent/skills/`, package manifests, or settings-defined skill paths. That makes it possible to keep shared skill roots or repo-local installs.
+
+### Package Install
+
+The intended repo-level install flow is:
+
+```bash
+pi install -l /absolute/path/to/ai-coding-skills
+pi list
+```
+
+Package details are finalized by the packaging milestone and verified by `scripts/verify-pi-resources.sh` once that script is added in M5.
+
+## Extension Decision
+
+Pi extensions are powerful enough to add todo tracking, review orchestration helpers, or sub-agent-like flows, but they are not required for v1.
+
+Current v1 decision:
+
+- ship usable pi skill variants without extensions
+- document the extension opportunities explicitly
+- only add an extension later if it removes meaningful friction that documentation and helper scripts cannot address cleanly
+
+This section is intentionally provisional until M4, which records the final v1 extension assessment in this document.
+
+## Scope Notes
+
+- Pi variants are written for pi-native behavior, not as thin copies of Codex instructions.
+- The workflow-heavy skills assume pi can load referenced skills, but they do not assume pi has built-in equivalents for Codex-specific concepts like `update_plan`.
+- Shared helper scripts are documented with deterministic install paths so workflow instructions stay reproducible.