# 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.