Paths: File paths (

shared/

,

references/

,

../ln-*

) are relative to skills repo root. If not found at CWD, locate this SKILL.md directory and go up one level for repo root. If

shared/

is missing, fetch files via WebFetch from

https://raw.githubusercontent.com/levnikolaevich/claude-code-skills/master/skills/{path}

.

ln-821-npm-upgrader

Type: L3 Worker Category: 8XX Optimization

Upgrades Node.js dependencies using npm, yarn, or pnpm with automatic breaking change detection and migration.

Overview

Workflow

Phases: Pre-flight -> Analyze -> Security Audit -> Check Outdated -> Identify Breaking -> Apply Upgrades -> Apply Migrations -> Verify Build -> Report

Phase 0: Pre-flight Checks

package.json

package-lock.json

yarn.lock

pnpm-lock.yaml

Runtime Coordination

Managed runs receive deterministic

runId

summaryArtifactPath

ln-820

Phase 1: Analyze Dependencies

Read

package.json

typescript

@types/*

react

vue

next

vite

webpack

esbuild

@radix-ui/*

tailwindcss

@tanstack/react-query

zustand

lodash

date-fns

eslint

prettier

Phase 2: Security Audit

npm audit --audit-level=high

yarn audit --level high

pnpm audit --audit-level high

Actions:

Phase 3: Check Outdated

npm outdated --json

yarn outdated --json

pnpm outdated --json

Phase 4: Identify Breaking Changes

MANDATORY READ: Load breaking_changes_patterns.md for full patterns.

Detection flow:

1. Compare current vs latest major versions.
2. Check shared breaking-change patterns.
3. Query Context7 or Ref for migration guides before changing code.

Common breaking examples:

Phase 5: Apply Upgrades

Upgrade order:

1. peer dependencies
2. framework packages
3. build tools
4. UI libraries
5. utilities
6. dev dependencies

npm install <package>@latest --save

yarn add <package>@latest

pnpm add <package>@latest

Peer dependency conflicts:

npm install --legacy-peer-deps

npm install --force

MCP Tools for Migration Search

mcp__context7__query-docs

mcp__Ref__ref_search_documentation

Use MCP tools to fetch migration guides before applying non-trivial changes.

Phase 6: Apply Migrations

1. Use MCP tools to find the current migration guide.
2. Apply automated code transforms only when the guide supports them.
3. Log manual follow-up steps for the final report.

Do not hardcode migrations without checking current documentation.

Phase 7: Verify Build

npm run check

npx tsc --noEmit

npm run build

npm test

On failure:

1. Identify the failing package.
2. Search Context7 or Ref for the fix.
3. If unresolved, rollback that package and continue with the remaining candidates.

Phase 8: Report Results

project

packageManager

duration

upgrades.major[]

upgrades.minor[]

upgrades.patch[]

migrations[]

skipped[]

verification

warnings[]

artifact_path

Configuration

Options:
  upgradeType: major          # major | minor | patch
  allowBreaking: true
  autoMigrate: true
  queryMigrationGuides: true
  auditLevel: high
  minimumReleaseAge: 14
  legacyPeerDeps: false
  force: false
  runBuild: true
  runTests: false
  runTypeCheck: true
  rollbackOnFailure: true

Error Handling

Rollback: Restore

package.json

References

• breaking_changes_patterns.md
• npm_peer_resolution.md

Runtime Summary Artifact

MANDATORY READ: Load

shared/references/coordinator_summary_contract.md

Emit a

dependency-worker

Managed mode:

• ln-820

  passes deterministic

  runId

  and exact

  summaryArtifactPath

• write the summary to the provided

  summaryArtifactPath

Standalone mode:

• omit

  runId

  and

  summaryArtifactPath

• write

  .hex-skills/runtime-artifacts/runs/{run_id}/dependency-worker/ln-821--{identifier}.json

Monitor (2.1.98+): For install/audit/build/test commands expected >30s, use

Monitor

Bash(run_in_background=true)

Definition of Done

• Package manifest analyzed and dependencies prioritized
• Security audit completed for the selected package manager
• Outdated packages identified
• Breaking changes checked via patterns plus current docs
• Upgrades applied with rollback on failure
• Build and relevant verification commands pass after upgrades

• dependency-worker

  summary artifact written to the managed or standalone path

Version: 1.1.0 Last Updated: 2026-01-10