Home/ai-coding-skills
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(pi): package warning-free skill mirror and docs

Browse Source
This commit is contained in:
Stefano Fiorini
2026-04-23 17:32:26 -05:00
parent 0456c51291
commit 3429dac894
51 changed files with 6703 additions and 155 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/PI-COMMON-REVIEWER.md
+69
View File
@@ -0,0 +1,69 @@
# PI COMMON REVIEWER
## Purpose
This document covers the shared reviewer-runtime helpers used by the Pi workflow skills.
It is intentionally separate from [PI-SUPERPOWERS.md](./PI-SUPERPOWERS.md). Superpowers are skill dependencies; reviewer-runtime is helper-script setup.
## Required Files
The workflow-heavy Pi skills expect these helper files from `skills/reviewer-runtime/pi/`:
- `run-review.sh`
- `notify-telegram.sh`
Supported install locations:
1. `.pi/skills/reviewer-runtime/pi/`
2. `~/.pi/agent/skills/reviewer-runtime/pi/`
## Verify An Existing Install
Project-local:
```bash
test -x .pi/skills/reviewer-runtime/pi/run-review.sh
test -x .pi/skills/reviewer-runtime/pi/notify-telegram.sh
```
Global:
```bash
test -x ~/.pi/agent/skills/reviewer-runtime/pi/run-review.sh
test -x ~/.pi/agent/skills/reviewer-runtime/pi/notify-telegram.sh
```
## Install The Common Reviewer Helpers
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
```
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
If you want the workflow skills to send completion messages, configure:
- `TELEGRAM_BOT_TOKEN`
- `TELEGRAM_CHAT_ID`
The Pi helper uses the same notification behavior documented in [TELEGRAM-NOTIFICATIONS.md](./TELEGRAM-NOTIFICATIONS.md).
## What This Doc Does Not Cover
- installing Obra Superpowers
- Pi package layout decisions
Those belong in [PI-SUPERPOWERS.md](./PI-SUPERPOWERS.md) and [PI.md](./PI.md).
docs/PI-RESEARCH.md
+3 -2
View File
@@ -32,7 +32,7 @@ Important discovery details from the skills docs:
- top-level `.md` files are loaded as skills in pi-native roots like `.pi/skills/`
- per the upstream skills docs, top-level `.md` files are ignored in `.agents/skills/`
Implication for this repo: `skills/<skill>/pi/SKILL.md` fits pi's recursive discovery model cleanly, both for local copies and for package-based installs.
Implication for this repo: `skills/<skill>/pi/SKILL.md` fits pi's recursive discovery model cleanly for source authoring and manual copies, but it is not clean for package-discovered installs because Pi requires the immediate parent directory of `SKILL.md` to match the skill frontmatter `name`.
### Package Support
@@ -46,7 +46,7 @@ Relevant package behaviors:
- installed pi packages can also ship `extensions/`, `prompts/`, and `themes/`
- when pi installs npm or git packages, it runs `npm install`
Implication for this repo: a single repo-level `package.json` is a viable v1 surface for shipping only the pi resources.
Implication for this repo: a single repo-level `package.json` is a viable v1 surface for shipping only the Pi resources, but the package-facing skill directories must be shaped like `<skill-name>/SKILL.md`. That means the repo should preserve `skills/<family>/pi/` for editing and expose a separate mirror such as `pi-package/skills/<skill-name>/` to Pi.
### Settings And Path Overrides
@@ -84,6 +84,7 @@ Implication for this repo:
## Decisions Derived From Research
- Use `skills/<skill>/pi/` for all five skill families.
- Package Pi skills through a separate mirror whose immediate directory names match the frontmatter `name` values.
- Publish shared pi guidance in repo docs instead of burying pi assumptions inside each skill.
- Use one repo-level pi package in v1.
- Assess extensions explicitly, but defer them unless they provide clear v1 value beyond documentation and helper scripts.
docs/PI-SUPERPOWERS.md
+72 -46
View File
@@ -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).
docs/PI.md
+70 -82
View File
@@ -2,9 +2,26 @@
## Purpose
This repo now treats pi as a first-class target alongside Codex, Claude Code, Cursor, and OpenCode.
This repo treats pi as a first-class target alongside Codex, Claude Code, Cursor, and OpenCode.
The pi support surface is built around the same family layout already used elsewhere in this repo:
The Pi support surface has two layers:
- editable source variants in `skills/<family>/pi/`
- a package-facing mirror in `pi-package/skills/<skill>/`
That split is intentional. Pi requires the immediate parent directory of `SKILL.md` to match the skill's frontmatter `name`, so the package cannot point directly at `skills/<family>/pi/`.
Related docs:
- [PI-RESEARCH.md](./PI-RESEARCH.md)
- [PI-SUPERPOWERS.md](./PI-SUPERPOWERS.md)
- [PI-COMMON-REVIEWER.md](./PI-COMMON-REVIEWER.md)
## Layout
### Source Of Truth
Author Pi variants under:
- `skills/atlassian/pi/`
- `skills/create-plan/pi/`
@@ -12,108 +29,79 @@ The pi support surface is built around the same family layout already used elsew
- `skills/implement-plan/pi/`
- `skills/web-automation/pi/`
Shared pi guidance lives in:
These are the directories to edit by hand.
- [PI-RESEARCH.md](./PI-RESEARCH.md)
- [PI-SUPERPOWERS.md](./PI-SUPERPOWERS.md)
### Package Mirror
## Support Strategy
The package exposes:
### Variant Layout
- `pi-package/skills/atlassian/`
- `pi-package/skills/create-plan/`
- `pi-package/skills/do-task/`
- `pi-package/skills/implement-plan/`
- `pi-package/skills/web-automation/`
Each skill family gets a dedicated `pi` variant instead of a pointer-only shim. That keeps pi-specific wording, installation paths, and workflow constraints reviewable in-repo.
Those directories are generated from the source variants by [`scripts/sync-pi-package-skills.sh`](../scripts/sync-pi-package-skills.sh).
### Shared Workflow Guidance
### Shared Setup Docs
The workflow-heavy skills (`create-plan`, `do-task`, `implement-plan`) refer to [PI-SUPERPOWERS.md](./PI-SUPERPOWERS.md) for:
Workflow-heavy Pi skills split their shared setup across two docs:
- exposing Obra Superpowers to pi
- installing the shared reviewer runtime for pi
- Telegram notification setup expectations
- [PI-SUPERPOWERS.md](./PI-SUPERPOWERS.md) for installing and verifying Obra Superpowers in Pi
- [PI-COMMON-REVIEWER.md](./PI-COMMON-REVIEWER.md) for installing and verifying the shared reviewer-runtime helpers
### Package Strategy
## Package Install
V1 uses one repo-level pi package rather than per-skill packages. The package surface is intentionally narrow:
- only pi skill variants
- shared pi docs
- pi reviewer-runtime helper sources
- a verification script
The package metadata and allowlist live at repo root so `pi install -l /absolute/path/to/ai-coding-skills` works without extra wrapping.
Current manifest shape:
- package name: `ai-coding-skills-pi`
- discovery keyword: `pi-package`
- `pi.skills`: the five `skills/<family>/pi` directories
- `files`: allowlisted to pi skill variants, pi docs, pi reviewer runtime helpers, and `scripts/verify-pi-resources.sh`
## Install Options
### Local Skill Copy
Copy a single variant into `~/.pi/agent/skills/<skill>/` or `.pi/skills/<skill>/` if you only want one skill.
### Shared Skill Roots
Pi can load from `~/.agents/skills/`, `.agents/skills/`, `.pi/skills/`, `~/.pi/agent/skills/`, package manifests, or settings-defined skill paths. That makes it possible to keep shared skill roots or repo-local installs.
### Package Install
The intended repo-level install flow is:
The repo-level package manifest lives at root so Pi can install directly from this checkout:
```bash
pi install -l /absolute/path/to/ai-coding-skills
pi install -l "$(pwd)"
pi list
```
Verify the package surface before packaging or publishing:
The package surface intentionally ships:
- `pi-package/skills/**`
- `skills/reviewer-runtime/pi/**`
- `docs/PI*.md`
- `scripts/verify-pi-resources.sh`
It intentionally does not ship `skills/<family>/pi/**` as package-discovered skills.
## Single-Skill Copy Install
If you only want one Pi skill without installing the whole package, copy from the package-facing mirror into a Pi skill root:
```bash
mkdir -p .pi/skills/create-plan
cp -R pi-package/skills/create-plan/* .pi/skills/create-plan/
```
Global installs use `~/.pi/agent/skills/<skill>/` instead of `.pi/skills/<skill>/`.
## Maintenance Workflow
When a source Pi variant changes:
```bash
./scripts/sync-pi-package-skills.sh
./scripts/verify-pi-resources.sh
npm pack --dry-run --json
```
The verifier is responsible for catching:
- missing mirror directories
- source/mirror drift
- package metadata pointing at the wrong skill roots
- missing shared Pi docs
## Extension Decision
Pi extensions are powerful enough to add todo tracking, review orchestration helpers, or sub-agent-like flows, but they are not required for v1.
Pi extensions are still optional for this repo.
Current v1 decision:
- ship usable pi skill variants without extensions
- document the extension opportunities explicitly
- only add an extension later if it removes meaningful friction that documentation and helper scripts cannot address cleanly
See [Extension Assessment](#extension-assessment) for the final v1 decision.
## Extension Assessment
The upstream pi extension docs make three candidate areas realistic for this repo:
| Candidate | What It Could Add | V1 Decision | Rationale |
|-----------|-------------------|-------------|-----------|
| Todo tracking extension | A pi-native task list or command for story state transitions while running `create-plan`, `do-task`, or `implement-plan` | Defer | The current file-backed trackers already work across agents, so shipping an extension now would add maintenance cost without unlocking base usability. |
| Reviewer-loop extension | A pi-native wrapper around the reviewer-runtime flow, potentially exposing review runs as a command or tool instead of shell glue | Defer | The standalone `run-review.sh` helper is enough for v1, and deferring keeps the package surface smaller while usage patterns are still unknown. |
| Sub-agent orchestration extension | Higher-level automation for worktree setup, milestone stepping, or multi-run coordination | Defer | This is the highest-complexity option and most likely to overfit early assumptions before the pi variants have real usage feedback. |
### Final V1 Decision
All extension candidates are deferred for v1.
The v1 package should ship:
- pi skill variants
- shared pi docs
- pi reviewer-runtime helper scripts
- verification tooling
It should not require any pi extension to be usable.
The threshold for a follow-up extension should be concrete, repeated friction that cannot be addressed cleanly with documentation, templates, or helper scripts alone.
## Scope Notes
- Pi variants are written for pi-native behavior, not as thin copies of Codex instructions.
- The workflow-heavy skills assume pi can load referenced skills, but they do not assume pi has built-in equivalents for Codex-specific concepts like `update_plan`.
- Shared helper scripts are documented with deterministic install paths so workflow instructions stay reproducible.
- ship usable Pi skills without extensions
- keep the package focused on skills, docs, and helpers
- revisit extensions only when documentation and helper scripts stop being enough
docs/README.md
+3 -2
View File
@@ -8,9 +8,10 @@ This directory contains user-facing docs for each skill.
- [CREATE-PLAN.md](./CREATE-PLAN.md) — Includes requirements, install, verification, and execution workflow for create-plan.
- [DO-TASK.md](./DO-TASK.md) — Single-prompt end-to-end execution with dual reviewer loops (plan + implementation), TDD-first, single task commit. Sibling of create-plan/implement-plan scoped to ad-hoc tasks.
- [IMPLEMENT-PLAN.md](./IMPLEMENT-PLAN.md) — Includes requirements, install, verification, and milestone review workflow for implement-plan.
- [PI.md](./PI.md) — Pi support overview, variant strategy, package direction, and extension decision.
- [PI.md](./PI.md) — Pi support overview, source-vs-package layout, install flow, and extension decision.
- [PI-RESEARCH.md](./PI-RESEARCH.md) — Source-backed pi findings that inform the repo's pi variants and packaging choices.
- [PI-SUPERPOWERS.md](./PI-SUPERPOWERS.md) — Shared Obra Superpowers and reviewer-runtime setup for pi workflow skills.
- [PI-SUPERPOWERS.md](./PI-SUPERPOWERS.md) — How to install or verify Obra Superpowers for Pi.
- [PI-COMMON-REVIEWER.md](./PI-COMMON-REVIEWER.md) — How to install or verify the shared reviewer-runtime helpers for Pi workflow skills.
- [TELEGRAM-NOTIFICATIONS.md](./TELEGRAM-NOTIFICATIONS.md) — Shared Telegram notification setup used by reviewer-driven skills.
- [WEB-AUTOMATION.md](./WEB-AUTOMATION.md) — Includes requirements, install, dependency verification, and usage examples for web-automation.