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.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