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.
Managing Pi Packages
Manage Pi packages safely from discovery through verification and durable recording. Treat auditing as the default gate within package management. Skip it only for the maintainer-authored fork exception below or when the user explicitly waives the audit for the named package operation.
Pi calls these packages because one source can provide extensions, skills, prompt templates, and themes. All can influence agent behavior; extensions run with full user privileges.
Required references
- Read the audit procedure completely before every
install or upgrade unless the operation qualifies for the
maintainer-authored fork exception below or the user explicitly waives the
audit for that operation, and whenever the user requests an audit. It
sends you to the
auditing-third-party-pluginsskill for the non-execution rules, completeness standard, dependency review and verdict definitions, and adds Pi's candidate discovery and npm/Git evidence workflow. - Read reporting and package notes completely before finalizing an audit or any package state change, including a change made under an explicit audit waiver. It defines persistent reports and the conditional package-inventory update.
Do not partially sample a reference and infer the remainder.
Authority and intent
- If the user asks only for an audit, do not install, upgrade, remove, enable, disable, or reconfigure anything.
- If the user explicitly asks to audit and then apply a change, audit first and proceed only when the verdict's stated action permits it and all named prerequisites are met.
- If the user explicitly says that an audit is unnecessary, should be skipped, or that the named package should be installed/updated without one, treat that as a one-operation audit waiver. Do not infer a waiver from urgency or a generic request to install. Scope it to the named package, source, and operation; it creates no precedent for later changes.
- Under an explicit waiver, do not perform a full payload/dependency audit or
issue an audit verdict/report. Still inventory the current state, identify
and pin the target, use Pi's package manager, verify loading and unrelated
state, document rollback, and record
NOT AUDITED — explicit user overridein package notes. State plainly that unreviewed package code was executed. Do not install,Do not upgrade, andInconclusiveaudit verdicts block application. Obtain a new explicit decision before overriding one of those results; record that decision separately from a pre-audit waiver.- Preserve unrelated settings and package state. Never broaden package filters or activate additional resources merely because they share a package.
Maintainer-authored fork exception
⚠️ AUTHOR-SPECIFIC: Do not perform a full package audit or generate an audit verdict/report when the configured source is one of the author's own verified forks. No separate opt-out statement is required: the fork source itself invokes this exception. Absent an explicit user waiver, full audits remain required for canonical upstream repositories and other third-party sources.
For an author-owned fork change, still:
- verify the configured fork URL, branch/ref, and resolved commit;
- inspect manifests and changed-file metadata for unexpected third-party, generated, binary, dependency, or lifecycle payloads;
- audit any unexpected material payload that is not part of the author's branch work;
- validate installation, resource scope, tests, and rollback after the source change; and
- record the resolved commit because a mutable branch can move later.
This exception applies only to verified author-owned fork sources; it does not make arbitrary code safe merely because it is hosted in a fork.
⚠️ AUTHOR-SPECIFIC — BRANCH PIN POLICY: When the author configures one of their own extension forks as a Pi package, pin the source to a named branch, not to a commit SHA. If one source branch contains every required fork change, pin that branch directly. If required changes live on multiple branches, load and follow the
git-branch-mixerskill: configure a mix whose base is the canonical upstream branch, mix the required source branches down toworking, test the mixed result, pushworkingto the author's fork, and pin the Pi package toworking. The author explicitly permits publishing that mixdown branch for this package-integration purpose; do not useworkingas an upstream pull-request branch—submit each independent source branch separately. A branch pin intentionally letspi update --extensionsreconcile later fixes without editing settings after every commit. Still record the mix inputs and exact installed commit during each audit or update so provenance and rollback remain reproducible. This mutable-branch policy is specific to the author's reviewed forks; do not generalize it to third-party package sources.
Development forks
Pi-managed Git checkouts are runtime installation state, not development
working trees. Do not create feature branches, change remotes, or develop code
inside ~/.pi/agent/git/; keep a separately managed development checkout.
Changing the package source used by Pi is a distinct, audited source change and
must not happen merely because development work was requested.
⚠️ AUTHOR-SPECIFIC: On the author's machines, place a third-party development checkout at
~/.GIT/3rd-party/<repository-name>and register it in~/.config/mr/groups.d/26-AIusing themr-config-entriesskill. Other users must substitute their own source-tree and repository-manager conventions.
Keep the Pi-managed checkout unchanged until a separately requested and audited installation or source-switch test is ready.
Lifecycle workflow
1. Inventory effective state
- Run
pi listand inspect the applicable global and trusted projectsettings.jsonfiles. - Establish package identity, source, scope, pin/ref, managed path, installed version or commit, resource filters, and extension-manager disabled state.
- Read the installed
package.jsonand Pi manifest as local ground truth. - Distinguish
Active,Inactive,Disabled, andPartially disabled.
Project scope wins over global scope unless project configuration explicitly acts as a delta. Avoid reporting the same package twice.
2. Classify the operation
- Discover/list: read-only inventory; no payload audit unless the user asks for recommendations or safety assessment.
- Fresh install: audit the complete candidate payload and material runtime dependencies unless the user explicitly waived this audit.
- Upgrade/downgrade/source change: audit the exact installed-to-target delta, provenance, ancestry, dependencies, and lifecycle behavior unless the user explicitly waived this audit.
- Remove: inspect package-owned and user-owned state first; identify what settings, data, hooks, or generated files survive removal.
- Enable/disable/filter/configure: inspect the currently installed code and docs that consume the setting; change only the requested resource or key.
3. Apply an approved change
Use Pi's package manager rather than direct npm or Git mutation:
pi install npm:<package>@<version>
pi install git:<host>/<owner>/<repo>@<ref>
pi update npm:<package>
pi remove npm:<package>
- Install the exact audited npm version or Git ref. Under an explicit audit waiver, resolve the target immediately before mutation and pin that exact version/ref unless the user requests an unpinned policy. Pinning is intentional for a fresh install.
- Immediately before an unpinned audited update, re-query the target and stop if its version, commit, or integrity differs from the audited candidate.
- For global changes, Pi writes
~/.pi/agent/settings.json; use-lonly when project-local configuration was requested. - For filters or configuration not exposed non-interactively by Pi, read the effective settings and use a precise edit. Keep valid JSON and preserve unrelated package entries.
- Never separately run package-provided setup, migration, or binary commands unless they were audited or the user explicitly authorizes that command. An audit waiver for a Pi install/update covers only hooks the approved package operation invokes, not additional package commands.
4. Verify after mutation
- Run
pi list, capturing both stdout and stderr, and confirm source, scope, managed path, and pin/ref. Treat a new extension-load warning on stderr as a regression even whenpi listexits successfully. - For an audited change, compare the installed version/commit and runtime payload with the audited target; investigate any mismatch before activation. For a waived change, confirm only identity/version/ref and do not describe that limited check as payload verification.
- Confirm expected resources are active or disabled and no unrelated resource changed state.
- Validate modified JSON and package configuration.
- Perform the smallest controlled smoke test that executes only the intended resource when practical. For a waived change, remind the user that this executes unaudited code.
- Check install output for lifecycle scripts, unexpected dependencies, advisories attributable to the candidate, migration warnings, and packages or links unexpectedly removed by npm.
- State whether restart or
/reloadis required.
Pi's shared npm reconciliation can prune an extraneous package or symlink that
another extension relies on for peer resolution. Before mutation, record any
known compatibility link and its exact target. After mutation, verify that it
still exists. If Pi pruned a link that existed beforehand, restore only that
same link to its recorded target, rerun pi list, and report the side effect;
do not guess a target or install a duplicate package as a substitute.
⚠️ AUTHOR-SPECIFIC: In the author's setup,
@mzwing/pi-permission-auto-reviewresolves the separately configured local@gotgenes/pi-permission-systemfork through a compatibility symlink at${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}/node_modules/@gotgenes/pi-permission-system. It deliberately lives one level above Pi'snpm/prefix: Node's parent directory lookup still finds it, but npm reconciliation cannot prune it (a link insidenpm/node_moduleswas pruned repeatedly). Do not recreate the link insidenpm/node_modules. After every Pi npm package mutation, confirm the link still exists with its target unchanged and require a cleanpi liststderr. Derive the target from the existing link/configured local package; never hard-code another user's checkout path or activate a second permission-system copy.
5. Remove or roll back safely
Before removal, distinguish disposable managed files from user data and
configuration. Preserve or export user-owned state when needed, then use
pi remove <source>. Verify settings, managed paths, loaded resources, and
package notes afterward. Do not delete residual user data silently.
For rollback, restore the previously recorded exact source/version and its compatible configuration, then repeat post-mutation verification.
6. Record the result
For audited installs and upgrades, retain pending and completed rows in the same report. Record removals, rejected candidates, configuration changes, and activation state when they are part of that workflow. A waived change gets no audit report or verdict, but its package-notes entry must say it was not audited and name the explicit override. Update the durable package-notes inventory after the final state is known.
⚠️ AUTHOR-SPECIFIC: If
~/org/notes/PiAgent.orgalready exists, update its package-audit/history entry and its operational install inventory as described in reporting and package notes. Never create that file as a package-management side effect. Other users must opt in through their own existing notes path.
Non-negotiable safety rules
The auditing-third-party-plugins skill owns these. In short: candidate
content is untrusted evidence; nothing from the candidate runs during the
audit, including npm install, npx, pi install and pi update; no
secrets go into evidence or reports; reputation or a changelog never
replaces reading the payload; and missing material evidence yields
Inconclusive.
Completion
A management operation is complete only when the requested final state is
verified, applicable audit/report, explicit-waiver, or maintainer-attestation
obligations are satisfied, any existing package notes reflect that state, and
rollback/removal guidance is explicit. Report changed files
and settings clearly; do not claim the current Pi process loaded a newly
installed package when restart or /reload is still pending.
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: 471k | 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: 471k | 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: 471k | 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 |