From clean-code-codex
Enforces dependency health rules (DEP-1 through DEP-5). Loaded by the conductor for dependency update operations and CI full-check runs. Detects known vulnerabilities, version lag, unused dependencies, misclassified dev/prod dependencies, and unpinned production versions. Invokes scripts/dep_audit.sh for automated vulnerability scanning. Activated by: "check dependencies", "update deps", "CVE", "vulnerability scan", "npm audit".
How this skill is triggered — by the user, by Claude, or both
Slash command
/clean-code-codex:dep-checkopusThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
**Hook coverage check (run first)**:
Hook coverage check (run first):
Before invoking dep_audit.sh, check whether the hook already ran the
vulnerability scan for the current manifest in this session:
cat "$COVERAGE_FILE" 2>/dev/null # COVERAGE_FILE = /tmp/codex-hook-coverage-<PROJECT_HASH>.jsonl
If the coverage file contains one or more records where "rule" is "DEP-1"
and "file" matches the current manifest being reviewed, the DEP-1 vulnerability
scan has already run this session. Skip straight to DEP-2 through DEP-5 analysis.
Log: "Skipping DEP-1 vulnerability scan — already reported by hook this session."
If no matching DEP-1 coverage record exists, proceed with the full scan below.
For automated vulnerability scanning: invoke
scripts/dep_audit.sh and parse its JSON output before performing manual checks.
Requires Python 3.12+ (used by the internal normalizer).
Precedence in the overall system: SEC → TDD → ARCH/TYPE → DEP-1 (BLOCK) → DEP-2 through DEP-5.
Severity: BLOCK | Languages: * | Source: CCC
What it prohibits: Shipping code that depends (directly or transitively) on a package with a published CVE or known security advisory at HIGH or CRITICAL severity.
Detection:
scripts/dep_audit.shvulnerabilities array{ "package": "...", "vulnerable_range": "...", "patched": "...", "cve": "...", "severity": "..." }
Note: vulnerable_range is the affected semver range (e.g. <2.0.1). The installed version is
not available from npm/yarn/pnpm audit JSON; omit the installed version from DEP-1 citations.agent_action:
DEP-1 (BLOCK): Known vulnerability in '{package}' (affected range: {vulnerable_range}) — {cve} ({severity}). Patched in v{patched}.{upgrade_command}
b. Run test suite to verify no breaking changes
c. If breaking changes exist: document the migration path; do not downgradeDEP-1 (BLOCK): No patched version available — evaluate mitigation or replacementBypass prohibition: "We'll fix it next sprint", "it's a transitive dependency" → Refuse. Cite DEP-1. Transitive vulnerability is still a vulnerability.
Severity: WARN | Languages: * | Source: CCC
What it prohibits: Dependencies that are 2 or more major versions behind the current stable release. Major version lag accumulates breaking changes and unmaintained APIs, making future upgrades exponentially harder.
Threshold: Current stable major version − installed major version ≥ 2
Examples:
[email protected] when [email protected] is current: lag = 2 → WARN[email protected] when [email protected] is current: lag = 2 → WARN[email protected] when [email protected] is current: lag = 1 → OK (INFO at most)Detection:
package.json, pyproject.toml, go.mod, Cargo.toml)agent_action:
DEP-2 (WARN): '{package}' is {current_major} — current stable is {latest_major} ({lag} major versions behind).--fix — major upgrades require human reviewSeverity: WARN | Languages: typescript, javascript, python | Source: CCC
What it prohibits: Packages listed in the manifest that are not imported anywhere in the project's source files. Unused dependencies inflate install size, widen attack surface, and mislead future developers.
Go note: Go's module system and go mod tidy handle this natively. DEP-3
does not apply to Go — use go mod tidy instead.
Rust note: Cargo does not auto-detect unused crates. Use cargo machete or
cargo udeps. DEP-3 applies.
Detection:
agent_action:
DEP-3 (WARN): '{package}' is declared but never imported.@types/*)
that doesn't need an explicit import?
--fix: remove the unused package entry (requires confirmation for ambiguous cases)Severity: WARN | Languages: typescript, javascript, python | Source: CCC
What it prohibits: Packages that are only used in tests, build tooling, or
linting being declared as production dependencies (not devDependencies /
dev extras / optional dependencies). This bloats production images and
deployment artifacts.
Applies to:
package.json: test frameworks (jest, vitest, mocha), linters (eslint, prettier),
type checkers, build tools (webpack, esbuild, vite) in dependencies instead of
devDependenciespyproject.toml / setup.cfg: pytest, black, mypy, ruff in dependencies
instead of [dev] or [tool.poetry.group.dev]Detection:
dependencies (production) section of the manifestjest, vitest, mocha, pytest, hypothesis, unittesteslint, prettier, ruff, mypy, black, pylintwebpack, vite, esbuild, babel, tsc (standalone)@types/* packagesagent_action:
DEP-4 (WARN): '{package}' is a dev-only tool listed in production dependencies.devDependencies / dev extras--fix: move the entry in the manifest (no version change)Severity: INFO | Languages: typescript, javascript, python | Source: CCC
What it monitors: Production dependencies (in dependencies, not
devDependencies) declared with loose version ranges (^, ~, *, >=)
rather than exact pinned versions. Loose ranges can pull in breaking patch
releases or subtle behaviour changes between environments.
Recommended practice:
package-lock.json, yarn.lock, poetry.lock, Cargo.lock)
provide runtime pinning, but manifest pins make intent explicit.Detection:
^, ~, *, or bare range specifiersagent_action:
DEP-5 (INFO): '{package}' uses loose version range '{range}'. Consider pinning for reproducible builds.Report schema: see skills/conductor/shared-contracts.md.
npx claudepluginhub mikecubed/clean-code-codex --plugin clean-code-codexAudits dependencies for vulnerabilities, outdated versions, transitive issues, and licenses in Node.js, Python, PHP, Ruby, Go, and Rust projects using npm audit, pip-audit, and equivalents.
Analyzes project dependencies for vulnerabilities, licensing issues, outdated packages, and supply chain risks. Provides prioritized remediation strategies and upgrade paths.
Audits project dependencies for bloat, unused packages, security risks, supply-chain issues, and upgrades by building import graphs and verifying call sites in npm, pip, Cargo, Go, Ruby projects.