Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions .apm/skills/spring-to-quarkus/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
---
name: spring-to-quarkus
description: Assess, implement or review migration of a Spring or Spring Boot application to Quarkus, choosing native Quarkus APIs or documented Spring compatibility extensions and verifying HTTP, injection, configuration, security and persistence contracts. Use for framework replacement, not a Spring Boot version upgrade.
---

# Spring to Quarkus

Read [provenance and evidence boundaries](references/provenance.md). Inventory the source Spring/Boot version, JDK, language, build, MVC or WebFlux stack, bean lifecycle, configuration, security, data access, transactions, messaging and deployment. Establish observable contracts and a passing baseline before edits; preserve unrelated work.

Choose the destination with [migration decisions](references/migration.md): native CDI and Jakarta REST, or explicitly supported Spring annotation compatibility. Record unsupported features and a replacement for each. Do not assume that a Spring library works because its annotations compile, or infer Boot 4 compatibility from Boot 3 examples.

Resolve a compatible Quarkus platform, plugin and Java baseline from the selected release documentation. Replace Boot packaging and starters with selected Quarkus extensions. Preserve approved dependency sources and inspect the effective build and dependency tree.

Migrate one vertical slice through startup, constructor injection, configuration, HTTP binding, serialization and tests. Verify clean build-time augmentation and actual HTTP behaviour before expanding. Keep blocking persistence and network calls off event-loop threads; explicitly preserve cancellation and context when adapting Reactor to Mutiny.

Port security and integrations with negative-path tests. Preserve authorization, CSRF, TLS, transaction boundaries and database contracts. Do not widen access, enable destructive schema generation or silently start external test services to make tests pass.

Run [acceptance checks](references/verification.md). Remove obsolete Spring runtime and build components only after retained APIs have documented compatibility extensions or tested replacements. Review packaged execution separately from development mode; native-image support needs its own evidence.

Report the chosen strategy, pinned versions, unsupported features, changed contracts and commands with test counts, failures and skips. Distinguish local checks, CI and deployment. Upstream tools and this skill do not authorize commits, pull requests or production changes beyond the user's requested scope.
4 changes: 4 additions & 0 deletions .apm/skills/spring-to-quarkus/agents/openai.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
interface:
display_name: "Spring to Quarkus"
short_description: "Migrate Spring applications to verified Quarkus contracts"
default_prompt: "Use $spring-to-quarkus to assess this Spring application, choose a Quarkus migration strategy, and implement and verify a vertical slice."
32 changes: 32 additions & 0 deletions .apm/skills/spring-to-quarkus/references/migration.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
# Migration decisions

## Destination and upstream guidance

The [official migration overview](https://quarkus.io/spring/migrate/) describes native Quarkus and Spring compatibility destinations and links the [Quarkus agent skills](https://github.com/quarkusio/skills). Consult that maintained guidance when useful; review its source and current revision before installing or running it. This package does not install it automatically or copy its instructions. Tool-generated edits still require contract review.

Prefer native APIs when the intended result removes Spring dependencies. Compatibility can reduce changes where every retained annotation and API is documented for the chosen Quarkus version. Record that choice per module, including any temporary compatibility dependency and its removal criteria.

| Spring concern | Quarkus migration decision and verification |
| --- | --- |
| Boot parent, starters, launcher | Import a compatible platform BOM and matching Quarkus build plugin; choose extensions and packaging deliberately. Verify effective dependencies and packaged startup. |
| Bean configuration, injection, scopes | Map to CDI beans, qualifiers and producers; check discovery, scope, proxying, conditional beans and initialization order. Review reflection and dynamically registered beans against build-time discovery. |
| Spring DI compatibility | The extension interprets supported metadata without starting a Spring application context. ApplicationContext calls, BeanPostProcessors and arbitrary Spring infrastructure need replacements. |
| MVC controllers | Use Jakarta REST resources and the selected JSON extension, or supported Spring Web annotations with the required REST implementation. Verify binding, validation, exception mapping, content negotiation, status codes and error bodies. Servlet-specific filters and APIs need a separately justified stack. |
| WebFlux and Reactor | Decide threading and streaming contracts before adapting types. Preserve cancellation, backpressure and security context; verify blocking isolation. A synchronous return type does not prove reactive equivalence. |
| Properties and profiles | Map keys explicitly to Quarkus configuration and config mappings. Distinguish build-time settings from runtime overrides, including profile precedence and missing required values. |
| JPA and repositories | Choose Hibernate ORM/Panache or the documented Spring Data JPA subset. Inventory derived queries, custom repositories, pagination, projections and locking rather than assuming API coverage. Preserve identifiers and schema migrations. |
| Transactions | Map propagation, rollback rules and resource enlistment explicitly. Reactive persistence is a separate execution model, not a mechanical repository replacement. Test rollback and lazy access boundaries. |
| Security | Replace authentication providers and filter-chain behaviour explicitly. The Spring Security extension supports a subset of authorization annotations/expressions; it is not the Spring Security runtime. Verify role prefix semantics, method interception, OIDC/JWT, CSRF, CORS, sessions and tenant isolation as applicable. |
| Events, scheduling and messaging | Distinguish in-process events from durable messaging. Preserve acknowledgement, retry, ordering, scheduling concurrency and shutdown behaviour; do not replace delivery guarantees with local callbacks. |
| Actuator and operations | Map required health, metrics, tracing and management endpoints with equivalent exposure controls. Validate shutdown and readiness in the packaged application. |

## Version-specific sources

Read only the guides relevant to the inventory, using documentation matching the selected release:

- [CDI reference](https://quarkus.io/guides/cdi-reference) and [Spring DI](https://quarkus.io/guides/spring-di/): bean discovery and supported compatibility metadata.
- [REST](https://quarkus.io/guides/rest) and [Spring Web](https://quarkus.io/guides/spring-web/): HTTP bindings and execution model.
- [Configuration reference](https://quarkus.io/guides/config-reference): build/runtime settings and profiles.
- [Spring Data JPA](https://quarkus.io/guides/spring-data-jpa/) and [transactions](https://quarkus.io/guides/transaction): repository support and transaction semantics.
- [Spring Security](https://quarkus.io/guides/spring-security/) and [security overview](https://quarkus.io/guides/security-overview): supported authorization and authentication choices.
- [Testing](https://quarkus.io/guides/getting-started-testing): application and packaged integration test boundaries.
11 changes: 11 additions & 0 deletions .apm/skills/spring-to-quarkus/references/provenance.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# Provenance and scope

Independently authored for this marketplace on 2026-11-12 from official Quarkus documentation linked in [migration decisions](migration.md). The official migration overview links `quarkusio/skills`; this package references that upstream resource rather than copying or installing it. No upstream skill or vendor example source is redistributed. This is not a vendor-endorsed package.

Experimental; long-term named ownership remains unassigned. Requires consuming application source, compatible JDK/build tools, dependency access and approved test services. No MCP server or other installed skill is required. Cross-harness compatibility is not established.

The bounded fixture baseline pins Spring Boot 3.5.16 and Quarkus 3.40.1 on Java 17-compatible source. These versions are test evidence, not a universal target or a claim of latest-release coverage. CI runs both HTTP fixtures on Java 17. The pull request records actual local and hosted outcomes separately.

Structural validation, content audits and repository security scanners are distinct from behavioural migration tests. Python dependency auditing does not certify JVM dependencies or the security of a migrated application. Compatibility extensions, Boot 4 migration, Kotlin/Gradle, persistence, authentication, messaging, performance, native images and deployment remain outside this fixture's evidence.

Local verification on 2026-11-12: Maven 4.0.0-rc-7 / Java 25 ran both fixtures successfully, one real-HTTP test each with zero failures, errors or skips. The Quarkus package build also passed. This does not establish packaged process or native-image execution.
16 changes: 16 additions & 0 deletions .apm/skills/spring-to-quarkus/references/verification.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
# Acceptance evidence

Compare the same external contracts before and after migration. Use isolated, approved test services and explicit timeouts; inspect test counts and skipped tests.

| Area | Required evidence when applicable |
| --- | --- |
| Build and startup | Clean augmentation, resolved BOM/plugin versions, discovered beans, required configuration errors and packaged process startup. |
| HTTP | Real requests for successful JSON, absent routes, invalid inputs, exception bodies, methods, content types, dates, decimals and nulls. |
| Injection/configuration | Constructor dependencies, qualifiers, scopes, conditional components, profile precedence and runtime overrides. |
| Security | Anonymous, expired credentials, insufficient roles, allowed users and cross-tenant denials; management endpoint exposure and browser protections. |
| Data | Representative repository queries, pagination, transaction commit/rollback, schema compatibility and concurrency. |
| Reactive/integrations | Event-loop isolation, cancellation, streaming/backpressure, messaging retries/acknowledgement and context propagation. |
| Operations | Readiness/liveness, shutdown, metrics/tracing, deployment configuration and rollback procedure. |
| Removal | Dependency tree and source search identify remaining Spring APIs and their intentional compatibility providers; no obsolete Boot launcher. |

Repository smoke fixtures compare the existing Spring baseline at `tests/fixtures/spring-to-micronaut-baseline` with `tests/fixtures/spring-to-quarkus`. Both exercise constructor injection and real HTTP: JSON success, content type and missing-route status. The new target uses native CDI and Jakarta REST, not Spring compatibility. These checks do not establish security, persistence, reactive, compatibility-extension, native-image or production acceptance. An application migration needs the broader scenarios above.
16 changes: 16 additions & 0 deletions .github/workflows/validate.yml
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,22 @@ jobs:
run: mvn --batch-mode --no-transfer-progress -f tests/fixtures/spring-to-micronaut-baseline/pom.xml verify
- name: Verify native Micronaut fixture
run: mvn --batch-mode --no-transfer-progress -f tests/fixtures/spring-to-micronaut/pom.xml verify
spring-quarkus-smoke:
name: Spring to Quarkus native HTTP contract
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
with:
persist-credentials: false
- uses: actions/setup-java@b6effb05e454b25005698d916606bdc6ffcbf961 # v5
with:
distribution: temurin
java-version: '17'
- name: Verify Spring HTTP baseline
run: mvn --batch-mode --no-transfer-progress -f tests/fixtures/spring-to-micronaut-baseline/pom.xml verify
- name: Verify native Quarkus HTTP target
run: mvn --batch-mode --no-transfer-progress -f tests/fixtures/spring-to-quarkus/pom.xml verify
vertx-smoke:
name: Quarkus to Vert.x HTTP and event-bus smoke
runs-on: ubuntu-latest
Expand Down
6 changes: 6 additions & 0 deletions marketplace.json
Original file line number Diff line number Diff line change
Expand Up @@ -100,6 +100,12 @@
"description": "Migrate Quarkus services to Kotlin http4k handlers. Experimental guidance.",
"category": "Migration",
"source": "./.apm/skills/quarkus-to-http4k"
},
{
"name": "spring-to-quarkus",
"description": "Experimental Spring-to-Quarkus migration with native and compatibility strategy assessment and HTTP verification.",
"category": "Migration",
"source": "./.apm/skills/spring-to-quarkus"
}
]
}
7 changes: 7 additions & 0 deletions tests/fixtures/spring-to-quarkus/pom.xml
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
<project xmlns="http://maven.apache.org/POM/4.0.0">
<modelVersion>4.0.0</modelVersion><groupId>example</groupId><artifactId>spring-to-quarkus-smoke</artifactId><version>1.0</version>
<properties><maven.compiler.release>17</maven.compiler.release><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding><quarkus.version>3.40.1</quarkus.version></properties>
<dependencyManagement><dependencies><dependency><groupId>io.quarkus.platform</groupId><artifactId>quarkus-bom</artifactId><version>${quarkus.version}</version><type>pom</type><scope>import</scope></dependency></dependencies></dependencyManagement>
<dependencies><dependency><groupId>io.quarkus</groupId><artifactId>quarkus-rest-jackson</artifactId></dependency><dependency><groupId>io.quarkus</groupId><artifactId>quarkus-junit5</artifactId><scope>test</scope></dependency></dependencies>
<build><plugins><plugin><groupId>io.quarkus.platform</groupId><artifactId>quarkus-maven-plugin</artifactId><version>${quarkus.version}</version><extensions>true</extensions><executions><execution><goals><goal>build</goal><goal>generate-code</goal><goal>generate-code-tests</goal></goals></execution></executions></plugin><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId><version>3.14.1</version><configuration><parameters>true</parameters></configuration></plugin><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-surefire-plugin</artifactId><version>3.5.4</version><configuration><failIfNoTests>true</failIfNoTests><systemPropertyVariables><java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager><quarkus.http.test-port>0</quarkus.http.test-port></systemPropertyVariables></configuration></plugin></plugins></build>
</project>
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
package example;

import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
import java.util.Map;

@Path("/hello")
public class GreetingResource {
private final GreetingService service;

@Inject
public GreetingResource(GreetingService service) { this.service = service; }

@GET
@Produces(MediaType.APPLICATION_JSON)
public Map<String, String> hello() { return Map.of("message", service.greeting()); }
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
package example;

import jakarta.enterprise.context.ApplicationScoped;

@ApplicationScoped
public class GreetingService {
public String greeting() { return "hello"; }
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
package example;
import io.quarkus.test.junit.QuarkusTest;
import io.quarkus.test.common.http.TestHTTPResource;
import java.net.URI;
import java.net.http.*;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.*;
@QuarkusTest
class MigrationTest {
@TestHTTPResource URI base;
@Test void httpContracts() throws Exception {
HttpClient client = HttpClient.newHttpClient();
var response = client.send(HttpRequest.newBuilder(base.resolve("/hello")).timeout(java.time.Duration.ofSeconds(5)).GET().build(), HttpResponse.BodyHandlers.ofString());
assertEquals(200, response.statusCode());
assertEquals("{\"message\":\"hello\"}", response.body());
assertTrue(response.headers().firstValue("content-type").orElse("").startsWith("application/json"));
var missing = client.send(HttpRequest.newBuilder(base.resolve("/missing")).timeout(java.time.Duration.ofSeconds(5)).GET().build(), HttpResponse.BodyHandlers.ofString());
assertEquals(404, missing.statusCode());
}
}
Loading