@eventmodelers/cli 1.0.64 → 1.0.65

package/README.md

@@ -346,10 +346,19 @@ Both are stored alongside your credentials in the project root's `.eventmodelers
   "boardId": "...",
   "token": "...",
   "anthropicBaseUrl": "http://localhost:8000",
-  "model": "claude-sonnet-5"
+  "model": "claude-sonnet-5",
+  "subagentModel": "sonnet"
 }
 ```
 
+`model` is what the agent session itself runs on. `subagentModel` (default `sonnet`) is what the
+subagents it fans a turn out to run on — the session model does the judging (which parts of the
+board need work, what each piece is, who owns what), and by the time an agent is dispatched
+what's left is execution against a written brief, which doesn't need the expensive model. Set
+them to the same value to turn that split off. `subagentModel` reaches the agents as the `model`
+argument of the `Agent` tool, so it takes one of that tool's short aliases (`sonnet`, `opus`,
+`haiku`) — not a full model id like `model` does.
+
 Beyond the one-time install bootstrap, each stack's own `ralph.js`/`ralph-claude.js` governs how config is re-read at runtime — check `<kit-dir>/lib/` for the specifics of the stack you installed.
 
 ### Hierarchical config resolution
@@ -393,6 +402,7 @@ Every config field can be set via an `EVENTMODELERS_*` env var instead of the in
 | `EVENTMODELERS_BASE_URL` | `baseUrl` |
 | `EVENTMODELERS_ANTHROPIC_BASE_URL` | `anthropicBaseUrl` |
 | `EVENTMODELERS_MODEL` | `model` |
+| `EVENTMODELERS_SUBAGENT_MODEL` | `subagentModel` |
 
 ```bash
 EVENTMODELERS_ORGANIZATION_ID=... EVENTMODELERS_BOARD_ID=... EVENTMODELERS_TOKEN=... \

package/cli.js

@@ -311,6 +311,7 @@ const ENV_CONFIG_MAP = {
   EVENTMODELERS_BASE_URL: 'baseUrl',
   EVENTMODELERS_ANTHROPIC_BASE_URL: 'anthropicBaseUrl',
   EVENTMODELERS_MODEL: 'model',
+  EVENTMODELERS_SUBAGENT_MODEL: 'subagentModel',
 };
 
 function applyEnvOverrides(config) {
@@ -401,6 +402,17 @@ const DEFAULT_BASE_URL = 'https://api.eventmodelers.ai';
 // still covering the usual burst — a handful of nodes across a couple of slices.
 const DEFAULT_MAX_AGENTS = 5;
 
+// What the subagents a turn fans out to run on (`subagentModel` in config.json, or
+// EVENTMODELERS_SUBAGENT_MODEL). The session's own model — `model`, which is what the
+// `claude` process is started with — is the one doing the judging: which areas need work,
+// what each piece is, who owns what. By the time an Agent is dispatched that is settled, and
+// what's left is execution against a written brief (fill in the examples, write the GWT
+// scenarios, render the screen, batch the writes), which the cheap model does just as well.
+// The agents inherit the session's model unless a turn says otherwise, so the turn says so.
+// This reaches the agent as the `Agent` tool's own `model` argument, which takes a short alias
+// (`sonnet`/`opus`/`haiku`) rather than the full model id `model` above is set with.
+const DEFAULT_SUBAGENT_MODEL = 'sonnet';
+
 // `--max-agents` is a cost guard, so a typo must not silently turn into "no limit" or
 // into the default: anything that isn't a positive integer is rejected outright.
 function parseMaxAgents(raw) {
@@ -1669,6 +1681,8 @@ async function runModeling(kitDir, projectDir, verbose = false, standalone = fal
     process.exit(1);
   }
 
+  const subagentModel = cfg.subagentModel || DEFAULT_SUBAGENT_MODEL;
+
   const log = (line) => console.log(`[modeling] ${line}`);
 
   const QUESTIONING_RULE =
@@ -1689,7 +1703,7 @@ async function runModeling(kitDir, projectDir, verbose = false, standalone = fal
   function withSessionHeader(body) {
     if (!firstTurn) return body;
     firstTurn = false;
-    return `MODE=modeling token=${cfg.token} org=${cfg.organizationId} baseUrl=${cfg.baseUrl} standalone=${standalone ? 'on' : 'off'}${standalone ? ` max_agents=${maxAgents}` : ''}\n\n${QUESTIONING_RULE}Read .agent-modeling-kit/CLAUDE.md now and follow it for every prompt in this session — it's a one-time read; don't re-read it on later turns.\n\n${body}`;
+    return `MODE=modeling token=${cfg.token} org=${cfg.organizationId} baseUrl=${cfg.baseUrl} standalone=${standalone ? 'on' : 'off'}${standalone ? ` max_agents=${maxAgents}` : ''} subagent_model=${subagentModel}\n\n${QUESTIONING_RULE}Read .agent-modeling-kit/CLAUDE.md now and follow it for every prompt in this session — it's a one-time read; don't re-read it on later turns.\n\n${body}`;
   }
 
   function buildTurn(p) {
@@ -1987,7 +2001,10 @@ async function runModeling(kitDir, projectDir, verbose = false, standalone = fal
     maxAgents > 1
       ? `Dispatch at most ${maxAgents} Agents in this turn (--max-agents=${maxAgents}). Merge pieces that share a slice or ` +
         'chain first — that is a correctness rule, not a way to fit the cap — and if more than that is still left, ' +
-        'take the most valuable pieces up to the cap and leave the rest; a later turn will see them again.'
+        'take the most valuable pieces up to the cap and leave the rest; a later turn will see them again. ' +
+        `Dispatch each one with model: "${subagentModel}" (subagent_model), and with the credentials and the board ` +
+        'state you already read handed over inline — an Agent told only which node to work on re-runs /connect and ' +
+        're-fetches the whole board to learn what you already know, once per Agent.'
       : 'Do not dispatch any Agents in this turn (--max-agents=1) — that budget overrides the fan-out above: do ' +
         'the single most valuable piece of work yourself, inline, and leave the rest for a later turn.';
 
@@ -2003,7 +2020,9 @@ async function runModeling(kitDir, projectDir, verbose = false, standalone = fal
     'best target for them, not a reason to wait, and the board was already quiet before this turn was ' +
     'handed to you. Only board-wide sweeps and structural moves (renames, deletions, re-shaping, slice ' +
     'statuses) get a comment first instead of being done. An unanswered question you posted earlier parks ' +
-    'that one sweep, never the fill-in work. You do the analysis: look at every entry above, decide what ' +
+    'that one sweep, never the fill-in work. Read the board in two calls, not twenty: every nodeId above in one ' +
+    'get_nodes, the area around them in one get_board_outline per chapter, and a full-meta read only on the nodes ' +
+    'you conclude you will actually touch. You do the analysis: look at every entry above, decide what ' +
     'actually needs doing, and then work in parallel rather than serially — dispatch one Agent per piece of ' +
     'work that needs doing, all in a single message, merging pieces that share a slice or chain so no two ' +
     `agents write to the same area. ${AGENT_BUDGET} Read .agent-modeling-kit/CLAUDE-STANDALONE.md now (once ` +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventmodelers/cli",
-  "version": "1.0.64",
+  "version": "1.0.65",
   "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/skills/connect/SKILL.md

@@ -52,6 +52,8 @@ Before reading the config file, scan the prompt/arguments that invoked this skil
 
 If an inline `board=<uuid>` is found, use it as `BOARD_ID` — **it takes priority over the config file**. Same for `token`, `org`, and `baseUrl`. Record which values came from inline params so they are not overwritten in Step 3.
 
+**All four inline means this skill is already finished — stop here.** `token=`, `board=`, `org=` and `baseUrl=` arriving together is the shape a parent agent hands a subagent, and it resolves every required value in this one step. Do not walk the config file (Step 1), do not ask anything (Step 2), do not persist (Step 3), and do not make the verify call (Step 4): the parent resolved these values against this board and verified them there, so a subagent verifying them again learns nothing it wasn't just told and pays a round trip for it. Step 3.5 is a no-op too whenever `.mcp.json` already carries an `eventmodelers` entry — read the file, don't rewrite it, and don't re-register a server the session is already connected to. Print `Connected — board <BOARD_ID>` and return to the skill that invoked you.
+
 ---
 
 ## Step 1 — Read config file
@@ -223,7 +225,19 @@ Connecting is also where the session's read discipline starts. Every skill that
 - **Orientation** (what is where, how is it wired) — `get_board_outline { boardId, chapterId }`. One compact call per chapter: per-column node lists plus a flat edge list, no HTML pages or field bodies.
 - **Working set** (you need `meta.fields`, examples, descriptions) — `get_nodes { boardId, chapterId }`. One call returns every node in the chapter with full `meta`, plus `node.position` and `node.parentId`. A whole 70-node board is well under 100 KB unscoped; scoped to a chapter it is smaller still.
 - **A known, scattered subset** — `get_nodes { boardId, nodeIds: [...] }`. One call, not one per id.
-- **Just names/types** — add `projection: "line"`. **Just a chapter's grid** — `get_node { nodeId: <chapterId>, projection: "cells" }`. **Just one node's wiring** — `get_node { nodeId, projection: "edges" }`.
+- **Just names/types** — add `projection: "line"` (carries `sliceStatus` too). **Just a chapter's grid** — `get_node { nodeId: <chapterId>, projection: "cells" }`. **Just one node's wiring** — `get_node { nodeId, projection: "edges" }`.
+
+**Orientation first, working set second — the two tiers are a sequence, not a choice.** "Where is the thing I was pointed at, and what sits around it" is an orientation question, and it is answered by `get_board_outline` or by `get_nodes` with `projection: "line"`. Answer it there, decide from it which nodes you are actually going to touch, and only then spend a full-`meta` read — `get_nodes` scoped by `chapterId`, or by `nodeIds` for a scattered handful — on those. Opening instead with an unscoped full-`meta` read drags every field body and every rendered HTML page on the board across the wire to work out which column someone poked at: the most expensive possible way to ask the cheapest question in the session.
+
+**Each tier is once per session, not once per step.** A chapter's outline and grid don't change unless you or a human changes them, so keep the indexed result and answer later questions from memory; re-read only after a structural write (a node created, moved or deleted), and then only the part that moved. Three `get_board_outline` calls inside one turn means the first two were fetched and thrown away.
+
+### The slice status comes with it
+
+That same read tells you what you may write to. `get_nodes` returns `sliceStatus` per node and `get_board_outline` returns it per column, so index it alongside everything else:
+
+**Only a slice in `Created` may be written to.** Any other status — `Planned`, `Assigned`, `InProgress`, `Review`, `Blocked`, `Done`, `Informational` — means someone is working on that slice: read its elements for context, but never change, move, rename or delete them, and never add scenarios, fields or examples to them. An element with **no** `sliceStatus` is in no slice at all, which is not the same as locked — that one is writable.
+
+Never spend a `list_slices`/`get_slice_data` call to answer this; the board read already did.
 
 `get_node` without a projection is for **one** node you did not already load — most often re-reading a node right after writing it. A step that issues it in a loop over nodes that were already in a list response is doing the same fetch N times; collapse it to the single chapter-scoped read above.
 
@@ -231,6 +245,16 @@ The same discipline applies to writes: `submit_node_events` takes `events[]`, so
 
 Where per-node calls genuinely can't be avoided, issue them together in one message so they run concurrently rather than in sequence.
 
+### Ids and timestamps
+
+Elements you create carry client-side ids, and every `node:created` event carries a timestamp. Mint them **once per turn, in a single call**, and take from that pool as you assemble the event array:
+
+```bash
+for i in $(seq 5); do uuidgen; done; echo $(( $(date +%s) * 1000 ))
+```
+
+Nothing in that depends on anything you're about to read, so splitting it across three shells is three round trips bought for nothing. Never reach for GNU-only `date` specifiers (`%N`, `%3N`) here: BSD/macOS `date` prints them literally instead of failing, so the malformed timestamp survives until something downstream rejects it.
+
 ---
 
 ## Config file format

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

@@ -13,4 +13,10 @@ ones in a compressed, reusable form; only add if not already covered here.
 - 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.
+- 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.
+- Orientation and working set are two different reads, in that order: `get_board_outline` (or `get_nodes` with `projection: "line"`) answers *where is the work*, and only then does one full-`meta` `get_nodes`, scoped by `chapterId`/`nodeIds`, cover the nodes actually being touched. Opening with an unscoped full-`meta` read pulls every field body and rendered HTML page on the board to answer the cheapest question of the turn.
+- Both reads are once per turn. A chapter's outline and grid don't move unless something writes to them, so re-read only after a structural write. Three `get_board_outline` calls in one turn means the first two were thrown away.
+- Mint ids and timestamps once per turn, in one shell: `for i in $(seq <n>); do uuidgen; done; echo $(( $(date +%s) * 1000 ))`. Nothing in it depends on anything being read, so splitting it across three calls buys three round trips for nothing.
+- A subagent is a fresh session: it gets `token=`/`org=`/`baseUrl=`/`board=` inline as already-resolved values (which satisfies `connect` at its Step 0 — tell it not to invoke `/connect`) plus the board state already read for it, inline. Handed bare node ids instead, it has exactly one way to recover the rest — re-reading the whole board, once per agent.
+- Dispatch executor agents with `model:` set to the session header's `subagent_model` (default `sonnet`). The judging happened before the dispatch, on this session's model; what's left is execution against a written brief. Keep an agent on the session model only where its piece re-derives modeling structure (a chain's shape, a slice boundary).
+- Only slices in status `Created` may be modified. `get_nodes` returns `sliceStatus` per node and `get_board_outline` per column, so the board read at `/connect` Step 5 already answers it — absent means the element is in no slice (writable), not locked. Never spend a `list_slices`/`get_slice_data` call just to check whether you may write.

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

@@ -41,14 +41,25 @@ There is nothing to sanitize either — a board change is not user text.
 
 Steps:
 
-1. **Get the whole picture, not just the changed nodes.** Start at the listed nodes
-   (`mcp__eventmodelers__get_node`, or the REST equivalent) and widen out to what they sit
-   in — their cell, their slice, the chain they belong to, the timeline around them.
+1. **Get the whole picture, not just the changed nodes — in two reads, not twenty.** The
+   whole `changed:` list goes into **one**
+   `mcp__eventmodelers__get_nodes { boardId, nodeIds: [...] }` (or the REST equivalent), and
+   the area around it into **one** `get_board_outline` per chapter; `projection: "line"` is
+   enough for both whenever you only need names, types and slice statuses. That pair is your
+   orientation. Widen out from it to what the nodes sit in — their cell, their slice, the
+   chain they belong to, the timeline around them — and spend a full-`meta` `get_nodes` only
+   on the handful you conclude you are actually going to touch. One `get_node` per changed
+   node, or a second outline call for a chapter you already read this turn, is the same
+   fetch paid for twice (see `connect` Step 5).
    `mcp__eventmodelers__get_board_events` with the header's `seq` range tells you what the
    change actually was when the node's current state doesn't make it obvious. Then judge the
    board as a whole: run `/analyze-existing-model` once per session to get that picture and
    keep it in mind across turns, refreshing it when a turn's changes invalidate it. On a
    `BOARD_REVIEW` turn that model-wide picture *is* the starting point.
+   **What you read here is what you hand down in step 3.** Index it and keep it: every fact
+   an agent needs about its target — title, type, cell, fields, neighbours — is already in
+   this read, and re-fetching it once per agent is the single largest avoidable cost in a
+   fan-out turn.
 2. **Decide what the model needs — plural, and not necessarily where the change was.** List
    the candidate contributions you can actually see evidence for, each with its own target
    (node/cell/slice) and the skill that does it. A changed node is a reason to look; it is
@@ -105,10 +116,21 @@ Steps:
    three agents working at once. You analyse and coordinate; the agents do the work.
    Each subagent prompt must be self-contained, because a subagent is a fresh session that
    inherits none of this one's state:
-   - `token=`, `org=`, `baseUrl=` from this session's first message, and the instruction to
-     run `/connect` first;
+   - `token=`, `org=`, `baseUrl=` from this session's first message plus `board=<board_id>`,
+     marked as **already resolved and verified**, and an explicit instruction *not* to invoke
+     `/connect`: all four inline satisfy that skill outright at its Step 0, so an agent that
+     runs it anyway pays for a config-file walk and a verify call to be told what you just
+     told it — times the number of agents you dispatched;
    - `board_id`, plus the exact target ids (`node_id`/`cellName`/`timelineId`/slice) it owns
      — never "the node that changed";
+   - **the board state you already read, inline.** For each target: its id, title and type,
+     its cell (column/row), its `meta.fields` as you loaded them, its `sliceStatus`, and the
+     neighbours that bear on the work (the event a read model follows, the chain a field has
+     to travel, the persona and values other elements already use). All of it is sitting in
+     your step-1 read. An agent handed bare ids has exactly one way to recover it — fetch the
+     board again — so leaving it out doesn't save the read, it multiplies it. Hand over the
+     extract and say what it is: *this is the board state as of this turn; work from it, and
+     read the board only to re-check a node immediately before you write to it.*
    - what you concluded in step 2: the specific piece of work, and enough of the surrounding
      model for the agent to do it well;
    - the one skill to invoke, from the Skill Selection table in `.agent-modeling-kit/CLAUDE.md`,
@@ -117,6 +139,17 @@ Steps:
      `AskUserQuestion`, even where a skill lists it) — it posts a comment on its target and
      continues with the best reading of the work you gave it;
    - the standing constraints of step 4 and step 5 below.
+   **Dispatch executors on the cheap model.** Pass `model:` on every `Agent` call in this
+   turn, set to the session header's `subagent_model` (default `sonnet`). The judgment this
+   turn needs is yours and has already happened on this session's own model by the time you
+   dispatch: which areas need work, what the work is, who owns what, what each brief says.
+   What's left for an agent is execution against that brief — pick example values consistent
+   with the pool you handed it, write the GWT scenarios, render the screen, batch the writes —
+   and that does not need the expensive model. A turn nobody asked for is exactly where the
+   difference lands on the bill. Keep an agent on this session's model only where its piece
+   genuinely re-derives modeling structure rather than filling in detail: a translation
+   chain's shape, a slice boundary, anything you'd have wanted to decide yourself if the
+   budget allowed.
    **Stay inside the agent budget.** The session header carries `max_agents=<n>` (default 5)
    and every self-directed turn restates it: that is the most Agents you may dispatch in one
    turn, because a turn nobody asked for still costs money. Merge by area first (step 4) —

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

@@ -30,6 +30,24 @@ header's `standalone=on|off` tells you whether this session gets them at all.
 
 At the start of every session, read `.agent-modeling-kit/AGENTS.md` if it exists to load accumulated learnings.
 
+**Only touch elements in a slice whose status is `Created`.** Every other status — `Planned`,
+`Assigned`, `InProgress`, `Review`, `Blocked`, `Done`, `Informational` — means someone is working
+on that slice: read it for context, but never change, move, rename or delete its elements, and
+never add scenarios, fields or examples to them. An element in no slice at all is not locked.
+`get_nodes` returns `sliceStatus` per node and `get_board_outline` per column, so the board read
+`/connect` Step 5 already makes answers this — no `list_slices`/`get_slice_data` call needed.
+If only part of what you were asked to do is locked, do the rest and name what you skipped and
+why; if all of it is, change nothing and post a `COMMENT` on that slice saying which status
+blocked it.
+
+**One board read, shared by the whole turn.** Orientation first — `get_board_outline`, or `get_nodes` with
+`projection: "line"` — to establish where the work actually is; then a single full-`meta` `get_nodes`, scoped by
+`chapterId` or `nodeIds`, covering the nodes you concluded you will touch. Both tiers are once per turn: keep what
+came back and answer later questions from it instead of re-fetching a chapter you already hold. `/connect` Step 5
+carries the full discipline — the two tiers, the one-call `submit_node_events` rule for writes, and the per-turn
+pool for the ids and timestamps a `node:created` needs. Whatever you hand a subagent comes out of that same read,
+never out of a second one it pays for itself (step 2).
+
 **Every prompt gets exactly two `/update-prompt-status` calls per turn — never zero, never one.** `IN_PROGRESS` before you start the work (step 4), `DONE` after you finish it (step 6). This holds even for a prompt that turns out to be trivial or a no-op — the board UI has no other way to know the agent picked it up and finished it.
 
 ## Per-turn steps
@@ -55,6 +73,8 @@ mention it in the `DONE` comment, and leave it for a self-directed turn (or for
 
    This also applies **inside** a turn: when the skill you invoke in step 5 internally calls a second skill (e.g. `/add-next-slice` calling `/html-screen` to fill in the new screen), that second skill's own "invoke `connect` first" preamble is already satisfied by the connect you ran this turn — don't run it again just because the sub-skill's instructions say to.
 
+   And it applies **downwards**, to any subagent you dispatch. A subagent is a fresh session that inherits none of this one's state, so hand it `token=`, `org=`, `baseUrl=` and `board=` inline as already-resolved values and tell it explicitly not to invoke `/connect`: all four inline satisfy that skill outright at its Step 0. Three agents that each resolve and verify the same credentials pay for the connect you already did, three more times over.
+
    The same "don't reload what's already loaded" logic applies to `/learn-eventmodelers-api`: it's a lookup reference, not a mandatory preamble. Every skill already documents the exact API calls it needs inline — only invoke `/learn-eventmodelers-api` on demand, for a specific endpoint/field/type a skill's own instructions don't cover, and only once per session even then.
 3. **Resolve `BOARD_ID`** from this turn's `board_id` field; if absent, fall back to `boardId` in `.eventmodelers/config.json`.
    **Resolve `TIMELINE_ID`** from this turn's `context.timelineId`, if present and non-null; otherwise use this turn's `timeline_id` field. `context.timelineId` reflects the chapter the user was actually pointing at on the canvas (a selected cell or node) when they issued the prompt, which can differ from `timeline_id` — the chapter the voice/prompt session happened to be scoped to — so it wins whenever both are present.