@eventmodelers/cli 1.0.44 → 1.0.46

package/stacks/umadb/templates/.claude/skills/build-state-view/SKILL.md

@@ -0,0 +1,338 @@
+---
+name: build-state-view
+authors:
+  - Martin Dilger
+description: >
+  Implement read slices (JPA-backed projections + query method + REST API + tests) that react to
+  events off the shared EventDispatcher subscription, in this project's one established pattern:
+  Query record → JPA entity/repository → @Component Projector implementing SliceEventListener →
+  plain on(event)/handle(query) unit test (no client, no Spring context). Use when implementing a
+  new read slice / projection from a slice.json event model in this project. There is exactly one
+  supported style — do not offer alternatives.
+---
+
+# UmaDB — Read Slice
+
+Grounded in the `AllCustomers` slice (test in `AllCustomersProjectorTest`) — verified, compiled and
+passing under `mvn test`, including the one Testcontainers-based end-to-end test
+(`UmaDbContainerIntegrationTest`) that proves a real `umadb/umadb:0.7.5` server, `EventDispatcher`'s
+live subscription, and this JPA projection all wire together correctly for real.
+
+UmaDB has no read-model/projection concept of its own (no `@EventHandler`, no query bus) — a read
+slice here is entirely this project's own convention, built on the shared `eventstore` package:
+`SliceEventListener` is the interface every projector implements, and `EventDispatcher` (already in
+the root scaffold, already proven — see below) is the ONE shared subscription that fans events out
+to every projector and automation processor in the app. **You do not need to write a new
+subscription or a new Testcontainers test for each read slice** — just implement
+`SliceEventListener` and `EventDispatcher` picks it up automatically as a Spring bean.
+
+## Step 0: Discover Target Project Conventions
+
+> **Comments & description**: each element carries a `comments: string[]` array (board comments)
+> and a `description` field — use them as implementation hints, and resolve consumed comments via
+> `POST <BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/nodes/<nodeId>/comments/<commentId>/resolve`.
+
+Before writing any code, read the target project's `.build-kit/CLAUDE.md`.
+
+**Determine `{basePackage}`** — every code example below is rooted at
+`{basePackage}.slices.{context}.{slicename}`. Resolve `{basePackage}` as documented there.
+
+## Step 1: Ensure Events Exist
+
+Before implementing the read slice, verify that every event the projector reacts to already exists
+in `src/main/java/.../{context}/events/`. If one doesn't, create it first following
+`build-state-change` Step 2 (sealed interface + concrete record + `TYPE` constant + `EventTags`
+entry) — a read slice never invents its own copy of an event another slice already owns.
+
+## Step 2: Implement the Read Slice
+
+If the slice details include `## Scenarios (GWTs)`, use them to derive test cases. GWT format for
+read slices: `Given (events) → Then (information)` — no When. Events in Given tell you which events
+the projector reacts to. The information element in Then describes the expected query result.
+
+If the slice description or comments contain `## Implementation Guidelines`, **follow them**.
+
+A read slice lives in a single package. **Do NOT add Domain/Application/Presentation section
+comments** — those are only for write slices. Read slices are never feature-flagged (no
+`@ConditionalOnProperty`) — unlike write and automation slices.
+
+### Slice package structure
+
+```
+.../slices/{context}/{slicename}/      (i.e. {basePackage}.slices.{context}.{slicename} — see Step 0)
+├── Get{SliceName}.java       ← query record + nested Result
+├── {SliceName}Summary.java   ← read model (projection output shape)
+├── {SliceName}Entity.java    ← JPA entity, package-private
+├── {SliceName}Repository.java   ← package-private JpaRepository
+├── {SliceName}Projector.java ← @Component, implements SliceEventListener
+└── {SliceName}RestApi.java   ← @RestController (if REST chosen)
+```
+
+### Query record
+
+```java
+package {basePackage}.slices.{context}.{slicename};
+
+import java.util.List;
+
+public record Get{SliceName}({filterField type} {filterField}) {
+
+    public record Result(List<{SliceName}Summary> items) {}
+}
+```
+
+No `@Query` annotation exists in this project (UmaDB has nothing like Axon's query bus) — the
+record is just this slice's own input/output shape, called directly (see Step 3's `RestApi`).
+
+### Read model summary
+
+```java
+public record {SliceName}Summary(String field1, String field2) {}
+```
+
+### JPA entity + repository
+
+Projections persist to a database via Spring Data JPA — this is the only supported style. Verified
+against `AllCustomersEntity`/`AllCustomersRepository`:
+
+```java
+package {basePackage}.slices.{context}.{slicename};
+
+import jakarta.persistence.Entity;
+import jakarta.persistence.Id;
+import jakarta.persistence.Table;
+
+@Entity
+@Table(name = "{context}_{slicename}")
+class {SliceName}Entity {
+
+    @Id
+    private String id;
+    private String field1;
+
+    protected {SliceName}Entity() {
+    }
+
+    {SliceName}Entity(String id, String field1) {
+        this.id = id;
+        this.field1 = field1;
+    }
+
+    {SliceName}Summary toSummary() {
+        return new {SliceName}Summary(id, field1);
+    }
+}
+```
+
+```java
+package {basePackage}.slices.{context}.{slicename};
+
+import org.springframework.data.jpa.repository.JpaRepository;
+
+interface {SliceName}Repository extends JpaRepository<{SliceName}Entity, String> {
+}
+```
+
+For filtered queries, add an indexed column and a derived-query method instead of `findAll()` —
+`@Table(indexes = {@Index(...)})` plus `List<{SliceName}Entity> findAllBy{FilterField}(String {filterField})`,
+used from the `@QueryHandler`-equivalent method below. DB-level filtering, not client-side.
+
+### Projector — implements `SliceEventListener`
+
+```java
+package {basePackage}.slices.{context}.{slicename};
+
+import io.umadb.client.Event;
+import {basePackage}.eventstore.EventCodec;
+import {basePackage}.eventstore.SliceEventListener;
+import {basePackage}.slices.{context}.events.{EventName};
+import org.springframework.stereotype.Component;
+
+import java.util.List;
+
+@Component
+public class {SliceName}Projector implements SliceEventListener {
+
+    private final {SliceName}Repository repository;
+
+    public {SliceName}Projector({SliceName}Repository repository) {
+        this.repository = repository;
+    }
+
+    @Override
+    public boolean supports(String eventType) {
+        return {EventName}.TYPE.equals(eventType);
+    }
+
+    @Override
+    public void onEvent(Event event) {
+        on(EventCodec.fromEvent(event, {EventName}.class));
+    }
+
+    /** Called directly (no client, no dispatcher) by {SliceName}ProjectorTest - see Step 4. */
+    public void on({EventName} event) {
+        repository.save(new {SliceName}Entity(event.idField(), event.field1()));
+    }
+
+    public Get{SliceName}.Result handle(Get{SliceName} query) {
+        List<{SliceName}Summary> items = repository.findAll().stream()
+                .map({SliceName}Entity::toSummary)
+                .toList();
+        return new Get{SliceName}.Result(items);
+    }
+}
+```
+
+`supports`/`onEvent` are the only two methods `EventDispatcher` calls — everything else (`on`,
+`handle`) is this projector's own API, called directly by tests and by the REST layer. Multiple
+event types: repeat the `event.type().equals(...)` check in `supports`, and add one more public
+`on(OtherEvent event)` overload.
+
+### Result DTO rules
+
+- If the read model matches the query result **1:1**, expose the summary record directly.
+- If the read model contains fields the caller already knows from the query (e.g. the filter
+  field), omit those from `Result` and map from the projector's internal model.
+
+## Step 3: REST API Exposure (Optional)
+
+Check the target project's convention first.
+
+```java
+package {basePackage}.slices.{context}.{slicename};
+
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+@RestController
+public class {SliceName}RestApi {
+
+    private final {SliceName}Projector projector;
+
+    public {SliceName}RestApi({SliceName}Projector projector) {
+        this.projector = projector;
+    }
+
+    @GetMapping("/api/{context}/{resource}")
+    public Get{SliceName}.Result query() {
+        return projector.handle(new Get{SliceName}());
+    }
+}
+```
+
+Plain Spring MVC, not WebFlux — same reasoning as `build-state-change` Step 5.
+
+## Step 4: Implement the Slice Test
+
+Pure unit test — instantiate the projector directly with a `@DataJpaTest`-provided repository, no
+`UmaDbClient` and no `EventDispatcher` involved. `@DataJpaTest` gives a real (embedded H2, not
+Testcontainers) JPA repository without a full Spring Boot application context:
+
+```java
+package {basePackage}.slices.{context}.{slicename};
+
+import {basePackage}.slices.{context}.events.{EventName};
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.autoconfigure.orm.jpa.DataJpaTest;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+@DataJpaTest
+class {SliceName}ProjectorTest {
+
+    @Autowired
+    private {SliceName}Repository repository;
+
+    private {SliceName}Projector projector;
+
+    @BeforeEach
+    void setUp() {
+        projector = new {SliceName}Projector(repository);
+    }
+
+    @Test
+    @DisplayName("given no events, when query, then empty result")
+    void emptyState() {
+        var result = projector.handle(new Get{SliceName}());
+
+        assertThat(result.items()).isEmpty();
+    }
+
+    @Test
+    @DisplayName("given a {EventName} event, then it appears in the result")
+    void creationEvent() {
+        projector.on(new {EventName}("id-1", "value1"));
+
+        var result = projector.handle(new Get{SliceName}());
+
+        assertThat(result.items()).containsExactly(new {SliceName}Summary("id-1", "value1"));
+    }
+}
+```
+
+Add a `com.h2database:h2` test-scope dependency once, project-wide, if it isn't already there
+(already in the root scaffold's `pom.xml`).
+
+### Mapping GWT Scenarios to Tests
+
+| GWT Element | Test Code |
+|---|---|
+| `NOTHING` in Given | instantiate projector, call `handle(query)` directly |
+| Event in Given | call `projector.on(event)` |
+| Information in Then | `assertThat(result.items()).containsExactlyInAnyOrder(...)` |
+
+## Step 4b: Storyline-Derived Tests (Optional)
+
+`slice.json` may also carry a `storylines[]` array — narrated walkthroughs where the *same* read
+model appears as multiple ordered "beats" across one flow. This is a secondary, supplementary
+source: `specifications[]` (Step 4) remains the primary and default source of test cases. Most
+slices have no `storylines[]` — skip this step silently when there's nothing relevant.
+
+For each storyline, find beats whose `type` is `READMODEL`. Two such beats **adjacent with only
+`EVENT` beat(s) between them** describe one clean, isolable projection test — events = the
+cumulative ordered `EVENT` beats through the intervening event(s), expected result = the later
+`READMODEL` beat's `fields`/`examples`/`expectEmptyList`. Keep these in a `@Nested` class named
+after the storyline's title:
+
+```java
+@Nested
+@DisplayName("Storyline: {storyline.title}")
+class StorylineTests {
+    @Test
+    @DisplayName("after {EventName}, read model shows {expected state}")
+    void beatTransition() {
+        projector.on(new {EventName}(/* fields from the intervening beat(s) */));
+
+        var result = projector.handle(new Get{SliceName}());
+
+        assertThat(result.items()).containsExactly(/* expected shape from the later beat */);
+    }
+}
+```
+
+If a beat between two read-model states is a `COMMAND` rather than an `EVENT`, that half belongs to
+`build-state-change` (its own command-handler test), not here.
+
+## Reference: Proving `EventDispatcher` Itself (already done — don't repeat per slice)
+
+`{basePackage}.eventstore.EventDispatcher` (root scaffold) is the ONE shared live subscription every
+projector and automation reacts through — it's already proven end-to-end against a real
+`umadb/umadb:0.7.5` server via Testcontainers (`UmaDbContainerIntegrationTest`, verified against
+`AllCustomersProjector` + `AutoSubscribeToDefaultCourseProcessor`). A new read slice does not need
+its own Testcontainers test — implementing `SliceEventListener` correctly (Step 2) and unit-testing
+`on(event)`/`handle(query)` directly (Step 4) is sufficient; `EventDispatcher` will deliver real
+events to it in production exactly as it does for the already-verified slices.
+
+## Final Verification: Does the Implementation Match slice.json?
+
+Before marking this slice as `Done`, verify the implementation against slice.json:
+
+- [ ] Every field in the read model / query result definition in slice.json has a field in `{SliceName}Summary` — no invented fields
+- [ ] Every event type in `events[]` has a `type().equals(...)` check in `supports` and a matching `on(...)` overload — no events missed or assumed
+- [ ] Every GWT scenario in `specifications[]` maps to a test case in `{SliceName}ProjectorTest`
+- [ ] If `storylines[]` is present: every adjacent READMODEL↔READMODEL beat pair for this slice's read model (with only EVENT beats between) has a `@Nested` storyline test — or was deliberately skipped as untraceable
+- [ ] No extra query parameters or filter logic were added beyond what slice.json defines
+- [ ] No field names were assumed or guessed — if a field is not in slice.json, it is not in the code

package/stacks/umadb/templates/build-kit/CLAUDE.md

@@ -0,0 +1,94 @@
+# Project Configuration
+
+Read events in `src/main/java/<basePackage>/slices/{context}/events/` to understand the global
+structure - one sealed event interface plus an `EventTags` class per context.
+
+`<basePackage>` in this project's Java code (`src/main/java/<basePackage>/slices/...`) is this
+project's own Java package prefix, not a fixed value - resolve it, in order: (1) the package of the
+project's `@SpringBootApplication` class, (2) the package of any existing slice already under
+`.../slices/{context}/{slicename}/`, (3) only if no code exists yet, Maven's `<groupId>` in
+`pom.xml`. Never hardcode `io.umadb.quickstart` (the shipped quickstart scaffold's package) or any
+other specific package.
+
+## File Structure Constraints
+
+- **Strict Path Limitation**: if not instructed otherwise, only check
+  `src/main/java/<basePackage>/slices/{context}/{slicename}/*.java` and its test counterpart under
+  `src/test/java/...`
+- **Slice Organization**: each feature/domain is a separate slice, flat under its context - no
+  `write`/`read`/`automation` folder layer in between (only the shared `slices/{context}/events/`
+  folder sits alongside slice folders, and automations live under `slices/{context}/automation/{slicename}/`)
+
+## Code Standards
+
+- **Language**: Java 21
+- **Module System**: standard Maven `src/main/java` / `src/test/java` layout
+- **Framework**: Spring Boot (plain MVC, not WebFlux - UmaDB's client API is blocking)
+- **Type Safety**: commands, events, and query/result types are records; decision models and
+  projectors are plain classes
+
+## Development Guidelines
+
+1. Each slice should be self-contained and focused on a specific domain
+2. Maintain clear separation of concerns within each slice
+3. Reuse the shared `eventstore` package's infrastructure (`DecisionModelLoader`, `EventCodec`,
+   `SliceEventListener`, `EventDispatcher`) rather than re-implementing the read/append or
+   subscribe/dispatch loop per slice - see each build skill's own reference to that infrastructure
+
+Ignore case for files and slices in prompts. "CartItems" slice is the same as "cartitems".
+
+Do not change test files unless explicitly instructed.
+
+At the start of every session, read `.build-kit/AGENTS.md` if it exists to load accumulated project learnings.
+
+When starting to work on a slice, invoke the `update-slice-status` skill with `InProgress` status before doing anything else.
+
+## Building a Slice
+
+**CRITICAL: You MUST always use the provided skills to build slices. NEVER implement a slice manually.**
+**ALL fields, event names, command names, and business rules MUST come exclusively from slice.json. Do NOT invent, assume, or guess any field or logic not present in the slice definition.**
+
+**If, at any point below, the slice's requirements are genuinely ambiguous, contradictory, or missing
+a decision you need in order to proceed — do not guess, and do not build anyway.** Invoke the
+`request-feedback` skill with the specific question; it posts the question as a comment on the slice
+and marks it `Blocked`, and you then stop work on this slice for this run. This is an escalation path,
+not a routine step — read `slice.json` and the matching build skill's own instructions fully first;
+most slices are fully specified and need none of this.
+
+When asked to build a slice, always follow this flow:
+
+1. Read the slice definition from `.build-kit/.slices/<context>/<slicename>/slice.json`.
+2. Determine the slice type:
+   - **Translation** — `sliceType === "TRANSLATION"` → read `description` and `notes` from slice.json for hints; default to `/build-automation` if nothing else is specified
+   - **Automation** — `processors` array is non-empty → invoke `/build-automation`
+   - **State-view** — `projections` or `queries` array is non-empty → invoke `/build-state-view`
+   - **State-change** — default (has `commands` / `events`) → invoke `/build-state-change`
+3. Invoke the matching skill and follow its instructions completely. Do not deviate.
+4. **Verify against slice.json**: After the skill completes, check that every command field, event field, and specification in slice.json appears in the implementation. No invented fields — if it is not in slice.json, it must not be in the code.
+5. Run quality checks (`./mvnw compile -q`, then the slice tests only).
+6. If checks pass, commit with `feat: [Slice Name]` and set slice status to `Done`.
+
+After you are done, automatically run the tests for the slice that was edited.
+
+## Example Slice Structure
+
+```
+src/main/java/<basePackage>/slices/
+├── {context}/
+│   ├── events/
+│   │   ├── {Context}Event.java          ← sealed interface every event in this context implements
+│   │   └── EventTags.java               ← "key:value" tag-string constants for this context
+│   ├── {slicename}/                     ← write slice (build-state-change)
+│   │   ├── {SliceName}Command.java
+│   │   ├── {SliceName}Decision.java     ← package-private, mutable
+│   │   ├── {SliceName}CommandHandler.java
+│   │   └── {SliceName}RestController.java   (only if a SCREEN depends on the command)
+│   ├── {slicename}/                     ← read slice (build-state-view)
+│   │   ├── Get{SliceName}.java          ← query record + nested Result
+│   │   ├── {SliceName}Summary.java      ← read model shape
+│   │   ├── {SliceName}Entity.java + {SliceName}Repository.java   ← JPA
+│   │   ├── {SliceName}Projector.java    ← implements SliceEventListener
+│   │   └── {SliceName}RestApi.java
+│   └── automation/{slicename}/          ← automation slice (build-automation)
+│       └── {AutomationName}Processor.java   ← implements SliceEventListener
+```

package/stacks/umadb/templates/build-kit/lib/AGENT.md

@@ -0,0 +1,47 @@
+# Agent Learnings
+
+Patterns and gotchas discovered during task processing. Update this file whenever you encounter something reusable.
+
+## tasks.json
+
+- Tasks are objects with `id`, `createdAt`, and `payload` (a `SliceChangedPayload`).
+- After completing a task, remove it from the array entirely — do not add a status field.
+- Write `[]` to `tasks.json` if the last task is completed.
+
+## SliceChangedPayload fields
+
+```
+event           always "slice:changed"
+organizationId  org UUID or null
+boardId         board UUID
+sliceId         SLICE_BORDER node UUID — use this with /load-slice
+sliceTitle      human-readable slice name (may be null)
+sliceStatus     e.g. "Created", "InProgress", "Done", "Blocked" (may be null)
+timestamp       unix ms when the change was emitted
+```
+
+## Slice files
+
+The realtime agent writes one file per slice on startup and after each `slice:changed` event:
+
+```
+.slices/<context>/<sliceName>/slice.json
+```
+
+- `<context>` is the slice's context value, or `default` if none.
+- `<sliceName>` is the slice title lowercased with spaces removed (e.g. `"Enable User"` → `enableuser`).
+
+These files are always up to date — read them directly before invoking any skill.
+
+## Skill Usage
+
+- Always run `/connect` first to load credentials from `.eventmodelers/config.json` before calling any other skill.
+- `/load-slice sliceId=<uuid>` re-fetches all slices from the API, refreshes the slice files, and returns the requested slice. Use it when you need a guaranteed-fresh view of a specific slice.
+- Read `.slices/<context>/<sliceName>/slice.json` directly when you already know the context and name and the file is recent enough.
+
+## Board API
+
+- The `boardId` and `organizationId` from each payload provide full context — pass them to skills.
+- Node events use `node:created`, `node:changed`, `node:deleted` — always POST to `/api/org/:orgId/boards/:boardId/nodes/events`.
+- Slice metadata (title, status) lives on the SLICE_BORDER node under `meta.sliceStatus` and `meta.title`.
+- `/update-slice-status` rejects moving a slice into a status it's already in — this is a concurrency guard, not a bug. It means another agent already claimed the slice. Treat it as `ALREADY_IN_STATUS`, skip that slice, and move on to the next `Planned` one instead of erroring out.

package/stacks/umadb/templates/build-kit/lib/backend-prompt.md

@@ -0,0 +1,169 @@
+# Ralph Agent Instructions
+
+You are an autonomous coding agent working on a software project. You apply your skills to build software slices. You only work on one slice at a time.
+
+The structure defined in the Project-Skills is relevant.
+
+## Context Boundary (READ FIRST — NON-NEGOTIABLE)
+
+You work within **exactly ONE context at a time** — the one named in `.build-kit/.slices/current_context.json`.
+
+- **ONLY** look for and build slices inside `.build-kit/.slices/<currentContext>/`.
+- **NEVER** read, scan, or build slices from any other context directory, even if it has "Planned" slices, and even if the current context has no work left.
+- A "Planned" slice in a *different* context (e.g. "Rename organization" while you are in "Board Invitations") is **NOT yours to build**. Ignore it completely.
+- If the current context has no "Planned" slice, you are **done for this iteration** — reply `<promise>NO_TASKS</promise>` and stop. Do not go looking elsewhere. The context is only ever changed on the board, never by you.
+
+## Your Task
+
+0. Do not read the entire code base. Focus on the tasks in this description.
+1. Read `.build-kit/.slices/current_context.json` to find the active context name, then read `.build-kit/.slices/<contextName>/index.json`. Every item in status "planned" is a task.
+2. Read the progress log at `progress.txt` (check Codebase Patterns section first)
+3. Make sure you are on the right branch "feature/<slicename>", if unsure, start from main.
+5. Pick the **highest priority** slice where status is **exactly** "Planned" (case insensitive). This becomes your PRD. Set the status "InProgress" in the index.json **and** update the slice status on the eventmodelers board using the `update-slice-status` skill (or MCP if available).
+   **IMPORTANT: Only work on slices with status "Planned" in the CURRENT context. Never pick up a slice that is "InProgress", "Done", "Blocked", "Created", or any other status — even if it looks incomplete. If no slice has status "Planned" in the current context, reply with:**
+   <promise>NO_TASKS</promise> and stop immediately. Do not work on other slices and do not switch to another context.
+   **Claim conflict**: the board rejects the status update if the slice is already in the target status — this is expected: another agent claimed it first, racing you for the same slice. This is NOT an error. Do not stop, do not retry the same slice. Re-read `index.json` (or re-fetch via `load-slice`), pick the next-highest-priority slice still "Planned", and try claiming that one instead. Repeat until a claim succeeds or no "Planned" slice remains, in which case reply `<promise>NO_TASKS</promise>`.
+6. Pick the slice definition from `.build-kit/.slices/<contextName>/<folder>/slice.json` as defined in the prd. Never work on more than one slice per iteration.
+7. A slice can define additional prompts as codegen/backendPrompt. any additional prompts defined in backend are hints for the implementation of the slice and have to be taken into account. If you use the additional prompt, add a line in progress.txt
+7. Define the slice type and load the matching skill:
+   - Write slice (has commands, no processors) → `build-state-change`
+   - Read slice (has readModel / information flow) → `build-state-view`
+   - Translation slice (`sliceType === "TRANSLATION"`) → read `description` and `notes` from slice.json for hints; default to `build-automation` if nothing else is specified
+   - Automation slice (processors-array is not empty) → `build-automation`
+8. Write a short progress one liner after each step to progress.txt
+9. Analyze and Implement that single slice, make use of the skills in the skills directory, but also your previsously collected
+   knowledge. Make a list TODO list for what needs to be done. Also make sure to adjust the implementation according to the json definition. Carefully inspect events, fields and compare against the implemented slice. JSON is the desired state. ATTENTION: A "planned" task can also be just added specifications. So always look at the slice itself, but also the specifications. If specifications were added in json, which are not on code, you need to add them in code.
+10. The slice in the json is always true, the code follows what is defined in the json
+11. slice is only 'Done' if business logic is implemented as defined in the JSON, APIs are implemented, all scenarios in  JSON are implemented in code and it
+    fulfills the slice.json. There must be no specification in json, that has no equivalent in code.
+12. make sure to write the ui-prompt.md as defined if defined in the skill
+13. Run quality checks — it is enough to run the tests for the slice only, not all tests:
+    - Compile: `./mvnw compile -q`
+    - Test:    `./mvnw test -Dtest="<SliceName>*" -q`
+    If the tests for the slice are not yet named predictably, run `./mvnw test -q` and check for failures.
+15. If checks pass, commit ALL changes with message: `feat: [Slice Name]` and merge back to main as FF merge ( update
+    first )
+16. Update the PRD to set `status: Done` for the completed story in index.json **and** update the slice status on the eventmodelers board using the `update-slice-status` skill (or MCP if available).
+17. Append your progress to `progress.txt` after each step in the iteration.
+18. append your new learnings to `.build-kit/AGENTS.md` in a compressed form, reusable for future iterations. Only add learnings if they are not already there.
+19. Finish the iteration.
+
+## Escalating Ambiguity
+
+**If the slice's requirements are genuinely ambiguous, contradictory, or missing a decision you need
+in order to proceed — do not guess, and do not build anyway.** Invoke `/request-feedback` with the
+specific question; it posts the question as a comment on the slice and marks it `Blocked` on the
+board (overriding the `InProgress` set earlier), then stop this iteration without finishing the
+build — reply `<promise>DONE</promise>` as if the iteration's work was to raise the question, not to
+implement the slice. This is an escalation path, not a routine step — read the slice.json and the
+matching build skill's own instructions fully first; most slices are fully specified and need none of
+this.
+
+## Progress Report Format
+
+APPEND to progress.txt (never replace, always append):
+
+```
+## [Date/Time] - [Slice]
+
+- What was implemented
+- Files changed
+- **Learnings for future iterations:**
+  - Patterns discovered (e.g., "this codebase uses X for Y")
+  - Gotchas encountered (e.g., "don't forget to update Z when changing W")
+  - Useful context (e.g., "the evaluation panel is in component X")
+---
+```
+
+The learnings section is critical - it helps future iterations avoid repeating mistakes and understand the codebase
+better.
+
+## Consolidate Patterns
+
+If you discover a **reusable pattern** that future iterations should know, add it to the `## Codebase Patterns` section
+at the TOP of progress.txt (create it if it doesn't exist). This section should consolidate the most important
+learnings:
+
+```
+## Codebase Patterns
+- Example: Use event sourcing aggregate patterns for all state changes
+- Example: Always use @CommandHandler on the aggregate for write slices
+- Example: Export query result types from the slice package
+```
+
+Only add patterns that are **general and reusable**, not story-specific details.
+
+## Update AGENTS.md Files
+
+Before committing, check if any edited files have learnings worth preserving in nearby AGENTS.md files:
+
+1. **Identify directories with edited files** - Look at which directories you modified
+3. **Add valuable learnings that apply to all tasks** to the Agents.md - If you discovered something future developers/agents should know:
+    - API patterns or conventions specific to that module
+    - Gotchas or non-obvious requirements
+    - Dependencies between files
+    - Testing approaches for that area
+    - Configuration or environment requirements
+
+**Examples of good AGENTS.md additions:**
+
+- "When modifying X, also update Y to keep them in sync"
+- "This module uses pattern Z for all API calls"
+- "Tests require the dev server running on PORT 3000"
+- "Field names must match the template exactly"
+
+**Do NOT add:**
+
+- Slice specific implementation details
+- Story-specific implementation details
+- Temporary debugging notes
+- Information already in progress.txt
+- Task specific learnings
+
+Only update AGENTS.md if you have **genuinely reusable knowledge** that would help future work
+
+## Quality Requirements
+
+- ALL commits must pass your project's quality checks
+- Compile: `./mvnw compile -q`
+- Test: `./mvnw test -Dtest="<SliceName>*" -q`
+- Do NOT commit broken code
+- Keep changes focused and minimal
+- Follow existing code patterns
+
+## Skills
+
+Use the provided skills in the skills folder as guidance.
+Update skill definitions if you find an improvement you can make.
+
+## Specifications
+
+For every specification added to the Slice, you need to implement one use executable Specification in Code.
+
+A Slice is not complete if specifications are missing or can´t be executed.
+
+## Stop Condition
+
+**After completing ONE slice, always stop — regardless of whether more slices are Planned.** The ralph loop will invoke you again for the next slice. Never chain multiple slices in one iteration.
+
+If the slice was completed and committed successfully, reply with:
+<promise>DONE</promise>
+
+If no slice has status "Planned" in the current context, reply with:
+<promise>NO_TASKS</promise>
+(Do NOT switch to another context to find work — stop here.)
+
+If ALL slices in the current context are Done, reply with:
+<promise>COMPLETE</promise>
+
+## Important
+
+- If `.build-kit/.eventmodelers/config.json` is absent, skip all platform communication (MCP calls, `update-slice-status`, board sync) and continue working locally.
+- Work on ONE slice per iteration
+- Commit frequently
+- update progress.txt frequently
+- Read the Codebase Patterns section in progress.txt before starting
+
+## When an iteration completes
+
+Use all the key learnings from the progress.txt and update the `.build-kit/AGENTS.md` file with those learnings.