Skill: Dependency Management
Process for adding, updating, auditing, and removing third-party
dependencies in any ecosystem (npm, Maven, pip, Go modules, Cargo…).
Reference: engineering-principles.md §2.8 (Supply Chain), §8 (Simplicity).
Adding a dependency — selection criteria
A new dependency must pay rent. Before adding, check:
Record non-obvious choices (framework, ORM, auth library) as an ADR
(see proc-adr).
Lockfile discipline
- Lockfiles (
package-lock.json, poetry.lock, go.sum…) are always
committed.
- CI installs strictly from the lockfile (
npm ci, --frozen-lockfile) —
never resolution at build time.
- Version ranges in the manifest stay narrow; the lockfile is the truth.
Update cadence
- Automated bot (Dependabot/Renovate) weekly, PR cap ~5 — see the
infra-ci-cd skill for configuration.
- Patch/minor: merge routinely once CI is green.
- Major: one PR per major upgrade, with changelog read and breaking
changes listed in the PR description; never bundle several majors.
- Never let the gap grow — upgrading 20 majors at once is a rewrite.
CVE response
| Severity (CVSS) |
Response window |
| Critical (9.0+) |
Same day — patch or mitigate |
| High (7.0–8.9) |
Within the week |
| Medium/Low |
Next scheduled update cycle |
If no patched version exists: check for a mitigation (config flag, disabling
the vulnerable path), document a suppression with justification and an
expiry date, and track it in docs/structural-analysis.md.
Removal hygiene
- Audit unused dependencies quarterly (
depcheck, mvn dependency:analyze,
or ecosystem equivalent) — every unused package is attack surface.
- When replacing a library, remove the old one in the same PR.
Common mistakes
| Mistake |
Cause |
Solution |
| Left-pad syndrome |
Dependency for trivial code |
Apply the < 50 lines rule |
| Lockfile in .gitignore |
Misunderstanding reproducibility |
Always commit lockfiles |
| Suppression without expiry |
"Temporary" forever |
Date + justification on every suppression |
| Mega-upgrade PR |
Updates postponed for months |
Weekly bot cadence, one major per PR |
| Abandoned transitive dep |
Only direct deps reviewed |
Audit the full tree, not just the manifest |
1---2name: proc-dependency-management3description: Use when adding a new dependency, upgrading existing ones, or auditing the dependency tree. Selection criteria, lockfile discipline, update cadence, CVE response, and removal hygiene for any package ecosystem.4---56# Skill: Dependency Management78Process for adding, updating, auditing, and removing third-party9dependencies in any ecosystem (npm, Maven, pip, Go modules, Cargo…).1011Reference: `engineering-principles.md` §2.8 (Supply Chain), §8 (Simplicity).1213## Adding a dependency — selection criteria1415A new dependency must pay rent. Before adding, check:1617- [ ] **Need:** would < ~50 lines of own code do? Then write the code.18- [ ] **Health:** maintained (commits/releases in the last year), responsive19 to security reports, more than one maintainer.20- [ ] **Footprint:** transitive dependency count; what else it drags in.21- [ ] **License:** compatible with the project (beware copyleft in22 proprietary code).23- [ ] **Security history:** open CVEs, advisories pattern.24- [ ] **Exit cost:** how hard to replace later? Wrap it behind an interface25 if the answer is "very".2627Record non-obvious choices (framework, ORM, auth library) as an ADR28(see `proc-adr`).2930## Lockfile discipline3132- Lockfiles (`package-lock.json`, `poetry.lock`, `go.sum`…) are **always33 committed**.34- CI installs strictly from the lockfile (`npm ci`, `--frozen-lockfile`) —35 never resolution at build time.36- Version ranges in the manifest stay narrow; the lockfile is the truth.3738## Update cadence3940- **Automated bot** (Dependabot/Renovate) weekly, PR cap ~5 — see the41 `infra-ci-cd` skill for configuration.42- **Patch/minor:** merge routinely once CI is green.43- **Major:** one PR per major upgrade, with changelog read and breaking44 changes listed in the PR description; never bundle several majors.45- Never let the gap grow — upgrading 20 majors at once is a rewrite.4647## CVE response4849| Severity (CVSS) | Response window |50|------------------|-----------------|51| Critical (9.0+) | Same day — patch or mitigate |52| High (7.0–8.9) | Within the week |53| Medium/Low | Next scheduled update cycle |5455If no patched version exists: check for a mitigation (config flag, disabling56the vulnerable path), document a suppression with justification and an57expiry date, and track it in `docs/structural-analysis.md`.5859## Removal hygiene6061- Audit unused dependencies quarterly (`depcheck`, `mvn dependency:analyze`,62 or ecosystem equivalent) — every unused package is attack surface.63- When replacing a library, remove the old one in the same PR.6465## Common mistakes6667| Mistake | Cause | Solution |68|---------|-------|----------|69| Left-pad syndrome | Dependency for trivial code | Apply the < 50 lines rule |70| Lockfile in .gitignore | Misunderstanding reproducibility | Always commit lockfiles |71| Suppression without expiry | "Temporary" forever | Date + justification on every suppression |72| Mega-upgrade PR | Updates postponed for months | Weekly bot cadence, one major per PR |73| Abandoned transitive dep | Only direct deps reviewed | Audit the full tree, not just the manifest |