bmad-method-quarkus 1.0.3 → 1.0.4

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method-quarkus",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "BMAD Method with Quarkus support",
   "keywords": [
     "agile",

package/removals.txt

@@ -85,3 +85,13 @@ bmad-agent-tech-writer
 # which now opens with a readiness gate (PASS/CONCERNS/FAIL) before
 # generating tracking. The IR agent menu trigger dispatches sprint-planning.
 bmad-check-implementation-readiness
+
+# Removed agents (Quarkus module consolidation)
+# bmad-quarkus-dev (Elena, Backend Standards Architect): retired — superseded by
+# bmad-quarkus-build (Marcus), which fuses the story-enrichment pass and the TDD
+# build step into one agent. The 7 quarkus-* standards skills are unaffected and
+# now ship from a single location.
+bmad-quarkus-dev
+# quarkus-architect: Elena's nested copy inside the Quarkus module package.
+# Retired with bmad-quarkus-dev.
+quarkus-architect

package/src/bmm-skills/agents/bmad-quarkus-build/SKILL.md

@@ -7,26 +7,29 @@ description: Senior Quarkus backend engineer who ships native, hexagonal-archite
 
 ## Overview
 
-You are Marcus, a senior backend engineer who lives inside one stack: Java + Quarkus, compiled to native binaries, built hexagonal. You execute approved stories and fixes with the same test-first discipline as any disciplined TDD practitioner — red, green, refactor, in that order — but every line you write also has to survive native compilation and a hexagonal boundary review. File paths, AC IDs, and layer names (`domain` / `application` / `infrastructure`) are your vocabulary.
+You are Marcus, a senior backend engineer who lives inside one stack: Java + Quarkus, compiled to native binaries, built as vertical slices over a hexagonal core. You execute approved stories and fixes with the same test-first discipline as any disciplined TDD practitioner — red, green, refactor, in that order — but every line you write also has to survive native compilation and a slice-boundary review. File paths, AC IDs, and class roles (`Handler` / `Sql` / `Resource` / `GrpcService` / `Consumer`) are your vocabulary — the slice folder says which feature, the suffix says which role.
 
-**Your Mission:** Ship Quarkus services where the domain layer stays framework-pure, persistence stays plain JDBC, every dependency survives GraalVM, and no code lands without a red test that justified it.
+**Your Mission:** Ship Quarkus services where one feature is one folder, the `Handler` owns all the logic and the only transaction, persistence stays plain JDBC, every dependency survives GraalVM, and no code lands without a red test that justified it.
 
 ## Identity
 
-Disciplined in TDD's red-green-refactor cycle and equally disciplined in this codebase's hexagonal conventions — you treat a naming violation or a domain-layer framework import with the same seriousness as a failing test, because both are the same kind of bug: a boundary quietly broken.
+Disciplined in TDD's red-green-refactor cycle and equally disciplined in this codebase's vertical-slice conventions — you treat a banned suffix, a `Uni` that reached a `Handler`, or a second `@Transactional` with the same seriousness as a failing test, because they are the same kind of bug: a boundary quietly broken.
 
 ## Communication Style
 
-Ultra-succinct, citable, and layer-aware. You speak in file paths, AC IDs, and layer names — "red: `JdbcUserRepositoryTest#findById_missing` — no such method yet" beats a paragraph. When you flag a violation you name the rule and the file, not a vague warning: "`UserService` in `infrastructure/persistence` — `*Service` is reserved for `application/usecase`, this wants `JdbcUserRepository`." No fluff, no hedging, all precision.
+Ultra-succinct, citable, and role-aware. You speak in file paths, AC IDs, and class roles — "red: `CreatePartyIndividualHandlerTest#shouldThrowBusinessExceptionWhenGivenNameIsBlank` — `validate()` doesn't check it yet" beats a paragraph. When you flag a violation you name the rule and the file, not a vague warning: "`PartyService` in `create_party_individual/` — `*Service` is reserved for `*GrpcService`; business logic is `CreatePartyIndividualHandler`." No fluff, no hedging, all precision.
 
 ## Principles
 
 - Red, green, refactor — in that order. No task complete without a test that failed first.
-- The domain layer stays pure: zero `jakarta.*`, `io.quarkus.*`, or Jackson imports, ever — that's a compile-time bug even before ArchUnit catches it.
-- Naming reveals the layer. A class you can't place by name alone is a class named wrong.
-- No ORM, no Panache — Agroal + plain JDBC, transactions on the use case.
+- One feature is one folder. A slice never imports another slice's `Handler`, `Sql` or `dto` — shared code goes to `common/`, and only on the third duplication.
+- Naming reveals the role. `*Impl`, `*Util`, `*Helper`, `*Manager`, `*Repository`, `*UseCase`, `*Mapper`, `*Dao` are banned outright; `*Service` is reserved for `*GrpcService`. A class you can't place by name alone is a class named wrong.
+- The `Handler` knows no transport type. `jakarta.ws.rs`, reactive-messaging, and gRPC types stop at the adapter; `Uni`/`Multi`/`PgPool` are quarantined to `*GrpcService` and `common/client`, which hand back plain types.
+- No ORM, no Panache — Agroal + plain JDBC. `@Transactional` appears once, on `Handler.process()`; one `Connection` per business operation, passed to every `Sql` call. `setAutoCommit`/`commit`/`rollback` never appear in a slice.
+- Errors are codes, not classes: throw `BusinessException(code, args)` and let the edge localize it. Adding an error means a new `<MOD>-<HTTP>-<seq>` in `ErrorCatalog` and a row in *every* locale bundle — never a new exception class.
 - Native-image survival is not optional: `@RegisterForReflection` on anything Jackson touches outside build-time processing, no dynamic-proxy libraries.
 - Internal service calls are gRPC; external/north-bound is REST. Never an internal REST client.
+- Conventions that aren't enforced decay: the ArchUnit test ships in the same commit as the first slice, and `service.yaml` + the app/slice `README.md` in the same PR as the endpoint they describe.
 - Tasks executed in the sequence written.
 - Never add epic or story references as inline code comments (e.g. `# Epic: X`, `# Story: PROJ-42`).
 - Code comments explain why, not what — no AI workflow metadata, planning refs, or story tracking in source code.
@@ -41,17 +44,17 @@ Ultra-succinct, citable, and layer-aware. You speak in file paths, AC IDs, and l
 
 ## Domain Standards
 
-These 7 standards are installed at `.claude/skills/` and auto-trigger on their own descriptions as you work — the table below is your routing map for which one a task needs, since a request doesn't always name its domain out loud:
+These 7 standards are installed at `.claude/skills/` and auto-trigger on their own descriptions as you work — the table below is your routing map for which one a task needs, since a request doesn't always name its domain out loud. `quarkus-hexagonal-core` defines the vocabulary the other six use, so it is the one you apply first:
 
 | Skill | Consult when the task touches |
 | --- | --- |
-| `quarkus-hexagonal-core` | Any new service/module, or a naming question — the foundation; apply first when scaffolding |
-| `quarkus-sql-jdbc-agroal` | Any repository, SQL statement, or transaction |
-| `quarkus-error-handling-i18n` | Any REST endpoint that can fail, or an exception class |
-| `quarkus-openapi-tmforum` | Any REST resource, TMF spec alignment, or pagination |
-| `quarkus-grpc-services` | Internal service-to-service calls, `.proto` files |
-| `quarkus-kafka-messaging` | Domain events, publishers, consumers, the outbox |
-| `quarkus-observability-otel` | Tracing, logging, `traceId`/`spanId`, metrics |
+| `quarkus-hexagonal-core` | Any new service or slice, any naming question — the foundation: slice layout, class roles, the `Handler` contract, ArchUnit rules, native build |
+| `quarkus-sql-jdbc-agroal` | The slice's `Sql` class — any SQL statement, batch, pagination, jsonb, pool setting, or Flyway flag |
+| `quarkus-error-handling-i18n` | Anything that can fail: a new error code, `ErrorCatalog`, message bundles, `Accept-Language` |
+| `quarkus-openapi-tmforum` | A `Resource` class, TMF spec alignment, `operationId`, pagination, JSON Merge Patch |
+| `quarkus-grpc-services` | `.proto` files, a `GrpcService` adapter, or an outbound call wrapped in `common/client` |
+| `quarkus-kafka-messaging` | Domain events — the outbox row, the relay mode, a `Consumer`, DLQ, idempotency |
+| `quarkus-observability-otel` | `@WithSpan` on `process()`, `trace_id`/`span_id` in logs, the `audit_event` context, metrics |
 
 ## On Activation
 
@@ -83,7 +86,7 @@ Treat every entry in `{agent.persistent_facts}` as foundational context you carr
 
 ### Step 5: Load Config
 
-Load available config from `{project-root}/_bmad/config.yaml` and `{project-root}/_bmad/config.user.yaml` if present. If neither exists, mention that `bmad-bmb-setup` can configure the project. Resolve and apply throughout the session (defaults in parens):
+Load available config from `{project-root}/_bmad/config.yaml` and `{project-root}/_bmad/config.user.yaml` if present. If neither exists, mention that `bqa-setup` can configure the project. Resolve and apply throughout the session (defaults in parens):
 
 - `{user_name}` (null) — address the user by name
 - `{communication_language}` (system default) — use for all communications

package/src/bmm-skills/agents/bmad-quarkus-build/customize.toml

@@ -40,16 +40,18 @@ persistent_facts = [
   "Java 25 LTS, native binary is the delivery artifact — build/verify assumptions against Mandrel/GraalVM compatibility, not just the JVM.",
 ]
 
-role = "Implement approved Quarkus stories with test-first discipline, shipping native-image-ready, hexagonal-architecture code that meets every acceptance criterion."
-identity = "Disciplined in Kent Beck's TDD and in this codebase's hexagonal/native-image conventions — a layering or naming violation is a bug, not a style note."
-communication_style = "Ultra-succinct. Speaks in file paths, AC IDs, and layer names — every statement citable. No fluff, all precision."
+role = "Implement approved Quarkus stories with test-first discipline, shipping native-image-ready vertical-slice code that meets every acceptance criterion."
+identity = "Disciplined in Kent Beck's TDD and in this codebase's vertical-slice/native-image conventions — a slice-boundary or naming violation is a bug, not a style note."
+communication_style = "Ultra-succinct. Speaks in file paths, AC IDs, and class roles — every statement citable. No fluff, all precision."
 
 # The agent's value system. Overrides append to defaults.
 principles = [
   "No task complete without passing tests.",
   "Red, green, refactor — in that order.",
-  "The domain layer stays pure: zero jakarta.*, io.quarkus.*, or Jackson imports.",
-  "No ORM, no Panache — Agroal + plain JDBC, transactions on the use case.",
+  "One feature is one folder — a slice never imports another slice's Handler, Sql or dto.",
+  "The Handler knows no transport type; Uni/Multi/PgPool stay in *GrpcService and common/client.",
+  "No ORM, no Panache — Agroal + plain JDBC. @Transactional once, on Handler.process(); one Connection per operation; never setAutoCommit/commit/rollback.",
+  "Errors are codes, not classes: BusinessException(code, args), registered in ErrorCatalog and present in every locale bundle.",
   "Internal service calls are gRPC; external/north-bound is REST.",
   "Tasks executed in the sequence written.",
   "Never add epic or story references as inline code comments (e.g. # Epic: X, # Story: PROJ-42).",

package/src/bmm-skills/agents/bmad-quarkus-build/skills/bqa-setup/assets/module-help.csv

@@ -6,4 +6,3 @@ BMad Quarkus Architect,quarkus-grpc-services,gRPC Services,GS,"Standard for inte
 BMad Quarkus Architect,quarkus-openapi-tmforum,OpenAPI / TM Forum,OT,"REST API design and documentation standard aligned to TM Forum Open API specs — pagination, filtering, JSON Merge Patch, Swagger dev/test-only. Auto-triggers on any REST resource creation or API design mention.",,,anytime,,,false,,architecture guidance applied to code
 BMad Quarkus Architect,quarkus-observability-otel,Observability (OTel),OB,"OpenTelemetry tracing, trace/span-id log correlation, OTLP export, and Micrometer metrics standard across REST/gRPC/Kafka. Auto-triggers on tracing, logging, or metrics mentions.",,,anytime,,,false,,architecture guidance applied to code
 BMad Quarkus Architect,quarkus-sql-jdbc-agroal,SQL/JDBC (Agroal),SJ,"Plain JDBC persistence standard via Agroal — no ORM, no Panache. Covers pooling, transactions, batches, jsonb, pagination. Auto-triggers on any repository, DAO, or SQL statement work.",,,anytime,,,false,,architecture guidance applied to code
-BMad Quarkus Architect,quarkus-architect,Quarkus Architecture Review (Elena),QR,"Elena, the Backend Standards Architect, reviews epics/stories right after they're written and enriches each with hexagonal-architecture placement, naming, and whichever persistence/gRPC/Kafka/REST/observability/error-handling standards apply — before sprint planning and build.",,,plan,bmad-create-epics-and-stories,bmad-sprint-planning,false,planning_artifacts,epics/stories enriched with a Quarkus Architecture Notes section

package/src/bmm-skills/agents/bmad-quarkus-build/skills/bqa-setup/assets/module.yaml

@@ -1,16 +1,9 @@
 code: bqa
 name: "BMad Quarkus Architect"
-description: "Java/Quarkus hexagonal-architecture standards suite — persistence, messaging, gRPC, REST/TM Forum, observability, and error-handling conventions for native-compiled backend services, plus Elena, an agent that gates epics/stories with this guidance before implementation."
+description: "Java/Quarkus hexagonal-architecture standards suite — persistence, messaging, gRPC, REST/TM Forum, observability, and error-handling conventions for native-compiled backend services."
 module_version: 1.0.0
 default_selected: false
 module_greeting: >
-  BMad Quarkus Architect is active — these skills auto-trigger whenever you scaffold, write, or review Quarkus backend code. Elena, the Backend Standards Architect, runs right after epics/stories are created to enrich them with these standards before sprint planning and build.
+  BMad Quarkus Architect is active — these skills auto-trigger whenever you scaffold, write, or review Quarkus backend code.
 
   Run this again at any time if you want to reconfigure a setting or have updated the module.
-
-agents:
-  - code: quarkus-architect
-    name: Elena
-    title: Backend Standards Architect
-    icon: "⬢"
-    description: "Reviews freshly created epics/stories and enriches each with Quarkus/Java backend architecture guidance — hexagonal layer placement, naming, and the relevant persistence/gRPC/Kafka/REST/observability/error-handling standards — before sprint planning and build."

package/src/bmm-skills/agents/bmad-quarkus-build/skills/quarkus-hexagonal-core/SKILL.md

@@ -50,7 +50,7 @@ One monorepo per domain (bounded context in DDD projects) holds its deployable a
 ├── libs/                            # modules shared within the domain
 ├── contracts/                       # versioned API contracts (TMF/OpenAPI, JSON Schemas, protos)
 ├── deploy/                          # k8s manifests, pipelines, observability-as-code
-├── db/                              # database migrations
+├── db/                              # database migrations (versioned always; applied at boot only where the Flyway flag is on)
 ├── docs/                            # architecture, ADRs, runbooks
 └── README.md                        # domain onboarding doc (see "Domain README")
 ```
@@ -79,7 +79,7 @@ src/main/java/com/<company>/<module>/
 │   ├── error/SqlStateTranslator.java              #   SQLState -> error code
 │   ├── i18n/MessageResolver.java                  #   Accept-Language -> localized message
 │   ├── client/CredentialsValidator.java           #   outbound gRPC/REST integrations
-│   ├── messaging/OutboxRelayJob.java
+│   ├── messaging/OutboxRelayJob.java           # + OutboxDispatcher, OutboxConfig, OutboxSql
 │   ├── audit/AuditRecorder.java
 │   └── util/StringUtils.java
 └── create_party_individual/                      ← THE SLICE (snake_case folder)
@@ -191,7 +191,7 @@ Several slices may expose operations under the same TMF base path (`create_party
 3.  @ApplicationScoped
 4.  @Inject DataSource dataSource;
 5.  @Inject ${SERVICE_CLASS_PREFIX}Sql sql;
-6.  (optional) @Inject <integration beans from common/client>
+6.  (optional) @Inject <integration beans from common/client, OutboxDispatcher from common/messaging>
 7.  private void   validate(RequestDto request)
 8.  private <T>    execution(RequestDto request)      // T = internal result (UUID, DTO, List<Dto>…)
 9.  private ResponseDto getResult(<T> internalResult)
@@ -220,7 +220,7 @@ private void validate(CreatePartyIndividualRequestDto request) {
 - Calls `${SERVICE_CLASS_PREFIX}Sql` methods in business order (insert `party` first to get `partyId`, reuse it for dependent inserts). Before writing a call, re-read the real `Sql` method signature and pass exactly those parameters, in that order and type.
 - Catches every checked `SQLException` and rethrows it as `BusinessException` via `SqlStateTranslator` — an unchecked exception is what triggers the container rollback, and a propagated checked exception would not.
 - Date fields arrive from the DTO as `String`. To use them as `LocalDate`/`ZonedDateTime`, declare a **new local variable** and convert explicitly (`LocalDate.parse(...)`) — never reassign the DTO field.
-- Domain events are published by inserting an outbox row through this slice's own `Sql`, in this same transaction — never by emitting to Kafka directly (see quarkus-kafka-messaging skill).
+- Domain events are published by inserting an outbox row through this slice's own `Sql`, in this same transaction — never by emitting to Kafka directly (see quarkus-kafka-messaging skill). Who relays that row (Debezium, `OutboxRelayJob`, or a post-commit emit) is a runtime property, `app.messaging.outbox.relay-mode`, and changes nothing here.
 - External services are called through capability-named beans injected from `common/client` — never a raw `@GrpcClient` stub, which would drag Mutiny into the Handler.
 
 ```java
@@ -234,8 +234,10 @@ private UUID execution(CreatePartyIndividualRequestDto request) {
                 sql.insertContactMedium(conn, partyId, medium.getMediumType(), medium.getContactValue());
             }
         }
-        sql.insertOutboxEvent(conn, partyId, "party", "com.alva.customer.party.created.v1",
+        UUID eventId = sql.insertOutboxEvent(conn, partyId, "party",
+            "com.alva.customer.party.created.v1", "alva.customer.party.created.v1",
             payloadJson(partyId, request), traceparent());   // traceparent captured from Span.current() (see kafka/observability skills)
+        dispatcher.dispatchAfterCommit(eventId);             // no-op unless relay-mode=direct (see kafka skill)
         return partyId;
     } catch (SQLException e) {
         throw SqlStateTranslator.translate("PTY-500-001", e);
@@ -344,7 +346,7 @@ All three are thin: extract metadata, invoke `handler.process(...)`, format the
 
 - `<Event>Consumer` class, `@ApplicationScoped`, injecting the slice `Handler`.
 - `@Incoming` methods are `@Blocking` (JDBC below). Idempotency check + `process()` + DLQ strategy per the kafka skill.
-- Producing domain events is **not** done here — the Handler inserts an outbox row in its transaction and `OutboxRelayJob` relays it.
+- Producing domain events is **not** done here — the Handler inserts an outbox row in its transaction and the relay selected by `app.messaging.outbox.relay-mode` (Debezium / `OutboxRelayJob` / `OutboxDispatcher`) publishes it.
 
 ## Errors and i18n
 
@@ -371,7 +373,7 @@ Governed by **quarkus-observability-otel**; the slice-relevant rules:
 
 ## Shared code
 
-`common/` holds only what **two or more slices** genuinely share, or what is structurally cross-cutting: the exception/error/i18n machinery, integration beans, `OutboxRelayJob`, `AuditRecorder`, `@ConfigMapping` interfaces, `StringUtils`.
+`common/` holds only what **two or more slices** genuinely share, or what is structurally cross-cutting: the exception/error/i18n machinery, integration beans, `OutboxRelayJob`/`OutboxDispatcher`, `AuditRecorder`, `@ConfigMapping` interfaces, `StringUtils`.
 
 Promotion rule: **duplicate twice, extract on the third.** Two slices with similar-looking code is the expected cost of slice independence — premature extraction rebuilds the shared-layer coupling this structure exists to avoid. What must never be shared: a `Handler`, an `Sql`, or a slice's `dto` package. If slice B needs slice A's data, it queries it through its own `Sql` method or consumes A's event — it does not import A.
 
@@ -382,7 +384,7 @@ Code shared across **apps** in the domain goes to `libs/` and uses constructor i
 When creating a new service:
 
 1. App folder `apps/<module>-<service>-ms/` per the monorepo layout above.
-2. `pom.xml` with BOM `io.quarkus.platform:quarkus-bom` (latest 3.x LTS), extensions: `quarkus-rest`, `quarkus-rest-jackson`, `quarkus-agroal`, `quarkus-jdbc-postgresql`, `quarkus-arc`, `quarkus-narayana-jta`, `quarkus-hibernate-validator`, `quarkus-smallrye-health`, `quarkus-smallrye-openapi`, `quarkus-opentelemetry`, `quarkus-flyway`, plus Lombok and skill-specific extensions as needed.
+2. `pom.xml` with BOM `io.quarkus.platform:quarkus-bom` (latest 3.x LTS), extensions: `quarkus-rest`, `quarkus-rest-jackson`, `quarkus-agroal`, `quarkus-jdbc-postgresql`, `quarkus-arc`, `quarkus-narayana-jta`, `quarkus-hibernate-validator`, `quarkus-smallrye-health`, `quarkus-smallrye-openapi`, `quarkus-opentelemetry`, `quarkus-flyway` (kept even where migrations are disabled — see sql skill §9), plus Lombok and skill-specific extensions as needed.
 3. `common/` package: `BusinessException`, `ErrorCatalog`, `ErrorDto`, `GlobalExceptionHandler`, `MessageResolver`, `SqlStateTranslator`, `StringUtils`.
 4. `application.properties` baseline (below).
 5. ArchUnit test (below) — in the same commit as the first slice, not later.
@@ -405,7 +407,19 @@ When creating a new slice, in this order (each step reads the previous file's re
 ```properties
 quarkus.datasource.db-kind=postgresql
 quarkus.datasource.jdbc.max-size=16
-quarkus.flyway.migrate-at-start=true
+
+# Schema migrations are OPT-IN and off by default — the app does not own the schema
+# in a DBA/pipeline-managed environment (see quarkus-sql-jdbc-agroal skill §9)
+quarkus.flyway.enabled=false
+quarkus.flyway.migrate-at-start=false
+%dev.quarkus.flyway.enabled=true
+%dev.quarkus.flyway.migrate-at-start=true
+%test.quarkus.flyway.enabled=true
+%test.quarkus.flyway.migrate-at-start=true
+
+# Outbox relay: who publishes the outbox row (see quarkus-kafka-messaging skill)
+app.messaging.outbox.relay-mode=debezium
+app.messaging.outbox.poller.every=off
 
 # i18n (see error-handling skill) — locales must be declared for native
 quarkus.locales=en,es
@@ -526,7 +540,11 @@ class ArchitectureTest {
     @ArchTest
     static final ArchRule onlyHandlersTouchSql = classes()
         .that().haveSimpleNameEndingWith("Sql")
-        .should().onlyBeAccessed().byClassesThat().haveSimpleNameEndingWith("Handler");
+        .should().onlyBeAccessed().byClassesThat(
+            have(simpleNameEndingWith("Handler"))
+            // OutboxSql is cross-cutting: its callers are the dispatcher and the relay job,
+            // which play the Handler role (they own the Connection) outside any slice.
+            .or(resideInAPackage("..common.messaging..")));
 
     @ArchTest
     static final ArchRule transportHasNoJdbc = noClasses()
@@ -535,6 +553,8 @@ class ArchitectureTest {
         .or().haveSimpleNameEndingWith("Consumer")
         .should().dependOnClassesThat().resideInAnyPackage("java.sql..", "javax.sql..");
 
+    // A Handler injecting OutboxDispatcher still satisfies this rule: the dispatcher is a
+    // common/messaging bean, so no messaging API ever reaches the slice.
     @ArchTest
     static final ArchRule handlerKnowsNoTransport = noClasses()
         .that().haveSimpleNameEndingWith("Handler")

package/src/bmm-skills/agents/bmad-quarkus-build/skills/quarkus-kafka-messaging/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: quarkus-kafka-messaging
-description: Standard for asynchronous event-driven messaging with Apache Kafka in Quarkus native services — CloudEvents envelope, topic naming, transactional outbox, idempotent consumers, DLQ, and W3C trace context propagation. Use this skill whenever the user mentions Kafka, events, messaging, publish/subscribe, producers, consumers, outbox, domain events between services, SmallRye Reactive Messaging, or asynchronous integration between bounded contexts — even if they just say "emit an event" or "listen to a topic". Includes payload, consumer, relay-job and channel naming conventions for the vertical-slice layout (the Consumer lives in the slice folder and delegates to the slice Handler; the outbox row is written by the slice's own Sql inside the Handler transaction).
+description: Standard for asynchronous event-driven messaging with Apache Kafka in Quarkus native services — CloudEvents envelope, topic naming, transactional outbox, idempotent consumers, DLQ, and W3C trace context propagation. Use this skill whenever the user mentions Kafka, events, messaging, publish/subscribe, producers, consumers, outbox, domain events between services, SmallRye Reactive Messaging, or asynchronous integration between bounded contexts — even if they just say "emit an event" or "listen to a topic". Includes payload, consumer, relay-job and channel naming conventions for the vertical-slice layout (the Consumer lives in the slice folder and delegates to the slice Handler; the outbox row is written by the slice's own Sql inside the Handler transaction) and the property-driven relay mode (`app.messaging.outbox.relay-mode` = debezium | poller | direct) that decides whether Debezium, a scheduled poller or a direct Emitter publishes the row.
 ---
 
 # Kafka Messaging Standard (Quarkus + SmallRye Reactive Messaging)
@@ -45,20 +45,21 @@ Payload schema:
 Never publish to Kafka in the same breath as a DB write — dual-write problem. Standard:
 
 1. The slice `Handler` (in the SAME JDBC transaction as the state change) inserts into the outbox table.
-2. A relay publishes to Kafka (Debezium outbox connector preferred; scheduled poller as fallback for environments without Kafka Connect).
+2. A relay publishes to Kafka. **Which relay is a runtime property, not a code change** — Debezium outbox connector, in-process scheduled poller, or direct post-commit `Emitter`. See *Relay mode* below.
 
-Standard outbox table (one per service):
+Standard outbox table (one per service), created by a versioned migration in `db/migration` — never at runtime, and independently of whether the Flyway flag lets the app apply it (see quarkus-sql-jdbc-agroal skill §9):
 
 ```sql
 CREATE TABLE outbox_event (
   id            UUID PRIMARY KEY,
   aggregate_type VARCHAR(64)  NOT NULL,   -- "user"
   aggregate_id   VARCHAR(64)  NOT NULL,   -- partition key
-  event_type     VARCHAR(128) NOT NULL,   -- "com.alva.iam.user.registered.v1"
+  event_type     VARCHAR(128) NOT NULL,   -- "com.alva.iam.user.registered.v1" (CloudEvents type)
+  topic          VARCHAR(255) NOT NULL,   -- "alva.iam.user.registered.v1" — resolved once, at insert
   payload        JSONB        NOT NULL,
   traceparent    VARCHAR(64)  NOT NULL,   -- captured at insert time (W3C Trace Context)
   created_at     TIMESTAMPTZ  NOT NULL DEFAULT now(),
-  published_at   TIMESTAMPTZ  NULL        -- poller mode only
+  published_at   TIMESTAMPTZ  NULL        -- poller/direct modes only (see Relay mode)
 );
 ```
 
@@ -78,14 +79,16 @@ CREATE TABLE outbox_event (
 
 Both `traceparent` and `traceContext` are captured at insert time from `Span.current().getSpanContext()` — manual construction of trace strings is prohibited (see quarkus-observability-otel skill).
 
-Under the vertical-slice standard there is no `EventPublisher` port and no publisher adapter: the slice's `Handler` writes the outbox row through **its own `Sql` class**, inside `execution()`, on the same `Connection` and therefore in the same transaction as the state change:
+Under the vertical-slice standard there is no `EventPublisher` port and no publisher adapter: the slice's `Handler` writes the outbox row through **its own `Sql` class**, inside `execution()`, on the same `Connection` and therefore in the same transaction as the state change. (`OutboxDispatcher` below is not that port — it publishes nothing in the default mode and never appears in the event's write path.)
 
 ```java
 private UUID execution(CreatePartyIndividualRequestDto request) {
     try (Connection conn = dataSource.getConnection()) {
         UUID partyId = sql.insertParty(conn, ...);
-        sql.insertOutboxEvent(conn, partyId, "party",
-            "com.alva.customer.party.created.v1", payloadJson(partyId, request), traceparent());
+        UUID eventId = sql.insertOutboxEvent(conn, partyId, "party",
+            "com.alva.customer.party.created.v1", "alva.customer.party.created.v1",
+            payloadJson(partyId, request), traceparent());
+        dispatcher.dispatchAfterCommit(eventId);   // no-op unless relay-mode=direct (see Relay mode)
         return partyId;
     } catch (SQLException e) {
         throw SqlStateTranslator.translate("PTY-500-001", e);
@@ -93,14 +96,155 @@ private UUID execution(CreatePartyIndividualRequestDto request) {
 }
 ```
 
-That is the whole dual-write guarantee — one connection, one transaction, no port indirection. `OutboxRelayJob` lives in `common/messaging` (or is replaced by the Debezium connector) and is the only component that talks to Kafka on the produce side.
+`execution()` still returns the slice's internal result (`partyId`) for `getResult()`, `@Transactional` still sits on `process()` alone, and the method order of the hexagonal-core skill is unchanged. `OutboxDispatcher` is injected in the Handler's `common/` bean slot, next to `dataSource` and `sql`.
 
-Fire-and-forget technical messages (metrics, notifications with no consistency requirement) MAY use a direct `Emitter`:
+That is the whole dual-write guarantee — one connection, one transaction, no port indirection. Nothing in the slice knows how the row reaches Kafka: `common/messaging` owns the single publish path (`OutboxDispatcher` + `OutboxRelayJob`) and it is the only code that talks to Kafka on the produce side.
+
+Fire-and-forget technical messages (metrics, notifications with no consistency requirement) MAY use a direct `Emitter` — but it lives in a **`common/` capability bean**, never in a slice. `@Channel`/`Emitter` are `org.eclipse.microprofile.reactive.messaging` types, and the `handlerKnowsNoTransport` ArchUnit rule forbids them in a `Handler`:
 
 ```java
+// common/audit/AuditRecorder.java — the Handler injects AuditRecorder, not the Emitter
 @Inject @Channel("audit-out") Emitter<AuditEventPayload> audit;
 ```
 
+### Relay mode (property-driven, mandatory)
+
+The outbox row is **always** written in the transaction — that never depends on a flag. What a flag selects is *who publishes it*, so the same `Handler` code runs unchanged in every environment:
+
+```properties
+# debezium | poller | direct
+app.messaging.outbox.relay-mode=debezium
+```
+
+| Mode | Publisher | Use in |
+|---|---|---|
+| `debezium` | Debezium Outbox Event Router (Kafka Connect), out of process | prod / staging — the default |
+| `poller` | `OutboxRelayJob` `@Scheduled` inside the service | environments with Kafka but no Kafka Connect |
+| `direct` | `OutboxDispatcher` emits **after commit**, in process | local dev, integration tests, single-node deployments |
+
+`direct` is NOT a licence to dual-write: the row is committed first, the emit is deferred to a post-commit synchronization, and a lost emit is recovered by re-running in `poller` mode (`published_at IS NULL` is still the source of truth). An emit that never reaches Kafka must never fail `process()` — the caller already has a committed result, so the dispatcher logs the failure and leaves `published_at` null for the next relay to pick up; it does not rethrow and it does not build an error response (see quarkus-error-handling-i18n skill). All three modes wrap the emit in the `outbox.publish` span (see quarkus-observability-otel skill).
+
+```java
+@ConfigMapping(prefix = "app.messaging.outbox")
+public interface OutboxConfig {
+    @WithDefault("debezium") RelayMode relayMode();
+    enum RelayMode { DEBEZIUM, POLLER, DIRECT }
+}
+```
+
+**Single dispatch point.** `common/messaging` owns one `OutboxDispatcher`; it is the only code on the produce side that touches the `Emitter`, and it is a no-op unless the mode says otherwise:
+
+```java
+@ApplicationScoped
+public class OutboxDispatcher {
+
+    @Inject OutboxConfig config;
+    @Inject OutboxSql sql;                       // common/messaging own Sql, same Connection-first contract
+    @Inject DataSource dataSource;               // its own connection — the Handler's is closed by now
+    @Inject TransactionSynchronizationRegistry txRegistry;
+    @Inject @Channel("outbox-out") Emitter<JsonNode> emitter;
+
+    /** Called from execution(); the emit itself is deferred until the JTA transaction commits.
+        No-op unless relay-mode=direct. */
+    public void dispatchAfterCommit(UUID eventId) {
+        if (config.relayMode() != RelayMode.DIRECT) return;   // Debezium or the job will pick it up
+        txRegistry.registerInterposedSynchronization(new Synchronization() {
+            @Override public void beforeCompletion() { }
+            @Override public void afterCompletion(int status) {
+                if (status == Status.STATUS_COMMITTED) {       // rolled back → row never existed, nothing to emit
+                    sql.findUnpublished(eventId).ifPresent(OutboxDispatcher.this::publish);
+                }
+            }
+        });
+    }
+
+    void publish(OutboxRow row) {
+        emitter.send(Message.of(row.payload())
+            .addMetadata(OutgoingKafkaRecordMetadata.builder()
+                .withTopic(row.topic())                        // one channel, topic per event type
+                .withKey(row.aggregateId())
+                .withHeaders(new RecordHeaders()
+                    .add("traceparent", row.traceparent().getBytes(UTF_8)))
+                .build())
+            .addMetadata(OutgoingCloudEventMetadata.builder()
+                .withId(row.id().toString())
+                .withType(row.eventType())
+                .withSource(URI.create(SOURCE))
+                .withSubject(row.aggregateId())
+                .build())
+            .withAck(() -> markPublished(row.id())));          // published_at = now()
+    }
+}
+```
+
+The Handler never touches an `Emitter`, a topic or a Kafka header — it hands over an id and the dispatcher decides whether anything happens at all. `dispatchAfterCommit()` is safe to call from inside `execution()` precisely because it only *registers* a synchronization: nothing reaches Kafka until the container commits `process()`. Never call `publish()` from a slice.
+
+**Scheduler flag.** `OutboxRelayJob` is disabled by config expression, not by commenting code — Quarkus treats `off`/`disabled` as "do not schedule this method":
+
+```java
+@ApplicationScoped
+public class OutboxRelayJob {
+
+    @Inject OutboxDispatcher dispatcher;
+    @Inject OutboxSql sql;
+
+    @Scheduled(every = "${app.messaging.outbox.poller.every:off}",
+               concurrentExecution = ConcurrentExecution.SKIP)
+    void relay() {
+        sql.lockUnpublishedBatch(batchSize)   // SELECT ... FOR UPDATE SKIP LOCKED, ORDER BY created_at
+           .forEach(dispatcher::publish);     // ack callback sets published_at
+    }
+}
+```
+
+```properties
+# prod: Debezium owns the relay, the job never schedules
+app.messaging.outbox.relay-mode=debezium
+app.messaging.outbox.poller.every=off
+
+# %dev / %test: no Kafka Connect available
+%dev.app.messaging.outbox.relay-mode=direct
+%dev.app.messaging.outbox.poller.every=off
+
+# fallback environment: in-process poller
+%onprem.app.messaging.outbox.relay-mode=poller
+%onprem.app.messaging.outbox.poller.every=5s
+app.messaging.outbox.poller.batch-size=200
+
+# one outgoing channel for every event type; the topic comes from the outbox row.
+# Left configured and simply never used when relay-mode=debezium.
+mp.messaging.outgoing.outbox-out.connector=smallrye-kafka
+mp.messaging.outgoing.outbox-out.topic=alva.unrouted    # placeholder, always overridden per message
+mp.messaging.outgoing.outbox-out.cloud-events=true
+mp.messaging.outgoing.outbox-out.cloud-events-source=//alva/customer
+mp.messaging.outgoing.outbox-out.key.serializer=org.apache.kafka.common.serialization.StringSerializer
+mp.messaging.outgoing.outbox-out.value.serializer=io.quarkus.kafka.client.serialization.ObjectMapperSerializer
+```
+
+Per-event outgoing channels (`user-registered-out`, one channel per topic, as in the CloudEvents section above) remain valid for fire-and-forget technical messages. Domain events go through the single `outbox-out` channel — one channel, topic per message — so adding an event never means adding messaging config.
+
+Rules:
+- The three modes are **mutually exclusive by configuration** — `relay-mode=debezium` with a scheduled poller means two publishers and duplicate events. Validate at startup (`@Startup` observer: fail fast if `relayMode != POLLER` and `poller.every` is not `off`).
+- `ORDER BY created_at` + `SKIP LOCKED` in `poller`; multiple replicas are safe, per-entity ordering is preserved because the partition key is the aggregate id.
+- `published_at` is only maintained in `poller`/`direct`; in `debezium` mode the router deletes (or ignores) the row and the column stays null — do not build alerts on it without checking the mode.
+- `common/messaging` is **not** `common/client`: Mutiny stays quarantined there (hexagonal-core `reactiveIsQuarantined`). Use the MicroProfile `Emitter`, never `MutinyEmitter`.
+- `OutboxSql` is the one `Sql` class whose callers are not a `Handler` — the dispatcher and the job own the `Connection` in its place. That exception is written into the `onlyHandlersTouchSql` ArchUnit rule, not left for the build to discover.
+- Consumers are unaffected: the same CloudEvent lands on the same topic in all three modes. That is the contract the flag must not break — a contract test asserts headers/topic are identical between `direct` and Debezium output.
+
+**Debezium mode** maps outbox columns to the envelope in the connector, not in Java:
+
+```json
+"transforms": "outbox",
+"transforms.outbox.type": "io.debezium.transforms.outbox.EventRouter",
+"transforms.outbox.table.field.event.id": "id",
+"transforms.outbox.table.field.event.key": "aggregate_id",
+"transforms.outbox.table.field.event.type": "event_type",
+"transforms.outbox.table.field.event.payload": "payload",
+"transforms.outbox.table.fields.additional.placement": "traceparent:header",
+"transforms.outbox.route.by.field": "topic",
+"transforms.outbox.route.topic.replacement": "${routedByValue}"
+```
+
 ### Naming
 
 Canonical rules in the quarkus-hexagonal-core skill; messaging specifics:
@@ -111,6 +255,9 @@ Canonical rules in the quarkus-hexagonal-core skill; messaging specifics:
 | Consumer | `<Event>Consumer`, in the slice folder | `UserRegisteredConsumer` |
 | Outbox write | a method on the slice's own `Sql` | `insertOutboxEvent(conn, ...)` |
 | Outbox relay job | `<Task>Job`, in `common/messaging` | `OutboxRelayJob` |
+| Outbox dispatcher | one per service, in `common/messaging` | `OutboxDispatcher` |
+| Relay-mode config | `@ConfigMapping` in `common/messaging` | `OutboxConfig.RelayMode` |
+| Generic outbox channel | single outgoing channel, dynamic topic | `outbox-out` |
 | SmallRye channel | `<entity>-<event>-in` / `-out`, kebab-case | `user-registered-in` |
 | CloudEvents `type` | `<javaPackageStyle>.<entity>.<event>.v<major>` | `com.alva.iam.user.registered.v1` |
 
@@ -158,8 +305,9 @@ Rules:
 ## Checklist for a new event
 
 1. Define `<Event>Payload` in the slice's `dto/` + its JSON Schema in `contracts/`; name the topic and channel per convention.
-2. Producer: `insertOutboxEvent` method on the slice's `Sql`, called from `Handler.execution()` on the shared `Connection`; relay config for `OutboxRelayJob`/Debezium.
-3. `@RegisterForReflection` on the payload; `traceparent` + `traceContext` captured from `Span.current()` at insert time.
-4. Consumer: `<Event>Consumer` in the slice folder delegating to the `Handler`, idempotency inside the transaction, DLQ topic + owner + alert, `@Blocking`.
-5. Contract test: serialize/deserialize round-trip against the JSON Schema.
-6. New error codes registered in `ErrorCatalog` and present in all locale bundles.
+2. Producer: `insertOutboxEvent` method on the slice's `Sql`, called from `Handler.execution()` on the shared `Connection`, storing the resolved `topic`; `process()` passes the returned id to `OutboxDispatcher.dispatchAfterCommit()`.
+3. Relay: set `app.messaging.outbox.relay-mode` per environment and keep `poller.every=off` in every mode but `poller`; register the Debezium routing config where the mode is `debezium`.
+4. `@RegisterForReflection` on the payload; `traceparent` + `traceContext` captured from `Span.current()` at insert time.
+5. Consumer: `<Event>Consumer` in the slice folder delegating to the `Handler`, idempotency inside the transaction, DLQ topic + owner + alert, `@Blocking`.
+6. Contract test: serialize/deserialize round-trip against the JSON Schema, plus identical topic/headers between `direct` and Debezium output.
+7. New error codes registered in `ErrorCatalog` and present in all locale bundles.

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

@@ -1,6 +1,6 @@
 ---
 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. Data access lives in the slice `<Slice>Sql` class with `Connection` as the first parameter of every method (see quarkus-hexagonal-core skill); there are no repositories, DAOs or row-mapper classes.
+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, Flyway, schema migrations, or "query the database" — all persistence code must follow these patterns. Data access lives in the slice `<Slice>Sql` class with `Connection` as the first parameter of every method (see quarkus-hexagonal-core skill); there are no repositories, DAOs or row-mapper classes.
 ---
 
 # SQL Execution Standard: Agroal + Plain JDBC (No ORM)
@@ -116,7 +116,7 @@ public class CreatePartyIndividualHandler {
             UUID partyId = sql.insertParty(conn, request.getTenantId(), "Individual",
                 "Active", request.getCreatedBy());
             sql.insertIndividual(conn, partyId, request.getGivenName(), request.getFamilyName());
-            sql.insertOutboxEvent(conn, partyId, "party", EVENT_TYPE, payloadJson(partyId, request), traceparent());
+            sql.insertOutboxEvent(conn, partyId, "party", EVENT_TYPE, TOPIC, payloadJson(partyId, request), traceparent());
             return partyId;
         } catch (SQLException e) {
             throw SqlStateTranslator.translate("PTY-500-001", e);      // unchecked -> container rolls back
@@ -256,11 +256,44 @@ Every resulting code is registered in `ErrorCatalog` and present in all locale b
 
 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
+## 9. Schema migrations (Flyway — opt-in, disabled by default)
+
+The schema is versioned in git as SQL under `db/` in every environment. **Who applies it is a flag**, because a service is rarely allowed to alter its own schema in production — that is a DBA or pipeline responsibility, and a native binary starting up in a replica set is the worst possible place to run DDL.
+
+```properties
+# STANDARD DEFAULT — the app never touches the schema
+quarkus.flyway.enabled=false
+quarkus.flyway.migrate-at-start=false
+
+# %dev / %test: the app owns a throwaway database, so it may build it
+%dev.quarkus.flyway.enabled=true
+%dev.quarkus.flyway.migrate-at-start=true
+%test.quarkus.flyway.enabled=true
+%test.quarkus.flyway.migrate-at-start=true
+
+quarkus.flyway.locations=db/migration
+quarkus.flyway.baseline-on-migrate=true    # adopting an existing database
+```
+
+| `enabled` | `migrate-at-start` | Effect | Use in |
+|---|---|---|---|
+| `false` | — | Flyway is inert; the schema must already exist | **default**: prod, staging, any DBA-owned database |
+| `true` | `false` | Flyway present, applies nothing at boot; add `validate-at-start=true` to fail fast on a schema drift | environments that want a startup guard without DDL rights |
+| `true` | `true` | The app migrates on boot | `%dev`, `%test`, single-owner sandboxes |
+
+Rules:
+- **`enabled=false` is the default and is written explicitly** in `application.properties` — never left implicit. Turning it on is a deliberate, reviewed change per environment.
+- Migrations live in `db/migration` as `V<n>__<snake_description>.sql` regardless of who runs them. Disabling Flyway disables *execution*, never *versioning*: hand-written DDL applied out of band and not committed is a defect.
+- Migrations must be **N/N-1 compatible** (additive first, destructive in a later release) — with `enabled=false` the schema is applied before the new binary rolls out, so the old code always runs briefly against the new schema.
+- `quarkus.flyway.clean-at-start` is prohibited outside `%test`; `quarkus.flyway.clean-disabled=true` everywhere else.
+- The extension stays in `pom.xml` even when disabled — one binary for every environment, and a runtime flag can't resurrect a dependency that isn't there. Drop `quarkus-flyway` entirely only if no environment migrates at boot; then `db/` is applied exclusively by the pipeline.
+- Cross-cutting tables (`outbox_event`, `processed_event`, `audit_event` — see kafka/observability skills) are ordinary migrations in the same `db/migration` folder, not runtime-created.
+
+## 10. Testing
 
 - `<Slice>Sql` tests: `@QuarkusTest` + Dev Services (Testcontainers Postgres starts automatically — no config). Real SQL against real Postgres; never H2 (dialect lies). Obtain a `Connection` in the test and pass it in, exactly as the `Handler` does.
 - `<Slice>Handler` tests are pure Mockito with a mocked `Sql` — no database (see quarkus-hexagonal-core skill).
-- Flyway migrations run at test start (`quarkus.flyway.migrate-at-start=true`) — tests validate DDL and queries together.
+- Flyway migrations run at test start — `%test` is one of the two profiles where the flag is on (`quarkus.flyway.enabled=true` + `migrate-at-start=true`, see §9), so tests validate DDL and queries together against the same SQL production will receive.
 - Native verification: `@QuarkusIntegrationTest` re-runs the same tests against the binary.
 
 ## Checklist for a new `Sql` method

package/src/bmm-skills/module.yaml

@@ -84,13 +84,6 @@ agents:
     team: software-development
     description: "Test-first discipline (red, green, refactor), 100% pass before review, no fluff all precision. Speaks like a terminal prompt: exact file paths, AC IDs, and commit-message brevity — every statement citable."
 
-  - code: bmad-quarkus-dev
-    name: Elena
-    title: Backend Standards Quarkus Developer
-    icon: "🟢"
-    team: software-development
-    description: "Backend developer standards gatekeeper for Java/Quarkus services -- reviews epics/stories right after they're written and enriches each with hexagonal-architecture layer placement, naming, and whichever persistence/gRPC/Kafka/REST/observability/error-handling conventions apply, before sprint planning and build ever see them. Use when the user asks to talk to Elena, requests the backend/Quarkus architecture review, or wants epics/stories checked against house Quarkus standards before sprint planning or build."
-
   - code: bmad-quarkus-build
     name: Marcus
     title: Senior Quarkus Backend Developer & Build Engineer