@eventmodelers/cli 1.0.36 → 1.0.38

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

@@ -11,18 +11,16 @@ 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.
 
 ## Interview Phase (Optional)
 
-**When to Interview**: Skip if the user has provided detailed, well-documented requirements (written user stories, feature specs, business rules). Interview when requirements are vague, incomplete, or when domain expertise is uncertain.
-
-**Interview Strategy**: Ensure requirements are complete and team understands domain well enough to brainstorm comprehensively. Identify hidden complexity areas upfront.
+**When to Interview**: Skip if the user has provided detailed, well-documented requirements (written user stories, feature specs, business rules) and named who understands the domain. Interview when requirements are vague, incomplete, or domain expertise is uncertain.
 
 ### Critical Questions
 
-When requirements need clarification:
-
 1. **Requirements Completeness** (Impact: Determines if brainstorm is likely to be exhaustive)
    - Question: "How complete are your requirements? Do you have: (A) Written user stories/specs, (B) Documented business rules, (C) Rough list, (D) Just verbal descriptions?"
    - Why it matters: Incomplete requirements cause missed events; complete requirements enable comprehensive brainstorm
@@ -43,76 +41,7 @@ When requirements need clarification:
    - Why it matters: Business rules often generate specific events; documenting them prevents overlooking state changes
    - Follow-up triggers: For each rule → ask "When this rule is violated, what event signals that?"
 
-### Interview Flow
-
-**Conditional Entry**:
-```text
-If user has provided:
-  - Written requirements or user stories (not just verbal)
-  - AND documented business rules or constraints
-  - AND named domain experts who will participate
-
-Then: Skip interview, proceed directly to brainstorming
-
-Else: Conduct interview
-```
-
-**Phase 1: Requirements Assessment** (Questions 1-2)
-- Gauge requirements completeness
-- Confirm domain expertise available
-- Adjust brainstorm scope accordingly
-
-**Phase 2: Complexity Mapping** (Questions 3-4)
-- Identify areas needing deep exploration
-- Document rules that may generate events
-- Plan brainstorm focus areas
-
-### Capturing Interview Findings
-
-Append findings to the project's event modeling file:
-
-**File**: `.trogonai/interviews/[project-name]/EVENTMODELING.md`
-
-Use Write tool to add/update this section:
-
-```markdown
-## 2. Brainstormed Events (eventmodeling-brainstorming-events)
-
-### Requirements Assessment
-[From Q1: Written requirements? Documented rules?]
-
-### Domain Expertise
-[From Q2: Who understands domain? Available for participation?]
-
-### Role Catalog
-#### Human Roles
-- [Role 1]: [Description] → Actions: [list]
-- [Role 2]: [Description] → Actions: [list]
-#### System Actors
-- [Actor 1]: [Description] → Triggers: [list]
-
-### Event Streams (Stream Roots)
-- Stream: [Name] (Identity: [id field])
-  - Events: [Event1, Event2, Event3]
-  - State changes: [State transitions]
-
-### Business Rules & Constraints
-[From Q3 & Q4]
-- Rule 1: [Statement] → [Events it generates]
-- Rule 2: [Statement] → [Events it generates]
-- Constraint 1: [Limitation]
-
-### Brainstorming Focus Areas
-- [Focus area 1]
-- [Focus area 2]
-```
-
-Update Interview Trail:
-```markdown
-| 2 | eventmodeling-brainstorming-events |  [today] | Event streams, business rules, constraints |
-```
-
-This section feeds into subsequent steps (plotting, storyboarding, etc.)
+Follow **`eventmodeling-interview-protocol`** to run this interview and record its findings — label this step "**2. Brainstormed Events** (`eventmodeling-brainstorming-events`)". Findings should cover: requirements completeness, domain expertise available, the Role Catalog, entities/event timelines identified, business rules & constraints, and brainstorming focus areas — this feeds directly into plotting and storyboarding.
 
 ---
 
@@ -125,11 +54,7 @@ Before brainstorming, check for EVENT nodes already on the board to avoid duplic
 mcp__eventmodelers__get_nodes { "boardId": "<BOARD_ID>", "type": "EVENT" }
 ```
 
-**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=EVENT"
-```
+**Fallback (no MCP):** see `references/api-fallback.md` — "Board Context — Check existing EVENT nodes".
 
 If events already exist, treat them as the starting list and focus on discovering what might be missing. Also check for existing chapters (timelines) so you can reuse them:
 
@@ -138,11 +63,7 @@ If events already exist, treat them as the starting list and focus on discoverin
 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` — "Board Context — Check existing CHAPTER nodes".
 
 ## Timeline Discovery (Mandatory Before Placing Any Event)
 
@@ -157,23 +78,24 @@ After completing the analysis, partition the full event list into groups where e
 
 If all events belong to a single flow, one timeline is correct — do not split artificially.
 
+**Divergent journey vs. a decision point — do not confuse the two.** A group of events sometimes contains a branch, and the branch's nature decides whether it gets its own chapter or stays inside this one:
+
+- **Divergent journey → its own chapter.** The actor makes a different choice *before* the process even starts, and everything downstream differs as a result (e.g. "Checkout with saved card" vs. "Checkout as guest" — different screens, different commands, arguably a different Role Catalog entry). Group these as separate workflows in Step 1, not as one group with a fork in it.
+- **Decision point → stays in this one chapter.** A single trigger — one command's outcome, or one automation's rule — resolves to one of several mutually exclusive results, and the rest of the process is otherwise the same story (e.g. `PaymentAuthorized` succeeds or fails, `OrderConfirmed` vs. `OrderCancelled` after the same confirm action). Keep this as one group; `eventmodeling-plotting-events`'s "Identify Alternative Paths" step is exactly where this branch gets shown, as sibling paths within the same timeline — it never means a second chapter.
+
+If unsure which one you're looking at, ask: "does this branch start a genuinely different story, or does it just decide how *this* story ends?" A different story is a new chapter; a different ending is a branch inside this one.
+
 ### 2. Create one chapter per group
 
 For each group, create a chapter on the board **before placing any events**. Reuse an existing chapter if one already matches the workflow name.
 
 **Prefer MCP — create a chapter:**
 ```
-mcp__eventmodelers__create_chapter { "boardId": "<BOARD_ID>", "x": 0, "y": 1200 }
-```
-(`x`/`y` are optional — see the vertical-stacking note below. Response includes the new `timelineId`.)
-
-**Fallback (no MCP) — create a chapter:**
-```bash
-curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/chapters" \
-  -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
-  -H "Content-Type: application/json" -d '{}'
-# → { timelineId: "<chapterId>", ... }
+mcp__eventmodelers__create_chapter { "boardId": "<BOARD_ID>", "x": 0, "y": 1200, "columns": <numberOfEventsInGroup> }
 ```
+(`x`/`y` are optional — see the vertical-stacking note below. `columns` is optional too — the group's event count is already known at this point, so pass it here to create the chapter with exactly the columns this group needs, instead of the default 3 plus a follow-up `add_column` batch. Response includes the new `timelineId` and `columnIds` — one id per column, left to right, ready to use directly in Step A below.)
+
+**Fallback (no MCP):** see `references/api-fallback.md` — "Timeline Discovery — Step 2: Create one chapter per group — create the chapter".
 
 **Immediately set its title** (use the workflow / bounded-context name):
 
@@ -192,20 +114,7 @@ mcp__eventmodelers__submit_node_events {
 }
 ```
 
-**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: brainstorming-events" -H "Content-Type: application/json" \
-  -d '[{
-    "id": "<uuid>",
-    "eventType": "node:changed",
-    "nodeId": "<chapterId>",
-    "boardId": "<boardId>",
-    "timestamp": 1234567890,
-    "meta": {"type": "CHAPTER", "title": "Reservation & Lending"}
-  }]'
-```
+**Fallback (no MCP):** see `references/api-fallback.md` — "Timeline Discovery — Step 2: Create one chapter per group — set its title".
 
 **Stack timelines vertically so they do not overlap, and in general place new chapters close to existing ones they relate to.**
 After creating each chapter, position it below the previous one. Use `y = index * 1200` (0-based creation order), `x = 0`. If existing chapters are already on the board, query their positions first. Prefer placing the new chapter directly below the existing chapter it is most closely related to (e.g. the same bounded context or an adjacent workflow), rather than mechanically appending below the lowest one — this keeps related chapters visually near each other on the canvas. Only fall back to `y = maxExistingY + 1200` when no related chapter exists yet. Pass this directly as `x`/`y` on `create_chapter` above, or reposition an existing chapter with:
@@ -215,13 +124,7 @@ After creating each chapter, position it below the previous one. Use `y = index
 mcp__eventmodelers__move_timeline_position { "boardId": "<BOARD_ID>", "timelineId": "<TL>", "x": 0, "y": 1200 }
 ```
 
-**Fallback (no MCP):**
-```bash
-curl -s -X PUT "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/timelines/$TL/position" \
-  -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
-  -H "Content-Type: application/json" \
-  -d '{"x": 0, "y": 1200}'   # first chapter: y=0, second: y=1200, third: y=2400, …
-```
+**Fallback (no MCP):** see `references/api-fallback.md` — "Timeline Discovery — Step 2: Reposition an existing chapter".
 
 Record the mapping: `workflow name → chapterId`. Every subsequent event placement will reference this ID.
 
@@ -265,38 +168,27 @@ Brainstorming events has two modes. Choose based on whether the chapter (timelin
 
 When a chapter is available, place each event directly into it. **Include `cellId` in `node:created`** — without it the node has no cell reference and will appear stranded at position 0,0 on the canvas.
 
-For each event:
-
-**Step A — Create a column** (append at end of the chapter):
+**Step A — Ensure enough columns exist, in a single call** (append at end of the chapter). Skip this step entirely if the chapter was just created above with `columns` already set to this group's event count. Otherwise (an existing/reused chapter, or one created without `columns`) — the number of events to place is already known from the brainstormed list, so pass it as `count` instead of calling `add_column` once per event:
 
 **Prefer MCP:**
 ```
-mcp__eventmodelers__add_column { "boardId": "<BOARD_ID>", "timelineId": "<CHAPTER_ID>" }
+mcp__eventmodelers__add_column { "boardId": "<BOARD_ID>", "timelineId": "<CHAPTER_ID>", "count": <numberOfEvents> }
+# → { "columnId": "<firstColUuid>", "index": <n>, "totalColumns": <n>, "columnIds": ["<col1>", "<col2>", ...] }
 ```
+Use `columnIds[i]` for the i-th event in Step C below. (Omit `count`, or pass `1`, for a single event — `columnIds` is only present when `count > 1`.)
 
-**Fallback (no MCP):**
-```bash
-curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/timelines/$CHAPTER_ID/columns" \
-  -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" -H "x-user-id: brainstorming-events" \
-  -H "Content-Type: application/json" -d '{}'
-# → { "columnId": "<colUuid>", "index": <n>, "totalColumns": <n> }
-```
+**Fallback (no MCP):** see `references/api-fallback.md` — "Mode A — Step A: Ensure enough columns exist".
 
 **Step B — Fetch the chapter to find the swimlane row ID** (only needed once per chapter):
 
-**Prefer MCP:**
+**Prefer MCP** — `projection: "cells"` returns just `{rows, columns, cells}`, not the whole chapter node:
 ```
-mcp__eventmodelers__get_node { "boardId": "<BOARD_ID>", "nodeId": "<CHAPTER_ID>" }
+mcp__eventmodelers__get_node { "boardId": "<BOARD_ID>", "nodeId": "<CHAPTER_ID>", "projection": "cells" }
 ```
 
-**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/$CHAPTER_ID"
-# → node.meta.timelineData.rows — find the row where type === "swimlane"
-```
+**Fallback (no MCP):** see `references/api-fallback.md` — "Mode A — Step B: Fetch the chapter to find the swimlane row ID".
 
-**Step C — Compute:** `cellId = swimlaneRow.id + "-" + columnId`
+**Step C — Compute, for the i-th event:** `cellId = swimlaneRow.id + "-" + columnIds[i]` (or the single `columnId` if only one column was created)
 
 **Step D — Create the event with `cellId`.**
 
@@ -327,29 +219,7 @@ mcp__eventmodelers__submit_node_events {
 }
 ```
 
-**Fallback (no MCP) — same body via `POST .../nodes/events`:**
-```json
-[{
-  "id": "<event-uuid>",
-  "eventType": "node:created",
-  "nodeId": "<node-uuid>",
-  "boardId": "<boardId>",
-  "timestamp": 1234567890,
-  "chapterId": "<chapterId>",
-  "cellId": "<swimlaneRowId>-<columnId>",
-  "meta": {
-    "type": "EVENT",
-    "title": "BookReserved",
-    "fields": [
-      {"name": "reservationId", "type": "String",   "example": "res-789"},
-      {"name": "copyId",        "type": "String",   "example": "copy-42"},
-      {"name": "memberId",      "type": "String",   "example": "mbr-101"},
-      {"name": "expiresAt",     "type": "DateTime", "example": "2026-06-01T00:00:00Z"},
-      {"name": "reservedAt",    "type": "DateTime", "example": "2026-05-29T10:00:00Z"}
-    ]
-  }
-}]
-```
+**Fallback (no MCP):** see `references/api-fallback.md` — "Mode A — Step D: Create the event with cellId".
 
 > **Never call `drop` after using `cellId` in `node:created`.** The drop endpoint adds a second cell reference without removing the first. `node:created + cellId` is the only placement step needed.
 
@@ -370,7 +240,7 @@ An event left without a chapter and cell reference will never appear in any time
 
 **Use swimlanes sparingly — a swimlane exists for exactly one purpose: marking where integration with another system happens. Nothing else justifies one.** Not a different actor, not a different role, not visual grouping, not "an explicit business rule" in the abstract. Every chapter starts with, and in the common case keeps, a single default swimlane holding all of this bounded context's own domain events. Before adding a lane, check whether an existing lane already covers the element's type. If yes, place the element in that lane.
 
-**The only valid reason to create a second `swimlane`-type lane: another system's own events cross into this chapter as integration triggers for a translation automation** (see `eventmodeling-identifying-outputs` Step 5b). Label it for that system and place its trigger events there — never fold them into this chapter's own event swimlane (they are not this bounded context's domain facts) and never treat them as an informal "signal" with no EVENT node at all. An external EVENT may only ever open the *translation* automation's todo list — never the todo list of the automation that does the actual domain work; that automation is triggered solely by the internal event the translation automation produces (Step 5b covers the full two-automation chain).
+**The only valid reason to create a second `swimlane`-type lane: another system's own events cross into this chapter as integration triggers for a translation automation** (see `eventmodeling-designing-automation-chains`, Step 4b). Label it for that system and place its trigger events there — never fold them into this chapter's own event swimlane (they are not this bounded context's domain facts) and never treat them as an informal "signal" with no EVENT node at all. An external EVENT may only ever open the *translation* automation's todo list — never the todo list of the automation that does the actual domain work; that automation is triggered solely by the internal event the translation automation produces, and only exists at all when reacting to that internal event genuinely requires a new decision (Step 4b covers the full translation chain, and when a worker automation belongs after it).
 
 **Never** add a swimlane for any other reason — not a new actor, not a new role, not visual grouping. Human roles get their own **actor** lane during Step 3 (Storyboarding) — a different row type entirely — never a new swimlane here.
 
@@ -382,78 +252,9 @@ An event left without a chapter and cell reference will never appear in any time
 
 ## Workshop Facilitation Guide
 
-**Setting**: This is a collaborative brainstorming workshop. The facilitator guides participants to envision the system and extract events rapidly.
-
-### The Brainstorming Flow
-
-**Phase 1: Understand Goals** (5-10 min)
-- Someone explains project goals
-- What problem are we solving?
-- Who are the users?
-- What are key outcomes?
-
-**Phase 2: Free Brainstorm** (15-20 min)
-Facilitator asks:
-> "What events could happen in this system? When something changes, what event occurs? Put down ANY event you think of."
-
-Participants call out events (sticky notes or digital cards):
-```text
-"Customer places order"
-"Order confirmed"
-"Payment received"
-"Inventory updated"
-"Order shipped"
-"Delivery confirmed"
-"Return requested"
-"Refund issued"
-```
-
-**Phase 3: Gentle Filtering** (10-15 min)
-Facilitator introduces state-changing concept gently:
-
-```text
-Facilitator: "Now let's think about these events. An event is something that
-CHANGED THE STATE of the system. It's something important that happened that
-others need to know about.
-
-Let me ask: Does 'Customer viewed the catalog' change anything?
-Participants: "Well... no, they just looked."
-Facilitator: "Right, so it's not an event. But if they SELECTED an item
-               from catalog, that changes what's in their cart, so that's
-               a state change. Call that 'ItemAddedToCart'."
-
-Does 'Payment received' change something?
-Participants: "Yes! Order goes from confirmed to paid."
-Facilitator: "Exactly! That's an event—state changed."
-```
-
-**Key points to clarify**:
-- "Customer logged in" → Maybe not state-changing (unless we track logins)
-- "Customer created account" → State-changing event
-- "System checked inventory" → Internal action, not state-changing
-- "Inventory reserved" → State-changing event
-- "Email sent" → Notification, not state-changing (unless we track email history)
-- "Notification requested" → Could be state-changing if we track preferences
-
-### Tips for Facilitators
-
-**Make it conversational**:
-- Don't say: "You identified a non-state-changing event"
-- Say: "Interesting! Does that actually change anything in the system?"
-
-**Use examples from their world**:
-- If e-commerce: "Like if someone just browsed but didn't buy?"
-- If banking: "Like if they just checked balance but didn't withdraw?"
-
-**Don't be rigid**:
-- If unsure whether something is state-changing, include it and refine later
-- Some events seem minor now but matter in implementation
-- Better to capture everything than miss important events
+**Setting**: This is a collaborative brainstorming workshop — the facilitator guides participants to envision the system and extract events rapidly. See `references/facilitating-event-modeling-workshops.md`'s "Step 1: Brainstorming Events" section for the full facilitation flow (goals framing, free brainstorm, gentle filtering, example dialogue) and general facilitation techniques (handling personalities, pacing, disagreement) that apply throughout.
 
-**Capture the "why"**:
-- Don't just list events, capture context
-- Why would this event matter?
-- Who cares about it? (Other systems, views, business rules)
+**The core move, in brief**: ask participants for any event they can think of, capture everything without filtering first, then gently introduce the state-changing test ("did this actually change something?") to separate real events from actions/notifications/internal checks — see the reference for the full example dialogue and phrasing tips.
 
 ## Workflow
 
@@ -473,35 +274,7 @@ For each role/actor, document:
 - **Key actions**: What state changes can this role initiate?
 - **Permissions boundary**: What can this role NOT do?
 
-Present as a Role Catalog:
-
-```text
-## Role Catalog
-
-### Human Roles
-
-1. **Customer** - Description: End user who browses, purchases, and tracks orders
-   - Key actions: Create order, confirm order, cancel order, submit review
-   - Cannot: Manage inventory, process refunds, respond to reviews as seller
-
-2. **Seller** - Description: Merchant who lists products and fulfills orders
-   - Key actions: List product, confirm stock, respond to reviews, update pricing
-   - Cannot: Place orders, approve own reviews, process payments
-
-3. **Support Agent** - Description: Internal staff handling escalations and manual overrides
-   - Key actions: Override order status, issue refunds, flag reviews
-   - Cannot: Place orders on behalf of customers (unless impersonating)
-
-### System Actors
-
-1. **Payment Gateway** (external)
-   - Triggers: Payment authorization, payment failure, refund confirmation
-   - Communication: Webhooks
-
-2. **Inventory System** (internal)
-   - Triggers: Reserve inventory, release reservation
-   - Communication: Event-driven
-```
+Present as a Role Catalog: for each human role, its name (in domain language), a one-line description, its key actions, and what it explicitly cannot do; for each system actor, its name, whether it's internal or external, what triggers it, and how it communicates (webhooks, event-driven, API). A full worked example (E-commerce domain) is in `references/examples.md`.
 
 This catalog feeds directly into:
 - **Step 3 (Storyboarding)**: One actor lane per human role (not a swimlane — see Swimlane Rules above)
@@ -509,18 +282,18 @@ This catalog feeds directly into:
 - **Step 7 (Scenarios)**: Scenarios reference roles by name
 - **Step 8 (Completeness)**: Verify every role has at least one command path
 
-### 2. Identify Event Streams (Stream Roots)
-Identify the main entities that will have event streams. These are NOT DDD aggregates—they're simply the logical roots of events:
+### 2. Identify Entities (Event Timelines)
+Identify the main entities whose story will be told as a timeline of events:
 - User/Account
 - Order
 - Payment
 - Shipment
 - etc.
 
-For each stream root, note:
+For each entity, note:
 - Name (use domain language, not technical terms)
 - Identity key (what uniquely identifies instances: orderId, paymentId, customerId, etc.)
-- What commands will affect it (we'll define state needs per command, not upfront)
+- What commands will affect it
 
 ### 3. Identify Business Processes
 Map out critical workflows:
@@ -573,13 +346,13 @@ Present findings in this structure (include facilitation notes for future worksh
    - Triggers: [What events/commands it initiates]
    - Communication: [Webhooks / Event-driven / API]
 
-## Event Streams (Stream Roots)
-List each stream root and its identity:
-- **Stream**: Review (Identity: reviewId)
-- **Stream**: SellerResponse (Identity: responseId)
-- **Stream**: Seller (Identity: sellerId)
+## Entities (Event Timelines)
+List each entity and its identity:
+- **Entity**: Review (Identity: reviewId)
+- **Entity**: SellerResponse (Identity: responseId)
+- **Entity**: Seller (Identity: sellerId)
 
-Note: These are just the logical groupings of events. The STATE needed for each command will be determined later—not all stream attributes are needed for all commands.
+Note: These are just the logical groupings of events — the story each entity's timeline tells.
 
 ## Business Processes
 1. **Process Name**: Description
@@ -602,23 +375,6 @@ Note: These are just the logical groupings of events. The STATE needed for each
 ## Output Format
 Present analysis in a clear markdown structure that can be directly used by the eventmodeling-designing-event-models skill.
 
-## Core Architectural Rule
-
- **NEVER use DDD Aggregate pattern for state design** Every command handler must have its own minimal state projection derived from events. This is non-negotiable.
-
-```text
- ANTI-PATTERN (Do NOT do this):
-OrderAggregate { orderId, customerId, items[], total, status, paymentId, address, shippedAt, cancelledAt, ... }
-Used by: ConfirmOrder, ShipOrder, CancelOrder, ApproveReturn
-Problem: Loads unused data, couples unrelated commands, violates minimal state principle
-
- CORRECT PATTERN:
-ConfirmOrderState { status, orderId }
-ShipOrderState { status, orderId, paymentId }
-CancelOrderState { status, orderId, createdAt }
-Each command loads ONLY what it needs.
-```
-
 ## Key Principles
 - Use **domain language**, not technical terms
 - Focus on **what** happens, not **how** it's implemented
@@ -628,9 +384,8 @@ Each command loads ONLY what it needs.
 - **Collaborative Process**: This is a group brainstorm, not a solo analysis
 - **Rapid Iteration**: Capture quickly, refine later
 - **Gentle Filtering**: Introduce "state-changing events" concept conversationally, not as rigid rule
-- **Event Sourcing Mindset**: Think in terms of immutable events and stream roots, NOT DDD aggregates. The stream root is just a logical grouping of events; state is minimal and command-specific.
-- **Defer State Design**: Don't list all entity attributes upfront. In the model designer step, we'll define minimal state projections needed for each specific command.
-- **Command State Isolation**: Each command handler has its own state shape. Different commands = different state interfaces.
+- **Event Sourcing Mindset**: Think in terms of immutable events grouped by entity, not upfront attribute lists
+- **Defer Detail**: Don't list all entity attributes upfront — commands, preconditions, and read models get worked out in the design step
 
 ## Best Practices for Requirements Analysis
 

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

@@ -0,0 +1,97 @@
+# Brainstorming 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.
+
+## Board Context — Check existing EVENT nodes
+
+```bash
+curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
+  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=EVENT"
+```
+
+## Board Context — Check existing CHAPTER nodes
+
+```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"
+```
+
+## Timeline Discovery — Step 2: Create one chapter per group — create the chapter
+
+```bash
+curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/chapters" \
+  -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
+  -H "Content-Type: application/json" -d '{}'
+# → { timelineId: "<chapterId>", ... }
+```
+
+## Timeline Discovery — Step 2: Create one chapter per group — set its title
+
+```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: brainstorming-events" -H "Content-Type: application/json" \
+  -d '[{
+    "id": "<uuid>",
+    "eventType": "node:changed",
+    "nodeId": "<chapterId>",
+    "boardId": "<boardId>",
+    "timestamp": 1234567890,
+    "meta": {"type": "CHAPTER", "title": "Reservation & Lending"}
+  }]'
+```
+
+## Timeline Discovery — Step 2: Reposition an existing chapter
+
+```bash
+curl -s -X PUT "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/timelines/$TL/position" \
+  -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
+  -H "Content-Type: application/json" \
+  -d '{"x": 0, "y": 1200}'   # first chapter: y=0, second: y=1200, third: y=2400, …
+```
+
+## Mode A — Step A: Ensure enough columns exist
+
+No batch form exists over REST; one call per event:
+
+```bash
+curl -s -X POST "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/timelines/$CHAPTER_ID/columns" \
+  -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" -H "x-user-id: brainstorming-events" \
+  -H "Content-Type: application/json" -d '{}'
+# → { "columnId": "<colUuid>", "index": <n>, "totalColumns": <n> }
+```
+
+## Mode A — Step B: Fetch the chapter to find the swimlane row ID
+
+```bash
+curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
+  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/$CHAPTER_ID"
+# → node.meta.timelineData.rows — find the row where type === "swimlane"
+```
+
+## Mode A — Step D: Create the event with cellId
+
+Same body via `POST .../nodes/events`:
+
+```json
+[{
+  "id": "<event-uuid>",
+  "eventType": "node:created",
+  "nodeId": "<node-uuid>",
+  "boardId": "<boardId>",
+  "timestamp": 1234567890,
+  "chapterId": "<chapterId>",
+  "cellId": "<swimlaneRowId>-<columnId>",
+  "meta": {
+    "type": "EVENT",
+    "title": "BookReserved",
+    "fields": [
+      {"name": "reservationId", "type": "String",   "example": "res-789"},
+      {"name": "copyId",        "type": "String",   "example": "copy-42"},
+      {"name": "memberId",      "type": "String",   "example": "mbr-101"},
+      {"name": "expiresAt",     "type": "DateTime", "example": "2026-06-01T00:00:00Z"},
+      {"name": "reservedAt",    "type": "DateTime", "example": "2026-05-29T10:00:00Z"}
+    ]
+  }
+}]
+```

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-brainstorming-events/references/examples.md

@@ -0,0 +1,35 @@
+# Brainstorming Events — Worked Examples
+
+These are conceptual worked examples of the reasoning this skill applies — useful for understanding the shape of a complete answer, but the actual mechanics are the numbered Workflow steps and board-placement rules in the main SKILL.md.
+
+## Role Catalog (E-commerce domain)
+
+A full worked Role Catalog, illustrating the level of detail expected for each human role and system actor (name, description, key actions, permission boundary; triggers and communication mechanism for system actors):
+
+```text
+## Role Catalog
+
+### Human Roles
+
+1. **Customer** - Description: End user who browses, purchases, and tracks orders
+   - Key actions: Create order, confirm order, cancel order, submit review
+   - Cannot: Manage inventory, process refunds, respond to reviews as seller
+
+2. **Seller** - Description: Merchant who lists products and fulfills orders
+   - Key actions: List product, confirm stock, respond to reviews, update pricing
+   - Cannot: Place orders, approve own reviews, process payments
+
+3. **Support Agent** - Description: Internal staff handling escalations and manual overrides
+   - Key actions: Override order status, issue refunds, flag reviews
+   - Cannot: Place orders on behalf of customers (unless impersonating)
+
+### System Actors
+
+1. **Payment Gateway** (external)
+   - Triggers: Payment authorization, payment failure, refund confirmation
+   - Communication: Webhooks
+
+2. **Inventory System** (internal)
+   - Triggers: Reserve inventory, release reservation
+   - Communication: Event-driven
+```