stefano
251148c3ff
## Summary - add repository-wide quality tooling and verification scaffolding, including CI workflows, pnpm workspace setup, ESLint/Prettier/markdown checks, and generated-output verification helpers - reorganize skill sources and generation flow by introducing canonical `_source` variants, generator/manifests, reusable helper abstractions, and shared web-automation/browser utilities - clean up and expand documentation so the root README flows into docs and skill docs, with clearer development, reviewer, installer, and workflow guidance ## Notable changes - docs flow and consistency cleanup across `README.md`, `docs/README.md`, and related docs - new scripts for `check`, docs verification, generated-file verification, shell portability, and safe directory replacement - refactors in Atlassian and web-automation skill runtimes to reduce duplication and centralize reusable code - changelog, development documentation, and CI surface updates ## Test Plan - [ ] `pnpm run check` - [ ] review generated/manifests and skill sync outputs - [ ] smoke-check docs flow from `README.md` to `docs/README.md` to skill docs ## Notes - this branch currently includes tracked `skills/web-automation/shared/node_modules` content that should be reviewed carefully as potentially noisy/accidental committed artifacts Co-authored-by: Stefano Fiorini <stefano.fiorini@firsthorizon.com> Reviewed-on: #1
166 lines
5.0 KiB
Markdown
166 lines
5.0 KiB
Markdown
# PI
|
|
|
|
## Purpose
|
|
|
|
This repo treats pi as a first-class target alongside Codex, Claude Code, Cursor, and OpenCode.
|
|
|
|
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
|
|
|
|
Edit the **canonical sources** under:
|
|
|
|
- `skills/atlassian/_source/pi/SKILL.md`
|
|
- `skills/create-plan/_source/pi/` (SKILL.md + templates)
|
|
- `skills/do-task/_source/pi/` (SKILL.md + templates)
|
|
- `skills/implement-plan/_source/pi/SKILL.md`
|
|
- `skills/web-automation/_source/pi/SKILL.md`
|
|
|
|
After editing a canonical source, run `pnpm run sync:pi` to regenerate all
|
|
agent-variant directories including `skills/<family>/pi/` and the package mirrors.
|
|
Do not edit the generated `skills/<family>/pi/` directories directly — they are
|
|
overwritten by the generator.
|
|
|
|
### Package Mirror
|
|
|
|
The package exposes:
|
|
|
|
- `pi-package/skills/atlassian/`
|
|
- `pi-package/skills/create-plan/`
|
|
- `pi-package/skills/do-task/`
|
|
- `pi-package/skills/implement-plan/`
|
|
- `pi-package/skills/web-automation/`
|
|
|
|
Those directories are generated from the canonical sources by
|
|
[`scripts/generate-skills.mjs`](../scripts/generate-skills.mjs)
|
|
(run via `pnpm run sync:pi`).
|
|
|
|
### Shared Setup Docs
|
|
|
|
Workflow-heavy Pi skills split their shared setup across two docs:
|
|
|
|
- [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 Install
|
|
|
|
The multi-client skill manager can guide Pi install/update/remove operations alongside the other supported clients:
|
|
|
|
```bash
|
|
./scripts/manage-skills.sh
|
|
node scripts/manage-skills.mjs --dry-run
|
|
```
|
|
|
|
The compatibility Pi package installer remains available for the focused Pi package path.
|
|
|
|
The user-facing Pi package install flow is the repo-owned installer script, not a raw `pi install` command.
|
|
|
|
Global install from a cloned checkout:
|
|
|
|
```bash
|
|
./scripts/install-pi-package.sh --global
|
|
```
|
|
|
|
Project-local install from a cloned checkout:
|
|
|
|
```bash
|
|
./scripts/install-pi-package.sh --local
|
|
```
|
|
|
|
Prerequisites for that one-liner:
|
|
|
|
- Node.js 20+
|
|
- `pi`
|
|
- either `pnpm` on `PATH`, or Node's bundled `corepack` support
|
|
|
|
The installer uses `pnpm` directly when available and falls back to `corepack pnpm` otherwise.
|
|
The root `package.json` pins the pnpm version so Corepack-backed installs resolve consistently.
|
|
|
|
That script:
|
|
|
|
- runs `pi install` in the chosen scope
|
|
- installs the nested runtime dependencies for `atlassian`
|
|
- installs the nested runtime dependencies for `web-automation`
|
|
- fetches the CloakBrowser binary for `web-automation`
|
|
- prints `pi list` at the end so the active install is visible immediately
|
|
|
|
For this cloned-checkout flow,
|
|
local checkout package install keeps the runtime in `pi-package/skills/<skill>/scripts`.
|
|
Pi loads the skills from the package mirror in this repo;
|
|
it does not copy them into `~/.pi/agent/skills/<skill>/` or `.pi/skills/<skill>/`
|
|
unless you do a manual copy install.
|
|
|
|
The package surface intentionally ships:
|
|
|
|
- `pi-package/skills/**`
|
|
- `skills/reviewer-runtime/pi/**`
|
|
- `docs/PI*.md`
|
|
- `scripts/install-pi-package.sh`
|
|
- `scripts/manage-skills.mjs` and `scripts/manage-skills.sh`
|
|
- `scripts/generate-skills.mjs`
|
|
- `scripts/verify-pi-resources.sh`
|
|
- `scripts/verify-pi-workflows.sh`
|
|
- `scripts/verify-reviewer-support.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
|
|
pnpm run sync:pi
|
|
npm run verify:pi
|
|
npm run verify:reviewers
|
|
npm pack --dry-run --json
|
|
```
|
|
|
|
The focused `scripts/install-pi-package.sh` installer intentionally does not run sync. It assumes
|
|
the checked-in `pi-package/skills/*` mirror is already current. The multi-client skill manager
|
|
plans a sync step before manual Pi skill-copy operations so manual installs use the current
|
|
package-facing mirror.
|
|
|
|
The verifier is responsible for catching:
|
|
|
|
- missing mirror directories
|
|
- source/mirror drift
|
|
- package metadata pointing at the wrong skill roots
|
|
- missing shared Pi docs
|
|
- missing user-facing installer wiring
|
|
|
|
## Extension Decision
|
|
|
|
Pi extensions are still optional for this repo.
|
|
|
|
Current v1 decision:
|
|
|
|
- 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
|