plannotator: Skill for Claude Code

Update Dependencies

Audit outdated packages, verify supply chain integrity, bump what's safe, defer what needs review, and log everything.

This process has three phases: discovery, integrity audit, and execution. The integrity audit is the most important — every package gets checked before it touches the lockfile.

Phase 1: Discovery

Run bun outdated to get the full list of packages with available updates.

bun outdated

Parse the output into a structured list. For each package, note:

• Package name
• Current version
• Available update version
• Whether it's age-gated (indicated by * in the output — the footnote "The * indicates that version isn't true latest due to minimum release age" confirms this)
• Whether it's a runtime dep, dev dep, or peer dep

Also check whether any packages are blocked entirely by the age gate (like @pierre/diffs was when its minimum semver range couldn't resolve). Flag these separately — they may need minimumReleaseAgeExcludes in bunfig.toml.

Phase 2: Integrity Audit

This is the core of the process. Spawn one Sonnet sub-agent per package to run the integrity check in parallel. Sonnet is used here because these are independent, structured verification tasks that don't need heavier reasoning.

Each sub-agent receives the package name, current version, and target version, and performs the following checks:

Sub-agent prompt template

For each outdated package, spawn a Sonnet agent with this task:

You are auditing the npm package "{package}" for a version bump from {current} to {target}.

Run these checks and report back with a JSON object:

1. **Maintainer verification**: Check if maintainers changed between versions.
   npm view {package}@{current} maintainers --json
   npm view {package}@{target} maintainers --json
   Compare the two lists. Flag any additions or removals.

2. **Publish date and age**: Get the publish timestamp.
   npm view {package} time --json
   Extract the date for version {target}. Calculate days since publication.
   Flag if younger than 7 days.

3. **Provenance**: Check if the package has registry signatures or attestations.
   npm audit signatures (if not already run this session)
   Note whether the package has provenance attestations.

4. **Tarball diff**: Show what actually changed in the published package.
   npm diff --diff={package}@{current} --diff={package}@{target}
   Summarize the changes:
   - How many files changed
   - Are changes limited to version bumps, deps, and rebuilt dist? Or are there meaningful source changes?
   - Any new runtime dependencies added?
   - Any suspicious patterns (obfuscated code, eval(), network calls in unexpected places)

5. **Release notes**: Try to find what changed.
   Check the package's repository for release notes or changelog:
   npm view {package}@{target} repository.url
   gh release view v{target} --repo <owner/repo> (try with and without v prefix)
   Summarize the changelog if found.

Report your findings as JSON:

{{
  "package": "{package}",
  "from": "{current}",
  "to": "{target}",
  "age_days": <number>,
  "maintainers_changed": <boolean>,
  "maintainers_added": [],
  "maintainers_removed": [],
  "provenance": <boolean>,
  "new_runtime_deps": [],
  "files_changed": <number>,
  "has_source_changes": <boolean>,
  "changelog_summary": "<brief summary>",
  "suspicious_patterns": [],
  "verdict": "safe" | "review" | "defer",
  "verdict_reason": "<one sentence explanation>"
}}

Verdict guidelines:
- "safe": Same maintainers, no new runtime deps, changes match what changelog describes, no suspicious patterns
- "review": Minor concerns (e.g., new maintainer who is clearly from the same org, small new dep from known publisher)
- "defer": Maintainer changes from unknown accounts, new runtime deps with unclear purpose, suspicious code patterns, substantive API changes that need integration testing