bmad-method-quarkus 1.0.2 → 1.0.3

package/src/bmm-skills/agents/bmad-quarkus-dev/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 event, payload, consumer, publisher and channel naming conventions.
+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).
 ---
 
 # Kafka Messaging Standard (Quarkus + SmallRye Reactive Messaging)
@@ -12,9 +12,9 @@ Extension: `quarkus-messaging-kafka` (SmallRye Reactive Messaging). Native-compa
 ## Topic naming
 
 ```
-<org>.<module>.<entity>.<event-type>.v<major>     # <module> = BC code or service name
-alva.bc05.user.registered.v1
-alva.bc01.subscription.status-changed.v2
+<org>.<module>.<entity>.<event-type>.v<major>     # <module> = semantic module name (see quarkus-hexagonal-core skill)
+alva.iam.user.registered.v1
+alva.tenant.subscription.status-changed.v2
 ```
 
 - Kebab-case segments, past-tense event types.
@@ -27,10 +27,10 @@ Producers emit CloudEvents in **binary mode** (attributes as Kafka headers `ce_*
 
 ```properties
 mp.messaging.outgoing.user-registered.connector=smallrye-kafka
-mp.messaging.outgoing.user-registered.topic=alva.bc05.user.registered.v1
+mp.messaging.outgoing.user-registered.topic=alva.iam.user.registered.v1
 mp.messaging.outgoing.user-registered.cloud-events=true
-mp.messaging.outgoing.user-registered.cloud-events-source=//alva/bc05
-mp.messaging.outgoing.user-registered.cloud-events-type=com.alva.bc05.user.registered.v1
+mp.messaging.outgoing.user-registered.cloud-events-source=//alva/iam
+mp.messaging.outgoing.user-registered.cloud-events-type=com.alva.iam.user.registered.v1
 mp.messaging.outgoing.user-registered.value.serializer=io.quarkus.kafka.client.serialization.ObjectMapperSerializer
 ```
 
@@ -42,9 +42,9 @@ Payload schema:
 
 ## Producing: transactional outbox (mandatory for domain events)
 
-Never publish directly from a use case in the same breath as a DB write — dual-write problem. Standard:
+Never publish to Kafka in the same breath as a DB write — dual-write problem. Standard:
 
-1. Use case (in the SAME JDBC transaction as the state change) inserts into the outbox table.
+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).
 
 Standard outbox table (one per service):
@@ -54,7 +54,7 @@ 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.bc05.user.registered.v1"
+  event_type     VARCHAR(128) NOT NULL,   -- "com.alva.iam.user.registered.v1"
   payload        JSONB        NOT NULL,
   traceparent    VARCHAR(64)  NOT NULL,   -- captured at insert time (W3C Trace Context)
   created_at     TIMESTAMPTZ  NOT NULL DEFAULT now(),
@@ -78,7 +78,22 @@ 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).
 
-The domain/application layer only knows an outbound port `EventPublisher.publish(DomainEvent e)`; the outbox insert is its JDBC adapter, `OutboxEventPublisher` in `infrastructure/messaging`.
+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:
+
+```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());
+        return partyId;
+    } catch (SQLException e) {
+        throw SqlStateTranslator.translate("PTY-500-001", e);
+    }
+}
+```
+
+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.
 
 Fire-and-forget technical messages (metrics, notifications with no consistency requirement) MAY use a direct `Emitter`:
 
@@ -92,17 +107,14 @@ Canonical rules in the quarkus-hexagonal-core skill; messaging specifics:
 
 | Artifact | Convention | Example |
 |---|---|---|
-| Domain event | past tense, no suffix, in `domain/event` | `UserRegistered` |
-| Wire payload DTO | `<Event>Payload`, in `infrastructure/messaging/dto` | `UserRegisteredPayload` |
-| Outbound port | `EventPublisher` (capability, no technology) | |
-| Publisher adapter | `Outbox<Port>` / `Kafka<Port>` | `OutboxEventPublisher` |
-| Consumer | `<Event>Consumer` | `UserRegisteredConsumer` |
-| Outbox relay job | `<Task>Job` | `OutboxRelayJob` |
-| Event ↔ payload mapper | `<Entity>EventMapper` | `UserEventMapper` |
+| Wire payload DTO | `<Event>Payload`, in the producing/consuming slice's `dto/` | `UserRegisteredPayload` |
+| 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` |
 | SmallRye channel | `<entity>-<event>-in` / `-out`, kebab-case | `user-registered-in` |
-| CloudEvents `type` | `<javaPackageStyle>.<entity>.<event>.v<major>` | `com.alva.bc05.user.registered.v1` |
+| CloudEvents `type` | `<javaPackageStyle>.<entity>.<event>.v<major>` | `com.alva.iam.user.registered.v1` |
 
-Keep the domain event (`UserRegistered`) and the wire payload (`UserRegisteredPayload`) as separate classes even when their fields match: the domain event is free to change with the model, while the payload is a published contract versioned by topic. Never annotate the domain event with Jackson or `@RegisterForReflection` — that annotation belongs on the payload.
+`<Event>Payload` is the **only** event class: there is no separate in-memory domain event, because the slice has no domain layer to protect it from. The payload is a published contract versioned by topic — treat a field rename as a breaking change and bump the topic version, never "because the model moved". It carries `@RegisterForReflection` for native. There is no `*EventMapper`: the payload is built in the `Handler`, the same place `getResult()` builds the response.
 
 ## Consuming
 
@@ -110,25 +122,29 @@ Keep the domain event (`UserRegistered`) and the wire payload (`UserRegisteredPa
 @ApplicationScoped
 public class UserRegisteredConsumer {
 
+    @Inject RegisterUserFromEventHandler handler;   // the slice's business logic
+
     @Incoming("user-registered-in")
     @Blocking            // JDBC inside → run on worker thread (or virtual thread)
-    public void on(UserRegisteredPayload payload) {   // wire DTO, not the domain event
-        // 1. idempotency check  2. delegate to use case  3. done
+    public void on(UserRegisteredPayload payload) {
+        handler.process(toRequest(payload));        // idempotency + side effects, one transaction
     }
 }
 ```
 
+The consumer is as thin as a `Resource`: deserialize, convert to the slice's request DTO, call `process()`. **The idempotency check belongs inside `Handler.execution()`**, not here — it must share the transaction with the side effects, and only the Handler owns the `Connection`. For explicit ack/nack, take `Message<UserRegisteredPayload>` and return `message.ack()` / `message.nack(e)`; do not catch `BusinessException` to build your own error response.
+
 ```properties
 mp.messaging.incoming.user-registered-in.connector=smallrye-kafka
-mp.messaging.incoming.user-registered-in.topic=alva.bc05.user.registered.v1
+mp.messaging.incoming.user-registered-in.topic=alva.iam.user.registered.v1
 mp.messaging.incoming.user-registered-in.group.id=${quarkus.application.name}
 mp.messaging.incoming.user-registered-in.auto.offset.reset=earliest
 mp.messaging.incoming.user-registered-in.failure-strategy=delayed-retry-then-dead-letter-queue
-mp.messaging.incoming.user-registered-in.dead-letter-queue.topic=alva.bc05.user.registered.v1.dlq
+mp.messaging.incoming.user-registered-in.dead-letter-queue.topic=alva.iam.user.registered.v1.dlq
 ```
 
 Rules:
-- **Idempotency is mandatory**: `processed_event(consumer_group, event_id)` table checked/inserted in the same transaction as the side effects. Kafka is at-least-once; duplicates WILL happen.
+- **Idempotency is mandatory**: `processed_event(consumer_group, event_id)` checked/inserted through the slice's `Sql` on the same `Connection`, in the same transaction as the side effects. Kafka is at-least-once; duplicates WILL happen.
 - Consumer group = service name; stable across deployments.
 - Failure strategy: bounded retries with delay, then DLQ topic `<topic>.dlq`. DLQ messages keep original headers plus `dead-letter-reason`. A DLQ must have an owner and an alert — never a silent graveyard.
 - Poison-pill safety: deserialization failures also route to DLQ (`...deserialization-failure-handler` or failure strategy), never block the partition.
@@ -141,8 +157,9 @@ Rules:
 
 ## Checklist for a new event
 
-1. Define `<Event>Payload` record + JSON Schema in `contracts/`, name the topic and channel per convention.
-2. Producer: outbox insert in use-case transaction; relay config.
-3. `@RegisterForReflection` on the payload record (never on the domain event).
-4. Consumer(s): idempotency table entry, DLQ topic + alert, `@Blocking` if JDBC.
+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.

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

@@ -1,18 +1,18 @@
 ---
 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.
+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-bean naming conventions for the vertical-slice layout (one span per Handler.process()).
 ---
 
 # 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.
+Every request must be traceable end-to-end: REST → Handler → 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.application.name=iam-users             # becomes service.name
 quarkus.otel.exporter.otlp.endpoint=http://otel-collector:4317
 quarkus.otel.resource.attributes=deployment.environment=${ENV:dev},service.namespace=alva
 
@@ -85,35 +85,43 @@ Stored value (snake_case keys, exactly these):
 { "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:
+Reference implementation. Auditing is cross-cutting, so it is a single capability-named bean in `common/audit` — no port, no adapter pair. It captures the active span itself and takes the caller's `Connection` so the audit row joins the caller's transaction:
 
 ```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>
+// common/audit — capability noun, no technology in the name, no interface
 @ApplicationScoped
-public class JdbcAuditRecorder implements AuditRecorder {
+public class AuditRecorder {
 
-    private final AuditEventRepository repository;
+    private static final String INSERT_AUDIT = """
+        INSERT INTO audit_event (action, entity, entity_id, context)
+             VALUES (?, ?, ?, ?::jsonb)
+        """;
 
-    public JdbcAuditRecorder(AuditEventRepository repository) { this.repository = repository; }
-
-    @Override
-    public void record(String action, String entity, String entityId) {
+    public void record(Connection conn, String action, String entity, String entityId) throws SQLException {
         String traceId = Span.current().getSpanContext().getTraceId();
         String spanId  = Span.current().getSpanContext().getSpanId();
-        JsonObject context = new JsonObject()
+        String context = new JsonObject()
             .put("trace_id", traceId)
-            .put("span_id", spanId);
-        repository.save(action, entity, entityId, context.encode());
+            .put("span_id", spanId)
+            .encode();
+        try (PreparedStatement ps = conn.prepareStatement(INSERT_AUDIT)) {
+            ps.setString(1, action);
+            ps.setString(2, entity);
+            ps.setString(3, entityId);
+            ps.setString(4, context);
+            ps.executeUpdate();
+        }
     }
 }
 ```
 
-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.
+The slice `Handler` calls it from `execution()` on the same `Connection` it already holds, so an audit row can never survive a rolled-back operation:
+
+```java
+audit.record(conn, "CREATE", "party", partyId.toString());
+```
+
+Identifiers are English (`record`, `action`, `entity`), even when the business vocabulary and the UI are Spanish — Spanish belongs in the message bundles, not in class and method names. `*Service` is not used here: under the slice standard that suffix is reserved for `*GrpcService`.
 
 Any code path that writes `audit_event` without populating `context` is non-compliant — flag it in review.
 
@@ -132,15 +140,23 @@ Both values come from `Span.current()` at insert time — never from manual stri
 
 ## Custom spans and attributes
 
-Annotate use cases that matter for diagnosis (not every method):
+Annotate the entry point of each slice — `Handler.process()` — not every method:
 
 ```java
-// application/usecase — RegisterUserService implements RegisterUserUseCase
+// the slice's Handler — one span per business operation
+@Transactional
 @WithSpan("usecase.registerUser")
-public UserId register(@SpanAttribute("user.email.domain") String emailDomain, RegisterUserCommand cmd) { ... }
+public RegisterUserResponseDto process(RegisterUserRequestDto request) {
+    Span.current().setAttribute("user.email.domain", domainOf(request.getEmail()));
+    validate(request);
+    return getResult(execution(request));
+}
 ```
 
-- Span names: `usecase.<verb><Entity>` (lowerCamelCase, matching the use-case method), `outbox.publish`, `job.<name>`.
+- Span names: `usecase.<sliceCamelCase>` (lowerCamelCase). Because a slice is named verb+entity (`register_user`), this is identical to the older `usecase.<verb><Entity>` convention — existing dashboards keep working.
+- **`process()` is the span boundary.** One span per business operation; do not annotate `validate()`/`execution()`/`getResult()` (they are private, so the interceptor would not fire anyway). JDBC spans come free from `quarkus.datasource.jdbc.telemetry=true`.
+- Other span names: `outbox.publish`, `job.<name>`.
+- Attributes are set inside `process()` via `Span.current().setAttribute(...)` — never by adding `@SpanAttribute` parameters, which would change the `process(RequestDto)` single-argument signature that every transport adapter and the Handler contract depend on (see quarkus-hexagonal-core skill).
 - 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.
 
@@ -150,12 +166,12 @@ Canonical class-naming rules live in the quarkus-hexagonal-core skill; these are
 
 | Artifact | Convention | Example |
 |---|---|---|
-| Audit port / adapter | `AuditRecorder` / `Jdbc<Port>` | `AuditRecorder`, `JdbcAuditRecorder` |
+| Audit bean | `AuditRecorder` — one class in `common/audit`, no port | `AuditRecorder` |
 | Trace-id response filter | `<Purpose>Filter` | `TraceIdResponseFilter` |
-| Span name | `usecase.<verb><Entity>`, `outbox.publish`, `job.<name>` | `usecase.registerUser` |
+| Span name | `usecase.<sliceCamelCase>` on `Handler.process()`, `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` | |
+| Metric | `<module>_<entity>_<action>_total` / `_seconds`, snake_case | `iam_user_registrations_total` |
+| Logger | one per class via `Log`/`Logger.getLogger(Xxx.class)` — never a shared `LogUtil`; the Handler's class name already carries the slice | |
 | 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.
@@ -163,7 +179,7 @@ Span, metric and log-field names are a contract with the dashboards — renaming
 ## 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.
+- Custom business metrics: counters/timers via `MeterRegistry`, names `iam_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
@@ -174,7 +190,7 @@ Span, metric and log-field names are a contract with the dashboards — renaming
 
 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.
+3. JDBC telemetry enabled; `audit_event.context` jsonb populated with `trace_id`/`span_id` (+ index) on the Handler's own `Connection`; 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.
+4. Every slice `Handler.process()` annotated `@WithSpan("usecase.<sliceCamelCase>")`; 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-dev/skills/quarkus-openapi-tmforum/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+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 and operationId naming conventions for the vertical-slice layout (the Resource class lives in the slice folder and delegates to the slice Handler; there are no REST mappers).
 ---
 
 # OpenAPI + TM Forum API Standard (Quarkus)
@@ -31,7 +31,7 @@ The raw OpenAPI document at `/q/openapi` may stay enabled in prod behind the gat
 
 ### 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.
+- Base path starts with the module's semantic name (`iam`, `tenant` — see quarkus-hexagonal-core skill, never a `bcNN` code): `/{module}/{context}/{apiName}/v{major}` e.g. `/iam/tmf-api/digitalIdentityManagement/v4`. Major version in path only.
 
 ### Standard operations
 | Operation | Verb | Response |
@@ -57,7 +57,9 @@ No PUT unless the TMF spec defines it. No RPC-ish URLs (`/user/activate`) — st
 
 ## Annotating resources (SmallRye OpenAPI)
 
-DTOs live in `infrastructure/rest/dto` — never annotate domain classes.
+DTOs live in the slice's own `dto/` package (`<slice_folder>/dto/*Dto.java`) — see quarkus-hexagonal-core skill. There is no separate domain class to protect: the DTO **is** the wire contract, so annotate it freely, and keep business logic out of it.
+
+The `Resource` class lives in the slice folder alongside the `Handler` it fronts, and does exactly three things: extract headers/params, call `handler.process(...)`, shape the response. It never catches `BusinessException` (the global handler owns that) and never touches JDBC.
 
 ### Naming
 
@@ -65,55 +67,69 @@ 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` |
+| Resource class | `<Resource>Resource` — matches the TMF resource name, lives in the slice folder | `DigitalIdentityResource` |
+| Response DTO | `<Resource>Dto`, or `${SERVICE_CLASS_PREFIX}ResponseDto` for a slice-specific shape | `DigitalIdentityDto` |
 | Create / update DTO | `<Resource>CreateDto` / `<Resource>UpdateDto` (TMF `X_Create` / `X_Update`) | `DigitalIdentityCreateDto` |
+| Request DTO (non-TMF) | `${SERVICE_CLASS_PREFIX}RequestDto` | `CreatePartyIndividualRequestDto` |
 | 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` |
 
+There is **no `*RestMapper` class** — the DTO↔internal conversion is the `Handler`'s `getResult()` (see quarkus-hexagonal-core skill), and `*Mapper` is a banned suffix. When a TMF spec prescribes `X_Create`/`X_Update`, those names win over the generic `RequestDto`; use the generic form only for non-TMF operations.
+
+**One Resource per TMF resource, or one per slice?** When several slices serve the same TMF path, the default is one `Resource` class per TMF resource that injects each slice's `Handler` — JAX-RS path resolution stays unambiguous and the OpenAPI tag stays clean. One class per slice sharing a base `@Path` also works in Quarkus REST provided no two classes declare the same method+sub-path; the `/q/openapi` snapshot test below is what catches a collision.
+
 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")
+@Path("/iam/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;
-    }
+    @Inject CreateDigitalIdentityHandler createHandler;   // the slice's business logic
+    @Inject FindDigitalIdentityHandler findHandler;
 
     @GET
+    @Blocking
     @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(
+            @HeaderParam("tenantId") String tenantId,
             @QueryParam("fields") String fields,
             @QueryParam("offset") @DefaultValue("0") int offset,
-            @QueryParam("limit") @DefaultValue("20") int limit) { ... }
+            @QueryParam("limit") @DefaultValue("20") int limit) {
+        var query = FilterDigitalIdentityDto.builder()
+            .tenantId(tenantId).fields(fields).offset(offset).limit(limit).build();
+        return RestResponse.ok(findHandler.process(query).getItems());
+    }
 
     @POST
+    @Blocking
     @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());
+    public RestResponse<DigitalIdentityDto> create(@HeaderParam("tenantId") String tenantId,
+                                                   @Valid DigitalIdentityCreateDto dto,
+                                                   @Context UriInfo uri) {
+        dto.setTenantId(tenantId);
+        var created = createHandler.process(dto);              // BusinessException propagates to the global handler
+        return RestResponse.ResponseBuilder
+            .created(uri.getAbsolutePathBuilder().path(created.getId()).build())
+            .entity(created).build();
     }
 }
 ```
 
 Rules:
+- Return `RestResponse<T>` synchronously — typed, so the generated schema is right. Never `Uni`/`Multi`: the `Handler` is blocking JDBC.
+- `@Blocking` (`io.smallrye.common.annotation.Blocking`) on JDBC-backed methods. With a plain return type Quarkus REST already dispatches to a worker thread, so it is redundant today — keep it as an explicit threading contract that survives a later signature change. `@RunOnVirtualThread` is the high-concurrency alternative (see sql skill §7).
+- Extract `tenantId`, `partyId`, `partyRolList`, `language` from headers where the contract requires them and set them on the request DTO before calling `process()`.
+- No `try/catch` around `process()`. Errors travel as `BusinessException` to `GlobalExceptionHandler`, which resolves the localized TMF Error body (see quarkus-error-handling-i18n skill).
 - `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.
+- Bean Validation on DTOs (`@NotNull`, `@Size`) so constraints appear in the schema — *form* only; business rules live in `Handler.validate()`.
 
 ## PATCH implementation (JSON Merge Patch)
 
@@ -121,8 +137,9 @@ Consume `application/merge-patch+json`. Apply merge onto the current DTO represe
 
 ## 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.
+1. TMF spec exists? Copy & trim official OpenAPI into `contracts/`, implement to match.
+2. `<Resource>Resource` class in the slice folder with full annotations + operationIds, `@Blocking`, injecting the slice `Handler`; DTOs in `<slice>/dto` with validation + `@RegisterForReflection`.
+3. Error responses referenced to the shared TMF Error components — and no `try/catch` in the resource.
+4. fields/offset/limit on list operations; `Location` header on create; 201 on create, 204 on delete.
+5. Snapshot test: `/q/openapi` diff against the committed contract (also catches a `@Path` collision between slices).
+6. `@QuarkusTest` + REST Assured covering one success and one localized error body (`Accept-Language: es`).