diff --git a/.pi/INSTALL.md b/.pi/INSTALL.md new file mode 100644 index 000000000..f7dcd3119 --- /dev/null +++ b/.pi/INSTALL.md @@ -0,0 +1,58 @@ +# Installing Superpowers for Pi + +## Prerequisites + +- [Pi](https://github.com/mariozechner/pi-coding-agent) installed +- Git + +## Installation + +```bash +pi install https://github.com/obra/superpowers +``` + +Pi clones the repo and discovers all skills from the `skills/` directory automatically. + +### Alternative: Local Clone + +If you already have a local clone: + +```bash +pi install /path/to/superpowers +``` + +## Verify + +Check that the package appears: + +```bash +pi list +``` + +Then start pi and use `/skill:brainstorming` to confirm skills load. + +## Updating + +Update superpowers: + +```bash +pi update https://github.com/obra/superpowers +``` + +Or pull manually if using a local path: + +```bash +cd /path/to/superpowers && git pull +``` + +## Uninstalling + +```bash +pi remove https://github.com/obra/superpowers +``` + +Or, if installed from a local path: + +```bash +pi remove /path/to/superpowers +``` diff --git a/README.md b/README.md index 57a2d9b67..fe9bbcc12 100644 --- a/README.md +++ b/README.md @@ -71,6 +71,16 @@ Fetch and follow instructions from https://raw.githubusercontent.com/obra/superp **Detailed docs:** [docs/README.opencode.md](docs/README.opencode.md) +### Pi (experimental) + +```bash +pi install https://github.com/obra/superpowers +``` + +Pi discovers skills from the `skills/` directory automatically. No plugins or bootstrap required. + +**Detailed docs:** [docs/README.pi.md](docs/README.pi.md) + ### Verify Installation Start a new session in your chosen platform and ask for something that should trigger a skill (for example, "help me plan this feature" or "let's debug this issue"). The agent should automatically invoke the relevant superpowers skill. diff --git a/docs/README.pi.md b/docs/README.pi.md new file mode 100644 index 000000000..d1fa09145 --- /dev/null +++ b/docs/README.pi.md @@ -0,0 +1,197 @@ +# Superpowers for Pi + +> **Experimental.** Pi support is new. Report issues at . + +Complete guide for using Superpowers with [pi](https://github.com/mariozechner/pi-coding-agent). + +## Quick Install + +```bash +pi install https://github.com/obra/superpowers +``` + +Pi clones the repository and discovers all skills from the `skills/` directory automatically. No plugins, hooks, or bootstrap scripts required. + +## Installation Options + +### Prerequisites + +- [Pi](https://github.com/mariozechner/pi-coding-agent) installed +- Git + +### Option A: Git Package (recommended) + +```bash +pi install https://github.com/obra/superpowers +``` + +This clones to `~/.pi/agent/git/github.com/obra/superpowers/` and adds the package to `~/.pi/agent/settings.json`. + +### Option B: Local Path + +If you already have a local clone: + +```bash +pi install /path/to/superpowers +``` + +### Option C: Symlink Skills Only + +To add superpowers skills alongside an existing skill tree: + +```bash +ln -s /path/to/superpowers/skills ~/.pi/agent/skills/superpowers +``` + +> **Note:** Symlinked skills are not managed by `pi update` or shown by `pi list`. Update manually with `git pull`. + +### Verify Installation + +Check the package appears: + +```bash +pi list +``` + +Then start pi and type `/skill:brainstorming` to confirm skills load. + +## Usage + +### Finding Skills + +Pi lists available skills at startup in the `` section of the system prompt. The agent sees skill names and descriptions automatically. + +### Loading a Skill + +Three ways: + +1. **Automatic** — the agent reads a matching skill when a task fits its description +2. **Command** — type `/skill:brainstorming` (or any skill name) +3. **Direct** — the agent uses `read` on the SKILL.md file + +### Personal Skills + +Create skills in `~/.pi/agent/skills/`: + +```bash +mkdir -p ~/.pi/agent/skills/my-skill +``` + +Create `~/.pi/agent/skills/my-skill/SKILL.md`: + +```markdown +--- +name: my-skill +description: Use when [condition] - [what it does] +--- + +# My Skill + +[Your skill content here] +``` + +### Project Skills + +Create project-specific skills in `.pi/skills/` within your project. + +## Tool Mapping + +Skills are written for Claude Code. Pi equivalents: + +| Claude Code | Pi | Notes | +|---|---|---| +| `Skill` tool | `read` tool / `/skill:name` | Pi loads skill content via `read` | +| `TodoWrite` | — | No direct equivalent; use markdown checklists | +| `Task` with subagents | `subagent` tool | Pi's native delegation system | +| `Read` | `read` | Same | +| `Write` | `write` | Same | +| `Edit` | `edit` | Same | +| `Bash` | `bash` | Same | + +### Subagent Differences + +Claude Code's `Task` tool spawns a subagent with isolated context. Pi's `subagent` tool provides similar functionality with three modes: + +- **single** — one agent, one task (closest to Claude Code's `Task`) +- **parallel** — multiple independent tasks +- **chain** — sequential tasks where each receives prior output + +## Architecture + +Pi's package system discovers superpowers with zero integration code: + +1. `pi install` clones the repo +2. Pi scans the `skills/` directory (convention-based discovery) +3. Each `SKILL.md` frontmatter is parsed for name and description +4. Skills appear in the system prompt's `` XML +5. The agent loads full skill content on demand via `read` + +No plugins, hooks, bootstrap scripts, or CLI wrappers needed. + +### Skill Locations + +Pi discovers skills from multiple locations. On name collision, the first skill found wins. See [pi's skill documentation](https://github.com/mariozechner/pi-coding-agent/blob/main/docs/skills.md) for authoritative loading order. + +- **Global** — `~/.pi/agent/skills/` +- **Project** — `.pi/skills/` +- **Settings/Packages** — `skills` array and installed packages +- **CLI** — `--skill ` + +## Updating + +```bash +pi update +``` + +`pi update` updates all installed packages. To update only Superpowers: + +```bash +pi update https://github.com/obra/superpowers +``` + +For local path installs, pull manually: + +```bash +cd /path/to/superpowers && git pull +``` + +## Uninstalling + +```bash +pi remove https://github.com/obra/superpowers +``` + +For symlink installs: + +```bash +rm ~/.pi/agent/skills/superpowers +``` + +## Troubleshooting + +### Skills not found + +1. Check package is installed: `pi list` +2. Check skills exist: `ls ~/.pi/agent/git/github.com/obra/superpowers/skills/` +3. Verify each skill has a `SKILL.md` with valid frontmatter + +### Skill not triggering automatically + +Pi includes skill descriptions in the system prompt but relies on the model to decide when to load them. Use `/skill:name` to load explicitly. + +### Tool mapping confusion + +If the agent attempts a Claude Code tool that doesn't exist in pi, remind it of the mapping above. + +## Known Differences from Claude Code + +- **No `TodoWrite`** — Pi has no built-in task tracking tool. Skills that use `TodoWrite` checklists produce markdown checklists instead. +- **No hooks system** — Pi doesn't inject bootstrap content on session start. The `using-superpowers` skill triggers via its description in ``. +- **Skill loading** — Claude Code has a dedicated `Skill` tool. Pi uses `read` on SKILL.md files. Functionally equivalent, syntactically different. +- **Subagent model** — Pi's `subagent` tool supports single/parallel/chain modes. Claude Code's `Task` maps to single mode. + +## Getting Help + +- Report issues: +- Main documentation: +- Pi documentation: