dev-dependency-management

Dependency Management

Use this skill for package-manager choice, lockfile policy, update strategy, supply-chain controls, and dependency hygiene across common ecosystems. It owns reproducibility and security defaults, not framework-specific app architecture.

Quick Reference

When to Use

• Choose or migrate a package manager.
• Define lockfile, wrapper, or toolchain pinning policy.
• Add, remove, pin, or upgrade dependencies safely.
• Resolve dependency conflicts or transitive-risk issues.
• Set up audits, SBOM generation, provenance checks, or update automation.
• Define dependency policy for monorepos or polyglot repos.

Route Elsewhere

• Framework-specific frontend or backend implementation: use the relevant software skill.
• AppSec architecture beyond the dependency layer: use software-security-appsec.
• CI/CD platform design: use ops-devops-platform.

Defaults

• Lockfile-first installs.
• Pinned package manager or wrapper where the ecosystem supports it.
• Smallest safe dependency change first.
• Patch updates often, majors in isolation.
• SBOM and audit workflow for release artifacts.
• AI-suggested packages are untrusted until verified.

Workflow

1. Identify ecosystem, package manager, lockfile, and wrapper conventions already present.
2. Decide the smallest safe change: add, remove, pin, update, audit, or migrate.
3. Load only the guidance needed for lockfiles, security, monorepo policy, or update strategy.
4. Verify volatile tool behavior and security claims against official sources before recommending migrations.
5. Finish with reproducibility checks, rollback notes, and any audit or SBOM follow-up.

ASCII Flow

dependency management request
  -> identify ecosystem, package manager, lockfile, wrapper, and workspace shape
  -> classify change: add, remove, pin, update, audit, migrate, or policy
  -> choose smallest safe dependency move
  -> check security, provenance, license, transitive risk, and AI package risk
  -> update lockfile or policy according to repo conventions
  -> run reproducibility, test, audit, and SBOM checks where available
  -> document rollback, owner, expiry, and follow-up

Core Decisions

Package-Manager Defaults

Keep repo-local consistency more important than theoretical ecosystem purity.

Lockfile and Toolchain Policy

Minimum rules:

• commit application lockfiles
• use exact lockfile installs in CI
• avoid hand-editing lockfiles
• do not carry multiple lockfiles for one package graph
• prefer repo-local wrappers or toolchain files over global latest installs

Update Strategy

Default cadence:

• patch: small and frequent
• minor: batched and tested
• major: isolated with release-note review and rollback plan
• security: prioritize by exploitability and exposure, not CVSS alone

Supply-Chain Controls

Use:

• official registries where possible
• provenance or signature verification where supported
• SBOM generation for release artifacts (CISA 2025 draft adds mandatory component hash, license, tool name, and generation context fields)
• explicit review of install or build scripts
• expiration on overrides, resolutions, and temporary pins
• pnpm minimumReleaseAge or Renovate minimumReleaseAge to avoid consuming just-published packages (Shai-Hulud, Axios, and Miasma npm compromises 2025-2026 repeatedly show a fast-publish-to-attack window under three hours)
• dependency confusion mitigations: scope all internal packages, audit all org-scoped packages before use
• npm v12 (shipping July 2026) disables install scripts, git dependencies, and remote-URL dependencies by default; plan the CI migration before it lands, and treat any repo still relying on install scripts as a review item, not a blocker to skip

AI-Generated Dependency Risk

Before accepting an AI-suggested package:

• verify it exists
• check for typosquatting risk
• check maintenance and release cadence
• prefer standard library or existing dependencies if feasible
• run the same audit and review workflow as for any other new package

Output Modes

Default to one of these:

• Dependency policy brief: manager choice, lockfile rules, update cadence, and security controls.
• Upgrade plan: scope, batching, testing, rollback, and audit follow-up.
• Dependency audit: health risks, unmaintained packages, graph complexity, and remediation order.
• Monorepo dependency strategy: workspace model, shared policy, and update automation rules.

Known Traps

• Upgrading transitive or security-sensitive packages without checking whether the fix actually lands in the production artifact path.
• Mixing wrapper, lockfile, and package-manager upgrades in one move, which makes rollback and blame assignment much harder.
• Assuming monorepo hoisting or workspace dedupe is harmless when postinstall scripts, peer deps, or native builds are involved.
• Accepting temporary pins or overrides without a removal owner, expiry, and retest trigger.
• Treating SBOM generation as complete supply-chain control while provenance, install scripts, and release process remain unreviewed.

Anti-Patterns

• Mixing package managers or lockfiles casually.
• Installing without the lockfile in CI.
• Migrating ecosystems for novelty instead of clear value.
• Treating AI-suggested packages as trusted by default.
• Leaving temporary overrides in place without owners or expiry.
• Chasing vulnerability counts without considering exploitability and production exposure.

References

Navigation

• Assets: assets/nodejs/package-json-template.json, assets/nodejs/npmrc-template.txt, assets/nodejs/pnpm-workspace-template.yaml, assets/python/pyproject-toml-template.toml, assets/automation/dependabot-config.yml, assets/automation/renovate-config.json, assets/automation/audit-checklist.md, assets/automation/template-dependency-upgrade-playbook.md, assets/automation/template-supply-chain-security.md, assets/automation/template-sbom-vuln-triage-checklist.md
• Scripts and samples: scripts/dep_auditor.py, scripts/README.md, data/sample-dependency-manifest.example.json

Fact-Checking

• Known bugs, regressions, framework/compiler/runtime footguns, and version-specific crash or workaround guidance must be verified against current primary web sources before being treated as current fact.
• Curated source links live in data/sources.json.
• Package-manager defaults, CLI flags, provenance behavior, and SBOM guidance are volatile and should be verified against current official docs before giving definitive recommendations.
• Prefer official package-manager, standards, and security-advisory sources over secondary blogs.

Learnings Loop

Before applying this skill on a non-trivial task, read learnings.consolidated.md in this directory (and learnings.md if present).

After applying it, if you encountered a pattern worth remembering, a mistake worth preventing, or a domain fact that surprised you, append one dated bullet to learnings.md via agents-skills-feedback-loop/scripts/append_learning.py. Do not modify SKILL.md itself.