@eventmodelers/cli 0.0.36 → 0.0.38

package/README.md

@@ -16,9 +16,10 @@ npx @eventmodelers/cli init --stack supabase         # Supabase
 npx @eventmodelers/cli init --stack axon             # Axon Framework (Java/Kotlin)
 npx @eventmodelers/cli init --stack cratis-csharp    # Cratis (.NET/C#)
 npx @eventmodelers/cli init-modeling                 # skills + agent loop only, no backend scaffold
+npx @eventmodelers/cli init --build-kit              # blank build-kit scaffold for a stack not built into this CLI yet
 ```
 
-`init-modeling` isn't a stack — it's the option for when you don't want a backend scaffolded at all, just the skills and the agent loop.
+`init-modeling` isn't a stack — it's the option for when you don't want a backend scaffolded at all, just the skills and the agent loop. `init --build-kit` isn't one of the four either — it installs the same `.build-kit/` + skills shape as a real stack, but with TODO-marked placeholders instead of real content, for integrating a stack this CLI doesn't support yet (see "Adding a stack" below).
 
 The installer prompts for your API token, Organization ID (and Board ID, for the four backend stacks) from [app.eventmodelers.ai/account](https://app.eventmodelers.ai/account).
 
@@ -227,6 +228,7 @@ npx @eventmodelers/cli init --stack <name>          # scaffold a stack + install
 npx @eventmodelers/cli init --stack <name> --global # same, but skills go to ~/.claude/skills/ (every project)
 npx @eventmodelers/cli init-modeling                # skills + agent loop only, no backend scaffold (alias: modeling)
 npx @eventmodelers/cli init-modeling --global       # same, but skills go to ~/.claude/skills/ (every project)
+npx @eventmodelers/cli init --build-kit             # blank build-kit scaffold (TODO placeholders) for a stack not built into this CLI yet
 npx @eventmodelers/cli init-mcp                     # register the MCP server in .claude/settings.json (+ optionally another harness)
 npx @eventmodelers/cli init-config                  # credentials only, no scaffold — writes ./.eventmodelers/config.json
 npx @eventmodelers/cli init-config --global         # same, but writes organizationId + token to ~/.eventmodelers/config.json
@@ -281,6 +283,12 @@ EVENTMODELERS_ORGANIZATION_ID=... EVENTMODELERS_BOARD_ID=... EVENTMODELERS_TOKEN
 
 Each stack lives under `stacks/<name>/templates/` with `.claude/` (skills), `root/` (spread into the project root), and either `build-kit/` (backend stacks) or `kit/` (modeling-only) for the agent runner. Files identical across all backend stacks live once in `shared/build-kit/` and get layered in automatically — only put stack-specific overrides under `stacks/<name>/templates/build-kit/`. Skills with no stack-specific content (`connect`, `learn-eventmodelers-api`, `update-slice-status`) work the same way via `shared/skills/` — a new stack gets them for free without copying anything; add a skill there only once it needs a stack-specific fork.
 
+`init --build-kit` (see above) installs exactly that layout into a real project — `.build-kit/CLAUDE.md`, `lib/prompt.md`, `lib/backend-prompt.md`, and `.claude/skills/build-{state-change,state-view,automation}/SKILL.md` — but with TODO-marked placeholders instead of real content, since there's no fixed backend to generate them from. Fill in the TODOs against the actual stack you're integrating (build/test commands, file layout, framework idioms) while building something real with it. Once it works, promote it to a first-class stack:
+
+1. Copy `.build-kit/` → `stacks/<name>/templates/build-kit/`, `.claude/skills/build-*` → `stacks/<name>/templates/.claude/skills/`, and whatever `root/` scaffold you built → `stacks/<name>/templates/root/`.
+2. Add an entry for `<name>` to the `STACKS` object in `cli.js` (`label`, `kitSubdir: 'build-kit'`, `kitDirName: '.build-kit'`, `useShared: true`, `needsBoardId: true`).
+3. Add it to this README's stack list, the "What gets installed" section, and the `stacks` command's output (generated from `STACKS`, so nothing to add there beyond the entry itself).
+
 ## Contributors
 
 | Contributor | Contribution |

package/cli.js

@@ -107,7 +107,24 @@ const BRIDGE_KIT = {
   needsBoardId: true,
 };
 
-const KIT_DIR_NAMES = [...new Set([...Object.values(STACKS), MODELING_KIT, BRIDGE_KIT].map((s) => s.kitDirName))];
+// Also not a stack — installed via `init --build-kit` instead of `init --stack <name>`.
+// useShared:true, same as any real backend stack: it reuses build-kit's cold-spawn/
+// tasks.json engine as-is (lib/ralph.js). Its templates/build-kit/CLAUDE.md,
+// lib/{prompt,backend-prompt}.md, and templates/.claude/skills/build-*/SKILL.md are
+// TODO-marked placeholders instead of real stack content (see stacks/blank/templates)
+// — this is for a stack that isn't built into this CLI yet: fill in the TODOs against
+// the real project this installs into, then optionally contribute it back as a
+// first-class entry in STACKS (see README, "Adding a stack").
+const BLANK_BUILD_KIT = {
+  key: 'blank',
+  label: 'Build kit — blank scaffold to fill in for a stack not built into this CLI yet',
+  kitSubdir: 'build-kit',
+  kitDirName: '.build-kit',
+  useShared: true,
+  needsBoardId: true,
+};
+
+const KIT_DIR_NAMES = [...new Set([...Object.values(STACKS), MODELING_KIT, BRIDGE_KIT, BLANK_BUILD_KIT].map((s) => s.kitDirName))];
 
 // Same principle Playwright MCP uses per harness: one shared server, but each coding
 // agent has its own registration mechanism. Automate the ones with a real, verified
@@ -264,19 +281,28 @@ function maskSecret(value) {
 // scripted installs) — the first interface can read ahead and consume lines meant
 // for later prompts, leaving the next one waiting on a stream that already ended.
 let sharedRl = null;
+let sharedRlLines = null;
 function getSharedRl() {
   if (!sharedRl) {
     sharedRl = createInterface({ input: process.stdin, output: process.stdout });
+    sharedRlLines = sharedRl[Symbol.asyncIterator]();
   }
   return sharedRl;
 }
 
-async function prompt(question) {
-  return new Promise((resolve) => {
-    getSharedRl().question(question, (answer) => {
-      resolve(answer.trim());
-    });
-  });
+// Pulls one line from the shared readline's own async iterator rather than calling
+// its `.question()` — `.question()` attaches a one-shot 'line' listener *after* the
+// prompt is issued, but when stdin is piped (a file, `<<<`, scripted/CI input) readline
+// parses and emits 'line' events for an entire buffered chunk synchronously as soon as
+// it arrives. So a second `.question()` call in the same process can miss a line that
+// was already emitted — and dropped, no listener attached yet — before it was even
+// called, hanging forever. Pulling from the iterator instead queues each line until
+// something asks for it, so nothing emitted ahead of time is ever lost between prompts.
+async function prompt(question = '') {
+  getSharedRl();
+  if (question) process.stdout.write(question);
+  const { value, done } = await sharedRlLines.next();
+  return (done ? '' : value).trim();
 }
 
 // Reads a pasted block of credentials, which may span one line (minified JSON,
@@ -286,7 +312,7 @@ async function prompt(question) {
 async function promptPasteBlock() {
   const lines = [];
   while (lines.length < 20) {
-    const line = await new Promise((resolve) => getSharedRl().question('', resolve));
+    const line = await prompt();
     if (line.trim() === '') {
       if (lines.length > 0) break;
       continue;
@@ -793,6 +819,28 @@ async function installStack(stackKey, stackCfg, options = {}) {
 
     // --- 3. Create the kit dir and install the agent runner ---
     const kitDir = join(targetDir, stackCfg.kitDirName);
+
+    // A non-empty kit dir here almost always means a previous install someone has
+    // since customized (e.g. filled in a `--build-kit` scaffold's TODOs, or hand-edited
+    // CLAUDE.md/AGENT.md) — the copy below overwrites same-named files unconditionally,
+    // so ask before silently clobbering that work. --print and --force both imply an
+    // explicit, non-interactive "yes" (mirrors how --force already means "overwrite
+    // without re-asking" for credentials).
+    if (existsSync(kitDir) && readdirSync(kitDir).length > 0 && !options.print && !options.force) {
+      const choice = await selectPrompt(
+        `${stackCfg.kitDirName} is not empty. Should we continue?`,
+        [
+          { label: 'No — cancel', value: 'no' },
+          { label: 'Yes — continue (files with matching names will be overwritten)', value: 'yes' },
+        ],
+        0,
+      );
+      if (choice === 'no') {
+        console.log('\n❌ Cancelled — nothing was installed.');
+        process.exit(1);
+      }
+    }
+
     mkdirSync(kitDir, { recursive: true });
     console.log(`📦 Installing agent kit into ${stackCfg.kitDirName}/...`);
 
@@ -1313,7 +1361,11 @@ program
 // cleanup commands that are meant to work — and report something useful — whether
 // or not a kit is present, and fetch only needs credentials plus somewhere to write
 // .slices/ (cwd, absent a kit dir — see lib/fetch.js), no kit-specific files.
-const NO_INIT_REQUIRED = new Set(['init', 'init-config', 'stacks', 'status', 'config', 'uninstall', 'fetch']);
+// activate-context/set-slice-status are the same story minus even the credentials — they
+// only ever read/write an already-fetched .slices/, and report their own hint (run `fetch`
+// first) when that's missing. set-slice-status only touches credentials at all for --remote,
+// which prompts for them itself the same way fetch does.
+const NO_INIT_REQUIRED = new Set(['init', 'init-config', 'stacks', 'status', 'config', 'uninstall', 'fetch', 'activate-context', 'set-slice-status']);
 
 program.hook('preAction', (_thisCommand, actionCommand) => {
   if (NO_INIT_REQUIRED.has(actionCommand.name())) return;
@@ -1346,22 +1398,24 @@ function credentialOverridesFromOpts(opts) {
 credentialFlags(program
   .command('init')
   .alias('install')
-  .description('Scaffold a stack + install the agent kit into the current directory (or --modeling for skills + agent loop only, no backend scaffold; or --bridge to translate board slices into another spec framework; or --git to install a community/custom build kit from a git repo)')
+  .description('Scaffold a stack + install the agent kit into the current directory (or --modeling for skills + agent loop only, no backend scaffold; or --bridge to translate board slices into another spec framework; or --build-kit for a blank build-kit scaffold to fill in for a stack not built into this CLI yet; or --git to install a community/custom build kit from a git repo)')
   .option('--stack <name>', `Stack to install (${Object.keys(STACKS).join(', ')}), or a name of your choosing when combined with --git`)
   .option('--git <url>', 'Install a build kit not built into this CLI by cloning this git repo (used with --stack <name> to name it) — the repo must mirror the templates/.claude, templates/root, templates/<kitSubdir> layout of this CLI\'s own stacks/<name>/templates, optionally with a stack.json declaring label/kitSubdir/useShared/needsBoardId')
   .option('--branch <name>', 'Branch to clone — only meaningful with --git (defaults to the repo\'s default branch)')
-  .option('--modeling', 'Install skills + the agent loop only — no backend scaffold. Mutually exclusive with --stack/--bridge.')
-  .option('--bridge', 'Install a bridge kit — translates board slices into another spec framework instead of building code. Mutually exclusive with --stack/--modeling. Requires --target.')
+  .option('--modeling', 'Install skills + the agent loop only — no backend scaffold. Mutually exclusive with --stack/--bridge/--build-kit.')
+  .option('--bridge', 'Install a bridge kit — translates board slices into another spec framework instead of building code. Mutually exclusive with --stack/--modeling/--build-kit. Requires --target.')
   .option('--target <name>', `Bridge target framework (${Object.keys(BRIDGE_TARGETS).join(', ')}) — only meaningful with --bridge`)
   .option('--hook <command>', 'Persist a default shell command hook for `bridge` to run per batch of slice changes instead of Claude/Ollama (e.g. commit + push .slices/ for a CI pipeline to pick up) — only meaningful with --bridge. Can also be set per-run with `bridge --hook`.')
+  .option('--build-kit', 'Install a blank build-kit scaffold (.build-kit/ + .claude/skills/build-*/SKILL.md placeholders, all TODO-marked) for a stack not built into this CLI yet — no fixed backend. Mutually exclusive with --stack/--modeling/--bridge.')
   .option('--global', 'Install skills into ~/.claude/skills/ instead of the project — available in every project')
   .option('-f, --force', 'Re-prompt for credentials even if a config already has everything required — overwrites the existing config.json'))
   .action(async (opts, command) => {
     const globalOpts = command.optsWithGlobals();
 
-    if (opts.modeling || opts.bridge) {
-      if (opts.stack || opts.git || (opts.modeling && opts.bridge)) {
-        console.error('❌ --stack/--git, --modeling, and --bridge are mutually exclusive — pick one.');
+    if (opts.modeling || opts.bridge || opts.buildKit) {
+      const modeCount = [opts.modeling, opts.bridge, opts.buildKit].filter(Boolean).length;
+      if (opts.stack || opts.git || modeCount > 1) {
+        console.error('❌ --stack/--git, --modeling, --bridge, and --build-kit are mutually exclusive — pick one.');
         process.exit(1);
       }
     }
@@ -1377,6 +1431,17 @@ credentialFlags(program
       return;
     }
 
+    if (opts.buildKit) {
+      await installStack(BLANK_BUILD_KIT.key, BLANK_BUILD_KIT, {
+        configPath: globalOpts.config,
+        print: globalOpts.print,
+        global: opts.global,
+        force: opts.force,
+        credentialOverrides: credentialOverridesFromOpts(opts),
+      });
+      return;
+    }
+
     if (opts.bridge) {
       if (!opts.target) {
         console.error(`❌ --bridge requires --target (${Object.keys(BRIDGE_TARGETS).join(', ')}).`);
@@ -1766,6 +1831,212 @@ program
     }
   });
 
+program
+  .command('activate-context')
+  .description('Choose which fetched context is active — writes .slices/current_context.json, which `run`/bridge/listen treat as sticky and never cross out of on their own')
+  .action(async () => {
+    const cwd = process.cwd();
+    const kitDir = findInstalledKitDir(cwd);
+    // Same modeling-kit exception `fetch` applies — see its action for why.
+    const slicesKitDir = kitDir?.endsWith(MODELING_KIT.kitDirName) ? null : kitDir;
+    const SLICES_DIR = join(slicesKitDir || cwd, '.slices');
+    const hint = '   Run `eventmodelers fetch --context <name>` first to pull a context from the board.';
+
+    // A context is any .slices/ subdirectory fetch/listen wrote an index.json into —
+    // that's the file both of them use as proof a context's slices actually landed.
+    const contextDirs = existsSync(SLICES_DIR)
+      ? readdirSync(SLICES_DIR, { withFileTypes: true })
+          .filter((e) => e.isDirectory() && existsSync(join(SLICES_DIR, e.name, 'index.json')))
+          .map((e) => e.name)
+      : [];
+
+    if (!contextDirs.length) {
+      console.error(`❌ No contexts found in ${relative(cwd, SLICES_DIR)}/.`);
+      console.error(hint);
+      process.exit(1);
+    }
+
+    const currentCtx = readJsonSafe(join(SLICES_DIR, 'current_context.json')).name;
+
+    // context.json's `name` is the human-readable display name; the directory itself
+    // (contextSlug) is what current_context.json must store, since readCurrentContext
+    // (shared/build-kit/lib/ralph.js) joins it straight onto `.slices/<name>/index.json`.
+    const choices = contextDirs.map((dirName) => ({
+      label: readJsonSafe(join(SLICES_DIR, dirName, 'context.json')).name || dirName,
+      value: dirName,
+    }));
+    const defaultIndex = Math.max(0, contextDirs.indexOf(currentCtx));
+
+    const selected = await selectPrompt(
+      `Which context should be active?${currentCtx ? ` (currently: ${choices[defaultIndex].label})` : ''}`,
+      choices,
+      defaultIndex,
+    );
+
+    writeFileSync(join(SLICES_DIR, 'current_context.json'), JSON.stringify({ name: selected }, null, 2));
+    const selectedLabel = choices.find((c) => c.value === selected)?.label || selected;
+    console.log(`✅ Active context set to "${selectedLabel}" → ${relative(cwd, join(SLICES_DIR, 'current_context.json'))}`);
+  });
+
+// Order/icons/default mirror the board UI's own slice-status picker.
+const SLICE_STATUSES = [
+  { label: '🌱 Created (default)', value: 'Created' },
+  { label: '✅ Done', value: 'Done' },
+  { label: '👤 Assigned', value: 'Assigned' },
+  { label: '🔄 InProgress', value: 'InProgress' },
+  { label: '🔍 Review', value: 'Review' },
+  { label: '🚫 Blocked', value: 'Blocked' },
+  { label: '📅 Planned', value: 'Planned' },
+  { label: 'ℹ️ Informational', value: 'Informational' },
+];
+
+program
+  .command('set-slice-status')
+  .description('Pick a slice from the active context and change its status — updates .slices/ locally, and the board itself with --remote')
+  .option('--remote', 'Also push the change to the board via the nodes/events API (same effect `update-slice-status` has, see shared/skills/update-slice-status)')
+  .action(async (opts, command) => {
+    const cwd = process.cwd();
+    const kitDir = findInstalledKitDir(cwd);
+    // Same modeling-kit exception `fetch`/`activate-context` apply — see fetch's action for why.
+    const slicesKitDir = kitDir?.endsWith(MODELING_KIT.kitDirName) ? null : kitDir;
+    const SLICES_DIR = join(slicesKitDir || cwd, '.slices');
+    const fetchHint = '   Run `eventmodelers fetch --context <name>` first to pull a context from the board.';
+
+    const currentCtx = readJsonSafe(join(SLICES_DIR, 'current_context.json')).name;
+    if (!currentCtx) {
+      console.error('❌ No active context set.');
+      console.error(existsSync(SLICES_DIR) ? '   Run `eventmodelers activate-context` to pick one.' : fetchHint);
+      process.exit(1);
+    }
+
+    const contextDir = join(SLICES_DIR, currentCtx);
+    const indexPath = join(contextDir, 'index.json');
+    const indexData = readJsonSafe(indexPath);
+    const slices = Array.isArray(indexData.slices) ? indexData.slices : [];
+    if (!slices.length) {
+      console.error(`❌ No slices found for context "${currentCtx}".`);
+      console.error(fetchHint);
+      process.exit(1);
+    }
+
+    const sliceChoices = slices.map((s) => ({ label: `${s.slice || s.id}  [${s.status || 'Created'}]`, value: s.id }));
+    const sliceId = await selectPrompt(`Which slice in "${currentCtx}" should change status?`, sliceChoices, 0);
+    const slice = slices.find((s) => s.id === sliceId);
+
+    const statusDefault = Math.max(0, SLICE_STATUSES.findIndex((s) => s.value === (slice.status || 'Created')));
+    const newStatus = await selectPrompt(`New status for "${slice.slice}"? (currently: ${slice.status || 'Created'})`, SLICE_STATUSES, statusDefault);
+
+    if (newStatus === (slice.status || 'Created')) {
+      console.log(`ℹ️  "${slice.slice}" is already ${newStatus} — nothing to change.`);
+      return;
+    }
+
+    // index.json's `definition` is a full copy of the slice (see lib/fetch.js's entry
+    // shape) — keep both copies of `status` in sync so anything reading either stays correct.
+    const previousStatus = slice.status || 'Created';
+    slice.status = newStatus;
+    if (slice.definition) slice.definition.status = newStatus;
+    writeFileSync(indexPath, JSON.stringify(indexData, null, 2));
+
+    if (slice.folder) {
+      const sliceJsonPath = join(contextDir, slice.folder, 'slice.json');
+      if (existsSync(sliceJsonPath)) {
+        const sliceData = readJsonSafe(sliceJsonPath);
+        sliceData.status = newStatus;
+        writeFileSync(sliceJsonPath, JSON.stringify(sliceData, null, 2));
+      }
+    }
+
+    console.log(`✅ "${slice.slice}": ${previousStatus} → ${newStatus} (${relative(cwd, indexPath)})`);
+
+    if (!opts.remote) return;
+
+    // slice.id is the SLICE_BORDER node ID (see shared/skills/update-slice-status/SKILL.md
+    // Step 2) — the same id the board's own nodes/events API expects as nodeId below.
+    const globalOpts = command.optsWithGlobals();
+    const explicitConfig = globalOpts.config;
+    const configPath = explicitConfig ? resolve(cwd, explicitConfig) : join(cwd, '.eventmodelers', 'config.json');
+    const requiredFields = ['organizationId', 'boardId', 'token'];
+    let { config: cfg } = loadEffectiveConfig(cwd, kitDir, explicitConfig);
+
+    async function promptForCredentials() {
+      cfg = await configureCredentials({
+        config: cfg,
+        configPath,
+        targetDir: cwd,
+        requiredFields,
+        boardIdOptional: false,
+        overrides: {},
+        print: globalOpts.print,
+      });
+      if (requiredFields.some((f) => !cfg[f])) {
+        console.error('❌ Still missing token/organizationId/boardId — re-run with --remote once configured.');
+        process.exit(1);
+      }
+    }
+    if (requiredFields.some((f) => !cfg[f])) await promptForCredentials();
+
+    const baseUrl = cfg.baseUrl || DEFAULT_BASE_URL;
+    async function pushRemote() {
+      return fetch(`${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': 'cli-set-slice-status',
+        },
+        body: JSON.stringify([{
+          id: randomUUID(),
+          eventType: 'node:changed',
+          nodeId: slice.id,
+          boardId: cfg.boardId,
+          timestamp: Date.now(),
+          changedAttributes: ['sliceStatus'],
+          meta: { sliceStatus: newStatus },
+        }]),
+      });
+    }
+
+    let res;
+    try {
+      res = await pushRemote();
+    } catch (err) {
+      console.error(`❌ Remote update failed: ${err.message}`);
+      process.exit(1);
+    }
+
+    // Same 401/403 reconfigure-and-retry dance `fetch` does — present-but-wrong
+    // credentials, not missing ones, so clear whichever field is implicated and retry once.
+    if (res.status === 401 || res.status === 403) {
+      console.error(`❌ Remote update: ${res.status === 401 ? 'invalid or expired token' : "token's organization does not match this board"}.`);
+      if (res.status === 403) delete cfg.boardId; else delete cfg.token;
+      await promptForCredentials();
+      try {
+        res = await pushRemote();
+      } catch (err) {
+        console.error(`❌ Remote update failed: ${err.message}`);
+        process.exit(1);
+      }
+    }
+
+    if (!res.ok) {
+      const body = await res.json().catch(() => null);
+      const msg = body?.error || `HTTP ${res.status}`;
+      // The API refuses to move a slice into a status it's already in (a concurrency
+      // guard so two agents/users can't both claim it) — not a real failure, just means
+      // the board had already moved on since the last fetch.
+      if (/already/i.test(msg)) {
+        console.log(`ℹ️  Board already has "${slice.slice}" at ${newStatus} — no remote change needed.`);
+        return;
+      }
+      console.error(`❌ Remote update failed: ${msg}`);
+      process.exit(1);
+    }
+
+    console.log(`✅ Pushed status change to the board (node ${slice.id}).`);
+  });
+
 program
   .command('stacks')
   .description('List available stacks (for `init --stack`)')

package/package.json

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

package/stacks/blank/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/blank/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/blank/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/blank/templates/build-kit/CLAUDE.md

@@ -0,0 +1,55 @@
+# 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.**
+
+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/blank/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 realtime agent writes one file per slice on startup and after each `slice:changed` event:
+
+```
+.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.

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

@@ -0,0 +1,124 @@
+# Agent Task Instructions
+
+You are an autonomous agent reacting to slice status change events on an Eventmodelers board.
+
+## Your Loop
+
+1. Read `AGENT.md` to load accumulated learnings before doing anything else.
+2. Read `.build-kit/tasks.json`.
+3. If `tasks.json` is empty or missing, reply with:
+   <promise>IDLE</promise>
+   and stop.
+4. Pick the **oldest task** (earliest `createdAt`).
+5. Execute the task — see the Execution section below.
+6. After execution, remove that task from the array and write `.build-kit/tasks.json` back.
+7. Append a progress entry to `progress.txt` (create if missing).
+8. Update `AGENT.md` with any new reusable learnings discovered this iteration.
+9. Reply normally so the next iteration can pick up the next task.
+
+## Execution
+
+Each task has a single `payload` of type `SliceChangedPayload`:
+
+```
+{
+  event:          "slice:changed"
+  organizationId: string | null
+  boardId:        string
+  sliceId:        string   ← SLICE_BORDER node UUID
+  sliceTitle:     string | null
+  sliceStatus:    string | null   ← e.g. "InProgress", "Done", "Blocked"
+  timestamp:      number
+}
+```
+
+### Step 1 — Load credentials
+
+Run `/connect` to resolve `TOKEN`, `BOARD_ID`, `ORG_ID`, and `BASE_URL` from `.eventmodelers/config.json`.
+
+### Step 2 — Load the slice
+
+Run `/load-slice sliceId=<payload.sliceId>` to fetch full slice details (title, status, raw node record).
+
+### Step 3 — Act on the change
+
+Inspect the `sliceStatus` in the payload:
+
+#### `Planned` — build the slice
+
+This is the build trigger. Setting `InProgress` and building are one atomic step:
+
+1. Immediately call `/update-slice-status` to set the slice to `InProgress` on the board.
+
+   **Claim conflict**: if this call reports the slice is already in `InProgress` (or any status other than `Planned`), another agent already claimed it first — this is expected, not an error. Log it in `progress.txt`, drop this task without building, and continue the loop (the next task will naturally cover the next slice). Do not retry.
+
+2. Read the slice definition from `.build-kit/.slices/<contextSlug>/<sliceFolder>/slice.json` (written by `/load-slice`).
+
+3. Determine the **slice type** from the slice.json:
+   - **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`
+
+4. Invoke the matching skill and follow its instructions **completely**. Do NOT implement the slice manually.
+
+5. **Verify against slice.json**: cross-check the implementation — every command field, event field, and specification in slice.json must appear in the code. No invented fields — if it is not in slice.json, it must not be in the code.
+
+6. Run quality checks (TODO: your stack's build + test commands — slice-scoped tests only, not the full suite).
+
+7. If checks pass, commit all changes with message: `feat: [Slice Name]`.
+
+8. Call `/update-slice-status` to set the slice to `Done` on the board.
+
+#### `InProgress`
+Another agent is already building this slice. Log it and skip — do not build.
+
+#### `Done`
+Summarize what was completed and update `progress.txt`.
+
+#### `Blocked`
+Log the blocker in `progress.txt`.
+
+#### `Review`
+Fetch slice details and prepare a review summary in `progress.txt`.
+
+#### Any other status (`Created`, etc.)
+Load the slice and log the state transition in `progress.txt`. No build action.
+
+Use the skills available in `.claude/skills/` to interact with the board.
+
+## Updating tasks.json
+
+After completing a task, remove it from the array and write the updated array back to `.build-kit/tasks.json`. If the array is now empty, write `[]`.
+
+## Progress Report Format
+
+APPEND to `progress.txt` (never replace):
+```
+## [ISO timestamp] — Task [task.id]
+
+Slice: [sliceTitle] ([sliceId])
+Status change: [sliceStatus]
+
+Action taken:
+- [what was done in response to the slice change]
+
+Learnings:
+- [any patterns, gotchas, or reusable knowledge discovered]
+---
+```
+
+## Stop Condition
+
+If `.build-kit/tasks.json` is empty (`[]`) or does not exist, reply with:
+<promise>IDLE</promise>
+
+## Updating AGENT.md
+
+After completing a task, add any **reusable** learnings to `AGENT.md` — patterns, gotchas, API quirks, or skill behaviour that future iterations should know. Only add things that are general and applicable beyond this single task. Do not duplicate what is already there.
+
+## Important
+
+- Process **one task per iteration**.
+- Read `AGENT.md` first — it contains patterns from previous iterations.
+- Always start with `/connect` if credentials are not yet loaded.

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

@@ -0,0 +1,128 @@
+# Ralph Agent Instructions
+
+You are an autonomous coding agent working on a software project. You apply your skills to build software slices. You only work on one slice at a time.
+
+The structure defined in the Project-Skills is relevant.
+
+## Context Boundary (READ FIRST — NON-NEGOTIABLE)
+
+You work within **exactly ONE context at a time** — the one named in `.build-kit/.slices/current_context.json`.
+
+- **ONLY** look for and build slices inside `.build-kit/.slices/<currentContext>/`.
+- **NEVER** read, scan, or build slices from any other context directory, even if it has "Planned" slices, and even if the current context has no work left.
+- A "Planned" slice in a *different* context is **NOT yours to build**. Ignore it completely.
+- If the current context has no "Planned" slice, you are **done for this iteration** — reply `<promise>NO_TASKS</promise>` and stop. Do not go looking elsewhere. The context is only ever changed on the board, never by you.
+
+## Your Task
+
+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` (check Codebase Patterns section first)
+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:**
+   <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. Determine the slice type and invoke the matching skill as defined in the **Building a Slice** section of `.build-kit/CLAUDE.md`. Do NOT implement manually.
+8. Write a short progress one liner after each step to progress.txt
+9. Analyze and Implement that single slice, making use of the skills in the skills directory plus your previously collected knowledge. Make a TODO list for what needs to be done, and adjust the implementation according to the JSON definition. Carefully inspect events, fields and compare against the implemented slice. JSON is the desired state. ATTENTION: a "planned" task can also be just added specifications. So always look at the slice itself, but also the specifications. If specifications were added in json which are not on code, you need to add them in code.
+10. The slice in the json is always true, the code follows what is defined in the json
+11. Slice is only 'Done' if business logic is implemented as defined in the JSON, APIs are implemented, all scenarios in JSON are implemented in code and it fulfills the slice.json. There must be no specification in json that has no equivalent in code.
+12. Make sure to write the ui-prompt.md as defined if defined in the skill
+13. Run quality checks — TODO: your stack's build command, TODO: your stack's test command (slice-scoped only; do not run all tests).
+14. If checks pass, commit ALL changes with message: `feat: [Slice Name]` and merge back to main as FF merge (update first)
+15. 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).
+16. Append your progress to `progress.txt` after each step in the iteration.
+17. 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.
+18. Finish the iteration.
+
+## Progress Report Format
+
+APPEND to progress.txt (never replace, always append):
+
+```
+## [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")
+---
+```
+
+The learnings section is critical - it helps future iterations avoid repeating mistakes and understand the codebase better.
+
+## Consolidate Patterns
+
+If you discover a **reusable pattern** that future iterations should know, add it to the `## Codebase Patterns` section at the TOP of progress.txt (create it if it doesn't exist).
+
+```
+## Codebase Patterns
+- TODO: an example of a your stack-specific reusable pattern once you have one
+```
+
+Only add patterns that are **general and reusable**, not story-specific details.
+
+## Update AGENTS.md Files
+
+Before committing, check if any edited files have learnings worth preserving in nearby AGENTS.md files — API patterns/conventions, gotchas, dependencies between files, testing approaches, configuration/environment requirements.
+
+**Do NOT add:**
+
+- Slice specific implementation details
+- Story-specific implementation details
+- Temporary debugging notes
+- Information already in progress.txt
+- Task-specific learnings
+
+Only update AGENTS.md if you have **genuinely reusable knowledge** that would help future work
+
+## Quality Requirements
+
+- ALL commits must pass this project's quality checks (typecheck/compile, lint, test)
+- TODO: your stack's build command
+- TODO: your stack's test command
+- Do NOT commit broken code
+- Keep changes focused and minimal
+- Follow existing code patterns
+
+## Skills
+
+Use the provided skills in the skills folder as guidance.
+Update skill definitions if you find an improvement you can make.
+
+## Specifications
+
+For every specification added to the Slice, you need to implement one executable Specification in Code.
+
+A Slice is not complete if specifications are missing or can't be executed.
+
+## Stop Condition
+
+**After completing ONE slice, always stop — regardless of whether more slices are Planned.** The ralph loop will invoke you again for the next slice. Never chain multiple slices in one iteration.
+
+If the slice was completed and committed successfully, reply with:
+<promise>DONE</promise>
+
+If no slice has status "Planned" in the current context, reply with:
+<promise>NO_TASKS</promise>
+(Do NOT switch to another context to find work — stop here.)
+
+If ALL slices in the current context are Done, reply with:
+<promise>COMPLETE</promise>
+
+## Important
+
+- If `.build-kit/.eventmodelers/config.json` is absent, 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
+
+## When an iteration completes
+
+Use all the key learnings from the progress.txt and update the `.build-kit/AGENTS.md` file with those learnings.

package/stacks/blank/templates/root/README.md

@@ -0,0 +1,16 @@
+# Your stack
+
+TODO — this is a placeholder project scaffold, installed by `init --build-kit` for a
+stack that isn't built into this CLI yet. Replace this file (and everything else under
+`root/`) with a real minimal starter for your stack: build/dependency file, source
+layout, a slices directory the skills in `.claude/skills/` generate into, and whatever
+local infra (docker-compose, migrations, etc.) it needs to run.
+
+See an existing stack's `templates/root/` in the eventmodelers-cli source —
+`stacks/node`, `stacks/supabase`, `stacks/axon`, `stacks/cratis-csharp` — for the shape
+a real one takes.
+
+Once this is filled in and working, consider contributing it back as a first-class
+stack: copy `.build-kit/`, `.claude/skills/`, and this `root/` scaffold into
+`stacks/<name>/templates/` in the eventmodelers-cli repo and register it in `STACKS`
+(cli.js) — see that repo's README, "Adding a stack".