# PI SUPERPOWERS

## Purpose

The pi workflow variants in this repo depend on two shared pieces of setup:

- Obra Superpowers skills
- reviewer-runtime helper scripts

This guide documents how to make both available to pi without inventing skill-specific setup instructions in three different workflow docs.

## Superpowers Setup

Pi can load skills from `~/.pi/agent/skills/`, `~/.agents/skills/`, `.pi/skills/`, `.agents/skills/`, package manifests, and settings-defined skill paths. Because of that, there are two supported ways to expose Obra Superpowers to pi.

### Option 1: Reuse `~/.agents/skills/`

If you already expose Superpowers through a shared root such as:

```bash
~/.agents/skills/superpowers -> ~/.codex/superpowers/skills
```

pi can discover those skill directories directly. This is only an example path, not a requirement; any shared skill root that pi can read is fine. It is simply the easiest path when Codex and pi share the same machine.

### Option 2: Add An Explicit Pi Settings Entry

If you want pi to load a different path, add it in either `~/.pi/agent/settings.json` or `.pi/settings.json`:

```json
{
  "skills": [
    "~/.agents/skills",
    "/absolute/path/to/obra/superpowers/skills"
  ]
}
```

Use this when the shared `~/.agents/skills/` root is missing or when you want a pi-specific override.

## Reviewer Runtime Setup

The workflow-heavy pi variants expect the helper scripts from `skills/reviewer-runtime/pi/` to be installed in one of these locations:

1. `.pi/skills/reviewer-runtime/pi/`
2. `~/.pi/agent/skills/reviewer-runtime/pi/`

Supported helper files:

- `run-review.sh`
- `notify-telegram.sh`

Example global install:

```bash
mkdir -p ~/.pi/agent/skills/reviewer-runtime/pi
cp -R skills/reviewer-runtime/pi/* ~/.pi/agent/skills/reviewer-runtime/pi/
chmod +x ~/.pi/agent/skills/reviewer-runtime/pi/*.sh
```

Example project-local install:

```bash
mkdir -p .pi/skills/reviewer-runtime/pi
cp -R skills/reviewer-runtime/pi/* .pi/skills/reviewer-runtime/pi/
chmod +x .pi/skills/reviewer-runtime/pi/*.sh
```

## Telegram Notifications

If you want pi workflow skills to send completion messages, configure:

- `TELEGRAM_BOT_TOKEN`
- `TELEGRAM_CHAT_ID`

The shared notification behavior matches the existing repo guidance in [TELEGRAM-NOTIFICATIONS.md](./TELEGRAM-NOTIFICATIONS.md).

## What This Does Not Assume

- pi does not automatically provide Codex `update_plan` semantics
- pi does not automatically provide plan mode or worktree workflows
- pi does not require extensions for the base workflow skills in this repo

The pi variants must therefore spell out their workflow steps directly and only rely on dependencies documented here.