@eventmodelers/cli 1.0.108 → 1.0.109

package/package.json

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

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

@@ -30,7 +30,7 @@ Write tools take their items as an array (`nodeIds[]`, `elements[]`, `connection
 | `get_node` | `boardId`, `nodeId`, `projection?` (`"cells"` \| `"edges"`) | Get one node (no `cellName` — address it by `nodeId`; cell addresses come only from `get_board_outline`). `projection: "cells"` (CHAPTER nodes only) returns just `{rows, columns, cells}` instead of the full `timelineData` — use whenever only the grid/occupancy is needed, not the whole chapter; `projection: "edges"` returns just that node's inbound/outbound connections instead of `findNodeById`'s full record. Both are opt-in — omitting `projection` is the unchanged full response. An unknown id is a `NODE_NOT_FOUND` error | §3 `GET .../nodes/:nodeId` (REST returns the node as stored, without `cellName`; `404` carries `code: 'NODE_NOT_FOUND'`) |
 | `get_node_comments` | `boardId`, `nodeId` | List comments on a node | §1 `GET .../nodes/:nodeId/comments` |
 | `get_chat_attachment` | `boardId`, `sessionId`, `attachmentId` | The file a chat message came with — the message's `attachments` list `{id, type, ending}`. Images come back as images, a PDF as an embedded resource, csv / xml / txt / json as text. Only the agent the message was addressed to can read it (`CHAT_ATTACHMENT_NOT_FOUND`); needs the connection's `x-agent-id` (`CHAT_AGENT_REQUIRED`). Max 5 MB per file. | §15 `GET /api/org/:orgId/chat/sessions/:sessionId/attachments/:attachmentId` |
-| `post_chat_message` | `boardId`, `text`, `replyTo?`, `sessionId?`, `preferUserId?`, `snippet?` | Write into a person's chat — a reply (`replyTo` marks their message answered) or a question you start (`preferUserId`). `text` ≤ 1000 characters. `snippet` attaches one interactive element under the text (confirm, poll, tasks, changes, link, image, code); the person's choice comes back as their next chat message. See §16 | §16 `POST /api/org/:orgId/boards/:boardId/chat/agent-messages` |
+| `post_chat_message` | `boardId`, `text`, `replyTo?`, `sessionId?`, `preferUserId?`, `snippet?` | Write into a person's chat — a reply (`replyTo` marks their message answered) or a question you start (`preferUserId`). `text` ≤ 1000 characters. `snippet` attaches one interactive element under the text (confirm, poll, tasks, changes, link, image, code, report); the person's choice comes back as their next chat message. See §16 | §16 `POST /api/org/:orgId/boards/:boardId/chat/agent-messages` |
 | `get_board_events` | `boardId`, `since?`, `seq?` | A page of at most 300 board events, oldest first, as `{events, pageSize, hasMore}`. Not the whole log: while `hasMore` is true, page on by passing the last event's `seq` as `since`. `seq` returns only the event of exactly that seq | §1 `GET .../events` |
 | `submit_node_events` | `boardId`, `events[]`, `autoConnect?`, `compact?` | Create/update nodes (raw `NodeChangeEvent`/edge events). Every event property is described on the tool's own `events[]` schema — read that rather than this skill when all you need is the event shape. An event needs its own `id` (required — a fresh uuid per event, never the node id) and its `eventType`, plus the keys of its kind (`nodeId`/`meta`/`node`, or `edgeId`/`source`/`target`). The `id` keys the returned `hashes` map and makes a resubmit idempotent — the same event sent twice under one id writes a single board event. Don't send `boardId` or `timestamp` per event — the server takes the board from the call and stamps the time itself, and ignores both if sent. `autoConnect: false` places freshly-created nodes without wiring them to their own/previous-column neighbors (avoids a stray nearest-left edge); `compact: true` returns `{persisted: <count>}` instead of the per-node hash map | §3 `POST .../nodes/events` |
 | `delete_node` | `boardId`, `nodeIds[]` | Delete nodes, applied in order — one failure doesn't stop the rest; answers `{results}`. Deleting a chapter (timeline) cascades — every node placed in one of its cells, plus any node parented to it (e.g. SLICE_BORDER), is deleted too, along with all their edges | (via `node:deleted` event, §3) |
@@ -1099,8 +1099,9 @@ Rule of thumb: if you are about to write "Shall I…?", "Want me to…?", "A or
 | to point at an element | `link` | nothing — it pans the canvas |
 | to show a picture | `image` | nothing |
 | to show a command or payload | `code` | nothing |
+| to show numbers as a diagram (counts per slice, a trend, shares of a whole) | `report` | nothing |
 
-`confirm`, `poll`, `tasks` and `changes` are questions: a person answers once, then they show as answered. `link`, `image` and `code` are display only and never wait for anything.
+`confirm`, `poll`, `tasks` and `changes` are questions: a person answers once, then they show as answered. `link`, `image`, `code` and `report` are display only and never wait for anything.
 
 ### Shapes
 ```typescript
@@ -1118,6 +1119,9 @@ Rule of thumb: if you are about to write "Shall I…?", "Want me to…?", "A or
 { kind: 'link',    nodeId: string, label?: string }
 { kind: 'image',   url: string, alt?: string, caption?: string }                  // https or png/jpg/gif/webp data URL; no svg
 { kind: 'code',    code: string, language?: string, title?: string }              // monospaced, with a copy button
+{ kind: 'report',  chart: 'bar' | 'line' | 'pie', title?: string, unit?: string,
+  labels: string[],                                                               // 1–50 points: x axis, or the pie slices
+  series: Array<{ name: string, values: number[] }> }                             // one number per label; bar/line up to 6 series, pie uses only the first (no negatives)
 ```
 
 ### How to use them
@@ -1127,6 +1131,7 @@ Rule of thumb: if you are about to write "Shall I…?", "Want me to…?", "A or
 - **Name elements** with `nodeId` wherever you can (`tasks`, `changes`, `link`), so the person can click through to them — in a `tasks` list, put the element's name in `description` and its id in `nodeId`.
 - **Answers are text.** For a `tasks` answer, match the titles (or ids) back to your list; an element the person left unticked was declined, not forgotten. A `poll` option with a `message` of your own makes the answer unambiguous.
 - `get_chat_session` shows your snippet on the message as `snippet`, and the person's answer is the user message after it, carrying `context.snippetReply.messageId` (your message's id) — useful to tell an answer to a snippet from a new message.
+- **`report`** draws the numbers you send — it computes nothing, so aggregate first. A series whose length differs from `labels`, or a non-number, makes the whole snippet invisible. Keep `text` as a one-line summary of what the diagram shows.
 - A snippet is shown exactly as you send it — keep secrets and tokens out of `code` and `image`.
 
 ---

package/stacks/modeling-kit/templates/.claude/skills/analyze-existing-model/SKILL.md

@@ -199,6 +199,31 @@ Total: <n> slices
 <2–4 sentences: overall model maturity, the most important gap or risk, one concrete suggestion>
 ```
 
+### In a chat — answer with a pie chart
+
+When this run has a chat (`CHAT_SESSION_ID` is set — a prompt's `origin_session_id`, or a `CHAT` turn), the report goes
+to the chat as **one** `post_chat_message` (`sessionId` = `CHAT_SESSION_ID`; `replyTo` = this turn's `message_id` in a
+`CHAT` turn) carrying a **`report` snippet**: a pie of the slice status breakdown (5b). The text is the short summary
+(contexts, spec coverage, the most important gap) — that is also the fallback if the snippet cannot be shown. Skip the
+long format above; mention the structural gaps and shapes in a sentence or two, and offer the full list on request.
+
+```
+mcp__eventmodelers__post_chat_message {
+  "boardId": "$BOARD_ID",
+  "sessionId": "<CHAT_SESSION_ID>",
+  "text": "3 contexts, 24 slices. 18 of 24 have scenarios; Checkout has 4 slices without any.",
+  "snippet": {
+    "kind": "report", "chart": "pie", "title": "Slices by status", "unit": "slices",
+    "labels": ["Done", "InProgress", "Planned", "Blocked"],
+    "series": [{ "name": "Slices", "values": [12, 6, 4, 2] }]
+  }
+}
+```
+- Only statuses with at least one slice, one number per label — the chart draws exactly what you send, so count first.
+- One snippet per message: if the person asks for more diagrams (spec coverage, element inventory per type as a `bar`),
+  answer each in its own reply.
+- Still read-only: nothing is posted to the board.
+
 If a context was specified but not found, tell the user clearly and list the contexts that do exist.
 
 ---

package/stacks/modeling-kit/templates/.claude/skills/detect-architecture-drift/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: detect-architecture-drift
+description: Compare the event model on the board with the code in this repository and report where they have drifted apart — fields on commands/events/read models, specifications vs tests, screens, edges, slices missing in code, and slices in code that the model doesn't have. Read-only; every finding comes with a suggested fix the user confirms first.
+---
+
+# Detect Architecture Drift
+
+> **Before doing anything else**, invoke the `connect` skill — if not already connected — to resolve `TOKEN`, `BOARD_ID`, `ORG_ID`, and `BASE_URL`. Do not proceed until the connect skill has completed.
+
+Prefer `mcp__eventmodelers__*` tools when available. See `learn-eventmodelers-api` for the curl fallback.
+
+The board is the intended design, the code is what was built. Over time the two part ways: someone edits a handler without touching the model, someone renames a field on the board after the slice was built. This skill finds those places and proposes how to close each gap. **It never changes the board or the code** — it reports, and only acts on what the person confirms.
+
+---
+
+## Step 1 — Parse arguments and resolve scope
+
+From `$ARGUMENTS` and the prompt context, extract:
+
+| Field | How to find it | Default |
+|-------|---------------|---------|
+| `timelineId` | `context.timelineId` of the prompt (overrules the prompt's own `timeline_id`), or a timeline/chapter named in the text | whole board |
+| `contextName` | a bounded context named in the text | all contexts |
+| `sliceTitle` | a single slice named in the text | all slices in scope |
+
+**If a timeline is in focus, only that timeline's slices are compared** — both on the board side and, through the slice → code mapping of Step 3, on the code side. Code that belongs to no slice in scope is not reported as "additional" in a scoped run; say so in the report footer instead of guessing.
+
+---
+
+## Step 2 — Read the model (once)
+
+Cheapest read first, once per run:
+
+```
+mcp__eventmodelers__list_slices   { "boardId": "$BOARD_ID" }
+mcp__eventmodelers__get_slice_data { "boardId": "$BOARD_ID", "contextName": "<CONTEXT>", "format": "toon" }
+```
+
+Use the **full** slice data (no `projection`): you need fields with types and `idAttribute`, dependencies (the edges), specifications, storylines and screens together. If the scope is a timeline, pass its title as `contextName` and keep only slices whose `chapter` is that timeline.
+
+Call `validate_model { boardId, chapterId }` for a scoped timeline — it already lists structural gaps on the board side (zero/multi-issuer commands, sourceless read models, missing scenarios). Those are model problems, not drift: mention them in one line, don't duplicate them as findings.
+
+Index the result in memory: per slice → commands, events, read models, screens, automations, specifications, dependencies.
+
+---
+
+## Step 3 — Understand the code
+
+You are in a repository that may hold any stack. Find out which, don't assume.
+
+1. Read `.build-kit/CLAUDE.md` (and `.build-kit/AGENTS.md` if present) — its *Structure* section says where slices live and how they're named (e.g. `src/slices/{slice}/` for Node, `src/main/java/.../slices/{context}/{slice}/` for Axon).
+2. If `.build-kit/.slices/<context>/<slice>/slice.json` exists, it is the snapshot the code was **last built from** — useful for telling "the code changed" apart from "the model changed since the build" (see Step 5).
+3. Without a build kit, infer the layout from the repo (folders named after slices, `*Command*`, `*Event*`, projection/read-model files, route/UI files). If you cannot find any slice structure, stop and tell the user what you looked at — do not fabricate a mapping.
+
+Build a **code inventory** per slice folder: the command type and its fields, the events it emits and their fields, read-model/projection types and fields, the screens/components/routes wired to it, tests and what they assert, and what each handler/projection/automation reads and writes.
+
+Map slice → code folder by name (ignore case, spaces and the `slice:` prefix, same slug rule as `load-slice`). A slice with no matching folder, or a folder with no matching slice, is itself a finding (5a/5b).
+
+Read only the slice folders in scope. Shared event/type folders are read only for the events the in-scope slices reference.
+
+---
+
+## Step 4 — Compare
+
+Work slice by slice. Every finding records: **kind**, **slice**, **element** (board `nodeId` where there is one), **what the model says**, **what the code says**.
+
+| Kind | Look for |
+|------|----------|
+| **Slice missing in code** | Slice on the board in status `Planned`/`InProgress`/`Done`… with no code folder. Status `Created`/`Planned` is expected not to have code yet — report only slices the board calls `Done`/`Review`. |
+| **Slice only in code** | Code folder shaped like a slice (command handler, projection, automation) with no slice on the board. |
+| **Fields** | On every COMMAND, EVENT and READMODEL: a field only in the model, a field only in the code, a name that differs (case or typo), a type that differs, `idAttribute` vs `@TargetEntityId`/event tag/aggregate key mismatch, optional vs required. |
+| **Specifications** | A model GWT scenario with no test asserting it; a test (given/when/then) with no matching model scenario; a scenario whose events/fields no longer match the code. Storylines are narrative — compare their beats only for elements that no longer exist. |
+| **Screens** | A SCREEN on the board with no UI counterpart; a UI screen/route/component wired to a slice's command or read model that the board doesn't show; a screen whose displayed read-model fields or submitted command fields differ from the model's dependencies. |
+| **Edges** | Model dependency with no code counterpart, and the reverse: command → event (handler emits it), event → read model (projection consumes it), read model → screen, event → automation → command. A handler that emits an event the model doesn't connect, or a projection subscribing to events the model doesn't wire in. |
+| **Elements** | An event/command/read model present on one side only, or a rename (same fields, different name). |
+
+Rules for judging, in order:
+
+- **Obvious typos and clearly wrong flags are one finding with a direct fix** (`custoemrId` in the code vs `customerId` on the board; `idAttribute: false` on the entity's own id) — name the correct side, don't ask which it is.
+- **Direction matters.** A mismatch with no earlier evidence has no "right" side: propose the fix in the direction the evidence points (see Step 5), and say when it is a judgement call.
+- Don't report framework noise: generated ids, metadata/envelope fields, serialization annotations, test fixtures' helper types, routes when the slice has no screen.
+- Don't flag what is clearly intentional (an internal slice with no screen; a read model used only by another read model).
+- Report each underlying difference **once**, at the element where it starts; a renamed field shows up on the command and the event and the read model — that is one finding listing the chain, not three.
+
+---
+
+## Step 5 — Decide the direction, propose the fix
+
+For every finding, pick who should move:
+
+| Evidence | Fix goes to | How it's done |
+|----------|-------------|---------------|
+| Code differs from `.build-kit/.slices` snapshot, board still equals the snapshot | **Model** — the code moved on deliberately | Skill that changes the board: `/attributes` (fields), `/timeline` / `/place-element` (elements), `/eventmodeling-elaborating-scenarios` (specs), `/storyboard-screen` or `/html-screen` (screens) |
+| Board differs from the snapshot, code still equals it | **Code** — the model moved on | Set the slice back to `Planned` with `/update-slice-status` so the build kit picks it up again and diffs code against `slice.json` |
+| Both moved, or no snapshot | **Judgement call** — present both options, recommend one | Recommend by which side is more specific/complete |
+| Slice only in code | **Model** | Add the slice, via `/eventmodeling-slicing-event-models` after placing its elements |
+| Slice missing in code, board says `Done` | **Model status** (it isn't done) | `/update-slice-status` → `Planned` |
+
+Never propose "fix the code" by editing it from this skill — code changes belong to the build kit (`/update-slice-status` → `Planned`).
+
+---
+
+## Step 6 — Show the findings; act only on confirmation
+
+Nothing is modified until the person answers.
+
+### In a chat (`CHAT_SESSION_ID` is set)
+
+Post **one** `post_chat_message` with a `tasks` snippet — the list of findings *and* the question which fixes to apply (same mechanics as `/wdyt` Step 4.0):
+
+```
+mcp__eventmodelers__post_chat_message {
+  "boardId": "$BOARD_ID",
+  "sessionId": "<CHAT_SESSION_ID>",
+  "text": "Found 6 places where the model and the code differ in Registration. Tick the fixes to apply.",
+  "snippet": {
+    "kind": "tasks",
+    "headline": "Apply these fixes?",
+    "submitLabel": "Apply",
+    "tasks": [
+      { "id": "d:model:<nodeId>:field:customerId", "title": "Rename field “custoemrId” to “customerId” on Register Customer", "description": "Code has customerId — model has a typo", "nodeId": "<nodeId>" },
+      { "id": "d:code:<sliceId>", "title": "Rebuild “Cancel Order” — the board added the field “reason” after it was built", "description": "Sets the slice back to Planned", "nodeId": "<sliceId>" }
+    ]
+  }
+}
+```
+
+- `title` is the proposed fix, one sentence, plain language. `description` says what differs (model vs code). `nodeId` is the element or slice border to jump to.
+- `id` is `d:<model|code|decide>:<nodeId>:<kind>[:<detail>]` — the answering turn remembers nothing, so it must carry the direction and target. Put **every** finding in the one snippet (it pages itself at 5).
+- Zero findings: a one-line text reply, no snippet. Then **end the turn.**
+
+The answer comes as a `CHAT` turn (`Please do these:` + ticked titles or ids). Read the snippet back with `get_chat_session`, match what was ticked, and create **one prompt** per direction: model fixes → *"Apply these model-drift fixes: `<id> | <title>` per line"*; code fixes → set each slice to `Planned`. Unticked fixes are declined — drop them.
+
+### Without a chat
+
+Print the report below, with every finding as a `- [ ]` checkbox carrying its proposed fix, and ask which to apply. Wait for the answer.
+
+```
+## Architecture Drift — <scope: board | timeline "<title>" | context "<name>">
+Compared: <n> slices on the board, <n> slice folders in code    Analysed: <ISO timestamp>
+
+### Slices
+- [ ] <slice> — in code, not on the board → add it to the model
+- [ ] <slice> — board says Done, no code → set back to Planned
+
+### Fields
+- [ ] <slice> / <element>: model `customerId: String`, code `custoemrId` → fix model typo
+
+### Specifications / Screens / Edges
+- [ ] ...
+
+### Summary
+<2–3 sentences: how far apart they are, which direction the drift mostly runs, the one fix worth doing first.>
+Not checked: <what was out of scope or unreadable>
+```
+
+Omit empty sections. Say plainly when nothing drifted.
+
+---
+
+## Learnings
+
+- Read-only until confirmed — the report is the product; the fixes run as separate, ticked work.
+- A scoped run (timeline in focus) never reports "slice only in code" for code outside the scope.
+- One difference, one finding: follow a rename along the chain instead of listing it per element.

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

@@ -203,7 +203,7 @@ for it. Instead:
      and posts nothing to the board until they answer (`/wdyt` Step 4.0). Your reply here is one line —
      *"On it — looking at Registration."*
    - **a skill by name** — the message starts with `/<name>` of one of your skills (the chat panel's menu
-     writes these: `/analyze-existing-model`, `/add-next-slice`, `/examples`, `/timeline …`,
+     writes these: `/analyze-existing-model`, `/detect-architecture-drift`, `/add-next-slice`, `/examples`, `/timeline …`,
      `/html-screen …`, `/storyboard …`): the person chose that skill, so it **is** the work — create one prompt,
      *"Run /<name> <the rest of the message>"*, with the target resolved from `context=` like any other
      (selected elements, chapter), and say so in one line. Don't re-interpret it as a question. A skill that
@@ -356,6 +356,7 @@ nothing to sanitize either, since a board change is not user text.
 | Design or update a single wireframe/sketch screen (explicit request only) | `/storyboard-screen` |
 | Business analysis, gap spotting, posting questions | `/wdyt` |
 | Analyse the existing model structure, slice coverage, element counts | `/analyze-existing-model` |
+| Find where the model and the code have drifted apart (fields, specs, screens, edges, missing/extra slices) and propose fixes | `/detect-architecture-drift` |
 | Turn a document or image (e.g. a tender/RFP) into a chaptered event model with screens, scenarios and a written blueprint summary | `/summarize` |
 | Look up any API endpoint or element type not already covered by the skill you're executing | `/learn-eventmodelers-api` |
 | Add or rename an attribute across a chain of elements | `/attributes` |