aspiers/ai-config / .agents/skills/managing-pi-packages
managing-pi-packages
VerifiedManages Pi packages across their lifecycle: discovers, audits, installs, upgrades, removes, enables, disables, filters, and configures extensions, skills, prompts, and themes from npm, Git, or local sources. Use before any Pi package install or upgrade, when reviewing available updates, changing package activation or configuration, or maintaining the package inventory.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 13.3 KB |
| references/auditing.md | markdown | 7.1 KB |
| references/reporting.md | markdown | 10.2 KB |
references/auditing.md
View on GitHub# Audit procedure for Pi packages
Load the `auditing-third-party-plugins` skill and read its procedure and
verdict references completely before using this file, unless the parent
skill's explicitly invoked maintainer-authored fork exception applies. That
skill owns the principles, the execution freeze, the review ledger, the
generic review checklist, verdicts and report contents. This file adds what
is specific to Pi: which packages to audit, how to obtain the payload Pi
would load, and what Pi itself executes.
## Scope
- If package names or sources were supplied, audit only those.
- A supplied package that is not installed is a fresh-install candidate. Audit
its complete executable payload and dependencies rather than inventing an
installed-to-target delta, and use install-specific wording in the report.
- Otherwise, audit every installed Pi package with an available upgrade. Do
not discover or recommend unrelated fresh installs by default.
- Include user and trusted project packages. Deduplicate the same package
identity, noting which scope wins.
- Treat npm specs containing a version and Git sources containing `@ref` as
pinned. Pi does not advance them automatically; report this if explicitly
requested, but do not invent an upgrade target.
- Local-path packages have no remote upgrade target. Report that when named.
## Pi commands frozen during an audit
On top of the shared execution freeze, do not run `pi update`, `pi install`
or `npx`, load candidate resources into Pi, or check out candidate Git code
into the installed worktree.
Create one unique temporary evidence directory and save a machine-readable
status file plus package-specific artifacts there. Use stable sanitized
package names. Run independent registry or fetch operations with bounded
concurrency (four workers is a reasonable default), but review each candidate
serially so findings are not mixed.
## 1. Discover candidates
Run `pi list` to obtain configured sources and managed install paths. Use the
installed `package.json` and Git checkout as local ground truth; a package or
extension manager's update badge is only a hint.
For each unpinned npm source:
1. Read `<managed-path>/package.json` to get the package name and installed
version.
2. Query the configured registry without installing:
```bash
npm view <package-name> version dist.integrity --json
```
3. It is a candidate only when the registry version differs from the
installed version.
For each unpinned Git source:
1. Record the installed commit, configured `origin`, current branch, and
tracked upstream. Do not assume the upstream belongs to `origin`.
2. Mirror Pi's target selection. Use the tracked branch only when it is an
`origin/<branch>` ref; otherwise query `origin`'s remote `HEAD` and flag
the mismatch. This matters for checkouts whose local branch tracks a fork:
```bash
installed=$(git -C <repo> rev-parse HEAD)
upstream=$(git -C <repo> rev-parse --abbrev-ref \
'@{upstream}' 2>/dev/null || true)
if [[ $upstream == origin/* ]]; then
ref="refs/heads/${upstream#origin/}"
else
ref=HEAD
fi
git -C <repo> fetch --quiet --no-tags origin "$ref"
target=$(git -C <repo> rev-parse FETCH_HEAD)
```
3. Classify ancestry as the shared procedure describes, with the installed
commit as the approved identity. A target Pi labels an update can still be
a downgrade.
4. It is a candidate only when the commits differ. Record the exact origin
URL, selected ref, target commit, and ancestry classification in the
evidence, but avoid exposing private URLs in the final report.
If discovery fails for one package, continue and report its evidence gap.
## 2. Inspect the payload Pi would load
Audit the payload Pi would load, not merely the repository's release page.
### npm packages
For a fresh install, query the exact version's metadata and fetch its published
`dist.tarball` URL into the evidence directory with `curl`. Verify the archive
against `dist.integrity`, list and extract it without running scripts, then
review every material shipped file and dependency. The absence of an installed
version is not a reason to use `npm diff` against an invented baseline.
For an upgrade, compare the two published tarballs directly:
```bash
npm diff \
--diff=<package-name>@<installed-version> \
--diff=<package-name>@<target-version> \
--diff-name-only
npm diff \
--diff=<package-name>@<installed-version> \
--diff=<package-name>@<target-version> \
-- package.json <changed-runtime-paths...>
```
Start with the file list and metadata. Do not request one enormous full diff
when selective path diffs will do. Group changed paths into package metadata,
runtime, generated/bundled, binaries, prompts/skills, docs, and tests; then
ask `npm diff` only for the next review group.
The published tarball is authoritative even when compiled output differs from
upstream source. If `npm diff` cannot retrieve both payloads, do not
substitute changelog claims for missing code.
### Git packages
For a fresh install, resolve the requested/default ref to an exact commit and
fetch a source archive or objects into the evidence directory without running
repository code. Inspect the complete package root, Pi resources, root and
workspace manifests, dependencies, lifecycle scripts, submodules, and
downloaded or generated artifacts.
For an upgrade, fetch objects without changing the installed checkout:
```bash
git -C <repo> fetch --quiet --no-tags origin refs/heads/<branch>
target=$(git -C <repo> rev-parse FETCH_HEAD)
git -C <repo> diff --no-ext-diff --no-textconv \
--name-status HEAD "$target"
git -C <repo> diff --no-ext-diff --no-textconv \
HEAD "$target" -- package.json <changed-runtime-paths...>
```
Start with `--name-status`, `--numstat`, package manifests, lockfiles, and
lifecycle scripts, then per-directory or per-file runtime diffs.
For monorepos, first determine which root and workspace manifests Pi
discovers, which resources are active, and which lifecycle script runs at the
managed checkout root. Do not audit every workspace equally when only a
subset can be loaded, but do include root install behavior and shared
dependencies.
## 3. Pi-specific checks
Follow the execution path from `package.json` and its `pi` manifest or
conventional resource directories. Extensions run with full user privileges;
skills, prompts and themes still change agent behaviour, so review them as
instructions. In addition to the shared checklist, look for:
- expanded tool behaviour, permissions, prompt or system instructions, hooks,
or automatic actions;
- peer-dependency and required Pi API or version changes;
- configuration migrations, changed defaults, renamed commands or tools, and
state-format changes.
Distinguish behaviour introduced by the candidate from lifecycle behaviour
that Pi re-runs during any Git checkout update: an unchanged `prepare` script
can still mutate the checkout or download artifacts.
## Pi verdict policy
Use the shared verdicts. Presume that keeping Pi packages current is
desirable after a complete audit, so `Upgrade with caution` must carry one of
the shared actions rather than act as a reason to defer by default.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |