---
name: repo-maintenance
description: Full maintenance runbook for the pi-agent config repo. Covers running tests, auditing installed pi packages for updates, searching npm for new pi extensions, detecting stale docs/CHANGELOG, and committing pending work. Use whenever the user asks to "check for updates", "do maintenance", or "look for new extensions".
---

# Repo Maintenance

Full-cycle maintenance for `~/.pi/agent`. Everything runs in parallel where possible.

## When to Use

- User asks to "run maintenance", "check for updates", or "look for new extensions"
- Before a major session to ensure tooling is fresh
- After a period of idle work to surface uncommitted drift
- Periodically (recommend: weekly)

---

## Phase 1 — Parallel Recon (launch all at once)

Fire these four checks in a single turn. They are fully independent.

```bash
# 1. Run tests
cd ~/.pi/agent && npm test

# 2. Check git status + uncommitted diff
cd ~/.pi/agent && git status && git diff --stat HEAD

# 3. Check pi-coding-agent version (installed vs npm latest)
INSTALLED=$(npm list -g @earendil-works/pi-coding-agent --depth=0 2>/dev/null \
  | rg pi-coding-agent | rg -o '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
LATEST=$(npm view @earendil-works/pi-coding-agent version 2>/dev/null)
echo "pi: installed=$INSTALLED latest=$LATEST"

# 4. Check all installed pi packages vs latest
for pkg in pi-subagents pi-web-access pi-powerline-footer \
           pi-mcp-adapter pi-model-aware-compaction pi-lens pi-btw; do
  INST=$(npm list -g $pkg --depth=0 2>/dev/null | rg -o '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
  LATEST=$(npm view $pkg version 2>/dev/null)
  echo "$pkg: installed=${INST:-not installed} latest=$LATEST"
done
```

While those run, also search npm for new packages:

```bash
# Search for new pi packages (run concurrently in separate bash calls)
npm search "pi-package" 2>/dev/null | head -30
npm search "pi-extension pi-coding-agent" 2>/dev/null | head -20
npm search "pi-subagents" 2>/dev/null | head -10
```

---

## Phase 2 — Evaluate Findings

### Tests

- All must pass before proceeding. A failing test is a blocker.

### Uncommitted Work

For each modified file in `git diff --stat HEAD`, classify it:

- **Config/settings changes** → single `chore:` commit
- **Code refactors** → one commit per logical area (e.g. one commit per extension)
- **New features** → `feat:` commit
- **Bug fixes** → `fix:` commit
- **Docs/CHANGELOG** → `docs:` commit last, after all code is committed

**Commit order:** code first, then CHANGELOG, then push.

### pi-coding-agent Version

If installed < latest, notify the user. Pi manages its own upgrades via `pi update`
or `npm install -g @earendil-works/pi-coding-agent@latest`. Don't auto-upgrade.

### Installed Pi Packages — Update Decision Matrix

| Gap           | Action                                              |
| ------------- | --------------------------------------------------- |
| patch (x.y.Z) | `npm install -g <pkg>@latest` — safe, do it         |
| minor (x.Y.z) | Read npm changelog, usually safe                    |
| major (X.y.z) | Read changelog carefully, ask user before upgrading |
| not installed | Evaluate whether it's worth adding (see Phase 3)    |

```bash
# Upgrade a specific package
npm install -g pi-subagents@latest
```

### Stale Docs Detection

```bash
cd ~/.pi/agent

# What commits happened after the last CHANGELOG entry?
LAST_VERSION=$(rg -m1 "^## \[" CHANGELOG.md | rg -o '[0-9]+\.[0-9]+\.[0-9]+')
LAST_DATE=$(rg -m1 "^## \[" CHANGELOG.md | rg -o '[0-9]{4}-[0-9]{2}-[0-9]{2}')
echo "Last documented: $LAST_VERSION on $LAST_DATE"
git log --oneline --after="$LAST_DATE"
```

If there are undocumented commits:

1. Read the diff for each commit: `git show <hash> --stat`
2. Draft a new CHANGELOG section `## [x.y.z] - YYYY-MM-DD`
3. Categorize under `### Added`, `### Changed`, `### Fixed`, `### Removed`

---

## Phase 3 — New Extensions Evaluation

### Search Commands

```bash
npm search "pi-package" 2>/dev/null
npm search "pi-extension pi-coding-agent" 2>/dev/null
npm search "pi-subagents" 2>/dev/null        # catch new subagent frameworks
```

### Evaluation Checklist

For each candidate package:

1. **Read the npm description** — is the use case real?
2. `npm view <pkg> readme` — skim the README
3. **Check publish date** — recent activity is a good sign
4. **Check if it overlaps** with existing extensions (don't add redundant tools)

### Notable Packages Encountered (April 2026 audit)

| Package                           | What it does                                                                                                           | Status                                               |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| `pi-btw@0.3.7`                    | Parallel side conversation while main agent runs; full tool access (`read`/`bash`/`edit`/`write`); inject summary back | **Recommended** — unique capability, no overlap      |
| `pi-acp@0.0.26`                   | ACP (Agent Client Protocol) adapter                                                                                    | Situational — only useful if using ACP orchestrators |
| `pi-docparser@1.1.1`              | Parse PDFs, Office docs, spreadsheets via LiteParse                                                                    | Situational — useful for document-heavy workflows    |
| `@a5c-ai/babysitter-pi@0.1.3`     | Orchestration/babysitter for pi agents                                                                                 | Uncertain — evaluate before install                  |
| `@ahkohd/pi-yagami-search@0.1.13` | Alternative web search via Yagami                                                                                      | Low priority — pi-web-access already covers this     |

### Install Command

```bash
# Test a new package
pi install npm:<package-name>

# Or add to settings.json packages array:
# "npm:<package-name>"
```

---

## Phase 4 — CHANGELOG + Commit Pending Work

### Determine New Version

- **patch** (0.x.Z): bug fixes, refactors, chore commits only
- **minor** (0.X.z): new features, new extensions added
- **major** (X.y.z): breaking changes (rare)

### CHANGELOG Template

```markdown
## [X.Y.Z] - YYYY-MM-DD

### Added

- **`<extension>.ts`** — description of new capability

### Changed

- **`<file>`** — what changed and why

### Fixed

- **`<file>`** — what was broken and how it was fixed

### Removed

- **`<file>`** — what was removed and why
```

### Commit Grouping Strategy

Group by concern, not by file. Each commit should answer: _"What changed and why?"_

| Commit message prefix | When to use                          |
| --------------------- | ------------------------------------ |
| `feat(<area>):`       | New user-visible capability          |
| `fix(<area>):`        | Bug fix                              |
| `refactor(<area>):`   | Code restructure, no behavior change |
| `chore:`              | Config, dependencies, tooling        |
| `docs(changelog):`    | CHANGELOG update — always last       |

```bash
# Commit sequence
git add <files-for-commit-1>
git commit -m "feat(toon-transformer): ..."

git add <files-for-commit-2>
git commit -m "refactor(<area>): ..."

# ... repeat for each logical group ...

git add CHANGELOG.md
git commit -m "docs(changelog): add [X.Y.Z] entry"

git push origin main
```

---

## Maintenance Checklist (Quick Reference)

```
[ ] npm test — all pass
[ ] git status — understand what's dirty
[ ] pi-coding-agent version — installed == latest
[ ] all pi packages — patch updates applied
[ ] npm search — new packages evaluated
[ ] uncommitted work — grouped into logical commits
[ ] CHANGELOG — updated with new version entry
[ ] git push origin main — repo published
```

---

## Recurring Gotchas

### vitest parent-directory config leakage

Running `npm test` inside a nested package directory may pick up `~/.pi/agent/vitest.config.ts`
(which sets `include: ["extensions/**/*.test.ts"]`). Ensure any nested package has its own
`vitest.config.ts` with the correct `include` glob.

### typebox package rename

pi-coding-agent 0.69.0 switched from `@sinclair/typebox@0.34.x` to `typebox@1.1.x`
(the library's new npm name). Any pi extension that imports `Type` from typebox must
use the unscoped `typebox` package at `^1.1.24` or higher. Using `@sinclair/typebox`
will cause type incompatibilities with pi-coding-agent's exported `TSchema` types.
