# Update Packages

> This skill should be used when upgrading dependencies, bumping packages, resolving outdated dependencies, or performing dependency updates. It guides safe Bun-based package upgrades with breaking-change handling, runtime pin alignment, and grouped version coordination.

- Skill: `blogic-cz/update-packages` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add blogic-cz/update-packages`
- Raw SKILL.md: https://api.skillmd.com/api/skills/blogic-cz/update-packages/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: blogic-cz (https://skillmd.com/u/blogic-cz)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/blogic-cz/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 update checklists

## Step 0: Prepare Session (Execution mode only)

Update skills and create a dedicated branch before touching packages.

```bash
# 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:

```bash
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.
- If a desired version is blocked by `minimumReleaseAge`, choose the newest older compatible version that satisfies the policy and update the manifest to that version instead of forcing the install.
- 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                                                |

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

### 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 Bun and Playwright update checklists from `references/runtime-checklists.md`.

## 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.