pi-collection-maintenance

name	pi-collection-maintenance
description	Use this skill whenever adding, removing, renaming, documenting, publishing, or reorganizing a package, extension, slash command, LLM tool, Pi skill, prompt, theme, subagent template, launch profile, catalog entry, README, or public-facing project documentation in this repository. Also use it for inventory drift audits and collection-wide release/discovery changes.
compatibility	Project-local workflow for this public Pi package and resource collection; requires Node.js and repository access.
metadata	{"version":"1"}

Pi Collection Maintenance

Purpose

Maintain this repository as an evolving, publicly readable, opinionated Pi tool collection without encoding a temporary package count or inventory in long-lived governance.

This skill owns the maintenance workflow, not product behavior. Resource owners remain authoritative for implementation, safety, and package-specific documentation.

Required reading

Before changing collection inventory or public documentation:

1. Read the repository-root AGENTS.md and README.md.
2. Read the documentation contract.
3. Inspect the current package/resource discovery inputs rather than relying on remembered names or counts.
4. For every affected package, read its manifest, README, package AGENTS.md, docs AGENTS.md, and docs index.
5. For Pi-native package resources, read the installed Pi documentation for packages and the relevant resource type.

Validate this skill after changing it:

node .agents/skills/pi-collection-maintenance/scripts/validate-skill.mjs

See the local validator.

Stable principles

• Discover; do not enumerate in governance. Root governance defines conventions and commands, never the current package list or count.
• Owner-local source of truth. A package owns its catalog metadata, manifest, public surfaces, safety summary, and README.
• Standard metadata first. Discover extensions, skills, prompts, and themes from the Pi package manifest. Use collection metadata only for information Pi does not describe, such as human summaries, slash commands, LLM tools, side effects, or built-in subagent templates.
• Generated portfolio views. Root summaries and the detailed catalog are deterministic projections. Do not hand-edit generated regions.
• Profiles are composition, not inventory. A resource may be discoverable and launchable without belonging to a named profile.
• Current use before history. Human entry points show what is available and how to use it before release chronology. Preserve historical evidence in version/archive records.
• Public-safe content only. Never catalog secrets, private paths, credentials, raw traces, local tokens, or unpublished personal configuration.
• No silent lifecycle promotion. Experimental resources become release-ready only through their owner-defined verification and release process.

Workflow

1. Classify the change

Identify every affected resource class:

• workspace package;
• Pi extension, skill, prompt, or theme;
• slash command or LLM-callable tool;
• built-in or project subagent template;
• launch profile;
• generated catalog/README projection;
• package README or planning index;
• lifecycle, release, deprecation, rename, or removal.

A change may affect more than one class. For example, adding an LLM tool affects implementation, owner metadata, owner README, generated catalog output, and verification.

2. Discover the current state

Use repository discovery and owner files. Do not copy a package list from prose.

Confirm:

• actual workspace packages and manifests;
• declared Pi resources and their files;
• registered commands/tools and package-owned subagent definitions;
• project meta skills and trusted project subagent templates;
• named profile membership;
• lifecycle status and release eligibility;
• generated output freshness.

Treat regex/source audits as conservative evidence, not proof of runtime behavior.

3. Update the owner

Follow the contract in references/documentation-contract.md.

For a package-owned change:

1. update implementation and focused tests;
2. update the package manifest and owner-local collection metadata;
3. update the package README public surface and safety/side-effect description;
4. update package planning/current-status docs only when product status changed;
5. update a profile only when composition intentionally changed.

For project meta skills or project subagent templates, update the owning file and let discovery include it. Do not add its name to root governance.

4. Regenerate projections

Use the repository's explicit generation command when available, then run the read-only freshness check. Generated output must be stable across two consecutive generations.

Never make generation an implicit side effect of a read-only check.

5. Verify boundedly

Run the smallest focused checks first, then collection checks required by the change:

• skill/frontmatter validation;
• owner package tests and typecheck;
• catalog discovery/audit and generated-doc freshness;
• profile audit when composition or exposed package surfaces changed;
• root documentation/tool tests;
• release gate when release-ready inventory or cross-package loading changed;
• git diff --check.

Report what was verified and what remains unverified. Do not claim that metadata or documentation proves provider, network, credential, or side-effecting runtime behavior.

Change-specific rules

Add a package or standard Pi resource

• Put it under the repository's workspace/package convention.
• Declare Pi-native resources in the standard pi manifest.
• Add owner-local collection metadata and lifecycle status.
• Ensure discovery includes it without editing a central current-package array.
• Add package governance/README/planning docs only to the depth warranted by its roadmap.

Add or rename a command or LLM tool

• Keep exact public names in owner-local metadata and the package README.
• Add focused registration/schema tests.
• Regenerate portfolio docs.
• Audit profile collisions, but do not add the package to a profile unless requested.

Add a subagent template

• Distinguish package built-ins from trusted project templates.
• Keep the template owner, trust requirement, tools, model override, and write authority explicit.
• Validate frontmatter and file containment.
• Never imply that template discovery grants worker authority or broader tools.

Remove, rename, deprecate, or replace a resource

• Search active consumers, profiles, docs links, release gates, and generated projections.
• Preserve historical release/adoption evidence unless the user explicitly requests historical rewriting.
• For renames, document compatibility aliases and removal timing when applicable.
• Regenerate and prove that stale active references are gone.

Stop conditions

Stop and ask before proceeding when:

• ownership or lifecycle status is ambiguous;
• a generated file would need a manual exception;
• public metadata would expose private configuration;
• a new resource type has no owner/discovery rule;
• a profile change would implicitly grant authority;
• source and owner metadata disagree and implementation intent cannot be established;
• release-ready promotion lacks its owner verification evidence.