@eventmodelers/cli 1.0.53 → 1.0.55

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
@@ -1874,7 +1898,11 @@ program
 
     console.log(`🔎 Running checks from ${relative(cwd, checkScript)}...`);
     try {
-      execSync(`node "${checkScript}"`, { cwd: kitDir, stdio: 'inherit' });
+      // cwd must be the project root (not kitDir/.build-kit) — the script's
+      // `git diff --relative` scopes its output to cwd's subtree, so running
+      // it from inside .build-kit/ makes every changed file outside .build-kit/
+      // (i.e. everything under src/) invisible, and the check silently no-ops.
+      execSync(`node "${checkScript}"`, { cwd, stdio: 'inherit' });
     } catch (err) {
       process.exit(err.status || 1);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventmodelers/cli",
-  "version": "1.0.53",
+  "version": "1.0.55",
   "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/build-kit/lib/util/find-slice.cjs

@@ -21,6 +21,7 @@ function findSliceJson(repoRoot, context, sliceName) {
   const root = path.join(repoRoot, '.build-kit', '.slices');
   if (!fs.existsSync(root)) return null;
 
+  const wantContext = normalize(context);
   const wantSlice = normalize(sliceName);
   const candidates = [];
 
@@ -33,6 +34,7 @@ function findSliceJson(repoRoot, context, sliceName) {
 
   for (const contextDir of contextDirs) {
     if (!contextDir.isDirectory()) continue;
+    if (normalize(contextDir.name) !== wantContext) continue;
     const contextPath = path.join(root, contextDir.name);
     let sliceDirs;
     try {

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/build-kit/lib/check-commit-scope.cjs

@@ -22,7 +22,9 @@
 //                  all uncommitted changes by default, staged-only with --staged
 //   touchesSlice    true — this commit touches src/slices/{context}/{slice}/**
 //                   (the runner already gates on this before loading checks)
-//   repoRoot        absolute path to the repo root
+//   repoRoot        absolute path to this project's own root (process.cwd()) —
+//                   not the outer git repo's top-level when this project is a
+//                   subdirectory of a larger repo
 //   SLICE_PATTERN   RegExp matching a path inside a slice's own folder
 //
 // Zero dependencies — plain Node, so it works from git's pre-commit hook
@@ -45,14 +47,20 @@ function parseNameStatus(out) {
     });
 }
 
+// --relative scopes and rewrites paths relative to cwd instead of the git
+// top-level — required when this runs from a subdirectory of a larger repo
+// (e.g. a `backend/` folder inside a monorepo): without it, every path comes
+// back prefixed (`backend/src/slices/...`), SLICE_PATTERN never matches, and
+// the whole guard silently no-ops on every commit. `git ls-files` is already
+// cwd-relative by default, so it needs no such flag.
 function stagedChanges() {
-  return parseNameStatus(execSync('git diff --cached --name-status --no-renames', { encoding: 'utf8' }));
+  return parseNameStatus(execSync('git diff --cached --name-status --no-renames --relative', { encoding: 'utf8' }));
 }
 
 function allChanges() {
   // Working tree vs HEAD already covers both staged and unstaged edits to
   // tracked files; untracked (never-`git add`ed) files need a separate call.
-  const tracked = parseNameStatus(execSync('git diff HEAD --name-status --no-renames', { encoding: 'utf8' }));
+  const tracked = parseNameStatus(execSync('git diff HEAD --name-status --no-renames --relative', { encoding: 'utf8' }));
   const untracked = execSync('git ls-files --others --exclude-standard', { encoding: 'utf8' })
     .split('\n')
     .filter(Boolean)
@@ -102,7 +110,12 @@ function main() {
   const ctx = {
     changes,
     touchesSlice,
-    repoRoot: execSync('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim(),
+    // Deliberately process.cwd(), not `git rev-parse --show-toplevel` — this
+    // project can be a subdirectory of a larger repo (see the --relative note
+    // on allChanges/stagedChanges above), and every path here (and every path
+    // checks join onto repoRoot, e.g. `.build-kit/.slices/`) is relative to
+    // this project's own root, not the outer git repo's.
+    repoRoot: process.cwd(),
     SLICE_PATTERN,
   };
 

package/stacks/node/templates/root/.githooks/pre-commit

@@ -3,9 +3,16 @@
 # is versioned and shared by every clone instead of living only in .git/hooks/.
 set -e
 
-repo_root=$(git rev-parse --show-toplevel)
-script="$repo_root/.build-kit/lib/check-commit-scope.cjs"
+# Deliberately NOT `git rev-parse --show-toplevel` — when this project is a
+# subdirectory of a larger repo (a monorepo with `.githooks` installed inside
+# e.g. `backend/`), show-toplevel returns the outer repo's root, `.build-kit`
+# doesn't exist there, and the hook would silently no-op on every commit.
+# This script's own location is always `<project_root>/.githooks/pre-commit`,
+# so use that instead — and cd into it so check-commit-scope.cjs's own
+# process.cwd()/--relative git-diff logic sees the right root too.
+project_root=$(cd "$(dirname "$0")/.." && pwd)
+script="$project_root/.build-kit/lib/check-commit-scope.cjs"
 
 if [ -f "$script" ]; then
-  node "$script" --staged
+  (cd "$project_root" && node "$script" --staged)
 fi

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).

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

@@ -0,0 +1,42 @@
+---
+name: build-state-view
+description: TODO — one-line description of how a read-side slice (a projection/read model kept up to date from events) is implemented for your stack (see an existing stack's build-state-view/SKILL.md under stacks/<name>/templates/.claude/skills/ for the level of detail expected)
+---
+
+# Build State View Slice
+
+> **TODO — placeholder installed by `init --build-kit`.** Study an existing stack's
+> build-state-view/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 View Slice is
+
+TODO — describe a read-side slice (a projection/read model kept up to date from events) 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
+- **projections[]** / **queries[]** — the read model(s) this slice serves
+- **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/build-kit/CLAUDE.md

@@ -0,0 +1,62 @@
+# Project Configuration
+
+TODO — one-line pointer to where domain events live in your stack's scaffold (e.g. "Read Events in src/events to understand the global structure").
+
+## File Structure Constraints
+
+- **Strict Path Limitation**: TODO — the one directory glob the agent should stay inside by default (e.g. `src/slices/{slicename}/*`)
+- **Slice Organization**: Each feature/domain should be organized as a separate slice
+
+## Code Standards
+
+- **Language**: TODO
+- **Module System**: TODO
+- **Type Safety**: TODO (delete this line if the language has no static typing)
+
+## Development Guidelines
+
+1. Each slice should be self-contained and focused on a specific domain
+2. Maintain clear separation of concerns within each slice
+3. TODO — your stack's own idioms/best practices
+
+TODO — any other guardrails worth stating up front (e.g. ignore routes files unless
+asked, ignore tests unless asked, slice names are case-insensitive) — copy the ones
+that still apply from an existing stack's build-kit/CLAUDE.md.
+
+At the start of every session, read `.build-kit/AGENTS.md` if it exists to load accumulated project learnings.
+
+When starting to work on a slice, invoke the `update-slice-status` skill with `InProgress` status before doing anything else.
+
+## 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.**
+
+**If, at any point below, the slice's requirements are genuinely ambiguous, contradictory, or missing
+a decision you need in order to proceed — do not guess, and do not build anyway.** Invoke the
+`request-feedback` skill with the specific question; it posts the question as a comment on the slice
+and marks it `Blocked`, and you then stop work on this slice for this run. This is an escalation path,
+not a routine step — read `slice.json` and the matching build skill's own instructions fully first;
+most slices are fully specified and need none of this.
+
+When asked to build a slice, always follow this flow:
+
+1. Read the slice definition from `.build-kit/.slices/<context>/<slicename>/slice.json`.
+2. Determine the slice type:
+   - **Translation** — `sliceType === "TRANSLATION"` → read `description` and `notes` from slice.json for hints; default to `/build-automation` if nothing else is specified
+   - **Automation** — `processors` array is non-empty → invoke `/build-automation`
+   - **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.
+5. Run quality checks (TODO: this stack's build + test commands), then the slice tests only.
+6. If checks pass, commit with `feat: [Slice Name]` and set slice status to `Done`.
+
+After you are done, automatically run the tests for the slice that was edited.
+
+## Example Slice Structure
+
+TODO — a short tree showing where one slice's files land, e.g.:
+```
+TODO
+```

package/stacks/react/templates/build-kit/README.md

@@ -0,0 +1,79 @@
+# .build-kit
+
+Ralph's runtime directory. Contains the agent loop, board poller, prompts, and Claude skills.
+
+> This is the **react** (API-access) stack — it talks to the board purely through
+> the plain REST `slicedata` endpoint on `api.eventmodelers.ai`, polled on an interval.
+> There is no Supabase/PocketBase realtime subscription and no direct database table
+> access anywhere in this kit. For instant push notifications instead of polling, use
+> the `supabase-react` stack.
+
+## Quick start
+
+```bash
+# Claude (default)
+node .build-kit/ralph-claude.js
+
+# Local Ollama model — run `ollama serve` first
+OLLAMA_MODEL=qwen3.5:9b node .build-kit/ralph-ollama.js
+
+# Custom project directory (defaults to the parent of .build-kit)
+node .build-kit/ralph-claude.js /path/to/project
+```
+
+## Files
+
+**Entry points** (top level):
+
+| File | Purpose |
+|------|---------|
+| `ralph-claude.js` | Runs the full loop using Claude Code as the executor |
+| `ralph-ollama.js` | Runs the full loop using a local Ollama model |
+| `ralph.sh` | Shell-based loop — alternative to the JS entry points |
+
+**Internals** (`lib/`):
+
+| File | Purpose |
+|------|---------|
+| `lib/ralph.js` | Shared library — board poller + loop logic; imported by the entry points |
+| `lib/ollama-agent.js` | Ollama executor — called by `ralph-ollama.js`, can also run manually |
+| `lib/agent.sh` | Thin shell wrapper around `claude` — called by `ralph.sh` |
+| `lib/prompt.md` | Phase 1 prompt: tells Claude how to load a slice from the board |
+| `lib/backend-prompt.md` | Phase 2 prompt: tells Claude how to build a planned slice |
+| `lib/AGENT.md` | Agent instructions included in Claude's context |
+
+## How it works
+
+**Phase 1** — triggered when `tasks.json` has entries:
+- The poller writes a task to `tasks.json` each time it notices a slice's status changed since the last poll
+- The loop picks it up and runs Claude (or Ollama) with `prompt.md`
+- Claude loads the slice data and updates `.slices/`
+
+**Phase 2** — triggered when any file in `.slices/` contains `"status": "Planned"`:
+- The loop runs Claude with `backend-prompt.md`
+- Claude implements the slice in the project
+- Phase 2 is Claude-only; Ollama mode skips it (ollama-agent handles its own queue)
+
+Both phases run in a continuous loop with a 3-second idle sleep. The board poller runs concurrently in the same process, re-fetching `slicedata/slices` every `RALPH_POLL_INTERVAL_MS` (default 10s — see `lib/ralph.js`).
+
+## Ollama configuration
+
+```bash
+OLLAMA_MODEL=qwen3.5:9b         # model to use (default: qwen3.5:9b)
+OLLAMA_URL=http://host:11434   # Ollama server URL (default: http://localhost:11434)
+```
+
+## Config
+
+Credentials are stored in `.build-kit/.eventmodelers/config.json` (written by `eventmodelers init`):
+
+```json
+{
+  "organizationId": "...",
+  "boardId": "...",
+  "token": "...",
+  "baseUrl": "https://api.eventmodelers.ai"
+}
+```
+
+Claude skills live in `.build-kit/.claude/skills/` and are available inside any Claude Code session started from `.build-kit/`.

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

@@ -0,0 +1,47 @@
+# Agent Learnings
+
+Patterns and gotchas discovered during task processing. Update this file whenever you encounter something reusable.
+
+## tasks.json
+
+- 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.
+
+## SliceChangedPayload fields
+
+```
+event           always "slice:changed"
+organizationId  org UUID or null
+boardId         board UUID
+sliceId         SLICE_BORDER node UUID — use this with /load-slice
+sliceTitle      human-readable slice name (may be null)
+sliceStatus     e.g. "Created", "InProgress", "Done", "Blocked" (may be null)
+timestamp       unix ms when the change was emitted
+```
+
+## Slice files
+
+The board poller writes one file per slice on startup and after each poll tick that detects a change:
+
+```
+.slices/<context>/<sliceName>.json
+```
+
+- `<context>` is the slice's context value, or `default` if none.
+- `<sliceName>` is the slice title lowercased with spaces and the `"slice:"` prefix removed (e.g. `"slice: Enable User"` → `enableuser`).
+
+These files are always up to date — read them directly before invoking any skill.
+
+## Skill Usage
+
+- Always run `/connect` first to load credentials from `.eventmodelers/config.json` before calling any other skill.
+- `/load-slice sliceId=<uuid>` re-fetches all slices from the API, refreshes the slice files, and returns the requested slice. Use it when you need a guaranteed-fresh view of a specific slice.
+- Read `.slices/<context>/<sliceName>.json` directly when you already know the context and name and the file is recent enough.
+
+## Board API
+
+- 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.