Stefano Fiorini
4.3 KiB
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:
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 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:
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
See Extension Assessment for the final v1 decision.
Extension Assessment
The upstream pi extension docs make three candidate areas realistic for this repo:
| Candidate | What It Could Add | V1 Decision | Rationale |
|---|---|---|---|
| Todo tracking extension | A pi-native task list or command for story state transitions while running create-plan, do-task, or implement-plan |
Defer | The current file-backed trackers already work across agents, so shipping an extension now would add maintenance cost without unlocking base usability. |
| Reviewer-loop extension | A pi-native wrapper around the reviewer-runtime flow, potentially exposing review runs as a command or tool instead of shell glue | Defer | The standalone run-review.sh helper is enough for v1, and deferring keeps the package surface smaller while usage patterns are still unknown. |
| Sub-agent orchestration extension | Higher-level automation for worktree setup, milestone stepping, or multi-run coordination | Defer | This is the highest-complexity option and most likely to overfit early assumptions before the pi variants have real usage feedback. |
Final V1 Decision
All extension candidates are deferred for v1.
The v1 package should ship:
- pi skill variants
- shared pi docs
- pi reviewer-runtime helper scripts
- verification tooling
It should not require any pi extension to be usable.
The threshold for a follow-up extension should be concrete, repeated friction that cannot be addressed cleanly with documentation, templates, or helper scripts alone.
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.