setup-maintenance

name	setup-maintenance
description	Maintain and improve a Pi coding agent setup over time — prevent drift AND find new leverage. Use when auditing setup health, before adding a package/extension, before publishing, or when asked "is my setup healthy" / "audit my setup" / "how do I keep this sharp".

Setup Maintenance

A setup that doesn't degrade is a setup with a maintenance discipline. This skill defines the cadence + the two loops: maintenance (prevent drift) and improvement (find new leverage). The one-command runner is /setup-audit.

The two loops

Maintenance loop — prevent drift. Versions fall behind, new packages conflict, skills bloat, disk grows, AGENTS.md goes stale, extensions develop latent bugs. Without a check, you discover this when something breaks at the worst time.

Improvement loop — find new leverage. The Pi ecosystem ships new packages/features weekly. Other setups (cc10x, Archon, spences10, tomsej/pi-ext) invent techniques worth stealing. Without a scan, you plateau. This is the loop that turned a good setup into a best-contender.

The cadence

When	What	How
Monthly	Full audit (both loops)	/setup-audit — fans out 6 subagents, writes a report
On-add (new package/extension)	Harmony re-audit	Read the new package's tools/commands/hooks/storage; check for collisions against existing packages + extensions (enumerate dynamically from settings.json + extensions dir). Reject if it duplicates an existing axis.
Before-publish (pushing my-pi)	Full audit + sync	/setup-audit → fix criticals → sync settings/extensions/skills to ~/Dev/my-pi → commit + push
On-extend (new skill)	Coach coverage check	After adding a skill, grep coach.ts — does any intent route to it? If not, add a detector or it's unreachable via Coach.

The /setup-audit runner

/setup-audit dispatches 6 parallel read-only subagents:

1. Version freshness — installed vs latest for Pi core + all npm packages. Flags drift + deprecation.
2. Harmony re-audit — tool/command/hook/storage collisions across all packages + extensions. File:line evidence.
3. Coach coverage scan — lists EVERY command + skill, flags which Coach never routes to. Each gap = leverage the setup has but doesn't surface. This is the highest-value axis — it's how we found the wayfinder gap.
4. Disk growth — sessions, hermes DB, workflows, context sidecar. Flags unbounded stores > 100MB.
5. AGENTS.md accuracy — line count (must be < 200) + does it match reality.
6. Ecosystem scan — new Pi packages + public setups worth stealing from. Conflict-assessed.

Output: a report at ~/Dev/my-pi/docs/audits/setup-audit-YYYY-MM-DD.md with health score per axis, critical/recommended/informational findings, Coach coverage gaps, ranked candidate steals, and ordered recommended actions.

The on-add harmony gate (do this BEFORE installing any new package)

Before npm install -g <pkg> and adding it to settings.json packages:

1. Read the package's main extension file — what tools does it register? What hooks? What storage?
2. Check against existing axes:
   • Tool name collision? (grep all installed package manifests)
   • Command name collision?
   • Hook on the same event as an existing package? (ordering risk)
   • Storage path overlap? (same SQLite DB or directory?)
3. Verdict: install-clean / install-with-config / reject (duplicates an existing axis).
4. If install-with-config: determine the right load order in packages array (e.g. confirm-destructive before pi-hypa; context before pi-lens).
5. After install: runtime load test (pi -p "ok" 2>err; grep -i error err), verify 0 load errors.

The rule: one axis, one owner. If a new package duplicates an existing package's axis, reject it — no matter how popular. Harmony over capability.

The improvement loop — how to steal well

When the ecosystem scan finds a candidate (a package, a setup, a prompt technique):

1. Identify the steal precisely — a specific technique, not "their setup is good."
2. Check the axis — does it duplicate something we have? (e.g. activeContext.md overlaps pi-hermes-memory → SKIP)
3. Is it harmony-safe? — steering text changes to loop.ts > new extensions > new packages (in order of risk).
4. Verify before claiming done — 0 LSP errors, 0 load errors, test the routing if it's Coach.
5. Document the steal — write to docs/audits/ so the next audit knows what was considered + why.

Don't

• Don't run /setup-audit and then skip the Coach coverage scan — that's the highest-value axis.
• Don't install a package without the on-add harmony gate. "It looked useful" is how conflicts arrive.
• Don't let AGENTS.md exceed 200 lines — every line is a token cost on every session.
• Don't prune skills just because they're old — prune because they stopped earning their system-prompt slot.
• Don't push the live ~/.pi/agent/ (not a git repo, contains secrets in auth.json/web-search.json/trust.json). Always sync to ~/Dev/my-pi first.