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)

npm install pkg

yarn add pkg

pnpm add pkg

npm install -D pkg

yarn add -D pkg

pnpm add -D pkg

npm uninstall pkg

yarn remove pkg

pnpm remove pkg

npm update pkg

yarn upgrade pkg

pnpm update pkg

npm audit

yarn audit

pnpm audit

package-lock.json

yarn.lock

pnpm-lock.yaml

Python (pip/poetry/pipenv)

pip install pkg

poetry add pkg

pipenv install pkg

pip install pkg

poetry add -D pkg

pipenv install -d pkg

pip uninstall pkg

poetry remove pkg

pipenv uninstall pkg

pip install -U pkg

poetry update pkg

pipenv update pkg

requirements.txt

poetry.lock

Pipfile.lock

Rust (cargo)

cargo add pkg

cargo add --dev pkg

cargo remove pkg

cargo update -p pkg

cargo audit

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