@eventmodelers/cli 1.0.162 → 2.0.1

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

@@ -20,16 +20,15 @@ You work within **exactly ONE context at a time** — the one named in `.build-k
 
 0. Do not read the entire code base. `.build-kit/ARCHITECTURE.md` tells you where to look; read the code of the precedent slices its Slice map names and the files the slice actually touches. If a `Done` slice has no row in the Slice map, run `/learn-architecture slices` first.
 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, 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.
@@ -37,44 +36,27 @@ You work within **exactly ONE context at a time** — the one named in `.build-k
 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). 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 `Handover`, 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).
-
-```
-## Codebase Patterns
-- Example: "Services are transactional at the class level — never open a transaction in the controller"
-- Example: "New tables need a Flyway migration in db/migration, never edit an existing one"
-```
-
-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
 
@@ -85,7 +67,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-specific learnings
 
 Only update AGENTS.md if you have **genuinely reusable knowledge** that would help future work
@@ -130,9 +112,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/classic/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
 
@@ -50,7 +44,7 @@ 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 `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.
 
@@ -78,52 +72,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/kurrent/templates/build-kit/CLAUDE.md

@@ -65,10 +65,9 @@ Ignore case for files and slices in prompts. "CartItems" slice is the same as "c
 Do not change test files unless explicitly instructed, or the change brings the test in line with slice.json (e.g. step 4's field/spec diff): `src/test/java/**/*Test.java`.
 
 At the start of every session, read `.build-kit/AGENTS.md` if it exists to load accumulated project
-learnings.
+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
 
@@ -76,7 +75,7 @@ doing anything else.
 **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:
 

package/stacks/kurrent/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,7 +43,7 @@ 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.
 
 ## KurrentDB-specific
 

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

@@ -17,20 +17,19 @@ 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. Define the slice type and load the matching skill:
    - Write slice (has commands, no processors) → `build-state-change`
    - Read slice (has readModel / information flow) → `build-state-view`
    - Translation slice (`sliceType === "TRANSLATION"`) → read `description` and `notes` from slice.json for hints; default to `build-automation` if nothing else is specified
    - Automation slice (processors-array is not empty) → `build-automation`
-8. Write a short progress one liner after each step to progress.txt
+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
@@ -43,48 +42,27 @@ You work within **exactly ONE context at a time** — the one named in `.build-k
     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). 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 `Handover`, 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: Register every new event's type string in CqrsConfiguration.eventTypeResolver() as part of the slice
-- Example: Automations must catch CommandSubjectAlreadyExistsException/CommandSubjectDoesNotExistException locally
-- Example: Export write-model records as package-private unless another slice legitimately needs them
-```
-
-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
 
@@ -110,7 +88,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 specific learnings
 
 Only update AGENTS.md if you have **genuinely reusable knowledge** that would help future work
@@ -154,9 +132,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/kurrent/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.
 
@@ -78,48 +72,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/modeling-kit/templates/.claude/skills/attributes/SKILL.md

@@ -114,22 +114,6 @@ Stop traversal when:
 
 ---
 
-## Step 3e — Check the slices first (before any write)
-
-Only elements in a slice with status `Created` may be changed — and an element in no slice at all is
-not locked. The chain you resolved does not carry that: `get_attribute_chain` and `get_node` do not
-report `sliceStatus`. Read it now, once: `mcp__eventmodelers__get_board_outline { "boardId": "$BOARD_ID", "chapterId": "$CHAPTER_ID" }`
-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`, `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
-  chain is one logical edit — and follow `CLAUDE.md` § *Locked slices in a chat*: ask in the chat with a
-  `confirm` snippet (or a `changes` snippet listing the elements) naming the slice and its status, post no
-  `COMMENT` on the slice, and end the turn. (No chat to ask in? Change nothing and post a `COMMENT` on the slice.)
-
 ## Step 4 — Apply the change to the whole chain in one write
 
 Compute the updated `fields` array for **every** node in the chain first, in order (TARGET_NODE first, then backwards to SOURCE_NODE), then submit them all in a **single** `submit_node_events` call. Do not write one node, check it, and move to the next — the chain is one logical edit and `events[]` takes the whole batch.
@@ -196,7 +180,7 @@ Tell the user:
 - **Operation**: add `"<name>"` / rename `"<old>"` → `"<new>"`
 - **Chain**: list each element in order (type + title + cell)
 - **Updated**: which nodes were changed
-- **Skipped**: which nodes were skipped and why (field already exists / field not found / slice not `Created` — asked to confirm)
+- **Skipped**: which nodes were skipped and why (field already exists / field not found)
 - **Lineage**: where the attribute starts (`generated` on which element) and any `mapping` you set for a renamed hop
 
 Example output:

package/stacks/modeling-kit/templates/.claude/skills/detect-model-drift/SKILL.md

@@ -84,7 +84,7 @@ Why per commit: when the range contains the commit that **created** a file (e.g.
 | Group | Examples | Handling |
 |-------|----------|----------|
 | **Behavior** | controllers/handlers, services, entities/aggregates, events, projections/queries, schema & migrations, validation, templates/UI, tests | compared in Step 5 |
-| **Noise** | dependency bumps, build/CI config, gradle/maven wrappers, formatting-only diffs, docs, `.build-kit/`, `.claude/`, `.agent-modeling-kit/`, `.eventmodelers/`, `.mcp.json`, `CLAUDE.md`, `progress.txt`, generated files | listed in the report footer as *not relevant*, never a finding |
+| **Noise** | dependency bumps, build/CI config, gradle/maven wrappers, formatting-only diffs, docs, `.build-kit/`, `.claude/`, `.agent-modeling-kit/`, `.eventmodelers/`, `.mcp.json`, `CLAUDE.md`, generated files | listed in the report footer as *not relevant*, never a finding |
 
 **Build-kit commits vs. hand-made commits.** A commit is the build kit's only if an `Implementation — <Slice>` evidence note names its sha, or — without evidence notes — its subject is `feat: <Slice Name>` for a slice on the board. It implemented the board, so its files are the **as-built state**: compare it cheaply against that slice only. Every other commit — including any commit after it that touches the same files — is a **hand-made change** and the main subject of this skill: for each file the build kit wrote, the drift candidates are `git diff <buildSha>..<REF> -- <file>`, attributed to the later commits.
 

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-core-rules/SKILL.md

@@ -127,6 +127,8 @@ To make one: place a normal new node of the same type (COMMAND/EVENT/READMODEL o
 
 A linked copy is allowed to diverge from its origin afterward in the specific field(s) a newly-connected event actually drives — e.g. the "Updating a Read Model That Already Feeds a Screen" copy above, where `status` is updated post-link to the event's new value. The link establishes "this is the same underlying fact, not a duplicate" at creation time; it doesn't freeze the copy's fields identical to the origin's forever.
 
+**Scenarios (and storylines) are always added to the original, never to a copy.** A copy is the same fact reused, so its GWT spec lives once, in the origin's column. Before calling `add_scenario`/`add_storyline`, check `meta.linkedTo` on the target node and follow it to the origin. `eventmodeling-elaborating-scenarios` carries the step-by-step.
+
 Never delete the original (the node with no `linkedTo`) once copies of it exist — copies reference it, and removing it breaks every copy. `eventmodeling-checking-completeness` already treats any `linkedTo`-marked node as an intentional copy, never a duplicate or missing-slice gap to flag.
 
 See `place-element` Step 6a for the mechanical linking steps.

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-elaborating-scenarios/SKILL.md

@@ -138,8 +138,10 @@ timestamp no event carries), add that field to the element — don't move the va
 - `isError` marks a beat as an alternate/error branch off the previous beat.
 - A note beat (`type: "STORYLINE_NOTE"`, `refId: ""`, markdown in `note`) may sit anywhere and is
   skipped by the order rules — see "Notes — Last Resort Only" above before adding one.
-- `fields`, `expectEmptyList`, `exampleMode`, `examples` mirror the same fields GWT scenario steps
-  use, letting a beat show concrete example data the same way a "then" readmodel step does.
+- `fields`, `expectEmptyList`, `exampleMode`, `examples` are set **per beat** — a list READMODEL beat
+  carries its own expected rows (or `expectEmptyList: true`), so every intermediate state is
+  asserted, not just "not empty". This is storyline-only: in a GWT scenario the same data goes on
+  the scenario, never on the `then` step (see Step 4b).
 
 Post storylines via `POST .../timelines/:tl/columns/:col/storylines` (see `learn-eventmodelers-api`
 for the full endpoint contract) — the same auto-create-if-missing SCENARIO spec node scenarios use,
@@ -406,6 +408,8 @@ mcp__eventmodelers__get_nodes { "boardId": "<BOARD_ID>", "type": "CHAPTER", "pro
 
 If there is more than one chapter, ask the user which timeline to target.
 
+**Scenarios go on the original node, never on a linked copy.** If the COMMAND/READMODEL you are specifying has `meta.linkedTo` (it is a copy), resolve to the origin node (the one without `linkedTo`), and use the origin's timeline and column for `add_scenario`/`POST .../scenarios`. A copy's column gets no spec node of its own; the origin's column holds the one spec for that fact. If the origin sits on another timeline, post there. The same applies to storylines.
+
 For each command or view being specified, find its column: `mcp__eventmodelers__get_board_outline { "boardId": "<BOARD_ID>", "chapterId": "<TL>" }` lists every column (`columnId`, index) with the nodes in it — take the column whose node list holds that COMMAND or READMODEL. If the user named the slice, find the SLICE_BORDER node with that title (`get_nodes { "type": "SLICE_BORDER", "name": "<slice title>", "projection": "line" }` gives its id) or its column in the outline to get the `colId`. (REST fallback: `GET .../nodes/$TL?projection=cells` → `{rows, columns, cells}`; find the cell whose `nodeId` is the COMMAND/READMODEL and take its `colId`.)
 
 ### Step 2 — Load valid step elements
@@ -454,7 +458,7 @@ Pass `compact: true` — you already hold every scenario object you sent, so the
 
 ### Step 4b — List-type readmodel scenario fields
 
-When `then` contains a READMODEL whose `listElement` property is `true` — set on the node when it was created, per `eventmodeling-core-rules`'s READMODEL section and `eventmodeling-identifying-outputs`/`eventmodeling-designing-automation-chains` — add two fields **at the scenario level** (not inside `then`):
+When `then` contains a READMODEL whose `listElement` property is `true` — set on the node when it was created, per `eventmodeling-core-rules`'s READMODEL section and `eventmodeling-identifying-outputs`/`eventmodeling-designing-automation-chains` — add two fields **at the scenario level** (not inside `then`). Setting `examples`, `exampleMode` or `expectEmptyList` on the `then` step is not supported — the board never reads it, and the API rejects it with `SCENARIO_STEP_LIST_EXPECTATION_UNSUPPORTED`:
 
 **`examples`** — one object per expected row, keyed by the readmodel's snake_case field names. Without this the spec node renders with no expected output and the scenario is unverifiable.
 

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

@@ -25,14 +25,6 @@ From `$ARGUMENTS`, extract:
 
 ---
 
-## Step 1a — Locked slices
-
-Only elements in a slice with status `Created` may be changed (no slice at all = not locked).
-`get_board_outline` reports `sliceStatus` per column; read it for the chapter before writing, and for
-any target in a column with another status (`Done`, `Review`, `InProgress`, …) **write nothing to it**
-unless the task says the person already confirmed changing that locked slice. Otherwise ask in the chat
-with a `confirm` snippet — `CLAUDE.md` § *Locked slices in a chat* — and post no `COMMENT` on the slice.
-
 ## Step 1b — Many targets at once
 
 `target` is singular, but the common real request is "fill in the examples across this chapter". When you have more than one target, **do not run this skill once per element and do not fetch context a node at a time.**