Skip to main content
command CX Codex

devkit.java.upgrade-dependencies — Claude Code command

devkit.java.upgrade-dependencies is a Claude Code command that plans and executes step-by-step dependency updates for Java, Maven, and Gradle projects, detects breaking changes, and creates migration guides.

MIT ★ 372 updated 2026-09-10

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add giuseppe-trisciuoglio/developer-kit
/plugin install developer-kit-java@developer-kit
Open on GitHub

What devkit.java.upgrade-dependencies does

The command scans pom.xml, build.gradle, or build.gradle.kts to map direct and transitive project dependencies. It flags outdated libraries, scans for known vulnerabilities, and groups upgrades into four risk tiers: patch, minor, major, and security.

Execution is controlled via three optional arguments. The scope parameter isolates entire projects, Spring modules, testing libraries, direct dependencies, or a single artifact. The strategy parameter chooses between read-only analysis, migration planning, markdown guide generation, automated updates, and rollback creation.

Workflows rely on local mvn or gradlew CLI tools to inspect dependency trees. When applying actual edits under the execute strategy, the agent pauses for user confirmation before writing changes.

What it helps with

  • audit Java projects for outdated and vulnerable dependencies
  • plan phased upgrades across major library releases
  • migrate test suites from JUnit 4 to JUnit 5
  • prepare rollback steps before applying dependency edits

Example prompts for the agent

  • /devkit.java.upgrade-dependencies spring plan
  • /devkit.java.upgrade-dependencies testing analyze
  • /devkit.java.upgrade-dependencies org.springframework.boot:spring-boot-starter-web migrate 3.2.0

How to install devkit.java.upgrade-dependencies

1Plugin marketplace

/plugin marketplace add giuseppe-trisciuoglio/developer-kit
/plugin install developer-kit-java@developer-kit

2Manually: put the files in place

.claude/commands/devkit.java.upgrade-dependencies.md

Call it with /devkit.java.upgrade-dependencies. For all projects use ~/.claude/commands/

Questions about devkit.java.upgrade-dependencies

How to install devkit.java.upgrade-dependencies in Claude Code?

Run both marketplace commands in sequence: /plugin marketplace add giuseppe-trisciuoglio/developer-kit, then /plugin install developer-kit-java@developer-kit.

What does devkit.java.upgrade-dependencies do?

It evaluates Maven and Gradle dependencies, flags breaking API changes across releases, and drafts structured upgrade plans.

Which arguments does the command support?

It accepts scope (all, spring, testing, security, direct, or an artifact id), strategy (analyze, plan, migrate, execute, rollback), and an optional target version.

Source text

devkit.java.upgrade-dependencies.md · MIT
---
allowed-tools: Read, Bash, Edit, Write, Grep, Glob
argument-hint: "[scope] [strategy] [version]"
description: Manages safe and incremental dependency upgrades for Java/Maven/Gradle projects with breaking change detection and migration guides. Use when upgrading project dependencies or migrating to new library versions.
---

# Java Dependency Upgrade Strategy

## Overview

Plan and execute safe, incremental upgrades of Java project dependencies with minimal risk, proper testing, and clear
migration paths for breaking changes.

Manages safe and incremental dependency upgrades for Java/Maven/Gradle projects with breaking change detection and
migration guides. Use when upgrading project dependencies or migrating to new library versions.

## Usage

```
/devkit.java.upgrade-dependencies $ARGUMENTS
```

## Arguments

$1 specifies the scope (optional - defaults to `all`):

- `all` - Analyze all dependencies
- `spring` - Focus on Spring Boot and Spring Framework dependencies
- `testing` - Focus on test dependencies (JUnit, Mockito, AssertJ, Testcontainers)
- `security` - Prioritize security vulnerabilities
- `direct` - Only direct dependencies (not transitive)
- `<groupId:artifactId>` - Specific dependency (e.g., `org.springframework.boot:spring-boot-starter-web`)

$2 specifies the strategy (optional - defaults to `analyze`):

- `analyze` - Analyze and report available updates with risk assessment
- `plan` - Create detailed upgrade plan with incremental steps
- `migrate` - Generate migration guide for major version upgrades
- `execute` - Execute planned upgrades (requires confirmation)
- `rollback` - Create rollback strategy and backup current state

$3 specifies target version for specific dependency upgrades (optional):

- Version number (e.g., `3.2.0`, `5.3.31`)
- `latest` - Latest stable release
- `latest-minor` - Latest minor version
- `latest-patch` - Latest patch version

## Execution Instructions

**Agent Selection**: To execute this task, use the following agent with fallback:

- Primary: `java-security-expert`
- If not available: Use `developer-kit:java-security-expert` or fallback to `general-purpose` agent with
  `spring-boot-crud-patterns` skill

## Context

- Build system: !`ls -la | grep -E "(pom\.xml|build\.gradle|build\.gradle\.kts)"`
- Current dependencies: !
  `if [ -f pom.xml ]; then mvn dependency:tree | head -30; elif [ -f build.gradle ]; then ./gradlew dependencies --configuration compileClasspath | head -30; fi`
- Outdated dependencies: !
  `if [ -f pom.xml ]; then mvn versions:display-dependency-updates 2>/dev/null | grep -E "\\->" | head -20; elif [ -f build.gradle ]; then ./gradlew dependencyUpdates 2>/dev/null | grep -E "\\->" | head -20; fi`

## Upgrade Analysis Process

### 1. Dependency Inventory

Analyze current state:

- List all dependencies (direct and transitive)
- Identify outdated dependencies
- Check for known security vulnerabilities
- Detect dependency conflicts

### 2. Risk Assessment

Categorize updates by risk level:

- **PATCH** (Low risk): Bug fixes, no breaking changes
- **MINOR** (Medium risk): New features, backward compatible
- **MAJOR** (High risk): Breaking changes, API modifications
- **SECURITY** (Critical): Security vulnerabilities requiring immediate action

### 3. Breaking Change Detection

For each major version update:

- Fetch release notes and changelogs
- Identify deprecated APIs
- Detect removed features
- Find renamed packages/classes
- Check compatibility with other dependencies

### 4. Framework-Specific Patterns

#### Spring Boot Upgrades

When upgrading Spring Boot:

- Check Spring Boot migration guide
- Update parent POM version
- Review breaking changes in Auto-configuration
- Update application.properties/yml if needed
- Verify starter dependencies compatibility
- Check for deprecated @Configuration patterns
- Test Actuator endpoint changes

#### JUnit 4 to JUnit 5

When upgrading JUnit:

- Replace `@Test` imports
- Convert `@Before/@After` to `@BeforeEach/@AfterEach`
- Update assertions (AssertJ recommended)
- Migrate test runners to `@ExtendWith`
- Replace `@RunWith(SpringRunner.class)` with `@ExtendWith(SpringExtension.class)`

#### Mockito Upgrades

When upgrading Mockito:

- Update import statements
- Replace deprecated methods
- Check ArgumentMatchers changes
- Verify BDDMockito compatibility
- Update MockitoJUnitRunner usage

### 5. Compatibility Matrix

Check peer dependencies:

- Spring Boot → Spring Framework version
- Spring Framework → Java version
- JUnit 5 → Mockito version
- Hibernate → Java Persistence API version
- Testcontainers → Docker Java version

## Upgrade Strategies

### Strategy 1: Patch Updates (Safe)

```bash
# Maven: Update all patch versions
mvn versions:use-latest-releases -DallowMajorUpdates=false -DallowMinorUpdates=false

# Gradle: Update patch versions
./gradlew useLatestVersions --update-dependency-locks
```

**Testing**: Smoke tests + unit tests
**Risk**: Very low
**Timeline**: Same day

### Strategy 2: Minor Updates (Careful)

```bash
# Maven: Update minor versions
mvn versions:use-latest-releases -DallowMajorUpdates=false

# Gradle with version catalog
./gradlew versionCatalogUpdate --no-major
```

**Testing**: Full regression suite
**Risk**: Low to medium
**Timeline**: 1-2 days

### Strategy 3: Major Updates (Planned)

Individual upgrade with migration:

1. Create feature branch
2. Update single dependency
3. Fix breaking changes
4. Run comprehensive tests
5. Code review
6. Merge after validation

**Testing**: Full test suite + manual QA
**Risk**: Medium to high
**Timeline**: 3-7 days per major dependency

### Strategy 4: Spring Boot Upgrade (Strategic)

```bash
# Check Spring Boot compatibility
curl -s https://spring.io/projects/spring-boot | grep -A 5 "supported versions"

# Incremental upgrade path
# Example: 2.7.x → 3.0.x → 3.1.x → 3.2.x
```

**Testing**: Integration tests with Testcontainers
**Risk**: High
**Timeline**: 1-2 sprints

## Maven Commands

### Analysis

```bash
# Check for updates
mvn versions:display-dependency-updates

# Check for plugin updates
mvn versions:display-plugin-updates

# Security vulnerabilities
mvn org.owasp:dependency-check-maven:check

# Dependency tree
mvn dependency:tree -Dverbose
```

### Execution

```bash
# Update specific dependency
mvn versions:use-dep-version -Dincludes=groupId:artifactId -DdepVersion=1.2.3

# Update all dependencies to latest
mvn versions:use-latest-versions

# Update parent POM
mvn versions:update-parent

# Revert changes if needed
mvn versions:revert
```

## Gradle Commands

### Analysis

```bash
# Check for updates (with plugin)
./gradlew dependencyUpdates

# Show dependency tree
./gradlew dependencies --configuration compileClasspath

# Security scan
./gradlew dependencyCheckAnalyze
```

### Execution

```bash
# Update version catalog
./gradlew versionCatalogUpdate

# Refresh dependencies
./gradlew build --refresh-dependencies

# Clean and rebuild
./gradlew clean build
```

## Migration Guide Template

For each major upgrade, generate:

```markdown
## Migration: [Dependency] [Old Version] → [New Version]

### Breaking Changes

- API change 1: `oldMethod()` → `newMethod()`
- Removed class: `com.example.OldClass`
- Configuration change: `old.property` → `new.property`

### Migration Steps

#### Step 1: Update Dependency

```xml
<!-- Maven -->
<dependency>
    <groupId>group.id</groupId>
    <artifactId>artifact-id</artifactId>
    <version>NEW_VERSION</version>
</dependency>
```

#### Step 2: Fix Compilation Errors

- Replace deprecated imports
- Update method calls
- Adjust configuration

#### Step 3: Update Tests

- Fix test compilation
- Update mocks and stubs
- Adjust test configurations

#### Step 4: Runtime Verification

- Start application
- Check logs for warnings
- Test critical paths

### Testing Checklist

- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Application starts successfully
- [ ] Health checks pass
- [ ] Manual smoke tests completed

### Rollback Plan

```bash
git revert HEAD
mvn clean install
```

### Estimated Effort

- Compilation fixes: X hours
- Test updates: Y hours
- Testing & validation: Z hours
  **Total**: W hours

```

## Post-Upgrade Validation

### Automated Checks
```bash
# Compile
mvn clean compile
./gradlew compileJava

# Run tests
mvn test
./gradlew test

# Integration tests
mvn verify
./gradlew integrationTest

# Code quality
mvn checkstyle:check spotbugs:check
./gradlew check

# Generate dependency report
mvn project-info-reports:dependencies
```

### Runtime Verification

- Application startup time
- Memory footprint comparison
- API response times
- Error rate monitoring
- Health check status

## Rollback Strategy

### Create Rollback Point

```bash
# Git tag before upgrade
git tag -a "pre-upgrade-$(date +%Y%m%d)" -m "Pre-upgrade snapshot"

# Backup POM/Gradle files
cp pom.xml pom.xml.backup
cp build.gradle build.gradle.backup
cp gradle/libs.versions.toml gradle/libs.versions.toml.backup
```

### Execute Rollback

```bash
# Restore from backup
git checkout pom.xml build.gradle gradle/libs.versions.toml

# Or revert to tag
git reset --hard pre-upgrade-YYYYMMDD

# Clean rebuild
mvn clean install
./gradlew clean build
```

## Common Java Dependency Upgrades

### Spring Boot

-
Check [Spring Boot Migration Guide](https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-3.0-Migration-Guide)
- Review breaking changes in Auto-configuration
- Update Java version if required (Spring Boot 3 requires Java 17+)

### Hibernate/JPA

- Review JPA specification changes
- Check for deprecated methods
- Test lazy loading behavior
- Verify transaction management

### Jackson

- Check for breaking changes in serialization
- Test date/time handling
- Verify custom serializers/deserializers

### Lombok

- Update IDE plugin
- Check annotation processing configuration
- Verify generated code compatibility

### Testcontainers

- Update Docker dependencies
- Check container image versions
- Verify network configuration

## Your Task

Based on the specified scope and strategy, provide:

1. **Dependency Analysis Report**
    - Current versions vs. available versions
    - Risk assessment for each update
    - Security vulnerability status
    - Dependency conflicts

2. **Prioritized Upgrade Plan**
    - Critical security updates (immediate)
    - Safe patch updates (batch)
    - Minor version updates (incremental)
    - Major version updates (planned)

3. **Migration Guides** (for major upgrades)
    - Breaking changes
    - Step-by-step migration
    - Code examples
    - Testing strategy

4. **Execution Commands**
    - Maven/Gradle commands to execute
    - Testing commands
    - Rollback procedures

5. **Timeline & Effort Estimation**
    - Realistic schedule
    - Resource requirements
    - Risk mitigation steps

Focus on **safe, incremental upgrades** that maintain system stability while keeping dependencies current and secure.
Always provide rollback strategies and comprehensive testing approaches.

## Examples

```bash
/devkit.java.upgrade-dependencies example-input
```

© Giuseppe Trisciuoglio · MIT · giuseppe-trisciuoglio/developer-kit

Similar slash commands

All slash commands for Backend and APIs →

From the same set191

The whole set →
langchain4j-ai-development-expert langchain4j-ai-development-expert — a subagent for building AI apps with LangChain4j: RAG systems, chatbots, and MCP servers. Configures vector stores, embeddings, and model integration. CX Codex ★ 372repo stars nestjs-unit-testing-expert nestjs-unit-testing-expert — a subagent for authoring Jest unit tests in NestJS and TypeScript applications with proper dependency isolation. CX Codex ★ 372repo stars general-docker-expert The general-docker-expert subagent helps create Dockerfiles, multi-stage builds, and Docker Compose configurations. Use it for containerization work and image optimization. CX Codex ★ 372repo stars aws-cloudformation-security aws-cloudformation-security is a Claude Code skill that provides CloudFormation security snippets for KMS, secret rotation, IAM, VPC controls and ACM, each with an AWS CLI check. CX Codex +1 ★ 372repo stars python-code-review-expert python-code-review-expert is a Claude Code subagent that checks Python code for bugs, security flaws, and quality issues. It joins code reviews and pull request assessments. CX Codex ★ 372repo stars aws-cloudformation-task-ecs-deploy-gh aws-cloudformation-task-ecs-deploy-gh — a skill that walks the agent through shipping containers to Amazon ECS from GitHub Actions: OIDC login, ECR push, task definition update, service deploy. CX Codex +1 ★ 372repo stars general-refactor-expert general-refactor-expert is a Claude Code subagent for refactoring code while preserving behavior. It finds code smells and applies SOLID patterns. CX Codex ★ 372repo stars aws-cloudformation-rds aws-cloudformation-rds guides Claude Code through AWS CloudFormation templates for Amazon RDS, Aurora, multi-AZ setups, and related network resources. Use it when shaping database infrastructure. CX Codex +1 ★ 372repo stars

Project sponsors

Companies that keep this analytics open