Dependencies Workflow

Purpose

Safely manage project dependencies including adding new packages, updating existing ones, and handling security advisories.

When to Use

• Adding a new dependency to the project
• Updating dependencies (routine or security)
• Auditing dependencies for vulnerabilities
• Investigating dependency conflicts
• Removing unused dependencies

Preconditions

• .agent/constitution.md exists with package manager info
• Understand the project's dependency management approach

Dependency Operations

Adding a New Dependency

Procedure:

1. Justify the addition:

   • What problem does it solve?
   • Is there an existing alternative in the project?
   • What is the package's maintenance status?
   • What is the license? (compatible with project?)

2. Evaluate the package:

   • Check download stats / popularity
   • Check last update date
   • Check open issues / security history
   • Check transitive dependencies (avoid bloat)

3. Add with pinned version:

   # npm
   npm install package-name@version --save-exact
   
   # pip
   pip install package-name==version
   
   # cargo
   cargo add package-name@version
   

4. Update lock file: Ensure lock file is committed

5. Run validation: Full test suite after adding

6. Document: Note in CHANGELOG if user-facing

Updating Dependencies

Routine Updates:

1. Check for available updates
2. Review changelogs for breaking changes
3. Update one package at a time (easier to debug)
4. Run full test suite after each update
5. Commit with clear message

Security Updates (Priority):

1. Identify severity (critical/high/medium/low)
2. For critical/high: update immediately
3. For medium/low: batch with routine updates
4. Test thoroughly (security patches can break things)
5. Document in CHANGELOG

Removing Dependencies

1. Identify why it's being removed
2. Find all usages in codebase
3. Remove usages first
4. Remove from package manifest
5. Update lock file
6. Run full test suite
7. Document removal reason

Security Audit

Running an Audit

# npm
npm audit

# pip (with safety)
safety check

# cargo
cargo audit

# yarn
yarn audit

Audit Report Format

## Dependency Audit - [date]

### Summary
- Total dependencies: X
- Direct: Y
- Transitive: Z
- Vulnerabilities found: N

### Vulnerabilities

| Package | Severity | CVE | Fix Available | Action |
|---------|----------|-----|---------------|--------|
| pkg-a | CRITICAL | CVE-XXXX | Yes (v2.0.1) | Update |
| pkg-b | HIGH | CVE-YYYY | No | Evaluate alternatives |
| pkg-c | MEDIUM | CVE-ZZZZ | Yes (v1.2.3) | Schedule update |

### Recommendations
1. Immediate: Update pkg-a to v2.0.1
2. Short-term: Replace pkg-b with alternative
3. Routine: Update pkg-c in next batch

Package Manager Reference

Node.js (npm/yarn/pnpm)

Operation	npm	yarn	pnpm
Add	npm install pkg	yarn add pkg	pnpm add pkg
Add dev	npm install -D pkg	yarn add -D pkg	pnpm add -D pkg
Remove	npm uninstall pkg	yarn remove pkg	pnpm remove pkg
Update	npm update pkg	yarn upgrade pkg	pnpm update pkg
Audit	npm audit	yarn audit	pnpm audit
Lock file	package-lock.json	yarn.lock	pnpm-lock.yaml

Python (pip/poetry/pipenv)

Operation	pip	poetry	pipenv
Add	pip install pkg	poetry add pkg	pipenv install pkg
Add dev	pip install pkg (manual)	poetry add -D pkg	pipenv install -d pkg
Remove	pip uninstall pkg	poetry remove pkg	pipenv uninstall pkg
Update	pip install -U pkg	poetry update pkg	pipenv update pkg
Lock file	requirements.txt	poetry.lock	Pipfile.lock

Rust (cargo)

Operation	Command
Add	cargo add pkg
Add dev	cargo add --dev pkg
Remove	cargo remove pkg
Update	cargo update -p pkg
Audit	cargo audit
Lock file	Cargo.lock

Constraints

Must Check with Constitution

• Allowed package sources (registries)
• Version pinning policy
• Lock file policy (commit or not)
• Audit requirements
• License restrictions

Safety Rules

• ❌ Never add dependencies without justification
• ❌ Never update major versions without review
• ❌ Never ignore critical security vulnerabilities
• ❌ Never remove lock files
• ✅ Always run tests after dependency changes
• ✅ Always commit lock file changes
• ✅ Always document significant dependency changes

Integration with AgentOps

During Planning

If task requires new dependency:

1. Add dependency evaluation to plan
2. Note license and security considerations
3. Plan for testing after addition

During Implementation

When adding dependency:

1. Follow the addition procedure above
2. Update focus.md with dependency added
3. Note in task's files_actually_changed

During Review

Check for:

• Unnecessary new dependencies
• Outdated dependencies with known vulnerabilities
• Unused dependencies that can be removed

Output

Update .agent/focus.md:

## Just did
- Added dependency: package-name@1.2.3
  - Reason: needed for feature X
  - License: MIT (compatible)
  - Tests: PASS

Create task for security issues:

## T-XXXX — Update vulnerable dependency
- Type: security
- Priority: P0
- Description: pkg-a has CRITICAL vulnerability CVE-XXXX
- Action: Update to v2.0.1