# pi-superpowers

A process-discipline skills bundle for [pi](https://pi.dev) — the minimal terminal coding agent by Mario Zechner.

Inspired by Claude Code's `superpowers` plugin, this package ships a set of [Agent Skills](https://agentskills.io/specification) that nudge pi toward better engineering habits: brainstorming before building, structured debugging, TDD, written plans, verification before claiming "done", and isolated work via git worktrees.

Skills auto-load and the model picks the right one based on your request — no slash-commands required.

## Install

```bash
# From npm (once published)
pi install npm:pi-superpowers

# From git
pi install git:github.com/krone9/pi-superpowers

# From a local clone (for development)
pi install /absolute/path/to/pi-superpowers
```

Add `-l` to install into a project's `.pi/settings.json` instead of global.

Verify installation:

```bash
pi list
```

You should see the package listed; on next `pi` startup the skills appear in the header.

## What's included

Each skill is a markdown file with `name` + `description` frontmatter. Pi loads the descriptions into its system prompt at startup; full instructions are pulled in on-demand when the model decides a skill applies (or when you force one with `/skill:name`).

| Skill | When pi will reach for it |
|---|---|
| `using-superpowers` | Bootstrap — instructs the model to check skills before responding |
| `brainstorming` | New feature, vague goal, "what should we build…" |
| `writing-plans` | Multi-step changes that should be planned before coding |
| `test-driven-development` | Adding behavior that can be tested |
| `systematic-debugging` | Bug reports, unexpected behavior, regressions |
| `verification-before-completion` | Before claiming a task is done |
| `using-git-worktrees` | Isolated feature/experiment branches |
| `dispatching-parallel-agents` | 2+ independent tasks that can run concurrently |
| `writing-skills` | Authoring a new skill |

### Workflow skills (ported from Claude Code)

These mirror Andy's `~/.claude/skills/` set — process/logging/git helpers. Pi auto-loads them by description; you can also force-load any with `/skill:<name>`.

`audit-structure`, `brief`, `changes`, `commit`, `debt`, `dependencies`, `log`, `nextsteps`, `optimise`, `restart`, `review`, `rollback`, `rules`, `scaffold`, `security`, `staging`, `status`, `wrapup`

## Customise

Skills are plain markdown — fork, edit, or add your own under `skills/<your-skill>/SKILL.md`. The `name` field must match the parent directory.

## Caveat

Pi runs many providers. Forced skill-checking is *prompt persuasion*, not a tool the model is trained on. Capable models (Claude, GPT-4-class, Gemini Pro) follow the bootstrap reliably; smaller models may ignore it. The skills themselves work everywhere — only the always-check-first nudge depends on model strength.

## Credit

Concept and skill names adapted from the [Claude Code superpowers plugin](https://github.com/anthropics) by Anthropic. Reimplemented for pi's skills system. Not affiliated with Anthropic or pi.dev.

## License

MIT