bmad-method-quarkus 1.0.2 → 1.0.4

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method-quarkus",
-  "version": "1.0.2",
+  "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-error-handling-i18n/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: quarkus-error-handling-i18n
-description: Unified (single) global exception handler and internationalized (i18n) API responses for Quarkus backend services, aligned to TM Forum error schema (TMF630). Use this skill whenever the user mentions exception handling, error responses, ExceptionMapper, error codes, Problem Details, localization, i18n, translations, Accept-Language, message bundles, or when creating/reviewing ANY REST endpoint that can fail — errors and locale handling must always go through this standard, never ad-hoc try/catch in resources. Also defines exception class naming and the English-identifiers/localized-messages rule.
+description: Unified (single) global exception handler and internationalized (i18n) API responses for Quarkus backend services, aligned to TM Forum error schema (TMF630). Use this skill whenever the user mentions exception handling, error responses, ExceptionMapper, error codes, Problem Details, localization, i18n, translations, Accept-Language, message bundles, or when creating/reviewing ANY REST endpoint that can fail — errors and locale handling must always go through this standard, never ad-hoc try/catch in resources. Also defines the single BusinessException type (code + args, never a pre-rendered message), the ErrorCatalog/MessageResolver machinery in common/, and the English-identifiers/localized-messages rule.
 ---
 
 # Unified Exception Handler + i18n Responses (Quarkus, TMF-aligned)
@@ -24,33 +24,42 @@ All error responses use `application/json` with the TMF Error structure (interop
 }
 ```
 
-- `code`: stable, machine-readable, defined in the **domain exception**, format `<MOD>-<HTTP>-<seq>` where `<MOD>` is a short module/domain code (the BC code in DDD projects). Never reworded, never localized.
+- `code`: stable, machine-readable, carried by the thrown `BusinessException`, format `<MOD>-<HTTP>-<seq>` where `<MOD>` is a short uppercase code derived from the semantic module name or its main entity (`IAM`, `USR`, `PTY` — never a `bcNN` inventory code; see quarkus-hexagonal-core skill). It is also the **bundle key**. Never reworded, never localized.
 - `message`: human-readable, **localized** via bundles.
 - `referenceError`: link to error catalog docs.
 - Add `traceId` propagation via response header `X-Trace-Id` (see observability skill), not in the body.
 
-## Exception hierarchy (domain layer, framework-free)
+## One business exception (`common/exception`)
+
+The vertical-slice standard uses a **single** business exception carrying a stable code plus interpolation arguments — not a subclass per error. The subclass hierarchy bought nothing that the code does not already express, and cost one file per error:
 
 ```java
-// domain/exception
-public abstract class DomainException extends RuntimeException {
+// common/exception
+public class BusinessException extends RuntimeException {
     private final String code;          // "USR-404-001"
-    private final Object[] messageArgs; // interpolated into localized message
-    protected DomainException(String code, Object... args) {
-        super(code);
+    private final Object[] messageArgs; // interpolated into the localized message
+    public BusinessException(String code, Object... args) {
+        super(code);                    // super message = the code; the human text is resolved at the edge
         this.code = code;
         this.messageArgs = args;
     }
+    public BusinessException(String code, Throwable cause, Object... args) { ... }
     public String code() { return code; }
     public Object[] messageArgs() { return messageArgs; }
 }
+```
 
-public final class UserNotFoundException extends DomainException {
-    public UserNotFoundException(UserId id) { super("USR-404-001", id.value()); }
-}
+Thrown from the slice `Handler` and nowhere else:
+
+```java
+throw new BusinessException("USR-404-001", userId);
 ```
 
-HTTP status is NOT known by the domain. The mapping code→status lives in the handler via a registry (an enum or properties-driven map in infrastructure).
+**The thrower never formats or translates the message.** A `Handler` that injects a `ResourceBundle` and passes a rendered string silently pins every response to one language, defeating `Accept-Language`. Resolution happens once, at the edge, in `GlobalExceptionHandler` / `GrpcExceptionInterceptor`.
+
+HTTP status is not known by the `Handler` either. The mapping code→status lives in `ErrorCatalog` (`common/error`).
+
+One sibling, not a subclass: `StaleVersionException` (optimistic-lock conflict) is the only other code-carrying exception. It is NOT a `BusinessException` subtype and NOT part of the `PersistenceException` family — a version conflict is a client-actionable 409, not an infrastructure failure hidden behind a 500. It is thrown by the `Handler` when a versioned `UPDATE` returns 0 rows (never by `SqlStateTranslator` — there is no `SQLException` involved) and mapped by its own dedicated mapper below.
 
 ### Naming
 
@@ -58,21 +67,24 @@ Canonical rules in the quarkus-hexagonal-core skill; the error/i18n specifics:
 
 | Artifact | Convention | Example |
 |---|---|---|
-| Domain exception | `<Thing><Problem>Exception`, in `domain/exception` | `UserNotFoundException`, `DuplicateEmailException` |
-| Base class | `DomainException` | |
-| Technical exceptions | `PersistenceException`, `TransientPersistenceException`, `StaleVersionException` | |
-| Single REST handler | `GlobalExceptionHandler` (the only sanctioned `*Handler`) | |
-| gRPC counterpart | `GrpcExceptionInterceptor` | |
+| Business exception | `BusinessException` — one class, in `common/exception` | thrown with `("USR-404-001", id)` |
+| Technical exceptions | `PersistenceException`, `TransientPersistenceException`, `PersistenceTimeoutException`, in `common/exception` | |
+| Concurrency-conflict exception | `StaleVersionException` — standalone, code-carrying (`code + args`, like `BusinessException`), in `common/exception` | thrown with `("PTY-409-001", id)` |
+| SQLState translator | `SqlStateTranslator`, in `common/error` | |
+| Single REST handler | `GlobalExceptionHandler`, in `common/error` | |
+| gRPC counterpart | `GrpcExceptionInterceptor`, in `common/error` | |
 | i18n components | `MessageResolver`, `ErrorCatalog` | |
-| Error DTO | `ErrorDto` | |
+| Error DTO | `ErrorDto` (TMF630 Error shape) | |
 | Bundle files | `messages/errors[_<lang>].properties` | `errors_en.properties` |
 | Bundle key | the error code itself, never a prose key | `USR-404-001` |
 
-Never name an exception after the HTTP status (`NotFoundException`, `BadRequestException`) — the domain does not know about HTTP, and the status is resolved by `ErrorCatalog`. Never shadow a JDK type (`ConcurrentModificationException` → `StaleVersionException`).
+`GlobalExceptionHandler` is no longer "the only sanctioned `*Handler`" — under the slice standard `*Handler` is the business-logic class of every slice (`CreatePartyIndividualHandler`). What stays true is that there is exactly **one** global exception handler per transport, both in `common/error`, and that no `Resource`, `GrpcService` or `Consumer` builds an error response itself.
 
-**Language rule:** class, method and field names are English; the *messages* are localized per bundle, with **English as the default locale** and other languages (es, pt, ...) added per project need. `UserNotFoundException` with a Spanish translation `El usuario {0} no existe.` in `errors_es.properties` is correct — `UsuarioNoEncontradoException` is not.
+Never name an exception after the HTTP status (`NotFoundException`, `BadRequestException`) — the status is resolved by `ErrorCatalog`. Never shadow a JDK type (`ConcurrentModificationException` → `StaleVersionException`).
 
-## The single global handler (infrastructure/rest)
+**Language rule:** class, method and field names are English; the *messages* are localized per bundle, with **English as the default locale** and other languages (es, pt, ...) added per project need. A slice named `create_party_individual` throwing `PTY-400-001`, translated as `El campo ''{0}'' es obligatorio.` in `errors_es.properties`, is correct — a class or key named `crear_persona.campo_obligatorio` is not.
+
+## The single global handler (`common/error`)
 
 Exactly ONE class. Use `@ServerExceptionMapper` (Quarkus REST) — build-time wired, native-friendly:
 
@@ -89,13 +101,27 @@ public class GlobalExceptionHandler {
     }
 
     @ServerExceptionMapper
-    public RestResponse<ErrorDto> map(DomainException e, HttpHeaders headers) {
+    public RestResponse<ErrorDto> map(BusinessException e, HttpHeaders headers) {
         var status = catalog.statusOf(e.code());               // e.g. 404
         var msg = messages.resolve(e.code(), headers, e.messageArgs());
         return RestResponse.status(status,
             ErrorDto.of(e.code(), status, msg));
     }
 
+    @ServerExceptionMapper
+    public RestResponse<ErrorDto> map(StaleVersionException e, HttpHeaders headers) {
+        // optimistic-lock conflict: 409 per catalog, client-visible and localized like a business error
+        var status = catalog.statusOf(e.code());               // 409
+        var msg = messages.resolve(e.code(), headers, e.messageArgs());
+        return RestResponse.status(status, ErrorDto.of(e.code(), status, msg));
+    }
+
+    @ServerExceptionMapper
+    public RestResponse<ErrorDto> map(PersistenceException e, HttpHeaders headers) {
+        // technical failures: 500/503 per catalog, stack trace to logs only
+        ...
+    }
+
     @ServerExceptionMapper
     public RestResponse<ErrorDto> map(ConstraintViolationException e, HttpHeaders headers) {
         // 400, code "GEN-400-001", join violations into localized detail
@@ -114,7 +140,7 @@ public class GlobalExceptionHandler {
 Rules:
 - Catch-all `Exception` mapper is mandatory: internal details/stack traces NEVER reach the client. Log with full context (trace_id lands in the log automatically via MDC).
 - Validation errors (Bean Validation) map to 400 with one generic code + per-field details array.
-- Resources and use cases must NOT catch-and-format errors themselves — throw domain exceptions and let the handler translate.
+- `Resource`, `GrpcService`, `Consumer` and `Handler` classes must NOT catch-and-format errors themselves — throw `BusinessException` with a code and let the handler translate. A `try { ... } catch (BusinessException e) { return Response.status(400)... }` inside a `Resource` is the anti-pattern this skill exists to prevent: it bypasses the catalog, the locale and the trace header.
 - `ErrorDto` is `@RegisterForReflection` (native).
 
 ## i18n resolution from Accept-Language
@@ -135,17 +161,23 @@ quarkus.default-locale=en
 ```properties
 # errors.properties (en, default)
 USR-404-001=User {0} does not exist.
+PTY-400-001=The ''{0}'' field is required.
 GEN-400-001=The request contains invalid data.
 GEN-500-001=Internal error. Contact support with the trace identifier.
 ```
 
+Bundles are **per application, keyed by error code** — not per slice, not keyed by prose. A slice contributes rows to the same files, which is what keeps "every code exists in every locale" a single testable invariant. (`''` escapes a literal apostrophe for `MessageFormat`.)
+
 ```properties
 # errors_es.properties
 USR-404-001=El usuario {0} no existe.
+PTY-400-001=El campo ''{0}'' es obligatorio.
 GEN-400-001=La solicitud contiene datos inválidos.
 GEN-500-001=Error interno. Contacte a soporte con el identificador de traza.
 ```
 
+Quality bar per language — Spanish: formal or infinitive, precise, no vague `Error de validación`. English: direct declarative, no vague `something went wrong`. Same key order in every file so diffs stay readable.
+
 For native: `quarkus.native.resources.includes=messages/*.properties`.
 
 ### Resolver
@@ -175,7 +207,9 @@ Success-path localizable strings (notification texts, report labels) use the sam
 
 ## Checklist when adding a new error
 
-1. Create domain exception extending `DomainException`, named `<Thing><Problem>Exception`, with new code `<MOD>-<HTTP>-<seq>`.
-2. Register code → status/reason in `ErrorCatalog`.
-3. Add the message key to ALL locale bundles (build fails a test if a code is missing in any bundle — write that test once: iterate catalog codes × locales).
-4. Document in the error catalog page referenced by `referenceError`.
+1. Pick the next code `<MOD>-<HTTP>-<seq>` — no new exception class.
+2. Throw `new BusinessException(code, args...)` from the slice `Handler` (`validate()` or `execution()`), with the interpolation args and no rendered text.
+3. Register code → status/reason in `ErrorCatalog`.
+4. Add the message key to ALL locale bundles (a test fails the build if a code is missing in any bundle — write it once: iterate catalog codes × locales).
+5. Document in the error catalog page referenced by `referenceError`, and add the row to the slice `README.md` "Business errors" table.
+6. Assert the code (not the message) in the `HandlerTest`; assert the localized body in the `Resource` `@QuarkusTest`.

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

@@ -1,6 +1,6 @@
 ---
 name: quarkus-grpc-services
-description: Standard for internal microservice-to-microservice communication using gRPC in Quarkus native services — proto conventions, Mutiny services, clients, deadlines, error mapping to domain exceptions, health checks, and native-image setup. Use this skill whenever the user mentions gRPC, protobuf, .proto files, internal service calls, synchronous inter-service communication, service clients, or "call service X from service Y" — internal synchronous calls are ALWAYS gRPC, never internal REST. Includes proto and gRPC adapter/client/mapper naming conventions.
+description: Standard for internal microservice-to-microservice communication using gRPC in Quarkus native services — proto conventions, Mutiny services, clients, deadlines, error mapping to BusinessException codes, health checks, and native-image setup. Use this skill whenever the user mentions gRPC, protobuf, .proto files, internal service calls, synchronous inter-service communication, service clients, or "call service X from service Y" — internal synchronous calls are ALWAYS gRPC, never internal REST. Includes proto and gRPC adapter/client naming conventions for the vertical-slice layout (the GrpcService lives in the slice folder and delegates to the slice Handler; outbound stubs are wrapped by capability-named beans in common/client).
 ---
 
 # gRPC Standard for Inter-Service Communication (Quarkus)
@@ -11,12 +11,12 @@ Extension: `quarkus-grpc` (fully native-compatible; code generation is build-tim
 
 ## Proto conventions
 
-Location: `src/main/proto/`. One package per service/module + major version (the module segment is the BC code in DDD projects, the service name otherwise):
+Location: `src/main/proto/<module>/v<major>/`, one file per capability group, published to the monorepo `contracts/` folder. One proto package per service/module + major version (the module segment is the module's semantic name — `iam`, `customer` — see quarkus-hexagonal-core skill, or the service name):
 
 ```protobuf
 syntax = "proto3";
-package alva.bc05.v1;
-option java_package = "com.alva.bc05.grpc.v1";
+package alva.iam.v1;
+option java_package = "com.alva.iam.grpc.v1";
 option java_multiple_files = true;
 
 service UserService {
@@ -36,27 +36,32 @@ Rules:
 - Proto files are contracts: keep them in a shared `contracts/` module (or a dedicated repo) consumed by both sides; do NOT copy-paste protos between services.
 - Streaming RPCs only with a justified use case (bulk export, watch); default is unary.
 
-## Server (inbound adapter, `infrastructure/grpc`)
+## Server (inbound adapter, in the slice folder)
 
 ```java
 @GrpcService
 public class UserGrpcService implements UserService {   // Mutiny-generated interface
 
-    private final GetUserUseCase getUser;   // inbound port from application layer
-
-    public UserGrpcService(GetUserUseCase getUser) { this.getUser = getUser; }
+    @Inject FindUserHandler findUser;      // the slice's Handler, blocking
 
     @Override
     public Uni<GetUserResponse> getUser(GetUserRequest req) {
-        return Uni.createFrom().item(() -> getUser.byId(new UserId(UUID.fromString(req.getUserId()))))
-            .runSubscriptionOn(Infrastructure.getDefaultWorkerPool())  // JDBC below → worker thread
-            .map(UserGrpcMapper::toResponse);
+        return Uni.createFrom().item(() -> {
+                var request = FindUserRequestDto.builder().userId(req.getUserId()).build();
+                var result = findUser.process(request);           // blocking JDBC
+                return GetUserResponse.newBuilder()
+                    .setUser(User.newBuilder().setId(result.getId()).setEmail(result.getEmail()))
+                    .build();
+            })
+            .runSubscriptionOn(Infrastructure.getDefaultWorkerPool());  // JDBC → worker thread
     }
 }
 ```
 
-- gRPC service = thin adapter: map proto ↔ command/result, delegate to the use case. No business logic.
-- Blocking work (JDBC) either `@Blocking` on the method or explicit worker pool as above.
+- gRPC service = thin adapter: convert proto ↔ DTO, delegate to the slice `Handler`. No business logic, no JDBC, no `Connection`.
+- **Proto ↔ DTO conversion happens inline, inside the `item(() -> ...)` lambda.** There is no `*GrpcMapper` class — `*Mapper` is a banned suffix (see quarkus-hexagonal-core skill).
+- This class and the integration beans in `common/client` are the **only** two places Mutiny is allowed; the ArchUnit rule `reactiveIsQuarantined` enforces it. Never let `Uni`/`Multi` reach a `Handler` or `Sql`.
+- Blocking work (JDBC) either `@Blocking` on the method or the explicit worker pool as above.
 
 ### Naming
 
@@ -68,60 +73,73 @@ Canonical rules in the quarkus-hexagonal-core skill; gRPC specifics:
 | Proto RPC | `<Verb><Entity>` | `GetUser`, `ValidateCredentials` |
 | Proto messages | `<Rpc>Request` / `<Rpc>Response`, one pair per RPC | `GetUserRequest` |
 | Proto fields | `snake_case` | `user_id` |
-| Server adapter | `<ProtoService>GrpcService` | `UserGrpcService` |
-| Client adapter | `Grpc<Port>` — port name from `application/port/out` | `GrpcCredentialsValidator` |
-| Proto ↔ domain mapper | `<Entity>GrpcMapper` | `UserGrpcMapper` |
-| Global error interceptor | `GrpcExceptionInterceptor` | |
-| Client config key | `<module>-<entity>` kebab-case, matching `@GrpcClient` | `bc05-users` |
+| Server adapter | `<ProtoService>GrpcService`, in the slice folder | `UserGrpcService` |
+| Outbound integration bean | capability noun, **no technology**, in `common/client` | `CredentialsValidator` |
+| Global error interceptor | `GrpcExceptionInterceptor`, in `common/error` | |
+| Client config key | `<module>-<entity>` kebab-case, matching `@GrpcClient` | `iam-users` |
+
+`*GrpcService` is the **only** class allowed to end in `Service` under the slice standard — it mirrors the proto service name, which is not ours to rename (ArchUnit rule `serviceSuffixIsReserved`). There is no `Grpc<Port>` client adapter and no `*GrpcMapper`: the outbound bean is named after the capability it provides, and only its internals reveal that gRPC is the transport.
 
-`*GrpcService` is the one place outside `application/usecase` where the `*Service` suffix is allowed — it mirrors the proto service name, which is not ours to rename. The client adapter is never called `UserServiceClient`: it implements a domain-named port, and only the `Grpc` prefix reveals the transport.
-- Separate gRPC server port (default `9000`) or unified with HTTP via `quarkus.grpc.server.use-separate-server=false` — pick one per platform and keep it consistent.
+Separate gRPC server port (default `9000`) or unified with HTTP via `quarkus.grpc.server.use-separate-server=false` — pick one per platform and keep it consistent.
 
-## Error mapping (domain exception → gRPC status)
+## Error mapping (`BusinessException` → gRPC status)
 
-One `ExceptionHandlerProvider`-style mapping, symmetric to the REST unified handler:
+One `ExceptionHandlerProvider`-style mapping, symmetric to the REST unified handler. The status is derived from the code's entry in `ErrorCatalog`, not from the exception class:
 
-| Domain situation | gRPC status |
+| Situation (per `ErrorCatalog`) | gRPC status |
 |---|---|
 | Not found | `NOT_FOUND` |
 | Validation / bad argument | `INVALID_ARGUMENT` |
 | Business rule conflict | `FAILED_PRECONDITION` |
-| Duplicate / concurrency | `ALREADY_EXISTS` / `ABORTED` |
+| Duplicate | `ALREADY_EXISTS` |
+| Stale version / concurrency (`StaleVersionException`) | `ABORTED` |
 | Auth | `UNAUTHENTICATED` / `PERMISSION_DENIED` |
 | Anything unexpected | `INTERNAL` (no details leaked) |
 
-Attach the stable error code in trailers metadata key `error-code` so callers can map back to their own domain exceptions. Implement once as a global gRPC exception interceptor (`GrpcExceptionInterceptor`, the counterpart of `GlobalExceptionHandler` — see quarkus-error-handling-i18n skill); individual services never build `StatusRuntimeException` by hand.
+Attach the stable error code in trailers metadata key `error-code` so callers can map it back through their own `ErrorCatalog`. Implement once as a global gRPC exception interceptor (`GrpcExceptionInterceptor` in `common/error`, the counterpart of `GlobalExceptionHandler` — see quarkus-error-handling-i18n skill); it resolves the localized message the same way, from the request's locale metadata. Individual services never build `StatusRuntimeException` by hand, and no `GrpcService` catches `BusinessException`.
 
-## Client (outbound adapter)
+## Client (outbound integration bean, `common/client`)
 
-Define an outbound port in `application/port/out` (e.g., `CredentialsValidator`); the gRPC client is its adapter:
+A slice `Handler` must never hold a `@GrpcClient` stub: the generated stub returns `Uni`, which would drag Mutiny into the business logic and break the `reactiveIsQuarantined` rule. Wrap it in a capability-named bean that `await()`s internally and exposes plain types:
 
 ```java
+// common/client — named for what it provides, not for how
 @ApplicationScoped
-public class GrpcCredentialsValidator implements CredentialsValidator {
+public class CredentialsValidator {
 
-    @GrpcClient("bc05-users") UserService client;   // Mutiny stub
+    @GrpcClient("iam-users") UserService client;   // Mutiny stub, contained here
 
-    @Override
-    public boolean validate(Credentials c) {
-        return client.validateCredentials(toRequest(c))
+    public boolean validate(String username, String password) {
+        return client.validateCredentials(
+                ValidateCredentialsRequest.newBuilder()
+                    .setUsername(username).setPassword(password).build())
             .map(ValidateCredentialsResponse::getValid)
-            .await().atMost(Duration.ofSeconds(2));
+            .await().atMost(Duration.ofSeconds(2));   // deadline also set in config
     }
 }
 ```
 
+The `Handler` then injects it like any other collaborator:
+
+```java
+@Inject CredentialsValidator credentials;   // returns boolean, knows nothing about gRPC
+```
+
+The bean always lives in `common/client`, even when only one slice calls it today — that is the package the `reactiveIsQuarantined` ArchUnit rule exempts (see quarkus-hexagonal-core skill), and it saves relocating the bean the day a second slice needs it. It is mocked in `HandlerTest` exactly like the `Sql` class.
+
+An interface is warranted only under the core skill's "when to add an interface back" rule — a second real implementation, a cross-module boundary, or a `common/` consumer that must not see the slice.
+
 ```properties
-quarkus.grpc.clients.bc05-users.host=bc05-users.internal
-quarkus.grpc.clients.bc05-users.port=9000
-quarkus.grpc.clients.bc05-users.deadline=2s
+quarkus.grpc.clients.iam-users.host=iam-users.internal
+quarkus.grpc.clients.iam-users.port=9000
+quarkus.grpc.clients.iam-users.deadline=2s
 ```
 
 Rules:
 - **Deadline on every client** (config `deadline` or per-call). No unbounded internal calls, ever — cascading hangs kill native pods just as well.
 - Retries only for idempotent RPCs and only `UNAVAILABLE`/`DEADLINE_EXCEEDED`, with budget — prefer platform/mesh retry policy over hand-rolled loops.
 - TLS/mTLS per platform standard (`quarkus.grpc.clients.*.ssl.*` / mesh-provided).
-- Translate `StatusRuntimeException` back into the caller's domain exceptions at the adapter — gRPC types never cross into application/domain.
+- Translate `StatusRuntimeException` into a `BusinessException` carrying the caller's own error code, inside the integration bean — gRPC types (and `Uni`) never reach a `Handler`. Read the upstream code from the `error-code` trailer and map it through the caller's `ErrorCatalog`.
 
 ## Health & reflection
 
@@ -134,8 +152,9 @@ Tracing is automatic when `quarkus-opentelemetry` is present — `traceparent` p
 
 ## Checklist for a new RPC
 
-1. Proto in shared contracts module, package `vN`, dedicated Request/Response.
-2. Server adapter delegating to a use case; blocking handled explicitly.
-3. Client behind an outbound port, deadline configured.
-4. Error mapping covered by the global interceptor (add new code if needed).
+1. Proto in `src/main/proto/<module>/v<major>/`, published to `contracts/`, dedicated Request/Response pair.
+2. `<ProtoService>GrpcService` in the slice folder delegating to the slice `Handler`; proto ↔ DTO conversion inline; blocking handled by `runSubscriptionOn` or `@Blocking`.
+3. Outbound calls wrapped in a capability-named bean in `common/client` that `await()`s and returns plain types; deadline configured.
+4. Error mapping covered by the global interceptor (register any new code in `ErrorCatalog` + all locale bundles).
 5. Contract check in CI (buf breaking-change detection or equivalent).
+6. No `Uni` outside the `GrpcService` and the integration bean — `reactiveIsQuarantined` proves it.