@eventmodelers/cli 1.0.36 → 1.0.38

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-orchestrating-event-modeling/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: eventmodeling-orchestrating-event-modeling
-description: "Orchestrates complete event modeling workflow from requirements to code generation. Models architecture as UI/Processor → Command → Event → Read Model. Use when modeling a domain end-to-end from requirements. Do not use for: executing a single step in isolation (invoke the named step skill directly, e.g., eventmodeling-brainstorming-events for Step 1 or eventmodeling-elaborating-scenarios for Step 7), validating an already-completed model (use eventmodeling-validating-event-models), or modernizing legacy systems (use eventmodeling-integrating-legacy-systems)."
+description: "Orchestrates complete event modeling workflow from requirements to code generation. Models architecture as UI/Processor → Command → Event → Read Model. Use when modeling a domain end-to-end from requirements. Do not use for: executing a single step in isolation (invoke the named step skill directly, e.g., eventmodeling-brainstorming-events for Step 1 or eventmodeling-elaborating-scenarios for Step 7), or validating an already-completed model (use eventmodeling-validating-event-models)."
 allowed-tools:
   - AskUserQuestion
   - Write
@@ -11,6 +11,8 @@ allowed-tools:
 
 > **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 it has completed. Consult `learn-eventmodelers-api` only if you need to look up a specific endpoint or field this file doesn't cover — don't load it eagerly.
 
+This step applies the shared element rules in **`eventmodeling-core-rules`** — read it once per session if you haven't already; it defines what a COMMAND/EVENT/READMODEL/SCREEN/AUTOMATION is, how each is named, and the anti-patterns to reject, so this step doesn't restate them.
+
 Prefer `mcp__eventmodelers__*` tools when available (registered by the `connect` skill) — the curl blocks below are the fallback for sessions without MCP connected.
 
 Coordinates the 11-step Event Modeling workflow. Each step delegates to a
@@ -37,11 +39,15 @@ These rules govern how every element is placed on the board. Enforce them throug
 - SCREEN (input/command screen) goes in the **actor row of that same column**.
 - **A COMMAND never stands alone.** Every COMMAND must have exactly one issuer in the actor row of its own column: a SCREEN when a human triggers it, an AUTOMATION when a processor or external-system integration triggers it. There is no third option and no exemption — a command with an empty actor-row cell is an unresolved gap the moment it's placed, not something to leave for a later step to notice. This applies just as much to a command that only *represents* an externally-triggered integration event crossing into this chapter (Step 1/Step 6 territory) as to any other command: place an AUTOMATION for the external actor even when that actor's own decision logic is out of scope for this model — the automation node documents *that* something triggers the command, not *how* it decides to.
 
-  Every AUTOMATION placed this way still needs its own todo-list READMODEL per `eventmodeling-identifying-outputs` Step 5b — including one whose trigger is an external integration signal. There is no exemption for this either: even when the only visible trigger is the automation's own resulting event, model a todo list that opens and closes within that same slice (per Step 5b's worked pattern) rather than leaving the automation without an incoming READMODEL.
+  **Before placing that automation, check whether the trigger is already a placed EVENT node in a second (external) swimlane** (from Step 1/brainstorming), as opposed to an unmodeled webhook/API call with no such node. These are not the same case:
+  - **No pre-existing EVENT node** (a plain webhook/API trigger) — place the AUTOMATION+COMMAND in one column as usual; the command produces a new EVENT there. Nothing further needed in Step 4.
+  - **A pre-existing EVENT node in another system's swimlane** — do **not** place the AUTOMATION/COMMAND in that event's column, and do **not** connect `COMMAND → EVENT` to it: that event already happened in another system and cannot be "produced" by a command in this one. Attribute the command to the Role Catalog and list it in the Command Catalog as *pending Step 4b*, but leave its placement and every one of its connections to Step 4b — placing it here only produces a wrong connection that Step 4b then has to delete and redo.
+
+  Every AUTOMATION placed this way still needs its own todo-list READMODEL, and one further rule governs *how* it's triggered: **an automation can only ever be directly triggered by an internal event — never by another system's event.** A signal arriving from a second swimlane must first be translated into an internal event by its own dedicated translation automation (external EVENT → todo-list READMODEL → translation AUTOMATION+COMMAND+*internal* EVENT) before any worker automation reacts to it — never one automation whose todo list is opened by the external EVENT directly. There is no exemption for a "pure relay" automation either — even one triggered only by its own resulting event still gets a todo list that opens and closes within the same slice. This is designed immediately after Step 4, in **Step 4b — Design Automation Chains** (`eventmodeling-designing-automation-chains`), precisely so it's resolved before Step 5 ever has to catch it as a gap.
 
 ### State-view slice (EVENT → READ MODEL → SCREEN)
 - READ MODEL goes in the **interaction row** of a column that is **immediately after the primary source event's column** — never at the end of the timeline.
-- SCREEN (view/output screen) goes in the **actor row of the same column as the READ MODEL**.
+- SCREEN (view/output screen) goes in the **actor row of the same column as the READ MODEL**. When that column's interaction row is unavailable to the read model (e.g. already holds a COMMAND), the **read model** gets a new column immediately **before** the screen's — the screen's own position is never moved to resolve this (`eventmodeling-identifying-outputs`'s Step 5g has the full mechanics).
 - If the primary source event's column already has a COMMAND in the interaction row, insert a **new column immediately after** (using `index = currentColumnIndex + 1`) and place the READ MODEL there.
 
 ### Never stack read models at the end
@@ -71,7 +77,7 @@ This is a **business-modeling decision, not a technical one** — it is not trig
 
 The question to ask is simply: **is this fact worth a new event?** A derived condition — "is this available right now," "has this moved to its next stage," etc. — is worth its own event when it's a fact a domain expert would recognize and name in its own right (not just "some field I compute"), and when that fact is valuable to a later step in the process — another automation would react to it, a different bounded context would want to subscribe to it, some downstream process needs to trigger off of it. If both hold, it deserves to exist as its own dedicated event — e.g. "the copy was marked available" — not just as derived read-model logic recomputed from several other events.
 
-When that's the case, model it as its own event, produced via the same todo-list + automation translation pattern Step 5b uses for external integrations, but triggered internally by whichever raw events can produce that outcome. If the condition is purely for display, with nothing downstream that would ever act on it, it stays a plain read-model projection — no new event needed, no matter how many raw events feed it or how wide the resulting fan-in looks.
+When that's the case, model it as its own event, produced via the same todo-list + automation translation pattern `eventmodeling-designing-automation-chains` (Step 4b) uses for external integrations, but triggered internally by whichever raw events can produce that outcome. If the condition is purely for display, with nothing downstream that would ever act on it, it stays a plain read-model projection — no new event needed, no matter how many raw events feed it or how wide the resulting fan-in looks.
 
 **Only fold together causes that are genuinely redundant for the same outcome — never causes that carry distinct business meaning.** A derived condition's causes typically split into two groups: several distinct events that all mean the *same* thing from the business's point of view (e.g. `CopyReservationReleased`, `CopyReturned`, and `CopyReturnedFromRepair` all mean "the copy is available again"), and several distinct events that each mean something the business still wants told apart (e.g. `CopyReserved` → Reserved, `CopyCheckedOut` → CheckedOut, `CopySentForRepair` → UnderRepair, `CopyReportedLost` → Lost, `CopyWithdrawn` → Withdrawn). Only the first group is safe to consolidate — a dedicated event like `CopyMarkedAvailable` collapses "N different reasons, same outcome" into one reusable signal without losing information. Collapsing the second group into something like a generic `CopyMarkedUnavailable` would erase the *why*, which some downstream consumer may actually need — leave those as separate events and direct connections, even though the read model's fan-in then stays wider than the fully-consolidated ideal. That remaining fan-in is not a failure of anything — it means those events are each individually meaningful, not synonymous with each other, and collapsing them would have been the actual modeling mistake.
 
@@ -81,19 +87,13 @@ After each step that creates elements (Steps 1–5), scan for any nodes that hav
 
 For each timeline in scope, check all node types that should be in cells.
 
-**Prefer MCP:** call `get_nodes` once per type (each call returns the full node objects, including `meta.chapterId`/cell placement, so no separate cell-occupancy lookup is needed):
+**Prefer MCP:** run `validate_model` once per chapter — the `unplaced` findings it returns are exactly this scan, plus five other structural checks, in one call and with a compact response (no full node objects):
 ```
-mcp__eventmodelers__get_nodes { "boardId": "$BOARD_ID", "type": "EVENT" }
-```
-Repeat with `"type": "COMMAND"`, `"READMODEL"`, `"SCREEN"`, `"AUTOMATION"`.
-
-**Fallback (no MCP):**
-```bash
-for TYPE in EVENT COMMAND READMODEL SCREEN AUTOMATION; do
-  curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
-    "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=$TYPE"
-done
+mcp__eventmodelers__validate_model { "boardId": "$BOARD_ID", "chapterId": "$TIMELINE_ID" }
 ```
+Only fall back to per-type `get_nodes` (`chapterId`-scoped, once each for `EVENT`, `COMMAND`, `READMODEL`, `SCREEN`, `AUTOMATION`) when you also need the node bodies for another reason in the same pass.
+
+**Fallback (no MCP):** see `references/api-fallback.md` — "No unplaced elements (0,0 nodes) — Scan for unplaced nodes".
 
 For each returned node, check whether it has a valid cell assignment. A node without a `cellId` (or with `chapterId` missing) is unplaced.
 
@@ -105,15 +105,7 @@ For each returned node, check whether it has a valid cell assignment. A node wit
   mcp__eventmodelers__drop_node_to_cell { "boardId": "$BOARD_ID", "timelineId": "<chapterId>", "cellId": "<rowId>-<colId>", "nodeId": "<nodeId>", "nodeType": "<TYPE>" }
   ```
 
-  **Fallback (no MCP):**
-  ```bash
-  curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/events" \
-    -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" -H "x-user-id: orchestrator" \
-    -H "Content-Type: application/json" \
-    -d '[{"id":"<uuid>","eventType":"node:changed","nodeId":"<nodeId>","boardId":"<BOARD_ID>",
-          "timestamp":1234567890,"chapterId":"<chapterId>","cellId":"<rowId>-<colId>",
-          "meta":{"type":"<TYPE>","title":"<title>"}}]'
-  ```
+  **Fallback (no MCP):** see `references/api-fallback.md` — "No unplaced elements (0,0 nodes) — Place a found unplaced node".
 - **If it is an orphan (duplicate or no longer needed)** → delete it.
 
   **Prefer MCP:**
@@ -121,18 +113,14 @@ For each returned node, check whether it has a valid cell assignment. A node wit
   mcp__eventmodelers__delete_node { "boardId": "$BOARD_ID", "nodeId": "<nodeId>" }
   ```
 
-  **Fallback (no MCP):**
-  ```bash
-  curl -s -X DELETE "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/<nodeId>" \
-    -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID"
-  ```
+  **Fallback (no MCP):** see `references/api-fallback.md` — "No unplaced elements (0,0 nodes) — Delete an orphaned node".
 
 Never leave an unplaced node on the board when proceeding to the next step.
 
 ### No backward arrows
 The timeline must always progress left-to-right — this is the goal to design toward, not just a validation check to run afterward. Every connection arrow — SCREEN→COMMAND, COMMAND→EVENT, READMODEL→SCREEN, READMODEL→AUTOMATION, AUTOMATION→COMMAND — must point to the right or downward (within the same column). A right-to-left arrow among these is always a layout error, full stop.
 
-**`EVENT → READMODEL` has exactly one exception, and it is narrow.** A read model that already carries a `READMODEL → AUTOMATION` edge — i.e. a todo-list read model feeding an automation, per `eventmodeling-identifying-outputs` Step 5b — may also be fed by a later-column event closing an item it opened earlier. That accumulator shape is what the todo-list pattern exists for, and it is confirmed against the platform API (`learn-eventmodelers-api` §3 — `POST .../connections`). **Outside that one case, the platform rejects the connection, for good reason:** without it, a read model would become a moving target for whatever screen or scenario later reaches back into it.
+**`EVENT → READMODEL` has exactly one exception, and it is narrow.** A read model that already carries a `READMODEL → AUTOMATION` edge — i.e. a todo-list read model feeding an automation, per `eventmodeling-designing-automation-chains` (Step 4b) — may also be fed by a later-column event closing an item it opened earlier. That accumulator shape is what the todo-list pattern exists for, and it is confirmed against the platform API (`learn-eventmodelers-api` §3 — `POST .../connections`). **Outside that one case, the platform rejects the connection, for good reason:** without it, a read model would become a moving target for whatever screen or scenario later reaches back into it.
 
 For every other read model — in particular one feeding a SCREEN rather than an AUTOMATION — never connect a later event back into it, no matter how convenient. If a later event needs to update what a screen already shows, resolve it the same way Step 5c resolves multi-component screens: place a **new copy of the read model** in (or immediately after) the later event's column, connect the later event forward into that copy, and place a matching copy of the same screen there (same title, updated data, optionally re-marked/highlighted per `html-screen`'s Marks feature). Never link the new copy back to the earlier instance.
 
@@ -145,7 +133,30 @@ Before wiring any of the five forward-only pairs, verify that `column(source)
 Screens placed during Step 3 (Storyboarding) are provisional positions. Steps 4 and 5 may need to move them to align with the commands or read models placed later.
 
 ### Column insertion
-Use `POST /timelines/:tl/columns` with `{"index": N}` to insert a column at a specific position (shifts existing columns right). Do not use `{}` (append) when placing read models or view screens — always target the correct position.
+Use `add_column` with `{"index": N}` to insert a column at a specific position (shifts existing columns right) — or, when the insertion point is "immediately before/after a node already on the board" rather than a numeric position you'd otherwise have to compute, pass `beforeNodeId`/`afterNodeId` instead and let the tool resolve the index itself. Do not use no position at all (append) when placing read models or view screens — always target the correct position.
+
+**Suppress auto-connect when inserting into an existing chain.** When you insert columns next to nodes that are *not* meant to connect to what you're about to place — e.g. slotting an output read model's column in beside an automation-chain column — the node placement's default auto-connect will wire the new node to whatever type-compatible node happens to sit in its own or the previous column (the "nearest event to the left"). That is the source of the recurring stray-edge cleanup. When the placement you're about to make should be wired only by your own explicit `set_connections` batch, pass `autoConnect: false` on the placing call (`submit_node_events`, `place_element`, `create_screen`/`create_screens`) and then wire every edge yourself. Keep the default (auto-connect on) for Steps 1/3/4 where same-column neighbors are exactly the intended wiring.
+
+### Prefer batch MCP tools over one-call-per-item loops
+
+Several MCP tools have a batch form that does the exact same thing as calling their singular form once per item, with the same validation rules and (where order matters, e.g. wiring a READMODEL→AUTOMATION edge before the backward EVENT→READMODEL edge that depends on it) the same in-order guarantee — just fewer round trips. Whenever a step's own instructions below show a single-item call and more than one item is being processed in the same pass, use the batch form instead:
+
+- `set_connections` (not `set_connection` repeated) — wiring multiple edges
+- `auto_connect_nodes` (not `auto_connect_node` repeated) — auto-connecting multiple freshly-placed nodes
+- `create_slice_definitions` (not `create_slice_definition` repeated) — defining multiple slices
+- `create_screens` (not `create_screen` repeated) — creating multiple HTML screens whose content is already authored
+- `move_nodes` (not `move_node_in_timeline` repeated) — moving multiple already-placed nodes within one timeline
+- `delete_nodes` / `delete_columns` (not `delete_node`/`delete_column` repeated) — removing multiple nodes or columns, e.g. a corrective cleanup after a modeling mistake
+- `add_column`'s `count` param (not `add_column` repeated) — appending or inserting several columns at once; `beforeNodeId`/`afterNodeId` resolve the insertion point from an already-placed node instead of a computed index
+- `create_chapter`'s `columns` param — when the chapter's initial column count is already known, instead of creating the default 3 and appending more after
+
+Also prefer `get_nodes`' `chapterId` param over an unscoped board-wide fetch whenever the step is working within one timeline (the common case), and `get_node`'s `projection: "cells"` over a full chapter fetch whenever only `{rows, columns, cells}` is needed (most cell/column bookkeeping lookups).
+
+For a "what is on the board and how is it wired right now" check between steps — the common orientation read, and the input to choosing an insertion anchor — use `get_board_outline` (`{boardId, chapterId}`). It returns one compact object: per-column node lists (`{id, type, title, lane}`) plus a flat edge list, with no rendered screen HTML or field bodies. Reserve full `get_nodes` (no projection) for when you actually need a node's `meta.fields` or page content.
+
+**Structural validation is one call, not a scan.** `validate_model` (`{boardId, chapterId}`) runs the whole structural checklist server-side — unplaced nodes, backward arrows (todo-list exception applied), zero/multi-issuer commands, sourceless read models, two-screens-in-a-column, missing scenarios — and returns only `findings`. Use it for the mandatory post-step unplaced check and as the first move in Step 9, instead of per-type `get_nodes` loops and `get_node` `projection: "edges"` spot-checks.
+
+**Ask echo-heavy write tools for less.** `add_scenario`, `add_storyline`, `set_connections` and `submit_node_events` each accept `compact: true`, which drops the full-object echo from the response (returning `{specNodeId, added, count, isNewNode}`, a `{connected, existed, removed, notFound, failed, errors}` tally, or `{persisted: <count>}` respectively). Pass it whenever you're not going to read individual fields back off the response — which is almost always for a large `set_connections` batch or a bulk scenario post.
 
 ### Documenting decisions inline, at any step
 
@@ -174,7 +185,7 @@ scope, and stated output goal (code, design, learning, docs).
 Confirm understanding before proceeding: "So we're modeling [domain], goal is
 [goal], constraints are [constraints]. Starting from [step]. Does that match?"
 
-**Capture findings** — write to `.trogonai/interviews/[project-name]/EVENTMODELING.md`:
+**Capture findings** — create `.trogonai/interviews/[project-name]/EVENTMODELING.md` with this header (this step is what creates the file; every later step appends to it per `eventmodeling-interview-protocol`):
 
 ```markdown
 # Event Modeling: [Project Name]
@@ -188,10 +199,9 @@ Confirm understanding before proceeding: "So we're modeling [domain], goal is
 
 | Step | Skill | Status | Key Output |
 |------|-------|--------|------------|
-| Orchestration | eventmodeling-orchestrating-event-modeling | Done | Domain scoped, starting point confirmed |
 ```
 
-Update this file as each step completes.
+Then follow **`eventmodeling-interview-protocol`** to record this step's own findings and add its Interview Trail row ("Orchestration" / `eventmodeling-orchestrating-event-modeling` / domain scoped, starting point confirmed). Every later step updates the same file as it completes.
 
 ---
 
@@ -279,15 +289,35 @@ role or system processor.
 
 ---
 
+### Step 4b: Design Automation Chains
+
+Invoke `eventmodeling-designing-automation-chains`.
+
+**Input**: Every AUTOMATION placed in Step 4, each already paired with its own
+COMMAND in one column.
+**Output to carry forward**: Every automation's todo-list READMODEL, placed
+and wired; every externally-triggered automation resolved into a two-stage
+translation chain (external EVENT → todo-list READMODEL → translation
+AUTOMATION+COMMAND+internal EVENT → worker automation's own todo list).
+**Gate**: No AUTOMATION on the board lacks an incoming `READMODEL →
+AUTOMATION` connection, and no automation's todo list is opened directly by
+another system's (second-swimlane) event. Skip this step only if Step 4
+placed zero automations.
+
+---
+
 ### Step 5: Identify Outputs
 
 Invoke `eventmodeling-identifying-outputs`.
 
-**Input**: Event list + Commands from Step 4 + the plain screens placed in Step 3.
+**Input**: Event list + Commands from Step 4 + automation chains already
+resolved in Step 4b + the plain screens placed in Step 3.
 **Output to carry forward**: Read model definitions — projections of events
-optimized for UI and processor queries — one per screen component, with any
+optimized for UI queries — one per screen component, with any
 multi-component screen already broken apart into same-named, highlighted
-screen copies (this step's Step 5a/5c, not Step 3's job).
+screen copies (this step's Step 5a/5c, not Step 3's job). Automation
+todo-list read models are already complete from Step 4b and are not
+re-derived here — this step only ever designs screen-facing read models.
 **Gate**: Every screen data need from the storyboards is satisfied by a read
 model, and no read model spans more than one component.
 
@@ -319,18 +349,7 @@ the elaborating-scenarios workflow — not just happy path + one error case —
 gate checklist below. A command-only pass is an incomplete Step 7, even if
 every command's coverage looks exhaustive.
 
-> **Do not reduce scenarios to a simple good-case / bad-case pair.** The `eventmodeling-elaborating-scenarios` skill defines a structured scenario workshop covering seven scenario types per command. All applicable types must be written before this step is complete.
-
-**Scenario types to work through for each command** — which apply is determined by the domain, not by a fixed rule:
-1. **Happy Path** — the normal success case
-2. **Validation Failure** — invalid or missing input
-3. **State Violation** — command issued when system is in an invalid state
-4. **Duplicate Action** — command issued again after it already succeeded
-5. **Alternative Path** — different valid outcomes depending on context
-6. **External Failure** — external system or scheduler fails
-7. **Compensation** — rollback or undo flow
-
-For each type, ask the relevant question against the business case and write a scenario if the situation can occur. Do not decide based on brevity — decide based on the domain.
+> **Do not reduce scenarios to a simple good-case / bad-case pair.** The `eventmodeling-elaborating-scenarios` skill defines a structured scenario workshop covering seven scenario types per command (Happy Path, Validation Failure, State Violation, Duplicate Action, Alternative Path, External Failure, Compensation — see that skill's own table for the question-form definition of each) — which apply is determined by the domain, not by a fixed rule. All applicable types must be written before this step is complete; do not decide based on brevity.
 
 > **Read models need scenarios too — easy to forget since the seven types above are command-shaped.** Every READMODEL needs at least one view scenario (GWT or storyline); a read model with zero scenarios is as incomplete as a command with zero. `eventmodeling-elaborating-scenarios`'s own checklist covers the details — connectivity rules, GWT-vs-storyline judgment per read model, and avoiding redundancy between a storyline and its GWTs — don't re-derive those here, just enforce the gate.
 
@@ -359,12 +378,11 @@ Invoke `eventmodeling-validating-event-models`.
 
 If FAIL: address findings and re-invoke `eventmodeling-validating-event-models`.
 
-**Optional — Production Readiness Checklist**: Invoke
-`eventmodeling-validating-event-models-checklist` when the model is destined
-for production. It runs 17 architectural checks across 7 phases and returns a
+**Optional — Structural Checklist**: Invoke
+`eventmodeling-validating-event-models-checklist` for a second, mechanical
+pass. It runs 12 structural checks across 6 phases and returns a
 PASS / PASS WITH WARNINGS / FAIL verdict independently of Step 9. A PASS on
-Step 9 does not substitute for this checklist when production readiness is
-required.
+Step 9 does not substitute for this checklist.
 
 ---
 
@@ -401,14 +419,7 @@ Not delegated to a separate skill — performed directly by this orchestrating s
    mcp__eventmodelers__add_lane { "boardId": "$BOARD_ID", "timelineId": "$CHAPTER_ID", "type": "feedback", "label": "Notes" }
    ```
 
-   **Fallback (no MCP):**
-   ```bash
-   curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/timelines/$CHAPTER_ID/lanes" \
-     -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" -H "x-user-id: orchestrator" \
-     -H "Content-Type: application/json" \
-     -d '{"type":"feedback","label":"Notes"}'
-   # → { laneId, type, label, index, totalLanes }
-   ```
+   **Fallback (no MCP):** see `references/api-fallback.md` — "Step 11 — Document Reasoning — Add a feedback lane".
 
 2. **Resolve the first column's ID** — the leftmost entry in `meta.timelineData.columns` (same chapter fetch used throughout this workflow for row/column lookups).
 
@@ -427,20 +438,12 @@ Not delegated to a separate skill — performed directly by this orchestrating s
    }
    ```
 
-   **Fallback (no MCP):**
-   ```bash
-   curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/events" \
-     -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" -H "x-user-id: orchestrator" \
-     -H "Content-Type: application/json" \
-     -d '[{"id":"<event-uuid>","eventType":"node:created","nodeId":"<node-uuid>","boardId":"<BOARD_ID>",
-           "timestamp":1234567890,"chapterId":"<CHAPTER_ID>","cellId":"<feedbackLaneId>-<firstColumnId>",
-           "meta":{"type":"MARKDOWN","title":"Modeling Reasoning — <Chapter Name>","description":"<full markdown body>"}}]'
-   ```
+   **Fallback (no MCP):** see `references/api-fallback.md` — "Step 11 — Document Reasoning — Create the MARKDOWN node".
 
    The note's body lives in **`meta.description`** as plain markdown source — headings, lists, bold, code fences, tables all render. **Not `meta.content`** — that field is accepted and stored without error but never rendered by the board UI, producing a visibly empty note; this was caught by comparing against a note authored directly in the UI, so treat it as confirmed, not a guess. There is no separate render/sketch call (unlike SCREEN/HTML_SCREEN) and no `fields[]` array on this element type.
 
 **What the note should actually contain** — write for the next person (or next session) who opens this board cold, not for whoever just built it:
-- **Scope**: what business process this chapter covers, and its stream roots (identity keys).
+- **Scope**: what business process this chapter covers, and its entities (identity keys).
 - **Assumptions added beyond the literal brief** — anything invented to fill a gap the requirements left open, and why (e.g. adding a resolution event so a state isn't a one-way trap door).
 - **Business rules deliberately encoded as scenarios, not new events** — so a reader doesn't mistake a missing event for an oversight.
 - **Sequencing or design corrections made mid-workflow** — e.g. a column reorder because an event's original placement implied the wrong causality.
@@ -472,22 +475,27 @@ A complete, sliced event model consisting of:
 These skills are not part of the 11-step main path but extend the model for
 specific needs:
 
-- **`eventmodeling-designing-event-models`** — Use when stream identity,
-  per-command state shapes, or event causality need detailed design work. Can
-  be applied at any step where those decisions arise, most commonly during or
-  after Step 1.
+- **`eventmodeling-designing-event-models`** — Use when the Command/Event/Read-Model
+  structure or event causality need detailed design work. Can be applied at
+  any step where those decisions arise, most commonly during or after Step 1.
 - **`eventmodeling-optimizing-stream-design`** — Use after the model is
-  complete to validate stream growth estimates and snapshotting decisions.
+  complete to validate that every entity's event timeline is anchored on a
+  single business identity, not a disguised collection or event log.
 - **`eventmodeling-translating-external-events`** — Use when external systems
   (webhooks, IoT, third-party APIs) need to feed into the domain model.
 
+### Further Reading
+
+- **[Project Planning with Event Modeling](references/project-planning-with-event-modeling.md)** — why explicit step contracts produce a flat cost curve and let teams build in parallel, plus velocity-based estimation and capacity planning built on workflow steps instead of story points.
+
 ---
 
 ## Quality Checklist
 
 - [ ] No elements stranded at 0,0 — every EVENT, COMMAND, READMODEL, SCREEN, and AUTOMATION has a valid `cellId` in its chapter
 - [ ] No `EVENT → READMODEL` connection points backward unless the read model already has a `READMODEL → AUTOMATION` edge (todo-list pattern) — every other later-event update uses a new read model + screen copy, never a link back to the earlier instance
-- [ ] All 11 modeling steps completed — no step skipped without explicit reason
+- [ ] All 11 modeling steps completed (plus Step 4b whenever Step 4 placed any automations) — no step skipped without explicit reason
+- [ ] Every AUTOMATION has a todo-list READMODEL, and no automation's todo list is opened directly by another system's event (Step 4b)
 - [ ] Every COMMAND, READMODEL, and AUTOMATION has a matching slice definition on the board
 - [ ] Every chapter has a Modeling Reasoning MARKDOWN node in its first column, written after that chapter's model was complete
 - [ ] Role Catalog exists with named human roles and system processors

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-orchestrating-event-modeling/references/api-fallback.md

@@ -0,0 +1,51 @@
+# Orchestrating Event Modeling — curl Fallback Calls
+
+Only needed when MCP is not connected. Every call below has an MCP equivalent in the main SKILL.md — always prefer that.
+
+## No unplaced elements (0,0 nodes) — Scan for unplaced nodes
+
+```bash
+for TYPE in EVENT COMMAND READMODEL SCREEN AUTOMATION; do
+  curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
+    "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=$TYPE"
+done
+```
+
+## No unplaced elements (0,0 nodes) — Place a found unplaced node
+
+```bash
+curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/events" \
+  -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" -H "x-user-id: orchestrator" \
+  -H "Content-Type: application/json" \
+  -d '[{"id":"<uuid>","eventType":"node:changed","nodeId":"<nodeId>","boardId":"<BOARD_ID>",
+        "timestamp":1234567890,"chapterId":"<chapterId>","cellId":"<rowId>-<colId>",
+        "meta":{"type":"<TYPE>","title":"<title>"}}]'
+```
+
+## No unplaced elements (0,0 nodes) — Delete an orphaned node
+
+```bash
+curl -s -X DELETE "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/<nodeId>" \
+  -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID"
+```
+
+## Step 11 — Document Reasoning — Add a feedback lane
+
+```bash
+curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/timelines/$CHAPTER_ID/lanes" \
+  -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" -H "x-user-id: orchestrator" \
+  -H "Content-Type: application/json" \
+  -d '{"type":"feedback","label":"Notes"}'
+# → { laneId, type, label, index, totalLanes }
+```
+
+## Step 11 — Document Reasoning — Create the MARKDOWN node
+
+```bash
+curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/events" \
+  -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" -H "x-user-id: orchestrator" \
+  -H "Content-Type: application/json" \
+  -d '[{"id":"<event-uuid>","eventType":"node:created","nodeId":"<node-uuid>","boardId":"<BOARD_ID>",
+        "timestamp":1234567890,"chapterId":"<CHAPTER_ID>","cellId":"<feedbackLaneId>-<firstColumnId>",
+        "meta":{"type":"MARKDOWN","title":"Modeling Reasoning — <Chapter Name>","description":"<full markdown body>"}}]'
+```

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-plotting-events/SKILL.md

@@ -10,6 +10,8 @@ allowed-tools:
 
 > **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 it has completed. Consult `learn-eventmodelers-api` only if you need to look up a specific endpoint or field this file doesn't cover — don't load it eagerly.
 
+This step applies the shared element rules in **`eventmodeling-core-rules`** — read it once per session if you haven't already; it defines what a COMMAND/EVENT/READMODEL/SCREEN/AUTOMATION is, how each is named, and the anti-patterns to reject, so this step doesn't restate them.
+
 Prefer `mcp__eventmodelers__*` tools when available (registered by the `connect` skill) — the curl blocks below are the fallback for sessions without MCP connected.
 
 Arrange all brainstormed events chronologically to create a logical sequence that makes sense as a narrative timeline. Show how events flow and depend on each other.
@@ -78,6 +80,8 @@ Path A: Payment succeeds → PaymentProcessed
 Path B: Payment fails → PaymentFailed → OrderCancelled
 ```
 
+**Every path here is a decision point, not a divergent journey** — by the time plotting runs, chapter structure is already fixed (Step 1), so a path in this step is always one trigger resolving to one of several outcomes within *this* timeline's story, shown as branching columns. If a "path" you're documenting actually starts a different story with its own screens/commands rather than just deciding how this one ends, it was mis-grouped in Step 1 — stop and send it back to `eventmodeling-brainstorming-events`'s chapter grouping (see its "Divergent journey vs. a decision point" note) rather than modeling it as a branch here.
+
 ### 4. Create Timeline Diagram
 Visual representation of event flow:
 
@@ -108,11 +112,7 @@ Prefer MCP:
 mcp__eventmodelers__get_nodes { "boardId": "$BOARD_ID", "type": "CHAPTER" }
 ```
 
-**Fallback (no MCP):**
-```bash
-curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
-  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=CHAPTER"
-```
+**Fallback (no MCP):** see `references/api-fallback.md` — "Chapters and Timelines — Resolve the Target Timeline".
 
 If multiple timelines exist, ask the user which one to work on now. Never reorder events across timelines in a single pass.
 

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-plotting-events/references/api-fallback.md

@@ -0,0 +1,10 @@
+# Plotting Events — curl Fallback Calls
+
+Only needed when MCP is not connected. Every call below has an MCP equivalent in the main SKILL.md — always prefer that.
+
+## Chapters and Timelines — Resolve the Target Timeline
+
+```bash
+curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
+  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=CHAPTER"
+```

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-slicing-event-models/SKILL.md

@@ -11,6 +11,8 @@ allowed-tools:
 
 > **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 it has completed. Consult `learn-eventmodelers-api` (in particular the **Slices** section) only if you need to look up a specific endpoint or field this file doesn't cover — don't load it eagerly.
 
+This step applies the shared element and slice rules in **`eventmodeling-core-rules`** — read it once per session if you haven't already; its "Slices" section defines the state-change/state-view/automation slice types this step derives, so this step doesn't restate them.
+
 > Prefer `mcp__eventmodelers__*` tools when available (registered by the `connect` skill) — the curl blocks below are the fallback for sessions without MCP connected.
 
 **Purpose**: Turn a completed event model's timeline into explicit slice definitions on the board, and note the event dependencies between them.
@@ -24,21 +26,7 @@ allowed-tools:
 
 ## Core Concept: A Slice Is One Command, One Read Model, or One Automation — Never Combined
 
-A **Feature Slice** is the thinnest possible vertical cut through the model — exactly one decision or one query:
-
-```
-state-change slice = SCREEN/Processor → COMMAND → EVENT(s)
-state-view slice   = EVENT(s) → READMODEL → SCREEN/Processor
-automation slice   = EVENT(s) → AUTOMATION → COMMAND → EVENT(s)
-```
-
-A slice never mixes a COMMAND and a READMODEL — the platform models these as two distinct slice types (`state-change` and `state-view`). If a "feature" needs both a command and a read model (e.g. "place an order" needs the `PlaceOrder` command *and* an `OrderDetailView` read model), that's **two slices**, not one.
-
-**Key characteristics**:
-- Exactly one COMMAND (state-change), exactly one READMODEL (state-view), or one AUTOMATION's command — never combined
-- Named after that command, read model, or automation
-- Independently deployable
-- Communicates with other slices via events only
+See `eventmodeling-core-rules`'s "Slices" section for the definition (state-change / state-view / automation, never combined) and why a feature needing both a command and a read model is two slices, not one.
 
 ---
 
@@ -62,10 +50,7 @@ Prefer MCP:
 mcp__eventmodelers__get_nodes { "boardId": "<BOARD_ID>", "type": "CHAPTER" }
 ```
 
-**Fallback (no MCP):**
-```bash
-curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=CHAPTER"
-```
+**Fallback (no MCP):** see `references/api-fallback.md` — "Step 1: Resolve the Timeline".
 
 - **Exactly one chapter** → use it automatically, tell the user which one was selected.
 - **Multiple chapters** → list them by name/ID and use `AskUserQuestion` to ask which one to slice.
@@ -73,34 +58,25 @@ curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=CHAPTER"
 
 ## Step 2: Enumerate Commands, Read Models, and Automations
 
-Use `spec-info` (or existing board knowledge) to list every COMMAND, READMODEL, and AUTOMATION node across the resolved timeline:
+Use `spec-info` (or existing board knowledge) to list every COMMAND and READMODEL node across the resolved timeline — `spec-info` only ever returns EVENT/COMMAND/READMODEL, never AUTOMATION, so pass `elementTypes` to skip the EVENT rows you don't need here:
 
 Prefer MCP:
 ```
-mcp__eventmodelers__get_spec_info { "boardId": "<BOARD_ID>", "timelineId": "<TL>" }
+mcp__eventmodelers__get_spec_info { "boardId": "<BOARD_ID>", "timelineId": "<TL>", "elementTypes": ["COMMAND", "READMODEL"] }
 ```
 
-**Fallback (no MCP):**
-```bash
-curl "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/timelines/$TL/spec-info" -H "x-token: $TOKEN"
-# → { timelineId, elements: [{ id, title, type }] }
-```
+**Fallback (no MCP):** see `references/api-fallback.md` — "Step 2: Enumerate Commands, Read Models, and Automations — spec-info".
 
-Filter to `type` in `COMMAND`, `READMODEL`, `AUTOMATION`.
+Separately, enumerate AUTOMATION nodes via `get_nodes { "boardId": "<BOARD_ID>", "type": "AUTOMATION", "chapterId": "<TL>" }` — `spec-info` cannot return them.
 
-`spec-info` doesn't include the column each element sits in, so fetch the chapter node to resolve it:
+`spec-info` doesn't include the column each element sits in, so fetch the chapter node to resolve it — `projection: "cells"` returns just `{rows, columns, cells}`, not the whole chapter node:
 
 Prefer MCP:
 ```
-mcp__eventmodelers__get_node { "boardId": "<BOARD_ID>", "nodeId": "<TL>" }
+mcp__eventmodelers__get_node { "boardId": "<BOARD_ID>", "nodeId": "<TL>", "projection": "cells" }
 ```
 
-**Fallback (no MCP):**
-```bash
-curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/$TL" -H "x-token: $TOKEN"
-# → meta.timelineData.columns: [{ id, index }]
-# → meta.timelineData.cells:   [{ id: "<rowId>-<columnId>", nodeId }]
-```
+**Fallback (no MCP):** see `references/api-fallback.md` — "Step 2: Enumerate Commands, Read Models, and Automations — Chapter Node".
 
 For each filtered element, find the cell whose `nodeId` matches the element's `id` — the `columnId` is the cell `id` with the leading `<rowId>-` (36 chars + hyphen) stripped off. Record `{ elementId, elementType, title, columnId }` for every COMMAND, READMODEL, and AUTOMATION.
 
@@ -111,36 +87,30 @@ Prefer MCP:
 mcp__eventmodelers__list_slices { "boardId": "<BOARD_ID>" }
 ```
 
-**Fallback (no MCP):**
-```bash
-curl $BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/slicedata/slices -H "x-token: $TOKEN"
-# → { slices: [{ id, title, status }] }
-```
+**Fallback (no MCP):** see `references/api-fallback.md` — "Step 2: Enumerate Commands, Read Models, and Automations — Check Existing Slices".
 
 A column already has a slice if its element's title matches an existing slice's title.
 
 ## Step 3: Define slices
 
-For each column from Step 2 that doesn't already have a matching slice, mark that **existing** column as a slice via the **slice-definitions** endpoint:
+For every column from Step 2 that doesn't already have a matching slice, mark each **existing** column as a slice via the **slice-definitions** endpoint — batch all of them into one call rather than one call per column:
 
 Prefer MCP:
 ```
-mcp__eventmodelers__create_slice_definition { "boardId": "<BOARD_ID>", "timelineId": "<TL>", "columnId": "<colId>", "title": "PlaceOrder" }
+mcp__eventmodelers__create_slice_definitions { "boardId": "<BOARD_ID>", "timelineId": "<TL>", "slices": [
+  { "columnId": "<colId1>", "title": "PlaceOrder" },
+  { "columnId": "<colId2>", "title": "OrderStatusView" }
+] }
 ```
+(`create_slice_definition`, singular, still exists for a one-off single-column case, but prefer the batch form here since Step 3 is defining every remaining column's slice in one pass.)
 
-**Fallback (no MCP):**
-```bash
-curl -X POST $BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/timelines/$TL/slice-definitions \
-  -H "x-token: $TOKEN" -H "Content-Type: application/json" \
-  -d '{"columnId":"<colId>","title":"PlaceOrder"}'
-# → 200 { nodeId, timelineId, columnId, title }
-```
+**Fallback (no MCP):** see `references/api-fallback.md` — "Step 3: Define Slices".
 
 - COMMAND column → title = command name (state-change slice)
 - READMODEL column → title = read model name (state-view slice)
 - AUTOMATION column → title = automation name, or the command it issues (automation slice)
 
-Use **`create_slice_definition`/`slice-definitions`**, never `create_slice`/the plain **`slices`** endpoint here — `create_slice`/`slices` creates a brand-new column with its own swimlane/content nodes, which would duplicate the element already placed on the timeline. `create_slice_definition`/`slice-definitions` only adds a `SLICE_BORDER` node to the column you already resolved in Step 2. `title` always comes from the request body — it is never derived automatically from the command/read model/automation node.
+Use **`create_slice_definitions`/`slice-definitions`**, never `create_slice`/the plain **`slices`** endpoint here — `create_slice`/`slices` creates a brand-new column with its own swimlane/content nodes, which would duplicate the element already placed on the timeline. `create_slice_definitions`/`slice-definitions` only adds a `SLICE_BORDER` node to each column you already resolved in Step 2. `title` always comes from the request body — it is never derived automatically from the command/read model/automation node.
 
 **If Step 2 finds nothing to slice** (every COMMAND/READMODEL/AUTOMATION on the timeline already has a matching `SLICE_BORDER`), this skill's job is done — there is no existing element left to make explicit. Do not invent new model content here; that is out of scope for a skill whose whole design assumes the model is already complete. Invoke the `add-next-slice` skill instead — it owns deciding on and creating a genuinely new slice from scratch.
 
@@ -167,4 +137,5 @@ This is useful to surface back to the user (e.g. "`OrderDetailView` depends on `
 ## Reference Documentation
 
 - **[patterns.md](references/patterns.md)** — naming, boundaries, cross-slice communication patterns
-- **[examples.md](references/examples.md)** — worked example of deriving slices from a timeline
+- **[examples.md](references/examples.md)** — worked example of deriving slices from a timeline
+- **[api-fallback.md](references/api-fallback.md)** — curl fallback calls for every MCP operation this skill uses.

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-slicing-event-models/references/api-fallback.md

@@ -0,0 +1,41 @@
+# Slicing Event Models — curl Fallback Calls
+
+Only needed when MCP is not connected. Every call below has an MCP equivalent in the main SKILL.md — always prefer that.
+
+## Step 1: Resolve the Timeline
+
+```bash
+curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=CHAPTER"
+```
+
+## Step 2: Enumerate Commands, Read Models, and Automations — spec-info
+
+```bash
+curl "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/timelines/$TL/spec-info" -H "x-token: $TOKEN"
+# → { timelineId, elements: [{ id, title, type }] } — filter client-side to type in COMMAND, READMODEL (no elementTypes param over REST)
+```
+
+## Step 2: Enumerate Commands, Read Models, and Automations — Chapter Node
+
+```bash
+curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/$TL" -H "x-token: $TOKEN"
+# → meta.timelineData.columns: [{ id, index }]
+# → meta.timelineData.cells:   [{ id: "<rowId>-<columnId>", nodeId }]
+```
+
+## Step 2: Enumerate Commands, Read Models, and Automations — Check Existing Slices
+
+```bash
+curl $BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/slicedata/slices -H "x-token: $TOKEN"
+# → { slices: [{ id, title, status }] }
+```
+
+## Step 3: Define Slices
+
+```bash
+curl -X POST $BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/timelines/$TL/slice-definitions \
+  -H "x-token: $TOKEN" -H "Content-Type: application/json" \
+  -d '{"columnId":"<colId>","title":"PlaceOrder"}'
+# → 200 { nodeId, timelineId, columnId, title }
+```
+(one call per column — the REST fallback has no batch form)