Skip to content

armgit / ECC

Public Imported from GitHub
0

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

docs: salvage Quarkus framework skills

Affaan Mustafa60782502d54e
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index b12310b58..612c86272 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -11,7 +11,7 @@
{
"name": "ecc",
"source": "./",
- "description": "The most comprehensive Claude Code plugin — 56 agents, 209 skills, 72 legacy command shims, selective install profiles, and production-ready hooks for TDD, security scanning, code review, and continuous learning",
+ "description": "The most comprehensive Claude Code plugin — 56 agents, 213 skills, 72 legacy command shims, selective install profiles, and production-ready hooks for TDD, security scanning, code review, and continuous learning",
"version": "2.0.0-rc.1",
"author": {
"name": "Affaan Mustafa",
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index f946782d2..7969aca05 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "ecc",
"version": "2.0.0-rc.1",
- "description": "Battle-tested Claude Code plugin for engineering teams — 56 agents, 209 skills, 72 legacy command shims, production-ready hooks, and selective install workflows evolved through continuous real-world use",
+ "description": "Battle-tested Claude Code plugin for engineering teams — 56 agents, 213 skills, 72 legacy command shims, production-ready hooks, and selective install workflows evolved through continuous real-world use",
"author": {
"name": "Affaan Mustafa",
"url": "https://x.com/affaanmustafa"
diff --git a/AGENTS.md b/AGENTS.md
index a2c7b6388..196c3f90f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,6 +1,6 @@
# Everything Claude Code (ECC) — Agent Instructions
-This is a **production-ready AI coding plugin** providing 56 specialized agents, 209 skills, 72 commands, and automated hook workflows for software development.
+This is a **production-ready AI coding plugin** providing 56 specialized agents, 213 skills, 72 commands, and automated hook workflows for software development.
**Version:** 2.0.0-rc.1
@@ -148,7 +148,7 @@ Troubleshoot failures: check test isolation → verify mocks → fix implementat
```
agents/ — 56 specialized subagents
-skills/ — 209 workflow skills and domain knowledge
+skills/ — 213 workflow skills and domain knowledge
commands/ — 72 slash commands
hooks/ — Trigger-based automations
rules/ — Always-follow guidelines (common + per-language)
diff --git a/README.md b/README.md
index 36a65a829..cf6bc7140 100644
--- a/README.md
+++ b/README.md
@@ -358,7 +358,7 @@ If you stacked methods, clean up in this order:
/plugin list ecc@ecc
```
-**That's it!** You now have access to 56 agents, 209 skills, and 72 legacy command shims.
+**That's it!** You now have access to 56 agents, 213 skills, and 72 legacy command shims.
### Dashboard GUI
@@ -526,6 +526,10 @@ everything-claude-code/
| |-- springboot-security/ # Spring Boot security (NEW)
| |-- springboot-tdd/ # Spring Boot TDD (NEW)
| |-- springboot-verification/ # Spring Boot verification (NEW)
+| |-- quarkus-patterns/ # Quarkus REST, Panache, and messaging patterns (NEW)
+| |-- quarkus-security/ # Quarkus JWT/OIDC and RBAC security (NEW)
+| |-- quarkus-tdd/ # Quarkus testing with JUnit, REST Assured, and Dev Services (NEW)
+| |-- quarkus-verification/ # Quarkus build, test, security, and native verification (NEW)
| |-- configure-ecc/ # Interactive installation wizard (NEW)
| |-- security-scan/ # AgentShield security auditor integration (NEW)
| |-- java-coding-standards/ # Java coding standards (NEW)
@@ -1358,7 +1362,7 @@ The configuration is automatically detected from `.opencode/opencode.json`.
|---------|-------------|----------|--------|
| Agents | PASS: 56 agents | PASS: 12 agents | **Claude Code leads** |
| Commands | PASS: 72 commands | PASS: 35 commands | **Claude Code leads** |
-| Skills | PASS: 209 skills | PASS: 37 skills | **Claude Code leads** |
+| Skills | PASS: 213 skills | PASS: 37 skills | **Claude Code leads** |
| Hooks | PASS: 8 event types | PASS: 11 events | **OpenCode has more!** |
| Rules | PASS: 29 rules | PASS: 13 instructions | **Claude Code leads** |
| MCP Servers | PASS: 14 servers | PASS: Full | **Full parity** |
@@ -1463,7 +1467,7 @@ ECC is the **first plugin to maximize every major AI coding tool**. Here's how e
|---------|------------|------------|-----------|----------|
| **Agents** | 56 | Shared (AGENTS.md) | Shared (AGENTS.md) | 12 |
| **Commands** | 72 | Shared | Instruction-based | 35 |
-| **Skills** | 209 | Shared | 10 (native format) | 37 |
+| **Skills** | 213 | Shared | 10 (native format) | 37 |
| **Hook Events** | 8 types | 15 types | None yet | 11 types |
| **Hook Scripts** | 20+ scripts | 16 scripts (DRY adapter) | N/A | Plugin hooks |
| **Rules** | 34 (common + lang) | 34 (YAML frontmatter) | Instruction-based | 13 instructions |
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 14e6f013f..0504057a0 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -160,7 +160,7 @@ Copy-Item -Recurse rules/typescript "$HOME/.claude/rules/"
/plugin list ecc@ecc
```
-**完成!** 你现在可以使用 56 个代理、209 个技能和 72 个命令。
+**完成!** 你现在可以使用 56 个代理、213 个技能和 72 个命令。
### multi-* 命令需要额外配置
diff --git a/agent.yaml b/agent.yaml
index 53c35b17b..a21c3391f 100644
--- a/agent.yaml
+++ b/agent.yaml
@@ -113,6 +113,10 @@ skills:
- python-testing
- pytorch-patterns
- quality-nonconformance
+ - quarkus-patterns
+ - quarkus-security
+ - quarkus-tdd
+ - quarkus-verification
- ralphinho-rfc-pipeline
- regex-vs-llm-structured-text
- repo-scan
diff --git a/docs/zh-CN/AGENTS.md b/docs/zh-CN/AGENTS.md
index 44a10ec5f..9f3f4895f 100644
--- a/docs/zh-CN/AGENTS.md
+++ b/docs/zh-CN/AGENTS.md
@@ -1,6 +1,6 @@
# Everything Claude Code (ECC) — 智能体指令
-这是一个**生产就绪的 AI 编码插件**,提供 56 个专业代理、209 项技能、72 条命令以及自动化钩子工作流,用于软件开发。
+这是一个**生产就绪的 AI 编码插件**,提供 56 个专业代理、213 项技能、72 条命令以及自动化钩子工作流,用于软件开发。
**版本:** 2.0.0-rc.1
@@ -147,7 +147,7 @@
```
agents/ — 56 个专业子代理
-skills/ — 209 个工作流技能和领域知识
+skills/ — 213 个工作流技能和领域知识
commands/ — 72 个斜杠命令
hooks/ — 基于触发的自动化
rules/ — 始终遵循的指导方针(通用 + 每种语言)
diff --git a/docs/zh-CN/README.md b/docs/zh-CN/README.md
index 4df8718f1..61cb39e10 100644
--- a/docs/zh-CN/README.md
+++ b/docs/zh-CN/README.md
@@ -224,7 +224,7 @@ Copy-Item -Recurse rules/typescript "$HOME/.claude/rules/"
/plugin list ecc@ecc
```
-**搞定!** 你现在可以使用 56 个智能体、209 项技能和 72 个命令了。
+**搞定!** 你现在可以使用 56 个智能体、213 项技能和 72 个命令了。
***
@@ -1134,7 +1134,7 @@ opencode
|---------|-------------|----------|--------|
| 智能体 | PASS: 56 个 | PASS: 12 个 | **Claude Code 领先** |
| 命令 | PASS: 72 个 | PASS: 35 个 | **Claude Code 领先** |
-| 技能 | PASS: 209 项 | PASS: 37 项 | **Claude Code 领先** |
+| 技能 | PASS: 213 项 | PASS: 37 项 | **Claude Code 领先** |
| 钩子 | PASS: 8 种事件类型 | PASS: 11 种事件 | **OpenCode 更多!** |
| 规则 | PASS: 29 条 | PASS: 13 条指令 | **Claude Code 领先** |
| MCP 服务器 | PASS: 14 个 | PASS: 完整 | **完全对等** |
@@ -1242,7 +1242,7 @@ ECC 是**第一个最大化利用每个主要 AI 编码工具的插件**。以
|---------|------------|------------|-----------|----------|
| **智能体** | 56 | 共享 (AGENTS.md) | 共享 (AGENTS.md) | 12 |
| **命令** | 72 | 共享 | 基于指令 | 35 |
-| **技能** | 209 | 共享 | 10 (原生格式) | 37 |
+| **技能** | 213 | 共享 | 10 (原生格式) | 37 |
| **钩子事件** | 8 种类型 | 15 种类型 | 暂无 | 11 种类型 |
| **钩子脚本** | 20+ 个脚本 | 16 个脚本 (DRY 适配器) | N/A | 插件钩子 |
| **规则** | 34 (通用 + 语言) | 34 (YAML 前页) | 基于指令 | 13 条指令 |
diff --git a/manifests/install-components.json b/manifests/install-components.json
index 28c107f68..9076882bd 100644
--- a/manifests/install-components.json
+++ b/manifests/install-components.json
@@ -121,6 +121,15 @@
"framework-language"
]
},
+ {
+ "id": "framework:quarkus",
+ "family": "framework",
+ "description": "Quarkus-focused engineering guidance for REST, Panache, security, testing, and verification.",
+ "modules": [
+ "framework-language",
+ "security"
+ ]
+ },
{
"id": "capability:database",
"family": "capability",
diff --git a/manifests/install-modules.json b/manifests/install-modules.json
index 6c37b0639..627a27efe 100644
--- a/manifests/install-modules.json
+++ b/manifests/install-modules.json
@@ -157,6 +157,9 @@
"skills/perl-testing",
"skills/python-patterns",
"skills/python-testing",
+ "skills/quarkus-patterns",
+ "skills/quarkus-tdd",
+ "skills/quarkus-verification",
"skills/rust-patterns",
"skills/rust-testing",
"skills/springboot-patterns",
@@ -267,6 +270,7 @@
"skills/llm-trading-agent-security",
"skills/nodejs-keccak256",
"skills/perl-security",
+ "skills/quarkus-security",
"skills/security-review",
"skills/security-scan",
"skills/security-bounty-hunter",
diff --git a/package.json b/package.json
index 7960dd3b7..7f4aff764 100644
--- a/package.json
+++ b/package.json
@@ -215,6 +215,10 @@
"skills/python-patterns/",
"skills/python-testing/",
"skills/quality-nonconformance/",
+ "skills/quarkus-patterns/",
+ "skills/quarkus-security/",
+ "skills/quarkus-tdd/",
+ "skills/quarkus-verification/",
"skills/ralphinho-rfc-pipeline/",
"skills/regex-vs-llm-structured-text/",
"skills/remotion-video-creation/",
diff --git a/rules/java/patterns.md b/rules/java/patterns.md
index 570282bd4..44ed3f2fa 100644
--- a/rules/java/patterns.md
+++ b/rules/java/patterns.md
@@ -143,4 +143,5 @@ public record ApiResponse<T>(boolean success, T data, String error) {
## References
See skill: `springboot-patterns` for Spring Boot architecture patterns.
+See skill: `quarkus-patterns` for Quarkus architecture patterns with REST, Panache, and messaging.
See skill: `jpa-patterns` for entity design and query optimization.
diff --git a/rules/java/security.md b/rules/java/security.md
index 31ca61b69..cbedc120f 100644
--- a/rules/java/security.md
+++ b/rules/java/security.md
@@ -97,4 +97,5 @@ try {
## References
See skill: `springboot-security` for Spring Security authentication and authorization patterns.
+See skill: `quarkus-security` for Quarkus security with JWT/OIDC, RBAC, and CDI.
See skill: `security-review` for general security checklists.
diff --git a/rules/java/testing.md b/rules/java/testing.md
index aa2e91f32..177b264af 100644
--- a/rules/java/testing.md
+++ b/rules/java/testing.md
@@ -112,6 +112,7 @@ class OrderRepositoryIT {
```
For Spring Boot integration tests, see skill: `springboot-tdd`.
+For Quarkus integration tests, see skill: `quarkus-tdd`.
## Test Naming
@@ -128,4 +129,5 @@ Use descriptive names with `@DisplayName`:
## References
See skill: `springboot-tdd` for Spring Boot TDD patterns with MockMvc and Testcontainers.
+See skill: `quarkus-tdd` for Quarkus TDD patterns with REST Assured and Dev Services.
See skill: `java-coding-standards` for testing expectations.
diff --git a/skills/quarkus-patterns/SKILL.md b/skills/quarkus-patterns/SKILL.md
new file mode 100644
index 000000000..3de2cc71d
--- /dev/null
+++ b/skills/quarkus-patterns/SKILL.md
@@ -0,0 +1,722 @@
+---
+name: quarkus-patterns
+description: Quarkus 3.x LTS architecture patterns with Camel for messaging, RESTful API design, CDI services, data access with Panache, and async processing. Use for Java Quarkus backend work with event-driven architectures.
+origin: ECC
+---
+
+# Quarkus Development Patterns
+
+Quarkus 3.x architecture and API patterns for cloud-native, event-driven services with Apache Camel.
+
+## When to Activate
+
+- Building REST APIs with JAX-RS or RESTEasy Reactive
+- Structuring resource → service → repository layers
+- Implementing event-driven patterns with Apache Camel and RabbitMQ
+- Configuring Hibernate Panache, caching, or reactive streams
+- Adding validation, exception mapping, or pagination
+- Setting up profiles for dev/staging/production environments (YAML config)
+- Custom logging with LogContext and Logback/Logstash encoder
+- Working with CompletableFuture for async operations
+- Implementing conditional flow processing
+- Working with GraalVM native compilation
+
+## Service Layer with Multiple Dependencies
+
+```java
+@Slf4j
+@ApplicationScoped
+@RequiredArgsConstructor
+public class OrderProcessingService {
+
+ private final OrderValidator orderValidator;
+ private final EventService eventService;
+ private final OrderRepository orderRepository;
+ private final FulfillmentPublisher fulfillmentPublisher;
+ private final AuditPublisher auditPublisher;
+
+ @Transactional
+ public OrderReceipt process(CreateOrderCommand command) {
+ ValidationResult validation = orderValidator.validate(command);
+ if (!validation.valid()) {
+ eventService.createErrorEvent(command, "ORDER_REJECTED", validation.message());
+ throw new WebApplicationException(validation.message(), Response.Status.BAD_REQUEST);
+ }
+
+ Order order = Order.from(command);
+ orderRepository.persist(order);
+
+ OrderReceipt receipt = OrderReceipt.from(order);
+ fulfillmentPublisher.publishAsync(receipt);
+ auditPublisher.publish("ORDER_ACCEPTED", receipt);
+ eventService.createSuccessEvent(receipt, "ORDER_ACCEPTED");
+
+ log.info("Processed order {}", order.id);
+ return receipt;
+ }
+}
+```
+
+**Key Patterns:**
+- `@RequiredArgsConstructor` for constructor injection via Lombok
+- `@Slf4j` for Logback logging
+- `@Transactional` on service methods that write through Panache or repositories
+- Validate input before persistence or message publication
+- Event tracking for success/error scenarios
+- Async Camel message publishing
+
+## Custom Logging Context Pattern (Logback)
+
+```java
+@ApplicationScoped
+public class ProcessingService {
+
+ public void processDocument(Document doc) {
+ LogContext logContext = CustomLog.getCurrentContext();
+ try (SafeAutoCloseable ignored = CustomLog.startScope(logContext)) {
+ // Add context to all log statements
+ logContext.put("documentId", doc.getId().toString());
+ logContext.put("documentType", doc.getType());
+ logContext.put("userId", SecurityContext.getUserId());
+
+ log.info("Starting document processing");
+
+ // All logs within this scope inherit the context
+ processInternal(doc);
+
+ log.info("Document processing completed");
+ } catch (Exception e) {
+ log.error("Document processing failed", e);
+ throw e;
+ }
+ }
+}
+```
+
+**Logback Configuration (logback.xml):**
+
+```xml
+<configuration>
+ <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
+ <encoder class="net.logstash.logback.encoder.LogstashEncoder">
+ <includeContext>true</includeContext>
+ <includeMdc>true</includeMdc>
+ </encoder>
+ </appender>
+
+ <logger name="com.example" level="INFO"/>
+ <root level="WARN">
+ <appender-ref ref="CONSOLE"/>
+ </root>
+</configuration>
+```
+
+## Event Service Pattern
+
+```java
+@Slf4j
+@ApplicationScoped
+@RequiredArgsConstructor
+public class EventService {
+ private final EventRepository eventRepository;
+ private final ObjectMapper objectMapper;
+
+ public void createSuccessEvent(Object payload, String eventType) {
+ Objects.requireNonNull(payload, "Payload cannot be null");
+ Event event = new Event();
+ event.setType(eventType);
+ event.setStatus(EventStatus.SUCCESS);
+ event.setPayload(serializePayload(payload));
+ event.setTimestamp(Instant.now());
+
+ eventRepository.persist(event);
+ log.info("Success event created: {}", eventType);
+ }
+
+ public void createErrorEvent(Object payload, String eventType, String errorMessage) {
+ Objects.requireNonNull(payload, "Payload cannot be null");
+ if (errorMessage == null || errorMessage.isBlank()) {
+ throw new IllegalArgumentException("Error message cannot be blank");
+ }
+ Event event = new Event();
+ event.setType(eventType);
+ event.setStatus(EventStatus.ERROR);
+ event.setErrorMessage(errorMessage);
+ event.setPayload(serializePayload(payload));
+ event.setTimestamp(Instant.now());
+
+ eventRepository.persist(event);
+ log.error("Error event created: {} - {}", eventType, errorMessage);
+ }
+
+ private String serializePayload(Object payload) {
+ try {
+ return objectMapper.writeValueAsString(payload);
+ } catch (JsonProcessingException e) {
+ throw new IllegalStateException("Failed to serialize event payload", e);
+ }
+ }
+}
+```
+
+## Camel Message Publishing (RabbitMQ)
+
+```java
+@Slf4j
+@ApplicationScoped
+@RequiredArgsConstructor
+public class BusinessRulesPublisher {
+ private final ProducerTemplate producerTemplate;
+
+ public void publishSync(BusinessRulesPayload payload) {
+ producerTemplate.sendBody(
+ "direct:business-rules-publisher",
+ payload
+ );
+ }
+}
+```
+
+**Camel Route Configuration:**
+
+```java
+@ApplicationScoped
+public class BusinessRulesRoute extends RouteBuilder {
+
+ @ConfigProperty(name = "camel.rabbitmq.queue.business-rules")
+ String businessRulesQueue;
+
+ @ConfigProperty(name = "rabbitmq.host")
+ String rabbitHost;
+
+ @ConfigProperty(name = "rabbitmq.port")
+ Integer rabbitPort;
+
+ @Override
+ public void configure() {
+ from("direct:business-rules-publisher")
+ .routeId("business-rules-publisher")
+ .log("Publishing message to RabbitMQ: ${body}")
+ .marshal().json(JsonLibrary.Jackson)
+ .toF("spring-rabbitmq:%s?hostname=%s&portNumber=%d",
+ businessRulesQueue, rabbitHost, rabbitPort);
+ }
+}
+```
+
+## Camel Direct Routes (In-Memory)
+
+```java
+@ApplicationScoped
+public class DocumentProcessingRoute extends RouteBuilder {
+
+ @Override
+ public void configure() {
+ // Error handling
+ onException(ValidationException.class)
+ .handled(true)
+ .to("direct:validation-error-handler")
+ .log("Validation error: ${exception.message}");
+
+ // Main processing route
+ from("direct:process-document")
+ .routeId("document-processing")
+ .log("Processing document: ${header.documentId}")
+ .bean(DocumentValidator.class, "validate")
+ .bean(DocumentTransformer.class, "transform")
+ .choice()
+ .when(header("documentType").isEqualTo("INVOICE"))
+ .to("direct:process-invoice")
+ .when(header("documentType").isEqualTo("CREDIT_NOTE"))
+ .to("direct:process-credit-note")
+ .otherwise()
+ .to("direct:process-generic")
+ .end();
+
+ from("direct:validation-error-handler")
+ .bean(EventService.class, "createErrorEvent")
+ .log("Validation error handled");
+ }
+}
+```
+
+## Camel File Processing
+
+```java
+@ApplicationScoped
+public class FileMonitoringRoute extends RouteBuilder {
+
+ @ConfigProperty(name = "file.input.directory")
+ String inputDirectory;
+
+ @ConfigProperty(name = "file.processed.directory")
+ String processedDirectory;
+
+ @ConfigProperty(name = "file.error.directory")
+ String errorDirectory;
+
+ @Override
+ public void configure() {
+ from("file:" + inputDirectory + "?move=" + processedDirectory +
+ "&moveFailed=" + errorDirectory + "&delay=5000")
+ .routeId("file-monitor")
+ .log("Processing file: ${header.CamelFileName}")
+ .to("direct:process-file");
+
+ from("direct:process-file")
+ .bean(OrderProcessingService.class, "processFile")
+ .log("File processing completed");
+ }
+}
+```
+
+## Camel Bean Invocation
+
+```java
+@ApplicationScoped
+public class InvoiceRoute extends RouteBuilder {
+
+ @Override
+ public void configure() {
+ from("direct:invoice-validation")
+ .bean(InvoiceFlowValidator.class, "validateFlowWithConfig")
+ .log("Validation result: ${body}");
+
+ from("direct:persist-and-publish")
+ .bean(DocumentJobService.class, "createDocumentAndJobEntities")
+ .bean(BusinessRulesPublisher.class, "publishAsync")
+ .bean(EventService.class, "createSuccessEvent(${body}, 'PUBLISHED')");
+ }
+}
+```
+
+## REST API Structure
+
+```java
+@Path("/api/documents")
+@Produces(MediaType.APPLICATION_JSON)
+@Consumes(MediaType.APPLICATION_JSON)
+@RequiredArgsConstructor
+public class DocumentResource {
+ private final DocumentService documentService;
+
+ @GET
+ public Response list(
+ @QueryParam("page") @DefaultValue("0") int page,
+ @QueryParam("size") @DefaultValue("20") int size) {
+ List<Document> documents = documentService.list(page, size);
+ return Response.ok(documents).build();
+ }
+
+ @POST
+ public Response create(@Valid CreateDocumentRequest request, @Context UriInfo uriInfo) {
+ Document document = documentService.create(request);
+ URI location = uriInfo.getAbsolutePathBuilder()
+ .path(String.valueOf(document.id))
+ .build();
+ return Response.created(location).entity(DocumentResponse.from(document)).build();
+ }
+
+ @GET
+ @Path("/{id}")
+ public Response getById(@PathParam("id") Long id) {
+ return documentService.findById(id)
+ .map(DocumentResponse::from)
+ .map(Response::ok)
+ .orElse(Response.status(Response.Status.NOT_FOUND))
+ .build();
+ }
+}
+```
+
+## Repository Pattern (Panache Repository)
+
+```java
+@ApplicationScoped
+public class DocumentRepository implements PanacheRepository<Document> {
+
+ public List<Document> findByStatus(DocumentStatus status, int page, int size) {
+ return find("status = ?1 order by createdAt desc", status)
+ .page(page, size)
+ .list();
+ }
+
+ public Optional<Document> findByReferenceNumber(String referenceNumber) {
+ return find("referenceNumber", referenceNumber).firstResultOptional();
+ }
+
+ public long countByStatusAndDate(DocumentStatus status, LocalDate date) {
+ return count("status = ?1 and createdAt >= ?2", status, date.atStartOfDay());
+ }
+}
+```
+
+## Service Layer with Transactions
+
+```java
+@ApplicationScoped
+@RequiredArgsConstructor
+public class DocumentService {
+ private final DocumentRepository repo;
+ private final EventService eventService;
+
+ @Transactional
+ public Document create(CreateDocumentRequest request) {
+ Document document = new Document();
+ document.setReferenceNumber(request.referenceNumber());
+ document.setDescription(request.description());
+ document.setStatus(DocumentStatus.PENDING);
+ document.setCreatedAt(Instant.now());
+
+ repo.persist(document);
+
+ eventService.createSuccessEvent(document, "DOCUMENT_CREATED");
+
+ return document;
+ }
+
+ public Optional<Document> findById(Long id) {
+ return repo.findByIdOptional(id);
+ }
+
+ public List<Document> list(int page, int size) {
+ return repo.findAll()
+ .page(page, size)
+ .list();
+ }
+}
+```
+
+## DTOs and Validation
+
+```java
+public record CreateDocumentRequest(
+ @NotBlank @Size(max = 200) String referenceNumber,
+ @NotBlank @Size(max = 2000) String description,
+ @NotNull @FutureOrPresent Instant validUntil,
+ @NotEmpty List<@NotBlank String> categories) {}
+
+public record DocumentResponse(Long id, String referenceNumber, DocumentStatus status) {
+ public static DocumentResponse from(Document document) {
+ return new DocumentResponse(document.getId(), document.getReferenceNumber(),
+ document.getStatus());
+ }
+}
+```
+
+## Exception Mapping
+
+```java
+@Provider
+public class ValidationExceptionMapper implements ExceptionMapper<ConstraintViolationException> {
+ @Override
+ public Response toResponse(ConstraintViolationException exception) {
+ String message = exception.getConstraintViolations().stream()
+ .map(cv -> cv.getPropertyPath() + ": " + cv.getMessage())
+ .collect(Collectors.joining(", "));
+
+ return Response.status(Response.Status.BAD_REQUEST)
+ .entity(Map.of("error", "validation_error", "message", message))
+ .build();
+ }
+}
+
+@Provider
+@Slf4j
+public class GenericExceptionMapper implements ExceptionMapper<Exception> {
+
+ @Override
+ public Response toResponse(Exception exception) {
+ log.error("Unhandled exception", exception);
+ return Response.status(Response.Status.INTERNAL_SERVER_ERROR)
+ .entity(Map.of("error", "internal_error", "message", "An unexpected error occurred"))
+ .build();
+ }
+}
+```
+
+## CompletableFuture Async Operations
+
+```java
+@Slf4j
+@ApplicationScoped
+@RequiredArgsConstructor
+public class FileStorageService {
+ private final S3Client s3Client;
+ private final ExecutorService executorService;
+
+ @ConfigProperty(name = "storage.bucket-name")
+ String bucketName;
+
+ public CompletableFuture<StoredDocumentInfo> uploadOriginalFile(
+ InputStream inputStream,
+ long size,
+ LogContext logContext,
+ InvoiceFormat format) {
+
+ return CompletableFuture.supplyAsync(() -> {
+ try (SafeAutoCloseable ignored = CustomLog.startScope(logContext)) {
+ String path = generateStoragePath(format);
+
+ PutObjectRequest request = PutObjectRequest.builder()
+ .bucket(bucketName)
+ .key(path)
+ .contentLength(size)
+ .build();
+
+ s3Client.putObject(request, RequestBody.fromInputStream(inputStream, size));
+
+ log.info("File uploaded to S3: {}", path);
+
+ return new StoredDocumentInfo(path, size, Instant.now());
+ } catch (Exception e) {
+ log.error("Failed to upload file to S3", e);
+ throw new StorageException("Upload failed", e);
+ }
+ }, executorService);
+ }
+}
+```
+
+## Caching
+
+```java
+@ApplicationScoped
+@RequiredArgsConstructor
+public class DocumentCacheService {
+ private final DocumentRepository repo;
+
+ @CacheResult(cacheName = "document-cache")
+ public Optional<Document> getById(@CacheKey Long id) {
+ return repo.findByIdOptional(id);
+ }
+
+ @CacheInvalidate(cacheName = "document-cache")
+ public void evict(@CacheKey Long id) {}
+
+ @CacheInvalidateAll(cacheName = "document-cache")
+ public void evictAll() {}
+}
+```
+
+## Configuration as YAML
+
+```yaml
+# application.yml
+"%dev":
+ quarkus:
+ datasource:
+ jdbc:
+ url: jdbc:postgresql://localhost:5432/dev_db
+ username: dev_user
+ password: ${DB_PASSWORD}
+ hibernate-orm:
+ database:
+ generation: drop-and-create
+
+ rabbitmq:
+ host: localhost
+ port: 5672
+ username: ${RABBITMQ_USER}
+ password: ${RABBITMQ_PASSWORD}
+
+"%test":
+ quarkus:
+ datasource:
+ jdbc:
+ url: jdbc:h2:mem:test
+ hibernate-orm:
+ database:
+ generation: drop-and-create
+
+"%prod":
+ quarkus:
+ datasource:
+ jdbc:
+ url: ${DATABASE_URL}
+ username: ${DB_USER}
+ password: ${DB_PASSWORD}
+ hibernate-orm:
+ database:
+ generation: validate
+
+ rabbitmq:
+ host: ${RABBITMQ_HOST}
+ port: ${RABBITMQ_PORT}
+ username: ${RABBITMQ_USER}
+ password: ${RABBITMQ_PASSWORD}
+
+# Camel configuration
+camel:
+ rabbitmq:
+ queue:
+ business-rules: business-rules-queue
+ invoice-processing: invoice-processing-queue
+```
+
+## Health Checks
+
+```java
+@Readiness
+@ApplicationScoped
+@RequiredArgsConstructor
+public class DatabaseHealthCheck implements HealthCheck {
+ private final AgroalDataSource dataSource;
+
+ @Override
+ public HealthCheckResponse call() {
+ try (Connection conn = dataSource.getConnection()) {
+ boolean valid = conn.isValid(2);
+ return HealthCheckResponse.named("Database connection")
+ .status(valid)
+ .build();
+ } catch (SQLException e) {
+ return HealthCheckResponse.down("Database connection");
+ }
+ }
+}
+
+@Liveness
+@ApplicationScoped
+public class CamelHealthCheck implements HealthCheck {
+ @Inject
+ CamelContext camelContext;
+
+ @Override
+ public HealthCheckResponse call() {
+ boolean isStarted = camelContext.getStatus().isStarted();
+ return HealthCheckResponse.named("Camel Context")
+ .status(isStarted)
+ .build();
+ }
+}
+```
+
+## Dependencies (Maven)
+
+```xml
+<properties>
+ <quarkus.platform.version>3.27.0</quarkus.platform.version>
+ <lombok.version>1.18.42</lombok.version>
+ <assertj-core.version>3.24.2</assertj-core.version>
+ <jacoco-maven-plugin.version>0.8.13</jacoco-maven-plugin.version>
+ <maven.compiler.release>17</maven.compiler.release>
+</properties>
+
+<dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>io.quarkus.platform</groupId>
+ <artifactId>quarkus-bom</artifactId>
+ <version>${quarkus.platform.version}</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+ <dependency>
+ <groupId>io.quarkus.platform</groupId>
+ <artifactId>quarkus-camel-bom</artifactId>
+ <version>${quarkus.platform.version}</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+ </dependencies>
+</dependencyManagement>
+
+<dependencies>
+ <!-- Quarkus Core -->
+ <dependency>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-arc</artifactId>
+ </dependency>
+ <dependency>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-config-yaml</artifactId>
+ </dependency>
+
+ <!-- Camel Extensions -->
+ <dependency>
+ <groupId>org.apache.camel.quarkus</groupId>
+ <artifactId>camel-quarkus-spring-rabbitmq</artifactId>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.camel.quarkus</groupId>
+ <artifactId>camel-quarkus-direct</artifactId>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.camel.quarkus</groupId>
+ <artifactId>camel-quarkus-bean</artifactId>
+ </dependency>
+
+ <!-- Lombok -->
+ <dependency>
+ <groupId>org.projectlombok</groupId>
+ <artifactId>lombok</artifactId>
+ <version>${lombok.version}</version>
+ <scope>provided</scope>
+ </dependency>
+
+ <!-- Logging -->
+ <dependency>
+ <groupId>io.quarkiverse.logging.logback</groupId>
+ <artifactId>quarkus-logging-logback</artifactId>
+ </dependency>
+ <dependency>
+ <groupId>net.logstash.logback</groupId>
+ <artifactId>logstash-logback-encoder</artifactId>
+ </dependency>
+</dependencies>
+```
+
+## Best Practices
+
+### Architecture
+- Use `@RequiredArgsConstructor` with Lombok for constructor injection
+- Keep service layer thin; delegate complex logic to specialized classes
+- Use Camel routes for message routing and integration patterns
+- Prefer Panache Repository pattern for data access
+
+### Event-Driven
+- Always track operations with EventService (success/error events)
+- Use Camel `direct:` endpoints for in-memory routing
+- Use `spring-rabbitmq` component for RabbitMQ integration
+- Implement async publishing with `ProducerTemplate.asyncSendBody()`
+
+### Logging
+- Use Logback with Logstash encoder for structured logging
+- Propagate LogContext through service calls with `SafeAutoCloseable`
+- Add contextual information to LogContext for request tracing
+- Use `@Slf4j` instead of manual logger instantiation
+
+### Async Operations
+- Use CompletableFuture for non-blocking I/O operations
+- Call `.join()` when you need to wait for completion
+- Handle exceptions from CompletableFuture properly
+- Pass LogContext to async operations for tracing
+
+### Configuration
+- Use YAML configuration (`quarkus-config-yaml`)
+- Profile-aware configuration for dev/test/prod environments
+- Externalize sensitive configuration to environment variables
+- Use `@ConfigProperty` for type-safe config injection
+
+### Validation
+- Validate at resource layer with `@Valid`
+- Use Bean Validation annotations on DTOs
+- Map exceptions to proper HTTP responses with `@Provider`
+
+### Transactions
+- Use `@Transactional` on service methods that modify data
+- Keep transactions short and focused
+- Avoid calling async operations within transactions
+
+### Testing
+- Use `camel-quarkus-junit5` for route testing
+- Use AssertJ for assertions
+- Mock all external dependencies
+- Test conditional flow logic thoroughly
+
+### Quarkus-Specific
+- Stay on latest LTS version (3.x)
+- Use Quarkus dev mode for hot reload
+- Add health checks for production readiness
+- Test native compilation compatibility periodically
diff --git a/skills/quarkus-security/SKILL.md b/skills/quarkus-security/SKILL.md
new file mode 100644
index 000000000..4a9af479a
--- /dev/null
+++ b/skills/quarkus-security/SKILL.md
@@ -0,0 +1,467 @@
+---
+name: quarkus-security
+description: Quarkus Security best practices for authentication, authorization, JWT/OIDC, RBAC, input validation, CSRF, secrets management, and dependency security.
+origin: ECC
+---
+
+# Quarkus Security Review
+
+Best practices for securing Quarkus applications with authentication, authorization, and input validation.
+
+## When to Activate
+
+- Adding authentication (JWT, OIDC, Basic Auth)
+- Implementing authorization with @RolesAllowed or SecurityIdentity
+- Validating user input (Bean Validation, custom validators)
+- Configuring CORS or security headers
+- Managing secrets (Vault, environment variables, config sources)
+- Adding rate limiting or brute-force protection
+- Scanning dependencies for CVEs
+- Working with MicroProfile JWT or SmallRye JWT
+
+## Authentication
+
+### JWT Authentication
+
+```java
+// Resource protected with JWT
+@Path("/api/protected")
+@Authenticated
+public class ProtectedResource {
+
+ @Inject
+ JsonWebToken jwt;
+
+ @Inject
+ SecurityIdentity securityIdentity;
+
+ @GET
+ public Response getData() {
+ String username = jwt.getName();
+ Set<String> roles = jwt.getGroups();
+ return Response.ok(Map.of(
+ "username", username,
+ "roles", roles,
+ "principal", securityIdentity.getPrincipal().getName()
+ )).build();
+ }
+}
+```
+
+Configuration (application.properties):
+```properties
+mp.jwt.verify.publickey.location=publicKey.pem
+mp.jwt.verify.issuer=https://auth.example.com
+
+# OIDC
+quarkus.oidc.auth-server-url=https://auth.example.com/realms/myrealm
+quarkus.oidc.client-id=backend-service
+quarkus.oidc.credentials.secret=${OIDC_SECRET}
+```
+
+### Custom Authentication Filter
+
+```java
+@Provider
+@Priority(Priorities.AUTHENTICATION)
+public class CustomAuthFilter implements ContainerRequestFilter {
+
+ @Inject
+ SecurityIdentity identity;
+
+ @Override
+ public void filter(ContainerRequestContext requestContext) {
+ String authHeader = requestContext.getHeaderString(HttpHeaders.AUTHORIZATION);
+
+ // Reject immediately if header is absent or malformed
+ if (authHeader == null || !authHeader.startsWith("Bearer ")) {
+ requestContext.abortWith(Response.status(Response.Status.UNAUTHORIZED).build());
+ return;
+ }
+
+ String token = authHeader.substring(7);
+ if (!validateToken(token)) {
+ requestContext.abortWith(Response.status(Response.Status.UNAUTHORIZED).build());
+ }
+ }
+
+ private boolean validateToken(String token) {
+ // Token validation logic
+ return true;
+ }
+}
+```
+
+## Authorization
+
+### Role-Based Access Control
+
+```java
+@Path("/api/admin")
+@RolesAllowed("ADMIN")
+public class AdminResource {
+
+ @GET
+ @Path("/users")
+ public List<UserDto> listUsers() {
+ return userService.findAll();
+ }
+
+ @DELETE
+ @Path("/users/{id}")
+ @RolesAllowed({"ADMIN", "SUPER_ADMIN"})
+ public Response deleteUser(@PathParam("id") Long id) {
+ userService.delete(id);
+ return Response.noContent().build();
+ }
+}
+
+@Path("/api/users")
+public class UserResource {
+
+ @Inject
+ SecurityIdentity securityIdentity;
+
+ @GET
+ @Path("/{id}")
+ @RolesAllowed("USER")
+ public Response getUser(@PathParam("id") Long id) {
+ // Check ownership
+ if (!securityIdentity.hasRole("ADMIN") &&
+ !isOwner(id, securityIdentity.getPrincipal().getName())) {
+ return Response.status(Response.Status.FORBIDDEN).build();
+ }
+ return Response.ok(userService.findById(id)).build();
+ }
+
+ private boolean isOwner(Long userId, String username) {
+ return userService.isOwner(userId, username);
+ }
+}
+```
+
+### Programmatic Security
+
+```java
+@ApplicationScoped
+public class SecurityService {
+
+ @Inject
+ SecurityIdentity securityIdentity;
+
+ public boolean canAccessResource(Long resourceId) {
+ if (securityIdentity.isAnonymous()) {
+ return false;
+ }
+
+ if (securityIdentity.hasRole("ADMIN")) {
+ return true;
+ }
+
+ String userId = securityIdentity.getPrincipal().getName();
+ return resourceRepository.isOwner(resourceId, userId);
+ }
+}
+```
+
+## Input Validation
+
+### Bean Validation
+
+```java
+// BAD: No validation
+@POST
+public Response createUser(UserDto dto) {
+ return Response.ok(userService.create(dto)).build();
+}
+
+// GOOD: Validated DTO
+public record CreateUserDto(
+ @NotBlank @Size(max = 100) String name,
+ @NotBlank @Email String email,
+ @NotNull @Min(18) @Max(150) Integer age,
+ @Pattern(regexp = "^\\+?[1-9]\\d{1,14}$") String phone
+) {}
+
+@POST
+@Path("/users")
+public Response createUser(@Valid CreateUserDto dto) {
+ User user = userService.create(dto);
+ return Response.status(Response.Status.CREATED).entity(user).build();
+}
+```
+
+### Custom Validators
+
+```java
+@Target({ElementType.FIELD, ElementType.PARAMETER})
+@Retention(RetentionPolicy.RUNTIME)
+@Constraint(validatedBy = UsernameValidator.class)
+public @interface ValidUsername {
+ String message() default "Invalid username format";
+ Class<?>[] groups() default {};
+ Class<? extends Payload>[] payload() default {};
+}
+
+public class UsernameValidator implements ConstraintValidator<ValidUsername, String> {
+ @Override
+ public boolean isValid(String value, ConstraintValidatorContext context) {
+ if (value == null) return false;
+ return value.matches("^[a-zA-Z0-9_-]{3,20}$");
+ }
+}
+
+// Usage
+public record CreateUserDto(
+ @ValidUsername String username,
+ @NotBlank @Email String email
+) {}
+```
+
+## SQL Injection Prevention
+
+### Panache Active Record (Safe by Default)
+
+```java
+// GOOD: Parameterized queries with Panache
+List<User> users = User.list("email = ?1 and active = ?2", email, true);
+
+Optional<User> user = User.find("username", username).firstResultOptional();
+
+// GOOD: Named parameters
+List<User> users = User.list("email = :email and age > :minAge",
+ Parameters.with("email", email).and("minAge", 18));
+```
+
+### Native Queries (Use Parameters)
+
+```java
+// BAD: String concatenation
+@Query(value = "SELECT * FROM users WHERE name = '" + name + "'", nativeQuery = true)
+
+// GOOD: Parameterized native query
+@Entity
+public class User extends PanacheEntity {
+ public static List<User> findByEmailNative(String email) {
+ return getEntityManager()
+ .createNativeQuery("SELECT * FROM users WHERE email = :email", User.class)
+ .setParameter("email", email)
+ .getResultList();
+ }
+}
+```
+
+## Password Hashing
+
+```java
+@ApplicationScoped
+public class PasswordService {
+
+ public String hash(String plainPassword) {
+ return BcryptUtil.bcryptHash(plainPassword);
+ }
+
+ public boolean verify(String plainPassword, String hashedPassword) {
+ return BcryptUtil.matches(plainPassword, hashedPassword);
+ }
+}
+
+// In service
+@ApplicationScoped
+public class UserService {
+ @Inject
+ PasswordService passwordService;
+
+ @Transactional
+ public User register(CreateUserDto dto) {
+ String hashedPassword = passwordService.hash(dto.password());
+ User user = new User();
+ user.email = dto.email();
+ user.password = hashedPassword;
+ user.persist();
+ return user;
+ }
+
+ public boolean authenticate(String email, String password) {
+ return User.find("email", email)
+ .firstResultOptional()
+ .map(u -> passwordService.verify(password, u.password))
+ .orElse(false);
+ }
+}
+```
+
+## CORS Configuration
+
+```properties
+# application.properties
+quarkus.http.cors=true
+quarkus.http.cors.origins=https://app.example.com,https://admin.example.com
+quarkus.http.cors.methods=GET,POST,PUT,DELETE
+quarkus.http.cors.headers=accept,authorization,content-type,x-requested-with
+quarkus.http.cors.exposed-headers=Content-Disposition
+quarkus.http.cors.access-control-max-age=24H
+quarkus.http.cors.access-control-allow-credentials=true
+```
+
+## Secrets Management
+
+```properties
+# application.properties - NO SECRETS HERE
+
+# Use environment variables
+quarkus.datasource.username=${DB_USER}
+quarkus.datasource.password=${DB_PASSWORD}
+quarkus.oidc.credentials.secret=${OIDC_CLIENT_SECRET}
+
+# Or use Vault
+quarkus.vault.url=https://vault.example.com
+quarkus.vault.authentication.kubernetes.role=my-role
+```
+
+### HashiCorp Vault Integration
+
+```java
+@ApplicationScoped
+public class SecretService {
+
+ @ConfigProperty(name = "api-key")
+ String apiKey; // Fetched from Vault
+
+ public String getSecret(String key) {
+ return ConfigProvider.getConfig().getValue(key, String.class);
+ }
+}
+```
+
+## Rate Limiting
+
+**Security Note**: Never use `X-Forwarded-For` directly — clients can spoof it.
+Use the actual remote address from the servlet request, or an authenticated
+identity (API key, JWT subject) when available.
+
+```java
+@ApplicationScoped
+public class RateLimitFilter implements ContainerRequestFilter {
+ private final Map<String, RateLimiter> limiters = new ConcurrentHashMap<>();
+
+ @Inject
+ HttpServletRequest servletRequest;
+
+ @Override
+ public void filter(ContainerRequestContext requestContext) {
+ String clientId = getClientIdentifier();
+ RateLimiter limiter = limiters.computeIfAbsent(clientId,
+ k -> RateLimiter.create(100.0)); // 100 requests per second
+
+ if (!limiter.tryAcquire()) {
+ requestContext.abortWith(
+ Response.status(429)
+ .entity(Map.of("error", "Too many requests"))
+ .build()
+ );
+ }
+ }
+
+ private String getClientIdentifier() {
+ // Use the container-provided remote address (not X-Forwarded-For).
+ // If behind a trusted proxy, configure quarkus.http.proxy.proxy-address-forwarding=true
+ // so getRemoteAddr() returns the real client IP.
+ return servletRequest.getRemoteAddr();
+ }
+}
+```
+
+## Security Headers
+
+```java
+@Provider
+public class SecurityHeadersFilter implements ContainerResponseFilter {
+
+ @Override
+ public void filter(ContainerRequestContext request, ContainerResponseContext response) {
+ MultivaluedMap<String, Object> headers = response.getHeaders();
+
+ // Prevent clickjacking
+ headers.putSingle("X-Frame-Options", "DENY");
+
+ // XSS protection
+ headers.putSingle("X-Content-Type-Options", "nosniff");
+ headers.putSingle("X-XSS-Protection", "1; mode=block");
+
+ // HSTS
+ headers.putSingle("Strict-Transport-Security", "max-age=31536000; includeSubDomains");
+
+ // CSP — avoid 'unsafe-inline' for script-src as it negates XSS protection;
+ // use nonces or hashes instead. 'unsafe-inline' for style-src is acceptable
+ // when CSS frameworks require it, but prefer nonces where possible.
+ headers.putSingle("Content-Security-Policy",
+ "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'");
+ }
+}
+```
+
+## Audit Logging
+
+```java
+@ApplicationScoped
+public class AuditService {
+ private static final Logger LOG = Logger.getLogger(AuditService.class);
+
+ @Inject
+ SecurityIdentity securityIdentity;
+
+ public void logAccess(String resource, String action) {
+ String user = securityIdentity.isAnonymous()
+ ? "anonymous"
+ : securityIdentity.getPrincipal().getName();
+
+ LOG.infof("AUDIT: user=%s action=%s resource=%s timestamp=%s",
+ user, action, resource, Instant.now());
+ }
+}
+
+// Usage in resource
+@Path("/api/sensitive")
+public class SensitiveResource {
+ @Inject
+ AuditService auditService;
+
+ @GET
+ @RolesAllowed("ADMIN")
+ public Response getData() {
+ auditService.logAccess("sensitive-data", "READ");
+ return Response.ok(data).build();
+ }
+}
+```
+
+## Dependency Security Scanning
+
+```bash
+# Maven
+mvn org.owasp:dependency-check-maven:check
+
+# Gradle
+./gradlew dependencyCheckAnalyze
+
+# Check Quarkus extensions
+quarkus extension list --installable
+```
+
+## Best Practices
+
+- Always use HTTPS in production
+- Enable JWT or OIDC for stateless authentication
+- Use `@RolesAllowed` for declarative authorization
+- Validate all input with Bean Validation
+- Hash passwords with BCrypt (never plaintext)
+- Store secrets in Vault or environment variables
+- Use parameterized queries to prevent SQL injection
+- Add security headers to all responses
+- Implement rate limiting for public endpoints
+- Audit sensitive operations
+- Keep dependencies updated and scan for CVEs
+- Use SecurityIdentity for programmatic checks
+- Set appropriate CORS policies
+- Test authentication and authorization paths
diff --git a/skills/quarkus-tdd/SKILL.md b/skills/quarkus-tdd/SKILL.md
new file mode 100644
index 000000000..beae1952a
--- /dev/null
+++ b/skills/quarkus-tdd/SKILL.md
@@ -0,0 +1,811 @@
+---
+name: quarkus-tdd
+description: Test-driven development for Quarkus 3.x LTS using JUnit 5, Mockito, REST Assured, Camel testing, and JaCoCo. Use when adding features, fixing bugs, or refactoring event-driven services.
+origin: ECC
+---
+
+# Quarkus TDD Workflow
+
+TDD guidance for Quarkus 3.x services with 80%+ coverage (unit + integration). Optimized for event-driven architectures with Apache Camel.
+
+## When to Use
+
+- New features or REST endpoints
+- Bug fixes or refactors
+- Adding data access logic, security rules, or reactive streams
+- Testing Apache Camel routes and event handlers
+- Testing event-driven services with RabbitMQ
+- Testing conditional flow logic
+- Validating CompletableFuture async operations
+- Testing LogContext propagation
+
+## Workflow
+
+1. Write tests first (they should fail)
+2. Implement minimal code to pass
+3. Refactor with tests green
+4. Enforce coverage with JaCoCo (80%+ target)
+
+## Unit Tests with @Nested Organization
+
+Follow this structured approach for comprehensive, readable tests:
+
+```java
+@ExtendWith(MockitoExtension.class)
+@DisplayName("OrderService Unit Tests")
+class OrderServiceTest {
+
+ @Mock
+ private OrderRepository orderRepository;
+
+ @Mock
+ private EventService eventService;
+
+ @Mock
+ private FulfillmentPublisher fulfillmentPublisher;
+
+ @InjectMocks
+ private OrderService orderService;
+
+ private CreateOrderCommand validCommand;
+
+ @BeforeEach
+ void setUp() {
+ validCommand = new CreateOrderCommand(
+ "customer-123",
+ List.of(new OrderLine("sku-123", 2))
+ );
+ }
+
+ @Nested
+ @DisplayName("Tests for createOrder")
+ class CreateOrder {
+
+ @Test
+ @DisplayName("Should persist order and publish fulfillment event")
+ void givenValidCommand_whenCreateOrder_thenPersistsAndPublishes() {
+ // ARRANGE
+ doNothing().when(orderRepository).persist(any(Order.class));
+
+ // ACT
+ OrderReceipt receipt = orderService.createOrder(validCommand);
+
+ // ASSERT
+ assertThat(receipt).isNotNull();
+ assertThat(receipt.customerId()).isEqualTo("customer-123");
+ verify(orderRepository).persist(any(Order.class));
+ verify(fulfillmentPublisher).publishAsync(receipt);
+ verify(eventService).createSuccessEvent(receipt, "ORDER_CREATED");
+ }
+
+ @Test
+ @DisplayName("Should reject missing customer id")
+ void givenMissingCustomerId_whenCreateOrder_thenThrowsBadRequest() {
+ // ARRANGE
+ CreateOrderCommand invalid = new CreateOrderCommand("", validCommand.lines());
+
+ // ACT & ASSERT
+ WebApplicationException exception = assertThrows(
+ WebApplicationException.class,
+ () -> orderService.createOrder(invalid)
+ );
+
+ assertThat(exception.getResponse().getStatus()).isEqualTo(400);
+ verify(orderRepository, never()).persist(any(Order.class));
+ verify(fulfillmentPublisher, never()).publishAsync(any());
+ }
+
+ @Test
+ @DisplayName("Should record error event when persistence fails")
+ void givenPersistenceFailure_whenCreateOrder_thenRecordsErrorEvent() {
+ // ARRANGE
+ doThrow(new PersistenceException("database unavailable"))
+ .when(orderRepository).persist(any(Order.class));
+
+ // ACT & ASSERT
+ PersistenceException exception = assertThrows(
+ PersistenceException.class,
+ () -> orderService.createOrder(validCommand)
+ );
+
+ assertThat(exception.getMessage()).contains("database unavailable");
+ verify(eventService).createErrorEvent(
+ eq(validCommand),
+ eq("ORDER_CREATE_FAILED"),
+ contains("database unavailable")
+ );
+ verify(fulfillmentPublisher, never()).publishAsync(any());
+ }
+
+ @Test
+ @DisplayName("Should reject null commands")
+ void givenNullCommand_whenCreateOrder_thenThrowsNullPointerException() {
+ // ACT & ASSERT
+ assertThrows(
+ NullPointerException.class,
+ () -> orderService.createOrder(null)
+ );
+
+ verify(orderRepository, never()).persist(any(Order.class));
+ }
+ }
+}
+```
+
+### Key Testing Patterns
+
+1. **@Nested Classes**: Group tests by method being tested
+2. **@DisplayName**: Provide readable test descriptions for test reports
+3. **Naming Convention**: `givenX_whenY_thenZ` for clarity
+4. **AAA Pattern**: Explicit `// ARRANGE`, `// ACT`, `// ASSERT` comments
+5. **@BeforeEach**: Setup common test data to reduce duplication
+6. **assertDoesNotThrow**: Test success scenarios without catching exceptions
+7. **assertThrows**: Test exception scenarios with message validation using AssertJ
+8. **Comprehensive Coverage**: Test happy paths, null inputs, edge cases, exceptions
+9. **Verify Interactions**: Use Mockito `verify()` to ensure methods are called correctly
+10. **Never Verify**: Use `never()` to ensure methods are NOT called in error scenarios
+
+## Testing Camel Routes
+
+```java
+@QuarkusTest
+@DisplayName("Business Rules Camel Route Tests")
+class BusinessRulesRouteTest {
+
+ @Inject
+ CamelContext camelContext;
+
+ @Inject
+ ProducerTemplate producerTemplate;
+
+ @InjectMock
+ EventService eventService;
+
+ @InjectMock
+ DocumentValidator documentValidator;
+
+ private BusinessRulesPayload testPayload;
+
+ @BeforeEach
+ void setUp() {
+ // ARRANGE - Test data
+ testPayload = new BusinessRulesPayload();
+ testPayload.setDocumentId(1L);
+ testPayload.setFlowProfile(FlowProfile.BASIC);
+ }
+
+ @Nested
+ @DisplayName("Tests for business-rules-publisher route")
+ class BusinessRulesPublisher {
+
+ @Test
+ @DisplayName("Should successfully publish message to RabbitMQ")
+ void givenValidPayload_whenPublish_thenMessageSentToQueue() throws Exception {
+ // ARRANGE
+ MockEndpoint mockRabbitMQ = camelContext.getEndpoint("mock:rabbitmq", MockEndpoint.class);
+ mockRabbitMQ.expectedMessageCount(1);
+
+ // Replace real endpoint with mock for testing
+ camelContext.getRouteController().stopRoute("business-rules-publisher");
+ AdviceWith.adviceWith(camelContext, "business-rules-publisher", advice -> {
+ advice.replaceFromWith("direct:business-rules-publisher");
+ advice.weaveByToString(".*spring-rabbitmq.*").replace().to("mock:rabbitmq");
+ });
+ camelContext.getRouteController().startRoute("business-rules-publisher");
+
+ // ACT
+ producerTemplate.sendBody("direct:business-rules-publisher", testPayload);
+
+ // ASSERT — body is a JSON String after .marshal().json(JsonLibrary.Jackson)
+ mockRabbitMQ.assertIsSatisfied(5000);
+
+ assertThat(mockRabbitMQ.getExchanges()).hasSize(1);
+ String body = mockRabbitMQ.getExchanges().get(0).getIn().getBody(String.class);
+ assertThat(body).contains("\"documentId\":1");
+ }
+
+ @Test
+ @DisplayName("Should handle marshalling to JSON")
+ void givenPayload_whenPublish_thenMarshalledToJson() throws Exception {
+ // ARRANGE
+ MockEndpoint mockMarshal = new MockEndpoint("mock:marshal");
+ camelContext.addEndpoint("mock:marshal", mockMarshal);
+ mockMarshal.expectedMessageCount(1);
+
+ camelContext.getRouteController().stopRoute("business-rules-publisher");
+ AdviceWith.adviceWith(camelContext, "business-rules-publisher", advice -> {
+ advice.weaveAddLast().to("mock:marshal");
+ });
+ camelContext.getRouteController().startRoute("business-rules-publisher");
+
+ // ACT
+ producerTemplate.sendBody("direct:business-rules-publisher", testPayload);
+
+ // ASSERT
+ mockMarshal.assertIsSatisfied(5000);
+
+ String body = mockMarshal.getExchanges().get(0).getIn().getBody(String.class);
+ assertThat(body).contains("\"documentId\":1");
+ assertThat(body).contains("\"flowProfile\":\"BASIC\"");
+ }
+ }
+
+ @Nested
+ @DisplayName("Tests for document-processing route")
+ class DocumentProcessing {
+
+ @Test
+ @DisplayName("Should route invoice to correct processor")
+ void givenInvoiceType_whenProcess_thenRoutesToInvoiceProcessor() throws Exception {
+ // ARRANGE
+ MockEndpoint mockInvoice = camelContext.getEndpoint("mock:invoice", MockEndpoint.class);
+ mockInvoice.expectedMessageCount(1);
+
+ camelContext.getRouteController().stopRoute("document-processing");
+ AdviceWith.adviceWith(camelContext, "document-processing", advice -> {
+ advice.weaveByToString(".*direct:process-invoice.*").replace().to("mock:invoice");
+ });
+ camelContext.getRouteController().startRoute("document-processing");
+
+ // ACT
+ producerTemplate.sendBodyAndHeader("direct:process-document",
+ testPayload, "documentType", "INVOICE");
+
+ // ASSERT
+ mockInvoice.assertIsSatisfied(5000);
+ }
+
+ @Test
+ @DisplayName("Should handle validation errors gracefully")
+ void givenValidationError_whenProcess_thenRoutesToErrorHandler() throws Exception {
+ // ARRANGE
+ MockEndpoint mockError = camelContext.getEndpoint("mock:error", MockEndpoint.class);
+ mockError.expectedMessageCount(1);
+
+ camelContext.getRouteController().stopRoute("document-processing");
+ AdviceWith.adviceWith(camelContext, "document-processing", advice -> {
+ advice.weaveByToString(".*direct:validation-error-handler.*")
+ .replace().to("mock:error");
+ });
+ camelContext.getRouteController().startRoute("document-processing");
+
+ // Mock validator bean to throw exception
+ when(documentValidator.validate(any())).thenThrow(new ValidationException("Invalid document"));
+
+ // ACT
+ producerTemplate.sendBody("direct:process-document", testPayload);
+
+ // ASSERT
+ mockError.assertIsSatisfied(5000);
+
+ Exception exception = mockError.getExchanges().get(0).getException();
+ assertThat(exception).isInstanceOf(ValidationException.class);
+ assertThat(exception.getMessage()).contains("Invalid document");
+ }
+ }
+}
+```
+
+## Testing Event Services
+
+```java
+@ExtendWith(MockitoExtension.class)
+@DisplayName("EventService Unit Tests")
+class EventServiceTest {
+
+ @Mock
+ private EventRepository eventRepository;
+
+ @Mock
+ private ObjectMapper objectMapper;
+
+ @InjectMocks
+ private EventService eventService;
+
+ private BusinessRulesPayload testPayload;
+
+ @BeforeEach
+ void setUp() {
+ // ARRANGE
+ testPayload = new BusinessRulesPayload();
+ testPayload.setDocumentId(1L);
+ }
+
+ @Nested
+ @DisplayName("Tests for createSuccessEvent")
+ class CreateSuccessEvent {
+
+ @Test
+ @DisplayName("Should create success event with correct attributes")
+ void givenValidPayload_whenCreateSuccessEvent_thenEventPersisted() throws Exception {
+ // ARRANGE
+ when(objectMapper.writeValueAsString(testPayload)).thenReturn("{\"documentId\":1}");
+
+ // ACT
+ assertDoesNotThrow(() ->
+ eventService.createSuccessEvent(testPayload, "DOCUMENT_PROCESSED"));
+
+ // ASSERT
+ verify(eventRepository).persist(argThat(event ->
+ event.getType().equals("DOCUMENT_PROCESSED") &&
+ event.getStatus() == EventStatus.SUCCESS &&
+ event.getPayload().equals("{\"documentId\":1}") &&
+ event.getTimestamp() != null
+ ));
+ }
+
+ @Test
+ @DisplayName("Should throw exception when payload is null")
+ void givenNullPayload_whenCreateSuccessEvent_thenThrowsException() {
+ // ARRANGE
+ Object nullPayload = null;
+
+ // ACT & ASSERT
+ NullPointerException exception = assertThrows(
+ NullPointerException.class,
+ () -> eventService.createSuccessEvent(nullPayload, "EVENT_TYPE")
+ );
+
+ assertThat(exception.getMessage()).isEqualTo("Payload cannot be null");
+ verify(eventRepository, never()).persist(any());
+ }
+ }
+
+ @Nested
+ @DisplayName("Tests for createErrorEvent")
+ class CreateErrorEvent {
+
+ @Test
+ @DisplayName("Should create error event with error message")
+ void givenError_whenCreateErrorEvent_thenEventPersistedWithMessage() throws Exception {
+ // ARRANGE
+ String errorMessage = "Processing failed";
+ when(objectMapper.writeValueAsString(testPayload)).thenReturn("{\"documentId\":1}");
+
+ // ACT
+ assertDoesNotThrow(() ->
+ eventService.createErrorEvent(testPayload, "PROCESSING_ERROR", errorMessage));
+
+ // ASSERT
+ verify(eventRepository).persist(argThat(event ->
+ event.getType().equals("PROCESSING_ERROR") &&
+ event.getStatus() == EventStatus.ERROR &&
+ event.getErrorMessage().equals(errorMessage) &&
+ event.getPayload().equals("{\"documentId\":1}")
+ ));
+ }
+
+ @ParameterizedTest
+ @DisplayName("Should reject invalid error messages")
+ @ValueSource(strings = {"", " "})
+ void givenBlankErrorMessage_whenCreateErrorEvent_thenThrowsException(String blankMessage) {
+ // ACT & ASSERT
+ IllegalArgumentException exception = assertThrows(
+ IllegalArgumentException.class,
+ () -> eventService.createErrorEvent(testPayload, "ERROR", blankMessage)
+ );
+
+ assertThat(exception.getMessage()).contains("Error message cannot be blank");
+ }
+ }
+}
+```
+
+## Testing CompletableFuture
+
+```java
+@ExtendWith(MockitoExtension.class)
+@DisplayName("FileStorageService Unit Tests")
+class FileStorageServiceTest {
+
+ @Mock
+ private S3Client s3Client;
+
+ @Mock
+ private ExecutorService executorService;
+
+ @InjectMocks
+ private FileStorageService fileStorageService;
+
+ private InputStream testInputStream;
+ private LogContext testLogContext;
+
+ @BeforeEach
+ void setUp() {
+ // ARRANGE
+ testInputStream = new ByteArrayInputStream("test content".getBytes());
+ testLogContext = new LogContext();
+ testLogContext.put("traceId", "trace-123");
+ }
+
+ @Nested
+ @DisplayName("Tests for uploadOriginalFile")
+ class UploadOriginalFile {
+
+ @Test
+ @DisplayName("Should successfully upload file and return document info")
+ void givenValidFile_whenUpload_thenReturnsDocumentInfo() throws Exception {
+ // ARRANGE
+ doAnswer(invocation -> {
+ ((Runnable) invocation.getArgument(0)).run();
+ return null;
+ }).when(executorService).execute(any(Runnable.class));
+
+ when(s3Client.putObject(any(PutObjectRequest.class), any(RequestBody.class)))
+ .thenReturn(PutObjectResponse.builder().build());
+
+ // ACT
+ CompletableFuture<StoredDocumentInfo> future =
+ fileStorageService.uploadOriginalFile(testInputStream, 1024L,
+ testLogContext, InvoiceFormat.UBL);
+
+ StoredDocumentInfo result = future.join();
+
+ // ASSERT
+ assertThat(result).isNotNull();
+ assertThat(result.getPath()).isNotBlank();
+ assertThat(result.getSize()).isEqualTo(1024L);
+ assertThat(result.getUploadedAt()).isNotNull();
+
+ verify(s3Client).putObject(any(PutObjectRequest.class), any(RequestBody.class));
+ }
+
+ @Test
+ @DisplayName("Should handle S3 upload failure")
+ void givenS3Failure_whenUpload_thenCompletableFutureFails() {
+ // ARRANGE — run synchronously so exception propagates through the future
+ doAnswer(invocation -> {
+ ((Runnable) invocation.getArgument(0)).run();
+ return null;
+ }).when(executorService).execute(any(Runnable.class));
+
+ when(s3Client.putObject(any(PutObjectRequest.class), any(RequestBody.class)))
+ .thenThrow(new StorageException("S3 unavailable"));
+
+ // ACT
+ CompletableFuture<StoredDocumentInfo> future =
+ fileStorageService.uploadOriginalFile(testInputStream, 1024L,
+ testLogContext, InvoiceFormat.UBL);
+
+ // ASSERT
+ assertThatThrownBy(() -> future.join())
+ .isInstanceOf(CompletionException.class)
+ .hasCauseInstanceOf(StorageException.class)
+ .hasMessageContaining("S3 unavailable");
+ }
+
+ @Test
+ @DisplayName("Should propagate LogContext to async operation")
+ void givenLogContext_whenUpload_thenContextPropagated() throws Exception {
+ // ARRANGE
+ AtomicReference<LogContext> capturedContext = new AtomicReference<>();
+
+ doAnswer(invocation -> {
+ capturedContext.set(CustomLog.getCurrentContext());
+ ((Runnable) invocation.getArgument(0)).run();
+ return null;
+ }).when(executorService).execute(any(Runnable.class));
+
+ // ACT
+ fileStorageService.uploadOriginalFile(testInputStream, 1024L,
+ testLogContext, InvoiceFormat.UBL).join();
+
+ // ASSERT
+ assertThat(capturedContext.get()).isNotNull();
+ assertThat(capturedContext.get().get("traceId")).isEqualTo("trace-123");
+ }
+ }
+}
+```
+
+## Resource Layer Tests (REST Assured)
+
+```java
+@QuarkusTest
+@DisplayName("DocumentResource API Tests")
+class DocumentResourceTest {
+
+ @InjectMock
+ DocumentService documentService;
+
+ @Nested
+ @DisplayName("Tests for GET /api/documents")
+ class ListDocuments {
+
+ @Test
+ @DisplayName("Should return list of documents")
+ void givenDocumentsExist_whenList_thenReturnsOk() {
+ // ARRANGE
+ List<Document> documents = List.of(createDocument(1L, "DOC-001"));
+ when(documentService.list(0, 20)).thenReturn(documents);
+
+ // ACT & ASSERT
+ given()
+ .when().get("/api/documents")
+ .then()
+ .statusCode(200)
+ .body("$.size()", is(1))
+ .body("[0].referenceNumber", equalTo("DOC-001"));
+ }
+ }
+
+ @Nested
+ @DisplayName("Tests for POST /api/documents")
+ class CreateDocument {
+
+ @Test
+ @DisplayName("Should create document and return 201")
+ void givenValidRequest_whenCreate_thenReturns201() {
+ // ARRANGE
+ Document document = createDocument(1L, "DOC-001");
+ when(documentService.create(any())).thenReturn(document);
+
+ // ACT & ASSERT
+ given()
+ .contentType(ContentType.JSON)
+ .body("""
+ {
+ "referenceNumber": "DOC-001",
+ "description": "Test document",
+ "validUntil": "2030-01-01T00:00:00Z",
+ "categories": ["test"]
+ }
+ """)
+ .when().post("/api/documents")
+ .then()
+ .statusCode(201)
+ .header("Location", containsString("/api/documents/1"))
+ .body("referenceNumber", equalTo("DOC-001"));
+ }
+
+ @Test
+ @DisplayName("Should return 400 for invalid input")
+ void givenInvalidRequest_whenCreate_thenReturns400() {
+ // ACT & ASSERT
+ given()
+ .contentType(ContentType.JSON)
+ .body("""
+ {
+ "referenceNumber": "",
+ "description": "Test"
+ }
+ """)
+ .when().post("/api/documents")
+ .then()
+ .statusCode(400);
+ }
+ }
+
+ private Document createDocument(Long id, String referenceNumber) {
+ Document document = new Document();
+ document.setId(id);
+ document.setReferenceNumber(referenceNumber);
+ document.setStatus(DocumentStatus.PENDING);
+ return document;
+ }
+}
+```
+
+## Integration Tests with Real Database
+
+```java
+@QuarkusTest
+@TestProfile(IntegrationTestProfile.class)
+@DisplayName("Document Integration Tests")
+class DocumentIntegrationTest {
+
+ @Test
+ @Transactional
+ @DisplayName("Should create and retrieve document via API")
+ void givenNewDocument_whenCreateAndRetrieve_thenSuccessful() {
+ // ACT - Create via API
+ Long id = given()
+ .contentType(ContentType.JSON)
+ .body("""
+ {
+ "referenceNumber": "INT-001",
+ "description": "Integration test",
+ "validUntil": "2030-01-01T00:00:00Z",
+ "categories": ["test"]
+ }
+ """)
+ .when().post("/api/documents")
+ .then()
+ .statusCode(201)
+ .extract().path("id");
+
+ // ASSERT - Retrieve via API
+ given()
+ .when().get("/api/documents/" + id)
+ .then()
+ .statusCode(200)
+ .body("referenceNumber", equalTo("INT-001"));
+ }
+}
+```
+
+## Coverage with JaCoCo
+
+### Maven Configuration (Complete)
+
+```xml
+<plugin>
+ <groupId>org.jacoco</groupId>
+ <artifactId>jacoco-maven-plugin</artifactId>
+ <version>0.8.13</version>
+ <executions>
+ <!-- Prepare agent for test execution -->
+ <execution>
+ <id>prepare-agent</id>
+ <goals>
+ <goal>prepare-agent</goal>
+ </goals>
+ </execution>
+
+ <!-- Generate coverage report -->
+ <execution>
+ <id>report</id>
+ <phase>verify</phase>
+ <goals>
+ <goal>report</goal>
+ </goals>
+ </execution>
+
+ <!-- Enforce coverage thresholds -->
+ <execution>
+ <id>check</id>
+ <goals>
+ <goal>check</goal>
+ </goals>
+ <configuration>
+ <rules>
+ <rule>
+ <element>BUNDLE</element>
+ <limits>
+ <limit>
+ <counter>LINE</counter>
+ <value>COVEREDRATIO</value>
+ <minimum>0.80</minimum>
+ </limit>
+ <limit>
+ <counter>BRANCH</counter>
+ <value>COVEREDRATIO</value>
+ <minimum>0.70</minimum>
+ </limit>
+ </limits>
+ </rule>
+ </rules>
+ </configuration>
+ </execution>
+ </executions>
+</plugin>
+```
+
+Run tests with coverage:
+```bash
+mvn clean test
+mvn jacoco:report
+mvn jacoco:check
+
+# Report at: target/site/jacoco/index.html
+```
+
+## Test Dependencies
+
+```xml
+<dependencies>
+ <!-- Quarkus Testing -->
+ <dependency>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-junit5</artifactId>
+ <scope>test</scope>
+ </dependency>
+ <dependency>
+ <groupId>io.quarkus</groupId>
+ <artifactId>quarkus-junit5-mockito</artifactId>
+ <scope>test</scope>
+ </dependency>
+
+ <!-- Mockito -->
+ <dependency>
+ <groupId>org.mockito</groupId>
+ <artifactId>mockito-core</artifactId>
+ <scope>test</scope>
+ </dependency>
+
+ <!-- AssertJ (preferred over JUnit assertions) -->
+ <dependency>
+ <groupId>org.assertj</groupId>
+ <artifactId>assertj-core</artifactId>
+ <version>3.24.2</version>
+ <scope>test</scope>
+ </dependency>
+
+ <!-- REST Assured -->
+ <dependency>
+ <groupId>io.rest-assured</groupId>
+ <artifactId>rest-assured</artifactId>
+ <scope>test</scope>
+ </dependency>
+
+ <!-- Camel Testing -->
+ <dependency>
+ <groupId>org.apache.camel.quarkus</groupId>
+ <artifactId>camel-quarkus-junit5</artifactId>
+ <scope>test</scope>
+ </dependency>
+</dependencies>
+```
+
+## Best Practices
+
+### Test Organization
+- Use `@Nested` classes to group tests by method being tested
+- Use `@DisplayName` for readable test descriptions visible in reports
+- Follow `givenX_whenY_thenZ` naming convention for test methods
+- Use `@BeforeEach` for common test data setup to reduce duplication
+
+### Test Structure
+- Follow AAA pattern with explicit comments (`// ARRANGE`, `// ACT`, `// ASSERT`)
+- Use `assertDoesNotThrow` for success scenarios
+- Use `assertThrows` for exception scenarios with message validation
+- Verify exception messages match expected values using AssertJ `contains()` or `isEqualTo()`
+
+### Test Coverage
+- Test happy paths for all public methods
+- Test null input handling
+- Test edge cases (empty collections, boundary values, negative IDs, blank strings)
+- Test exception scenarios comprehensively
+- Mock all external dependencies (repositories, services, Camel endpoints)
+- Aim for 80%+ line coverage, 70%+ branch coverage
+
+### Assertions
+- **Prefer AssertJ** (`assertThat`) over JUnit assertions for value checks
+- Use fluent AssertJ API for readability: `assertThat(list).hasSize(3).contains(item)`
+- For exceptions: use JUnit `assertThrows` to capture, then AssertJ to validate the message
+- For non-throwing success paths: use JUnit `assertDoesNotThrow`
+- For collections: `extracting()`, `filteredOn()`, `containsExactly()`
+
+### Testing Integration
+- Use `@QuarkusTest` for integration tests
+- Use `@InjectMock` to mock dependencies in Quarkus tests
+- Prefer REST Assured for API testing
+- Use `@TestProfile` for test-specific configuration
+
+### Event-Driven Testing
+- Test Camel routes with `AdviceWith` and `MockEndpoint`
+- Use `@CamelQuarkusTest` annotation (if using standalone Camel tests)
+- Verify message content, headers, and routing logic
+- Test error handling routes separately
+- Mock external systems (RabbitMQ, S3, databases) in unit tests
+
+### Camel Route Testing
+- Use `MockEndpoint` for asserting message flow
+- Use `AdviceWith` to modify routes for testing (replace endpoints with mocks)
+- Test message transformation and marshalling
+- Test exception handling and dead letter queues
+
+### Testing Async Operations
+- Test CompletableFuture success and failure scenarios
+- Use `.join()` in tests to wait for async completion
+- Test exception propagation from CompletableFuture
+- Verify LogContext propagation to async operations
+
+### Performance
+- Keep tests fast and isolated
+- Run tests in continuous mode: `mvn quarkus:test`
+- Use parameterized tests (`@ParameterizedTest`) for input variations
+- Build reusable test data builders or factory methods
+
+### Quarkus-Specific
+- Stay on latest LTS version (Quarkus 3.x)
+- Test native compilation compatibility periodically
+- Use Quarkus test profiles for different scenarios
+- Leverage Quarkus dev services for local testing
+- Use `@InjectMock` instead of `@MockBean` (Quarkus-specific)
+
+### Verification Best Practices
+- Always verify interactions on mocked dependencies
+- Use `verify(mock, never())` to ensure methods are NOT called in error scenarios
+- Use `argThat()` for complex argument matching
+- Verify the order of calls when it matters: `InOrder` from Mockito
diff --git a/skills/quarkus-verification/SKILL.md b/skills/quarkus-verification/SKILL.md
new file mode 100644
index 000000000..54748e99a
--- /dev/null
+++ b/skills/quarkus-verification/SKILL.md
@@ -0,0 +1,479 @@
+---
+name: quarkus-verification
+description: "Verification loop for Quarkus projects: build, static analysis, tests with coverage, security scans, native compilation, and diff review before release or PR."
+origin: ECC
+---
+
+# Quarkus Verification Loop
+
+Run before PRs, after major changes, and pre-deploy.
+
+## When to Activate
+
+- Before opening a pull request for a Quarkus service
+- After major refactoring or dependency upgrades
+- Pre-deployment verification for staging or production
+- Running full build → lint → test → security scan → native compilation pipeline
+- Validating test coverage meets thresholds (80%+)
+- Testing native image compatibility
+
+## Phase 1: Build
+
+```bash
+# Maven
+mvn clean verify -DskipTests
+
+# Gradle
+./gradlew clean assemble -x test
+```
+
+If build fails, stop and fix compilation errors.
+
+## Phase 2: Static Analysis
+
+### Checkstyle, PMD, SpotBugs (Maven)
+
+```bash
+mvn checkstyle:check pmd:check spotbugs:check
+```
+
+### SonarQube (if configured)
+
+```bash
+mvn sonar:sonar \
+ -Dsonar.projectKey=my-quarkus-project \
+ -Dsonar.host.url=http://localhost:9000 \
+ -Dsonar.login=${SONAR_TOKEN}
+```
+
+### Common Issues to Address
+
+- Unused imports or variables
+- Complex methods (high cyclomatic complexity)
+- Potential null pointer dereferences
+- Security issues flagged by SpotBugs
+
+## Phase 3: Tests + Coverage
+
+```bash
+# Run all tests
+mvn clean test
+
+# Generate coverage report
+mvn jacoco:report
+
+# Enforce coverage threshold (80%)
+mvn jacoco:check
+
+# Or with Gradle
+./gradlew test jacocoTestReport jacocoTestCoverageVerification
+```
+
+### Test Categories
+
+#### Unit Tests
+Test service logic with mocked dependencies:
+
+```java
+@ExtendWith(MockitoExtension.class)
+class UserServiceTest {
+ @Mock UserRepository userRepository;
+ @InjectMocks UserService userService;
+
+ @Test
+ void createUser_validInput_returnsUser() {
+ var dto = new CreateUserDto("Alice", "[email protected]");
+
+ // Panache persist() is void — use doNothing + verify
+ doNothing().when(userRepository).persist(any(User.class));
+
+ User result = userService.create(dto);
+
+ assertThat(result.name).isEqualTo("Alice");
+ verify(userRepository).persist(any(User.class));
+ }
+}
+```
+
+#### Integration Tests
+Test with real database (Testcontainers):
+
+```java
+@QuarkusTest
+@QuarkusTestResource(PostgresTestResource.class)
+class UserRepositoryIntegrationTest {
+
+ @Inject
+ UserRepository userRepository;
+
+ @Test
+ @Transactional
+ void findByEmail_existingUser_returnsUser() {
+ User user = new User();
+ user.name = "Alice";
+ user.email = "[email protected]";
+ userRepository.persist(user);
+
+ Optional<User> found = userRepository.findByEmail("[email protected]");
+
+ assertThat(found).isPresent();
+ assertThat(found.get().name).isEqualTo("Alice");
+ }
+}
+```
+
+#### API Tests
+Test REST endpoints with REST Assured:
+
+```java
+@QuarkusTest
+class UserResourceTest {
+
+ @Test
+ void createUser_validInput_returns201() {
+ given()
+ .contentType(ContentType.JSON)
+ .body("""
+ {"name": "Alice", "email": "[email protected]"}
+ """)
+ .when().post("/api/users")
+ .then()
+ .statusCode(201)
+ .body("name", equalTo("Alice"));
+ }
+
+ @Test
+ void createUser_invalidEmail_returns400() {
+ given()
+ .contentType(ContentType.JSON)
+ .body("""
+ {"name": "Alice", "email": "invalid"}
+ """)
+ .when().post("/api/users")
+ .then()
+ .statusCode(400);
+ }
+}
+```
+
+### Coverage Report
+
+Check `target/site/jacoco/index.html` for detailed coverage:
+- Overall line coverage (target: 80%+)
+- Branch coverage (target: 70%+)
+- Identify uncovered critical paths
+
+## Phase 4: Security Scanning
+
+### Dependency Vulnerabilities (Maven)
+
+```bash
+mvn org.owasp:dependency-check-maven:check
+```
+
+Review `target/dependency-check-report.html` for CVEs.
+
+### Quarkus Security Audit
+
+```bash
+# Check vulnerable extensions
+mvn quarkus:audit
+
+# List all extensions
+mvn quarkus:list-extensions
+```
+
+### OWASP ZAP (API Security Testing)
+
+```bash
+docker run -t owasp/zap2docker-stable zap-api-scan.py \
+ -t http://localhost:8080/q/openapi \
+ -f openapi
+```
+
+### Common Security Checks
+
+- [ ] All secrets in environment variables (not in code)
+- [ ] Input validation on all endpoints
+- [ ] Authentication/authorization configured
+- [ ] CORS properly configured
+- [ ] Security headers set
+- [ ] Passwords hashed with BCrypt
+- [ ] SQL injection protection (parameterized queries)
+- [ ] Rate limiting on public endpoints
+
+## Phase 5: Native Compilation
+
+Test GraalVM native image compatibility:
+
+```bash
+# Build native executable
+mvn package -Dnative
+
+# Or with container
+mvn package -Dnative -Dquarkus.native.container-build=true
+
+# Test native executable
+./target/*-runner
+
+# Run basic smoke tests
+curl http://localhost:8080/q/health/live
+curl http://localhost:8080/q/health/ready
+```
+
+### Native Image Troubleshooting
+
+Common issues:
+- **Reflection**: Add reflection config for dynamic classes
+- **Resources**: Include resources with `quarkus.native.resources.includes`
+- **JNI**: Register JNI classes if using native libraries
+
+Example reflection config:
+```java
+@RegisterForReflection(targets = {MyDynamicClass.class})
+public class ReflectionConfiguration {}
+```
+
+## Phase 6: Performance Testing
+
+### Load Testing with K6
+
+```javascript
+// load-test.js
+import http from 'k6/http';
+import { check } from 'k6';
+
+export const options = {
+ stages: [
+ { duration: '30s', target: 50 },
+ { duration: '1m', target: 100 },
+ { duration: '30s', target: 0 },
+ ],
+};
+
+export default function () {
+ const res = http.get('http://localhost:8080/api/markets');
+ check(res, {
+ 'status is 200': (r) => r.status === 200,
+ 'response time < 200ms': (r) => r.timings.duration < 200,
+ });
+}
+```
+
+Run:
+```bash
+k6 run load-test.js
+```
+
+### Metrics to Monitor
+
+- Response time (p50, p95, p99)
+- Throughput (requests/sec)
+- Error rate
+- Memory usage
+- CPU usage
+
+## Phase 7: Health Checks
+
+```bash
+# Liveness
+curl http://localhost:8080/q/health/live
+
+# Readiness
+curl http://localhost:8080/q/health/ready
+
+# All health checks
+curl http://localhost:8080/q/health
+
+# Metrics (if enabled)
+curl http://localhost:8080/q/metrics
+```
+
+Expected responses:
+```json
+{
+ "status": "UP",
+ "checks": [
+ {
+ "name": "Database connection",
+ "status": "UP"
+ }
+ ]
+}
+```
+
+## Phase 8: Container Image Build
+
+```bash
+# Build container image
+mvn package -Dquarkus.container-image.build=true
+
+# Or with specific registry
+mvn package \
+ -Dquarkus.container-image.build=true \
+ -Dquarkus.container-image.registry=docker.io \
+ -Dquarkus.container-image.group=myorg \
+ -Dquarkus.container-image.tag=1.0.0
+
+# Test container
+docker run -p 8080:8080 myorg/my-quarkus-app:1.0.0
+```
+
+### Container Security Scan
+
+```bash
+# Trivy
+trivy image myorg/my-quarkus-app:1.0.0
+
+# Grype
+grype myorg/my-quarkus-app:1.0.0
+```
+
+## Phase 9: Configuration Validation
+
+```bash
+# Check all configuration properties
+mvn quarkus:info
+
+# List all config sources
+curl http://localhost:8080/q/dev/io.quarkus.quarkus-vertx-http/config
+```
+
+### Environment-Specific Checks
+
+- [ ] Database URLs configured per environment
+- [ ] Secrets externalized (Vault, env vars)
+- [ ] Logging levels appropriate
+- [ ] CORS origins set correctly
+- [ ] Rate limiting configured
+- [ ] Monitoring/tracing enabled
+
+## Phase 10: Documentation Review
+
+- [ ] OpenAPI/Swagger docs up to date (`/q/swagger-ui`)
+- [ ] README has setup instructions
+- [ ] API changes documented
+- [ ] Migration guide for breaking changes
+- [ ] Configuration properties documented
+
+Generate OpenAPI spec:
+```bash
+curl http://localhost:8080/q/openapi -o openapi.json
+```
+
+## Verification Checklist
+
+### Code Quality
+- [ ] Build passes without warnings
+- [ ] Static analysis clean (no high/medium issues)
+- [ ] Code follows team conventions
+- [ ] No commented-out code or TODOs in PR
+
+### Testing
+- [ ] All tests pass
+- [ ] Code coverage ≥ 80%
+- [ ] Integration tests with real database
+- [ ] Security tests pass
+- [ ] Performance within acceptable limits
+
+### Security
+- [ ] No dependency vulnerabilities
+- [ ] Authentication/authorization tested
+- [ ] Input validation complete
+- [ ] Secrets not in source code
+- [ ] Security headers configured
+
+### Deployment
+- [ ] Native compilation successful
+- [ ] Container image builds
+- [ ] Health checks respond correctly
+- [ ] Configuration valid for target environment
+
+### Native Image
+- [ ] Native executable builds
+- [ ] Native tests pass
+- [ ] Startup time < 100ms
+- [ ] Memory footprint acceptable
+
+## Automated Verification Script
+
+```bash
+#!/bin/bash
+set -e
+
+echo "=== Phase 1: Build ==="
+mvn clean verify -DskipTests
+
+echo "=== Phase 2: Static Analysis ==="
+mvn checkstyle:check pmd:check spotbugs:check
+
+echo "=== Phase 3: Tests + Coverage ==="
+mvn test jacoco:report jacoco:check
+
+echo "=== Phase 4: Security Scan ==="
+mvn org.owasp:dependency-check-maven:check
+
+echo "=== Phase 5: Native Compilation ==="
+mvn package -Dnative -Dquarkus.native.container-build=true
+
+echo "=== All Phases Complete ==="
+echo "Review reports:"
+echo " - Coverage: target/site/jacoco/index.html"
+echo " - Security: target/dependency-check-report.html"
+echo " - Native: target/*-runner"
+```
+
+## CI/CD Integration
+
+### GitHub Actions Example
+
+```yaml
+name: Verification
+
+on: [push, pull_request]
+
+jobs:
+ verify:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v3
+
+ - name: Set up JDK 21
+ uses: actions/setup-java@v3
+ with:
+ java-version: '21'
+ distribution: 'temurin'
+
+ - name: Cache Maven packages
+ uses: actions/cache@v3
+ with:
+ path: ~/.m2
+ key: ${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }}
+
+ - name: Build
+ run: mvn clean verify -DskipTests
+
+ - name: Test with Coverage
+ run: mvn test jacoco:report jacoco:check
+
+ - name: Security Scan
+ run: mvn org.owasp:dependency-check-maven:check
+
+ - name: Upload Coverage
+ uses: codecov/codecov-action@v3
+ with:
+ files: target/site/jacoco/jacoco.xml
+```
+
+## Best Practices
+
+- Run verification loop before every PR
+- Automate in CI/CD pipeline
+- Fix issues immediately; don't accumulate debt
+- Keep coverage above 80%
+- Update dependencies regularly
+- Test native compilation periodically
+- Monitor performance trends
+- Document breaking changes
+- Review security scan results
+- Validate configuration for each environment