@eventmodelers/cli 1.0.153 → 1.0.154

package/shared/skills/ui-contract/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: ui-contract
+description: Publish the slice's UI contract (read contract = GET, write/state-change contract = POST) as its own `## UI Contract` section in the slice's MARKDOWN node in the feedback lane, which the slice export carries in `slice.json` `notes[]` — so the UI build kit finds the contract in one lookup instead of parsing the whole note. Called by every build-state-view / build-state-change skill after the endpoint is built. A build kit can override it by shipping its own `ui-contract` skill.
+---
+
+# UI Contract
+
+The UI build kit builds the frontend against what the backend slice **actually exposes**. This skill
+records that as a contract — one per slice, in a fixed, machine-findable place.
+
+> Invoke `connect` first if not already connected (`BOARD_ID`). Prefer `mcp__eventmodelers__*` tools;
+> the REST equivalents are in `learn-eventmodelers-api`.
+>
+> **Override**: a build kit that needs a different contract shape or location ships its own
+> `.claude/skills/ui-contract/SKILL.md`. The kit's copy replaces this one at install time (stack
+> templates are applied after the shared skills). Callers only say "invoke `ui-contract`" — they never
+> restate the format.
+
+## When
+
+At the end of building a slice, **after** the endpoint exists (so the contract describes the real
+route, not the plan), before the final commit:
+
+| Slice type | Contract kind |
+|---|---|
+| `STATE_VIEW` (READMODEL) | **read** — `GET` |
+| `STATE_CHANGE` (COMMAND) | **write** — `POST` (a state change) |
+| `AUTOMATION` | none — no UI counterpart, skip |
+
+## Step 1 — Derive the contract from the built endpoint
+
+Never copy from the plan — the contract describes what was built.
+
+1. **Use the source the stack names.** If the calling `build-state-view` / `build-state-change`
+   skill's `## UI Contract` section points to a more authoritative source for this stack (for example a
+   machine-readable API description it already maintains), derive from that, mechanically.
+2. **Otherwise read the endpoint's route/handler code**: method, path, parameter and field names,
+   success status, and the error codes/statuses the handler really returns.
+3. Field `type` / `optional` / `example` come from the `slice.json` element fields.
+4. **Cross-check against `slice.json`**: the `body` / `response.fields` names must equal the command's /
+   read model's `fields[]`. A mismatch is an implementation bug — fix the code, don't publish a
+   contract that disagrees with `slice.json`.
+
+**Read contract** (`kind: "read"`):
+
+```json
+{
+  "kind": "read",
+  "slice": "<slice title>",
+  "sliceId": "<SLICE_BORDER node id>",
+  "readModel": "<READMODEL title>",
+  "method": "GET",
+  "path": "/api/<...>",
+  "pathParams": [{ "name": "customerId", "type": "UUID" }],
+  "queryParams": [{ "name": "page", "type": "Int", "optional": true }],
+  "response": {
+    "cardinality": "Single | List",
+    "fields": [{ "name": "status", "type": "String", "optional": false, "example": "active" }]
+  },
+  "errors": [{ "status": 404, "code": "not_found", "when": "no row for this id" }]
+}
+```
+
+**Write contract** (`kind: "write"`):
+
+```json
+{
+  "kind": "write",
+  "slice": "<slice title>",
+  "sliceId": "<SLICE_BORDER node id>",
+  "command": "<COMMAND title>",
+  "method": "POST",
+  "path": "/api/<...>",
+  "pathParams": [],
+  "body": [{ "name": "itemId", "type": "UUID", "optional": false, "example": "..." }],
+  "response": { "status": 200, "body": [] },
+  "errors": [{ "status": 400, "code": "snake_case_code", "when": "business rule violated" }]
+}
+```
+
+Keep it to what a UI needs — no internal details (no table names, no auth plumbing beyond "requires bearer token" if `security` is set).
+
+## Step 2 — Write the `## UI Contract` section into the slice's MARKDOWN node
+
+1. **Find the node, creating whatever is missing** — never skip or fail because it doesn't exist yet:
+   1. `get_board_outline { boardId, chapterId }` → locate the slice's column and the chapter's
+      `feedback` lane. **No feedback lane** → create it: `add_lane { boardId, timelineId, lanes: [{ type: "feedback", label: "Notes" }] }`
+      (returns the `laneId`; a feedback lane sorts after the spec lane automatically).
+   2. Look for a `markdown` node in the feedback lane in the slice's column. **None** → create it with a
+      `node:created` event through `submit_node_events` (not `place_element` / cell-drop):
+      `{ "id": "<fresh uuid>", "eventType": "node:created", "nodeId": "<fresh uuid>", "chapterId": "<chapterId>",
+      "cellId": "<feedbackRowId>-<columnId>", "meta": { "type": "MARKDOWN", "title": "<slice title>",
+      "description": "## UI Contract\n\n…" } }` — the new node's body is just the section in the format of item 3 below.
+2. **Upsert only the section** (skip the read when you just created the node): read the node once (`get_node`), then replace the text from the
+   `## UI Contract` heading to the next `## ` heading (or end of file) — or append it when absent.
+   Leave every other section untouched. Write back `meta.description` via a `node:changed` event
+   (`submit_node_events`; the content lives in `description`, never `content`).
+3. **Section format** — exactly this, so it can be extracted with a single match:
+
+````markdown
+## UI Contract
+
+**READ** `GET /api/customers/{customerId}/reservation` — <one-line purpose>
+
+| Part | Name | Type | Optional | Example |
+|---|---|---|---|---|
+| path | customerId | UUID | no | … |
+| response | status | String | no | active |
+
+```json ui-contract
+{ ...the Step 1 JSON, verbatim... }
+```
+````
+
+The table is for humans; the fenced block whose info string is `ui-contract` is the single
+machine-readable source. Both must say the same thing.
+
+## Step 3 — Nothing else to write
+
+The board is the single source. The slice export (`fetch` / `get_slice_data`, full projection) carries
+every MARKDOWN node of the slice's column as a plain string in `slice.json` `notes[]` (the
+`outline` / `fields` / `specs` projections leave `notes` out). The UI build kit therefore needs no
+extra file and no board call.
+
+## Step 4 — Completion status: `Handover` instead of `Done`
+
+A slice with a UI is only finished once the UI kit has built its half. Whether this build kit hands
+over is decided per run, in this order: the task request's `Handover: on|off` line (authoritative — the
+runner resolves `run --handover` over the project setting), else `"handover": true` in
+`.eventmodelers/config.json` (saved by `init --handover` / `eventmodelers config --handover on|off`).
+
+- **On** — the build kit's "set the slice to `Done`" for a STATE_VIEW / STATE_CHANGE slice means
+  **`Handover`** instead: after the contract is published and the commit/merge succeeded, via
+  `update-slice-status` (mirrored in the local `index.json`). The UI kit claims `Handover` slices and sets
+  `Done` when its UI is built.
+- **Off / unset** — nothing changes: `Done`.
+- Automations and translations have no UI → always `Done`.
+
+## How the UI build kit looks the contract up
+
+1. In the slice's `slice.json`, take the `notes[]` entry that contains a `## UI Contract` heading.
+   Ignore every other entry.
+2. In that entry, take the fenced block whose info string is `ui-contract` (```` ```json ui-contract ````)
+   and parse just that JSON. Ignore the rest of the note.
+3. No such entry → the backend slice isn't built yet, or the slice wasn't re-fetched since; re-fetch
+   once, and if still absent build against `slice.json` and note the assumption.
+
+## Re-running
+
+Idempotent: a rebuilt slice overwrites its own section; it never duplicates the
+section and never touches other sections of the note.

package/shared/skills/update-slice-status/SKILL.md

@@ -23,8 +23,10 @@ Valid status values (case-sensitive):
 | Value | Meaning |
 |-------|---------|
 | `Created` | Default — slice has been created but not started |
-| `Planned` | Work is planned |
+| `Ready` | Modeling is done — specified and ready to be planned for implementation |
+| `Planned` | Work is planned — queued for the backend build kit |
 | `InProgress` | Work is actively in progress |
+| `Handover` | Backend built and its UI contract published (`## UI Contract` in the slice's markdown note) — queued for the UI build kit |
 | `Review` | Ready for review |
 | `Done` | Completed |
 | `Blocked` | Blocked by something |

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

@@ -435,6 +435,12 @@ EVENT→READMODEL beats) belongs to `build-state-view`'s own storyline step, sin
 touches a projector. If the beat immediately after the command isn't an EVENT, don't force a test —
 leave it undocumented rather than fabricating an assertion.
 
+## UI Contract
+
+Once the command endpoint is built, invoke the `ui-contract` skill (write contract, `POST`): it publishes
+the endpoint's contract as the `## UI Contract` section of the slice's feedback-lane markdown node, which the slice export then carries in `slice.json` `notes[]`. Do not restate the format here — the skill owns it
+(a build kit may override it).
+
 ## Final Verification
 
 Before considering the slice done:

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

@@ -319,6 +319,12 @@ class {SliceName}ProjectorTest {
 - **Assert with full objects**: Use `containsExactlyInAnyOrder(new Summary(...))` rather than
   field-by-field assertions — catches serialization mismatches.
 
+## UI Contract
+
+Once the read endpoint is built, invoke the `ui-contract` skill (read contract, `GET`): it publishes
+the endpoint's contract as the `## UI Contract` section of the slice's feedback-lane markdown node, which the slice export then carries in `slice.json` `notes[]`. Do not restate the format here — the skill owns it
+(a build kit may override it).
+
 ## Final Verification: Does the Implementation Match slice.json?
 
 Before marking this slice as `Done`, verify the implementation against slice.json:

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

@@ -55,7 +55,7 @@ When asked to build a slice, always follow this flow:
 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. This applies even when the slice was previously `Done` and reappears as `Planned` — never dismiss a mismatch as "already implemented" or harmless drift; diff slice.json against the code field by field and update the code to match every change.
 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`.
+6. If checks pass, commit with `feat: [Slice Name]` and set slice status to `Done`. For STATE_VIEW/STATE_CHANGE slices when `handover` is enabled the status to set is `Handover`, not `Done` — see the `ui-contract` skill, Step 4.
 
 After you are done, automatically run the tests for the slice that was edited.
 

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

@@ -36,14 +36,14 @@ You work within **exactly ONE context at a time** — the one named in `.build-k
 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
+12. Invoke the `ui-contract` skill for STATE_VIEW / STATE_CHANGE slices (publishes the UI Contract section to the slice's feedback-lane markdown node)
 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).
+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). For STATE_VIEW/STATE_CHANGE slices when `handover` is enabled the status to set is `Handover`, not `Done` — see the `ui-contract` skill, Step 4.
 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.

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

@@ -41,3 +41,15 @@ TODO — file layout, naming conventions, framework idioms, how the handler/proj
 ## Quality gate
 
 TODO — this stack's build command and how to run only this slice's tests (not the full suite).
+
+## UI Contract
+
+Once the command endpoint is built, invoke the `ui-contract` skill (write contract, `POST`): it publishes the contract
+as the `## UI Contract` section of the slice's feedback-lane markdown node, which the slice export then carries in `slice.json` `notes[]`. Do not restate the format here — the skill owns it.
+
+TODO — **Source for this stack:** say where the contract is derived from. If your stack maintains a
+machine-readable API description (OpenAPI, GraphQL schema, protobuf, ...), name it here and put the
+mapping to the contract keys in a reference file (see `ui-contract-from-openapi.md` in
+`stacks/node/templates/.claude/skills/build-state-change/references/`). If it has none, delete this
+line — the skill then reads the endpoint's route/handler code. If your UI needs a different contract
+shape or location, ship your own `.claude/skills/ui-contract/SKILL.md`; it replaces the shared one.

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

@@ -40,3 +40,15 @@ TODO — file layout, naming conventions, framework idioms, how the handler/proj
 ## Quality gate
 
 TODO — this stack's build command and how to run only this slice's tests (not the full suite).
+
+## UI Contract
+
+Once the read endpoint is built, invoke the `ui-contract` skill (read contract, `GET`): it publishes the contract
+as the `## UI Contract` section of the slice's feedback-lane markdown node, which the slice export then carries in `slice.json` `notes[]`. Do not restate the format here — the skill owns it.
+
+TODO — **Source for this stack:** say where the contract is derived from. If your stack maintains a
+machine-readable API description (OpenAPI, GraphQL schema, protobuf, ...), name it here and put the
+mapping to the contract keys in a reference file (see `ui-contract-from-openapi.md` in
+`stacks/node/templates/.claude/skills/build-state-change/references/`). If it has none, delete this
+line — the skill then reads the endpoint's route/handler code. If your UI needs a different contract
+shape or location, ship your own `.claude/skills/ui-contract/SKILL.md`; it replaces the shared one.

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

@@ -45,7 +45,7 @@ When asked to build a slice, always follow this flow:
 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. This applies even when the slice was previously `Done` and reappears as `Planned` — never dismiss a mismatch as "already implemented" or harmless drift; diff slice.json against the code field by field and update the code to match every change.
 5. Run quality checks (TODO: this stack's build + test commands), then the slice tests only.
-6. If checks pass, commit with `feat: [Slice Name]` and set slice status to `Done`.
+6. If checks pass, commit with `feat: [Slice Name]` and set slice status to `Done`. For STATE_VIEW/STATE_CHANGE slices when `handover` is enabled the status to set is `Handover`, not `Done` — see the `ui-contract` skill, Step 4.
 
 After you are done, automatically run the tests for the slice that was edited.
 
@@ -55,3 +55,10 @@ TODO — a short tree showing where one slice's files land, e.g.:
 ```
 TODO
 ```
+
+## UI Contract
+
+`build-state-view` and `build-state-change` end by invoking the shared `ui-contract` skill (publishes the
+slice's read/write contract for the UI build kit). Decide for your stack where it is derived from — see
+the `UI Contract` section of those two skills — or override the skill entirely by shipping
+`.claude/skills/ui-contract/SKILL.md`.

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

@@ -30,10 +30,10 @@ You work within **exactly ONE context at a time** — the one named in `.build-k
 9. Analyze and Implement that single slice, making use of the skills in the skills directory plus your previously collected knowledge. Make a TODO list for what needs to be done, and 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
+12. Invoke the `ui-contract` skill for STATE_VIEW / STATE_CHANGE slices (publishes the UI Contract section to the slice's feedback-lane markdown node)
 13. Run quality checks — TODO: your stack's build command, TODO: your stack's test command (slice-scoped only; do not run all tests).
 14. If checks pass, commit ALL changes with message: `feat: [Slice Name]` and merge back to main as FF merge (update first)
-15. 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).
+15. 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). For STATE_VIEW/STATE_CHANGE slices when `handover` is enabled the status to set is `Handover`, not `Done` — see the `ui-contract` skill, Step 4.
 16. Append your progress to `progress.txt` after each step in the iteration.
 17. 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.
 18. Finish the iteration.

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

@@ -101,6 +101,12 @@ After the commit, invoke `/record-evidence`: it writes this slice's element →
 
 ---
 
+## UI Contract
+
+Once the command endpoint is built, invoke the `ui-contract` skill (write contract, `POST`): it publishes
+the endpoint's contract as the `## UI Contract` section of the slice's feedback-lane markdown node, which the slice export then carries in `slice.json` `notes[]`. Do not restate the format here — the skill owns it
+(a build kit may override it).
+
 ## Final Verification: Does the Implementation Match slice.json?
 
 - [ ] Every command field is received and used (validated, persisted or passed on)

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

@@ -105,6 +105,12 @@ After the commit, invoke `/record-evidence`: it writes this slice's element →
 
 ---
 
+## UI Contract
+
+Once the read endpoint is built, invoke the `ui-contract` skill (read contract, `GET`): it publishes
+the endpoint's contract as the `## UI Contract` section of the slice's feedback-lane markdown node, which the slice export then carries in `slice.json` `notes[]`. Do not restate the format here — the skill owns it
+(a build kit may override it).
+
 ## Checklist
 
 - [ ] Every read model field is returned, sourced from where its feeding event's data is persisted

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

@@ -33,11 +33,11 @@ You work within **exactly ONE context at a time** — the one named in `.build-k
 9. Analyze and Implement that single slice, making use of the skills in the skills directory plus your previously collected knowledge. Make a TODO list for what needs to be done, and 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
+12. Invoke the `ui-contract` skill for STATE_VIEW / STATE_CHANGE slices (publishes the UI Contract section to the slice's feedback-lane markdown node)
 13. Run the quality checks listed in `.build-kit/ARCHITECTURE.md` — build/compile, then only the tests touched by this slice (do not run all tests).
 14. If checks pass, commit ALL changes with message: `feat: [Slice Name]` and merge back to main as FF merge (update first)
 15. Invoke `/record-evidence` to write the implementation evidence (element → code mapping, files, specification → test mapping, seams, assumptions, commit) as a note into the slice's column, in the chapter's `Implementation` feedback lane.
-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).
+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). For STATE_VIEW/STATE_CHANGE slices when `handover` is enabled the status to set is `Handover`, not `Done` — see the `ui-contract` skill, Step 4.
 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.

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

@@ -404,6 +404,12 @@ EVENT→READMODEL beats) belongs to `build-state-view`'s own storyline step. If
 after the command isn't an EVENT, don't force a test — leave it undocumented rather than fabricating an
 assertion.
 
+## UI Contract
+
+Once the command endpoint is built, invoke the `ui-contract` skill (write contract, `POST`): it publishes
+the endpoint's contract as the `## UI Contract` section of the slice's feedback-lane markdown node, which the slice export then carries in `slice.json` `notes[]`. Do not restate the format here — the skill owns it
+(a build kit may override it).
+
 ## Final Verification
 
 Before considering the slice done:

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

@@ -379,6 +379,12 @@ If a beat between two read-model states is a `COMMAND` rather than an `EVENT`, t
 half. If a storyline segment involves a `SCREEN`/other untraceable beat, don't force a test — leave it
 undocumented rather than fabricating an assertion.
 
+## UI Contract
+
+Once the read endpoint is built, invoke the `ui-contract` skill (read contract, `GET`): it publishes
+the endpoint's contract as the `## UI Contract` section of the slice's feedback-lane markdown node, which the slice export then carries in `slice.json` `notes[]`. Do not restate the format here — the skill owns it
+(a build kit may override it).
+
 ## Final Verification: Does the Implementation Match slice.json?
 
 Before marking this slice as `Done`, verify the implementation against slice.json:

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

@@ -94,7 +94,7 @@ When asked to build a slice, always follow this flow:
    reappears as `Planned` — never dismiss a mismatch as "already implemented" or harmless drift; diff
    slice.json against the code field by field and update the code to match every change.
 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`.
+6. If checks pass, commit with `feat: [Slice Name]` and set slice status to `Done`. For STATE_VIEW/STATE_CHANGE slices when `handover` is enabled the status to set is `Handover`, not `Done` — see the `ui-contract` skill, Step 4.
 
 After you are done, automatically run the tests for the slice that was edited.
 

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

@@ -36,14 +36,14 @@ You work within **exactly ONE context at a time** — the one named in `.build-k
 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
+12. Invoke the `ui-contract` skill for STATE_VIEW / STATE_CHANGE slices (publishes the UI Contract section to the slice's feedback-lane markdown node)
 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).
+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). For STATE_VIEW/STATE_CHANGE slices when `handover` is enabled the status to set is `Handover`, not `Done` — see the `ui-contract` skill, Step 4.
 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.

package/stacks/modeling-kit/templates/.claude/skills/analyze-existing-model/SKILL.md

@@ -39,7 +39,7 @@ Save the full slice list. Count total slices and group by status:
 
 | Status values |
 |---------------|
-| `Created`, `Planned`, `InProgress`, `Review`, `Done`, `Blocked`, `Assigned`, `Informational` |
+| `Created`, `Ready`, `Planned`, `InProgress`, `Handover`, `Review`, `Done`, `Blocked`, `Assigned`, `Informational` |
 
 ---
 

package/stacks/modeling-kit/templates/.claude/skills/attributes/SKILL.md

@@ -122,7 +122,7 @@ report `sliceStatus`. Read it now, once: `mcp__eventmodelers__get_board_outline
 gives every column a `sliceStatus` when a slice spans it. Look up each chain node's column.
 
 - **Every node writable** (`Created`, or no `sliceStatus`) → continue with Step 4.
-- **Any node in a column with another status** (`Done`, `Review`, `InProgress`, `Blocked`, `Planned`, `Assigned`,
+- **Any node in a column with another status** (`Done`, `Review`, `Handover`, `InProgress`, `Blocked`, `Ready`, `Planned`, `Assigned`,
   `Informational`) → **do not write that node.** If the task text says the person already confirmed changing
   that locked slice (*"The person confirmed changing the locked slice '…'"*, with an `origin_message_id`), you may
   change those elements and only those. Otherwise write **nothing** — not even the nodes that are writable, the

package/stacks/modeling-kit/templates/kit/CLAUDE.md

@@ -84,8 +84,8 @@ header's `standalone=on|off` tells you which mode they come in.
 
 At the start of every session, read `.agent-modeling-kit/AGENTS.md` if it exists to load accumulated learnings.
 
-**Only touch elements in a slice whose status is `Created` — unless the person explicitly confirmed it.** Every other status — `Planned`,
-`Assigned`, `InProgress`, `Review`, `Blocked`, `Done`, `Informational` — means someone is working
+**Only touch elements in a slice whose status is `Created` — unless the person explicitly confirmed it.** Every other status — `Ready`, `Planned`,
+`Assigned`, `InProgress`, `Handover`, `Review`, `Blocked`, `Done`, `Informational` — means someone is working
 on that slice: read it for context, but never change, move, rename or delete its elements, and
 never add scenarios, fields or examples to them. An element in no slice at all is not locked.
 `get_board_outline` returns `sliceStatus` per column (`get_nodes` does not carry it), so the
@@ -312,8 +312,8 @@ for it. Instead:
    - a **screen idea** in the conversation ("what could that screen look like?") → `screen`, a sandboxed HTML mock-up in the chat; putting a screen on the board is `/html-screen` work;
    - **where one piece of information comes from and where it is used** → `dataJourney` (the `/data-journey` skill);
    - **who does what with which work object, per chapter** → an `svg` domain story (the `/domain-story` skill);
-   - **"draw" / "sketch" / "diagram" something** (a UML diagram, a flow, a class model) → a snippet in the chat (`svg`, or a
-     `code` block with Mermaid/PlantUML/ASCII), **never** drawn on the board with stickies, arrows or `create_drawing`.
+   - **"draw" / "sketch" / "diagram" something** (a UML diagram, a flow, a class model) → a snippet in the chat (`mermaid` for a sequence/flow/state/ER/class diagram written as
+     Mermaid, `svg` for a picture you draw yourself, or a `code` block with PlantUML/ASCII), **never** drawn on the board with stickies, arrows or `create_drawing`.
      Only an explicit request to put it on the board changes that, and then as an image (`/domain-story` § board), not rebuilt from shapes;
    - **rows and columns** — a comparison, a matrix, a short list with a few attributes per item → `table`.
    - **a prototype you just built** (the `/prototype` skill) → `prototype`, the uploaded page running in the chat with a Full screen button;

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

@@ -417,6 +417,14 @@ import {api as {SliceName}Api} from './slices/{context}/{SliceName}/routes';
 
 ---
 
+## UI Contract
+
+Once the command endpoint is built, invoke the `ui-contract` skill (write contract, `POST`): it publishes
+the endpoint's contract as the `## UI Contract` section of the slice's feedback-lane markdown node, which the slice export then carries in `slice.json` `notes[]`. Do not restate the format here — the skill owns it
+(a build kit may override it).
+
+**Source for this stack:** derive the contract from the handler's `@openapi` block, using `references/ui-contract-from-openapi.md`.
+
 ## Files to create
 
 ```

package/stacks/node/templates/.claude/skills/build-state-change/references/ui-contract-from-openapi.md

@@ -0,0 +1,17 @@
+# UI Contract — derive from the `@openapi` block
+
+Used by the `ui-contract` skill. This stack's `routes.ts` carries an `@openapi` JSDoc block above every
+handler (guarded by the `openapi-annotation` commit check), so derive the contract from it mechanically
+instead of re-reading handler logic.
+
+| Contract key | OpenAPI source |
+|---|---|
+| `method` | the verb key under the path (`get` / `post`) |
+| `path` | the path key, verbatim (`{param}` style) |
+| `pathParams` / `queryParams` | `parameters[]` with `in: path` / `in: query` → `name`, `schema` (`optional` = not `required`) |
+| `body` (write) | `requestBody…schema.properties` |
+| `response.fields` (read) | the `200` response schema `properties` (follow a `$ref` to `components.schemas`); `Single` vs `List` = object vs `type: array` |
+| `response.status` (write) | the success response code |
+| `errors[]` | every non-2xx response: `status` = the key, `code` / `when` = its description / `error` example |
+| `type` | `string`+`uuid` → `UUID`, `integer`/`int32` → `Int`, `int64` → `Long`, `number`/`double` → `Double`, `number` → `Decimal`, `boolean` → `Boolean`, `date` / `date-time` → `Date` / `DateTime`, `object` → `Custom`, else `String` |
+| `example` | the schema's `example`, nothing invented |

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

@@ -484,6 +484,14 @@ import {api as {SliceName}Api} from './slices/{context}/{SliceName}/routes';
 
 ---
 
+## UI Contract
+
+Once the read endpoint is built, invoke the `ui-contract` skill (read contract, `GET`): it publishes
+the endpoint's contract as the `## UI Contract` section of the slice's feedback-lane markdown node, which the slice export then carries in `slice.json` `notes[]`. Do not restate the format here — the skill owns it
+(a build kit may override it).
+
+**Source for this stack:** derive the contract from the handler's `@openapi` block, using `../build-state-change/references/ui-contract-from-openapi.md`.
+
 ## Files to create / modify
 
 ```

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

@@ -50,7 +50,7 @@ When asked to build a slice, always follow this flow:
 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. This applies even when the slice was previously `Done` and reappears as `Planned` — never dismiss a mismatch as "already implemented" or harmless drift; diff slice.json against the code field by field and update the code to match every change.
 5. Run quality checks (`npm run build`, then the slice tests only).
-6. If checks pass, commit with `feat: [Slice Name]` and set slice status to `Done`.
+6. If checks pass, commit with `feat: [Slice Name]` and set slice status to `Done`. For STATE_VIEW/STATE_CHANGE slices when `handover` is enabled the status to set is `Handover`, not `Done` — see the `ui-contract` skill, Step 4.
 
 After you are done, automatically run the tests for the slice that was edited.
 

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

@@ -32,12 +32,12 @@ You work within **exactly ONE context at a time** — the one named in `.build-k
 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
+12. Invoke the `ui-contract` skill for STATE_VIEW / STATE_CHANGE slices (publishes the UI Contract section to the slice's feedback-lane markdown node)
 13. Run quality checks ( npm run build, npm run test ) - Attention - it´s enough to run the tests for the slice. Do not run all tests.
 14. even if the slice is fully implemented, run your test-analyzer skill and provide the code-slice.json file as defined in the skill
 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).
+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). For STATE_VIEW/STATE_CHANGE slices when `handover` is enabled the status to set is `Handover`, not `Done` — see the `ui-contract` skill, Step 4.
 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.

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

@@ -399,6 +399,12 @@ EVENT→READMODEL beats) belongs to `build-state-view`'s own storyline step, sin
 touches a projector. If the beat immediately after the command isn't an EVENT, don't force a test —
 leave it undocumented rather than fabricating an assertion.
 
+## UI Contract
+
+Once the command endpoint is built, invoke the `ui-contract` skill (write contract, `POST`): it publishes
+the endpoint's contract as the `## UI Contract` section of the slice's feedback-lane markdown node, which the slice export then carries in `slice.json` `notes[]`. Do not restate the format here — the skill owns it
+(a build kit may override it).
+
 ## Final Verification
 
 Before considering the slice done:

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

@@ -342,6 +342,12 @@ to `build-state-change` (its own command-handler test), not here — only projec
 `READMODEL` half. If a storyline segment involves a `SCREEN`/other untraceable beat, don't force a
 test — leave it undocumented in code rather than fabricating an assertion.
 
+## UI Contract
+
+Once the read endpoint is built, invoke the `ui-contract` skill (read contract, `GET`): it publishes
+the endpoint's contract as the `## UI Contract` section of the slice's feedback-lane markdown node, which the slice export then carries in `slice.json` `notes[]`. Do not restate the format here — the skill owns it
+(a build kit may override it).
+
 ## Final Verification: Does the Implementation Match slice.json?
 
 Before marking this slice as `Done`, verify the implementation against slice.json:

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

@@ -80,7 +80,7 @@ When asked to build a slice, always follow this flow:
    reappears as `Planned` — never dismiss a mismatch as "already implemented" or harmless drift; diff
    slice.json against the code field by field and update the code to match every change.
 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`.
+6. If checks pass, commit with `feat: [Slice Name]` and set slice status to `Done`. For STATE_VIEW/STATE_CHANGE slices when `handover` is enabled the status to set is `Handover`, not `Done` — see the `ui-contract` skill, Step 4.
 
 After you are done, automatically run the tests for the slice that was edited.
 

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

@@ -36,14 +36,14 @@ You work within **exactly ONE context at a time** — the one named in `.build-k
 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
+12. Invoke the `ui-contract` skill for STATE_VIEW / STATE_CHANGE slices (publishes the UI Contract section to the slice's feedback-lane markdown node)
 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).
+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). For STATE_VIEW/STATE_CHANGE slices when `handover` is enabled the status to set is `Handover`, not `Done` — see the `ui-contract` skill, Step 4.
 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.

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

@@ -30,6 +30,11 @@ From the slice definition, extract:
 - **events[]** — list of events emitted by each command
 - **specifications[]** — test scenarios (given/when/then)
 
+- **UI contract** — the backend slice's published write (`POST`) contract: look it up as described in the
+  `ui-contract` skill ("How the UI build kit looks the contract up": the `## UI Contract` entry in
+  `slice.json` `notes[]`, parse only its `ui-contract` block). It fixes the request: `path` (+ `pathParams`), the exact `body` fields, the success `response`, and `errors[]` (status + code) — surface each error code as its own user-facing state, not one generic failure. When absent, the backend slice isn't
+  built or re-fetched yet: build against `slice.json` and note the assumption in `progress.txt`.
+
 > **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`.
 
 ---

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

@@ -29,6 +29,11 @@ From the slice definition, extract:
 - **projections[]** / **queries[]** — the read model(s) this slice serves
 - **specifications[]** — test scenarios (given/when/then)
 
+- **UI contract** — the backend slice's published read (`GET`) contract: look it up as described in the
+  `ui-contract` skill ("How the UI build kit looks the contract up": the `## UI Contract` entry in
+  `slice.json` `notes[]`, parse only its `ui-contract` block). It fixes the request: `path` (+ `pathParams`/`queryParams`), the exact `response.fields` and `Single` vs `List` cardinality, and `errors[]` — render each error status as a distinct state. When absent, the backend slice isn't
+  built or re-fetched yet: build against `slice.json` and note the assumption in `progress.txt`.
+
 > **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`.
 
 ---