bmad-method-quarkus 1.0.0

package/src/bmm-skills/agents/bmad-quarkus-architect/skills/quarkus-observability-otel/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: quarkus-observability-otel
+description: Observability standard for Quarkus native services using OpenTelemetry — distributed tracing with W3C Trace Context (traceparent), trace_id/span_id in every log line (JSON logs + MDC), OTLP export, metrics with Micrometer, custom spans, and trace propagation across REST, gRPC, and Kafka. Use this skill whenever the user mentions OpenTelemetry, OTel, tracing, trace_id, span_id, traceparent, distributed tracing, logging standard, log correlation, metrics, Grafana/Tempo/Jaeger/Prometheus, or debugging requests across services. Includes span, metric, logger and audit-adapter naming conventions.
+---
+
+# OpenTelemetry Observability Standard (Quarkus)
+
+Every request must be traceable end-to-end: REST → use case → JDBC → outbox → Kafka → consumer → gRPC. `trace_id`/`span_id` appear in every log line and propagate across every transport via W3C Trace Context. Applies to any Quarkus backend project; project directives (CLAUDE.md, ADRs, explicit instructions) override these defaults.
+
+Extensions: `quarkus-opentelemetry` (+ `quarkus-micrometer-registry-prometheus` or Micrometer→OTLP for metrics, `quarkus-logging-json` for structured logs). All native-compatible.
+
+## Baseline configuration
+
+```properties
+quarkus.application.name=bc05-users            # becomes service.name
+quarkus.otel.exporter.otlp.endpoint=http://otel-collector:4317
+quarkus.otel.resource.attributes=deployment.environment=${ENV:dev},service.namespace=alva
+
+# W3C Trace Context + Baggage are the DEFAULT propagators — do not override with B3 unless mandated
+# quarkus.otel.propagators=tracecontext,baggage
+
+# Sampling: head-based ratio in prod, always_on elsewhere
+%prod.quarkus.otel.traces.sampler=parentbased_traceidratio
+%prod.quarkus.otel.traces.sampler.arg=0.10
+
+# Don't trace health/metrics noise
+quarkus.otel.traces.suppress-non-application-uris=true
+```
+
+Export to an **OTel Collector** (agent/sidecar/gateway), never directly to the vendor backend — keeps services vendor-neutral.
+
+## Logs: trace_id and span_id in every line
+
+Quarkus OTel injects `traceId`, `spanId`, `sampled` into the MDC automatically.
+
+Console (dev, human-readable):
+
+```properties
+%dev.quarkus.log.console.format=%d{HH:mm:ss} %-5p traceId=%X{traceId} spanId=%X{spanId} [%c{2.}] %s%e%n
+```
+
+Prod: JSON logs (parseable, ship to the log pipeline):
+
+```properties
+%prod.quarkus.log.console.json=true
+%prod.quarkus.log.console.json.additional-field."service.name".value=${quarkus.application.name}
+```
+
+`quarkus-logging-json` includes MDC (traceId/spanId) as fields — logs↔traces correlation in Grafana/Tempo/Loki works with zero code. Rule: NEVER log a business operation without going through JBoss Logging/`Log` — `System.out` breaks correlation.
+
+Also return the trace id to API callers for support tickets: a tiny response filter adds header `X-Trace-Id: ${Span.current().getSpanContext().getTraceId()}` on every response (especially errors — pairs with the unified exception handler).
+
+## Automatic instrumentation (free)
+
+With the extension present, these produce/propagate spans with no code:
+- HTTP server (Quarkus REST) and REST Client
+- gRPC server & client (metadata `traceparent`)
+- Kafka via SmallRye Reactive Messaging (header `traceparent`)
+- Agroal/JDBC: add `quarkus-opentelemetry-jdbc` wrapper (`quarkus.datasource.jdbc.telemetry=true`) for SQL spans
+
+## Mandatory: trace context extraction via the OTel SDK only
+
+It is **strictly prohibited** to build or parse trace strings by hand (no manual `00-...-...-01` concatenation, no UUID-based fake trace ids). The ONLY sanctioned way to obtain the active trace is the SDK injected by `quarkus-opentelemetry`:
+
+```java
+String traceId = Span.current().getSpanContext().getTraceId();
+String spanId  = Span.current().getSpanContext().getSpanId();
+```
+
+If `Span.current()` is invalid (no active trace — e.g., a batch job without instrumentation), fix the instrumentation of the entry point; do not fabricate ids.
+
+## Audit standard: `context` jsonb column in `audit_event`
+
+Every service with a local `audit_event` table persists the active trace in a `context` column of type `jsonb`:
+
+```sql
+ALTER TABLE audit_event ADD COLUMN IF NOT EXISTS context jsonb;
+CREATE INDEX IF NOT EXISTS idx_audit_event_trace_id
+ON audit_event ((context->>'trace_id'));
+```
+
+Stored value (snake_case keys, exactly these):
+
+```json
+{ "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736", "span_id": "00f067aa0ba902b7" }
+```
+
+Reference implementation. The application layer depends on an outbound port `AuditRecorder` (`application/port/out`); capturing the active span is an infrastructure concern, so it happens in the adapter:
+
+```java
+// application/port/out — capability noun, no technology in the name
+public interface AuditRecorder {
+    void record(String action, String entity, String entityId);
+}
+
+// infrastructure/persistence — Jdbc<Port>
+@ApplicationScoped
+public class JdbcAuditRecorder implements AuditRecorder {
+
+    private final AuditEventRepository repository;
+
+    public JdbcAuditRecorder(AuditEventRepository repository) { this.repository = repository; }
+
+    @Override
+    public void record(String action, String entity, String entityId) {
+        String traceId = Span.current().getSpanContext().getTraceId();
+        String spanId  = Span.current().getSpanContext().getSpanId();
+        JsonObject context = new JsonObject()
+            .put("trace_id", traceId)
+            .put("span_id", spanId);
+        repository.save(action, entity, entityId, context.encode());
+    }
+}
+```
+
+Identifiers are English (`record`, `action`, `entity`), even when the business vocabulary and the UI are Spanish — Spanish belongs in the i18n bundles, not in class and method names. `*Service` is not used here: this is an outbound adapter, not a use case.
+
+Any code path that writes `audit_event` without populating `context` is non-compliant — flag it in review.
+
+## Trace context through the outbox (async gap)
+
+The automatic Kafka instrumentation covers direct emits. The outbox breaks the chain — the standard requires the trace in TWO places (see quarkus-kafka-messaging skill):
+
+1. **Kafka header** `traceparent` (W3C format `00-<trace_id>-<span_id>-01`) for technical propagation — captured at outbox insert, forwarded by the relay (Debezium SMT or poller). Consumer side: SmallRye extracts it automatically → consumer spans join the original trace.
+2. **Inside the outbox `payload` jsonb**, a `traceContext` block for audit/immutability:
+
+```json
+"traceContext": { "trace_id": "...", "span_id": "..." }
+```
+
+Both values come from `Span.current()` at insert time — never from manual strings.
+
+## Custom spans and attributes
+
+Annotate use cases that matter for diagnosis (not every method):
+
+```java
+// application/usecase — RegisterUserService implements RegisterUserUseCase
+@WithSpan("usecase.registerUser")
+public UserId register(@SpanAttribute("user.email.domain") String emailDomain, RegisterUserCommand cmd) { ... }
+```
+
+- Span names: `usecase.<verb><Entity>` (lowerCamelCase, matching the use-case method), `outbox.publish`, `job.<name>`.
+- Attributes: business-relevant, LOW-cardinality, NEVER PII (no emails, MSISDNs, tokens — use derived/hashed values).
+- Manual spans (`Tracer.spanBuilder`) only for background work not covered by annotations; always `try/finally` end the span and restore scope.
+
+### Naming for telemetry artifacts
+
+Canonical class-naming rules live in the quarkus-hexagonal-core skill; these are the observability-specific ones:
+
+| Artifact | Convention | Example |
+|---|---|---|
+| Audit port / adapter | `AuditRecorder` / `Jdbc<Port>` | `AuditRecorder`, `JdbcAuditRecorder` |
+| Trace-id response filter | `<Purpose>Filter` | `TraceIdResponseFilter` |
+| Span name | `usecase.<verb><Entity>`, `outbox.publish`, `job.<name>` | `usecase.registerUser` |
+| Span attribute | dotted lowercase, OTel semconv where one exists | `user.email.domain` |
+| Metric | `<module>_<entity>_<action>_total` / `_seconds`, snake_case | `bc05_user_registrations_total` |
+| Logger | one per class via `Log`/`Logger.getLogger(Xxx.class)` — never a shared `LogUtil` | |
+| MDC / jsonb trace keys | `snake_case`, exactly `trace_id` / `span_id` | |
+
+Span, metric and log-field names are a contract with the dashboards — renaming one silently breaks alerts. Treat a rename like an API change.
+
+## Metrics (Micrometer)
+
+- Rely on built-in HTTP/JVM-substrate/Kafka metrics first.
+- Custom business metrics: counters/timers via `MeterRegistry`, names `bc05_user_registrations_total` style, low-cardinality tags only.
+- Expose `/q/metrics` for Prometheus scrape or bridge Micrometer→OTLP if the platform standardizes on the collector for metrics too.
+
+## Health
+
+`quarkus-smallrye-health`: `/q/health/live`, `/q/health/ready`. Readiness includes DB and Kafka checks (provided by extensions). These endpoints are excluded from tracing (see suppress config).
+
+## Checklist per service
+
+1. `quarkus-opentelemetry` + JSON logging configured as above; OTLP → collector.
+2. Log format includes traceId/spanId (both profiles); `X-Trace-Id` response filter registered.
+3. JDBC telemetry enabled; `audit_event.context` jsonb populated with `trace_id`/`span_id` (+ index); outbox rows carry `traceparent` (header) AND `traceContext` in payload; the relay forwards the header.
+   3b. No manual trace-string construction anywhere — grep-check in review; only `Span.current()` via the OTel SDK.
+4. Key use cases annotated `@WithSpan`; attributes reviewed for PII/cardinality.
+5. Verify end-to-end in dev: one request produces a single trace spanning REST → DB → Kafka → consumer (Dev UI or Jaeger/Tempo).

package/src/bmm-skills/agents/bmad-quarkus-architect/skills/quarkus-openapi-tmforum/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: quarkus-openapi-tmforum
+description: API design and documentation standard for Quarkus REST services — OpenAPI 3.1 via SmallRye, Swagger UI restricted to dev/test, and full alignment with TM Forum Open API specifications (TMF630 design guidelines, TMF resource patterns, Error schema, pagination, filtering, JSON Merge Patch). Use this skill whenever the user mentions Swagger, OpenAPI, API documentation, REST API design, TMF/TM Forum APIs, endpoints/resources naming, pagination, PATCH semantics, or creates/reviews ANY REST resource class. Includes resource, DTO, mapper and operationId naming conventions.
+---
+
+# OpenAPI + TM Forum API Standard (Quarkus)
+
+North-bound/external REST APIs follow TM Forum Open API conventions (TMF630 REST Design Guidelines). Internal service-to-service calls use gRPC (see quarkus-grpc-services skill) — do not build internal REST clients. Applies to any Quarkus backend project (TMF specs matter most in telco-facing APIs; the TMF630 conventions are good REST defaults everywhere); project directives override where they conflict.
+
+Extension: `quarkus-smallrye-openapi`.
+
+## Design-first with TMF specs
+
+1. If a TM Forum spec covers the capability (e.g., TMF632 Party, TMF672 User Roles & Permissions, TMF720 Digital Identity, TMF691 Federated ID, TMF696), START from the official TMF OpenAPI file: commit it to the monorepo `contracts/` folder (e.g. `contracts/tmf678-customer-bill.yaml` — the same folder the app's `service.yaml` references under `apis.provided[].contract`), trim to the operations actually implemented, and implement resources to match it. Do not invent alternative shapes for concepts TMF already models.
+2. Only for non-TMF internal concepts, design your own — still following TMF630 conventions below.
+3. The OpenAPI document is the contract: generate/verify in CI that the served `/q/openapi` matches the committed spec (store snapshot, diff on build).
+
+## Swagger UI: dev/test only (hard rule)
+
+```properties
+# default is already dev-only; NEVER set always-include=true in a prod profile
+quarkus.swagger-ui.always-include=false
+%test.quarkus.swagger-ui.always-include=true
+quarkus.smallrye-openapi.info-title=${quarkus.application.name}
+quarkus.smallrye-openapi.info-version=${quarkus.application.version}
+```
+
+The raw OpenAPI document at `/q/openapi` may stay enabled in prod behind the gateway if the platform team requires it; Swagger UI itself never ships in the native prod binary.
+
+## TMF630 conventions to enforce on every resource
+
+### URLs & versioning
+- Plural kebab-free camelCase resource names as in TMF specs: `/user`, `/partyAccount` — follow the TMF spec exactly when implementing one; plural nouns for custom resources.
+- Base path: `/{context}/{apiName}/v{major}` e.g. `/tmf-api/digitalIdentityManagement/v4`. Major version in path only.
+
+### Standard operations
+| Operation | Verb | Response |
+|---|---|---|
+| List | `GET /resource` | 200 + array |
+| Retrieve | `GET /resource/{id}` | 200 |
+| Create | `POST /resource` | **201 + Location header + created body** |
+| Partial update | `PATCH /resource/{id}` (JSON Merge Patch, `application/merge-patch+json`) | 200 + updated body |
+| Delete | `DELETE /resource/{id}` | 204 |
+
+No PUT unless the TMF spec defines it. No RPC-ish URLs (`/user/activate`) — state changes go through PATCH of a state field or a TMF Task resource (`POST /resource/{id}/taskName` only when the spec defines the task pattern).
+
+### Query patterns (list operations)
+- **Attribute selection**: `?fields=id,name,status` — always support; huge payloads otherwise.
+- **Pagination**: `?offset=0&limit=20`; respond with headers `X-Total-Count`, `X-Result-Count`. Enforce a max limit.
+- **Filtering**: simple equality `?status=active&role=admin`; document supported filters per resource.
+
+### Resource body conventions
+- Every resource has `id` and `href`.
+- Polymorphism/extensibility fields where TMF-defined: `@type`, `@baseType`, `@schemaLocation`.
+- Dates ISO-8601 UTC (`OffsetDateTime` serialized as `2026-08-17T15:04:05Z`).
+- Errors: TMF Error schema from the unified handler (see quarkus-error-handling-i18n skill) — document it as the response for 4xx/5xx on every operation.
+
+## Annotating resources (SmallRye OpenAPI)
+
+DTOs live in `infrastructure/rest/dto` — never annotate domain classes.
+
+### Naming
+
+Canonical rules in the quarkus-hexagonal-core skill; REST/TMF specifics:
+
+| Artifact | Convention | Example |
+|---|---|---|
+| Resource class | `<Resource>Resource` — matches the TMF resource name | `DigitalIdentityResource` |
+| Response DTO | `<Resource>Dto` | `DigitalIdentityDto` |
+| Create / update DTO | `<Resource>CreateDto` / `<Resource>UpdateDto` (TMF `X_Create` / `X_Update`) | `DigitalIdentityCreateDto` |
+| Error DTO | `ErrorDto` (see quarkus-error-handling-i18n skill) | |
+| DTO ↔ domain mapper | `<Resource>RestMapper` | `DigitalIdentityRestMapper` |
+| `operationId` | `list/retrieve/create/patch/delete` + `<Resource>` | `listDigitalIdentity` |
+| Path segment | camelCase, exactly as the TMF spec spells it | `/partyAccount` |
+| JSON field | camelCase; TMF meta-fields keep their `@` | `@type`, `@baseType` |
+
+When implementing a TMF spec the wire names are **not negotiable** — DTO field names must match the spec even where our own convention would differ. The Java class name adds the `Dto` suffix; the serialized schema name stays the TMF one (`@Schema(name = "DigitalIdentity")`).
+
+```java
+@Path("/tmf-api/digitalIdentityManagement/v4/digitalIdentity")
+@Tag(name = "DigitalIdentity")
+public class DigitalIdentityResource {
+
+    private final CreateDigitalIdentityUseCase createIdentity;   // inbound port
+    private final DigitalIdentityRestMapper mapper;
+
+    public DigitalIdentityResource(CreateDigitalIdentityUseCase createIdentity,
+                                   DigitalIdentityRestMapper mapper) {
+        this.createIdentity = createIdentity;
+        this.mapper = mapper;
+    }
+
+    @GET
+    @Operation(operationId = "listDigitalIdentity", summary = "List or find DigitalIdentity objects")
+    @APIResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = DigitalIdentityDto[].class)))
+    @APIResponse(responseCode = "400", ref = "#/components/responses/BadRequest")
+    public RestResponse<List<DigitalIdentityDto>> list(
+            @QueryParam("fields") String fields,
+            @QueryParam("offset") @DefaultValue("0") int offset,
+            @QueryParam("limit") @DefaultValue("20") int limit) { ... }
+
+    @POST
+    @Operation(operationId = "createDigitalIdentity")
+    @APIResponse(responseCode = "201", headers = @Header(name = "Location"))
+    public RestResponse<DigitalIdentityDto> create(@Valid DigitalIdentityCreateDto dto, @Context UriInfo uri) {
+        var created = createIdentity.create(mapper.toCommand(dto));
+        return RestResponse.created(uri.getAbsolutePathBuilder().path(created.id()).build());
+    }
+}
+```
+
+Rules:
+- `operationId` on every operation (client generation depends on it); match TMF naming (`listX`, `retrieveX`, `createX`, `patchX`, `deleteX`).
+- Reusable components: define common responses (400/401/404/409/500 with TMF Error schema) once via an `@OpenAPIDefinition`/filter class, `ref` them everywhere.
+- `*CreateDto` (no id/href) vs full DTO — TMF pattern (`X_Create`, `X_Update`).
+- Bean Validation on DTOs (`@NotNull`, `@Size`) so constraints appear in the schema.
+
+## PATCH implementation (JSON Merge Patch)
+
+Consume `application/merge-patch+json`. Apply merge onto the current DTO representation, validate the result, map to an update command. Reject attempts to modify read-only fields (`id`, `href`, audit fields) with 400/409 per spec.
+
+## Checklist for a new endpoint
+
+1. TMF spec exists? Copy & trim official OpenAPI, implement to match.
+2. `<Resource>Resource` class with full annotations + operationIds; `<Resource>Dto` / `<Resource>CreateDto` with validation + `@RegisterForReflection`.
+3. Error responses referenced to the shared TMF Error components.
+4. fields/offset/limit on list operations; Location header on create.
+5. Snapshot test: `/q/openapi` diff against committed contract.

package/src/bmm-skills/agents/bmad-quarkus-architect/skills/quarkus-sql-jdbc-agroal/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: quarkus-sql-jdbc-agroal
+description: Standard for executing SQL queries, updates, batches, and transactions in Quarkus WITHOUT Panache or any ORM — using the Agroal connection pool with plain JDBC (default) or the reactive Vert.x SQL client (justified cases only). Use this skill whenever the user writes or reviews ANY repository, DAO, SQL statement, SELECT/INSERT/UPDATE/DELETE, batch operation, transaction, pagination query, jsonb access, connection pool configuration, or mentions Agroal, JDBC, PreparedStatement, datasource, or "query the database" — all persistence code must follow these patterns, including repository/adapter/row-mapper naming.
+---
+
+# SQL Execution Standard: Agroal + Plain JDBC (No ORM)
+
+Applies to any Quarkus backend project; project directives (CLAUDE.md, ADRs, explicit instructions) override these defaults where they conflict.
+
+Persistence is explicit SQL through the Agroal pool. No Panache, no Hibernate, no reflection-based row mappers. Repositories are adapters in `infrastructure/persistence` implementing outbound ports (see quarkus-hexagonal-core skill).
+
+One clarification to keep teams from chasing ghosts: **Agroal is a JDBC (blocking) pool** — there is no "reactive Agroal". The reactive path in Quarkus is the Vert.x SQL client (`quarkus-reactive-pg-client`) with its own pool. Default choice here is **Agroal + JDBC** (simpler, dominant skill base, works perfectly in native); reactive client only for measured hot paths with extreme concurrency (see §7).
+
+## 1. Datasource configuration (Agroal)
+
+```properties
+quarkus.datasource.db-kind=postgresql
+quarkus.datasource.username=${DB_USER}
+quarkus.datasource.password=${DB_PASSWORD}
+quarkus.datasource.jdbc.url=jdbc:postgresql://${DB_HOST}:5432/${DB_NAME}
+
+# Pool sizing: start small; size = concurrent transactions, NOT concurrent users
+quarkus.datasource.jdbc.min-size=2
+quarkus.datasource.jdbc.max-size=16
+quarkus.datasource.jdbc.acquisition-timeout=5S
+
+# Hygiene
+quarkus.datasource.jdbc.validation-query-sql=SELECT 1
+quarkus.datasource.jdbc.leak-detection-interval=60S
+quarkus.datasource.jdbc.idle-removal-interval=5M
+quarkus.datasource.jdbc.max-lifetime=30M
+
+# Observability (pairs with quarkus-observability-otel skill)
+quarkus.datasource.jdbc.telemetry=true
+quarkus.datasource.metrics.enabled=true
+```
+
+Rules:
+- `max-size` per pod must respect the DB's `max_connections` budget across ALL replicas of ALL services. Coordinate with DBAs; 16 is a ceiling, not a target.
+- Leak detection stays on in every environment — a logged leak is a bug, treat it as such.
+- Multiple datasources: named (`quarkus.datasource."audit".jdbc.url=...`) and injected with `@DataSource("audit")`.
+
+## 2. Injection and the golden resource pattern
+
+Inject the pool, never raw drivers, never `DriverManager`:
+
+```java
+@ApplicationScoped
+public class JdbcUserRepository implements UserRepository {
+
+    private final AgroalDataSource ds;
+    public JdbcUserRepository(AgroalDataSource ds) { this.ds = ds; }
+}
+```
+
+Every statement uses **try-with-resources on Connection, PreparedStatement AND ResultSet** — this is what returns connections to the pool. A missed close under load exhausts the pool and takes the native pod down:
+
+```java
+private static final String FIND_BY_ID = """
+    SELECT id, email, status, created_at
+    FROM app_user
+    WHERE id = ?
+    """;
+
+@Override
+public Optional<User> findById(UserId id) {
+    try (var con = ds.getConnection();
+         var ps  = con.prepareStatement(FIND_BY_ID)) {
+        ps.setObject(1, id.value());
+        try (var rs = ps.executeQuery()) {
+            return rs.next() ? Optional.of(mapRow(rs)) : Optional.empty();
+        }
+    } catch (SQLException e) {
+        throw translate("user.find_by_id", e);
+    }
+}
+```
+
+Absolute rules:
+- SQL as `private static final String` text blocks. Never concatenate user input — `PreparedStatement` placeholders ALWAYS (SQL injection + plan cache).
+- Dynamic WHERE clauses: build from a whitelist of column/operator constants, values still as placeholders.
+- One private `mapRow(ResultSet) -> Entity` per repository (or a `RowMapper<T>` functional interface shared via a tiny helper — see §6). No reflection mappers: they break native and hide cost.
+
+Naming (canonical rules in the quarkus-hexagonal-core skill):
+
+| Artifact | Convention | Example |
+|---|---|---|
+| Outbound port | `<Entity>Repository`, in `application/port/out` | `UserRepository` |
+| JDBC adapter | `Jdbc<Port>`, in `infrastructure/persistence` | `JdbcUserRepository` |
+| Shared row mapper | `<Entity>RowMapper` (private `mapRow` when not shared) | `UserRowMapper` |
+| SQL constant | `UPPER_SNAKE_CASE` verb-first `private static final String` | `FIND_BY_ID`, `INSERT_USER` |
+| Table / column | `snake_case`, singular table name | `app_user`, `created_at` |
+| Technical exception | `PersistenceException` + specific subtypes (§8) | `TransientPersistenceException` |
+
+Never name a repository `*Dao`, `*Manager` or `*Service` — `*Service` is reserved for use-case implementations, and a repository that grows business logic is a use case in disguise.
+
+## 3. Transactions: on the use case, not the repository
+
+The unit of work is the business operation. Annotate the **application-layer use case**:
+
+```java
+@ApplicationScoped
+public class RegisterUserService implements RegisterUserUseCase {   // impl = *Service, port = *UseCase
+
+    @Transactional
+    public UserId register(RegisterUserCommand cmd) {
+        var user = User.register(cmd);       // domain
+        userRepository.save(user);           // same tx
+        eventPublisher.publish(new UserRegistered(user.id())); // same tx (outbox insert)
+        return user.id();
+    }
+}
+```
+
+With `@Transactional` active, Agroal enlists the connection in the JTA transaction automatically — repositories keep using `ds.getConnection()` and all writes inside the use case share one transaction, committed/rolled back together. This is exactly what the outbox pattern requires (see quarkus-kafka-messaging skill).
+
+- Runtime exceptions roll back by default; domain exceptions extend `RuntimeException`, so throwing them rolls back — correct by construction.
+- Programmatic control when annotations don't fit (loops with per-item commit, batch jobs):
+
+```java
+QuarkusTransaction.requiringNew().timeout(30).run(() -> { ...repos... });
+```
+
+- Never call `con.commit()`/`setAutoCommit()` manually inside JTA-managed code paths.
+- Read-only single queries need no `@Transactional` (auto-commit read is fine); multi-read consistency or any write → transaction.
+
+## 4. Updates, inserts, upserts, generated keys
+
+```java
+private static final String INSERT = """
+    INSERT INTO app_user (id, email, status, created_at)
+    VALUES (?, ?, ?, ?)
+    ON CONFLICT (email) DO NOTHING
+    """;
+
+@Override
+public void save(User u) {
+    try (var con = ds.getConnection(); var ps = con.prepareStatement(INSERT)) {
+        ps.setObject(1, u.id().value());
+        ps.setString(2, u.email().value());
+        ps.setString(3, u.status().name());
+        ps.setObject(4, u.createdAt());
+        if (ps.executeUpdate() == 0) throw new DuplicateEmailException(u.email());
+    } catch (SQLException e) {
+        throw translate("user.save", e);
+    }
+}
+```
+
+- Check `executeUpdate()` counts — 0 rows on an expected UPDATE is a bug or a concurrency signal, not a success.
+- Prefer DB-generated values via `RETURNING` (Postgres) over `getGeneratedKeys()` when you need them: `INSERT ... RETURNING id` + `executeQuery()`.
+- Optimistic locking: `version` column, `UPDATE ... WHERE id = ? AND version = ?`; 0 rows → `StaleVersionException` (domain) → 409 via the unified handler. Do NOT name it `ConcurrentModificationException` — it shadows `java.util.ConcurrentModificationException` and an accidental import turns the 409 mapping into a 500.
+- Upserts: `ON CONFLICT ... DO UPDATE` explicitly; never SELECT-then-INSERT races.
+
+## 5. Batches, pagination, jsonb
+
+**Batch** (bulk inserts/updates — outbox relays, imports):
+
+```java
+try (var con = ds.getConnection(); var ps = con.prepareStatement(INSERT)) {
+    for (var item : items) {
+        bind(ps, item);
+        ps.addBatch();
+    }
+    ps.executeBatch();          // add ?reWriteBatchedInserts=true to the JDBC URL (Postgres)
+}
+```
+
+Chunk batches (500–1000) inside long jobs; combine with `QuarkusTransaction` per chunk.
+
+**Pagination**: keyset over OFFSET for anything user-facing/deep:
+
+```sql
+SELECT ... FROM app_user WHERE (created_at, id) < (?, ?) ORDER BY created_at DESC, id DESC LIMIT ?
+```
+
+OFFSET/LIMIT acceptable for TMF `offset/limit` list operations with bounded depth; when aggregations are involved, paginate FIRST in a CTE, then join/aggregate over the page — never aggregate the full set and paginate last.
+
+**jsonb** (audit `context`, outbox `payload` — see observability/kafka skills):
+
+```java
+var pgo = new org.postgresql.util.PGobject();
+pgo.setType("jsonb");
+pgo.setValue(json);          // serialized with Jackson/JsonObject, never string-built
+ps.setObject(5, pgo);
+```
+
+Read side: `rs.getString("context")` then parse. Index jsonb lookups you actually query (`(context->>'trace_id')`).
+
+## 6. A tiny helper is allowed; a framework is not
+
+To kill boilerplate, ONE small internal helper class (~50 lines) per service or shared lib is the sanctioned maximum:
+
+```java
+public final class Jdbc {
+    @FunctionalInterface public interface RowMapper<T> { T map(ResultSet rs) throws SQLException; }
+
+    public static <T> Optional<T> queryOne(DataSource ds, String sql, RowMapper<T> m, Object... params) { ... }
+    public static <T> List<T> queryList(DataSource ds, String sql, RowMapper<T> m, Object... params) { ... }
+    public static int update(DataSource ds, String sql, Object... params) { ... }
+}
+```
+
+- Pure delegation to the try-with-resources pattern above; no reflection, no annotations, no SQL generation. If someone proposes adding criteria builders or entity mapping to it, that's an ORM growing back — reject.
+- The class is named `Jdbc` — a namespace, not `JdbcUtils`/`JdbcHelper`. The banned-suffix ArchUnit rule (see quarkus-hexagonal-core skill) exists precisely to stop this class from becoming a junk drawer.
+- jOOQ (code-gen, type-safe SQL) MAY be evaluated as an alternative via formal ADR; MyBatis/Hibernate remain excluded.
+
+## 7. Blocking model: worker threads or virtual threads (and when reactive)
+
+JDBC blocks. Never run it on the event loop:
+
+- Quarkus REST resources are blocking by default when returning plain types — fine as-is.
+- Reactive signatures (`Uni`), Kafka consumers, gRPC: mark `@Blocking` or hop to a worker pool (see grpc/kafka skills).
+- **Virtual threads**: `@RunOnVirtualThread` on JDBC-heavy endpoints is the modern default for high-concurrency blocking work (Java 25 baseline; synchronized-block pinning is fixed since JDK 24) — cheap threads, same simple code. Caveat: keep pool `max-size` as the real ceiling; virtual threads make it easy to pile up on `acquisition-timeout`.
+- **Reactive SQL client** (`quarkus-reactive-pg-client`, Vert.x pool — NOT Agroal): only for measured hot paths (extreme fan-in, streaming thousands of rows). It's a different programming model and a second pool to size; adopting it in a service requires an ADR. Do not mix both models in the same repository class.
+
+## 8. SQLException translation
+
+One translator in `infrastructure/persistence`, mapping SQLState to domain/persistence exceptions so callers never see `SQLException`:
+
+| SQLState | Meaning | Throw |
+|---|---|---|
+| `23505` | unique violation | domain conflict exception (→ 409) |
+| `23503` | FK violation | domain integrity exception |
+| `40001` / `40P01` | serialization failure / deadlock | retryable `TransientPersistenceException` |
+| `57014` | statement timeout/cancel | `PersistenceTimeoutException` |
+| other | infrastructure failure | `PersistenceException(code, e)` (→ 500) |
+
+Set `statement_timeout` (session or per-datasource via `quarkus.datasource.jdbc.additional-jdbc-properties.options=-c statement_timeout=5000`) so runaway queries fail fast instead of holding pool connections.
+
+## 9. Testing
+
+- Repository tests: `@QuarkusTest` + Dev Services (Testcontainers Postgres starts automatically — no config). Real SQL against real Postgres; never H2 (dialect lies).
+- Flyway migrations run at test start (`quarkus.flyway.migrate-at-start=true`) — tests validate DDL and queries together.
+- Native verification: `@QuarkusIntegrationTest` re-runs the same tests against the binary.
+
+## Checklist for a new repository method
+
+0. Names follow the canonical table above (`Jdbc<Port>` adapter, `<Entity>Repository` port, `UPPER_SNAKE` SQL constants).
+1. SQL text block constant, placeholders only; whitelist for any dynamic fragment.
+2. try-with-resources on connection/statement/resultset (or the `Jdbc` helper).
+3. Transaction boundary on the use case, not here.
+4. `executeUpdate()` count checked; SQLState translated, never leaked.
+5. jsonb via `PGobject`; batch + chunking for bulk; keyset pagination if deep.
+6. `@Blocking`/virtual thread if called from a reactive context; Dev Services test written.

package/src/bmm-skills/module-help.csv

@@ -0,0 +1,19 @@
+module,skill,display-name,menu-code,description,action,args,phase,preceded-by,followed-by,required,output-location,outputs
+BMad Method,_meta,,,,,,,,,false,https://docs.bmad-method.org/llms.txt,
+BMad Method,bmad-project-context,Project Context,PC,"Set up or refresh a repo's agent instructions so AI agents work well in it: verified commands, policy, conventions that differ from defaults, and known pitfalls. Setup, refresh, record, and audit — replaces document-project and generate-project-context.",,,anytime,,,false,repo root,AGENTS.md managed block
+BMad Method,bmad-build,Build,BD,Official Phase 4 implementation loop: clarify intent plan implement review and present.,,,ship,bmad-sprint-planning,bmad-code-review,true,implementation_artifacts,spec and project implementation
+BMad Method,bmad-spec,Spec,SPC,"Use to distill any intent input (brief, PRD, transcript, brain dump, design folder, mixed multi-source) into a succinct, no-fluff SPEC.md contract + companions that downstream work derives from. Locks the WHAT before the HOW. Works for software, game design, research, editorial, policy, business, anything intent-bearing. Validation mode also available.",,[path],anytime,,,false,{output_folder}/specs/spec-{slug},SPEC.md + companion files
+BMad Method,bmad-correct-course,Correct Course,CC,Navigate significant changes. May recommend start over update PRD redo architecture sprint planning or correct epics and stories.,,,anytime,,,false,planning_artifacts,change proposal
+BMad Method,bmad-brainstorming,Brainstorm Project,BP,Expert guided facilitation through a single or multiple techniques.,,,plan,,,false,{output_folder}/brainstorming,brainstorming session
+BMad Method,bmad-product-brief,Create Brief,CB,An expert guided experience to nail down your product idea in a brief. a gentler approach than PRFAQ when you are already sure of your concept and nothing will sway you.,,-A,plan,,,false,planning_artifacts,product brief
+BMad Method,bmad-prfaq,PRFAQ Challenge,WB,Working Backwards guided experience to forge and stress-test your product concept to ensure you have a great product that users will love and need through the PRFAQ gauntlet to determine feasibility and alignment with user needs. alternative to product brief.,,-H,plan,,,false,planning_artifacts,prfaq document
+BMad Method,bmad-prd,Create Edit and Review PRD,PRD,"Facilitated PRD workflow — create a new PRD via coached discovery, update an existing one against a change signal, or validate a finished PRD against a checklist with an HTML findings report.",,,2-planning,bmad-product-brief,,true,planning_artifacts,prd
+BMad Method,bmad-ux,Create UX,CU,"Guidance through realizing the plan for your UX, strongly recommended if a UI is a primary piece of the proposed project.",,,2-planning,bmad-prd,,false,planning_artifacts,ux design
+BMad Method,bmad-architecture,Architecture,CA,Offer once requirements exist (a PRD or spec; plus UX if present) and the user is ready to move from what to how. Also offer any time independently-built parts risk diverging. Produces the architecture spine: the invariants that keep features epics and stories consistent. Comes before epics and stories and scales from a quick spine to a full architecture (brownfield: ratifies the existing codebase).,,,plan,,,true,planning_artifacts,architecture
+BMad Method,bmad-create-epics-and-stories,Create Epics and Stories,CE,,,,plan,bmad-architecture,,true,planning_artifacts,epics and stories
+BMad Method,bmad-sprint-planning,Sprint Planning,SP,Readiness gate then tracking: verifies the planning is implementable (PASS/CONCERNS/FAIL) and produces the sprint status the implementation agents follow for every story.,,,plan,,,true,implementation_artifacts,sprint status
+BMad Method,bmad-sprint-planning,Sprint Status,SS,Anytime: summarize sprint status with risks open action items and the next recommended action; can also validate or repair the tracking file.,status,,anytime,,,false,,status summary
+BMad Method,bmad-code-review,Code Review,CR,Ad hoc review of any code change. Optional extra layer after Build's built-in review.,,,ship,bmad-build,,false,,
+BMad Method,bmad-checkpoint-preview,Checkpoint,CK,Guided walkthrough of a change from purpose and context into details. Use for human review of commits branches or PRs.,,,ship,,,false,,
+BMad Method,bmad-qa-generate-e2e-tests,QA Automation Test,QA,Generate automated API and E2E tests for implemented code. NOT for code review or story validation — use CR for that.,,,ship,bmad-build,,false,implementation_artifacts,test suite
+BMad Method,bmad-retrospective,Retrospective,ER,Optional at epic end: Review completed work lessons learned and next epic or if major issues consider CC.,,,ship,bmad-code-review,,false,implementation_artifacts,retrospective