@eventmodelers/cli 1.0.153 → 1.0.155

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,13 @@
+# UI Contract — take the operation 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). The contract **is** that operation —
+publish it as is, don't translate it into another shape.
+
+1. Take the YAML from the handler's `@openapi` block (strip the ` * ` comment prefix) — one path, one verb.
+2. Keep it keyed by its path (`/api/...:` → `get:`/`post:`), with `summary`, `description`, `parameters`,
+   `requestBody` and every `responses` entry. Follow a `$ref` into `components.schemas` and inline it, so
+   the operation is self-contained.
+3. Drop `tags` and anything internal. Add nothing the block doesn't say — examples come from the block.
+4. Write it as the ```` ```yaml ui-contract ```` block of the `## UI Contract` section, with real line
+   breaks and 2-space indentation (see the skill's formatting rule).

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 — an OpenAPI operation). It fixes the request: the path (+ path `parameters`), the exact `requestBody` properties, the 2xx `responses` entry, and every non-2xx response (status + description) — 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 — an OpenAPI operation). It fixes the request: the path (+ path/query `parameters`), the exact 2xx response schema (object = `Single`, `type: array` = `List`), and every non-2xx response — 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`.
 
 ---

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

@@ -44,4 +44,4 @@ These files are always up to date — read them directly before invoking any ski
 - 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.
+- `/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 `Handover` one instead of erroring out.

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

@@ -9,28 +9,28 @@ The structure defined in the Project-Skills is relevant.
 You work within **exactly ONE context at a time** — the one named in `.build-kit/.slices/current_context.json` (the runner picks it).
 
 - **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 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 runner moves `current_context.json` on to the next context with planned work between iterations — never change it yourself.
+- **NEVER** read, scan, or build slices from any other context directory, even if it has "Handover" slices, and even if the current context has no work left.
+- A "Handover" slice in a *different* context is **NOT yours to build**. Ignore it completely.
+- If the current context has no "Handover" slice, you are **done for this iteration** — reply `<promise>NO_TASKS</promise>` and stop. Do not go looking elsewhere. The runner moves `current_context.json` on to the next context with Handover work between iterations — never change it yourself.
 
 ## 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.
+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 "handover" is a task.
 2. Read the progress log at `progress.txt` **if it exists** (check Codebase Patterns section first) — it is absent until the first slice is built, which is not an error; create it when you write your first entry
 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:**
+5. Pick the **highest priority** slice where status is **exactly** "Handover" (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 "Handover" 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 "Handover" 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>`.
+   **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 "Handover", and try claiming that one instead. Repeat until a claim succeeds or no "Handover" 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. Determine the slice type and invoke the matching skill as defined in the **Building a Slice** section of `.build-kit/CLAUDE.md`. Do NOT implement manually.
 8. Write a short progress one liner after each step to progress.txt
-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.
+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 "handover" 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. Build against the backend slice's published UI contract (see the `ui-contract` skill, "How the UI build kit looks the contract up") — the build-state-view / build-state-change skills say how to apply it
 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).
@@ -107,12 +107,12 @@ 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.
+**After completing ONE slice, always stop — regardless of whether more slices are in Handover.** 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:
+If no slice has status "Handover" in the current context, reply with:
 <promise>NO_TASKS</promise>
 (Do NOT switch to another context to find work — stop here.)
 

package/stacks/react/templates/build-kit/lib/kit.json

@@ -0,0 +1,3 @@
+{
+  "pickupStatus": "Handover"
+}

package/stacks/react/templates/build-kit/lib/prompt.md

@@ -44,13 +44,13 @@ Run `/load-slice sliceId=<payload.sliceId>` to fetch full slice details (title,
 
 Inspect the `sliceStatus` in the payload:
 
-#### `Planned` — build the slice
+#### `Handover` — build the slice
 
 This is the build trigger. Setting `InProgress` and building are one atomic step:
 
 1. Immediately call `/update-slice-status` to set the slice to `InProgress` on the board.
 
-   **Claim conflict**: if this call reports the slice is already in `InProgress` (or any status other than `Planned`), another agent already claimed it first — this is expected, not an error. Log it in `progress.txt`, drop this task without building, and continue the loop (the next task will naturally cover the next slice). Do not retry.
+   **Claim conflict**: if this call reports the slice is already in `InProgress` (or any status other than `Handover`), another agent already claimed it first — this is expected, not an error. Log it in `progress.txt`, drop this task without building, and continue the loop (the next task will naturally cover the next slice). Do not retry.
 
 2. Run `/load-slice sliceId=<payload.sliceId>` to fetch the full slice, then read the slice definition from `.build-kit/.slices/<contextSlug>/<sliceFolder>/slice.json`. The runner keeps a `slice.json` fresh from a summary endpoint, so a file holding only `id`, `title`, `status` and `sliceType` is that stub, not an empty slice — never conclude a slice has no elements from it. Only if the full fetch itself returns no commands/events/read models/fields is the slice actually empty.
 

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

@@ -424,6 +424,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/supabase/templates/.claude/skills/build-state-change/references/ui-contract-from-openapi.md

@@ -0,0 +1,13 @@
+# UI Contract — take the operation 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). The contract **is** that operation —
+publish it as is, don't translate it into another shape.
+
+1. Take the YAML from the handler's `@openapi` block (strip the ` * ` comment prefix) — one path, one verb.
+2. Keep it keyed by its path (`/api/...:` → `get:`/`post:`), with `summary`, `description`, `parameters`,
+   `requestBody` and every `responses` entry. Follow a `$ref` into `components.schemas` and inline it, so
+   the operation is self-contained.
+3. Drop `tags` and anything internal. Add nothing the block doesn't say — examples come from the block.
+4. Write it as the ```` ```yaml ui-contract ```` block of the `## UI Contract` section, with real line
+   breaks and 2-space indentation (see the skill's formatting rule).

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

@@ -459,6 +459,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
 
 ```