fix(pi): package warning-free skill mirror and docs
This commit is contained in:
Stefano Fiorini
+72
-46
@@ -2,30 +2,76 @@
|
||||
|
||||
## Purpose
|
||||
|
||||
The pi workflow variants in this repo depend on two shared pieces of setup:
|
||||
This document is only about making Obra Superpowers visible to Pi.
|
||||
|
||||
- Obra Superpowers skills
|
||||
- reviewer-runtime helper scripts
|
||||
If you need the shared reviewer helpers (`run-review.sh`, `notify-telegram.sh`), use [PI-COMMON-REVIEWER.md](./PI-COMMON-REVIEWER.md) instead.
|
||||
|
||||
This guide documents how to make both available to pi without inventing skill-specific setup instructions in three different workflow docs.
|
||||
## What Pi Needs
|
||||
|
||||
## Superpowers Setup
|
||||
The workflow-heavy Pi skills depend on Superpowers such as:
|
||||
|
||||
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.
|
||||
- `brainstorming`
|
||||
- `writing-plans`
|
||||
- `executing-plans`
|
||||
- `test-driven-development`
|
||||
- `verification-before-completion`
|
||||
- `finishing-a-development-branch`
|
||||
- `using-git-worktrees`
|
||||
|
||||
### Option 1: Reuse `~/.agents/skills/`
|
||||
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.
|
||||
|
||||
If you already expose Superpowers through a shared root such as:
|
||||
## Verify An Existing Install
|
||||
|
||||
If you think Superpowers may already be installed, check the common shared-root setup first:
|
||||
|
||||
```bash
|
||||
~/.agents/skills/superpowers -> ~/.codex/superpowers/skills
|
||||
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
|
||||
```
|
||||
|
||||
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.
|
||||
If those pass, Pi can usually reuse the same install directly.
|
||||
|
||||
### Option 2: Add An Explicit Pi Settings Entry
|
||||
To verify a Pi-native install instead:
|
||||
|
||||
If you want pi to load a different path, add it in either `~/.pi/agent/settings.json` or `.pi/settings.json`:
|
||||
```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
|
||||
{
|
||||
@@ -36,49 +82,29 @@ If you want pi to load a different path, add it in either `~/.pi/agent/settings.
|
||||
}
|
||||
```
|
||||
|
||||
Use this when the shared `~/.agents/skills/` root is missing or when you want a pi-specific override.
|
||||
## Post-Install Verification
|
||||
|
||||
## Reviewer Runtime Setup
|
||||
After any install path, verify the specific skills your workflow needs.
|
||||
|
||||
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:
|
||||
Planning-focused check:
|
||||
|
||||
```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
|
||||
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
|
||||
```
|
||||
|
||||
Example project-local install:
|
||||
Execution-focused check:
|
||||
|
||||
```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
|
||||
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
|
||||
```
|
||||
|
||||
## Telegram Notifications
|
||||
## What This Doc Does Not Cover
|
||||
|
||||
If you want pi workflow skills to send completion messages, configure:
|
||||
- reviewer-runtime helper installation
|
||||
- Telegram helper installation
|
||||
- package layout or Pi package installation
|
||||
|
||||
- `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.
|
||||
Those belong in [PI-COMMON-REVIEWER.md](./PI-COMMON-REVIEWER.md) and [PI.md](./PI.md).
|
||||
|
||||
Reference in New Issue
Block a user