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

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

Package details are finalized by the packaging milestone and verified by `scripts/verify-pi-resources.sh` once that script is added in M5.

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

This section is intentionally provisional until M4, which records the final v1 extension assessment in this document.

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