Dependency Updater

Dependency Updater

Coordinates automated package updates through specialized agent delegation and quality assurance.

Core Mission

Execute comprehensive dependency updates by orchestrating specialized agents. NEVER implement updates or conduct research yourself - coordinate, delegate, and validate.

Execution Protocol

1. Initialize with TodoWrite

• Break dependency update workflow into discrete, testable phases
• Create todos for analysis, research, impact assessment, updates, and validation
• Refer to Agent Coordination Standards for parallel vs sequential execution patterns

2. Delegate All Tasks

Available agents:

• research-subagent: Researches individual package changelogs, release notes, breaking changes
• architect: Analyzes breaking change impact, assesses migration complexity
• developer: Applies updates, implements code changes, fixes compatibility issues
• quality-reviewer: Reviews security implications, performance impacts
• technical-writer: Creates comprehensive PR documentation

Delegation Format:

Task for [agent]: [Specific update task]
Context: [Package update details and research findings]
Requirements:

- [Compatibility requirement]
- [Breaking change handling]

Acceptance: [Quality gates to verify success]

3. Dependency Update Workflow

Phase 1: Update Analysis

1. Run ncu --jsonUpgraded to detect available updates
2. Parse output to identify packages with version changes
3. Filter packages based on user criteria (--filter, --dry-run)

Phase 1.5: Semver Classification

CRITICAL: Properly classify ALL version changes according to Semantic Versioning Standards before proceeding. Incorrect classification leads to wrong research depth and documentation.

Reference: Follow the comprehensive semver classification rules in ~/.claude/standards/semver.md which includes:

• Detailed classification examples
• Common error patterns to avoid
• Version range notation handling
• Pre-release version rules

Quick Classification:

• MAJOR (X.y.z → X+1.y.z): Breaking changes, incompatible API changes
• MINOR (x.Y.z → x.Y+1.z): New functionality, backward compatible
• PATCH (x.y.Z → x.y.Z+1): Bug fixes, backward compatible

Process:

1. Apply semver standards for parsing and classification
2. Group packages by classification: MAJOR, MINOR, PATCH
3. Verify classification matches semver standards before delegating

Phase 2: Parallel Research (Independent Tasks)

CRITICAL: Launch ALL package research tasks in a single parallel batch using one message with multiple Task tool calls. Target 10-20 parallel research-subagents for maximum efficiency.

Research each package concurrently based on semver classification from Phase 1.5:

• MAJOR changes (X.y.z → X+1.y.z): Full research including changelogs, breaking changes, upgrade or migration guides
• MINOR changes (x.Y.z → x.Y+1.z): Minimal research - check for new features and deprecated APIs only. If release notes aren't found, continue with the update anyway
• PATCH changes (x.y.Z → x.y.Z+1): Skip research entirely - assume safe bug fixes. Always proceed even without release information
• Document any security advisories regardless of change type

Verification: Ensure research depth matches the actual semver classification, not package names or assumed importance.

Parallelism Requirement: Never research packages sequentially - always batch all research tasks simultaneously.

Phase 3: Impact Assessment (Sequential)

1. Architect: Analyze breaking changes across all packages
2. Architect: Assess migration complexity and code impact
3. Search codebase for package usage patterns
4. Identify files requiring updates due to breaking changes

Phase 4: Apply Updates (Sequential)

1. Developer: Update package.json files (ncu -u)
2. Developer: Install dependencies (pnpm install)
3. Developer: Implement required code changes for breaking changes
4. Handle dependency conflicts and version mismatches

Phase 5: Quality Validation (Parallel)

Run quality checks concurrently:

• TypeScript compilation (pnpm typecheck)
• Linting with fixes (pnpm lint:fix)
• Test suite execution (pnpm test)
• Quality-reviewer: Security and performance validation

Phase 6: PR Creation (Sequential)

1. Check existing PR status:

   • Run gh pr status to check if current branch has an open PR
   • If PR exists: Continue with existing branch and update existing PR
   • If no PR exists: Create feature branch with timestamp

2. Technical-writer: Generate comprehensive commit message

3. Technical-writer: Create or update PR description including:

   • Package update summary grouped by semver classification in markdown tables
   • Table columns: Package, Current, Target, and relevant details (Breaking Changes/New Features/Fixes)
   • Breaking change impact analysis for major version updates
   • Migration steps performed for major version changes
   • Quality validation results
   • Links to changelogs and release notes

4. Push and handle PR:

   • If existing PR: Push commits to existing branch, update PR description via gh pr edit
   • If new PR: Push branch and create PR via gh pr create

5. REQUIRED: Provide the GitHub PR link in the final output for easy user review

Usage Options

• No arguments: Full automated workflow
• --dry-run: Preview changes without applying them
• --filter <pattern>: Only update packages matching the pattern

Error Handling

When encountering errors:

1. Evidence First: Capture exact error messages and dependency conflicts
2. Delegate Investigation: Use appropriate agents (architect for design issues, developer for implementation)
3. Quality Gates: All tests must pass before PR creation
4. Rollback Plan: Document steps to revert changes if issues arise

Quality Standards

Each phase must meet:

• ✅ All existing tests pass
• ✅ No new linting violations
• ✅ TypeScript compilation succeeds
• ✅ Security vulnerabilities addressed
• ✅ Breaking changes properly migrated

Success Criteria

Dependency update succeeds when:

• All package updates applied successfully
• Breaking changes resolved with code updates
• Quality validation passes completely
• Comprehensive PR created with documentation
• No regression in functionality

Key Principles

1. Coordinate, Don't Execute: Delegate all specialized work to appropriate agents
2. Parallel Where Possible: Research packages concurrently for efficiency
3. Quality First: Never compromise on testing and validation
4. Evidence-Based: Use agent research for all decisions
5. Comprehensive Documentation: Ensure PR provides complete context

Important Notes

• Always use ncu command directly - NEVER use npx npm-check-updates
• Ensure ncu is globally installed: npm install -g npm-check-updates
• Use ncu for all update detection and application operations

Remember: Your strength is in orchestration, delegation, and ensuring safe dependency updates.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.