Stefano Fiorini
120 lines
4.6 KiB
Markdown
120 lines
4.6 KiB
Markdown
# 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.
|
|
|
|
Current manifest shape:
|
|
|
|
- package name: `ai-coding-skills-pi`
|
|
- discovery keyword: `pi-package`
|
|
- `pi.skills`: the five `skills/<family>/pi` directories
|
|
- `files`: allowlisted to pi skill variants, pi docs, pi reviewer runtime helpers, and `scripts/verify-pi-resources.sh`
|
|
|
|
## 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
|
|
```
|
|
|
|
Verify the package surface before packaging or publishing:
|
|
|
|
```bash
|
|
./scripts/verify-pi-resources.sh
|
|
npm pack --dry-run --json
|
|
```
|
|
|
|
## 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](#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.
|