@eventmodelers/cli 0.0.1

package/stacks/axon/templates/.claude/skills/build-state-change/SKILL.md

@@ -0,0 +1,396 @@
+---
+name: build-state-change
+authors:
+  - Mateusz Nowak
+  - Martin Dilger
+description: >
+  Implement Event Sourcing write slices using Axon Framework 5.1.1 in this project's one established
+  pattern: Command record → mutable decision-model entity (@EventSourced + @EventCriteriaBuilder) →
+  @Component CommandHandler that checks entity state inline → AxonTestFixture unit test (no Spring
+  context). Use when implementing a new write slice / command handler from a slice.json event model in
+  this project. There is exactly one supported style — do not offer alternatives.
+---
+
+# Axon Framework 5 — Write Slice
+
+One pattern only. Directory layout is flat — `src/main/java/.../slices/{context}/{slicename}/`, no
+`write`/`read`/`automation` folder layer in between (only the shared `slices/{context}/events/` folder
+sits alongside slice folders). Every step below is grounded in the `RegisterCustomer` slice
+(`src/main/java/.../foo/register/`, test in
+`src/test/java/.../foo/register/RegisterCustomerDecisionModelTest.java`) and, for the compound-identifier
+case in Step 1, the `SubscribeToCourse` slice (`src/main/java/.../foo/subscribetocourse/`) — both
+verified, compiled and passing under `mvn test` against `io.axoniq.framework:axoniq-framework-bom:5.1.1`.
+
+## Step 0: Read the slice definition
+
+Read `.build-kit/.slices/{context}/{slicename}/slice.json`. Extract, and use **only** what's there:
+
+- `commands[].fields[]` → Command record fields, in order
+- `events[].fields[]` → Event record fields, in order
+- `specifications[]` (GWT scenarios) → one test method per scenario
+- Which command field(s) have `idAttribute: true` — these carry `@TargetEntityId` (see Step 1) and the
+  matching event field(s) carry `@EventTag`
+
+Never invent a field, business rule, or event that isn't in slice.json.
+
+## Step 1: Command
+
+**Exactly one field has `idAttribute: true` in slice.json** — annotate it directly:
+
+```java
+package io.axoniq.quickstart.slices.{context}.{slicename};
+
+import org.axonframework.messaging.commandhandling.annotation.Command;
+import org.axonframework.modelling.annotation.TargetEntityId;
+
+@Command(namespace = "{Context}", name = "{SliceName}", version = "1.0.0")
+public record {SliceName}Command(
+    String field1,
+    @TargetEntityId
+    String idField
+) {}
+```
+
+**Two or more fields have `idAttribute: true`** — Axon only allows the resolved identifier to collapse
+to exactly one distinct non-null value (`AnnotationBasedEntityIdResolver`, package
+`org.axonframework.modelling.annotation`); annotating two fields with different values throws
+`EntityIdResolutionException` at command-dispatch time, not at compile time. **Never annotate more than
+one field directly.** Instead build a compound id record and put `@TargetEntityId` on a derived method —
+verified against the `SubscribeToCourse` slice (`email` + `courseId` both `idAttribute: true`):
+
+```java
+package io.axoniq.quickstart.slices.{context}.{slicename};
+
+public record {SliceName}Id(String field1, String field2) {}
+```
+
+```java
+package io.axoniq.quickstart.slices.{context}.{slicename};
+
+import org.axonframework.messaging.commandhandling.annotation.Command;
+import org.axonframework.modelling.annotation.TargetEntityId;
+
+@Command(namespace = "{Context}", name = "{SliceName}", version = "1.0.0")
+public record {SliceName}Command(String field1, String field2) {
+
+    @TargetEntityId
+    public {SliceName}Id identifier() {
+        return new {SliceName}Id(field1, field2);
+    }
+}
+```
+
+The entity's generic id type becomes `{SliceName}Id` everywhere it's referenced (Step 3's
+`@EventCriteriaBuilder` first parameter, Step 7's `EventSourcedEntityModule.autodetected({SliceName}Id.class, ...)`)
+instead of `String`. `@TargetEntityId` scans both fields and methods on the payload
+(`AnnotationBasedEntityIdResolver.findMembers`), so a method works exactly like a field for this purpose.
+
+## Step 2: Event — only if it doesn't already exist
+
+Check `src/main/java/.../{context}/events/` first; add to the existing sealed/marker interface rather
+than creating a duplicate.
+
+```java
+package io.axoniq.quickstart.slices.{context}.events;
+
+import org.axonframework.eventsourcing.annotation.EventTag;
+import org.axonframework.messaging.eventhandling.annotation.Event;
+
+@Event(namespace = "{Context}", name = "{EventName}", version = "1.0.0")
+public record {EventName}(
+    String field1,
+    @EventTag(key = EventTags.{TAG_CONSTANT})
+    String idField
+) implements {Context}Event {}
+```
+
+Add the tag constant to the context's `EventTags` class if it isn't already there:
+
+```java
+public static final String {TAG_CONSTANT} = "idField";
+```
+
+## Step 3: Decision-model entity
+
+Package-private, mutable field(s) — **not** an immutable `State` record with free-standing
+`decide()`/`evolve()` static methods. One boolean/value field per fact the command handler's rule
+check needs, nothing else.
+
+```java
+package io.axoniq.quickstart.slices.{context}.{slicename};
+
+import io.axoniq.quickstart.slices.{context}.events.{EventName};
+import io.axoniq.quickstart.slices.{context}.events.EventTags;
+import org.axonframework.eventsourcing.annotation.EventCriteriaBuilder;
+import org.axonframework.eventsourcing.annotation.EventSourcingHandler;
+import org.axonframework.eventsourcing.annotation.reflection.EntityCreator;
+import org.axonframework.extension.spring.stereotype.EventSourced;
+import org.axonframework.messaging.core.MessageTypeResolver;
+import org.axonframework.messaging.eventstreaming.EventCriteria;
+import org.axonframework.messaging.eventstreaming.Tag;
+
+@EventSourced
+class {SliceName}DecisionModel {
+
+    public boolean <ruleFlag>;
+
+    @EntityCreator
+    private {SliceName}DecisionModel() {
+    }
+
+    @EventCriteriaBuilder
+    private static EventCriteria resolveCriteria(String idField, MessageTypeResolver messageTypeResolver) {
+        return EventCriteria.havingTags(Tag.of(EventTags.{TAG_CONSTANT}, idField))
+                             .andBeingOneOfTypes(messageTypeResolver, {EventName}.class);
+    }
+
+    @EventSourcingHandler
+    public void on({EventName} event) {
+        this.<ruleFlag> = true;
+    }
+}
+```
+
+**Always write `@EventCriteriaBuilder`. Never rely on bare `@EventSourced(tagKey = "...")`.** A tag-key
+mismatch produces no compiler error and no runtime exception — the entity just silently never loads any
+prior events, so it always looks "fresh" and the business rule never fires. `@EventCriteriaBuilder`'s
+first parameter is always the `@TargetEntityId` type; a second `MessageTypeResolver` parameter is
+resolved automatically from `Configuration` — pass it plus the event class straight into
+`andBeingOneOfTypes(messageTypeResolver, {EventName}.class)`.
+
+**The `MessageTypeResolver` parameter is not optional — don't drop it to save an injection.** It was
+tempting to think `andBeingOneOfTypes(new QualifiedName({EventName}.class))` should work without it,
+since `QualifiedName` has a `Class<?>` constructor. Verified experimentally that it does NOT:
+`QualifiedName(Class<?>)`'s only job is `clazz.getName()` — the raw Java class name
+(`io.axoniq.quickstart.slices.foo.events.CustomerRegistered`) — not the `@Event(namespace, name)` value
+the event was actually appended under (`Foo.CustomerRegistered`). Swapping to it in
+`SubscribeToCourseDecisionModel` as a test made 2 of 3 passing tests fail immediately, silently, with
+no exception pointing at the real cause — the criteria just stopped matching anything, identical in
+effect to a `tagKey` mismatch. `MessageTypeResolver` is what correctly bridges the `@Event` annotation
+to the type Axon actually matches on; there is no annotation-free shortcut. Never hand-type a
+`"Namespace.Name"` string either, and never pass `{EventName}.class.getName()` — both drift silently
+out of sync with the event's `@Event` annotation with no compiler check.
+
+`EventCriteria`/`Tag` live in `org.axonframework.messaging.eventstreaming` in 5.1.1 — not
+`org.axonframework.eventsourcing.eventstore` (that package has no such classes in this version).
+
+**If Step 1 used a compound `{SliceName}Id`** (two or more `idAttribute: true` fields), the first
+parameter here is `{SliceName}Id id` instead of `String idField` — pull the individual values back out
+with `id.field1()`/`id.field2()` for tagging.
+
+**Tag each event type by what THIS decision actually needs checked for it — not uniformly.** When
+multiple event types feed one entity (via `EventCriteria.either(...)`), each branch gets its own tag
+set, chosen per the specific invariant that event type is being loaded to verify. This is context-
+dependent: the same event type can legitimately need a wider or narrower tag set in a different slice
+that reads it for a different rule. Verified worked example — `SubscribeToCourseDecisionModel`, id is
+`SubscriptionId(email, courseId)`, two rules, two different tag scopes on two different event types:
+
+```java
+@EventCriteriaBuilder
+private static EventCriteria resolveCriteria(SubscriptionId id, MessageTypeResolver messageTypeResolver) {
+    return EventCriteria.either(
+        // "is this customer registered at all" — scoped to email only
+        EventCriteria.havingTags(Tag.of(EventTags.EMAIL, id.email()))
+                     .andBeingOneOfTypes(messageTypeResolver, CustomerRegistered.class),
+        // "did this customer already subscribe to THIS course" — scoped to email + courseId
+        EventCriteria.havingTags(Tag.of(EventTags.EMAIL, id.email()), Tag.of(EventTags.COURSE_ID, id.courseId()))
+                     .andBeingOneOfTypes(messageTypeResolver, SubscribedToCourse.class)
+    );
+}
+```
+
+`CustomerRegistered` only needs the `email` tag — "is this customer registered" doesn't involve a
+course. `SubscribedToCourse` needs **both** `email` and `courseId` tags together — the rule is "already
+subscribed to *this* course", not "subscribed to any course", so loading a customer's subscription to a
+*different* course must not satisfy it. This also directly simplifies the entity: narrowing the second
+branch to `email` + `courseId` means the entity only ever sees `SubscribedToCourse` events for this
+exact course, so a `Set<String> subscribedCourseIds` collecting every course is unnecessary — a single
+`boolean alreadySubscribedToThisCourse` set by `@EventSourcingHandler` is enough. Getting the tag scope
+wrong doesn't fail loudly: too-wide a scope silently pulls in unrelated events (correct here only by
+coincidence, e.g. it still worked when courses were checked in Java after the fact) or double-counts;
+too-narrow a scope silently drops events the rule actually needed.
+
+A read-side use case for the *same* `SubscribedToCourse` event (e.g. "how many courses is this customer
+subscribed to") would legitimately query it with `email` only, no `courseId` — the correct tag scope is
+a property of the specific decision/query consuming the event, not a fixed property of the event type
+itself.
+
+## Step 4: Command handler
+
+```java
+package io.axoniq.quickstart.slices.{context}.{slicename};
+
+import io.axoniq.quickstart.slices.{context}.events.{EventName};
+import org.axonframework.messaging.commandhandling.annotation.CommandHandler;
+import org.axonframework.messaging.core.Metadata;
+import org.axonframework.messaging.eventhandling.gateway.EventAppender;
+import org.axonframework.modelling.annotation.InjectEntity;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.stereotype.Component;
+
+@Component
+@ConditionalOnProperty(prefix = "slices.{context}.write", name = "{slicename}.enabled")
+public class {SliceName}CommandHandler {
+
+    @CommandHandler
+    public void handle(
+        {SliceName}Command command,
+        Metadata metadata,
+        @InjectEntity {SliceName}DecisionModel entity,
+        EventAppender eventAppender
+    ) {
+        if (entity.<ruleFlag>) {
+            throw new IllegalStateException("...");
+        }
+        eventAppender.append(new {EventName}(command.field1(), command.idField()));
+    }
+}
+```
+
+`Metadata` is `org.axonframework.messaging.core.Metadata` — **not** `AxonMetadata`, which does not
+exist as a type in this version.
+
+## Step 5: REST endpoint — only if slice.json shows an inbound `SCREEN` dependency on the command
+
+```java
+package io.axoniq.quickstart.slices.{context}.{slicename};
+
+import org.axonframework.messaging.commandhandling.gateway.CommandGateway;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RestController;
+import reactor.core.publisher.Mono;
+
+@RestController
+@ConditionalOnProperty(prefix = "slices.{context}.write", name = "{slicename}.enabled")
+public class {SliceName}RestController {
+
+    private final CommandGateway commandGateway;
+
+    public {SliceName}RestController(CommandGateway commandGateway) {
+        this.commandGateway = commandGateway;
+    }
+
+    @PostMapping("/api/{context}/{resource}")
+    public Mono<ResponseEntity<Void>> handle(@RequestBody {SliceName}RequestBody body) {
+        var command = new {SliceName}Command(body.field1(), body.idField());
+        return Mono.fromFuture(commandGateway.send(command).getResultMessage())
+            .map(ignored -> ResponseEntity.ok().<Void>build())
+            .onErrorResume(e -> Mono.just(ResponseEntity.badRequest().<Void>build()));
+    }
+
+    public record {SliceName}RequestBody(String field1, String idField) {}
+}
+```
+
+If the only inbound dependency is another slice's `AUTOMATION`, skip this step — it calls the
+`CommandGateway` in-process, it doesn't need HTTP.
+
+This project uses WebFlux (`Mono<ResponseEntity<...>>`, not plain `ResponseEntity`) — see
+[references/rest-api-patterns.md](references/rest-api-patterns.md) for the full annotated breakdown and
+a `WebTestClient`-based test shape (this repo has no REST test yet — that file's test is the
+recommended pattern for the first one, not a verified-passing example like the other references).
+
+## Step 6: Feature flag
+
+Every slice component (handler, REST controller) gets `@ConditionalOnProperty(prefix =
+"slices.{context}.write", name = "{slicename}.enabled")` — the entity does not need it. Wire the flag
+in all three places:
+
+- `src/main/resources/application.properties` — `slices.{context}.write.{slicename}.enabled=true`
+- `src/test/resources/application.properties` — `slices.{context}.write.{slicename}.enabled=false`
+- `META-INF/additional-spring-configuration-metadata.json` — add a `{"name": "...", "type":
+  "java.lang.Boolean", "description": "..."}` entry
+
+This flag is irrelevant to the Step 7 test below — that test never boots Spring, so
+`@ConditionalOnProperty` never runs.
+
+## Step 7: Test — `AxonTestFixture`, no Spring context
+
+One-time `pom.xml` addition (no version needed — resolved via the project's existing
+`axoniq-framework-bom` → `axon-framework-bom` import):
+
+```xml
+<dependency>
+    <groupId>org.axonframework</groupId>
+    <artifactId>axon-test</artifactId>
+    <scope>test</scope>
+</dependency>
+```
+
+```java
+package io.axoniq.quickstart.slices.{context}.{slicename};
+
+import io.axoniq.quickstart.slices.{context}.events.{EventName};
+import org.axonframework.eventsourcing.configuration.EventSourcedEntityModule;
+import org.axonframework.eventsourcing.configuration.EventSourcingConfigurer;
+import org.axonframework.messaging.commandhandling.configuration.CommandHandlingModule;
+import org.axonframework.test.fixture.AxonTestFixture;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+class {SliceName}DecisionModelTest {
+
+    private AxonTestFixture fixture;
+
+    @BeforeEach
+    void setUp() {
+        var entityModule = EventSourcedEntityModule
+            .autodetected(String.class, {SliceName}DecisionModel.class);
+        var commandHandlerModule = CommandHandlingModule.named("{SliceName}")
+            .commandHandlers()
+            .autodetectedCommandHandlingComponent(c -> new {SliceName}CommandHandler());
+        var configurer = EventSourcingConfigurer.create()
+            .registerEntity(entityModule)
+            .registerCommandHandlingModule(commandHandlerModule);
+        fixture = AxonTestFixture.with(configurer);
+    }
+
+    @AfterEach
+    void tearDown() {
+        fixture.stop();
+    }
+
+    @Test
+    @DisplayName("given no prior activity, when {sliceName}, then {eventName} emitted")
+    void happyPath() {
+        fixture.given().noPriorActivity()
+               .when().command(new {SliceName}Command("value1", "id-1"))
+               .then().success()
+               .events(new {EventName}("value1", "id-1"));
+    }
+
+    @Test
+    @DisplayName("given <rule already true>, when {sliceName}, then rejected")
+    void ruleViolation() {
+        fixture.given().event(new {EventName}("value1", "id-1"))
+               .when().command(new {SliceName}Command("value2", "id-1"))
+               .then().exception(IllegalStateException.class, "...");
+    }
+}
+```
+
+One test method per GWT scenario in slice.json's `specifications[]`. This works because
+`EventSourcedEntityModule.autodetected(...)` and `...autodetectedCommandHandlingComponent(...)` operate
+directly on the `@EventSourced`/`@Component` classes via reflection — the same classes Spring
+auto-discovers in production also work standalone, with zero `ApplicationContext`, zero
+`@SpringBootTest`.
+
+Fluent API cheat sheet and known gotchas (wrong `EventCriteria`/`Tag` package, a builder method that
+was renamed between AF5 patch versions, `Customization.disableAxonServer()` not existing in 5.1.1):
+see [references/axon-test-fixture-patterns.md](references/axon-test-fixture-patterns.md).
+
+## Final Verification
+
+Before considering the slice done:
+
+- [ ] Every field in slice.json's `commands[]` is in the Command record — no invented fields, none missing
+- [ ] Every field in slice.json's `events[]` is in the Event record — no invented fields, none missing
+- [ ] Every `specifications[]` scenario has a corresponding test method
+- [ ] No business rule exists in the handler that isn't traceable to slice.json's `description`/`comments`
+- [ ] `mvn compile -q`, then run the slice's own tests only
+- [ ] If checks pass, commit with `feat: {Slice Name}` and set slice status to `Done`

package/stacks/axon/templates/.claude/skills/build-state-change/references/axon-test-fixture-patterns.md

@@ -0,0 +1,162 @@
+# AxonTestFixture Patterns (Verified against Axon Framework 5.1.1)
+
+Everything on this page was compiled and run with `mvn test` against
+`io.axoniq.framework:axoniq-framework-bom:5.1.1` (which pulls in
+`org.axonframework:axon-framework-bom:5.1.1`). It supersedes any conflicting claim elsewhere in this
+skill about `@SpringBootTest` / `AxonTestFixture.configSlice(...)` — that method does not exist in
+5.1.1. Ground-truth worked example: `RegisterCustomer` slice in this repo
+s(`src/main/java/.../foo/register/`, test in `src/test/java/.../foo/register/RegisterCustomerDecisionModelTest.java`).
+Slice folders sit directly under their context — `slices/{context}/{slicename}/`, no `write`/`read`/
+`automation` layer in between.
+
+## 0. Add the dependency
+
+`axon-test` is **not** pulled in by `axoniq-spring-boot-starter`. Add it explicitly (no version needed —
+it's managed by the `axoniq-framework-bom` → `axon-framework-bom` import already in the project's `pom.xml`):
+
+```xml
+<dependency>
+    <groupId>org.axonframework</groupId>
+    <artifactId>axon-test</artifactId>
+    <scope>test</scope>
+</dependency>
+```
+
+## 0b. `@EventSourced` (Spring stereotype) works directly with `EventSourcedEntityModule.autodetected(...)`
+
+`org.axonframework.extension.spring.stereotype.EventSourced` is not a plain marker — it aliases its
+attributes onto `org.axonframework.eventsourcing.annotation.EventSourcedEntity` via Spring's
+`@AliasFor` mechanism. `AnnotationBasedEventCriteriaResolver`/`EventSourcedEntityModule.autodetected(...)`
+resolve that alias correctly at runtime even with zero Spring context — verified empirically:
+`EventSourcedEntityModule.autodetected(String.class, RegisterCustomerDecisionModel.class)` succeeded
+against an entity annotated only with the bare `@EventSourced` (no explicit `@EventSourcedEntity`).
+You do **not** need to dual-annotate or swap to `@EventSourcedEntity` just to make the entity
+fixture-testable.
+
+## 1. Key finding: you do NOT need a Spring context to test the entity/handler pair
+
+Production code stays `@EventSourced` (Spring stereotype) entity + `@Component` handler, auto-discovered
+by `SpringEventSourcedEntityLookup` at runtime. The test does **not** have to boot Spring —
+`EventSourcedEntityModule.autodetected(...)` and `CommandHandlingModule...autodetectedCommandHandlingComponent(...)`
+work directly off the annotated classes via reflection, regardless of them also being
+`@Component`/`@EventSourced`-Spring-stereotyped for production wiring. This is dramatically faster than
+`@SpringBootTest` (no `ApplicationContext` startup) and needs zero Spring test slices.
+
+```java
+class RegisterCustomerDecisionModelTest {
+
+    private AxonTestFixture fixture;
+
+    @BeforeEach
+    void setUp() {
+        var entityModule = EventSourcedEntityModule
+            .autodetected(String.class, RegisterCustomerDecisionModel.class);
+        var commandHandlerModule = CommandHandlingModule.named("Register")
+            .commandHandlers()
+            .autodetectedCommandHandlingComponent(c -> new RegisterCustomerCommandHandler());
+        var configurer = EventSourcingConfigurer.create()
+            .registerEntity(entityModule)
+            .registerCommandHandlingModule(commandHandlerModule);
+        fixture = AxonTestFixture.with(configurer);
+    }
+
+    @AfterEach
+    void tearDown() {
+        fixture.stop();
+    }
+
+    @Test
+    @DisplayName("given no prior registration, when register customer, then customer registered emitted")
+    void happyPath() {
+        fixture.given().noPriorActivity()
+               .when().command(new RegisterCustomerCommand("Martin", "test@test.de"))
+               .then().success()
+               .events(new CustomerRegistered("Martin", "test@test.de"));
+    }
+
+    @Test
+    @DisplayName("given customer registered, when register customer with same email, then already registered")
+    void alreadyRegistered() {
+        fixture.given().event(new CustomerRegistered("Martin", "test@test.de"))
+               .when().command(new RegisterCustomerCommand("Max", "test@test.de"))
+               .then().exception(IllegalStateException.class, "Email already registered");
+    }
+}
+```
+
+**Method name note**: in 5.0.1 the fluent builder method was `annotatedCommandHandlingComponent`; it was
+**renamed** to `autodetectedCommandHandlingComponent` in 5.1.x. Use `javap` against the project's actual
+resolved jar before trusting either name in a new project — don't assume the older name still compiles.
+
+`AxonTestFixture.Customization::disableAxonServer` (seen in older AF4-adjacent examples) does **not**
+exist as a method in 5.1.1's `AxonTestFixture.Customization` record — the plain `AxonTestFixture.with(configurer)`
+overload (no customization argument) already runs fully in-memory with no Axon Server connection. Only
+reach for the `UnaryOperator<Customization>` overload (`.asIntegrationTest()`, `.registerFieldFilter(...)`,
+`.registerIgnoredField(...)`) when you actually need one of those specific behaviors.
+
+## 2. Fluent API cheat sheet
+
+```java
+fixture.given().noPriorActivity()                 // no prior events
+fixture.given().event(someEvent)                  // one prior event
+fixture.given().events(e1, e2, ...)                // several prior events
+
+fixture.when().command(someCommand)
+fixture.when().event(someEvent)                    // dispatch via when() also supported
+
+.then().success()                                   // command handler returned normally
+.then().events(expectedEvent1, expectedEvent2)       // exact events emitted (equality via all-fields match)
+.then().exception(IllegalStateException.class)                       // exception type only
+.then().exception(IllegalStateException.class, "Email already registered") // type + exact message
+.then().noEvents()                                   // handler ran, nothing emitted
+```
+
+`given()`/`when()`/`then()` all live on `AxonTestFixture` (`fixture.given()`, `fixture.when()`), chained
+onto the previous phase's return value (`.given()....when()....then()...`), not called repeatedly on
+`fixture` mid-chain.
+
+## 3. `@EventCriteriaBuilder` over bare `tagKey`
+
+**Do not** rely on `@EventSourced(tagKey = "...")` (or the plain `@EventSourcedEntity(tagKey = "...")`)
+for anything beyond the most trivial single-tag case — it silently produces an entity that never loads
+any prior events if the tag key doesn't happen to match by coincidence, and there is no compiler or
+runtime error to catch the mismatch; you only notice when a "should already exist" test unexpectedly
+passes as if the entity were fresh. Prefer an explicit `@EventCriteriaBuilder` static method:
+
+```java
+@EventCriteriaBuilder
+private static EventCriteria resolveCriteria(String email, MessageTypeResolver messageTypeResolver) {
+    return EventCriteria.havingTags(Tag.of(EventTags.EMAIL, email))
+                         .andBeingOneOfTypes(messageTypeResolver, CustomerRegistered.class);
+}
+```
+
+Rules (verified from `AnnotationBasedEventCriteriaResolver`, package `org.axonframework.eventsourcing.annotation`):
+- Must be `static`, must return `EventCriteria` (package `org.axonframework.messaging.eventstreaming`, **not**
+  `org.axonframework.eventsourcing.eventstore` — that package does not contain `EventCriteria`/`Tag` in 5.1.1).
+- First parameter is always the entity's `@InjectEntity`/`@TargetEntityId` identifier type (here `String`).
+- Any additional parameters are resolved as components from the `Configuration` — `MessageTypeResolver` is
+  a valid injectable component and is the type-safe way to restrict the criteria to specific event classes:
+  `andBeingOneOfTypes(MessageTypeResolver, Class<?>...)`. This avoids hand-typing `"Namespace.Name"` strings
+  that can silently drift out of sync with the `@Event(namespace=..., name=...)` annotation on the event
+  record — prefer it over the string-literal `andBeingOneOfTypes(String...)` overload wherever a
+  `MessageTypeResolver` is easily injectable (which it always is, inside an `@EventCriteriaBuilder` method).
+- Only one `@EventCriteriaBuilder` method may exist per distinct identifier parameter type on a given entity.
+
+## 4. Minimal working `pom.xml` diff
+
+```xml
+<dependency>
+    <groupId>org.junit.jupiter</groupId>
+    <artifactId>junit-jupiter</artifactId>
+    <scope>test</scope>
+</dependency>
+<dependency>                                 <!-- add this -->
+    <groupId>org.axonframework</groupId>
+    <artifactId>axon-test</artifactId>
+    <scope>test</scope>
+</dependency>
+```
+
+No other pom changes are required — version resolution comes from the BOM already imported for the
+main `org.axonframework`/`io.axoniq.framework` dependencies.

package/stacks/axon/templates/.claude/skills/build-state-change/references/feature-flag-patterns.md

@@ -0,0 +1,56 @@
+# Feature Flag Patterns
+
+This project's one supported approach: `@ConditionalOnProperty` on the handler and REST controller
+(**not** on the entity — verified against the `RegisterCustomer`, `AllCustomers`, and `NotifyCustomer`
+slices, none of which put the annotation on their entity/projector-internals class). Examples use a
+generic `Ordering` bounded context.
+
+## Annotation on slice components
+
+```java
+// Handler
+@ConditionalOnProperty(prefix = "slices.ordering.write", name = "placeorder.enabled")
+@Component
+public class PlaceOrderCommandHandler { ... }
+
+// REST controller (if applicable)
+@ConditionalOnProperty(prefix = "slices.ordering.write", name = "placeorder.enabled")
+@RestController
+public class PlaceOrderRestController { ... }
+```
+
+## `application.properties` (main — enable by default)
+
+```properties
+slices.ordering.write.placeorder.enabled=true
+slices.ordering.read.getorders.enabled=true
+slices.ordering.automation.notifycustomeronorder.enabled=true
+```
+
+## `application.properties` (test — disable by default)
+
+```properties
+slices.ordering.write.placeorder.enabled=false
+slices.ordering.read.getorders.enabled=false
+slices.ordering.automation.notifycustomeronorder.enabled=false
+```
+
+This only matters for tests that boot a Spring context (`@SpringBootTest`). The `AxonTestFixture`
+unit-test pattern in [axon-test-fixture-patterns.md](axon-test-fixture-patterns.md) never boots Spring,
+so these properties don't affect it either way.
+
+## `META-INF/additional-spring-configuration-metadata.json`
+
+Register each property so IDEs auto-complete and validate it:
+
+```json
+{
+  "properties": [
+    {
+      "name": "slices.ordering.write.placeorder.enabled",
+      "type": "java.lang.Boolean",
+      "description": "Enable/disable the PlaceOrder write slice in the Ordering bounded context."
+    }
+  ]
+}
+```