Specialist Dependency Ally

A dependency management agent that helps you maintain healthy, secure, and up-to-date project dependencies across package ecosystems, handling version conflicts, security vulnerabilities, and upgrade strategies.

When to Use This Agent

Choose Specialist Dependency Ally when:

• Auditing dependencies for security vulnerabilities (CVEs, advisories)
• Planning and executing major dependency upgrades (React 18→19, Node 18→22)
• Resolving version conflicts and peer dependency issues
• Reducing dependency count and bundle size by finding lighter alternatives
• Setting up automated dependency management (Dependabot, Renovate)

Consider alternatives when:

• Building new features that require choosing a library (use a development agent)
• Debugging issues caused by a specific library (use a debugging agent)
• Optimizing build times related to dependencies (use a build engineering agent)

Quick Start

Copy
# .claude/agents/specialist-dependency-ally.yml
name: Specialist Dependency Ally
description: Manage and maintain project dependencies
model: claude-sonnet
tools:
  - Read
  - Edit
  - Bash
  - Glob
  - Grep

Example invocation:

claude "Audit our dependencies for security vulnerabilities, identify outdated packages, and create an upgrade plan prioritized by risk"

Core Concepts

Dependency Health Assessment

Metric	Healthy	Warning	Critical
Age	<1 year behind latest	1-2 years behind	3+ years behind
Vulnerabilities	0 known CVEs	Low severity CVEs	High/Critical CVEs
Maintenance	Active commits, responses	Slow responses	Archived/abandoned
License	MIT, Apache 2.0	LGPL, MPL	GPL, AGPL (if commercial)
Size	<100 KB	100-500 KB	500+ KB
Alternatives	Standard choice	Viable alternatives exist	Better options available

Audit and Upgrade Workflow

Copy
# Step 1: Security audit
npm audit --json > audit-report.json
# or
yarn audit --json > audit-report.json

# Step 2: Check for outdated packages
npx npm-check-updates --format group

# Step 3: Analyze bundle impact
npx bundle-analyzer analyze

# Step 4: Check for deprecated packages
npx depcheck --json

# Step 5: Verify license compliance
npx license-checker --json --production > licenses.json

Upgrade Strategy Template

Copy
## Dependency Upgrade Plan

### Phase 1: Security Fixes (This Sprint)
| Package | Current | Target | CVE | Breaking? |
|---------|---------|--------|-----|-----------|
| lodash | 4.17.15 | 4.17.21 | CVE-2021-23337 | No |
| axios | 0.21.0 | 0.21.4 | CVE-2021-3749 | No |

### Phase 2: Minor Upgrades (Next Sprint)
| Package | Current | Target | Changes | Risk |
|---------|---------|--------|---------|------|
| react-query | 3.39.0 | 3.39.3 | Bug fixes | Low |
| tailwindcss | 3.3.0 | 3.4.1 | New utilities | Low |

### Phase 3: Major Upgrades (Planned)
| Package | Current | Target | Migration Guide | Effort |
|---------|---------|--------|----------------|--------|
| Next.js | 13.5 | 14.1 | nextjs.org/blog/next-14 | 3-5 days |
| React | 18.2 | 19.0 | react.dev/blog/react-19 | 5-10 days |

### Packages to Remove
| Package | Reason | Replacement |
|---------|--------|-------------|
| moment | Deprecated, large bundle | date-fns |
| request | Deprecated | fetch (native) |

Configuration

Parameter	Description	Default
package_manager	Package manager (npm, yarn, pnpm, bun)	Auto-detect
audit_level	Minimum vulnerability severity to report	moderate
upgrade_strategy	Upgrade approach (conservative, balanced, aggressive)	balanced
license_policy	Allowed license types	["MIT", "Apache-2.0", "BSD-*", "ISC"]
auto_update	Configure automated update tool	renovate
lockfile_strategy	Lockfile management (strict, update, regenerate)	strict

Best Practices

1. Upgrade one major dependency at a time and verify between each. Upgrading React, Next.js, and TypeScript simultaneously makes it impossible to identify which upgrade caused a regression. Upgrade one, run the full test suite, verify in staging, then proceed to the next. This adds time but dramatically reduces debugging effort when something breaks.

2. Pin exact versions in applications, use ranges in libraries. Applications deployed to production need reproducible builds — use exact versions ("react": "18.2.0") and commit lockfiles. Libraries published to npm should use ranges ("react": "^18.0.0") to avoid forcing consumers into specific versions that may conflict with their other dependencies.

3. Audit dependencies before adding new ones. Before npm install new-package, check: How large is it? (bundlephobia.com) How many transitive dependencies does it add? Is it actively maintained? Is the license compatible? Could a 10-line utility function replace it? Every dependency is a maintenance liability, a security surface, and a potential supply chain attack vector.

4. Set up automated dependency update tooling with defined merge rules. Configure Renovate or Dependabot to open PRs for dependency updates automatically. Auto-merge patch updates that pass CI. Require manual review for minor updates. Require team discussion for major updates. This keeps the dependency baseline current without requiring developers to manually check for updates.

5. Keep a decision log for why specific versions are pinned. When you pin a dependency to an older version due to a known issue or incompatibility, document why. Without this context, future developers will assume the pin is stale and upgrade, reintroducing the problem. A comment in package.json or a section in the project's context file prevents unnecessary upgrade cycles.

Common Issues

Peer dependency conflicts block installation. Package A requires React ^17.0.0 while Package B requires React ^18.0.0, and npm refuses to install. Use npm install --legacy-peer-deps as a temporary workaround, but investigate the root cause. Often, one package has released a newer version supporting both React versions. Check if the conflict is real (the packages actually break) or advisory (the peer dep range is just outdated).

Bundle size grows uncontrollably as dependencies accumulate. Each new dependency adds transitive dependencies. A seemingly small library can pull in hundreds of kilobytes of code. Monitor bundle size in CI using tools like size-limit or bundlewatch. Set a budget (e.g., max 250 KB gzipped for the main bundle) and enforce it. When the budget is exceeded, analyze the bundle to find the largest contributors and evaluate alternatives.

Dependency updates break the build in CI but work locally. Developers run npm install locally (updating their lockfile) but do not commit the lockfile changes. CI runs npm ci (which uses the committed lockfile) and gets different versions. Always commit lockfile changes. Run npm ci locally before pushing to catch lockfile inconsistencies. In CI, fail the build if the lockfile is out of sync with package.json.