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: <STATUS> 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
       → log "Migration aborted — prerequisite gate failed: <failing check(s)>"
       → STOP immediately. Do not evaluate or execute any further module.
  3. IF prerequisite gate == PASS (warnings are allowed)
       → log "Prerequisite gate: PASS — proceeding with migration"
       → continue to the module loop below

FOR module IN [planning, build, code, messaging, frontend, testing, cleanup]:

  1. EVALUATE — inspect <source> for the gate condition
  2. DECIDE
     IF gate == ALWAYS → proceed to step 3
     IF gate == PASS   → proceed to step 3
     IF gate == SKIP   → log "Module {name}: SKIPPED — {reason}", mark checkbox, continue
  3. LOAD — read the module file and relevant reference files
  4. EXECUTE — read from <source>, write to <target>. Follow the module instructions, adapting to the chosen strategy
  5. COMPILE — run the compile command in <target> (`cd <target> && ./mvnw clean compile -DskipTests` for Maven, `cd <target> && ./gradlew clean compileJava -x test` for Gradle)
     Fails → load [modules/compile-fix.md](modules/compile-fix.md) and follow the retry procedure.
             If compile-fix reports MANUAL_REVIEW_REQUIRED (unresolved errors after 3 retries),
             ask the user whether to continue with the next module or stop the migration.
  6. LOG — mark checkbox as done

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:

## Migration Report: [app-name]

### Summary
- Source: [source directory path]
- Target: [target directory path]
- Strategy: [Full Migration / Spring Compatibility]
- Agent: [AI agent name - e.g claude, pi, opencode, gemini, etc]
- Model: [model name — e.g. claude-sonnet-4-6, check system context]
- Modules completed: [X/8]
- Checks passed: [X/6]
- Token usage: [input tokens / output tokens — check session stats]
- Estimated cost: [~$X.XX — token counts × per-model pricing from anthropic.com/pricing]

### Changes by Module
| Module | Files changed | Key changes |
|--------|--------------|-------------|
| build | pom.xml or build.gradle(.kts), application.properties | ... |
| code | ... | ... |
| frontend | ... | ... |
| testing | ... | ... |

### Validation Results
| Check | Result | Notes |
|-------|--------|-------|
| Builds | PASS/FAIL | |
| No Spring deps | PASS/FAIL | |
| Has Quarkus | PASS/FAIL | |
| Tests pass | PASS/FAIL | |
| Starts up | PASS/FAIL | |
| No leftover templates | PASS/FAIL | |

### Unmigrated Code (TODOs)
| File | Line | What | Why not migrated |
|------|------|------|-----------------|

### Removed Code
| File | What was removed | Justification |
|------|-----------------|---------------|

### Skill Improvement Suggestions
- [Any missing mappings, unclear instructions, or edge cases discovered]