dependency-manager

name	dependency-manager
source	botcore
description	Guides dependency evaluation, selection, and lifecycle management for software projects. Covers package health assessment (OpenSSF Scorecard, maintenance signals, popularity metrics), vendoring vs forking decisions, major version upgrade strategies, automated update tooling (Dependabot, Renovate), supply chain security (SLSA, Sigstore, SBOM, provenance), monorepo dependency patterns, and agentic workflows for dependency operations. Use when evaluating new packages, adding dependencies, upgrading major versions, configuring automated updates, auditing dependency health, making vendor-or-fork decisions, or securing the software supply chain. Triggers: dependency, package, npm install, pip install, cargo add, upgrade, update, vendoring, fork, supply chain, SBOM, SLSA, Dependabot, Renovate, lockfile, vulnerability, dependency health, monorepo dependencies.
version	1.0.0
triggers	["dependency","package","npm install","pip install","cargo add","add dependency","upgrade dependency","update dependency","vendoring","fork dependency","supply chain","SBOM","SLSA","Dependabot","Renovate","lockfile","dependency health","dependency audit","monorepo dependencies","package evaluation","major version upgrade","dependency security"]
portable	true

Dependency Management

Expert guidance for evaluating, selecting, securing, and maintaining software dependencies across their full lifecycle.

Capabilities

1. Evaluate packages -- Assess health, maintenance, security posture, and fitness of candidate dependencies before adoption
2. Add dependencies -- Select the right package with minimal transitive footprint, pin versions, and update lockfiles
3. Upgrade dependencies -- Plan and execute minor, patch, and major version upgrades safely
4. Configure automation -- Set up Dependabot, Renovate, or similar tools for continuous dependency updates
5. Vendor or fork -- Decide when to vendor, fork, wrap, or directly depend on third-party code
6. Secure the supply chain -- Apply SLSA, Sigstore, SBOM, and provenance verification to dependency pipelines
7. Manage monorepo dependencies -- Handle shared versions, workspace protocols, and internal package references
8. Agentic dependency operations -- Guide AI agents through safe dependency evaluation and modification workflows

Routing Logic

Request type	Load reference
Evaluating a new package, health check, fitness assessment	references/package-evaluation.md
Vendoring, forking, wrapping, or inlining dependencies	references/vendoring-and-forking.md
Major version upgrades, migration planning, breaking changes	references/version-upgrades.md
Dependabot, Renovate, automated update configuration	references/automated-updates.md
SLSA, Sigstore, SBOM, provenance, supply chain security	references/supply-chain-security.md
Monorepo patterns, workspaces, shared versions, catalogs	references/monorepo-patterns.md
Agentic workflows, AI agent dependency operations	references/agentic-workflows.md
Vulnerability scanning, audit commands, remediation	references/vulnerability-scanning.md

Core Principles

1. Minimize Dependency Surface

Every dependency is a liability -- it adds maintenance burden, security exposure, and build complexity. Before adding a package, ask: Can we achieve this with the standard library or existing dependencies? Is the functionality worth the cost of another node in the dependency graph?

2. Evaluate Before Adopting

Never add a dependency without assessment. Check maintenance activity, security posture, license compatibility, transitive dependency count, and download trends. A package that solves today's problem but is abandoned tomorrow creates technical debt.

3. Pin and Lock

Always use lockfiles (package-lock.json, poetry.lock, Cargo.lock, go.sum). Pin direct dependencies to exact versions or tight semver ranges in production. Lockfiles must be committed to version control -- they are the source of truth for reproducible builds.

4. Automate Updates, Review Thoughtfully

Use automated update tools (Dependabot, Renovate) to surface available updates, but never blindly merge. Require CI to pass, review changelogs for breaking changes, and enforce a minimum release age for auto-merged updates to avoid supply chain attacks via newly published malicious versions.

5. Secure the Supply Chain

Verify provenance of packages. Use registry-native integrity checks (npm integrity, pip --require-hashes, cargo checksums). Adopt SBOM generation and SLSA provenance verification for critical software. Treat AI-suggested packages with extra scrutiny -- hallucinated package names (slopsquatting) are a real attack vector.

6. Prefer Wrapping Over Direct Coupling

Isolate third-party dependencies behind internal interfaces (wrappers, adapters, facades). This reduces blast radius when upgrading or replacing a dependency and keeps domain code decoupled from external APIs.

7. Keep Dependency Trees Shallow

Deep transitive dependency chains amplify risk. Prefer packages with few transitive dependencies. When evaluating alternatives, the package with fewer sub-dependencies is often the better choice, all else being equal.

Workflow

Adding a New Dependency

1. Justify the Need

• Confirm the functionality cannot be achieved with the standard library
• Confirm no existing dependency already provides this capability
• Document why this dependency is needed (PR description or ADR)

2. Evaluate Candidates

• Compare at least 2 alternatives when feasible
• Run the Package Health Assessment (see references/package-evaluation.md)
• Check license compatibility with your project
• Review transitive dependency count (npm ls, pip show, cargo tree)
• Search for known vulnerabilities (npm audit, pip-audit, cargo audit)

3. Install and Configure

• Install with exact version or tight range
• Verify lockfile is updated and committed
• Add to appropriate dependency group (production vs dev vs optional)
• Create wrapper/adapter if the dependency touches more than 3 files

4. Validate

• Run full test suite
• Verify build succeeds in CI
• Check bundle size impact (for frontend packages)
• Run security audit with no new high/critical findings

Upgrading a Dependency

1. Assess the Upgrade

• Read changelog and release notes for all versions between current and target
• Identify breaking changes and required code modifications
• For major upgrades, upgrade through each major version sequentially

2. Execute the Upgrade

• Update version in manifest and regenerate lockfile
• Apply code changes required by breaking changes
• Run full test suite and fix failures
• Test in staging/preview environment before merging

3. Verify

• CI passes with no regressions
• No new security vulnerabilities introduced
• Bundle size impact is acceptable
• Performance benchmarks show no regressions

Quick Reference -- Package Health Signals

Signal	Healthy	Warning	Critical
Last commit	< 3 months	3-12 months	> 12 months
Open issues response	Maintainer responds	Slow response	No response
Release cadence	Regular releases	Infrequent	None in 12+ months
Known vulnerabilities	0 high/critical	Patched within 30d	Unpatched high/critical
Downloads trend	Stable or growing	Declining	Steep decline
Bus factor	3+ maintainers	2 maintainers	1 maintainer
License	OSI-approved, compatible	Uncommon but compatible	Incompatible or none
Transitive deps	< 10	10-50	> 50
OpenSSF Scorecard	7+	4-6	< 4

Quick Reference -- Ecosystem Commands

Task	npm/Node	Python/pip	Rust/Cargo	Go
Add dependency	npm install pkg	pip install pkg	cargo add pkg	go get pkg
Audit vulnerabilities	npm audit	pip-audit	cargo audit	govulncheck ./...
List dependency tree	npm ls --all	pipdeptree	cargo tree	go mod graph
Check outdated	npm outdated	pip list --outdated	cargo outdated	go list -m -u all
Update lockfile	npm install	pip freeze > ...	cargo update	go mod tidy
Verify integrity	npm ci	pip install --require-hashes	built-in	go mod verify

Checklist

Before Adding a Dependency

• Justification: Need documented; standard library cannot fulfill it
• Health check: Package passes health assessment (see quick reference above)
• License: Compatible with project license
• Security: No unpatched high/critical vulnerabilities
• Size: Transitive dependency count is acceptable
• Alternatives: At least one alternative was considered

Ongoing Maintenance

• Automation: Dependabot or Renovate configured for the repository
• Lockfile: Committed to version control and kept up to date
• Audit: npm audit / pip-audit / cargo audit runs in CI
• SBOM: Generated for releases (if required by compliance)
• Review cadence: Dependencies reviewed quarterly for health signals
• Wrapper pattern: High-churn dependencies isolated behind interfaces

Supply Chain Security

• Integrity: Lockfile hashes verified during CI install (npm ci, --require-hashes)
• Provenance: Signed provenance checked for critical packages
• Slopsquatting: AI-suggested package names verified against registry before install
• Scoped packages: Private packages use scoped names to prevent confusion attacks
• Registry config: .npmrc / pip.conf restricts to trusted registries

When to Escalate

Escalate to human review when any of these conditions arise:

• License conflict -- Candidate dependency has a viral license (GPL, AGPL) and the project is proprietary
• Sole maintainer abandonment -- Critical dependency has a single maintainer who has stopped responding
• Supply chain incident -- Evidence of typosquatting, dependency confusion, or compromised package
• Major version jump -- Upgrading across 2+ major versions with extensive breaking changes
• Vendoring decision -- Team must decide whether to vendor, fork, or replace a problematic dependency
• Transitive vulnerability -- High/critical CVE in a transitive dependency with no upstream fix available
• Compliance requirement -- SBOM, SLSA, or provenance requirements mandated by contract or regulation
• AI-hallucinated package -- Agent suggests installing a package that does not exist in the registry