# 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