# Nuke Deps

> Use when dependencies need a planned audit or upgrade — "nuke deps", "update dependencies", "are our deps safe/outdated", "upgrade to v5" — vulnerable, outdated, unused, or duplicated packages, upgraded in gated waves with majors isolated one at a time, never a blind bulk bump.

- Skill: `b4r7x/nuke-deps` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add b4r7x/nuke-deps`
- Raw SKILL.md: https://api.skillmd.com/api/skills/b4r7x/nuke-deps/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: b4r7x (https://skillmd.com/u/b4r7x)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/b4r7x/nuke-deps

---


# Nuke Deps

A dependency bump is a change to code you did not write, tested by gates you did not design (map: references/family-map.md — a self-contained loop) — which is why "update everything and see" ships breakage. This skill scans first (vulnerable / outdated / unused / duplicated), then upgrades in dependency-ordered waves with gates between each batch, majors strictly one at a time with their migration notes researched before the bump, not after the break.

## Arguments

`[mode]` — `light` (default) | `full` | `plan` (preflight, print, STOP).
`[scope]` — a manifest path (one workspace) | default: every manifest family in the repo (mixed-monorepo protocol in references/stack-adapters.md).
`--ask` — pause at the preflight plan for confirmation; default is no gate — the plan prints and the run starts (references/preflight.md).

## Modes

Tier vocabulary and platform mechanics: references/model-tiers.md.

| | **light** (default) | **full** |
|---|---|---|
| Scanners | clerk | worker |
| Scan depth | tool output (audit/outdated) + unused check | + duplicate/overlap analysis, license flags, install-script review |
| Migration researcher (majors) | session | session |
| Upgrade implementers | worker | worker |
| Validator per batch — one tier above | session | top |
| Majors attempted | security-driven + user-named only | every major, one at a time |
| Cycles per batch | cap 2 | cap 3 |

## Mandates

1. **Scan before touching anything.** The upgrade plan is built from the scan report, confirmed at the plan gate — never "bump and see".
2. **Majors are isolated.** One major per batch, its changelog/migration guide read via docs lookup or web search BEFORE the bump, breaking changes listed in the batch entry. A failing major is reverted whole and recorded as a blocker — never left half-migrated.
3. **Gates between every batch.** The full matching gates table (references/stack-adapters.md) runs after each batch, output verbatim; a red gate stops the wave until fixed or the batch is reverted.
4. **Lockfile changes ride along; nothing else does.** Manifest + lockfile + the minimal source edits a migration requires. No opportunistic refactors.
5. **Unused ≠ delete on sight.** An unused-dep finding carries the grep evidence (zero imports outside the manifest); removal is a batch like any other, gated.
6. **Install scripts and new transitive trust are findings** (full): a dep whose upgrade adds install-time exec or a new git-sourced transitive is flagged before the batch runs.
7. **No `git add` / `git commit` / `git stash`.** Working tree left for review; the report tells the user to commit per-batch if they want bisectable history.

## Artifacts

`run_dir = .nuke/<YYYY-MM-DD>-<HHmmss>-deps-<slug>/` — fresh per run; on collision append `-2`, `-3`, ….

| File | Role |
|---|---|
| `plan.md` | Manifest inventory, scan summary, batch plan, tiers |
| `deps.md` | Full scan: `D-###` findings (vulnerable/outdated/unused/duplicate) with evidence |
| `progress.md` | Per-batch status, gate outputs, reverts, blockers |

## Pipeline

```
Phase 0 preflight → Phase 1 scan → Phase 2 batch plan (into plan gate) → Phase 3 gated upgrade waves → Phase 4 report (STOP)
```

## Phase 0 + 1 — Preflight and scan

Read references/preflight.md. Resolve manifests and baseline gates (run once — a red baseline is recorded; upgrades are then judged on "no NEW failures"). Scanners run the stack's native tooling (`npm audit`/`pnpm audit`, `pip-audit`, `cargo audit`, `govulncheck`, …) plus outdated listings and an unused check (import grep per Mandate 5). Findings → `D-###` in deps.md: package, current → available, severity (vulns carry their advisory ID), evidence. The plan block prints the scan summary AND the proposed batches, then applies (gate only with `--ask`) — the scan is cheap and read-only, so it runs before the plan; all writes come after it. A scanner or gate that cannot run at all follows the unblock protocol in references/preflight.md.

## Phase 2 — Batch plan

Batches ordered: security patches (any semver distance the advisory requires) → patch/minor bulk per workspace → majors one at a time (Mandate 2), dependency-ordered when majors depend on each other (framework before its plugins). Each major batch carries its researched migration notes: breaking changes, codemods available, affected files grepped in advance.

## Phase 3 — Gated upgrade waves

Per batch: implementer applies the bump + the migration edits its notes name → full matching gates (Mandate 3) → fresh validator one tier above verifies gates verbatim, greps for deprecated-API usage the changelog names, checks no NEW type escapes appeared (references/stack-adapters.md table B). Failures → fix cycle (cap per mode) or revert-whole-batch with the blocker recorded in progress.md. Never proceed past a red batch.

## Phase 4 — Report (STOP)

Before/after inventory table (package · from → to · batch · status), vulnerabilities closed by advisory ID, blockers with exactly what broke (verbatim), unused deps removed, majors deferred with their migration-note paths for next time. Run stats + artifacts; calibration line appended to `.nuke/calibration.log` (format in references/preflight.md). Suggest per-batch commits to the user (Mandate 7). STOP.