Better Dependencies

Improve dependency health without chasing versions

Minimize supply-chain and maintenance burden while preserving compatibility. Treat an upgrade as a migration decision, not housekeeping.

Own dependency decisions

Own direct and transitive package necessity, version and runtime compatibility, health, deprecation, advisories, lockfiles, redundant capability, and migration planning.

Do not recommend architectural replacement merely because another library is fashionable. Coordinate boundary changes with better-architecture, custom-code simplification with better-simplicity, and upgrade verification with better-testing.

Review workflow

1. Inventory the dependency surface

Inspect every relevant manifest and lockfile in scope. Identify:

• direct, development, optional, peer, build, and platform dependencies;
• supported language, runtime, framework, and operating-system versions;
• workspaces, overrides, resolutions, patches, vendored code, and generated clients;
• imported APIs and the actual capability each direct package supplies;
• multiple lockfiles, unpinned sources, local paths, or manifest/lock mismatches;
• deployment and library consumers that constrain upgrades.

Use the ecosystem's native package manager for inspection. Do not rewrite a lockfile with a different tool.

2. Classify candidates

Investigate:

• published security advisories that affect the resolved version and usage;
• deprecated packages or APIs with an official migration path;
• unsupported versions relative to the project's runtime;
• abandoned packages only when maintenance evidence and risk are credible;
• packages that overlap substantially and increase bundle or maintenance cost;
• direct dependencies used for one trivial, stable operation available in the standard library;
• dependencies declared but not imported or required by tooling;
• version conflicts, duplicated majors, invalid peer ranges, or incompatible transitive constraints;
• lockfiles that are missing, stale, non-reproducible, or inconsistent with policy;
• framework or runtime upgrades blocked by a dependency.

An old publication date or available major version is not a finding by itself.

3. Verify current external facts

When network access is available, prefer primary sources:

• official package registry metadata;
• maintainer release notes and migration guides;
• official runtime or framework compatibility tables;
• ecosystem or vendor security advisory databases;
• upstream repository support policy.

Record the date and source. Distinguish a published advisory from generic package-age concern. If current facts cannot be checked, mark them Not verified and do not assert abandonment, security exposure, compatibility, or the correct target version.

4. Evaluate the decision

For every remove, replace, or upgrade candidate, assess:

• verified benefit and urgency;
• breaking changes across used APIs;
• support for the project's current runtime and platforms;
• maturity and support status of the target version;
• transitive and peer-dependency effects;
• lockfile and build-system impact;
• test and rollout coverage;
• migration effort, rollback path, and operational risk.

Choose the smallest target that resolves the evidenced problem. The newest version is not automatically the right target.

5. Prefer native capability carefully

Replace a package with the standard library only when the native facility is supported by every target runtime and preserves edge cases, security behavior, locale, parsing, error semantics, and performance required by current callers.

Evidence requirements

For each finding, provide:

• manifest and lockfile locations;
• resolved current version and actual usage;
• verified source for advisory, deprecation, compatibility, or support claims;
• recommended action and target, if any;
• breaking changes relevant to this codebase;
• migration and rollback path;
• confidence, change risk, and verification commands.

Do not report a package-manager audit total without establishing that the advisory affects the resolved dependency and relevant runtime surface.

Implementation rules

When asked to implement:

• update one related dependency set at a time;
• read official migration notes before editing code;
• use the native package manager and commit the resulting lockfile changes;
• keep unrelated transitive churn out when the package manager permits;
• update code only for confirmed breaking changes;
• run build, type, unit, integration, and package-specific checks as relevant;
• do not suppress advisories or relax peer constraints merely to obtain a clean command.

Standalone review output

When invoked directly, return:

1. Dependency inventory — manifests, lockfiles, runtimes, tools, and external sources inspected.
2. Findings — current version, evidence, impact, recommended target or removal, migration cost, confidence, and change risk.
3. Keep as-is — dependencies or versions deliberately retained and why.
4. Migration sequence — grouped by compatibility and rollback boundary.
5. Verification — exact commands, external fact date, results, and gaps.

If no dependency action has verified positive value, state No actionable dependency findings.

Guardrails

• Never recommend an upgrade merely because a newer version exists.
• Never claim a vulnerability, abandonment, or compatibility fact without a current authoritative source.
• Never jump to a major version without reading breaking changes and migration guidance.
• Never replace a mature dependency with custom code without accounting for edge cases and ownership.
• Never remove a seemingly unused dependency before checking build, generated, plugin, and runtime loading paths.
• Never hand-edit generated lockfile entries.
• Never combine unrelated major upgrades into one migration.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: NicolasYusim
• Source: NicolasYusim/better-codebase
• License: MIT

Install and usage instructions live in the source repository linked above.