Dependency Management

Quick Reference

Task	Use
Ecosystem defaults and package-manager choice	references/ecosystem-guides.md
Lockfiles and CI install policy	references/lockfile-management.md
Security scanning, SBOMs, and provenance	references/security-scanning.md, assets/automation/template-supply-chain-security.md, assets/automation/template-sbom-vuln-triage-checklist.md
Monorepos and workspace policy	references/monorepo-patterns.md, assets/nodejs/pnpm-workspace-template.yaml
Update strategy and rollback	references/update-strategies.md, assets/automation/template-dependency-upgrade-playbook.md
Add-or-avoid dependency decision	references/dependency-selection-guide.md, references/transitive-dependencies.md
Vulnerability detection	The ecosystem's native audit tool (npm audit, pnpm audit, pip-audit, cargo audit, govulncheck, composer audit) or osv-scanner; see references/security-scanning.md
Vulnerability triage, VEX, EU CRA lookup	references/security-scanning.md
Policy-manifest scorer (not a vulnerability scanner: no advisory database, refuses real manifests, exits 2 on unchecked input)	python3 scripts/dep_auditor.py --help, limits in scripts/README.md

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.

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. Before migrating Node tooling, check the target major's release notes and its script-approval settings using the lookups below; compare them with CI's runtime and required native builds.
5. Finish with reproducibility checks, rollback notes, and any audit or SBOM follow-up.

Upgrade proof and rollback bundle

Treat the manifest and lockfile as one change unit. Before the upgrade, capture the resolved version, integrity/source metadata, transitive dependency delta, install-script delta, and the exact build/test/runtime probes that protect the affected path. Review newly introduced packages and lifecycle scripts even when the requested direct dependency looks harmless.

A rollback instruction must restore both manifest and lockfile to a known pair and state whether caches, generated clients, database state, or persisted wire formats make code rollback insufficient. For a stateful or protocol-changing upgrade, require a forward-compatible migration or a tested downgrade path before rollout. “Revert the dependency bump” is not a complete rollback plan when the new version has already written data or changed an external contract.

Core Decisions

Package-Manager Defaults

Ecosystem	Default for new repos	Version lookup	Key constraint
Node	pnpm unless compat pressure favors npm	npm view pnpm dist-tags (a new major may ship on a non-default tag)	pnpm 11 removed onlyBuiltDependencies in favour of allowBuilds; check the target major's release notes for its runtime and install path, and build settings for script approvals before setting CI policy
Python	uv	uv release notes	Check whether uv is still on 0.x versioning before promising API stability
Rust	Cargo	pinned rust-toolchain.toml	commit Cargo.lock for apps
Go	go modules	go / toolchain lines in go.mod	go.mod + go.sum canonical
Java	Maven wrapper or Gradle wrapper	wrapper properties	wrappers plus BOMs or version catalogs
.NET	PackageReference	global.json SDK pin	PackageReference over packages.config
PHP	Composer	composer.json config.platform	commit composer.lock for apps

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 unpinned global installs

Rule: rules/deps/lockfiles.md loads this invariant when Claude edits a matching file.

Update Strategy

Default cadence:

• patch: small and frequent
• minor: batched and tested
• major: isolated with release-note review and rollback plan
• security: prioritize by reachability and exploitation evidence (KEV listing first, EPSS as a likelihood signal, CVSS as severity only), and record not_affected findings as VEX statements with a justification; see Vulnerability Triage

Supply-Chain Controls

Use:

• official registries where possible
• provenance or signature verification where supported
• SBOM generation for release artifacts, with the minimum-element fields your customer or regulator requires (lookup step in references/security-scanning.md)
• explicit review of install or build scripts
• a build-time static gate on every shipped artifact, not only source code. The gate covers the package or binary and everything bundled into it: vendored and statically linked dependencies, plugins, extension or recipe manifests, and templates. Before publish it checks licenses against an allowlist, known advisories, and allowed sources (no git or path dependencies that bypass the lockfile), and it schema-validates bundled manifests. An artifact that fails does not reach a release channel. A policy file such as cargo-deny's deny.toml is one way to express this
• expiration on overrides, resolutions, and temporary pins
• a release-age delay (pnpm minimumReleaseAge, Renovate minimumReleaseAge, Dependabot cooldown) to avoid consuming just-published packages; it is one layer, not a fix, because several historical npm compromises were live for only hours before removal (see the incident patterns in references/security-scanning.md)
• dependency confusion mitigations: scope all internal packages, audit all org-scoped packages before use
• EU market: if you ship products with digital elements in the EU, look up which Cyber Resilience Act (Regulation (EU) 2024/2847) vulnerability-reporting obligations apply to you before designing the triage workflow; see EU Cyber Resilience Act Lookup
• Before adopting an npm major, read its versioned configuration docs and changelog for dependency lifecycle-script approvals and git/remote dependency defaults. Check required native builds and sources in CI, and review each approval rather than enabling all scripts.

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

Rule: rules/common/dependencies.md loads this invariant in every coding session.

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.

• Treating a clean dep_auditor.py run as an audit: it reads self-declared flags only. Its input requires an explicit dependency list (use [] for a dependency-free ecosystem), boolean policy flags, non-negative integer ages when provided, and a scan date that is not in the future; malformed declarations exit 2.

References

File	What it covers
references/ecosystem-guides.md	Per-ecosystem package-manager defaults, CI install commands, and watchouts for Node, Python, Rust, Go, Java, .NET, PHP
references/lockfile-management.md	Lockfile matrix, golden rules, per-ecosystem exact-install commands, CI rules, and drift recovery
references/security-scanning.md	Native audit commands, SBOM generation, provenance controls, Dependabot/Renovate usage, and triage workflow
references/monorepo-patterns.md	JS/TS workspace defaults, pnpm supply-chain settings, polyglot structure, and version governance
references/dependency-selection-guide.md	Add-or-avoid decision criteria, graph inspection commands, AI-suggested package checklist
references/update-strategies.md	Update cadence table, batch-by-risk workflow, bot policy, and rollback rule
references/transitive-dependencies.md	Tree inspection, override patterns, deduplication, and resolution decision tree
references/license-compliance.md	License risk table, GPL decision tree, automated tooling, CI integration, and SBOM generation commands
references/version-conflict-resolution.md	Conflict types, per-manager diagnostic commands, forced resolution syntax, and pnpm catalogs
references/container-dependency-patterns.md	Multi-stage build patterns, layer caching, vulnerability scanning (Trivy/Grype), and reproducible base image pinning
references/semver-guide.md	SemVer constraint syntax for npm, Python, and Cargo with common pitfalls
references/anti-patterns.md	Critical and moderate anti-patterns with corrective examples

Curated source links live in data/sources.json.

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

Learnings Loop

When prior decisions or pitfalls are relevant, consult learnings.consolidated.md if present; use learnings.md only for needed history or as the available fallback. Otherwise skip both.

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.