Stefano Fiorini
108 lines
2.8 KiB
Markdown
108 lines
2.8 KiB
Markdown
# PI
|
|
|
|
## Purpose
|
|
|
|
This repo treats pi as a first-class target alongside Codex, Claude Code, Cursor, and OpenCode.
|
|
|
|
The Pi support surface has two layers:
|
|
|
|
- editable source variants in `skills/<family>/pi/`
|
|
- a package-facing mirror in `pi-package/skills/<skill>/`
|
|
|
|
That split is intentional. Pi requires the immediate parent directory of `SKILL.md` to match the skill's frontmatter `name`, so the package cannot point directly at `skills/<family>/pi/`.
|
|
|
|
Related docs:
|
|
|
|
- [PI-RESEARCH.md](./PI-RESEARCH.md)
|
|
- [PI-SUPERPOWERS.md](./PI-SUPERPOWERS.md)
|
|
- [PI-COMMON-REVIEWER.md](./PI-COMMON-REVIEWER.md)
|
|
|
|
## Layout
|
|
|
|
### Source Of Truth
|
|
|
|
Author Pi variants under:
|
|
|
|
- `skills/atlassian/pi/`
|
|
- `skills/create-plan/pi/`
|
|
- `skills/do-task/pi/`
|
|
- `skills/implement-plan/pi/`
|
|
- `skills/web-automation/pi/`
|
|
|
|
These are the directories to edit by hand.
|
|
|
|
### Package Mirror
|
|
|
|
The package exposes:
|
|
|
|
- `pi-package/skills/atlassian/`
|
|
- `pi-package/skills/create-plan/`
|
|
- `pi-package/skills/do-task/`
|
|
- `pi-package/skills/implement-plan/`
|
|
- `pi-package/skills/web-automation/`
|
|
|
|
Those directories are generated from the source variants by [`scripts/sync-pi-package-skills.sh`](../scripts/sync-pi-package-skills.sh).
|
|
|
|
### Shared Setup Docs
|
|
|
|
Workflow-heavy Pi skills split their shared setup across two docs:
|
|
|
|
- [PI-SUPERPOWERS.md](./PI-SUPERPOWERS.md) for installing and verifying Obra Superpowers in Pi
|
|
- [PI-COMMON-REVIEWER.md](./PI-COMMON-REVIEWER.md) for installing and verifying the shared reviewer-runtime helpers
|
|
|
|
## Package Install
|
|
|
|
The repo-level package manifest lives at root so Pi can install directly from this checkout:
|
|
|
|
```bash
|
|
pi install -l "$(pwd)"
|
|
pi list
|
|
```
|
|
|
|
The package surface intentionally ships:
|
|
|
|
- `pi-package/skills/**`
|
|
- `skills/reviewer-runtime/pi/**`
|
|
- `docs/PI*.md`
|
|
- `scripts/verify-pi-resources.sh`
|
|
|
|
It intentionally does not ship `skills/<family>/pi/**` as package-discovered skills.
|
|
|
|
## Single-Skill Copy Install
|
|
|
|
If you only want one Pi skill without installing the whole package, copy from the package-facing mirror into a Pi skill root:
|
|
|
|
```bash
|
|
mkdir -p .pi/skills/create-plan
|
|
cp -R pi-package/skills/create-plan/* .pi/skills/create-plan/
|
|
```
|
|
|
|
Global installs use `~/.pi/agent/skills/<skill>/` instead of `.pi/skills/<skill>/`.
|
|
|
|
## Maintenance Workflow
|
|
|
|
When a source Pi variant changes:
|
|
|
|
```bash
|
|
./scripts/sync-pi-package-skills.sh
|
|
./scripts/verify-pi-resources.sh
|
|
npm pack --dry-run --json
|
|
```
|
|
|
|
The verifier is responsible for catching:
|
|
|
|
- missing mirror directories
|
|
- source/mirror drift
|
|
- package metadata pointing at the wrong skill roots
|
|
- missing shared Pi docs
|
|
|
|
## Extension Decision
|
|
|
|
Pi extensions are still optional for this repo.
|
|
|
|
Current v1 decision:
|
|
|
|
- ship usable Pi skills without extensions
|
|
- keep the package focused on skills, docs, and helpers
|
|
- revisit extensions only when documentation and helper scripts stop being enough
|