gh-xloxn69-agileflow/commands/packages.md

description, allowed-tools

description	allowed-tools
packages	Bash, Read, Edit, Write, Glob, Grep

packages

Manage project package dependencies (npm, pip, cargo, etc.) with dashboard, updates, and security audits.

Prompt

ROLE: Package Dependency Manager

INPUTS (optional)

• ACTION=dashboard|update|audit (default: dashboard)
• SCOPE=all|security|major|minor|patch (for ACTION=update, default: all)
• OUTPUT=markdown|html|json|csv (for ACTION=dashboard, default: markdown)
• INCLUDE_DEV=yes|no (default: yes)
• SAVE_TO= (default: docs/08-project/dependencies-dashboard.md)
• AUTO_PR=yes|no (for ACTION=update, default: no, ask first)

---

ACTION=dashboard (default)

Generate comprehensive dashboard of all project dependencies.

Detection

Scan for dependency manifests:

• Node.js: package.json, package-lock.json
• Python: requirements.txt, Pipfile, pyproject.toml
• Ruby: Gemfile, Gemfile.lock
• Go: go.mod, go.sum
• Rust: Cargo.toml, Cargo.lock
• Java: pom.xml, build.gradle
• .NET: *.csproj, packages.config
• PHP: composer.json

Analysis

For each dependency, collect:

1. Name: Package name
2. Current Version: Installed version
3. Latest Version: Most recent available
4. Type: Production / Development / Peer
5. Status: Up-to-date / Minor update / Major update / Deprecated
6. Vulnerabilities: Known CVEs
7. License: Software license
8. Last Updated: When dependency was last updated upstream
9. Dependents: How many project files import it

Data Sources

• npm outdated, pip list --outdated, etc.
• npm audit, pip-audit, etc.
• Registry APIs (npmjs.com, pypi.org, crates.io, etc.)
• License scanners
• Import/usage analysis (grep)

Dashboard Format (Markdown)

# Dependencies Dashboard

**Project**: <name>
**Generated**: 2025-10-25 10:00:00 UTC
**Total Dependencies**: 145 (prod: 98, dev: 47)

---

## Summary

| Category | Count | Action Needed |
|----------|-------|---------------|
| 🔴 Critical Vulnerabilities | 2 | Update immediately |
| 🟠 Major Updates | 12 | Review breaking changes |
| 🟡 Minor Updates | 28 | Safe to update |
| 🟢 Up-to-date | 85 | No action |
| ⚪ Deprecated | 3 | Find alternatives |

---

## Critical Vulnerabilities 🔴

### express@4.16.0
**Current**: 4.16.0 → **Latest**: 4.18.2 (+2 major)
**Severity**: HIGH (CVSS 7.5)
**CVE**: CVE-2022-24999
**Description**: ReDoS vulnerability in Express.js routing
**Fix**: `npm install express@4.18.2`
**Affected**: 3 files import this
**License**: MIT

---

[Additional sections: Deprecated Packages, Major Updates, Minor/Patch Updates, License Compliance, Size Analysis, etc.]

---

## Maintenance Score: 78/100

**Breakdown**:
- Security: 60/100 (2 critical vulnerabilities)
- Freshness: 80/100 (most deps recent)
- License compliance: 95/100 (2 GPL warnings)
- Bundle size: 75/100 (some optimization possible)

**Recommendation**: Address security issues immediately, then plan regular maintenance.

Visualization (HTML Output)

If OUTPUT=html, generate interactive dashboard with:

• Color-coded status badges
• Sortable/filterable tables
• Dependency graph visualization (D3.js or Mermaid)
• Click to expand details
• Quick action buttons ("Update", "Learn more")

JSON Output

If OUTPUT=json, provide structured data for tooling:

{
  "generated": "2025-10-25T10:00:00Z",
  "project": "my-app",
  "summary": {
    "total": 145,
    "production": 98,
    "development": 47,
    "critical": 2,
    "major_updates": 12,
    "minor_updates": 28,
    "up_to_date": 85,
    "deprecated": 3
  },
  "vulnerabilities": [...],
  "outdated": [...],
  "deprecated": [...],
  "licenses": {...}
}

---

ACTION=update

Automatically update project dependencies with security audit.

Detection & Analysis

1. Detect package manager(s):

   • Node.js: package.json, package-lock.json, yarn.lock, pnpm-lock.yaml
   • Python: requirements.txt, Pipfile, pyproject.toml, poetry.lock
   • Ruby: Gemfile, Gemfile.lock
   • Go: go.mod, go.sum
   • Rust: Cargo.toml, Cargo.lock
   • Java: pom.xml, build.gradle
   • .NET: *.csproj, packages.config

2. Run appropriate outdated check:

   • npm outdated --json
   • pip list --outdated --format=json
   • bundle outdated --parseable
   • go list -u -m all
   • cargo outdated --format json
   • mvn versions:display-dependency-updates

3. Security audit:

   • npm audit --json
   • pip-audit --format json
   • bundle audit
   • cargo audit --json
   • snyk test (if available)

Categorization

Group updates by SCOPE:

• security: Security vulnerabilities (CVE)
• major: Breaking changes (1.x → 2.x)
• minor: New features (1.2.x → 1.3.x)
• patch: Bug fixes (1.2.3 → 1.2.4)
• all: All of the above

Output Report

# Dependency Update Report

**Generated**: <ISO timestamp>
**Project**: <name from manifest>
**Package Manager**: <detected>
**Scope**: <SCOPE parameter>

## Critical Security Updates
| Package | Current | Latest | Severity | CVE |
|---------|---------|--------|----------|-----|
| express | 4.16.0 | 4.18.2 | High | CVE-2022-24999 |

## Major Updates (Breaking Changes)
| Package | Current | Latest | Changelog |
|---------|---------|--------|-----------|
| react | 17.0.2 | 18.2.0 | [link] |

## Minor Updates (New Features)
| Package | Current | Latest | Changelog |
|---------|---------|--------|-----------|
| lodash | 4.17.19 | 4.17.21 | [link] |

## Patch Updates (Bug Fixes)
| Package | Current | Latest |
|---------|---------|--------|
| uuid | 8.3.0 | 8.3.2 |

Actions (after user review)

1. For SCOPE=security or critical vulnerabilities:

   • Preview update command (e.g., npm update )
   • Ask: "Apply security updates? (YES/NO)"

2. For major updates:

   • Suggest creating individual stories per major update (may require code changes)
   • Format: "US-XXXX: Upgrade from to "

3. For minor/patch:

   • Offer bulk update: "Apply all minor/patch updates? (YES/NO)"

4. If AUTO_PR=yes and approved:

   • Create feature branch: deps/-
   • Run update commands
   • Run tests (if available)
   • Commit with message: "chore(deps): update dependencies ()"
   • Push and create PR using /AgileFlow:pr-template

Integration

• Save report to docs/08-project/dependency-report-.md
• If vulnerabilities found, create story: "US-XXXX: Fix security vulnerabilities in dependencies"
• Update docs/09-agents/bus/log.jsonl with "dependency-check" event

Schedule Suggestion

Recommend adding to CI:

- cron: '0 0 * * 1'  # Weekly on Monday

---

ACTION=audit

Run security audit only (no updates).

Process

1. Detect package manager

2. Run security audit:

   • npm audit --json
   • pip-audit --format json
   • bundle audit
   • cargo audit --json
   • snyk test (if available)

3. Report findings with severity levels

4. Suggest fixes (but don't apply)

5. Optional: Create story for security fixes

Output

# Security Audit Report

**Generated**: 2025-10-25 10:00:00 UTC
**Package Manager**: npm

## Critical (2)
- express@4.16.0: CVE-2022-24999 (CVSS 7.5)
- lodash@4.17.19: CVE-2021-23337 (CVSS 7.4)

## High (0)
None

## Moderate (3)
[...]

**Recommendation**: Run /AgileFlow:packages ACTION=update SCOPE=security

---

Usage Examples

# Show dependency dashboard (default)
/AgileFlow:packages
/AgileFlow:packages ACTION=dashboard

# Export dashboard as HTML
/AgileFlow:packages ACTION=dashboard OUTPUT=html

# Export as JSON for tooling
/AgileFlow:packages ACTION=dashboard OUTPUT=json > deps.json

# Security audit only
/AgileFlow:packages ACTION=audit

# Update security vulnerabilities
/AgileFlow:packages ACTION=update SCOPE=security

# Update all minor and patch versions
/AgileFlow:packages ACTION=update SCOPE=minor

# Update all with auto-PR
/AgileFlow:packages ACTION=update SCOPE=all AUTO_PR=yes

# Update only production dependencies
/AgileFlow:packages ACTION=update INCLUDE_DEV=no

---

CI Integration

Suggest adding automated checks:

- name: Dependency audit
  run: npm audit --audit-level=high

- name: Check outdated
  run: npm outdated || true  # Don't fail, just warn

- name: Generate dashboard
  run: npx claude-code /AgileFlow:packages ACTION=dashboard

Suggest Dependabot config (.github/dependabot.yml):

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 10

---

Rules

• Prioritize security updates
• Group minor/patch updates when safe
• Warn about breaking changes (major updates)
• Never auto-update without approval
• Highlight deprecated packages prominently
• Consider bundle size impact
• Check license compatibility
• Never force-update without running tests
• Preview all commands before execution (require YES/NO)
• Link to changelogs and migration guides

---

Output

Depending on ACTION:

• dashboard: Dependency dashboard (markdown/html/json/csv)
• update: Update report + optional PR with updates (if approved)
• audit: Security audit report with severity levels