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
5.0 KiB
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:
Layout
Source Of Truth
Edit the canonical sources under:
skills/atlassian/_source/pi/SKILL.mdskills/create-plan/_source/pi/(SKILL.md + templates)skills/do-task/_source/pi/(SKILL.md + templates)skills/implement-plan/_source/pi/SKILL.mdskills/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
(run via pnpm run sync:pi).
Shared Setup Docs
Workflow-heavy Pi skills split their shared setup across two docs:
- PI-SUPERPOWERS.md for installing and verifying Obra Superpowers in Pi
- 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:
./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:
./scripts/install-pi-package.sh --global
Project-local install from a cloned checkout:
./scripts/install-pi-package.sh --local
Prerequisites for that one-liner:
- Node.js 20+
pi- either
pnpmonPATH, or Node's bundledcorepacksupport
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 installin 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 listat 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*.mdscripts/install-pi-package.shscripts/manage-skills.mjsandscripts/manage-skills.shscripts/generate-skills.mjsscripts/verify-pi-resources.shscripts/verify-pi-workflows.shscripts/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:
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:
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