@eventmodelers/cli 1.0.54 → 1.0.56

package/README.md

@@ -22,6 +22,8 @@ npx @eventmodelers/cli init --stack cratis-csharp    # Cratis (.NET/C#)
 npx @eventmodelers/cli init --stack opencqrs         # OpenCQRS (Java, EventSourcingDB)
 npx @eventmodelers/cli init --stack umadb            # UmaDB (Java)
 npx @eventmodelers/cli init --stack kurrent          # Kurrent (Java, KurrentDB)
+npx @eventmodelers/cli init --stack react            # React (frontend, board-polling sync) — TODO-marked, not yet filled in
+npx @eventmodelers/cli init --stack supabase-react   # React + Supabase (frontend, UI-only, realtime sync)
 ```
 
 The installer prompts for your API token, Organization ID, and Board ID from [app.eventmodelers.ai/account](https://app.eventmodelers.ai/account), scaffolds the stack into your project, and writes `.eventmodelers/config.json` with your credentials.
@@ -78,6 +80,10 @@ your-project/
 
 The seven backend stacks (`node`, `supabase`, `axon`, `cratis-csharp`, `opencqrs`, `umadb`, `kurrent`) also scaffold a real project skeleton into your project root (`templates/root/`) — source layout, build files, migrations, etc.
 
+`react` and `supabase-react` are two more registered stacks (installable the same way). `supabase-react` is real, filled-in content — a Vite + React 19 + TypeScript scaffold that authenticates and issues command POSTs via a Supabase session (`src/lib/api.ts`/`src/lib/supabase.ts`), plus `init-style-guide`/`learn-styleguide` skills so generated UI stays on-brand. It's UI-only: `.build-kit/CLAUDE.md` only routes `STATE_CHANGE`/`STATE_VIEW` slices to `build-state-change`/`build-state-view` — an `AUTOMATION` slice has no UI counterpart and gets flagged via `request-feedback` instead, since it belongs to whichever backend stack is installed alongside this one. It needs no overrides at all and uses `shared/build-kit`'s realtime agent as-is.
+
+`react` (the plain-REST/board-polling variant, no Supabase) is still in the same state as a fresh `init --build-kit` scaffold — CLAUDE.md, the `build-*` skills, and `templates/root/` are all TODO-marked placeholders, not real content, pending an equivalent reference implementation. It overrides `lib/ralph.js` (+ `ralph-claude.js`/`ralph-ollama.js`/`package.json`/`README.md`) for board-polling sync. Fill in the TODOs (and add a real `templates/root/` scaffold) against an actual project before relying on it.
+
 ## Skills
 
 Use skills in Claude Code with `/skill-name`:

package/cli.js

@@ -91,6 +91,30 @@ const STACKS = {
     useShared: true,
     needsBoardId: true,
   },
+  // Frontend-only kits (UI-only: build STATE_CHANGE/STATE_VIEW slices, not
+  // AUTOMATION — those belong to whichever backend stack is installed alongside).
+  // react overrides lib/ralph.js (+ralph-claude.js/ralph-ollama.js/package.json/
+  // README.md) for board-polling instead of the realtime channel every other
+  // stack uses; supabase-react needs no overrides at all — it uses
+  // shared/build-kit's realtime agent as-is. react's CLAUDE.md/build-*
+  // skills/templates/root are still TODO-marked, same as a fresh `init
+  // --build-kit` scaffold — supabase-react's are real, filled-in content
+  // (Vite + React 19 + TypeScript + Supabase, plus init-style-guide/
+  // learn-styleguide for on-brand generated UI).
+  react: {
+    label: 'React (frontend, board-polling sync) — TODO-marked, not yet filled in',
+    kitSubdir: 'build-kit',
+    kitDirName: '.build-kit',
+    useShared: true,
+    needsBoardId: true,
+  },
+  'supabase-react': {
+    label: 'React + Supabase (frontend, UI-only, realtime sync)',
+    kitSubdir: 'build-kit',
+    kitDirName: '.build-kit',
+    useShared: true,
+    needsBoardId: true,
+  },
 };
 
 // Not a stack — no backend scaffold, just skills + the agent loop. Installed via

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventmodelers/cli",
-  "version": "1.0.54",
+  "version": "1.0.56",
   "description": "Eventmodelers CLI — real-time Claude agent + skills for Claude Code, for any stack (Node, Supabase, Axon, Cratis, OpenCQRS, UmaDB, Kurrent, or modeling-only)",
   "type": "module",
   "bin": {

package/shared/build-kit/lib/ralph.js

@@ -407,7 +407,7 @@ function readCurrentContext(kitDir) {
 // Returns the first Planned slice IN THE CURRENT CONTEXT ONLY. If the current
 // context has no planned work, returns null so the loop waits — it must NEVER
 // cross into another context to find something to build.
-function getFirstPlannedSliceTitle(kitDir) {
+function getFirstPlannedSlice(kitDir) {
   const currentCtx = readCurrentContext(kitDir);
   if (!currentCtx) return null;
   const indexPath = join(kitDir, '.slices', currentCtx, 'index.json');
@@ -415,11 +415,95 @@ function getFirstPlannedSliceTitle(kitDir) {
   try {
     const { slices } = JSON.parse(readFileSync(indexPath, 'utf-8'));
     const planned = slices && slices.find((s) => (s.status || '').toLowerCase() === 'planned');
-    if (planned) return planned.slice || planned.id || null;
+    if (planned) return { id: planned.id ?? null, title: planned.slice || planned.id || null, ctx: currentCtx };
   } catch {}
   return null;
 }
 
+// If the exact same Planned slice (by id) comes back up this many times in a
+// row without its status ever leaving "Planned", onPlannedSlice is stuck on
+// it — declining to build it, or building it but its own status change keeps
+// getting reverted (e.g. a failed check). Rather than retry it forever (or
+// crash the whole loop, which would take down every other slice with it),
+// mark it Blocked with a note explaining why and move on to other work.
+// Critical for unsupervised/CI runs, which have no human watching to notice
+// a stall. Configurable for teams that want more slack.
+const MAX_PLANNED_ATTEMPTS = Number(process.env.RALPH_MAX_PLANNED_ATTEMPTS) || 2;
+
+// Marks a stuck slice Blocked (locally, and on the board if credentialed) and
+// records why, so the loop can move on instead of looping or exiting.
+async function blockStuckSlice(kitDir, cfg, credentialed, planned, attempts) {
+  const now = new Date().toISOString();
+  const reason = `Ralph loop picked up this slice ${attempts} times in a row without its status ever leaving ` +
+    `"Planned" — the build agent kept declining to build it, or kept building it but its own status change kept ` +
+    `getting reverted (e.g. a failed check). Auto-blocked to stop the loop from retrying it forever.`;
+
+  const indexPath = join(kitDir, '.slices', planned.ctx, 'index.json');
+  let folder;
+  try {
+    const indexData = JSON.parse(readFileSync(indexPath, 'utf-8'));
+    const entry = (indexData.slices ?? []).find((s) => s.id === planned.id);
+    if (entry) {
+      entry.status = 'Blocked';
+      entry.blockedReason = reason;
+      entry.blockedAt = now;
+      folder = entry.folder;
+      writeFileSync(indexPath, JSON.stringify(indexData, null, 2), 'utf-8');
+    }
+  } catch (err) {
+    console.error(`[ralph] Failed to write Blocked status to ${indexPath}:`, err.message);
+  }
+
+  if (folder) {
+    const sliceJsonPath = join(kitDir, '.slices', planned.ctx, folder, 'slice.json');
+    try {
+      if (existsSync(sliceJsonPath)) {
+        const sliceData = JSON.parse(readFileSync(sliceJsonPath, 'utf-8'));
+        sliceData.status = 'Blocked';
+        sliceData.blockedReason = reason;
+        sliceData.blockedAt = now;
+        writeFileSync(sliceJsonPath, JSON.stringify(sliceData, null, 2), 'utf-8');
+      }
+    } catch (err) {
+      console.error(`[ralph] Failed to write Blocked status to ${sliceJsonPath}:`, err.message);
+    }
+  }
+
+  try {
+    const progressPath = join(dirname(kitDir), 'progress.txt');
+    const existing = existsSync(progressPath) ? readFileSync(progressPath, 'utf-8') : '';
+    const note = `\n## ${now} — Slice auto-blocked\n\nSlice: ${planned.title} (id=${planned.id}, context=${planned.ctx})\n\n- ${reason}\n---\n`;
+    writeFileSync(progressPath, existing + note, 'utf-8');
+  } catch (err) {
+    console.error('[ralph] Failed to append progress.txt note:', err.message);
+  }
+
+  // Best-effort: also reflect Blocked on the board itself so a synced fetch
+  // doesn't just pull "Planned" back down over our local fix. Never fatal —
+  // this loop must keep going locally even if the board call fails.
+  if (credentialed) {
+    try {
+      await fetchJSON(`${cfg.baseUrl}/api/org/${cfg.organizationId}/boards/${cfg.boardId}/nodes/events`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'x-token': cfg.token, 'x-board-id': cfg.boardId, 'x-user-id': 'ralph-loop' },
+        body: JSON.stringify([{
+          id: randomUUID(),
+          eventType: 'node:changed',
+          nodeId: planned.id,
+          boardId: cfg.boardId,
+          timestamp: Date.now(),
+          changedAttributes: ['sliceStatus'],
+          meta: { sliceStatus: 'Blocked' },
+        }]),
+      });
+    } catch (err) {
+      console.error(`[ralph] Failed to sync Blocked status to the board:`, err.message);
+    }
+  }
+
+  console.error(`[ralph] ${reason} Marked "${planned.title}" (id=${planned.id}) as Blocked — moving on.`);
+}
+
 async function runWithRetry(label, fn) {
   while (true) {
     try {
@@ -441,6 +525,9 @@ async function ralphLoop(kitDir, cfg, onTask, onPlannedSlice, localOnly = false)
   // this back on.
   const credentialed = !localOnly && hasCredentials(cfg);
   let lastIdleCtx;
+  // Tracks consecutive sightings of the same Planned slice id — see
+  // MAX_PLANNED_ATTEMPTS above.
+  let stuckSlice = { id: null, count: 0 };
 
   while (true) {
     let didWork = false;
@@ -452,10 +539,21 @@ async function ralphLoop(kitDir, cfg, onTask, onPlannedSlice, localOnly = false)
       didWork = true;
     }
 
-    const plannedTitle = onPlannedSlice && getFirstPlannedSliceTitle(kitDir);
-    if (plannedTitle) {
+    const planned = onPlannedSlice && getFirstPlannedSlice(kitDir);
+    if (planned) {
+      stuckSlice = planned.id !== null && planned.id === stuckSlice.id
+        ? { id: stuckSlice.id, count: stuckSlice.count + 1 }
+        : { id: planned.id, count: 1 };
+
+      if (stuckSlice.count > MAX_PLANNED_ATTEMPTS) {
+        await blockStuckSlice(kitDir, cfg, credentialed, planned, stuckSlice.count);
+        stuckSlice = { id: null, count: 0 };
+        didWork = true;
+        continue;
+      }
+
       const prompt = readFileSync(backendPromptFile, 'utf-8');
-      await runWithRetry(`onPlannedSlice: building slice "${plannedTitle}"...`, () => onPlannedSlice(prompt));
+      await runWithRetry(`onPlannedSlice: building slice "${planned.title}"...`, () => onPlannedSlice(prompt));
       console.log(`[ralph] Slice build complete — waiting for next slice`);
       if (credentialed) await fetchAndPersistSlices(cfg, kitDir).catch(() => {});
       didWork = true;

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

@@ -114,6 +114,9 @@ SCENARIO       // GWT scenario
 LANE           // Timeline row
 SLICE_BORDER   // Slice boundary marker
 MARKDOWN       // Free-text markdown note — the content type a `feedback` lane accepts (see §2)
+VIDEO          // Embedded video (YouTube/Loom link in `data.url`). API/MCP-only — no palette button in
+               // the UI, but renders on the board like any other node. Free-floating: create it via
+               // `submit_node_events` with a position and no chapterId/cellId, same as a drawing.
 ```
 
 ---

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

@@ -57,6 +57,9 @@ Follow the **build-state-change** skill to create:
 
 **Do NOT create a `routes.ts`** for automations — the command is fired internally by the processor, not via HTTP.
 
+**No `routes.ts` also means no OpenAPI block** — an automation has no HTTP surface, so it contributes nothing to `/api-docs` or `/swagger.json`. If the slice also defines a todo-list read model that is queried over HTTP, that endpoint belongs to **build-state-view**, and its `@openapi` annotation is required there (see that skill's Step 6a).
+
+
 Refer to the build-state-change skill for the full command handler structure.
 
 ### Storyline-derived tests
@@ -269,4 +272,5 @@ src/common/
 - [ ] Command data fields map exclusively from fields available on the trigger event per slice.json — no invented mappings
 - [ ] No filtering conditions were invented — all conditions come from slice.json `description` or `comments`
 - [ ] No field names were assumed or guessed — if a field is not in slice.json, it is not in the code
-- [ ] If `storylines[]` is present, its command-handler segment was covered via build-state-change's storyline-derived tests (no separate reactor test needed)
+- [ ] If `storylines[]` is present, its command-handler segment was covered via build-state-change's storyline-derived tests (no separate reactor test needed)
+- [ ] No `routes.ts`, therefore no `@openapi` block — any todo-list read-model query endpoint is documented by build-state-view instead

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

@@ -244,7 +244,7 @@ Put these in their own `describe` block named after the storyline (same pattern
 
 File: `src/slices/{context}/{SliceName}/routes.ts`
 
-> **Concrete example**: `src/slices/example/routes.ts` — shows the full pattern with `requireUser`, `assertNotEmpty`, error mapping, and OpenAPI annotations. Read it before implementing.
+> **Pattern reference**: the template below is the full pattern — auth, error mapping, and the mandatory `@openapi` annotation (Step 5a). If the project already has slices under `src/slices/`, open one of their `routes.ts` files first and match it.
 
 ```typescript
 import {Request, Response, Router} from 'express';
@@ -254,6 +254,59 @@ import {{SliceName}Command, handle{SliceName}} from './{SliceName}Command';
 
 export const api = (): WebApiSetup => (router: Router): void => {
 
+    /**
+     * @openapi
+     * /api/{slicename}/{id}:
+     *   post:
+     *     tags: [{Context}]
+     *     summary: {slice title from slice.json}
+     *     description: {slice.json description — plus any comments that explain the endpoint}
+     *     security:
+     *       - bearerAuth: []
+     *     parameters:
+     *       - in: path
+     *         name: id
+     *         required: true
+     *         schema:
+     *           type: string
+     *         description: Stream id this command is applied to
+     *       - in: header
+     *         name: correlation_id
+     *         required: false
+     *         schema:
+     *           type: string
+     *     requestBody:
+     *       required: true
+     *       content:
+     *         application/json:
+     *           schema:
+     *             type: object
+     *             required: [{command fields without optional: true}]
+     *             properties:
+     *               {fieldName}:
+     *                 type: string
+     *                 example: {the field's own example from slice.json, if it has one}
+     *     responses:
+     *       '201':
+     *         description: Accepted — {EmittedEventName} appended
+     *         content:
+     *           application/json:
+     *             schema:
+     *               type: object
+     *               properties:
+     *                 ok:
+     *                   type: boolean
+     *                 next_expected_stream_version:
+     *                   type: string
+     *                 last_event_global_position:
+     *                   type: string
+     *       '401':
+     *         description: Not authenticated
+     *       '409':
+     *         description: {message errorMapping returns — one line per error code}
+     *       '500':
+     *         description: Server error
+     */
     router.post('/api/{slicename}/:id', async (req: Request, res: Response) => {
         const auth = await requireUser(req, res);
         if (auth.error) return;
@@ -306,6 +359,39 @@ const errorMapping = (code: string): string | null => {
 
 ---
 
+### Step 5a — OpenAPI annotation (required)
+
+`src/swagger.ts` builds the published OpenAPI document by scanning `./src/slices/**/routes.ts` for `@openapi` JSDoc blocks. A handler without one is **invisible** in Swagger UI (`/api-docs`) and in `/swagger.json` — the endpoint works, but nobody can find it. `src/swagger.ts` is shared infra and outside a slice's commit scope, so the block in this slice's own `routes.ts` is the only place the endpoint can be documented. The `openapi-annotation` commit check rejects a `routes.ts` whose handlers have no matching block.
+
+Everything in the block comes from slice.json — same rule as the code: no invented fields, no guessed types.
+
+| slice.json field `type` | OpenAPI schema |
+|---|---|
+| `String` | `type: string` |
+| `UUID` | `type: string`, `format: uuid` |
+| `Int` | `type: integer`, `format: int32` |
+| `Long` | `type: integer`, `format: int64` |
+| `Double` | `type: number`, `format: double` |
+| `Decimal` | `type: number` |
+| `Boolean` | `type: boolean` |
+| `Date` | `type: string`, `format: date` |
+| `DateTime` | `type: string`, `format: date-time` |
+| `Custom` | `type: object` |
+
+Mapping rules:
+
+- **path key** — the express path with `:param` rewritten as `{param}` (`/api/foo/:id` → `/api/foo/{id}`). If the two disagree, Swagger publishes a path that does not exist.
+- **tags** — `[{Context}]`, the slice's context, so every slice of one context groups under one heading.
+- **summary** — the slice title. **description** — slice.json `description`, plus any `comments[]` that explain what the endpoint does.
+- **requestBody properties** — exactly `commands[].fields`, minus the ones taken from the URL path or a header. Types from the table above.
+- **required** — every command field not marked `optional: true`.
+- **example** — only from the field's own `example` in slice.json. A field with no example gets no `example:` line; do not invent one.
+- **responses** — `'201'` with the body the handler actually returns; one `'409'` per error code in `errorMapping` (i.e. per failing specification); `'401'` whenever the handler enforces auth; `'500'`.
+
+A placeholder left unreplaced ships straight into the published spec, and `npm run build` will not catch it — open `/api-docs` and look at the rendered endpoint before marking the slice `Done`.
+
+---
+
 ## Step 6 — Wire up the route
 
 Find the application's router registration (usually `src/index.ts` or `src/app.ts`) and add:
@@ -353,4 +439,6 @@ Before marking this slice as `Done`, verify the implementation against slice.jso
 - [ ] Every entry in `specifications[]` maps to a test case in `{SliceName}.test.ts`
 - [ ] No business rules, defaults, or constraints were added that do not appear in slice.json `description` or `comments`
 - [ ] No field names were assumed or guessed — if a field is not in slice.json, it is not in the code
-- [ ] If `storylines[]` is present, a storyline-derived test was added for every COMMAND beat matching this slice's command
+- [ ] If `storylines[]` is present, a storyline-derived test was added for every COMMAND beat matching this slice's command
+- [ ] `routes.ts` carries an `@openapi` JSDoc block above every handler, and its path key matches the registered route with `:param` written as `{param}`
+- [ ] The documented request body is exactly `commands[].fields`, and every error code in `errorMapping` has a `'409'` line — no undocumented fields, no invented ones

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

@@ -352,7 +352,7 @@ Skip a beat pair when a COMMAND beat sits in between (that half belongs to build
 
 File: `src/slices/{context}/{SliceName}/routes.ts`
 
-> **Concrete example**: `src/slices/example/routes.ts` — shows the full pattern with `requireUser`, `assertNotEmpty`, error mapping, and OpenAPI annotations. Read it before implementing.
+> **Pattern reference**: the template below is the full pattern — auth, error mapping, and the mandatory `@openapi` annotation (Step 6a). If the project already has slices under `src/slices/`, open one of their `routes.ts` files first and match it.
 
 ```typescript
 import {Request, Response, Router} from 'express';
@@ -364,6 +364,48 @@ import createClient from '../../../supabase/api';
 
 export const api = (): WebApiSetup => (router: Router): void => {
 
+    /**
+     * @openapi
+     * /api/query/{slicename}-collection:
+     *   get:
+     *     tags: [{Context}]
+     *     summary: {slice title from slice.json}
+     *     description: {slice.json description — what this read model answers}
+     *     security:
+     *       - bearerAuth: []
+     *     parameters:
+     *       - in: query
+     *         name: _id
+     *         required: false
+     *         schema:
+     *           type: string
+     *         description: When set, returns the single row with this id instead of the full collection
+     *     responses:
+     *       '200':
+     *         description: The {SliceName} read model
+     *         content:
+     *           application/json:
+     *             schema:
+     *               oneOf:
+     *                 - $ref: '#/components/schemas/{SliceName}ReadModel'
+     *                 - type: array
+     *                   items:
+     *                     $ref: '#/components/schemas/{SliceName}ReadModel'
+     *       '401':
+     *         description: Not authenticated
+     *       '500':
+     *         description: Server error
+     * components:
+     *   schemas:
+     *     {SliceName}ReadModel:
+     *       type: object
+     *       properties:
+     *         id:
+     *           type: string
+     *         {fieldName}:
+     *           type: string
+     *           example: {the field's own example from slice.json, if it has one}
+     */
     router.get('/api/query/{slicename}-collection', async (req: Request, res: Response) => {
         try {
             const principal = await requireUser(req, res, true);
@@ -394,6 +436,40 @@ export const api = (): WebApiSetup => (router: Router): void => {
 
 ---
 
+### Step 6a — OpenAPI annotation (required)
+
+`src/swagger.ts` builds the published OpenAPI document by scanning `./src/slices/**/routes.ts` for `@openapi` JSDoc blocks. A handler without one is **invisible** in Swagger UI (`/api-docs`) and in `/swagger.json` — the endpoint works, but nobody can find it. `src/swagger.ts` is shared infra and outside a slice's commit scope, so the block in this slice's own `routes.ts` is the only place the endpoint can be documented. The `openapi-annotation` commit check rejects a `routes.ts` whose handlers have no matching block.
+
+Everything in the block comes from slice.json — same rule as the code: no invented fields, no guessed types.
+
+| slice.json field `type` | OpenAPI schema |
+|---|---|
+| `String` | `type: string` |
+| `UUID` | `type: string`, `format: uuid` |
+| `Int` | `type: integer`, `format: int32` |
+| `Long` | `type: integer`, `format: int64` |
+| `Double` | `type: number`, `format: double` |
+| `Decimal` | `type: number` |
+| `Boolean` | `type: boolean` |
+| `Date` | `type: string`, `format: date` |
+| `DateTime` | `type: string`, `format: date-time` |
+| `Custom` | `type: object` |
+
+Mapping rules:
+
+- **path key** — the express path exactly as registered (a query read model has no path params; if you do add one, rewrite `:param` as `{param}`).
+- **tags** — `[{Context}]`, the slice's context, so every slice of one context groups under one heading.
+- **summary** — the slice title. **description** — slice.json `description`, plus any `comments[]` that explain what the read model answers.
+- **schema properties** — exactly the read model fields from slice.json, the same set as the migration columns and the `{SliceName}ReadModel` type. Keep the JSON field spelling the route returns, not the snake_case column name, when they differ.
+- **required** — omit it unless slice.json marks fields as mandatory; a projection row can legitimately be sparse.
+- **example** — only from the field's own `example` in slice.json. A field with no example gets no `example:` line; do not invent one.
+- **`components.schemas`** — declaring the read model once and `$ref`-ing it keeps the single-row and collection responses in sync. swagger-jsdoc merges the `components` block from every scanned file, so name the schema `{SliceName}ReadModel` to avoid colliding with another slice's.
+- **responses** — `'200'` with the shape above, `'401'` whenever the handler enforces auth, `'500'`.
+
+A placeholder left unreplaced ships straight into the published spec, and `npm run build` will not catch it — open `/api-docs` and look at the rendered endpoint before marking the slice `Done`.
+
+---
+
 ## Step 7 — Wire up the route
 
 Find the application's router registration (usually `src/index.ts` or `src/app.ts`) and add:
@@ -434,8 +510,10 @@ src/common/
 - [ ] No `db.destroy()` calls in `evolve()` — the projection never owns its own connection
 - [ ] Tests use `runFlywayMigrations()` to apply the real schema
 - [ ] One test scenario per specification in slice.json
-o- [ ] Every field in the read model definition in slice.json has a column in the migration and a field in the TypeScript type — no invented columns
+- [ ] Every field in the read model definition in slice.json has a column in the migration and a field in the TypeScript type — no invented columns
 - [ ] Every event type in `events[]` is listed in the projection's `canHandle` — no assumed events
 - [ ] No extra columns or fields were added beyond what slice.json defines
 - [ ] No field names were assumed or guessed — if a field is not in slice.json, it is not in the code
-- [ ] If `storylines[]` is present, a storyline-derived test was added for every isolable read-model-chain transition (adjacent READMODEL beats with only EVENT beats between them)
+- [ ] If `storylines[]` is present, a storyline-derived test was added for every isolable read-model-chain transition (adjacent READMODEL beats with only EVENT beats between them)
+- [ ] `routes.ts` carries an `@openapi` JSDoc block above every handler, and its path key matches the registered route
+- [ ] The documented response schema lists exactly the read model fields from slice.json — same set as the migration columns and the `{SliceName}ReadModel` type

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

@@ -20,7 +20,9 @@ Read Events in src/events to understand the global structure.
 3. Follow TypeScript best practices for type definitions and interfaces
 
 Only check src/slices/{slice}/*.ts, do not check subfolders unless explicitely tasked to.
-If not tasked explicitely to change routes, ignore routes*.ts
+If not tasked explicitely to change routes, ignore routes*.ts — except the `routes.ts` of the slice you are
+building: the build skill owns that file, and its `@openapi` block has to stay in step with the slice's
+fields (the `openapi-annotation` check blocks the commit otherwise).
 
 Ignore case for files and slices in prompts. "CartItems" slice is the same as "cartitems"
 
@@ -72,6 +74,9 @@ It loads every check under `.build-kit/lib/checks/` and rejects the commit if an
   `.build-kit/.slices/{context}/{slice}/slice.json`
 - **spec-coverage** — heuristic: the test file needs at least as many `it(...)` blocks as slice.json
   has `specifications[]` entries
+- **openapi-annotation** — every handler in a slice's `routes.ts` needs an `@openapi` JSDoc block
+  above it, keyed on the registered path (`:param` written as `{param}`); without it the endpoint
+  never reaches `/api-docs` or `/swagger.json`
 - **tsc-build** — `npx tsc --noEmit` must still pass
 
 If a commit is rejected, split it — commit the out-of-scope file separately from the slice work, or add

package/stacks/node/templates/build-kit/lib/checks/60-openapi-annotation.cjs

@@ -0,0 +1,72 @@
+'use strict';
+
+// Every HTTP handler in a slice's routes.ts must carry an `@openapi` JSDoc block
+// directly above it. src/swagger.ts builds the published OpenAPI document by
+// scanning ./src/slices/**/routes.ts for those blocks, so a handler without one
+// is a working endpoint that never appears in Swagger UI (/api-docs) or in
+// /swagger.json — and swagger.ts itself is shared infra a slice commit may not
+// touch, so the block in routes.ts is the only place the endpoint can be
+// documented. See the build-state-change / build-state-view SKILL.md files for
+// the block template and the slice.json -> OpenAPI field mapping.
+//
+// Heuristic, not an OpenAPI parser: it checks that a block exists between the
+// previous handler and this one, and that the block names this handler's own
+// path (express `:param` rewritten as `{param}`). An invalid schema, or a
+// placeholder left unreplaced, still slips through — the rendered /api-docs
+// page is the real check.
+
+const fs = require('fs');
+const path = require('path');
+
+const ROUTES_FILE = /^src\/slices\/[^/]+\/[^/]+\/routes\.ts$/;
+const ROUTE_CALL = /\brouter\s*\.\s*(get|post|put|patch|delete)\s*\(\s*(['"`])([^'"`]+)\2/g;
+const OPENAPI_BLOCK = /\/\*\*(?:[\s\S]*?)@openapi(?:[\s\S]*?)\*\//g;
+
+// /api/foo/:id -> /api/foo/{id}
+const toOpenApiPath = (p) => p.replace(/:([A-Za-z0-9_]+)/g, '{$1}');
+
+module.exports = {
+  name: 'openapi-annotation',
+  run(ctx) {
+    const violations = [];
+
+    for (const { path: p } of ctx.changes) {
+      if (!ROUTES_FILE.test(p)) continue;
+
+      let content;
+      try {
+        content = fs.readFileSync(path.join(ctx.repoRoot, p), 'utf8');
+      } catch {
+        continue; // deleted — nothing to check
+      }
+
+      ROUTE_CALL.lastIndex = 0;
+      let cursor = 0; // start of the text belonging to the handler being checked
+      let call;
+      while ((call = ROUTE_CALL.exec(content))) {
+        const [, method, , routePath] = call;
+        const preceding = content.slice(cursor, call.index);
+        cursor = ROUTE_CALL.lastIndex;
+
+        const blocks = preceding.match(OPENAPI_BLOCK) || [];
+        if (blocks.length === 0) {
+          violations.push({
+            path: p,
+            reason: `${method.toUpperCase()} ${routePath} has no @openapi JSDoc block above it — the endpoint would be missing from /api-docs and /swagger.json`,
+          });
+          continue;
+        }
+
+        const documented = toOpenApiPath(routePath);
+        if (!blocks[blocks.length - 1].includes(documented)) {
+          violations.push({
+            path: p,
+            reason: `the @openapi block above ${method.toUpperCase()} ${routePath} does not document "${documented}" — the path key must match the registered route, with express ":param" written as "{param}"`,
+          });
+        }
+      }
+    }
+
+    return violations;
+  },
+};

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

@@ -0,0 +1,42 @@
+---
+name: build-automation
+description: TODO — one-line description of how a reactive slice (a processor/reactor that reacts to events and issues new commands) is implemented for your stack (see an existing stack's build-automation/SKILL.md under stacks/<name>/templates/.claude/skills/ for the level of detail expected)
+---
+
+# Build Automation Slice
+
+> **TODO — placeholder installed by `init --build-kit`.** Study an existing stack's
+> build-automation/SKILL.md (stacks/node, stacks/supabase, stacks/axon, or stacks/cratis-csharp,
+> under `templates/.claude/skills/`) for the level of detail expected, then rewrite
+> every section below for your stack's real conventions — file layout, naming, and
+> the actual framework/language idioms. Delete this callout once done.
+
+> Before doing anything else, read the slice definition from `.slices/{Context}/{slicename}/slice.json`.
+> This file is the **source of truth** for all fields, events, and metadata — never invent
+> fields not defined there. Keep this line verbatim; it applies to every stack.
+
+---
+
+## What an Automation Slice is
+
+TODO — describe a reactive slice (a processor/reactor that reacts to events and issues new commands) in terms of your stack's own primitives.
+
+## Step 1 — Read the slice.json
+
+From the slice definition, extract:
+- **sliceName** — the slice title
+- **context** — the bounded context
+- **processors[]** — the reactions this slice implements
+- **specifications[]** — test scenarios (given/when/then)
+
+> **Comments & description**: each element carries a `comments: string[]` array (board comments) and a `description` field — use them as implementation hints, and resolve consumed comments via `POST <BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/nodes/<nodeId>/comments/<commentId>/resolve`.
+
+---
+
+## Step 2 — TODO (your stack-specific implementation steps)
+
+TODO — file layout, naming conventions, framework idioms, how the handler/projection/reactor is wired up.
+
+## Quality gate
+
+TODO — this stack's build command and how to run only this slice's tests (not the full suite).

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

@@ -0,0 +1,43 @@
+---
+name: build-state-change
+description: TODO — one-line description of how a write-side slice (command validated against replayed events, new events emitted) is implemented for your stack (see an existing stack's build-state-change/SKILL.md under stacks/<name>/templates/.claude/skills/ for the level of detail expected)
+---
+
+# Build State Change Slice
+
+> **TODO — placeholder installed by `init --build-kit`.** Study an existing stack's
+> build-state-change/SKILL.md (stacks/node, stacks/supabase, stacks/axon, or stacks/cratis-csharp,
+> under `templates/.claude/skills/`) for the level of detail expected, then rewrite
+> every section below for your stack's real conventions — file layout, naming, and
+> the actual framework/language idioms. Delete this callout once done.
+
+> Before doing anything else, read the slice definition from `.slices/{Context}/{slicename}/slice.json`.
+> This file is the **source of truth** for all fields, events, and metadata — never invent
+> fields not defined there. Keep this line verbatim; it applies to every stack.
+
+---
+
+## What a State Change Slice is
+
+TODO — describe a write-side slice (command validated against replayed events, new events emitted) in terms of your stack's own primitives.
+
+## Step 1 — Read the slice.json
+
+From the slice definition, extract:
+- **sliceName** — the slice title
+- **context** — the bounded context
+- **commands[]** — list of commands with their data fields
+- **events[]** — list of events emitted by each command
+- **specifications[]** — test scenarios (given/when/then)
+
+> **Comments & description**: each element carries a `comments: string[]` array (board comments) and a `description` field — use them as implementation hints, and resolve consumed comments via `POST <BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/nodes/<nodeId>/comments/<commentId>/resolve`.
+
+---
+
+## Step 2 — TODO (your stack-specific implementation steps)
+
+TODO — file layout, naming conventions, framework idioms, how the handler/projection/reactor is wired up.
+
+## Quality gate
+
+TODO — this stack's build command and how to run only this slice's tests (not the full suite).