@eventmodelers/cli 0.0.30 → 0.0.31

package/cli.js

@@ -2,7 +2,7 @@
 
 import { Command } from 'commander';
 import { fileURLToPath, pathToFileURL } from 'url';
-import { dirname, join, relative, resolve, sep } from 'path';
+import { dirname, isAbsolute, join, normalize, relative, resolve, sep } from 'path';
 import {
   existsSync,
   mkdirSync,
@@ -529,6 +529,17 @@ function findAllInstalledKitDirs(cwd) {
   return KIT_DIR_NAMES.map((name) => join(cwd, name)).filter((p) => existsSync(p));
 }
 
+// Appends any line from a previous install's .gitignore that the freshly-copied one
+// doesn't already cover — unlike CLAUDE.md's freeform prose, .gitignore is just a line
+// list, so a simple dedup-append is enough to keep both kits' ignore rules intact.
+function mergeGitignoreLines(oldContent, newContent) {
+  const newLines = new Set(newContent.split('\n').map((l) => l.trim()).filter(Boolean));
+  const additions = oldContent.split('\n').filter((l) => l.trim() && !newLines.has(l.trim()));
+  if (!additions.length) return newContent;
+  const sep = newContent.endsWith('\n') ? '' : '\n';
+  return `${newContent}${sep}${additions.join('\n')}\n`;
+}
+
 function copyDirContents(srcDir, destDir, { skip = [] } = {}) {
   if (!existsSync(srcDir)) return;
   mkdirSync(destDir, { recursive: true });
@@ -567,6 +578,17 @@ function cloneGitStack(url, branch) {
   return dest;
 }
 
+// stack.json's kitSubdir is attacker-controlled (it comes from whatever repo --git
+// cloned) and feeds straight into join(templatesSource, kitSubdir) — installStack
+// then copies everything under that path into the target project. Reject anything
+// that isn't a plain relative subdirectory name so a malicious stack.json can't walk
+// out of the clone (e.g. "../../../../etc") and have arbitrary host files copied in.
+function isSafeRelativeSubpath(p) {
+  if (typeof p !== 'string' || !p) return false;
+  const normalized = normalize(p);
+  return !isAbsolute(normalized) && normalized.split(sep).every((part) => part !== '..');
+}
+
 // A community stack repo must mirror the internal stacks/<key>/templates layout exactly
 // (templates/.claude, templates/root, templates/<kitSubdir>) so installStack() can treat
 // it identically to a built-in stack — see STACKS above for the shape. An optional
@@ -580,7 +602,40 @@ function resolveGitStackConfig(clonedDir, name) {
     console.error(`❌ ${relative(process.cwd(), clonedDir) || clonedDir} has no templates/ directory — a build kit repo needs templates/.claude, templates/root, and templates/<kitSubdir>, the same layout this CLI's own stacks/<name>/templates use.`);
     process.exit(1);
   }
-  const manifest = readJsonSafe(join(clonedDir, 'stack.json'));
+  for (const required of ['.claude', 'root']) {
+    if (!existsSync(join(templatesSource, required))) {
+      console.error(`❌ ${relative(process.cwd(), templatesSource) || templatesSource} is missing "${required}/" — a build kit repo needs templates/.claude, templates/root, and templates/<kitSubdir>, the same layout this CLI's own stacks/<name>/templates use.`);
+      process.exit(1);
+    }
+  }
+
+  const manifestPath = join(clonedDir, 'stack.json');
+  const manifestRaw = existsSync(manifestPath) ? readFileSync(manifestPath, 'utf-8') : null;
+  let manifest = {};
+  if (manifestRaw !== null) {
+    try {
+      manifest = JSON.parse(manifestRaw);
+    } catch {
+      console.error(`❌ ${relative(process.cwd(), manifestPath) || manifestPath} is not valid JSON.`);
+      process.exit(1);
+    }
+  }
+
+  if (manifest.label !== undefined && (typeof manifest.label !== 'string' || !manifest.label)) {
+    console.error('❌ stack.json "label" must be a non-empty string.');
+    process.exit(1);
+  }
+  if (manifest.kitSubdir !== undefined && !isSafeRelativeSubpath(manifest.kitSubdir)) {
+    console.error(`❌ stack.json "kitSubdir" must be a plain relative subdirectory name (no "..", no absolute paths) — got ${JSON.stringify(manifest.kitSubdir)}.`);
+    process.exit(1);
+  }
+  for (const boolField of ['useShared', 'needsBoardId']) {
+    if (manifest[boolField] !== undefined && typeof manifest[boolField] !== 'boolean') {
+      console.error(`❌ stack.json "${boolField}" must be a boolean.`);
+      process.exit(1);
+    }
+  }
+
   const kitSubdir = manifest.kitSubdir || 'build-kit';
   if (!existsSync(join(templatesSource, kitSubdir))) {
     console.error(`❌ ${relative(process.cwd(), templatesSource) || templatesSource} is missing its kit subdirectory "${kitSubdir}/" (from stack.json, or the "build-kit" default) — nothing to install.`);
@@ -668,9 +723,72 @@ async function installStack(stackKey, stackCfg, options = {}) {
 
     // --- 2. Spread stack scaffold files into the project root ---
     const rootSrc = join(templatesSource, 'root');
+    // root/CLAUDE.md is never copied to the project root directly (see step 3 below) —
+    // built-in stacks no longer ship one at all, and an outdated community/--git stack
+    // that still does gets it relocated into its own kit dir instead, so this generic
+    // copy must never let it slip through to root and clobber the shared router there.
+    const stackRootClaudeSrc = join(rootSrc, 'CLAUDE.md');
+    const stackShipsOwnRootClaude = existsSync(stackRootClaudeSrc);
     if (existsSync(rootSrc)) {
       console.log('📦 Installing project files...');
-      copyDirContents(rootSrc, targetDir);
+      // .gitignore is the one file every stack's root/ ships that can collide with
+      // another already-installed kit's own .gitignore (e.g. modeling-kit + a build-kit
+      // stack) — capture what's there before the copy below overwrites it wholesale,
+      // then merge the two afterwards instead of silently losing whichever rules the
+      // first-installed kit added (e.g. node_modules/.idea from a build-kit install).
+      const gitignoreDest = join(targetDir, '.gitignore');
+      const priorGitignore = existsSync(gitignoreDest) ? readFileSync(gitignoreDest, 'utf-8') : null;
+      copyDirContents(rootSrc, targetDir, { skip: ['CLAUDE.md'] });
+      if (priorGitignore !== null && existsSync(gitignoreDest)) {
+        const incoming = readFileSync(gitignoreDest, 'utf-8');
+        const merged = mergeGitignoreLines(priorGitignore, incoming);
+        if (merged !== incoming) {
+          writeFileSync(gitignoreDest, merged);
+          console.log('  ✓ Merged .gitignore with the rules from an already-installed kit');
+        }
+      }
+    }
+
+    // A modeling-kit + build-kit (or bridge) combo in the same project is supported
+    // (they share one config.json — see ensureAgentId) but each kit's own instructions
+    // now live in its own kit dir (.build-kit/CLAUDE.md, .agent-modeling-kit/CLAUDE.md)
+    // instead of root/CLAUDE.md, precisely so a second kit's install can never clobber
+    // the first kit's instructions the way it used to — including an outdated community
+    // stack's own root/CLAUDE.md, already relocated above rather than left here to
+    // compete for this slot. The root CLAUDE.md is instead a small, stack-agnostic router
+    // pointing at whichever kit CLAUDE.md files exist — identical content regardless of
+    // which stack installs it, so a fresh project or one that already has the up-to-date
+    // router both just get it written/left alone silently. Only a pre-migration
+    // single-stack CLAUDE.md (from before this fix shipped) or the user's own hand-edited
+    // notes is there an actual decision to make, so that's the one case this asks about
+    // instead of silently guessing either way.
+    const rootClaudeDest = join(targetDir, 'CLAUDE.md');
+    const sharedRootClaude = join(__dirname, 'shared', 'root-claude', 'CLAUDE.md');
+    const routerContent = existsSync(sharedRootClaude) ? readFileSync(sharedRootClaude, 'utf-8') : null;
+    if (routerContent !== null) {
+      if (!existsSync(rootClaudeDest)) {
+        writeFileSync(rootClaudeDest, routerContent);
+        console.log('  ✓ Installed root CLAUDE.md — a router pointing at .build-kit/CLAUDE.md and .agent-modeling-kit/CLAUDE.md, whichever are present');
+      } else if (readFileSync(rootClaudeDest, 'utf-8') === routerContent) {
+        console.log('  ✓ Root CLAUDE.md already present and up to date — left as-is');
+      } else if (options.print) {
+        console.log('  ℹ️  --print — a different root CLAUDE.md already exists, leaving it as-is (rerun without --print to choose)');
+      } else {
+        const choice = await selectPrompt(
+          'A root CLAUDE.md already exists with different content (your own notes, another stack\'s, or a pre-upgrade file) — overwrite it with the router template pointing at each installed kit\'s own CLAUDE.md?',
+          [
+            { label: 'Keep the existing CLAUDE.md (recommended)', value: 'keep' },
+            { label: 'Overwrite with the router template', value: 'overwrite' },
+          ],
+          0,
+        );
+        if (choice === 'overwrite') {
+          writeFileSync(rootClaudeDest, routerContent);
+          console.log('  ✓ Overwrote root CLAUDE.md with the router template');
+        } else {
+          console.log('  ✓ Kept the existing root CLAUDE.md');
+        }
+      }
     }
 
     // --- 3. Create the kit dir and install the agent runner ---
@@ -683,6 +801,19 @@ async function installStack(stackKey, stackCfg, options = {}) {
     }
     copyDirContents(join(templatesSource, stackCfg.kitSubdir), kitDir, { skip: ['.eventmodelers'] });
 
+    // An outdated community/--git stack that still ships root/CLAUDE.md (the pre-fix
+    // layout every built-in stack used to follow too) gets it relocated here instead
+    // of left in root/ — same destination a built-in stack's own templates/<kitSubdir>
+    // now ships it at directly. No prompt needed: this is this stack's own file, moving
+    // to where its counterpart already lives, not a conflict with anything else.
+    if (stackShipsOwnRootClaude) {
+      const kitClaudeDest = join(kitDir, 'CLAUDE.md');
+      if (!existsSync(kitClaudeDest)) {
+        copyFileSync(stackRootClaudeSrc, kitClaudeDest);
+        console.log(`  ✓ Relocated this stack's CLAUDE.md into ${stackCfg.kitDirName}/ (root/CLAUDE.md is reserved for the shared router)`);
+      }
+    }
+
     // Static (no-LLM) bridge adapters live once in this package's own lib/
     // adapters/ — `fetch --spec-kitty` imports them directly, and a bridge
     // install gets its own copy here so ralph-static.js can run standalone

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventmodelers/cli",
-  "version": "0.0.30",
+  "version": "0.0.31",
   "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/shared/root-claude/CLAUDE.md

@@ -0,0 +1,13 @@
+# Project Configuration
+
+This project can have more than one eventmodelers agent kit installed at once — typically
+one backend stack plus the modeling kit, working side by side on the same board. Each
+installed kit ships its own CLAUDE.md with that kit's own responsibilities. Check which
+of these exist in this project and read whichever are present, following all of them
+together:
+
+- `.build-kit/CLAUDE.md` — building this project's backend from board slices
+- `.agent-modeling-kit/CLAUDE.md` — designing and updating the event model board itself
+
+Neither is guaranteed to exist — this file is installed once, up front, before either kit
+is known to be present.

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

@@ -30,7 +30,7 @@ There are two kinds:
 
 > **Comments & description**: Each element in the slice carries a `comments: string[]` array and a `description` field. Use these as implementation hints. When done, resolve each used comment: `POST <BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/nodes/<nodeId>/comments/<commentId>/resolve` (get IDs first via GET on same path).
 
-Read the target project's `CLAUDE.md` and explore existing slices. Look for:
+Read the target project's `.build-kit/CLAUDE.md` and explore existing slices. Look for:
 
 - File splitting conventions (one Java file per class vs inner classes)
 - Visibility conventions

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

@@ -27,7 +27,7 @@ New workflow slices live under
 
 > **Comments & description**: Each element in the slice carries a `comments: string[]` array and a `description` field. Use these as implementation hints. When done, resolve each used comment: `POST <BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/nodes/<nodeId>/comments/<commentId>/resolve` (get IDs first via GET on same path).
 
-Read `CLAUDE.md` and check whether the project already uses AF5 Workflows. Look for:
+Read `.build-kit/CLAUDE.md` and check whether the project already uses AF5 Workflows. Look for:
 
 - A `WorkflowModule` bean in any `@Configuration` class
 - Classes annotated with `@Workflow`

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

@@ -19,7 +19,7 @@ description: >
 
 > **Comments & description**: Each element in the slice carries a `comments: string[]` array and a `description` field. Use these as implementation hints. When done, resolve each used comment: `POST <BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/nodes/<nodeId>/comments/<commentId>/resolve` (get IDs first via GET on same path).
 
-Before writing any code, read the target project's `CLAUDE.md`
+Before writing any code, read the target project's `.build-kit/CLAUDE.md`
 
 ## Step 1: Ensure Events Exist
 

package/stacks/axon/templates/{root → build-kit}/CLAUDE.md

@@ -26,7 +26,7 @@ Ignore case for files and slices in prompts. "CartItems" slice is the same as "c
 
 Do not change files with tests unless explicitely instructed: *.test.ts
 
-At the start of every session, read `AGENTS.md` if it exists to load accumulated project learnings.
+At the start of every session, read `.build-kit/AGENTS.md` if it exists to load accumulated project learnings.
 
 When starting to work on a slice, invoke the `update-slice-status` skill with `InProgress` status before doing anything else.
 

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

@@ -45,7 +45,7 @@ You work within **exactly ONE context at a time** — the one named in `.build-k
     first )
 16. Update the PRD to set `status: Done` for the completed story in index.json **and** update the slice status on the eventmodelers board using the `update-slice-status` skill (or MCP if available).
 17. Append your progress to `progress.txt` after each step in the iteration.
-18. append your new learnings to AGENTS.md in a compressed form, reusable for future iterations. Only add learnings if they are not already there.
+18. append your new learnings to `.build-kit/AGENTS.md` in a compressed form, reusable for future iterations. Only add learnings if they are not already there.
 19. Finish the iteration.
 
 ## Progress Report Format
@@ -155,4 +155,4 @@ If ALL slices in the current context are Done, reply with:
 
 ## When an iteration completes
 
-Use all the key learnings from the progress.txt and update the AGENTS.md file with those learnings.
+Use all the key learnings from the progress.txt and update the `.build-kit/AGENTS.md` file with those learnings.

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

@@ -23,7 +23,7 @@ event  →  IReactor method (dispatch by first param type)  →  side effect / I
 
 ## Step 0 — Discover conventions
 
-Read `CLAUDE.md` and one existing reactor. Confirm the namespace root, how reactors are placed within a
+Read `.build-kit/CLAUDE.md` and one existing reactor. Confirm the namespace root, how reactors are placed within a
 slice, which services are available for side effects, and how existing translations call
 `ICommandPipeline`. Resolve slice `comments` when done (see the state-change skill's Step 0).
 

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

@@ -24,7 +24,7 @@ file**:
 
 ## Step 0 — Discover the target project's conventions
 
-Before writing code, read the project's `CLAUDE.md` and **at least one existing slice** (the starter
+Before writing code, read the project's `.build-kit/CLAUDE.md` and **at least one existing slice** (the starter
 ships one under `SomeModule/SomeFeature/`). Confirm:
 
 - The namespace root (read the `.csproj` `<RootNamespace>` and existing `.cs` files — never

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

@@ -23,7 +23,7 @@ file**:
 
 ## Step 0 — Discover conventions
 
-Read `CLAUDE.md` and one existing read slice. Confirm the namespace root, how existing read models
+Read `.build-kit/CLAUDE.md` and one existing read slice. Confirm the namespace root, how existing read models
 declare queries (snapshot vs observable), whether projections use model-bound attributes or
 `IProjectionFor<T>`, and the MongoDB collection wiring. Resolve slice `comments` when done (see the
 state-change skill's Step 0 for the resolve endpoint).

package/stacks/modeling-kit/templates/kit/AGENTS.md

@@ -0,0 +1,12 @@
+# Learnings
+
+Reusable learnings accumulated while processing prompts for this board. Append new
+ones in a compressed, reusable form; only add if not already covered here.
+
+- `/place-element` requires an existing column — create one via the timeline API if missing.
+- `/wdyt` posts QUESTION comments onto nodes — use for analysis only, not modifications.
+- The `board_id`, `timeline_id`, and `organization_id` from each prompt provide full context — pass them to skills that need them.
+- Node events POST to `/api/boards/:boardId/nodes/events` using `node:created`, `node:changed`, `node:deleted`.
+- `/update-slice-status` rejects moving a slice into a status it's already in — this is a concurrency guard so two agents can't both claim the same slice. Treat this as `ALREADY_IN_STATUS`, not a task failure: drop the prompt, move on to the next task, and do not retry the same update.
+- macOS/BSD `date` silently ignores GNU-only format specifiers like `%N`/`%3N` (sub-second precision) instead of erroring — it prints the literal characters, producing a malformed timestamp that only fails downstream. Don't shell out to `date` for sub-second precision; use `$(( $(date +%s) * 1000 ))` for whole-second-in-ms, or a runtime call (`Date.now()`, `process.hrtime()`) instead.
+- Before retrying a failed shell command a second time, diagnose why it failed (e.g. a GNU/BSD flag mismatch) rather than re-running it unchanged — repeating the same command produces the same failure and just burns retries.

package/stacks/modeling-kit/templates/kit/CLAUDE.md

@@ -0,0 +1,45 @@
+# Agent Instructions & Learnings
+
+You are an autonomous agent processing prompts for an eventmodelers board.
+
+## Mode
+
+This project runs in one mode only — a warm, direct-dispatch session driven by
+`npx @eventmodelers/cli run --modeling`. The first message begins with `MODE=modeling`;
+read and follow the project root's **`claude-modeling.md`** for every prompt in this
+session, and don't re-read it on every turn once you've read it once. There is no
+file-queue loop and no `tasks.json` for a modeling-kit install — that's a build-kit
+concept, for their independent, self-contained slice-implementation tasks.
+
+The root `claude-modeling.md` shares the Skill Selection table and Progress Entry Format below.
+
+At the start of every session, read `.agent-modeling-kit/AGENTS.md` if it exists to load accumulated learnings.
+
+## Skill Selection
+
+| Intent | Skill |
+|--------|-------|
+| Add, rename, or reorder events on a timeline | `/timeline` |
+| Place a COMMAND, READMODEL, or EVENT at a position | `/place-element` |
+| Generate a full storyboard with multiple screens | `/storyboard` |
+| Design or update a single wireframe screen | `/storyboard-screen` |
+| Design or update a single real HTML/CSS screen (explicit request only) | `/html-screen` |
+| Business analysis, gap spotting, posting questions | `/wdyt` |
+| Analyse the existing model structure, slice coverage, element counts | `/analyze-existing-model` |
+| Look up any API endpoint or element type | `/learn-eventmodelers-api` |
+| Add or rename an attribute across a chain of elements | `/attributes` |
+| Add or improve example data on element fields | `/examples` |
+| Update the status of a slice (e.g. done, in-progress) | `/update-slice-status` |
+
+Read `.claude/skills/<skill-name>/SKILL.md` before executing — each skill has required inputs and step-by-step instructions.
+
+## Progress Entry Format
+
+APPEND to `progress.txt` (never replace):
+```
+## [ISO timestamp] — [task/prompt identifier]
+Prompts processed: [prompt text(s)]
+Outcome: [what changed on the board]
+Learnings: [any reusable pattern or gotcha noticed this turn, or "none"]
+---
+```

package/stacks/modeling-kit/templates/root/claude-modeling.md

@@ -14,9 +14,9 @@ You are a long-lived process handling many turns in a row. Don't redo one-time s
 
    Otherwise skip straight to executing the prompt — re-running `/connect` every turn defeats the point of a modeling session.
 3. **Resolve `BOARD_ID`** from this turn's `board_id` field; if absent, fall back to `boardId` in `.eventmodelers/config.json`.
-4. Execute the prompt using the skill matched in CLAUDE.md's Skill Selection table.
+4. Execute the prompt using the skill matched in `.agent-modeling-kit/CLAUDE.md`'s Skill Selection table.
    **Questioning rule**: you are running autonomously — no human is available to answer questions. If you need clarification, do not pause or ask interactively — post a `QUESTION`-type comment (`/handle-comment` with `action=place`, `type=QUESTION`) on the most relevant node, then continue with your best interpretation.
 5. If this turn has a `comment_id` field, invoke `/handle-comment` with `action=resolve`, `nodeId` from `node_id`, `commentId` from `comment_id`.
-6. Append a progress entry to `progress.txt` — see CLAUDE.md's Progress Entry Format.
-7. Add any reusable learnings to CLAUDE.md's **Learnings** section at the bottom.
+6. Append a progress entry to `progress.txt` — see `.agent-modeling-kit/CLAUDE.md`'s Progress Entry Format. Fill in the `Learnings` line with anything reusable noticed this turn (pattern, gotcha, useful context), or "none".
+7. If this turn's `Learnings` line was not "none", promote it to `.agent-modeling-kit/AGENTS.md` (create it if it doesn't exist) — only add it if it's not already there.
 8. Reply `<promise>DONE</promise>` and wait for the next turn.

package/stacks/node/templates/{root → build-kit}/CLAUDE.md

@@ -26,7 +26,7 @@ Ignore case for files and slices in prompts. "CartItems" slice is the same as "c
 
 Do not change files with tests unless explicitely instructed: *.test.ts
 
-At the start of every session, read `AGENTS.md` if it exists to load accumulated project learnings.
+At the start of every session, read `.build-kit/AGENTS.md` if it exists to load accumulated project learnings.
 
 When starting to work on a slice, invoke the `update-slice-status` skill with `InProgress` status before doing anything else.
 

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

@@ -25,7 +25,7 @@ You work within **exactly ONE context at a time** — the one named in `.build-k
    **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 CLAUDE.md. Do NOT implement manually.
+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, make use of the skills in the skills directory, but also your previsously collected
    knowledge. Make a list TODO list for what needs to be done. Also make sure to adjust the implementation according to the json definition. Carefully inspect events, fields and compare against the implemented slice. JSON is the desired state. ATTENTION: A "planned" task can also be just added specifications. So always look at the slice itself, but also the specifications. If specifications were added in json, which are not on code, you need to add them in code.
@@ -39,7 +39,7 @@ You work within **exactly ONE context at a time** — the one named in `.build-k
     first )
 16. Update the PRD to set `status: Done` for the completed story in index.json **and** update the slice status on the eventmodelers board using the `update-slice-status` skill (or MCP if available).
 17. Append your progress to `progress.txt` after each step in the iteration.
-18. append your new learnings to AGENTS.md in a compressed form, reusable for future iterations. Only add learnings if they are not already there.
+18. append your new learnings to `.build-kit/AGENTS.md` in a compressed form, reusable for future iterations. Only add learnings if they are not already there.
 19. Finish the iteration.
 
 ## Progress Report Format
@@ -149,4 +149,4 @@ If ALL slices in the current context are Done, reply with:
 
 ## When an iteration completes
 
-Use all the key learnings from the progress.txt and update the AGENTS.md file with those learnings.
+Use all the key learnings from the progress.txt and update the `.build-kit/AGENTS.md` file with those learnings.

package/stacks/supabase/templates/{root → build-kit}/CLAUDE.md

@@ -26,7 +26,7 @@ Ignore case for files and slices in prompts. "CartItems" slice is the same as "c
 
 Do not change files with tests unless explicitely instructed: *.test.ts
 
-At the start of every session, read `AGENTS.md` if it exists to load accumulated project learnings.
+At the start of every session, read `.build-kit/AGENTS.md` if it exists to load accumulated project learnings.
 
 When starting to work on a slice, invoke the `update-slice-status` skill with `InProgress` status before doing anything else.
 

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

@@ -25,7 +25,7 @@ You work within **exactly ONE context at a time** — the one named in `.build-k
    **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 CLAUDE.md. Do NOT implement manually.
+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, make use of the skills in the skills directory, but also your previsously collected
    knowledge. Make a list TODO list for what needs to be done. Also make sure to adjust the implementation according to the json definition. Carefully inspect events, fields and compare against the implemented slice. JSON is the desired state. ATTENTION: A "planned" task can also be just added specifications. So always look at the slice itself, but also the specifications. If specifications were added in json, which are not on code, you need to add them in code.
@@ -39,7 +39,7 @@ You work within **exactly ONE context at a time** — the one named in `.build-k
     first )
 16. Update the PRD to set `status: Done` for the completed story in index.json **and** update the slice status on the eventmodelers board using the `update-slice-status` skill (or MCP if available).
 17. Append your progress to `progress.txt` after each step in the iteration.
-18. append your new learnings to AGENTS.md in a compressed form, reusable for future iterations. Only add learnings if they are not already there.
+ 18. append your new learnings to `.build-kit/AGENTS.md` in a compressed form, reusable for future iterations. Only add learnings if they are not already there.
 19. Finish the iteration.
 
 ## Progress Report Format
@@ -149,4 +149,4 @@ If ALL slices in the current context are Done, reply with:
 
 ## When an iteration completes
 
-Use all the key learnings from the progress.txt and update the AGENTS.md file with those learnings.
+Use all the key learnings from the progress.txt and update the `.build-kit/AGENTS.md` file with those learnings.

package/stacks/modeling-kit/templates/root/CLAUDE.md

@@ -1,54 +0,0 @@
-# Agent Instructions & Learnings
-
-You are an autonomous agent processing prompts for an eventmodelers board.
-
-## Mode
-
-This project runs in one mode only — a warm, direct-dispatch session driven by
-`npx @eventmodelers/cli run --modeling`. The first message begins with `MODE=modeling`;
-read and follow **`claude-modeling.md`** for every prompt in this session, and don't
-re-read it on every turn once you've read it once. There is no file-queue loop and no
-`tasks.json` for a modeling-kit install — that's a build-kit concept, for their
-independent, self-contained slice-implementation tasks.
-
-`claude-modeling.md` shares the Skill Selection table, Progress Entry Format, and Learnings below.
-
-## Skill Selection
-
-| Intent | Skill |
-|--------|-------|
-| Add, rename, or reorder events on a timeline | `/timeline` |
-| Place a COMMAND, READMODEL, or EVENT at a position | `/place-element` |
-| Generate a full storyboard with multiple screens | `/storyboard` |
-| Design or update a single wireframe screen | `/storyboard-screen` |
-| Design or update a single real HTML/CSS screen (explicit request only) | `/html-screen` |
-| Business analysis, gap spotting, posting questions | `/wdyt` |
-| Analyse the existing model structure, slice coverage, element counts | `/analyze-existing-model` |
-| Look up any API endpoint or element type | `/learn-eventmodelers-api` |
-| Add or rename an attribute across a chain of elements | `/attributes` |
-| Add or improve example data on element fields | `/examples` |
-| Update the status of a slice (e.g. done, in-progress) | `/update-slice-status` |
-
-Read `.claude/skills/<skill-name>/SKILL.md` before executing — each skill has required inputs and step-by-step instructions.
-
-## Progress Entry Format
-
-APPEND to `progress.txt` (never replace):
-```
-## [ISO timestamp] — [task/prompt identifier]
-Prompts processed: [prompt text(s)]
-Outcome: [what changed on the board]
----
-```
-
----
-
-## Learnings
-
-- `/place-element` requires an existing column — create one via the timeline API if missing.
-- `/wdyt` posts QUESTION comments onto nodes — use for analysis only, not modifications.
-- The `board_id`, `timeline_id`, and `organization_id` from each prompt provide full context — pass them to skills that need them.
-- Node events POST to `/api/boards/:boardId/nodes/events` using `node:created`, `node:changed`, `node:deleted`.
-- `/update-slice-status` rejects moving a slice into a status it's already in — this is a concurrency guard so two agents can't both claim the same slice. Treat this as `ALREADY_IN_STATUS`, not a task failure: drop the prompt, move on to the next task, and do not retry the same update.
-- macOS/BSD `date` silently ignores GNU-only format specifiers like `%N`/`%3N` (sub-second precision) instead of erroring — it prints the literal characters, producing a malformed timestamp that only fails downstream. Don't shell out to `date` for sub-second precision; use `$(( $(date +%s) * 1000 ))` for whole-second-in-ms, or a runtime call (`Date.now()`, `process.hrtime()`) instead.
-- Before retrying a failed shell command a second time, diagnose why it failed (e.g. a GNU/BSD flag mismatch) rather than re-running it unchanged — repeating the same command produces the same failure and just burns retries.