update-packages

Update Packages

Operation Mode

Identify the operation mode before running any update command:

• Use Advisory mode to analyze, report, and propose changes only. Do not create a branch.
• Use Execution mode to apply version changes. Create a fresh update branch before the first package edit.

References

Use these references during execution:

• references/package-groups.md — package groups that must be updated together
• references/feature-adoption-tiers.md — T0-T3 adoption rubric
• references/report-formats.md — release report and "What's New" output formats
• references/testing-matrix.md — required tests by update type
• references/runtime-checklists.md — Bun and Playwright checklists; read the Effect Updates section for Effect or compiler updates and the SDK Updates section for SDK upgrades

Step 0: Prepare Session (Execution mode only)

Update skills and create a dedicated branch before touching packages.

# Update all skills from skills-lock.json (reads sources + skill names from lock)
bun run .agents/skills/update-packages/references/skills-update-local.ts

# Dry run to see what would be executed
bun run .agents/skills/update-packages/references/skills-update-local.ts --dry-run

# Create a fresh branch
git checkout -b chore/update-packages-$(date +%y%m%d-%H%M)

Apply these rules:

• Update skills first.
• Create a new update branch for execution work.
• Reuse no previous update branch.
• Place all update commits on the execution branch.

Update Strategy

Per Package Group Flow

Read references/package-groups.md. Execute steps 1-4 for each group before moving to the next group.

Step 1 — Identify versions + release notes

Run all three reports:

bun run .agents/skills/update-packages/references/check-outdated.ts
bun run .agents/skills/update-packages/references/check-outdated.ts --changelog
bun run .agents/skills/update-packages/references/report.ts --json

Use generated JSON files as session data:

Script flag	Saved to
--json	.agents/skills/update-packages/references/outdated.json
--changelog	.agents/skills/update-packages/references/outdated-changelog.json
report.ts --json	.agents/skills/update-packages/references/runtime-report.json

Handle stale report files before analysis:

• Regenerate all three reports at session start.
• Delete old report files first if they contain data from a prior run or branch.
• Treat saved JSON files as disposable local artifacts. Do not commit them.

Handle catalog packages in one place:

• Find catalog versions in root package.json under catalog and catalogs.
• Check latest versions manually (npm view <package> version) when needed.
• Respect the repository's Bun install policy in bunfig.toml, especially minimumReleaseAge and related excludes.
• Do not bypass Bun's age gate with flags like bun install --minimum-release-age 0 unless the user explicitly requests that override.
• Choose the newest compatible version that satisfies minimumReleaseAge for the whole package group. If a requested version appears blocked, reproduce it with bun install <package>@<version> --dry-run --no-save before recording the refusal; then use the newest eligible version.
• Update catalog entries manually, then run plain bun install.

Step 2 — Update + Adopt features IN PARALLEL

Track A: Apply Update	Track B: Adopt features from release notes
Apply version bumps via bun upgrade or catalog edit	Read outdated-changelog.json — each entry has releases[] with full release notes
bun install if catalog (respecting bunfig.toml minimum-release-age policy)	Classify each new feature by tier (see references/feature-adoption-tiers.md)
	T0/T1: implement config-level changes (target files in configFiles[]), verify with bun run check
	T2: generate concrete diffs, include in report
	Search codebase for usages of changed/deprecated/new APIs

For SDK upgrades, follow the SDK Updates checklist in references/runtime-checklists.md.

Delegate release-note research to a subagent/librarian when available. If delegation is unavailable, process package groups sequentially in the main agent with the same rubric.

Apply the T0-T3 rubric from references/feature-adoption-tiers.md.

Step 3 — Check + Fix

Run required tests from references/testing-matrix.md. Run bun run check at minimum. Fix failures using release-note context from outdated-changelog.json.

Step 4 — Commit the group

Use separate commits for version bumps and feature adoptions:

• chore: update <package> to vX.Y.Z — version bump only
• feat: adopt <package> vX.Y improvements (<feature list>) — config/code changes from new features

Put behavior or security fixes found during an update in a separate PR from the dependency bump.

Internal library releases

Pin peer dependencies to the exact compatible family version. Do not start a peer range at a prerelease. Before release, install the library into a clean consumer for each supported family version and package manager, then verify the lockfile contains one copy of each family package.

Release Notes Report

Generate the release report using references/report-formats.md. When using subagents, require each subagent to search for usages of changed/deprecated/new APIs. When running sequentially, perform the same search directly.

What's New Summary

Generate the "What's New" summary using references/report-formats.md. Use outdated-changelog.json as the primary source. Fetch missing release notes with a librarian only when needed.

Special Cases

Apply the Bun and Playwright checklists from references/runtime-checklists.md. For Effect or compiler updates, follow its Effect Updates section. For SDK upgrades, follow its SDK Updates section.

After deployment, check Sentry for new issues in each project and environment. Request / and the liveness route; a successful liveness response alone does not verify server rendering.

Testing Requirements

Use references/testing-matrix.md to choose required tests.

Guardrails

• Do not update packages with workspace:*.
• Do not skip @typescript/native-preview updates.
• Do not use bun outdated; use check-outdated.ts.
• Do not bypass Bun's minimumReleaseAge policy unless the user explicitly asks for it.
• If bun install fails due to minimumReleaseAge, downgrade the requested package versions to the newest policy-compliant releases and retry with plain bun install.
• Run bun clean:packages then bun install if install fails.

Definition of Done

• Confirm check-outdated.ts shows no remaining direct dependency updates.
• Confirm bun run check passes.
• Confirm all tests required by references/testing-matrix.md pass.