ai-coding-skills/docs/PI.md

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

Shared Setup Docs

Workflow-heavy Pi skills split their shared setup across two docs:

• PI-SUPERPOWERS.md for installing and verifying Obra Superpowers in Pi
• 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:

./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:

./scripts/install-pi-package.sh --global

Project-local install from a cloned checkout:

./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:

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:

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