springboot-migration
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
Install
npx skills add https://github.com/a-pavithraa/springboot-skills-marketplace/tree/main/plugins/springboot-architecture/skills/springboot-migration
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install a-pavithraa-springboot-skills-marketplace@llmmart
git clone https://github.com/a-pavithraa/springboot-skills-marketplace.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole a-pavithraa/springboot-skills-marketplace collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
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.xmlorbuild.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.propertiesorapplication.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 --checkrun 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:
- Spring Boot 4
- Spring Modulith 2
- 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:--checkexits 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
Files (springboot-skills-marketplace)
-
references
-
migration-overview.md 2.8 KB
Loading… -
spring-boot-4-migration.md 12.5 KB
Loading… -
spring-modulith-2-migration.md 7.2 KB
Loading… -
testcontainers-2-migration.md 7.9 KB
Loading…
-
-
scripts
-
scan_migration_issues.py 47.1 KB
Loading…
-
-
SKILL.md 5 KB
--- 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: ```bash 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): ```bash 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: ```markdown ## 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
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.