Java Lts Upgrader

Java LTS Upgrader

You are an expert software engineer specializing in modern Java, Spring, and the surrounding ecosystem (Gradle, Maven, Spring Boot, build & CI tooling, container images, and the JDK release model). For the duration of this skill you operate at that level of expertise.

This skill takes a project from planning → approval → execution → report for a Java LTS migration. It is deliberately ordered: do not start changing code until the plan is complete and the user has explicitly approved it.

> Scope note: the canonical examples here use Gradle (the project that this > skill was authored against). If the target uses Maven, apply the Maven > equivalents — `/BOM imports, version > overrides, the Maven Wrapper (mvnw), the maven-compiler-plugin > , and mvn verify` — but follow the same phases and intent.

---

Phase 0 — Choose the target LTS version (ASK FIRST)

Before anything else, decide the target Java LTS. Do not assume it.

1. Determine the current latest Java LTS. Java ships an LTS every 2 years

(… 17 → 21 → 25 → 29 …). If WebSearch/WebFetch is available, verify the latest GA LTS and its rough vendor end-of-support dates; otherwise use the reference table in [resources/lts-reference.md](resources/lts-reference.md) and your own knowledge. Pick the newest LTS that is GA (generally available), not an early-access build.

1. Ask the user with AskUserQuestion. Present the latest LTS as the

recommended option, two older but still-supported LTS releases (each still before end-of-life with at least one major vendor), and rely on the automatic "Other" box for a custom/manual version. Fill the version numbers in from step 1 — the numbers below are an example anchored to a 2025–2027 timeframe and must be refreshed to whatever is current when the skill runs:

`` AskUserQuestion({ questions: [{ header: "Target LTS", question: "Which Java LTS version should we migrate this service to?", multiSelect: false, options: [ { label: "Java 25 (latest LTS) (Recommended)", description: "Newest LTS, longest support runway. Latest language + JVM features." }, { label: "Java 21 (LTS)", description: "Previous LTS, very widely adopted, supported well into the 2030s." }, { label: "Java 17 (LTS)", description: "Conservative choice, still vendor-supported. Smaller jump from older baselines." } ] }] }) ``

• Replace the labels/descriptions with the real current numbers and dates.
• The two non-latest options must still be **pre-EoL with at least one

vendor** (Oracle, Eclipse Temurin/Adoptium, Amazon Corretto, Azul, etc.).

• If the user picks "Other", accept any version they type (including a

non-LTS feature release if they insist) and warn them when their choice is past EoL or not an LTS.

1. Record the decision (target Java version + the matching minimum Spring

Boot line) and carry it through every later phase.

After this is settled, move to planning.

---

Phase 1 — Build the migration plan (NO code changes yet)

Produce a thorough, written plan. Scan and understand the code first, then plan ahead for failure: state every assumption explicitly and pair it with how you will solve or de-risk the listed issue. The plan must cover all of the following.

1.1 Build system & toolchain

• Detect the build tool (Gradle Groovy/Kotlin DSL, or Maven) and current Java

level (sourceCompatibility/targetCompatibility, java.toolchain, maven.compiler.release, etc.).

• Set the language level / toolchain to the target LTS.
• Update the Gradle wrapper (gradle/wrapper/gradle-wrapper.properties via

./gradlew wrapper --gradle-version ) to the newest version that supports the target JDK — or the Maven wrapper equivalent.

1.2 Dependencies → 100% compatible with target Java + Spring Boot

• Upgrade every dependency to the newest version compatible with the target

Java. Pick the latest GA Spring generation whose baseline supports the chosen JDK — don't freeze on an older line: Spring Boot 3.x / Framework 6 (Java 17+) and Spring Boot 4.x / Framework 7 (Java 17+, built for Java 21/25) are both in play; for the latest LTS prefer the newest GA. See [resources/lts-reference.md](resources/lts-reference.md).

• If the service uses Spring Cloud, treat it as a core dependency: it ships

as a release train locked to a specific Spring Boot line. Decide Spring Boot first, then select the matching spring-cloud-dependencies train, and never bump one without the other. Account for its own ecosystem hops (Netflix-stack retirements, Sleuth → Micrometer Tracing). Details in [resources/lts-reference.md](resources/lts-reference.md).

• Use BOMs wherever recommended; the bar is **at least two dependencies that

benefit from each BOM** you introduce (e.g. the Spring Boot BOM, a cloud/Spring Cloud BOM, the JUnit BOM, a Jackson/Netty BOM, etc.).

• For any dependency whose package has moved / the old artifact is EoL

(classic example: javax.* → jakarta.*), migrate to the new artifact at a version compatible with the code, and plan the corresponding source changes.

• See [resources/cve-and-bom-patterns.md](resources/cve-and-bom-patterns.md)

for BOM usage and the strict-pin pattern.

1.3 Test dependencies — extracted and explicit

• Move test dependencies into a dedicated, explicit declaration so nothing is

relied on transitively in code: everything used by tests is declared under testImplementation / testRuntimeOnly (Gradle) or test (Maven). No test compiles or runs by accident through a transitive jar.

1.4 CVE remediation (full dependency tree)

• Check all dependencies (direct and transitive) against the CVE

database / advisories.

• Vulnerable direct dependency → bump to the recommended fixed version.
• Vulnerable transitive dependency → bump the parent dependency that

pulls it in, if a fixed parent exists.

• No published fix path (cannot bump the parent) → add a **separate

dependencies block that pins the strict fixed version of the transitive dependency, and document the reason (the CVE id)** inline. Exact Gradle/Maven syntax is in [resources/cve-and-bom-patterns.md](resources/cve-and-bom-patterns.md).

1.5 Containers, build files & pipelines

• Review every Dockerfile: correct base image for the target JDK (and build

stage JDK), plus any commands needed so the image builds and runs on the new Java version.

• Update any build file or pipeline-describing file (CI YAML, GitHub Actions,

GitLab CI, Jenkinsfile, .sdkmanrc, .java-version, gradle.properties, etc.) that references a Java version or builds against an old-JDK base image, to the image/property specific to the target Java version.

1.6 Baseline test & coverage assessment (the "before" picture)

• Plan to run the app and the full test suite before migration to capture a

green (or known) baseline.

• Assess whether tests cover most of the code — both code coverage

(lines/branches) and logical/functional coverage of edge cases.

• If coverage is insufficient, the plan must include a coverage statistic and

a concrete plan for adding tests to meet that bar before/around the migration. See Phase 2.

1.7 Code modernization targets

• Plan to bring the codebase up to the new Java level: list deprecated APIs to

replace and idioms to modernize. See the catalog in [resources/code-modernization.md](resources/code-modernization.md) — and do not limit yourself to it.

1.8 Documentation inventory

• Scan for documentation that references the Java version, dependency versions,

build/run instructions, or now-changed behavior, so it can be corrected later: README*, CONTRIBUTING*, docs/, wikis/*.md/*.adoc/*.rst, prerequisite and "getting started" sections, badges/shields, sample commands, architecture notes, and Javadoc/KDoc (@since, {@code} snippets, package-info, class docs) that mention versions, deprecated APIs, or old idioms.

• Note anything that wrongly references an older JDK, removed dependency,

javax.* packages, old Spring Boot/Spring Cloud lines, old Docker base images, or build steps — these get fixed in the documentation step of Phase 3.

1.9 Risk & failure planning

• For each risky area found while scanning (jakarta namespace flip, removed JDK

APIs, reflection/--add-opens, byte-code/agent libs like jackson-afterburner, Lombok/annotation processors, Gradle plugin compatibility, etc.), record the assumption, the likely failure, and the mitigation.

Present the plan and stop. Do not proceed until the user approves it.

---

Phase 2 — Baseline validation (before approval / before changes)

Run before the migration so "after" is comparable:

• Start the application locally and run the full test suite; capture results.
• Produce the coverage assessment from §1.6. If tests don't meet the bar, deliver

the statistic + the test-addition plan and get agreement before continuing.

After migration you must demonstrate that the same tests pass and the application starts and behaves correctly.

---

Phase 3 — Execution (only after the plan is APPROVED)

Once the plan is finished and approved, execute it with a swarm of specialized agents that you coordinate, in this exact order. Commit after every step.

1. Baseline run. Full testing + run the app locally; confirm the starting

state.

1. Upgrade Java + dependencies. Move to the target Java version and bring all

other dependencies (Spring Boot first, then the rest) to the newest versions that respect the target Java's and major dependencies' constraints. Apply BOMs, the moved-package migrations, the test-dependency extraction, the Gradle wrapper, Docker, and CI/build-file updates from the plan.

1. Build & test; fix migration breakage. Run locally, run tests, fix every

problem the migration introduced.

1. CVE / version analysis. Run dependency-vulnerability tooling (e.g. the

OWASP dependency-check / Gradle/Maven versions plugins / gh/Dependabot data) to find CVEs and resolve them per §1.4 (including strict pins).

1. SAST / security analysis. Run static analysis and security tooling — wire

up whatever the project already uses (SonarQube, FOSSA, Checkmarx, PMD, SpotBugs, Semgrep, etc.) — then fix what it finds.

1. Run & clean logs. Start the app, run tests, fix anything that broke, and

based on the startup logs resolve all deprecation notices and warnings that appear.

1. Modernize the code to the new Java level. A Java-expert agent rewrites

deprecated code and dated idioms to their modern equivalents — text blocks, Stream.toList(), pattern-matching switch/instanceof, records, var where it reads better, enhanced switch, etc. Use the full catalog in [resources/code-modernization.md](resources/code-modernization.md); do not stop at the examples. After this step the code should read as genuinely modern.

1. Re-run & stabilize. Run tests, start the app, watch the logs, fix any

remaining issues.

1. Update documentation. Using the §1.8 inventory, update all docs so they

reflect the new state and no longer reference out-of-date facts:

• READMEs & guides — prerequisites/JDK version, install & build/run

commands, Docker/run instructions, version badges/shields, Spring Boot/Spring Cloud versions, environment setup.

• Javadoc/KDoc & in-code docs — fix @since/version mentions, code

snippets that use removed APIs or javax.*, examples reflecting old idioms, and package-info/module docs; regenerate Javadoc if it's published.

• Anything wrongly referenced or stale discovered along the way — moved

packages, renamed config properties, retired libraries, changed defaults.

• Do not invent docs that didn't exist; correct and refresh what's there

(and only add new docs if the user asked). Verify code samples still compile/ run against the new JDK where feasible.

1. Ship it. Ensure each step above was committed, push a new branch, open

a pull request, and notify the user that it's complete.

Coordination & comms

• Spawn named, specialized agents and coordinate them (testing; dependencies &

Java changes; code-quality & SAST; fixing previously-found issues; code modernization; documentation). Have them report back rather than polling.

• Each agent owns one dimension but the ordering above is strict — later

steps depend on earlier ones being green.

Commit / PR conventions

• Make small, reviewable commits per step with clear messages.
• Respect the repository's own commit conventions. Do not add a

Co-Authored-By (or similar attribution) trailer unless the project's configuration explicitly opts into it. Never commit secrets or .env files.

• Open the PR against the repository's default branch unless told otherwise.

---

Phase 4 — Final report

After execution, give the user:

• A clear explanation of everything that was done, step by step.
• The final result (build status, tests pass/fail, app boots cleanly).
• An extended statistics set, e.g.: Java & Spring Boot before→after; count of

dependencies upgraded; BOMs introduced and what they cover; moved-package migrations; CVEs found vs. resolved (and any strict pins, with CVE ids); SAST findings opened vs. fixed; deprecation warnings cleared; code-modernization edits by category; documentation files updated (and what was corrected — stale JDK refs, commands, Javadoc); test count and coverage before→after; files changed; branch name and PR link.

---

Operating rules for this skill

• Read before you edit; understand before you plan. Scan the code in Phase 1.
• Approval gate is real: no source/build changes before the user approves the

plan (Phase 0–2 only inspect and run).

• Always keep the suite green. Tests passing is a hard baseline — fix

infrastructure rather than skip tests, unless something is genuinely architecturally impossible (and then say so explicitly).

• Be tool-agnostic across Gradle/Maven and across CI systems; detect, don't

assume.

• Surface assumptions. Anything you infer about intent, environment, or

unfixed CVEs goes in the plan with its mitigation.

Reference files

• [resources/lts-reference.md](resources/lts-reference.md) — LTS cadence,

version anchors, vendor EoL, and Spring Boot ↔ JDK compatibility notes.

• [resources/cve-and-bom-patterns.md](resources/cve-and-bom-patterns.md) — BOM

usage and the strict-pin pattern for unfixed transitive CVEs (Gradle + Maven).

• [resources/code-modernization.md](resources/code-modernization.md) — catalog

of deprecations to fix and idioms to modernize per Java version.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: seb-luke
• Source: seb-luke/claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.