@eventmodelers/cli 1.0.163 → 2.0.2

package/shared/scaffold/supabase/template/web/src/lib/api.ts.tmpl

@@ -0,0 +1,226 @@
+import { supabase } from './supabase';
+
+/**
+ * Common API client — the ONLY place that knows about base URLs, auth headers,
+ * correlation/causation tracing, and how to reach Supabase tables. Slice components
+ * must never call `fetch` directly, read the Supabase session, or import
+ * `./supabase` themselves — they call `postCommand`/`queryReadModel` and handle only
+ * the request/response shape their command/read model defines.
+ *
+ * Every call here has two implementations: a real one (Supabase) and a mock one that
+ * serves a numbered sample instead. This is what makes every slice component testable
+ * in isolation — flip `VITE_DATA_MODE` to `mock` and every read/write in the app is
+ * served from `samples/sample-<VITE_MOCK_SAMPLE>.json` files instead of a live backend.
+ */
+
+export const API_BASE = import.meta.env.VITE_API_BASE ?? '';
+
+/** `true` when reads/writes should be served from samples instead of Supabase/the backend. */
+export function isMockMode(): boolean {
+  return import.meta.env.VITE_DATA_MODE === 'mock';
+}
+
+/** Which numbered sample set is active in mock mode, e.g. `"1"`, `"2"`. */
+export function activeMockSample(): string {
+  return import.meta.env.VITE_MOCK_SAMPLE ?? '1';
+}
+
+async function getAuthHeaders(json = true): Promise<Record<string, string>> {
+  const {
+    data: { session },
+  } = await supabase.auth.getSession();
+
+  return {
+    // multipart bodies must leave Content-Type unset so the browser adds the boundary
+    ...(json ? { 'Content-Type': 'application/json' } : {}),
+    Authorization: session ? `Bearer ${session.access_token}` : '',
+    'x-correlation-id': crypto.randomUUID(),
+    'x-causation-id': crypto.randomUUID(),
+  };
+}
+
+/** 501 means the endpoint is modeled but its slice is not built yet (distinct from a 404 for a wrong URL). */
+export const NOT_BUILT_MESSAGE = 'This feature is not built yet.';
+
+function errorMessage(status: number, payload: { error?: string; message?: string } | undefined): string {
+  if (status === 501) return NOT_BUILT_MESSAGE;
+  return (payload && (payload.error || payload.message)) || `Request failed with status ${status}`;
+}
+
+/** True when an error from this module means "modeled, but its slice is not built yet" (HTTP 501). */
+export function isNotBuilt(err: unknown): boolean {
+  return err instanceof ApiError && err.status === 501;
+}
+
+export class ApiError extends Error {
+  status: number;
+  body: unknown;
+
+  constructor(message: string, status: number, body?: unknown) {
+    super(message);
+    this.name = 'ApiError';
+    this.status = status;
+    this.body = body;
+  }
+}
+
+/**
+ * POST a command to `path` (taken verbatim from the command's API description in
+ * slice.json — never invented) with `body` as the JSON payload. Resolves with the
+ * parsed JSON response, or throws `ApiError` on a non-2xx response.
+ *
+ * In mock mode this never hits the network — it resolves with `{ ok: true }` so a
+ * command component can be exercised (submitting/success states) fully offline.
+ */
+export async function postCommand<TResponse = unknown>(
+  path: string,
+  body: unknown,
+): Promise<TResponse> {
+  if (isMockMode()) {
+    return { ok: true } as TResponse;
+  }
+
+  const headers = await getAuthHeaders();
+  const res = await fetch(`${API_BASE}${path}`, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify(body),
+  });
+
+  const payload = await res.json().catch(() => undefined);
+
+  if (!res.ok) {
+    throw new ApiError(errorMessage(res.status, payload), res.status, payload);
+  }
+
+  return payload as TResponse;
+}
+
+/**
+ * POST a multipart/form-data command (e.g. one carrying a file) to `path`. Same contract as
+ * `postCommand`: resolves with the parsed JSON response, throws `ApiError` on a non-2xx
+ * response, and resolves with `{ ok: true }` locally in mock mode.
+ */
+export async function postForm<TResponse = unknown>(
+  path: string,
+  body: FormData,
+): Promise<TResponse> {
+  if (isMockMode()) {
+    return { ok: true } as TResponse;
+  }
+
+  const headers = await getAuthHeaders(false);
+  const res = await fetch(`${API_BASE}${path}`, { method: 'POST', headers, body });
+
+  const payload = await res.json().catch(() => undefined);
+
+  if (!res.ok) {
+    throw new ApiError(errorMessage(res.status, payload), res.status, payload);
+  }
+
+  return payload as TResponse;
+}
+
+export interface ReadModelParams {
+  /** `readmodel.apiEndpoint`, verbatim — the Postgres table/view name. */
+  table: string;
+  /** Column names to select, comma-separated (never `'*'`). */
+  select: string;
+  /** Simple equality filters, e.g. `{ customer_id: customerId }`. */
+  filters?: Record<string, unknown>;
+  /** `true` for a single-row read model (`.maybeSingle()`), `false` for a list. */
+  single?: boolean;
+}
+
+/**
+ * Read a read model's data — `params.table` via Supabase in the real implementation,
+ * or `samples[activeMockSample()]` in mock mode. `samples` is this component's own
+ * `samples/sample-*.json` map (see the component for how it's built); every read model
+ * component supplies its own, `queryReadModel` never reaches into a slice folder itself.
+ */
+export async function queryReadModel<T>(
+  params: ReadModelParams,
+  samples?: Record<string, T>,
+): Promise<T> {
+  if (isMockMode()) {
+    return mockSample(samples, `table "${params.table}"`);
+  }
+
+  let query = supabase.from(params.table).select(params.select);
+  for (const [column, value] of Object.entries(params.filters ?? {})) {
+    query = query.eq(column, value);
+  }
+
+  const { data, error } = params.single ? await query.maybeSingle() : await query;
+  // A read-model table that does not exist yet means its slice is not built: same 501 as the backend fallback.
+  if (error && (error.code === '42P01' || error.code === 'PGRST205')) throw new ApiError(NOT_BUILT_MESSAGE, 501, error);
+  if (error) throw new ApiError(error.message, 500, error);
+  return data as T;
+}
+
+/**
+ * GET a read model from a backend query route, e.g. `/api/query/orderlist-collection` —
+ * for read models whose table has RLS on with no policies (kept off Supabase's Data API),
+ * so `queryReadModel` would only ever see an empty result. Resolves with the parsed JSON
+ * response, or throws `ApiError` on a non-2xx response; mock-aware like `queryReadModel`.
+ */
+export async function getReadModel<T>(path: string, samples?: Record<string, T>): Promise<T> {
+  if (isMockMode()) {
+    return mockSample(samples, `"${path}"`);
+  }
+
+  const headers = await getAuthHeaders();
+  const res = await fetch(`${API_BASE}${path}`, { method: 'GET', headers });
+
+  const payload = await res.json().catch(() => undefined);
+
+  if (!res.ok) {
+    throw new ApiError(errorMessage(res.status, payload), res.status, payload);
+  }
+
+  return payload as T;
+}
+
+async function fetchFile(path: string): Promise<Blob> {
+  const headers = await getAuthHeaders(false);
+  const res = await fetch(`${API_BASE}${path}`, { method: 'GET', headers });
+  if (!res.ok) {
+    const payload = await res.json().catch(() => undefined);
+    throw new ApiError(errorMessage(res.status, payload), res.status, payload);
+  }
+  return res.blob();
+}
+
+/**
+ * GET a binary file (e.g. a generated PDF) from `path` with auth headers and open it in a new
+ * browser tab. In mock mode nothing is fetched; the call just resolves.
+ */
+export async function openFile(path: string): Promise<void> {
+  if (isMockMode()) return;
+
+  const url = URL.createObjectURL(await fetchFile(path));
+  window.open(url, '_blank');
+  setTimeout(() => URL.revokeObjectURL(url), 60_000);
+}
+
+/**
+ * GET a file (e.g. a template logo) from `path` with auth headers and return a blob URL for an
+ * `<img src>`, which would send no bearer token itself. The caller revokes it with
+ * `URL.revokeObjectURL`. In mock mode nothing is fetched; resolves with `null`.
+ */
+export async function fileUrl(path: string): Promise<string | null> {
+  if (isMockMode()) return null;
+
+  return URL.createObjectURL(await fetchFile(path));
+}
+
+function mockSample<T>(samples: Record<string, T> | undefined, source: string): T {
+  const n = activeMockSample();
+  const sample = samples?.[n];
+  if (sample === undefined) {
+    throw new Error(
+      `Mock mode is on (VITE_MOCK_SAMPLE=${n}) but no sample-${n}.json exists for ${source} — add one under this component's samples/ folder.`,
+    );
+  }
+  return sample;
+}

package/shared/scaffold/supabase/template/web/src/main.tsx.tmpl

@@ -0,0 +1,13 @@
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+__CSS_IMPORT__
+import { BrowserRouter } from 'react-router-dom'
+import App from './App.tsx'
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <BrowserRouter>
+      <App />
+    </BrowserRouter>
+  </StrictMode>,
+)

package/shared/skills/learn-eventmodelers-api/SKILL.md

@@ -646,7 +646,7 @@ Create a complete slice (1 column + its nodes automatically placed).
     interaction?: Partial<NodeData> & { rowId?: string, fields?: FieldDef[] }
     swimlane?: Partial<NodeData> & { rowId?: string, fields?: FieldDef[] }
   }
-  status?: 'Created' | 'Ready' | 'Planned' | 'InProgress' | 'Handover' | 'Review' | 'Done' | 'Blocked' | 'Assigned' | 'Informational'
+  status?: 'Created' | 'Ready' | 'Planned' | 'InProgress' | 'Waiting' | 'Review' | 'Done' | 'Blocked' | 'Assigned' | 'Informational'
 }
 ```
 
@@ -673,7 +673,7 @@ Create a standalone SLICE_BORDER node spanning an **existing** column. Unlike th
 {
   columnId: string   // id of an existing column on this timeline
   title: string      // slice title — always taken from this field, never derived
-  status?: 'Created' | 'Ready' | 'Planned' | 'InProgress' | 'Handover' | 'Review' | 'Done' | 'Blocked' | 'Assigned' | 'Informational'
+  status?: 'Created' | 'Ready' | 'Planned' | 'InProgress' | 'Waiting' | 'Review' | 'Done' | 'Blocked' | 'Assigned' | 'Informational'
   data?: Record<string, unknown>   // optional node.data payload
   meta?: Record<string, unknown>   // optional extra meta fields (type, colId, title are always set explicitly and cannot be overridden here)
 }
@@ -847,8 +847,8 @@ How much each slice of one context has been reworked — read-only, derived from
 for it.
 
 A slice's rework is read from its own SLICE_BORDER history. Going backwards means a step down the progress order
-(Created → Ready → Planned → Assigned → InProgress → Handover → Review → Done), or reaching `Blocked` from
-`Handover`/`Review`/`Done`;
+(Created → Ready → Planned → Assigned → InProgress → Waiting → Review → Done), or reaching `Blocked` from
+`Waiting`/`Review`/`Done`;
 `Informational` is never scored. `reopens` counts transitions leading away from `Done`, `changes` counts writes to the
 slice itself. This says nothing about edits to the elements inside a slice.
 
@@ -1066,11 +1066,22 @@ Send `x-agent-id` here too: a prompt the user addressed to one preferred agent (
 
 Note what this endpoint does *not* do: an agent that sends its id still gets every untargeted prompt on top of its own. A caller that wants only what was addressed to it has to hand the rest back itself (`POST /prompts/:id/status` with `status: 'ADDED'`), which is what `eventmodelers run --exclusive` does.
 
+The claim records its holder: `claimed_by` is the caller's `x-agent-id` (`null` if it sent none) and `claimed_at` the time. That is what tells a prompt an agent is working from one a crashed agent left behind. Before claiming, this endpoint puts prompts whose known holder has **no live heartbeat** (and that were claimed more than 45 s ago) back to `ADDED`; a prompt with no recorded holder is never handed back, and an agent that is still pinging keeps its prompts however long a turn takes. An agent that restarts under the same id finds what it was holding with `GET /prompts?claimed_by=<its id>&status=CLAIMED,IN_PROGRESS` and hands it back itself.
+
 **Query params**: `board_id` (required)
 **Response**: `200` — the claimed row (now `status: "CLAIMED"`), including its parsed `context` and the `hidden` flag · `404` — no `ADDED` prompts available
 
 ---
 
+### GET `/api/org/:orgId/prompts`
+List a board's prompts **with their status** — the only way to read a prompt's status. Read-only: nothing is claimed. Auth: `x-token` **and** a Supabase JWT (`Authorization: Bearer`) together, like `/prompts/next` — an agent uses the realtime token it already holds. A status write is unconditional (`CLAIMED` → `ADDED` works on a `DONE` prompt too), so an agent that wants to hand back prompts a crash left it holding looks here first and releases only the ones still `CLAIMED` / `IN_PROGRESS`.
+
+**Query params**: `board_id` (required) · `status` (optional, comma-separated subset of `ADDED`,`CLAIMED`,`IN_PROGRESS`,`DONE`) · `ids` (optional, comma-separated prompt ids, at most 200 — only these prompts of the board come back; an empty value asks about none, and the id of another board's prompt matches nothing) · `claimed_by` (optional, an agent id — only the prompts that agent holds) · `limit` (optional, default 200, max 500)
+**Response**: `200` — `{ "prompts": [ … ] }`, each row with `id`, `status`, `agent_id` (who it is addressed to), `claimed_by` / `claimed_at` (who holds it and since when), `priority`, `creation_time`, `node_id`, `comment_id`, the progress `comment` and the parsed `context`. Ordered like the claim: priority first, then oldest first.
+**Errors**: `400` missing `board_id`, unknown status (`PROMPT_STATUS_INVALID`), more than 200 ids or a bad `limit` · `403` the board is not in the token's organization
+
+---
+
 ### POST `/api/org/:orgId/prompts/:id/status`
 Set a prompt's status, optionally attaching a progress comment. Auth: `x-token` only (bot token — no user JWT needed, this is meant to be called directly by the agent working the prompt).
 
@@ -1084,6 +1095,8 @@ Set a prompt's status, optionally attaching a progress comment. Auth: `x-token`
 }
 ```
 
+Setting `ADDED` hands the prompt back to the queue and clears `claimed_by` / `claimed_at`; the other statuses leave the holder as it was.
+
 **Response**: `200` — the updated row
 **Errors**: `400` invalid/missing `status` · `403` token not for this prompt's org · `404` prompt not found · `409` (`PROMPT_STATUS_ALREADY_SET`) the prompt already carries that status — another agent already made this transition, so don't retry it
 

package/shared/skills/request-feedback/SKILL.md

@@ -16,8 +16,7 @@ Prefer `mcp__eventmodelers__*` tools when available (registered by the `connect`
 **The default is to assume and build.** A missing example value, an unclear field type, a status
 mapping, a referenced event that isn't modeled yet, a dependency slice that isn't built yet — none of
 these is a reason to stop. Pick the most sensible interpretation from `slice.json`, its
-`specifications[]` and the surrounding model, build the slice, and record each assumption in one line
-in `progress.txt` and as a code comment. **Read `slice.json` fully, and read the build skill's own
+`specifications[]` and the surrounding model, build the slice, and record each assumption in one line as a code comment. **Read `slice.json` fully, and read the build skill's own
 instructions and reference docs, before concluding anything is missing.**
 
 Invoke `request-feedback` **only if the slice literally cannot be built**: even with sensible

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

@@ -18,7 +18,7 @@ records that as a contract — the endpoint's **OpenAPI operation**, one per sli
 
 ## When
 
-**Only when handover is on** — the task request's `Handover: on|off` line (authoritative; the runner resolves `run --handover` over the project setting), else `"handover": true` in `.eventmodelers/config.json`. With handover **off/unset**, do nothing: publish no contract, write no `## UI Contract` section, and finish the slice as `Done` (Step 4). The contract exists only for the UI kit that picks up `Handover` slices.
+**Only when handover is on** — the task request's `Handover: on|off` line (authoritative; the runner resolves `run --handover` over the project setting), else `"handover": true` in `.eventmodelers/config.json`. With handover **off/unset**, do nothing: publish no contract, write no `## UI Contract` section, and finish the slice as `Done` (Step 4). The contract exists only for the UI kit that picks up `Waiting` slices.
 
 At the end of building a slice, **after** the endpoint exists (so the contract describes the real
 route, not the plan), before the final commit:
@@ -99,7 +99,7 @@ every MARKDOWN node of the slice's column as a plain string in `slice.json` `not
 `outline` / `fields` / `specs` projections leave `notes` out). The UI build kit therefore needs no
 extra file and no board call.
 
-## Step 4 — Completion status: `Handover` instead of `Done`
+## Step 4 — Completion status: `Waiting` instead of `Done`
 
 A slice with a UI is only finished once the UI kit has built its half. Whether this build kit hands
 over is decided per run, in this order: the task request's `Handover: on|off` line (authoritative — the
@@ -107,9 +107,11 @@ runner resolves `run --handover` over the project setting), else `"handover": tr
 `.eventmodelers/config.json` (saved by `init --handover` / `eventmodelers config --handover on|off`).
 
 - **On** — the build kit's "set the slice to `Done`" for a STATE_VIEW / STATE_CHANGE slice means
-  **`Handover`** instead: after the contract is published and the commit/merge succeeded, via
-  `update-slice-status` (mirrored in the local `index.json`). The UI kit claims `Handover` slices and sets
-  `Done` when its UI is built.
+  **`Waiting`** instead: after the contract is published and the commit/merge succeeded. Where the build
+  kit's prompt says to call `update-slice-status` (a queued task), set `Waiting` through it,
+  mirrored in the local `index.json`. For a run-loop build (the task request names the slice), record it
+  with `npx @eventmodelers/cli slice-status Waiting` — the run loop pushes it to the board; do not call
+  `update-slice-status`. The UI kit claims `Waiting` slices and sets `Done` when its UI is built.
 - **Off / unset** — nothing changes: `Done`.
 - Automations and translations have no UI → always `Done`.
 

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

@@ -26,7 +26,7 @@ Valid status values (case-sensitive):
 | `Ready` | Modeling is done — specified and ready to be planned for implementation |
 | `Planned` | Work is planned — queued for the backend build kit |
 | `InProgress` | Work is actively in progress |
-| `Handover` | Backend built and its UI contract published (`## UI Contract` in the slice's markdown note) — queued for the UI build kit |
+| `Waiting` | Backend built and its UI contract published (`## UI Contract` in the slice's markdown note) — queued for the UI build kit |
 | `Review` | Ready for review |
 | `Done` | Completed |
 | `Blocked` | Blocked by something |

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

@@ -33,16 +33,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:
 
@@ -53,9 +53,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 (`./mvnw compile -q`, 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 (`./mvnw compile -q`, 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/axon/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/axon/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 `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 event sourcing aggregate patterns for all state changes
-- Example: Always use @CommandHandler on the aggregate for write slices
-- Example: Export query result types from the slice package
-```
-
-Only add patterns that are **general and reusable**, not story-specific details.
+- 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.