Update Packages
Step 0: Update Skills + Create Branch (MANDATORY)
Before touching any packages, update skills and create a dedicated branch.
# 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)
Rules:
- Always update skills first — they may contain updated instructions for this workflow
- Never reuse an existing update-packages branch
- All package update commits go to this branch
Package Groups (Update Together)
These packages must always be updated as a group — mismatched versions cause type errors or runtime failures:
| Group |
Packages |
| tanstack-router |
@tanstack/react-router, @tanstack/router-devtools, @tanstack/router-plugin, @tanstack/start |
| tanstack-query |
@tanstack/react-query, @tanstack/react-query-devtools, @tanstack/query-core |
| trpc |
@trpc/server, @trpc/client, @trpc/react-query, @trpc/tanstack-react-query |
| effect |
effect, @effect/schema, @effect/platform, @effect/language-service |
| drizzle |
drizzle-orm, drizzle-kit, drizzle-zod |
| pino |
pino, pino-pretty, @types/pino |
| playwright |
@playwright/test, playwright (+ Docker image sync — see Special Cases) |
Update Strategy
Per Package Group Flow
For each group, execute steps 1–4 before moving to the next:
Step 1 — Identify versions (old → new)
- Run
bun upgrade interactively, note minor/major bumps
- For catalog packages:
npm view <package> version
Step 2 — Update + Analyze release notes IN PARALLEL
| Track A: Apply Update |
Track B: Analyze Release Notes (background) |
Apply version bumps via bun upgrade or catalog edit |
npm view <pkg> repository.url → gh release view <tag> --repo <owner/repo> |
bun install if catalog |
Major: breaking changes, migration guides, removed APIs |
|
Minor: new APIs, deprecations, opt-in improvements |
|
Search codebase for usages of changed/deprecated/new APIs |
Each package group shares one background subagent. Standalone packages get one subagent each.
Step 3 — Check + Fix
- Run
bun run check
- If it fails: use release notes from Step 2 for context-aware fixes
Step 4 — Commit the group
Release Notes Report
After all groups are updated, output a unified summary:
| Package | Type | Old → New | Changes | Impact |
|---------|------|-----------|---------|--------|
Rules:
- Each subagent MUST search the codebase for usages of changed/deprecated/new APIs
- For breaking changes: list affected files with line numbers + migration snippets
- For new features: suggest where they could be adopted (diffs only, don't apply)
- Skip patch-only updates in the report
Special Cases
Bun Runtime Updates
- Update
packageManager in root package.json: "bun@X.Y.Z"
- Update
ARG BUN_VERSION=X.Y.Z in all Dockerfiles
- Update
BUN_VERSION in CI pipeline files
bun run check → commit: chore: update bun to vX.Y.Z
Playwright Updates
- Docker image version must match npm package version exactly
- Update all references to
mcr.microsoft.com/playwright:vX.Y.Z-noble across Dockerfiles, CI, and Helm values
bun run test:e2e → commit: chore: update playwright to vX.Y.Z
Catalog Packages
Packages in Bun's catalog need manual version checks: npm view <package> version. Update entries in package.json manually.
Testing Requirements
| Update Type |
Required Tests |
| UI/component packages |
bun run check + visual review |
| TRPC / TanStack Router |
bun run check + bun run test |
| Drizzle ORM |
bun run check + bun run test |
| Effect packages |
bun run check + bun run test |
| Playwright |
bun run check + bun run test:e2e |
| Bun runtime |
bun run check + bun run test + bun run test:e2e |
| All others |
bun run check |
Guardrails
- DO NOT update packages with
workspace:* — these are internal monorepo packages
- DO NOT skip
@typescript/native-preview updates — affects TypeScript LSP performance
- DO NOT use
bun outdated — misses catalog packages; use bun upgrade interactively
- If packages fail to install:
bun clean:packages && bun install
Definition of Done
bun upgrade shows all packages at latest versions- All checks pass (
bun run check)
- All relevant tests pass
1---2name: update-packages3description: LOAD THIS SKILL when: updating npm packages, user mentions 'update packages', 'update-packages', 'outdated', 'dependency updates'. Covers autonomous npm package updates with breaking change handling, Bun updates, Playwright Docker sync, and package group coordination.4---56# Update Packages78## Step 0: Update Skills + Create Branch (MANDATORY)910Before touching any packages, update skills and create a dedicated branch.1112```bash13# Update all skills from skills-lock.json (reads sources + skill names from lock)14bun run .agents/skills/update-packages/references/skills-update-local.ts1516# Dry run to see what would be executed17bun run .agents/skills/update-packages/references/skills-update-local.ts --dry-run1819# Create a fresh branch20git checkout -b chore/update-packages-$(date +%y%m%d-%H%M)21```2223**Rules:**24- Always update skills first — they may contain updated instructions for this workflow25- Never reuse an existing update-packages branch26- All package update commits go to this branch2728## Package Groups (Update Together)2930These packages must always be updated as a group — mismatched versions cause type errors or runtime failures:3132| Group | Packages |33|-------|----------|34| **tanstack-router** | `@tanstack/react-router`, `@tanstack/router-devtools`, `@tanstack/router-plugin`, `@tanstack/start` |35| **tanstack-query** | `@tanstack/react-query`, `@tanstack/react-query-devtools`, `@tanstack/query-core` |36| **trpc** | `@trpc/server`, `@trpc/client`, `@trpc/react-query`, `@trpc/tanstack-react-query` |37| **effect** | `effect`, `@effect/schema`, `@effect/platform`, `@effect/language-service` |38| **drizzle** | `drizzle-orm`, `drizzle-kit`, `drizzle-zod` |39| **pino** | `pino`, `pino-pretty`, `@types/pino` |40| **playwright** | `@playwright/test`, `playwright` (+ Docker image sync — see Special Cases) |4142## Update Strategy4344### Per Package Group Flow4546For each group, execute steps 1–4 before moving to the next:4748**Step 1 — Identify versions (old → new)**49- Run `bun upgrade` interactively, note minor/major bumps50- For catalog packages: `npm view <package> version`5152**Step 2 — Update + Analyze release notes IN PARALLEL**5354| Track A: Apply Update | Track B: Analyze Release Notes (background) |55|---|---|56| Apply version bumps via `bun upgrade` or catalog edit | `npm view <pkg> repository.url` → `gh release view <tag> --repo <owner/repo>` |57| `bun install` if catalog | **Major**: breaking changes, migration guides, removed APIs |58| | **Minor**: new APIs, deprecations, opt-in improvements |59| | Search codebase for usages of changed/deprecated/new APIs |6061Each package group shares one background subagent. Standalone packages get one subagent each.6263**Step 3 — Check + Fix**64- Run `bun run check`65- If it fails: use release notes from Step 2 for context-aware fixes6667**Step 4 — Commit the group**6869### Release Notes Report7071After all groups are updated, output a unified summary:7273```74| Package | Type | Old → New | Changes | Impact |75|---------|------|-----------|---------|--------|76```7778**Rules:**79- Each subagent MUST search the codebase for usages of changed/deprecated/new APIs80- For breaking changes: list affected files with line numbers + migration snippets81- For new features: suggest where they could be adopted (diffs only, don't apply)82- Skip patch-only updates in the report8384## Special Cases8586### Bun Runtime Updates87881. Update `packageManager` in root `package.json`: `"bun@X.Y.Z"`892. Update `ARG BUN_VERSION=X.Y.Z` in all Dockerfiles903. Update `BUN_VERSION` in CI pipeline files914. `bun run check` → commit: `chore: update bun to vX.Y.Z`9293### Playwright Updates94951. Docker image version **must match** npm package version exactly962. Update all references to `mcr.microsoft.com/playwright:vX.Y.Z-noble` across Dockerfiles, CI, and Helm values973. `bun run test:e2e` → commit: `chore: update playwright to vX.Y.Z`9899### Catalog Packages100101Packages in Bun's catalog need manual version checks: `npm view <package> version`. Update entries in `package.json` manually.102103## Testing Requirements104105| Update Type | Required Tests |106|-------------|----------------|107| UI/component packages | `bun run check` + visual review |108| TRPC / TanStack Router | `bun run check` + `bun run test` |109| Drizzle ORM | `bun run check` + `bun run test` |110| Effect packages | `bun run check` + `bun run test` |111| Playwright | `bun run check` + `bun run test:e2e` |112| Bun runtime | `bun run check` + `bun run test` + `bun run test:e2e` |113| All others | `bun run check` |114115## Guardrails116117- **DO NOT** update packages with `workspace:*` — these are internal monorepo packages118- **DO NOT** skip `@typescript/native-preview` updates — affects TypeScript LSP performance119- **DO NOT** use `bun outdated` — misses catalog packages; use `bun upgrade` interactively120- If packages fail to install: `bun clean:packages && bun install`121122## Definition of Done123124- `bun upgrade` shows all packages at latest versions125- All checks pass (`bun run check`)126- All relevant tests pass
jsgforever