Node Dependency Bumper
Use Taze to build one structured update plan, apply compatible ranged updates, and make major-version decisions as a
batch.
Adding Dependencies
For a new package or CLI, use the repository's package manager and existing range convention instead of Taze. Installing
package@latest and retaining the package manager's resulting ^x.y.z range is allowed. Do not replace a caret range
with an exact version merely because it can admit future releases.
When an effective package-manager minimum-release-age policy exists, it provides the freshness boundary for candidate
versions; read references/conditional-workflows.md. The committed lockfile and
frozen deployment install provide reproducibility. Exact-pin only when the user or repository requires it, a known
compatibility constraint justifies it, or the package will run without a committed lockfile and frozen install.
Workflow
Resolve the skill directory and save the helper plan from the target repository:
bash <skill-dir>/scripts/run-taze.sh --plan [--include package-a,package-b] > <taze-plan.json>
The JSON plan classifies every discovered update as apply, review-major, review, or skip-fixed. The helper
detects monorepos, includes locked versions during scans, and mirrors Bun minimum-release-age settings. If the
repository uses package-manager age gates or Bun catalogs, read
references/conditional-workflows.md for that active branch only.
If --dry-run was requested, present the plan and counts, then stop without changing manifests or lockfiles.
Select every ranged minor/patch update marked apply. Never auto-approve a major package by name. Present all
review-major and unknown updates in one decision batch with current version, target version, package role when
discoverable, and relevant migration/release notes. Apply only the majors the user selects.
If nothing is selected, report the no-op and stop. If the root manifest uses Bun catalogs, preview the exact selected
catalog transitions from the accepted plan:
uv run <skill-dir>/scripts/update-bun-catalogs.py \
--root <repo> --plan <taze-plan.json> --include package-a,package-b
The preview is read-only. Missing catalog entries, conflicting plan rows, unsupported versions, or a catalog value
that no longer matches the plan fail before writes. The helper does not select upgrades.
Before the first manifest or lockfile write, discover and run the repository's standard validation suite against the
existing dependency state. Prefer its advertised aggregate check; otherwise run every exposed dependency-resolution,
build, test, typecheck, lint, formatting-check, codegen-check, and repository-invariant command. Use frozen or
non-writing modes where available, and record the exact commands for the post-bump rerun. Attribute every failure
before deciding whether it blocks. Proceed when an unrelated pre-existing failure is reproducible, can be compared
after the bump, and does not prevent dependency resolution or the checks needed to detect regressions; do not fix it
as part of the bump. Dependency or peer-resolution conflicts, actionable unsafe behavior, or a baseline that cannot
provide trustworthy before/after signal block the bump. In that case, stop with
### ⛔ Dependency bump blocked — baseline unusable and report the exact prerequisite and diagnostics without asking
for redundant authorization. Informational notices such as unavoidable deprecations do not block.
Write all selected Taze updates in one command:
bash <skill-dir>/scripts/run-taze.sh --write --include package-a,package-b
For Bun catalogs, rerun update-bun-catalogs.py with the same plan and include set plus --write. It atomically
updates every matching default/named catalog occurrence and preserves each existing ^, ~, or empty prefix. Then
run ni so the repository's package manager updates its lockfile.
Inspect the manifest and lockfile diff. Rerun the exact baseline commands, plus the narrowest checks that exercise
the updated dependencies and any required migrations. Treat every newly introduced error, type issue, check failure
(including tests, builds, lint, formatting, codegen, and repository invariants), dependency or peer-resolution
conflict, and actionable compatibility or safety warning as caused by the bump unless evidence shows otherwise.
Fix every issue caused by the bump, including required source or configuration migrations, while preserving intended
behavior. Do not suppress diagnostics, weaken validation, or change expected behavior merely to make checks pass.
After each fix, rerun the affected check, then rerun the complete recorded suite until it passes. If no clear safe
fix exists within the task's authority, stop with ### ⚠️ Dependency regression decision required. Present all such
issues in one table with the evidence, affected locations, fix and revert options, and likely effects. Do not report
completion until the user chooses, the fix is applied or the offending update is reverted, the lockfile is
regenerated, and the complete suite passes.
User-Facing Output
Present plans as ### 📦 Dependency plan with counts and a compact table:
| ID |
Plan value |
Decision |
Package |
Current → target |
Type |
Notes |
Use the plan's exact apply, review-major, review, and skip-fixed values alongside plain-language decisions.
Assign stable IDs to rows needing a choice so the user can answer once. Use ### 🔎 Dry run — no files written for a
preview and ### ✅ No selected updates for a no-op.
Finish applied work with ### 🏁 Dependencies updated, a tree of changed manifests/lockfiles, and
### 🧪 Verification. Use ### ⚠️ Remaining review only for non-blocking informational matters, never for an
unresolved issue caused by the bump. Keep helper JSON, package/version strings, commands, and diagnostics exact and
undecorated.
Invariants
- Fixed versions and non-semver protocols remain unchanged unless the user explicitly asks otherwise.
- Caret ranges are valid for new dependencies and CLIs; do not describe them as unreproducible when a committed lockfile
and frozen install control resolution.
- Package arguments constrain both scan and write phases.
- The same maturity-period policy applies to scan and write.
- Bun catalog preview and write use the same accepted Taze plan and selected package set; stale plans never write.
- Do not infer compatibility from SemVer alone when repository evidence, peer ranges, or release notes indicate
otherwise.
Completion requires an attributed, comparison-safe pre-write baseline, a reviewed plan, the retained selected updates, a
regenerated lockfile, no new failure in the recorded suite or dependency-specific checks, and no unresolved issue caused
by the bump. Dry-run completion requires the structured plan and zero writes.
1---
2argument-hint: "[--dry-run] [package ...]"
3effort: medium
4model: sonnet
5name: node-deps-bumper
6description: "Use for dependency updates: bump npm/pnpm/yarn/bun packages, check outdated, or run taze."
7---
8
9# Node Dependency Bumper
10
11Use Taze to build one structured update plan, apply compatible ranged updates, and make major-version decisions as a
12batch.
13
14## Adding Dependencies
15
16For a new package or CLI, use the repository's package manager and existing range convention instead of Taze. Installing
17`package@latest` and retaining the package manager's resulting `^x.y.z` range is allowed. Do not replace a caret range
18with an exact version merely because it can admit future releases.
19
20When an effective package-manager minimum-release-age policy exists, it provides the freshness boundary for candidate
21versions; read [references/conditional-workflows.md](references/conditional-workflows.md). The committed lockfile and
22frozen deployment install provide reproducibility. Exact-pin only when the user or repository requires it, a known
23compatibility constraint justifies it, or the package will run without a committed lockfile and frozen install.
24
25## Workflow
26
271. Resolve the skill directory and save the helper plan from the target repository:
28
29 ```sh
30 bash <skill-dir>/scripts/run-taze.sh --plan [--include package-a,package-b] > <taze-plan.json>
31 ```
32
33 The JSON plan classifies every discovered update as `apply`, `review-major`, `review`, or `skip-fixed`. The helper
34 detects monorepos, includes locked versions during scans, and mirrors Bun minimum-release-age settings. If the
35 repository uses package-manager age gates or Bun catalogs, read
36 [references/conditional-workflows.md](references/conditional-workflows.md) for that active branch only.
37
382. If `--dry-run` was requested, present the plan and counts, then stop without changing manifests or lockfiles.
39
403. Select every ranged minor/patch update marked `apply`. Never auto-approve a major package by name. Present all
41 `review-major` and unknown updates in one decision batch with current version, target version, package role when
42 discoverable, and relevant migration/release notes. Apply only the majors the user selects.
43
444. If nothing is selected, report the no-op and stop. If the root manifest uses Bun catalogs, preview the exact selected
45 catalog transitions from the accepted plan:
46
47 ```sh
48 uv run <skill-dir>/scripts/update-bun-catalogs.py \
49 --root <repo> --plan <taze-plan.json> --include package-a,package-b
50 ```
51
52 The preview is read-only. Missing catalog entries, conflicting plan rows, unsupported versions, or a catalog value
53 that no longer matches the plan fail before writes. The helper does not select upgrades.
54
555. Before the first manifest or lockfile write, discover and run the repository's standard validation suite against the
56 existing dependency state. Prefer its advertised aggregate check; otherwise run every exposed dependency-resolution,
57 build, test, typecheck, lint, formatting-check, codegen-check, and repository-invariant command. Use frozen or
58 non-writing modes where available, and record the exact commands for the post-bump rerun. Attribute every failure
59 before deciding whether it blocks. Proceed when an unrelated pre-existing failure is reproducible, can be compared
60 after the bump, and does not prevent dependency resolution or the checks needed to detect regressions; do not fix it
61 as part of the bump. Dependency or peer-resolution conflicts, actionable unsafe behavior, or a baseline that cannot
62 provide trustworthy before/after signal block the bump. In that case, stop with
63 `### ⛔ Dependency bump blocked — baseline unusable` and report the exact prerequisite and diagnostics without asking
64 for redundant authorization. Informational notices such as unavoidable deprecations do not block.
65
666. Write all selected Taze updates in one command:
67
68 ```sh
69 bash <skill-dir>/scripts/run-taze.sh --write --include package-a,package-b
70 ```
71
727. For Bun catalogs, rerun `update-bun-catalogs.py` with the same plan and include set plus `--write`. It atomically
73 updates every matching default/named catalog occurrence and preserves each existing `^`, `~`, or empty prefix. Then
74 run `ni` so the repository's package manager updates its lockfile.
75
768. Inspect the manifest and lockfile diff. Rerun the exact baseline commands, plus the narrowest checks that exercise
77 the updated dependencies and any required migrations. Treat every newly introduced error, type issue, check failure
78 (including tests, builds, lint, formatting, codegen, and repository invariants), dependency or peer-resolution
79 conflict, and actionable compatibility or safety warning as caused by the bump unless evidence shows otherwise.
80
819. Fix every issue caused by the bump, including required source or configuration migrations, while preserving intended
82 behavior. Do not suppress diagnostics, weaken validation, or change expected behavior merely to make checks pass.
83 After each fix, rerun the affected check, then rerun the complete recorded suite until it passes. If no clear safe
84 fix exists within the task's authority, stop with `### ⚠️ Dependency regression decision required`. Present all such
85 issues in one table with the evidence, affected locations, fix and revert options, and likely effects. Do not report
86 completion until the user chooses, the fix is applied or the offending update is reverted, the lockfile is
87 regenerated, and the complete suite passes.
88
89## User-Facing Output
90
91Present plans as `### 📦 Dependency plan` with counts and a compact table:
92
93| ID | Plan value | Decision | Package | Current → target | Type | Notes |
94| --- | ---------- | -------- | ------- | ---------------- | ---- | ----- |
95
96Use the plan's exact `apply`, `review-major`, `review`, and `skip-fixed` values alongside plain-language decisions.
97Assign stable IDs to rows needing a choice so the user can answer once. Use `### 🔎 Dry run — no files written` for a
98preview and `### ✅ No selected updates` for a no-op.
99
100Finish applied work with `### 🏁 Dependencies updated`, a tree of changed manifests/lockfiles, and
101`### 🧪 Verification`. Use `### ⚠️ Remaining review` only for non-blocking informational matters, never for an
102unresolved issue caused by the bump. Keep helper JSON, package/version strings, commands, and diagnostics exact and
103undecorated.
104
105## Invariants
106
107- Fixed versions and non-semver protocols remain unchanged unless the user explicitly asks otherwise.
108- Caret ranges are valid for new dependencies and CLIs; do not describe them as unreproducible when a committed lockfile
109 and frozen install control resolution.
110- Package arguments constrain both scan and write phases.
111- The same maturity-period policy applies to scan and write.
112- Bun catalog preview and write use the same accepted Taze plan and selected package set; stale plans never write.
113- Do not infer compatibility from SemVer alone when repository evidence, peer ranges, or release notes indicate
114 otherwise.
115
116Completion requires an attributed, comparison-safe pre-write baseline, a reviewed plan, the retained selected updates, a
117regenerated lockfile, no new failure in the recorded suite or dependency-specific checks, and no unresolved issue caused
118by the bump. Dry-run completion requires the structured plan and zero writes.
gabrielmoreira