# PI SUPERPOWERS

## Purpose

This document is only about making Obra Superpowers visible to Pi.

If you need the shared reviewer helpers (`run-review.sh`, `notify-telegram.sh`), use [PI-COMMON-REVIEWER.md](./PI-COMMON-REVIEWER.md) instead.

## What Pi Needs

The workflow-heavy Pi skills depend on Superpowers such as:

- `brainstorming`
- `writing-plans`
- `executing-plans`
- `test-driven-development`
- `verification-before-completion`
- `finishing-a-development-branch`
- `using-git-worktrees`

Pi can discover them from shared roots like `~/.agents/skills/`, Pi-native roots like `~/.pi/agent/skills/` or `.pi/skills/`, or settings-defined skill directories.

## Verify An Existing Install

If you think Superpowers may already be installed, check the common shared-root setup first:

```bash
test -L ~/.agents/skills/superpowers
test -f ~/.agents/skills/superpowers/brainstorming/SKILL.md
test -f ~/.agents/skills/superpowers/test-driven-development/SKILL.md
test -f ~/.agents/skills/superpowers/verification-before-completion/SKILL.md
test -f ~/.agents/skills/superpowers/finishing-a-development-branch/SKILL.md
```

If those pass, Pi can usually reuse the same install directly.

To verify a Pi-native install instead:

```bash
test -f ~/.pi/agent/skills/superpowers/brainstorming/SKILL.md || test -f .pi/skills/superpowers/brainstorming/SKILL.md
```

## Install Option 1: Reuse A Shared Skills Root

If you already have Superpowers available for another harness, the simplest Pi setup is to expose that same tree through `~/.agents/skills/`.

Example:

```bash
mkdir -p ~/.agents/skills
ln -s ~/.codex/superpowers/skills ~/.agents/skills/superpowers
```

Re-run the verification checks above after creating the symlink.

## Install Option 2: Pi-Native Symlink Or Copy

If you do not want to use `~/.agents/skills/`, point Pi at a checked-out Superpowers tree directly.

Global Pi install:

```bash
mkdir -p ~/.pi/agent/skills
ln -s /absolute/path/to/obra/superpowers/skills ~/.pi/agent/skills/superpowers
```

Project-local Pi install:

```bash
mkdir -p .pi/skills
ln -s /absolute/path/to/obra/superpowers/skills .pi/skills/superpowers
```

If you prefer a settings-based path instead of a symlink, add it to either `~/.pi/agent/settings.json` or `.pi/settings.json`:

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

## Post-Install Verification

After any install path, verify the specific skills your workflow needs.

Planning-focused check:

```bash
test -f ~/.agents/skills/superpowers/brainstorming/SKILL.md || test -f ~/.pi/agent/skills/superpowers/brainstorming/SKILL.md || test -f .pi/skills/superpowers/brainstorming/SKILL.md
test -f ~/.agents/skills/superpowers/writing-plans/SKILL.md || test -f ~/.pi/agent/skills/superpowers/writing-plans/SKILL.md || test -f .pi/skills/superpowers/writing-plans/SKILL.md
```

Execution-focused check:

```bash
test -f ~/.agents/skills/superpowers/test-driven-development/SKILL.md || test -f ~/.pi/agent/skills/superpowers/test-driven-development/SKILL.md || test -f .pi/skills/superpowers/test-driven-development/SKILL.md
test -f ~/.agents/skills/superpowers/verification-before-completion/SKILL.md || test -f ~/.pi/agent/skills/superpowers/verification-before-completion/SKILL.md || test -f .pi/skills/superpowers/verification-before-completion/SKILL.md
test -f ~/.agents/skills/superpowers/finishing-a-development-branch/SKILL.md || test -f ~/.pi/agent/skills/superpowers/finishing-a-development-branch/SKILL.md || test -f .pi/skills/superpowers/finishing-a-development-branch/SKILL.md
```

## What This Doc Does Not Cover

- reviewer-runtime helper installation
- Telegram helper installation
- package layout or Pi package installation

Those belong in [PI-COMMON-REVIEWER.md](./PI-COMMON-REVIEWER.md) and [PI.md](./PI.md).