migrate-spring-to-quarkus

Spring Boot to Quarkus Migration

Modular, gate-driven migration of Spring Boot applications to Quarkus.

Critical Rules

• Never delete code you cannot migrate. If you cannot fully migrate a piece of code, leave the original in place with a // TODO: Migration required — <reason> comment explaining what needs to change and why. This applies to:
  • Methods, classes, or annotations you don't know how to convert
  • Spring-specific patterns without a clear Quarkus equivalent
  • Configuration or wiring code whose purpose is unclear If you must remove code (e.g., a Spring-only base class), document what was removed and why in a // REMOVED: comment at the same location.
• Don't break the build. Run the compile command in <target> after each phase (cd <target> && ./mvnw clean compile -DskipTests for Maven, cd <target> && ./gradlew clean compileJava -x test for Gradle). Never move to the next phase with a broken build.
• Source is read-only. Never modify files in <source>. All changes go into <target>. The only exception is <source>/migration-metadata/, where extraction metadata may be written.
• Document every decision. When choosing between migration approaches, explain the trade-off to the user.
• No silent changes. Every file modification must be intentional and traceable. If a check fails after a phase, diagnose and fix — don't skip the check or delete the failing code.

Reference Files

Load the relevant reference file when working on a module:

Step 1: Execute Modules

Instructions

• Execute the instructions of the modules according to the following Decision Gate Table
• Always log which Module and Gate check is evaluated and the status using the format: Gate result: and <CONDITION_EVALUATED>

Decision Gate Table

• For each module, evaluate whether it applies by inspecting <source>. A module executes only when its gate status is: PASS.
• Inspect <source> to determine the gate result -- do not rely on blind grep commands; use your understanding of the codebase.

Execution Protocol

STEP 0 — PREREQUISITE GATE (mandatory, runs before everything else)
  1. LOAD modules/prerequisite/prerequisite.md and execute all checks
  2. IF prerequisite gate == FAIL

Running Individual Modules

To run a single module outside the full migration flow, read all the files in the module folder directly:

• "Read modules/build/build.md and execute it"
• "Run only the frontend module"
• "Re-run the cleanup module"

The module will use the current <source> and <target> paths and the chosen strategy (if already decided). If no strategy has been chosen, the module will ask.

Step 2: Verify the Migration

All verification checks run against <target>. Run each check in order. A check fails = stop and fix before continuing.

Step 3: Reporting

After verification completes, run the reporting module. It reads the verification results and all per-module data to produce:

• <target>/migration-metadata/execution-metadata.json -- agent, model, tokens, cost, timing, verification results
• <target>/migration-summary.md -- full 13-section migration report

The reporting module must run after verification so that it can include check results and record an accurate finished_at timestamp.

Console Summary

After the reporting module completes, present the following directly to the user so they get an immediate overview without opening the generated files.

Answer each question honestly:

1. What migrated cleanly? Patterns that mapped 1:1.
2. What required manual judgment? Non-obvious decisions made.
3. What was left as TODO? Every // TODO: Migration required comment and why.
4. Was any code removed? What, where, justification. Flag runtime risks.
5. What checks failed initially? Failures from verification and how you fixed them.
6. What's missing from the skill references? Mappings you had to figure out.

Then present the review as a structured report: