/springboot-migration

name: springboot-migration
description: "Use when upgrading an existing Spring Boot application, for example from Boot 3.x to Boot 4 or to the latest Spring Boot and Java: dependency transitions and starter renames, test annotations such as @MockBean to @MockitoBean, Jackson 3 issues, Spring Modulith 2 or Testcontainers 2 upgrades, code that stops compiling after a version bump, or planning a phased migration. Not for greenfield project creation or isolated repository design."

Spring Boot Migration

Purpose

Use this skill for phased upgrade work on existing Spring Boot applications. This skill adds value through the migration scanner, the Boot 4 / Modulith 2 / Testcontainers 2 reference guides, and a strict migration order that avoids mixing too many changes at once.

Critical rules

• Never migrate blindly. Scan the codebase first.
• Never apply every migration at once. Follow phased upgrades.
• Treat Spring Boot 4, Spring Modulith 2, and Testcontainers 2 as the intended target stack for this skill unless the user asks for a narrower target. Boot 4's Java baseline is 17; recommend Java 25 for new compile targets but do not force an upgrade past what the migration actually requires. For Java 26+ targets, read `../creating-springboot-projects/references/java-version-policy.md`.
• Verify after each phase and stop when failures appear.

Workflow

Step 1: Scan the project

Use the migration scanner before planning or editing. It reads `pom.xml`, `build.gradle`, or `build.gradle.kts` (whichever the project has) plus Java sources, properties files, and Flyway migrations:

python3 "${CLAUDE_SKILL_DIR}/scripts/scan_migration_issues.py" /path/to/project

`${CLAUDE_SKILL_DIR}` is this skill's folder. Codex doesn't set it, so there use the folder this `SKILL.md` is in.

Use the scan output to identify:

• current Spring Boot version
• starter rename work
• annotation and import migrations
• configuration changes
• Spring Modulith compatibility
• Testcontainers compatibility
• Java preview APIs (`StableValue`, `StructuredTaskScope`) that break on a newer JDK

Step 2: Identify which migrations apply

Load only the references that match the codebase:

| Migration | Trigger | Read | |-----------|---------|------| | Spring Boot 4.0 | Boot 3.x to 4.x upgrade | `references/spring-boot-4-migration.md` | | Spring Modulith 2.0 | Existing Modulith 1.x usage | `references/spring-modulith-2-migration.md` | | Testcontainers 2.x | Existing Testcontainers 1.x usage | `references/testcontainers-2-migration.md` | | Cross-cutting scenarios and pitfalls | Mixed upgrade planning | `references/migration-overview.md` |

Step 3: Plan the migration in phases

Use the reference guides to plan and execute in this order.

Phase 1: Dependencies

• update `pom.xml` or `build.gradle`
• rename starters where required
• add or remove dependencies needed by the target stack
• align version properties

Phase 2: Source-code changes

• update imports and package names
• migrate test annotations
• fix Jackson 3 issues
• fix Testcontainers API changes where relevant

Phase 3: Configuration

• update `application.properties` or `application.yml`
• apply Boot 4 defaults intentionally
• update Spring Modulith event-store configuration if relevant

Phase 4: Verification

• run the scanner again with `--check`; it exits with 1 while any CRITICAL issue remains (a missing modular starter, for example, compiles but fails at startup):

  python3 "${CLAUDE_SKILL_DIR}/scripts/scan_migration_issues.py" /path/to/project --check

• run unit tests
• run integration tests
• run container-based tests where present
• check for deprecations and startup failures

Step 4: Use the right migration order for mixed upgrades

When multiple ecosystems are involved, use this order:

1. Spring Boot 4 2. Spring Modulith 2 3. Testcontainers 2

Read `references/migration-overview.md` before deviating from this sequence.

Step 5: Report progress after each phase

After each phase, report:

• what changed
• what remains
• what failed, if anything
• whether it is safe to continue

Reference loading guide

• Spring Boot 4 migration details: `references/spring-boot-4-migration.md`
• Spring Modulith 2 migration details: `references/spring-modulith-2-migration.md`
• Testcontainers 2 migration details: `references/testcontainers-2-migration.md`
• Mixed scenarios and common issues: `references/migration-overview.md`

Available script

• `scripts/scan_migration_issues.py`: `--check` exits with 1 while CRITICAL issues remain. It skips build output and hidden directories, including project-level skill installs.

Output format

When planning or reporting the migration, return:

## Migration scope
- Current versions:
- Target versions:

## Planned phases
1. ...
2. ...
3. ...

## Files expected to change
- `path/to/file`

## Verification
- Tests or checks to run

When not to use this skill

• Creating a new Spring Boot project from scratch
• Broad architecture advice without an actual migration task