name: springboot-migration description: Migrates Spring Boot applications to Boot 4 with Java 25, including related Spring Modulith 2 and Testcontainers 2 upgrade work. Use when the task is a concrete upgrade, dependency transition, starter rename, test-annotation migration, or phased migration plan. Do not use for greenfield project creation or for isolated repository design questions.

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 Java 25, 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.
• Verify after each phase and stop when failures appear.

Workflow

Step 1: Scan the project

Use the migration scanner before planning or editing:

python3 <SKILL_DIR>/scripts/scan_migration_issues.py /path/to/project

Use the scan output to identify:

• current Spring Boot version
• starter rename work
• annotation and import migrations
• configuration changes
• Spring Modulith compatibility
• Testcontainers compatibility

Step 2: Identify which migrations apply

Load only the references that match the codebase:

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 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

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
• JPA-specific implementation work that belongs in spring-data-jpa