ben-eddy74/agent-skills

Quarkus BCE Backend Workflow

Scope & Directory Boundary

• STRICT BOUNDARY: Operate ONLY inside backend/. Never touch frontend/ files.
• Architecture: Strict Adam Bien BCE pattern (com.app.<domain>.{boundary, control, entity}).
• Tech Stack: Quarkus, Jakarta EE (jakarta.* ONLY—never javax.* or org.springframework.*).

2-Phase Execution Gate

Phase 1: Contract & Spine (STOP FOR HUMAN REVIEW)

1. entity: Create/update immutable Java record payloads (with @NotNull, @NotBlank, @Schema) and JPA/Panache entities inside ..<domain>.entity. Zero dependencies on control or boundary.
2. boundary: Create/update JAX-RS @Path resource signatures (@Transactional, @RolesAllowed, @Operation) inside ..<domain>.boundary.
3. Tests: Create/update failing JUnit @QuarkusTest or unit test stubs in backend/src/test/java/..<domain>/boundary/.
4. PAUSE: Show the diff of entity, boundary, and tests to the user. Wait for approval before writing control implementation.

Phase 2: Implementation & Schema Export

1. control: Implement business logic inside ..<domain>.control (@ApplicationScoped). Never call another domain's control directly; always go through its boundary.
2. Verify & Export Contract: Run inside backend/:

   ./mvnw test
   

Java 25 LTS Language & JVM Rules (Mandatory)

Target Java 25 LTS exclusively (<maven.compiler.release>25</maven.compiler.release>). Never write legacy Java 8/11/17 boilerplate:

1. Exhaustive Switch & Record Deconstruction (control & entity):
   • Model domain outcomes and state machines using sealed interface + record implementations in entity.
   • In control, process them using exhaustive switch expressions with record pattern deconstruction and guarded when clauses (e.g., case PaidOrder(var id, var total) when total > 1000 -> ...).
   • NEVER include a default branch on a sealed interface switch so the Java 25 compiler enforces exhaustiveness when new states are added.
2. Flexible Constructor Bodies (JEP 513):
   • Perform fail-fast validation and data normalization directly inside constructors before calling super(...) or this(...) rather than creating bloated static helper methods.
3. Unnamed Variables (_):
   • Always use _ for unused lambda parameters, ignored exception variables, or unused deconstructed record components (e.g., case Order(var id, _, _)).
4. Virtual Threads & Scoped Values (JEP 506):
   • For blocking I/O endpoints in Quarkus boundary, prefer @RunOnVirtualThread over reactive Uni<T> chains unless streaming is required.
   • Never use ThreadLocal; always use Java 25 ScopedValue<T> if contextual state must be passed within a thread scope.
5. Modern Collections & Stream Gatherers (JEP 485):
   • Use SequencedCollection methods (.getFirst(), .getLast(), .reversed()) instead of index math list.get(list.size() - 1).
   • Use Stream.gather(Gatherers.windowFixed(...)) instead of manual chunking loops.
6. No Preview Flags Unless Requested:
   • Stick to finalized Java 25 LTS features (do not enable --enable-preview for JEP 507 primitive patterns or JEP 505 structured concurrency unless explicitly asked).