@eventmodelers/cli 1.0.163 → 2.0.2

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

@@ -4,17 +4,11 @@ You are an autonomous agent reacting to slice status change events on an Eventmo
 
 ## Your Loop
 
-1. Read `AGENT.md` to load accumulated learnings before doing anything else.
-2. Read `.build-kit/tasks.json`.
-3. If `tasks.json` is empty or missing, reply with:
-   <promise>IDLE</promise>
-   and stop.
-4. Pick the **oldest task** (earliest `createdAt`).
-5. Execute the task — see the Execution section below.
-6. After execution, remove that task from the array and write `.build-kit/tasks.json` back.
-7. Append a progress entry to `progress.txt` (create if missing).
-8. Update `AGENT.md` with any new reusable learnings discovered this iteration.
-9. Reply normally so the next iteration can pick up the next task.
+1. Read `AGENT.md` and, if it exists, `.build-kit/AGENTS.md` to load accumulated knowledge before doing anything else.
+2. The task request at the end of this prompt names your task: its id and the slice change that queued it (`sliceId`, `sliceTitle`, `sliceStatus`, …). It is the oldest one waiting — the run loop picked it for you.
+3. Execute the task — see the Execution section below.
+4. Record any reusable learning with `npx @eventmodelers/cli learn "<one terse line>" --topic <topic>` (see **Recording Learnings**).
+5. Reply normally. The run loop completes the task when your turn ends and hands you the next one in a fresh turn — you never read or write a queue file.
 
 ## Execution
 
@@ -44,13 +38,13 @@ Run `/load-slice sliceId=<payload.sliceId>` to fetch full slice details (title,
 
 Inspect the `sliceStatus` in the payload:
 
-#### `Handover` — build the slice
+#### `Waiting` — 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 `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.
+   **Claim conflict**: if this call reports the slice is already in `InProgress` (or any status other than `Waiting`), another agent already claimed it first — this is expected, not an error. Say so in your reply, 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.
 
@@ -62,6 +56,33 @@ This is the build trigger. Setting `InProgress` and building are one atomic step
 
 4. Invoke the matching skill and follow its instructions **completely**. Do NOT implement the slice manually.
 
+   **UI baseline gate** — before touching any code, run `npx @eventmodelers/cli ui-baseline check`. It
+   compares the board's node hashes (the slice's screen and every element) and `codeGen.uiPrompts` with
+   what was recorded after the last UI build, and decides what this build has to do:
+   - `UNCHANGED` — nothing on the board changed since the last UI build. Skip all UI work; do not
+     re-fetch or diff the screen. Only now is "no code changes needed" a valid outcome.
+   - `NO_BASELINE` — no UI build recorded yet (first build, or the slice predates the baseline). Do one
+     full screen diff (below), apply every UI prompt.
+   - `UNKNOWN` — the board could not be read. Treat it as `NO_BASELINE`; never as `UNCHANGED`.
+   - `CHANGED` — it also lists, per element, what changed, was added or was removed since the last recorded
+     build (e.g. `changed: Contact Details (screen), Assign Tag (command)`). Work on exactly those nodes
+     and leave what matches alone. Act on the parts it flags:
+     - `SCREEN_CHANGED`: re-fetch the live screen node (`get_node`, its `meta.pages` / `meta.marks`) —
+       never trust the JSX already in the repo — and diff the existing component(s) against the marked
+       (or whole, if unmarked) HTML: tags, classes, layout, copy, fields/buttons added, removed or
+       reordered, and `cssFrameworks`. Edit the components (and `src/pages/<ScreenTitle>.tsx`, for this
+       slice's marked position only) until they match 1:1 and update `samples/`. Keep what already
+       matches; do not regenerate the slice from scratch.
+     - `ELEMENTS_CHANGED`: diff slice.json against the code field by field (fields,
+       `apiEndpoint`/UI contract) and fix every drift.
+     - `PROMPTS_CHANGED`: apply the UI prompts it prints — each is an instruction the user typed on the
+       board for this slice's UI (e.g. "adjust the UI to the new layout!") — to the component(s) and
+       screen markup. Name each prompt and the change you made for it in your final reply.
+
+   When the UI work is done and the checks in step 6 pass, run `npx @eventmodelers/cli ui-baseline record`
+   **before committing**, so `ui-baseline.json` is committed with the slice. Never record without having
+   done the work the verdict asked for.
+
 5. **Verify against slice.json**: cross-check the implementation — every command field, event field, and specification in slice.json must appear in the code. No invented fields — if it is not in slice.json, it must not be in the code.
 
 6. Run quality checks (TODO: your stack's build + test commands — slice-scoped tests only, not the full suite).
@@ -74,52 +95,35 @@ This is the build trigger. Setting `InProgress` and building are one atomic step
 Another agent is already building this slice. Log it and skip — do not build.
 
 #### `Done`
-Summarize what was completed and update `progress.txt`.
+Summarize what was completed in your reply.
 
 #### `Blocked`
-Log the blocker in `progress.txt`.
+State the blocker in your reply.
 
 #### `Review`
-Fetch slice details and prepare a review summary in `progress.txt`.
+Fetch slice details and prepare a review summary in your reply.
 
 #### Any other status (`Created`, etc.)
-Load the slice and log the state transition in `progress.txt`. No build action.
+Load the slice and note the state transition in your reply. No build action.
 
 Use the skills available in `.claude/skills/` to interact with the board.
 
-## Updating tasks.json
-
-After completing a task, remove it from the array and write the updated array back to `.build-kit/tasks.json`. If the array is now empty, write `[]`.
-
 ## Escalating Ambiguity
 
-**Default: make a reasonable assumption and build the slice.** If a detail is unclear or missing (an example value, a field type, a status mapping, a referenced event that isn't modeled yet, ...), pick the most sensible interpretation from `slice.json`, its specifications and the surrounding model, build it, and record each assumption in one line in `progress.txt` and as a code comment. Ambiguity alone is never a reason to stop. **Only if the slice literally cannot be built** — nothing runnable can be produced even with sensible assumptions — invoke `/request-feedback` with the specific question; it posts the question as a comment on the slice and marks it `Blocked`. That must be the absolute exception; a `Blocked` slice should mean "impossible without a human", never "the agent preferred to ask".
-
-## Progress Report Format
-
-APPEND to `progress.txt` (never replace):
-```
-## [ISO timestamp] — Task [task.id]
+**Default: make a reasonable assumption and build the slice.** If a detail is unclear or missing (an example value, a field type, a status mapping, a referenced event that isn't modeled yet, ...), pick the most sensible interpretation from `slice.json`, its specifications and the surrounding model, build it, and record each assumption in one line as a code comment. Ambiguity alone is never a reason to stop. **Only if the slice literally cannot be built** — nothing runnable can be produced even with sensible assumptions — invoke `/request-feedback` with the specific question; it posts the question as a comment on the slice and marks it `Blocked`. That must be the absolute exception; a `Blocked` slice should mean "impossible without a human", never "the agent preferred to ask".
 
-Slice: [sliceTitle] ([sliceId])
-Status change: [sliceStatus]
+## Recording Learnings
 
-Action taken:
-- [what was done in response to the slice change]
+`.build-kit/AGENTS.md` is generated from the learnings recorded so far — read it at the start of every session, never edit it by hand. Record a learning the moment you have it:
 
-Learnings:
-- [any patterns, gotchas, or reusable knowledge discovered]
----
+```
+npx @eventmodelers/cli learn "<one terse line>" --topic "<topic>"
 ```
 
-## Stop Condition
-
-If `.build-kit/tasks.json` is empty (`[]`) or does not exist, reply with:
-<promise>IDLE</promise>
-
-## Updating AGENT.md
-
-After completing a task, add any **reusable** learnings to `AGENT.md` — patterns, gotchas, API quirks, or skill behaviour that future iterations should know. Only add things that are general and applicable beyond this single task. Do not duplicate what is already there.
+- Only what is genuinely reusable: codebase patterns, gotchas, commands that work or don't, conventions — and, after a failed approach, what was tried and why it failed. Not slice-specific details, and nothing the code or git log already says.
+- One learning per call, one line each. A learning that is already in `.build-kit/AGENTS.md` is skipped for you.
+- `--scope system` for what is true of the modeled domain (a business rule, a naming convention of the model); `repo` (the default) for the codebase and its tooling. `--tag <tag>` labels it (repeatable).
+- One in `.build-kit/AGENTS.md` that turned out wrong or obsolete: `npx @eventmodelers/cli learnings --ids` lists each with its id, `npx @eventmodelers/cli learn --retract <id>` removes it.
 
 ## Important
 

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

@@ -42,8 +42,22 @@ CREATE TABLE IF NOT EXISTS "public"."{tablename}"
     -- use snake_case for all column names
     created_at  TIMESTAMP DEFAULT NOW()
 );
+
+-- The UI reads this table DIRECTLY through Supabase (no read endpoint in between), so it must be readable.
+-- RLS on with no policy returns an EMPTY list, not an error - always ship the policy with the table.
+ALTER TABLE "public"."{tablename}" ENABLE ROW LEVEL SECURITY;
+GRANT SELECT ON "public"."{tablename}" TO authenticated;
+CREATE POLICY "{tablename}_select" ON "public"."{tablename}"
+    FOR SELECT TO authenticated USING (true);
 ```
 
+**The UI reads the read-model table directly.** The frontend never goes through the `GET` route for a
+read model: it selects from this table with the user's session, and Row Level Security decides which
+rows come back. `USING (true)` is the default (every signed-in user sees every row); when the read
+model is per user or per tenant (an owner/user/tenant column, or `description`/`comments[]` say so),
+narrow the policy to it, e.g. `USING (owner_id = auth.uid()::text)`. The `GET` route in Step 5 stays
+for API consumers and tests; the UI does not depend on it.
+
 **Column type guide** — field `type` values are the canonical set from the [event-modeling-spec schema](https://github.com/dilgerma/event-modeling-spec/blob/main/eventmodeling.schema.json):
 
 | Field type | SQL type |
@@ -487,6 +501,7 @@ src/common/
 ## Checklist
 
 - [ ] Migration file created with correct version number and all columns
+- [ ] Migration enables RLS, grants `SELECT` to `authenticated` and creates a select policy: the UI reads the table directly, and no policy means an empty list
 - [ ] `tableName` constant matches the migration table name exactly
 - [ ] Projection registered in `loadPostgresEventstore.ts`
 - [ ] `canHandle` lists every event type the projection reacts to

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

@@ -28,16 +28,16 @@ Ignore case for files and slices in prompts. "CartItems" slice is the same as "c
 
 Do not change files with tests unless explicitely instructed, or the change brings the test in line with slice.json (e.g. step 4's field/spec diff): *.test.ts
 
-At the start of every session, read `.build-kit/AGENTS.md` if it exists to load accumulated project learnings.
+At the start of every session, read `.build-kit/AGENTS.md` if it exists to load accumulated project learnings. It is generated from the learnings recorded so far — record a new one with `npx @eventmodelers/cli learn "<one terse line>" --topic <topic>`, never by editing the file.
 
-When starting to work on a slice, invoke the `update-slice-status` skill with `InProgress` status before doing anything else.
+When working from a queued task, invoke the `update-slice-status` skill with `InProgress` status before doing anything else. When the task request names the slice to build (a run-loop build), the run loop has already set it to `InProgress` and pushes the final status itself — do not call `update-slice-status`; record the outcome with `npx @eventmodelers/cli slice-status <status>`.
 
 ## Building a Slice
 
 **CRITICAL: You MUST always use the provided skills to build slices. NEVER implement a slice manually.**
 **ALL fields, event names, command names, and business rules MUST come exclusively from slice.json. Do NOT invent, assume, or guess any field or logic not present in the slice definition.**
 
-**Default: make a reasonable assumption and build the slice.** If a detail is unclear or missing (an example value, a field type, a status mapping, a referenced event that isn't modeled yet, ...), pick the most sensible interpretation from `slice.json`, its specifications and the surrounding model, build it, and record each assumption in one line in `progress.txt` and as a code comment. Ambiguity alone is never a reason to stop. **Only if the slice literally cannot be built** — nothing runnable can be produced even with sensible assumptions — invoke `/request-feedback` with the specific question; it posts the question as a comment on the slice and marks it `Blocked`. That must be the absolute exception; a `Blocked` slice should mean "impossible without a human", never "the agent preferred to ask".
+**Default: make a reasonable assumption and build the slice.** If a detail is unclear or missing (an example value, a field type, a status mapping, a referenced event that isn't modeled yet, ...), pick the most sensible interpretation from `slice.json`, its specifications and the surrounding model, build it, and record each assumption in one line as a code comment. Ambiguity alone is never a reason to stop. **Only if the slice literally cannot be built** — nothing runnable can be produced even with sensible assumptions — invoke `/request-feedback` with the specific question; it posts the question as a comment on the slice and marks it `Blocked`. That must be the absolute exception; a `Blocked` slice should mean "impossible without a human", never "the agent preferred to ask".
 
 When asked to build a slice, always follow this flow:
 
@@ -49,9 +49,10 @@ When asked to build a slice, always follow this flow:
    - **State-view** — `projections` or `queries` array is non-empty → invoke `/build-state-view`
    - **State-change** — default (has `commands` / `events`) → invoke `/build-state-change`
 3. Invoke the matching skill and follow its instructions completely. Do not deviate.
-4. **Verify against slice.json**: After the skill completes, check that every command field, event field, and specification in slice.json appears in the implementation. No invented fields — if it is not in slice.json, it must not be in the code. 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`. 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.
+4. **Baseline gate**: run `npx @eventmodelers/cli build-baseline check --scope backend` first and act only on its verdict — `UNCHANGED` means nothing on the board changed since the last recorded build: do not rebuild, just run the slice's tests and finish; `NO_BASELINE`/`UNKNOWN` mean one full field-by-field diff of slice.json against the code; `CHANGED` lists exactly which elements changed, were added or removed — diff and fix only those. After the checks pass and before committing, run `build-baseline record --scope backend`. A screen or UI prompt change never triggers a backend build.
+5. **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.
+6. Run quality checks (`npm run build`, then the slice tests only).
+7. 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 `Waiting`, 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/supabase/templates/build-kit/lib/AGENT.md

@@ -1,12 +1,11 @@
-# Agent Learnings
+# Agent Reference
 
-Patterns and gotchas discovered during task processing. Update this file whenever you encounter something reusable.
+What task processing relies on: the shape of a task and the API facts the skills use. A reusable learning is recorded with `npx @eventmodelers/cli learn "<one terse line>"`, not added here.
 
-## tasks.json
+## Tasks
 
-- Tasks are objects with `id`, `createdAt`, and `payload` (a `SliceChangedPayload`).
-- After completing a task, remove it from the array entirely — do not add a status field.
-- Write `[]` to `tasks.json` if the last task is completed.
+- A task is a slice change the run loop queued: an `id` and a `payload` (a `SliceChangedPayload`). The task request names it.
+- You never read or write a queue file: the run loop completes the task when your turn ends.
 
 ## SliceChangedPayload fields
 
@@ -44,4 +43,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 `Planned` one instead of erroring out. This applies to queued tasks only: when the task request names the slice to build, the run loop owns its status — never call `/update-slice-status` there.

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

@@ -17,16 +17,15 @@ You work within **exactly ONE context at a time** — the one named in `.build-k
 
 0. Do not read the entire code base. Focus on the tasks in this description.
 1. Read `.build-kit/.slices/current_context.json` to find the active context name, then read `.build-kit/.slices/<contextName>/index.json`. Every item in status "planned" is a task.
-2. Read the progress log at `progress.txt` **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
+2. Read `.build-kit/AGENTS.md` **if it exists** — the project's accumulated learnings, generated from what earlier builds recorded. If the slice's `slice.json` has a `lastAttempt`, an earlier attempt at it failed: read its `reason`, `lastReply`, `branch` and `changed`, and do not repeat what failed.
 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. Your slice is the one the task request names (the run loop picked the highest priority slice with status "Planned"); it becomes your PRD. The run loop has already claimed it — its status is "InProgress" in index.json and on the board. Build that slice and do not call `update-slice-status`: the run loop owns the slice's status on the board.
+   **IMPORTANT: Only work on the slice named in the task request. Never switch to another slice, whatever its status. If the task request names no slice and no slice has status "Planned" in the current context, reply with:**
    <promise>NO_TASKS</promise> and stop immediately. Do not work on other slices and do not switch to another context.
-   **Claim conflict**: the board rejects the status update if the slice is already in the target status — this is expected: another agent claimed it first, racing you for the same slice. This is NOT an error. Do not stop, do not retry the same slice. Re-read `index.json` (or re-fetch via `load-slice`), pick the next-highest-priority slice still "Planned", and try claiming that one instead. Repeat until a claim succeeds or no "Planned" slice remains, in which case reply `<promise>NO_TASKS</promise>`.
 6. Pick the slice definition from `.build-kit/.slices/<contextName>/<folder>/slice.json` as defined in the prd. Never work on more than one slice per iteration.
-7. A slice can define additional prompts as codegen/backendPrompt. any additional prompts defined in backend are hints for the implementation of the slice and have to be taken into account. If you use the additional prompt, add a line in progress.txt
+7. 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.
 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
+8. Record each learning the moment you have it (see **Recording Learnings**), not at the end.
 9. Analyze and Implement that single slice, make use of the skills in the skills directory, but also your previsously collected
    knowledge. Make a list TODO list for what needs to be done. Also make sure to adjust the implementation according to the json definition. Carefully inspect events, fields and compare against the implemented slice. JSON is the desired state. ATTENTION: A "planned" task can also be just added specifications. So always look at the slice itself, but also the specifications. If specifications were added in json, which are not on code, you need to add them in code.
 10. The slice in the json is always true, the code follows what is defined in the json
@@ -37,48 +36,27 @@ You work within **exactly ONE context at a time** — the one named in `.build-k
 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). 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.
+16. Record the outcome with `npx @eventmodelers/cli slice-status Done` — not by editing index.json, and do not call `update-slice-status`: the run loop pushes the status to the board when your turn ends. For STATE_VIEW/STATE_CHANGE slices when `handover` is enabled the status to record is `Waiting`, not `Done` — see the `ui-contract` skill, Step 4. A slice you could not finish needs no status: leave it as it is and the run loop discards the attempt.
+17. Record any reusable learning you have not recorded yet (see **Recording Learnings**).
+ 18. If an entry in `.build-kit/AGENTS.md` turned out wrong or obsolete, retract it (see **Recording Learnings**).
 19. Finish the iteration.
 
 ## Escalating Ambiguity
 
-**Default: make a reasonable assumption and build the slice.** If a detail is unclear or missing (an example value, a field type, a status mapping, a referenced event that isn't modeled yet, ...), pick the most sensible interpretation from `slice.json`, its specifications and the surrounding model, build it, and record each assumption in one line in `progress.txt` and as a code comment. Ambiguity alone is never a reason to stop. **Only if the slice literally cannot be built** — nothing runnable can be produced even with sensible assumptions — invoke `/request-feedback` with the specific question; it posts the question as a comment on the slice and marks it `Blocked`. That must be the absolute exception; a `Blocked` slice should mean "impossible without a human", never "the agent preferred to ask".
+**Default: make a reasonable assumption and build the slice.** If a detail is unclear or missing (an example value, a field type, a status mapping, a referenced event that isn't modeled yet, ...), pick the most sensible interpretation from `slice.json`, its specifications and the surrounding model, build it, and record each assumption in one line as a code comment. Ambiguity alone is never a reason to stop. **Only if the slice literally cannot be built** — nothing runnable can be produced even with sensible assumptions — invoke `/request-feedback` with the specific question; it posts the question as a comment on the slice and marks it `Blocked`. That must be the absolute exception; a `Blocked` slice should mean "impossible without a human", never "the agent preferred to ask".
 
-## Progress Report Format
+## Recording Learnings
 
-APPEND to progress.txt (never replace, always append):
+`.build-kit/AGENTS.md` is generated from the learnings recorded so far — read it at the start of every session, never edit it by hand. Record a learning the moment you have it:
 
 ```
-## [Date/Time] - [Slice]
-
-- What was implemented
-- Files changed
-- **Learnings for future iterations:**
-  - Patterns discovered (e.g., "this codebase uses X for Y")
-  - Gotchas encountered (e.g., "don't forget to update Z when changing W")
-  - Useful context (e.g., "the evaluation panel is in component X")
----
+npx @eventmodelers/cli learn "<one terse line>" --topic "<topic>"
 ```
 
-The learnings section is critical - it helps future iterations avoid repeating mistakes and understand the codebase
-better.
-
-## Consolidate Patterns
-
-If you discover a **reusable pattern** that future iterations should know, add it to the `## Codebase Patterns` section
-at the TOP of progress.txt (create it if it doesn't exist). This section should consolidate the most important
-learnings:
-
-```
-## Codebase Patterns
-- Example: Use `sql<number>` template for aggregations
-- Example: Always use `IF NOT EXISTS` for migrations
-- Example: Export types from actions.ts for UI components
-```
-
-Only add patterns that are **general and reusable**, not story-specific details.
+- Only what is genuinely reusable: codebase patterns, gotchas, commands that work or don't, conventions — and, after a failed approach, what was tried and why it failed. Not slice-specific details, and nothing the code or git log already says.
+- One learning per call, one line each. A learning that is already in `.build-kit/AGENTS.md` is skipped for you.
+- `--scope system` for what is true of the modeled domain (a business rule, a naming convention of the model); `repo` (the default) for the codebase and its tooling. `--tag <tag>` labels it (repeatable).
+- One in `.build-kit/AGENTS.md` that turned out wrong or obsolete: `npx @eventmodelers/cli learnings --ids` lists each with its id, `npx @eventmodelers/cli learn --retract <id>` removes it.
 
 ## Update AGENTS.md Files
 
@@ -104,7 +82,7 @@ Before committing, check if any edited files have learnings worth preserving in
 - Slice specific implementation details
 - Story-specific implementation details
 - Temporary debugging notes
-- Information already in progress.txt
+- Information already recorded as a learning in `.build-kit/AGENTS.md`
 - Task speecific learnings like "- Timesheet approval requires: submitted=true, reverted=false, approved=false, declined=false"
 
 Only update AGENTS.md if you have **genuinely reusable knowledge** that would help future work
@@ -148,9 +126,9 @@ If ALL slices in the current context are Done, reply with:
 - If no `.eventmodelers/config.json` exists anywhere (project root or an ancestor directory, or `~/.eventmodelers/config.json` — the one inside `.build-kit/` is only an optional override, so its absence means nothing), skip all platform communication (MCP calls, `update-slice-status`, board sync) and continue working locally.
 - Work on ONE slice per iteration
 - Commit frequently
-- update progress.txt frequently
-- Read the Codebase Patterns section in progress.txt before starting
+- Record learnings as you go with `learn`
+- Read `.build-kit/AGENTS.md` before starting
 
 ## When an iteration completes
 
-Use all the key learnings from the progress.txt and update the `.build-kit/AGENTS.md` file with those learnings.
+Make sure every reusable learning is recorded with `learn`; `.build-kit/AGENTS.md` is generated from them — never edit it by hand.

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

@@ -4,17 +4,11 @@ You are an autonomous agent reacting to slice status change events on an Eventmo
 
 ## Your Loop
 
-1. Read `AGENT.md` to load accumulated learnings before doing anything else.
-2. Read `.build-kit/tasks.json`.
-3. If `tasks.json` is empty or missing, reply with:
-   <promise>IDLE</promise>
-   and stop.
-4. Pick the **oldest task** (earliest `createdAt`).
-5. Execute the task — see the Execution section below.
-6. After execution, remove that task from the array and write `.build-kit/tasks.json` back.
-7. Append a progress entry to `progress.txt` (create if missing).
-8. Update `AGENT.md` with any new reusable learnings discovered this iteration.
-9. Reply normally so the next iteration can pick up the next task.
+1. Read `AGENT.md` and, if it exists, `.build-kit/AGENTS.md` to load accumulated knowledge before doing anything else.
+2. The task request at the end of this prompt names your task: its id and the slice change that queued it (`sliceId`, `sliceTitle`, `sliceStatus`, …). It is the oldest one waiting — the run loop picked it for you.
+3. Execute the task — see the Execution section below.
+4. Record any reusable learning with `npx @eventmodelers/cli learn "<one terse line>" --topic <topic>` (see **Recording Learnings**).
+5. Reply normally. The run loop completes the task when your turn ends and hands you the next one in a fresh turn — you never read or write a queue file.
 
 ## Execution
 
@@ -48,11 +42,11 @@ Inspect the `sliceStatus` in the payload:
 
 This is the build trigger. Setting `InProgress` and building are one atomic step:
 
-**Default: make a reasonable assumption and build the slice.** If a detail is unclear or missing (an example value, a field type, a status mapping, a referenced event that isn't modeled yet, ...), pick the most sensible interpretation from `slice.json`, its specifications and the surrounding model, build it, and record each assumption in one line in `progress.txt` and as a code comment. Ambiguity alone is never a reason to stop. **Only if the slice literally cannot be built** — nothing runnable can be produced even with sensible assumptions — invoke `/request-feedback` with the specific question; it posts the question as a comment on the slice and marks it `Blocked`. That must be the absolute exception; a `Blocked` slice should mean "impossible without a human", never "the agent preferred to ask".
+**Default: make a reasonable assumption and build the slice.** If a detail is unclear or missing (an example value, a field type, a status mapping, a referenced event that isn't modeled yet, ...), pick the most sensible interpretation from `slice.json`, its specifications and the surrounding model, build it, and record each assumption in one line as a code comment. Ambiguity alone is never a reason to stop. **Only if the slice literally cannot be built** — nothing runnable can be produced even with sensible assumptions — invoke `/request-feedback` with the specific question; it posts the question as a comment on the slice and marks it `Blocked`. That must be the absolute exception; a `Blocked` slice should mean "impossible without a human", never "the agent preferred to ask".
 
 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 `Planned`), another agent already claimed it first — this is expected, not an error. Say so in your reply, 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.
 
@@ -75,48 +69,31 @@ This is the build trigger. Setting `InProgress` and building are one atomic step
 Another agent is already building this slice. Log it and skip — do not build.
 
 #### `Done`
-Summarize what was completed and update `progress.txt`.
+Summarize what was completed in your reply.
 
 #### `Blocked`
-Log the blocker in `progress.txt`.
+State the blocker in your reply.
 
 #### `Review`
-Fetch slice details and prepare a review summary in `progress.txt`.
+Fetch slice details and prepare a review summary in your reply.
 
 #### Any other status (`Created`, etc.)
-Load the slice and log the state transition in `progress.txt`. No build action.
+Load the slice and note the state transition in your reply. No build action.
 
 Use the skills available in `.claude/skills/` to interact with the board.
 
-## Updating tasks.json
+## Recording Learnings
 
-After completing a task, remove it from the array and write the updated array back to `.build-kit/tasks.json`. If the array is now empty, write `[]`.
+`.build-kit/AGENTS.md` is generated from the learnings recorded so far — read it at the start of every session, never edit it by hand. Record a learning the moment you have it:
 
-## Progress Report Format
-
-APPEND to `progress.txt` (never replace):
 ```
-## [ISO timestamp] — Task [task.id]
-
-Slice: [sliceTitle] ([sliceId])
-Status change: [sliceStatus]
-
-Action taken:
-- [what was done in response to the slice change]
-
-Learnings:
-- [any patterns, gotchas, or reusable knowledge discovered]
----
+npx @eventmodelers/cli learn "<one terse line>" --topic "<topic>"
 ```
 
-## Stop Condition
-
-If `.build-kit/tasks.json` is empty (`[]`) or does not exist, reply with:
-<promise>IDLE</promise>
-
-## Updating AGENT.md
-
-After completing a task, add any **reusable** learnings to `AGENT.md` — patterns, gotchas, API quirks, or skill behaviour that future iterations should know. Only add things that are general and applicable beyond this single task. Do not duplicate what is already there.
+- Only what is genuinely reusable: codebase patterns, gotchas, commands that work or don't, conventions — and, after a failed approach, what was tried and why it failed. Not slice-specific details, and nothing the code or git log already says.
+- One learning per call, one line each. A learning that is already in `.build-kit/AGENTS.md` is skipped for you.
+- `--scope system` for what is true of the modeled domain (a business rule, a naming convention of the model); `repo` (the default) for the codebase and its tooling. `--tag <tag>` labels it (repeatable).
+- One in `.build-kit/AGENTS.md` that turned out wrong or obsolete: `npx @eventmodelers/cli learnings --ids` lists each with its id, `npx @eventmodelers/cli learn --retract <id>` removes it.
 
 ## Important
 

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

@@ -61,8 +61,8 @@ Extract:
   `requestBody` properties, the 2xx `responses` entry, and every non-2xx response (status + description) — surface each error code as a
   distinct user-facing state through `onError`, not one generic failure. When absent, the backend slice
   isn't built or re-fetched yet: fall back to `apiEndpoint` / `fields[]` as above and note the assumption
-  in `progress.txt`. If contract and `command.fields[]` disagree, the contract wins for the request and
-  you record the mismatch in `progress.txt`.
+  as a code comment. If contract and `command.fields[]` disagree, the contract wins for the request and
+  you record the mismatch as a code comment.
   **Build the call from it**: `postCommand(buildPath('<contract path>', { <path params> }), { <requestBody
   properties> })` — `buildPath` (in `src/lib/api.ts`) fills and URL-encodes `{param}` segments; the body
   carries exactly the contract's `requestBody` properties (props the contract doesn't list stay out).
@@ -71,8 +71,9 @@ Extract:
 - **screens[]** — the actor `SCREEN` element(s) that trigger this command, if any. Empty when the
   command has no UI trigger (rare — build the component from fields alone in that case, skip Step
   2).
-- **specifications[]** — GWT scenarios; treat as acceptance criteria for the component's business
-  logic (e.g. "given empty `email`, submit is disabled").
+- **specifications[]** and **storylines[]** (optional) — GWT scenarios / board walkthroughs. These
+  describe how the slice should **behave** — read them in full (Step 3a) to understand the outcomes
+  and states the UI must present. The business logic itself lives in the backend; the UI does not implement it.
 
 > **Comments**: each element carries `comments: string[]` (board comments) — read them as
 > implementation hints, and resolve consumed ones via
@@ -80,6 +81,10 @@ Extract:
 
 ## Step 2 — Read the screen, and especially its marks
 
+> **Gated by `ui-baseline check`** (build prompt, `lib/prompt.md`, Step 4): do this step when the verdict
+> is `SCREEN_CHANGED`, `NO_BASELINE` or `UNKNOWN` — and then also diff the existing JSX against the fetched
+> screen and adjust the UI to it. On `UNCHANGED` skip it.
+
 `slice.json`'s `screens[]` entries only carry `id`/`title`/`fields[]`/`description` (fields already
 scoped to this slice) — not the actual markup. Fetch the live node to get that:
 
@@ -132,19 +137,76 @@ lane concept, so the frontend path isn't a strict 1:1 mirror of it. `CommandTitl
 **Markup**: translate the blueprint HTML from Step 2 into JSX **1:1** — same tags, same classes
 (the screen's `cssFrameworks` framework), same layout and copy. This is not a redesign; the screen *is*
 the design. Only change what must become dynamic:
-- A field's example value becomes that input's controlled `value`.
+- A field's example value becomes that input's **initial/default** `value` only for what the user is
+  *entering* (a new-record form). Anything the screen *displays* about an existing entity (names,
+  titles, current selection, existing tags, list rows) is **not** static — see "Data binding" below.
 - An element repeated for a `cardinality: "List"` field becomes a `.map()` over that field.
 - `class`/`style`/structure otherwise stay exactly as drawn — except the board's own mark plumbing:
   drop every `data-em-mark-id` attribute and `em-mark`/`em-mark-<hex>` class (they only draw the
   highlight outline on the canvas; the app never ships it).
 - The classes only render correctly if the screen's CSS framework (`cssFrameworks`) is loaded in the app — see Step 7 (styles); don't hand-write CSS to compensate.
 
+**Data binding — mockup text is sample data, not copy.** The example values drawn in a screen are
+placeholders from the model. Before translating, classify every piece of text/value in the fragment:
+*label/copy* (headings like "Tags", button captions, placeholders — keep verbatim) vs. *data* (a person's
+name, a role/organisation line, a pre-selected dropdown value, dropdown options, existing list rows,
+badges, counts, dates). For each *data* item find its source in `slice.json` / the model — the
+`readmodels[]` whose fields carry it, or the command's own `fields[]` — and render it from there.
+**Never hardcode a data value from the mockup into JSX.**
+
+**Find the screen's data sources on the board, not just in `slice.json`.** A screen is often shown by
+one slice but fed by a read model that belongs to *another* slice (e.g. the Contact Details screen
+sits in the Assign Tag slice, yet its contact data comes from the Contact List read model via an edge
+READMODEL → SCREEN). `slice.json` only lists this slice's own elements, so also call
+`mcp__eventmodelers__get_connected_nodes { boardId, nodeId: <screen.id> }` and take every READMODEL
+wired into the screen. Each one is a data source for the displayed values; look up its fields in that
+read model's slice (`.build-kit/.slices/*/*/slice.json`, or `get_node`). A list read model feeding a
+detail screen (`Contact List[]` → one contact) means: query it filtered by the entity id the page
+gets from the route (match the id field, e.g. `contactId` / the command's `recordId`) and render that
+row. If the source read model's slice isn't built, still type and wire against its fields (TODO), do
+not substitute the mockup's values.
+
+- Data comes from a read model (query component of the same page/screen, via `queryReadModel` /
+  `getReadModel`) → bind it to that data (props from the parent that fetched it, or fetch it here
+  when this component owns that read). If that read-model slice is not built yet, wire the component
+  against the typed shape and leave a `// TODO(<read model title>)` — do not paste the example in.
+- Select/dropdown *options* come from a read model (e.g. the customer list), never from the
+  options drawn in the mockup; the *selected* value comes from the entity's own read model.
+- The only legitimate static content is label/copy and `VITE_DATA_MODE=mock` samples in `samples/*.json`.
+- Self-check before finishing: grep the component for the mockup's example strings (e.g. the person's
+  name, organisation, tag text). Any hit outside `samples/` is a bug.
+
 **Props**: exactly `command.fields[]`, typed per each field's `type` (`String`→`string`,
 `Boolean`→`boolean`, `Int`/`Long`→`number`, etc. — `subfields[]` become a nested object type),
 respecting `optional`. Add two callback props: `onSuccess?: (result: TResponse) => void` and
 `onError?: (error: ApiError) => void`. **No other inputs** — no context/store reads, no fetching
 inside the component. All business data the component needs arrives via props from its parent.
 
+### Step 3a — Read the scenarios to understand behavior (not to implement rules)
+
+**Business logic lives in the backend. The UI never re-implements it.** Do not copy a scenario's
+rules (preconditions, limits, uniqueness, state checks) into the component as validation or guards —
+the backend decides, and a duplicated rule drifts the moment the model changes.
+
+Read every entry in `specifications[]` (and the beat runs in `storylines[]` containing this command)
+to understand **how the component should behave around the command**: what the user is trying to
+accomplish, what outcomes exist, and what each outcome must look like. Use them to decide:
+
+| Scenario shows | What it tells the UI |
+|---|---|
+| `when` this command → `then` EVENT(s) | the success outcome: what to confirm or reset after `postCommand` resolves, and what `onSuccess` hands the parent |
+| `when` this command → `then` an error / rejection (e.g. "already reserved") | the failure outcomes that exist: render each as its own readable message from the `ApiError` the backend returns — not one generic failure. The backend decides *whether* it fails; the UI only shows it |
+| `optional` fields, fields that vary between scenarios | which inputs are required vs. optional in the form (mirror the flags, no invented rules) |
+| `given` events before the command | context for what the user was doing — background to understand the flow, not logic to reproduce |
+| a `STORYLINE_NOTE` beat | background only |
+
+Rules:
+- Understand, don't implement: no business validation, no precondition checks, no computed outcomes
+  in the component. Only presentation: states (idle/submitting/success/error), required-vs-optional
+  inputs, and showing what the backend returns.
+- If a scenario's outcome needs a UI state the markup doesn't show, add the minimal state and note
+  the scenario in a one-line comment (e.g. `// spec: "already reserved" → backend 409 shown inline`).
+
 **Default — keep the logic in the component.** For an ordinary command (one form, one submit
 action, which is most of them) local state and the `postCommand` call live directly inside the
 component. This is the common case and needs nothing more:
@@ -211,9 +273,10 @@ is driven entirely by props, each sample is a **full set of prop values** — th
 renders this component in isolation (a `src/pages/` composition, or ad hoc while developing) to
 spread as props, e.g. `<ReserveBike {...sample1} onSuccess={...} />`.
 
-Add `sample-1.json` for the ordinary case (`command.fields[].example` values); add more numbered
-ones for other scenarios `specifications[]` calls out (an edge case, an `optional` field omitted,
-...). As in `build-state-view`, the same number across different components' samples is meant to
+Add `sample-1.json` for the ordinary case (`command.fields[].example` values); add a numbered
+sample for **each** scenario in `specifications[]` that changes what the component does (an invalid
+input that blocks submit, an `optional` field omitted, a precondition that disables the trigger).
+Take the values from the scenario's own example data. As in `build-state-view`, the same number across different components' samples is meant to
 represent one coherent scenario across the app, not an arbitrary per-component index.
 
 ## Step 5 — Context/Provider, only if the marked fragment needs shared local state
@@ -290,6 +353,13 @@ how many pages this app needs — not one page per slice.
      content there, passing whatever props it declares. Only substitute positions whose slice
      component already exists; leave any not-yet-built slice's marked area as the mockup's static
      placeholder until that slice is built and this step runs again for it.
+   - **Unmarked/unbuilt regions are not an excuse to hardcode data.** Static placeholder is only for
+     label/copy. A displayed data value (e.g. the contact's name and "role · organisation" line, the
+     selected organisation and the organisation dropdown options) must be bound to the read model that
+     carries it — if that read model's component exists (e.g. the contact list/details read), fetch
+     through it and pass the values down; if not, type the prop and leave a `// TODO(<read model>)`.
+     Never paste the mockup's example (or a slice's `samples/sample-1.json`) into the page as the
+     data. The page reads the entity id from the route/query param.
    - The page owns threading shared inputs (route/query params, the current session, etc.) down as
      props to each slice component — a slice component still only knows its own declared props, not
      the rest of the page or its siblings.
@@ -348,6 +418,8 @@ After writing the hook/component (and context/page/base page, if any), confirm:
   time, the provisional `/api/mock/...` path noted in a comment (Step 1).
 - At least one numbered sample exists under this slice's `samples/` folder, shaped exactly like
   this component's props.
+- Every scenario outcome (success, each named failure) has a rendered state, and **no business rule
+  from a scenario was re-implemented in the component** — the backend owns it.
 - If a screen was read in Step 2, the rendered JSX matches the marked (or whole, if unmarked)
   HTML fragment structurally — no invented buttons/fields the mockup didn't show, nothing from
   the mockup silently dropped.