# 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