---
name: migrate-spring-to-jakarta
description: Migrate Java applications from Spring Framework to Jakarta EE running on OpenLiberty with one-shot execution. Use when converting Spring Boot or Spring Framework projects to Jakarta EE/OpenLiberty, modernizing Spring services to standards-based Jakarta APIs, or when asked to perform Spring-to-Jakarta dependency, configuration, annotation, and build migration with compile validation and migration logging.
---

# Spring to Jakarta Migration (OpenLiberty)

Execute the migration autonomously in one run. Do not ask follow-up questions unless blocked by missing or unreadable files.

## Operating Contract

Follow these constraints for every run:

- Work only inside the provided project root.
- Prioritize successful compilation over stylistic refactors.
- Preserve business behavior while replacing framework integrations.
- Target OpenLiberty runtime assumptions for Jakarta EE packaging, APIs, and configuration.
- Keep a chronological migration log in `migration-artifacts/MONOLOUGE.log.md` with ISO8601 UTC timestamps and severity levels: `info`, `warning`, `error`.
- Persist verbose intermediate artifacts under `migration-artifacts/` for every step, including: thinking/reasoning notes, every tool/command call with inputs, raw tool outputs, interpretation of outputs, and explicit next-step decisions.

## Required Workflow

Run these steps in order and log each step outcome in `migration-artifacts/MONOLOUGE.log.md`.

1. Inspect project structure.
2. Detect build system and framework usage.
3. Migrate dependencies and plugins.
4. Migrate framework configuration.
5. Refactor framework-bound source code.
6. Compile and fix errors until build succeeds or no safe fix remains.
7. Produce a final migration report including file changes, chronological log, full `migration-artifacts/MONOLOUGE.log.md`, and unresolved issues.

## Step 1: Inspect Project Structure

- Identify build files (`pom.xml`, `build.gradle`, `settings.gradle`, wrappers).
- Detect module layout (single module vs multi-module).
- Enumerate framework-bound entrypoints and layers:
  - `@SpringBootApplication`
  - Spring MVC controllers
  - Spring Data repositories
  - Spring Security config
  - Spring configuration classes
- Record findings in `migration-artifacts/MONOLOUGE.log.md`.

## Step 2: Detect Migration Scope

- Locate Spring dependencies and plugins in build files.
- Locate Spring-specific configuration in:
  - `application.properties`
  - `application.yml`
  - XML config files
- Locate Spring API imports and annotations in Java/Kotlin sources.
- Use targeted search (`rg`) and log counts/locations.

## Step 3: Migrate Dependencies and Build

- Replace Spring dependencies with Jakarta APIs and OpenLiberty runtime dependencies.
- Remove Spring Boot plugin and executable-jar packaging assumptions.
- Add or adapt WAR packaging and OpenLiberty build plugin where needed.
- Keep non-framework libraries unless incompatible.
- Prefer current stable OpenLiberty/Jakarta coordinates already used in repository conventions when available.

For common mappings, read:

- `references/dependency-mapping.md`

Validation:

- Resolve dependencies by running a compile/package command before code refactors when feasible.
- If this early build fails due to known source incompatibility, continue and log why.

## Step 4: Migrate Configuration

- Convert Spring keys and conventions to OpenLiberty/Jakarta equivalents.
- Preserve ports, datasource settings, profile intent, and feature flags.
- Migrate or remove unsupported Spring-specific sections.
- Keep application-level config in project conventions and runtime-level settings in OpenLiberty config (`server.xml`, bootstrap variables) when needed.

For common property mappings, read:

- `references/config-mapping.md`

Validation:

- Re-check configuration syntax and required values before compile.

## Step 5: Refactor Source Code

- Replace Spring annotations/imports with CDI/JAX-RS/Jakarta equivalents.
- Replace constructor/field injection patterns with CDI idioms.
- Replace Spring MVC web layer with JAX-RS endpoints where needed.
- Replace Spring lifecycle and transactional APIs with Jakarta equivalents.
- Replace Spring Boot startup/bootstrap patterns with Jakarta-compatible application bootstrapping for OpenLiberty.

For common annotation and API mappings, read:

- `references/code-mapping.md`

Validation:

- After significant refactors, run a compile/build.
- Fix compile errors in small batches and log each resolution.

## Step 6: Compile and Iterate

Use commands that write local caches to project-local directories:

- Maven: `mvn -q -Dmaven.repo.local=.m2repo clean package`
- Gradle: `./gradlew -g .gradle clean build`

If build fails:

- Capture the exact failing symbols/classes/modules.
- Apply minimal, safe fix.
- Rebuild and repeat.
- If blocked, record clear mitigation steps for manual follow-up.

## Step 7: Logging and Report Requirements

For monologue and intermediate artifact capture requirements, read:

- `references/MONOLOUGE.md`

- `migration-artifacts/MONOLOUGE.log.md` is the only required migration log file and single source of truth.

`migration-artifacts/MONOLOUGE.log.md` format:

- Use one entry per action or corrective step.
- Include timestamp, severity, title, and details.
- For errors include:
  - failing file/area
  - root cause
  - attempted fix
  - final outcome

Final response format:

1. `Migration Summary`
2. `File Tree` with modified/added/removed files and short purpose notes
3. `Step-by-Step Log` in chronological order
4. `MONOLOUGE.log.md Contents` full file in fenced code block
5. `Error Handling` with counts, blockers, mitigations, and manual intervention flag

## Execution Policy

- Do not stop at partial edits when a safe next fix exists.
- Do not claim success without a compile attempt.
- If full migration is not possible, provide precise blockers and next actions.