Stefano Fiorini
161 lines
4.7 KiB
Markdown
161 lines
4.7 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 multi-client skill manager can guide Pi install/update/remove operations alongside the other supported clients:
|
|
|
|
```bash
|
|
./scripts/manage-skills.sh
|
|
node scripts/manage-skills.mjs --dry-run
|
|
```
|
|
|
|
The compatibility Pi package installer remains available for the focused Pi package path.
|
|
|
|
The user-facing Pi package install flow is the repo-owned installer script, not a raw `pi install` command.
|
|
|
|
Global install from a cloned checkout:
|
|
|
|
```bash
|
|
./scripts/install-pi-package.sh --global
|
|
```
|
|
|
|
Project-local install from a cloned checkout:
|
|
|
|
```bash
|
|
./scripts/install-pi-package.sh --local
|
|
```
|
|
|
|
Prerequisites for that one-liner:
|
|
|
|
- Node.js 20+
|
|
- `pi`
|
|
- either `pnpm` on `PATH`, or Node's bundled `corepack` support
|
|
|
|
The installer uses `pnpm` directly when available and falls back to `corepack pnpm` otherwise.
|
|
The root `package.json` pins the pnpm version so Corepack-backed installs resolve consistently.
|
|
|
|
That script:
|
|
|
|
- runs `pi install` in the chosen scope
|
|
- installs the nested runtime dependencies for `atlassian`
|
|
- installs the nested runtime dependencies for `web-automation`
|
|
- fetches the CloakBrowser binary for `web-automation`
|
|
- prints `pi list` at the end so the active install is visible immediately
|
|
|
|
For this cloned-checkout flow,
|
|
local checkout package install keeps the runtime in `pi-package/skills/<skill>/scripts`.
|
|
Pi loads the skills from the package mirror in this repo;
|
|
it does not copy them into `~/.pi/agent/skills/<skill>/` or `.pi/skills/<skill>/`
|
|
unless you do a manual copy install.
|
|
|
|
The package surface intentionally ships:
|
|
|
|
- `pi-package/skills/**`
|
|
- `skills/reviewer-runtime/pi/**`
|
|
- `docs/PI*.md`
|
|
- `scripts/install-pi-package.sh`
|
|
- `scripts/manage-skills.mjs` and `scripts/manage-skills.sh`
|
|
- `scripts/sync-pi-package-skills.sh`
|
|
- `scripts/verify-pi-resources.sh`
|
|
- `scripts/verify-pi-workflows.sh`
|
|
- `scripts/verify-reviewer-support.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
|
|
npm run verify:pi
|
|
npm run verify:reviewers
|
|
npm pack --dry-run --json
|
|
```
|
|
|
|
The focused `scripts/install-pi-package.sh` installer intentionally does not run sync. It assumes
|
|
the checked-in `pi-package/skills/*` mirror is already current. The multi-client skill manager
|
|
plans a sync step before manual Pi skill-copy operations so manual installs use the current
|
|
package-facing mirror.
|
|
|
|
The verifier is responsible for catching:
|
|
|
|
- missing mirror directories
|
|
- source/mirror drift
|
|
- package metadata pointing at the wrong skill roots
|
|
- missing shared Pi docs
|
|
- missing user-facing installer wiring
|
|
|
|
## 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
|