diegosouzapw 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.mdexists with package manager info- Understand the project's dependency management approach
Dependency Operations
Adding a New Dependency
Procedure:
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?)
Evaluate the package:
- Check download stats / popularity
- Check last update date
- Check open issues / security history
- Check transitive dependencies (avoid bloat)
Add with pinned version:
# npm npm install package-name@version --save-exact # pip pip install package-name==version # cargo cargo add package-name@versionUpdate lock file: Ensure lock file is committed
Run validation: Full test suite after adding
Document: Note in CHANGELOG if user-facing
Updating Dependencies
Routine Updates:
- Check for available updates
- Review changelogs for breaking changes
- Update one package at a time (easier to debug)
- Run full test suite after each update
- Commit with clear message
Security Updates (Priority):
- Identify severity (critical/high/medium/low)
- For critical/high: update immediately
- For medium/low: batch with routine updates
- Test thoroughly (security patches can break things)
- Document in CHANGELOG
Removing Dependencies
- Identify why it's being removed
- Find all usages in codebase
- Remove usages first
- Remove from package manifest
- Update lock file
- Run full test suite
- 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:
- Add dependency evaluation to plan
- Note license and security considerations
- Plan for testing after addition
During Implementation
When adding dependency:
- Follow the addition procedure above
- Update focus.md with dependency added
- 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