@eventmodelers/cli 1.0.37 → 1.0.38

package/package.json

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

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

@@ -68,7 +68,7 @@ Server name: `eventmodelers`. Every tool takes `boardId` explicitly; none need `
 
 **Not exposed via MCP at all** — always use REST/curl for these: §7 Config Import, §10 Snapshots, §11–12 User Management, §13 Utility (`/api/user`, swagger), and the rest of §14 Prompts (submission, claiming, deletion, realtime-token) — only the status-update endpoint has an MCP tool (`update_prompt_status`, used by the `update-prompt-status` skill); everything else in Prompts is an intentionally separate lifecycle the board-content MCP server doesn't otherwise own.
 
-**Capabilities with no direct MCP filter** — e.g. REST's `GET .../nodes?cellId=<id>` (§3) has no `cellId` param on `get_nodes`. Get the same answer by calling `get_node` on the CHAPTER and reading `meta.timelineData.cells` (sparse array; a cell absent from it is empty) instead of asking the server to filter by cell.
+**Capabilities with no direct MCP filter** — e.g. REST's `GET .../nodes?cellId=<id>&timelineId=<id>` and `?colId=<id>&timelineId=<id>` (§3) have no equivalent params on `get_nodes`. Either call the REST endpoint directly, or get the same answer by calling `get_node` on the CHAPTER and reading `meta.timelineData.cells` (sparse array; a cell absent from it is empty) instead of asking the server to filter by cell/column.
 
 ---
 
@@ -379,8 +379,15 @@ interface NodeChangeEvent {
 ### GET `/api/org/:orgId/boards/:boardId/nodes`
 List all nodes on a board.
 
-**Query params**: `type?: ElementType`  
-**Response**: `200` — node record array
+**Query params**:
+- `type?: ElementType` — exact match.
+- `cellId?: string` — return only the node occupying this timeline cell (format `<rowId>-<colId>`). Requires `timelineId`. Empty array if the cell is unoccupied.
+- `colId?: string` — return every node occupying this column, across *all* rows of the timeline (e.g. to check for an existing COMMAND/READMODEL/SCREEN/AUTOMATION before placing one, since the server caps those at one per column even across separate lane rows). Requires `timelineId`. Combine with `type` to narrow to one element type.
+- `timelineId?: string` — the CHAPTER node `cellId`/`colId` are resolved against. Required together with either of those two; `400` if omitted.
+
+Cell/column occupancy lives only in the CHAPTER node's `meta.timelineData.cells`, never on the node rows themselves — this endpoint resolves `cellId`/`colId` against that timeline internally so callers don't have to fetch and parse the whole chapter node just to check occupancy.
+
+**Response**: `200` — node record array. `400` — `cellId`/`colId` given without `timelineId`. `404` — `timelineId` doesn't reference an existing CHAPTER node with grid data.
 
 ---
 

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-applying-conways-law/SKILL.md

@@ -11,16 +11,14 @@ 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.
+
 ## Interview Phase (Optional)
 
 **When to Interview**: Skip if the user has already specified: existing team structure, team responsibilities, and autonomous boundary preferences. Interview when team structure is unclear or organizational alignment hasn't been discussed.
 
-**Interview Strategy**: Understand team organization and decision-making to design system boundaries that teams can own independently. Misalignment here creates bottlenecks and tight coupling later.
-
 ### Critical Questions
 
-When team structure or boundaries are unclear:
-
 1. **Team Structure & Ownership** (Impact: Determines how many swimlanes/systems to create)
    - Question: "How is your organization structured? (A) Single team owns everything, (B) Separate teams by domain (payments, inventory, etc.), (C) Separate teams by function (backend, frontend, etc.)"
    - Why it matters: Team structure directly shapes system boundaries; aligning them reduces coordination overhead
@@ -36,63 +34,7 @@ When team structure or boundaries are unclear:
    - Why it matters: External systems often become separate swimlanes; knowing which ones matters for boundary design
    - Follow-up triggers: For each integration → ask "Who owns the integration—existing team or new team?"
 
-### Interview Flow
-
-**Conditional Entry**:
-```
-If user has provided:
-  - Clear team structure (who owns what)
-  - AND specified desired level of autonomy
-  - AND identified external integrations
-
-Then: Skip interview, proceed directly to swimlanes
-
-Else: Conduct interview
-```
-
-**Phase 1: Organization Assessment** (Questions 1-2)
-- Understand team structure
-- Determine autonomy expectations
-- Establish boundary philosophy
-
-**Phase 2: Integration Mapping** (Question 3)
-- Identify external systems
-- Plan integration boundaries
-- Finalize swimlane count
-
-### 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
-## 6. Conway's Law (eventmodeling-applying-conways-law)
-
-### Team Structure
-- Team 1: [Name] - Owns [domain]
-- Team 2: [Name] - Owns [domain]
-- Team 3: [Name] - Owns [domain]
-
-### Autonomy Goals
-[High / Moderate / Low]
-
-### Swimlanes
-- [Swimlane 1]: [Team] owns [events]
-- [Swimlane 2]: [Team] owns [events]
-- [Swimlane 3]: [Team] owns [events]
-
-### Cross-Team Communication
-- [Team A] → [Team B] via [event]
-- [Team B] → [Team C] via [event]
-```
-
-Update Interview Trail:
-```markdown
-| 6 | eventmodeling-applying-conways-law | [today] | Swimlanes defined, team boundaries confirmed |
-```
+Follow **`eventmodeling-interview-protocol`** to run this interview and record its findings — label this step "**6. Conway's Law** (`eventmodeling-applying-conways-law`)". Findings should cover: team structure and ownership, autonomy goals, the resulting swimlanes (which team owns which events), and cross-team communication paths.
 
 ---
 

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.
 
 ---
 
@@ -149,6 +78,13 @@ 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.
@@ -304,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-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 (Step 4b 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.
 
@@ -346,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:
@@ -410,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
@@ -439,10 +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 a DDD Aggregate pattern for state design** — every command handler must have its own minimal state projection derived from events. This is non-negotiable. See `eventmodeling-designing-event-models`'s "Core Architectural Rule" for the full anti-pattern/correct-pattern worked example (`OrderAggregate` vs. per-command state) — the rule applies from this very first step, not just once design begins.
-
 ## Key Principles
 - Use **domain language**, not technical terms
 - Focus on **what** happens, not **how** it's implemented
@@ -452,9 +384,8 @@ Present analysis in a clear markdown structure that can be directly used by the
 - **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-checking-completeness/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.
 
 ## Board Context

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-core-rules/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: eventmodeling-core-rules
+description: Shared, foundational rules for every event-modeling step — what a COMMAND/EVENT/READMODEL/SCREEN/AUTOMATION is, how each is named, and the anti-patterns to reject. Not a step of its own — referenced upfront by every other eventmodeling-* skill instead of each restating its own copy. Do not use standalone.
+---
+
+# Event Modeling — Core Rules
+
+These rules apply to every step of event modeling, regardless of which step's SKILL.md you're currently following. Read this once per session — a step's own file only states what's specific to that step, not these fundamentals.
+
+## Modes
+
+Which step you're in sets the posture — don't mix them.
+
+- **Modeling Mode** — `brainstorming-events`, `plotting-events`, `storyboarding-events`, `identifying-inputs`, `identifying-outputs`, `designing-automation-chains`, `elaborating-scenarios`, `translating-external-events`: explore and build. Capture the process as completely as you can. A naming slip or an incomplete precondition is something to flag and move past, not a reason to stall the whole step — don't over-correct early.
+- **Critic Mode** — `validating-event-models`, `validating-event-models-checklist`, `checking-completeness`, `wdyt`, `optimizing-stream-design`: review what's already there. Apply every rule in this file strictly. Surface every violation, gap, and inconsistency — don't soften a finding because the model "mostly works." Post findings as comments (`handle-comment`) rather than silently fixing them, unless the step explicitly says to fix.
+
+Don't mix them in one pass: a modeling step is not the place to run a full rules audit, and a critic step is not the place to quietly add missing structure on the model's behalf instead of flagging it.
+
+## Lanes — What Lives Where
+
+Every column on a timeline has (at most) four rows, and each element type belongs in exactly one:
+
+| Lane type | Elements allowed | What it represents |
+|---|---|---|
+| `actor` | SCREEN, AUTOMATION | Who or what initiates — a human via a screen, or a system via an automation |
+| `interaction` | COMMAND, READMODEL | The business intent going in (COMMAND), or the query result coming out (READMODEL) |
+| `swimlane` | EVENT | The business fact recorded — which system/entity's own story this event belongs to |
+| `spec` | SCENARIO | The Given/When/Then behavior spec for this column's COMMAND or READMODEL |
+
+An EVENT never shares a column with another EVENT even across different swimlane rows — one column is one moment in time. See `place-element` for the full placement mechanics; this table is only "what belongs where," not "how to place it."
+
+## Slices
+
+A **slice** is the thinnest possible vertical cut through the model — exactly one COMMAND, one READMODEL, or one AUTOMATION's command, never combined:
+
+```
+state-change slice = SCREEN/AUTOMATION → COMMAND → EVENT(s)
+state-view slice   = EVENT(s) → READMODEL → SCREEN/AUTOMATION
+automation slice   = EVENT(s) → AUTOMATION → COMMAND → EVENT(s)
+```
+
+A slice never mixes a COMMAND and a READMODEL — those are two different slice types (`state-change` and `state-view`), even when they belong to the same feature. Slices are independently deployable and only communicate with each other via events.
+
+Slices are not placed directly — they're **derived** from a completed model. Every COMMAND on the board implies a `state-change` slice, every READMODEL implies a `state-view` slice, every AUTOMATION implies an `automation` slice. `eventmodeling-slicing-event-models` makes that implicit structure explicit on the board once modeling is done; it never invents a slice that isn't already implied by an element that's there.
+
+## Elements
+
+### EVENT
+- Represents a business fact that already happened.
+- Naming: past tense, business language.
+  - Valid: `OrderPlaced`, `PaymentAuthorized`, `UserRegistered`
+  - Invalid: `SidebarOpened`, `RequestCompleted`, `ApiCalled` — these describe machinery or UI state, not business facts
+- Immutable — never modify or delete an event once created; a correction is a new event, not an edit.
+- Contains only captured facts. No computed or derived values — those belong in a READMODEL.
+
+### COMMAND
+- Represents business intent — what an actor wants to do.
+- Can be rejected; only succeeds if its documented preconditions hold.
+- Naming: imperative, business language.
+  - Valid: `PlaceOrder`, `ConfirmPayment`, `CancelSubscription`
+  - Invalid: `LoadOrders`, `FetchData`, `OpenDialog` — these are queries or UI-only actions, not business intent
+- Issued by exactly one SCREEN or AUTOMATION — never two. See `place-element`'s Step 7c for the mechanical check/fix; this rule is stated here, the fix lives there.
+- Produces one or more EVENTs on success, or is rejected with no event.
+
+### READMODEL
+- A projection built from events, shaped for a specific query.
+- Naming: noun phrase, business language, named for the data — not the machinery that produces it.
+  - Valid: `OrderSummary`, `InvoiceList`
+  - Invalid: `OrderSummaryProjector`, `InvoiceListRepository` — implementation detail leaking into the model
+- Optional — nothing requires a READMODEL to exist for a COMMAND or a downstream consumer.
+- Never drives COMMAND validation directly — a COMMAND is checked against its own documented preconditions, not a read model.
+
+### SCREEN
+- Represents what a user sees and can act on.
+- Naming: what a user would call it, not its internals.
+  - Valid: `Dashboard`, `OrderOverviewPage`
+  - Invalid: `OrderOverviewComponent`, `ProjectorView`
+
+### AUTOMATION
+- Represents an automated actor — a processor, scheduler, or system reacting to events.
+- Naming: what it does, in business language.
+  - Valid: `BillingScheduler`, `InventoryReserver`
+  - Invalid: `OrderServiceHandler` — implementation-flavored, not a business actor's name
+
+## Causality
+
+- Every EVENT traces to the COMMAND that produced it.
+- Every COMMAND traces to the SCREEN or AUTOMATION that issued it — exactly one.
+- A process starts with a read (SCREEN + READMODEL) or an AUTOMATION reacting to an existing EVENT — never with an unmotivated COMMAND.
+
+## Role Catalog
+
+Every event model needs one, established before brainstorming events (it's the first mandatory step) — without it, downstream steps have no way to say *who* does what:
+
+- **Human roles** (Customer, Seller, Admin...) and **system actors** (Payment Gateway, Scheduler...), each with: a name in domain language, a one-line description, its key actions, and what it explicitly cannot do.
+- No COMMAND may be attributed to a generic "User" — it must name a specific role or actor from the catalog.
+- Every COMMAND is issued by exactly one role/actor (this is the same rule as the COMMAND single-issuer rule above, stated from the Role Catalog's side).
+- Every human role needs at least one COMMAND and one READMODEL — a role in the catalog that never acts and never sees anything is decorative, not modeled.
+
+See `eventmodeling-brainstorming-events` for how the catalog is built, `eventmodeling-identifying-inputs` for attributing commands to it, and `eventmodeling-validating-event-models` for re-checking it holds once the model is complete.
+
+## Field Lineage
+
+Every field on a COMMAND or READMODEL must carry a `mapping` that traces it back to where its value actually comes from — user input, the session, a prior event's field, a derived/computed value, or an external webhook payload. **A field with no mapping is a gap, not a detail to fill in later.**
+
+See `eventmodeling-identifying-inputs` for the full COMMAND mapping vocabulary and `eventmodeling-identifying-outputs` for the READMODEL equivalent — this rule only states that every field must have one, not the mapping syntax itself.
+
+## Connections Read Forward
+
+A connection either goes **downward within the same column** (actor → interaction → swimlane → spec) or **forward to a later column** — never backward (right-to-left). This is why elements that belong together — a SCREEN and the READMODEL it queries, a SCREEN/AUTOMATION and the COMMAND it issues, a COMMAND and the EVENT it produces — should share a column whenever possible: the moment they don't, a backward arrow becomes a real risk.
+
+When an element's natural column is already occupied by something else, insert a new column immediately before or after (whichever keeps every connection forward) rather than wiring across the gap. See `place-element` for the mechanical insertion rules and each step's own placement section for where "before" vs. "after" applies.
+
+## Translation Chain
+
+An AUTOMATION reacting to an event from another system — external (a webhook/API) or second-swimlane (another team's own timeline) — needs a two-stage shape, never a direct reaction:
+
+```
+external EVENT → todo-list READMODEL → translation AUTOMATION + COMMAND → internal EVENT → worker automation's own todo list
+```
+
+- The external/second-swimlane EVENT opens only a *translation* automation's todo list — never a *worker* automation's todo list directly.
+- A translation automation's own todo list is opened by that external event and is never closed — it doesn't track "done," it only relays.
+- Its resulting COMMAND produces the internal EVENT the domain actually works with — that's the moment external data becomes a business fact in this domain's own language, ready for a worker automation (or anything else) to react to.
+
+Every AUTOMATION, translation or worker, needs its own todo-list READMODEL (opened by triggering events, closed by completion events) — no "pure relay" exemption. See `eventmodeling-designing-automation-chains` for the todo-list pattern and board placement mechanics, and `eventmodeling-translating-external-events` for mapping the external payload's raw fields to the internal EVENT's domain fields (correlation, idempotency, duplicate handling).
+
+## Open Questions vs. Decided Failures
+
+Two different things are easy to conflate, and conflating them corrupts completeness checking:
+
+- **Open question** — something genuinely undecided. Post it as a `QUESTION`-type comment (`handle-comment`) on the relevant node. It stays open until someone actually answers it — resolving means answering, not deleting the comment.
+- **Decided failure** — a rejection or error case whose behavior is already decided (e.g. "payment fails → reject, no event"). Model it as a SCENARIO with `expectError: true` and an `errorDescription` (see `eventmodeling-elaborating-scenarios`), never as a comment. It's permanent, specified behavior, not something waiting on an answer.
+
+A decided failure left as a lingering `QUESTION` comment looks unresolved when it isn't. When counting completeness (`eventmodeling-checking-completeness`), only a genuinely unanswered `QUESTION` counts as a gap — a decided failure path needs its `expectError` scenario, not a comment standing in for one.
+
+## Offline-First Thinking
+
+Model the business process as it would work without any software first, then translate to elements:
+
+- How would this work manually, with people, on paper?
+- Who acts, and what triggers each action?
+- What information do they need before they can act?
+
+Question any step that exists only because of the system — a loading spinner, a cache refresh, a session check is not a business step and does not belong on the timeline. This is the discipline behind the Anti-Patterns below; the anti-patterns are what it looks like when this principle is skipped.
+
+## Anti-Patterns
+
+- **Data-loading commands**: `LoadOrders`/`FetchData` are queries, not business intent — model as a READMODEL, not a COMMAND.
+- **UI-interaction events**: `SidebarOpened`/`ButtonClicked` are UI state, not business facts — don't model them unless the business genuinely cares.
+- **Technical events**: `ApiCalled`/`ResponseReceived` describe machinery, not an outcome — find the business fact underneath.
+- **Calculated events**: an event whose value is recomputed as source data changes (a running total, an average) is a READMODEL, not an EVENT.
+
+## Flow & Causality
+
+Model causality, not strict sequence:
+
+- A timeline starts with a **state-view** (READMODEL feeding a SCREEN) or an **automation** reacting to an EVENT already on the board — never with an unmotivated COMMAND.
+- Every COMMAND must be traceable to a trigger: a SCREEN (a user decision) or an AUTOMATION (a system reaction).
+- A `state-change` slice must not follow another `state-change` slice without a trigger in between (a new SCREEN or AUTOMATION) — two COMMANDs in a row with nothing issuing the second one is a gap, not a shortcut.
+
+Valid transitions between slices:
+- state-view → state-change
+- state-change → state-view
+- state-change → automation
+- automation → state-change
+- automation → state-view
+
+## Quick Self-Check
+
+Before treating a model as done, verify:
+
+- [ ] Every EVENT is past tense and describes a business fact, not machinery or UI state
+- [ ] Every COMMAND is imperative business intent, not a data-loading query
+- [ ] Every READMODEL is named for its data, not its implementation
+- [ ] No EVENT holds a computed/aggregated value — that belongs in a READMODEL
+- [ ] Every COMMAND has exactly one issuer (one inbound SCREEN or AUTOMATION edge)
+- [ ] Every COMMAND traces back to a SCREEN (user decision) or AUTOMATION (system reaction)
+- [ ] The timeline starts with a state-view or an automation reacting to an event — not a bare COMMAND
+- [ ] No two `state-change`/`state-change` slices are chained without a new trigger between them
+
+This is the fast pass — the full, deeper check is `eventmodeling-validating-event-models-checklist`.

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-designing-automation-chains/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` 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.
 
 This is **Step 4b**. It runs immediately after `eventmodeling-identifying-inputs` (Step 4) places an AUTOMATION and its COMMAND, and before `eventmodeling-identifying-outputs` (Step 5) designs any screen-facing read model. Designing an automation's todo list — and, when it applies, its translation chain — while the automation is still fresh from Step 4 is what prevents the alternative: discovering the gap only once Step 5's own verification pass runs, after commands and connections already built on top of the incomplete shape.
@@ -39,15 +41,27 @@ Even an automation that looks like a "pure signal relay" still has a todo list
 
 **There is no such thing as an invisible or informal "signal" — a trigger is always a real EVENT node**, placed in a second swimlane when it belongs to another system (see `eventmodeling-brainstorming-events`'s swimlane rule).
 
-**An automation can only ever be directly triggered by an internal event — never by another system's event.** A "trigger" arriving from a second swimlane is not itself the thing that drives your domain's work; it first has to be *translated* into an internal event. Do not model this as one automation whose todo list is opened by the external EVENT and that also does the real work (e.g. an automation reading a todo list opened by `ReservationRequested` from another system's swimlane and directly issuing `ReserveCopy`) — that lets an external system trigger domain work with no translation step, which this model doesn't allow. **Apply this now, in Step 4b** — Conway's Law (Step 6) only confirms the boundary, it doesn't introduce the chain. When an integration trigger comes from another team's system, model it as **two chained automations**, never one:
+**An automation can only ever be directly triggered by an internal event — never by another system's event.** A "trigger" arriving from a second swimlane is not itself the thing that drives your domain's work; it first has to be *translated* into an internal event. Do not model this as one automation whose todo list is opened by the external EVENT and that also does the real work (e.g. an automation reading a todo list opened by `ReservationRequested` from another system's swimlane and directly issuing `ReserveCopy`) — that lets an external system trigger domain work with no translation step, which this model doesn't allow. **Apply this now, in Step 4b** — Conway's Law (Step 6) only confirms the boundary, it doesn't introduce the chain. Every integration trigger from another team's system needs a **translation automation** — that part is never optional:
 
 1. **Translation automation** — converts the external fact into an internal one; the other system's own decision logic is out of scope. Its todo list is opened by the external EVENT — the one and only place an external EVENT may open a todo list. **It is not closed by the internal EVENT its own command produces, and gets no backward arrow.** A translation automation's job is an instantaneous, always-succeeding relay: there is no real work-in-progress window between "signal arrived" and "internal fact recorded" worth modeling as an open/close lifecycle, unlike a worker automation that can genuinely have pending items. This read model exists only to satisfy "every automation reads from a todo list," not to accumulate and drain a queue — so it stays open-ended: fed by the external EVENT, read by the automation, never closed.
    - **Three separate columns**, left to right: `[external EVENT] → [todo-list READMODEL] → [AUTOMATION + COMMAND + internal EVENT]`. Never crammed into one or two — the "one EVENT per column" rule applies here too.
    - **Name the internal EVENT for its business meaning, not the transport** — usually the same name as the external EVENT (e.g. external `CopyReserved` → internal `CopyReserved`; the swimlane already shows which is which), never a mechanical `<X>SignalReceived`/`<X>RequestReceived` suffix. Same for the automation/command: `Record Reservation`/`RecordReservation`, not `Record Reservation Signal`/`RecordReservationSignal`.
-   - Its command and event carry no business decision — they only exist to produce the internal fact the next automation needs.
-2. **Worker automation** — the one that does the actual work (the domain reaction the process is really about, e.g. `ReserveCopy`). Its todo list is opened **only** by the internal EVENT the translation automation produced (this chapter's own swimlane) — never by the external EVENT directly — and closed by whatever event marks that work done. Unlike the translation stage, the worker's todo list keeps its normal open/close accumulator shape, because real pending work can sit there (it's the point where actual domain decisions happen).
+   - Its command and event carry no business decision — they only exist to produce the internal fact a worker automation would need, *if one is even needed* (see below).
+
+### Does a worker automation come after it, or does the chain stop there?
+
+The translation automation never decides anything — it only records a fact. Whether something needs to happen *after* that fact depends on whether there is still a decision left to make:
+
+- **Build a worker automation only when reacting to the internal EVENT requires a genuinely new decision on this side** — an invariant to check, a choice to make, data to compute that the internal EVENT doesn't already carry. That decision is what earns its own COMMAND, which is what earns the automation that issues it (see item 2 below for its shape).
+- **Do not build one when the internal EVENT already *is* the business-relevant fact.** If the external system already made every decision involved, and the "next" EVENT you were about to model would just restate data the internal EVENT already carries under a different name (same identity, no new field, no invariant checked, no choice made) — stop after the translation automation. That is not a second stage of the same chain; it is no chain at all, just a fact recorded once. Anything else that needs this fact reads the internal EVENT directly through a state-view READMODEL projection — it does not get an automated command reaction bolted on solely to keep a fixed "two automations" shape.
+
+  *Example*: an external `ReservationPlaced` opens a translation chain and already carries `reservationId`, `copyId`, and `memberId` — the copy to reserve was chosen upstream, by the other system. Translating it into an internal `ReservationPlaced` is still required (per the rule above — an automation may never react to the external event directly). But adding a second `ReservationsToApply` todo list + `Reserve Copy` automation + `CopyReserved` event on top of it is redundant: `CopyReserved` doesn't decide anything `ReservationPlaced` didn't already decide, it's the same fact under a different name. A read model showing "reserved copies" should project directly off the internal `ReservationPlaced` event, not off a manufactured second automation stage.
+
+2. **Worker automation** (only when the check above says one is needed) — the one that does the actual work (a real domain decision the process is about, e.g. checking copy availability before issuing `ReserveCopy`). Its todo list is opened **only** by the internal EVENT the translation automation produced (this chapter's own swimlane) — never by the external EVENT directly — and closed by whatever event marks that work done. Unlike the translation stage, the worker's todo list keeps its normal open/close accumulator shape, because real pending work can sit there (it's the point where actual domain decisions happen).
+
+**Two chained automations only when there genuinely are two decisions** — the translation (none, by definition) and the worker (a real one). Whether a worker stage exists at all is a judgment call driven by whether that second decision actually exists, not a fixed shape to stamp onto every cross-swimlane trigger.
 
-Wire the todo lists differently for each automation in the chain: for the translation automation, the external EVENT (second swimlane) **opens** the row and nothing closes it; for the worker automation, the internal EVENT **opens** its row and its own resulting EVENT **closes** it (backward arrow, per the exemption below). `EVENT → READMODEL` connections from both swimlanes are unaffected by which swimlane the event sits in.
+When a worker automation *is* warranted, wire the todo lists differently for each automation in the chain: for the translation automation, the external EVENT (second swimlane) **opens** the row and nothing closes it; for the worker automation, the internal EVENT **opens** its row and its own resulting EVENT **closes** it (backward arrow, per the exemption below). `EVENT → READMODEL` connections from both swimlanes are unaffected by which swimlane the event sits in.
 
 ## Fields on a todo-list read model
 
@@ -116,8 +130,9 @@ Run `validate_model` (`{boardId, chapterId}`) first — with the chain placed `a
 1. Does it have an incoming `READMODEL → AUTOMATION` connection to a todo-list read model? An AUTOMATION is **never** exempt — if not, design and wire it now.
 2. Is its todo list opened by an internal event only, **unless it is itself a translation automation** (which is the one case a second-swimlane event may open a todo list)? If a worker automation's todo list is opened directly by another system's event, that automation is missing its translation chain — split it into translation + worker automations per the rule above.
 3. If it's a **translation** automation, does its todo list have no closing edge — i.e. no connection from its own resulting internal EVENT back to its own todo-list read model? If one exists, remove it: a translation automation's todo list is never closed.
-4. If it's a **worker** automation, does its todo list have a proper closing edge from its own resulting event? If not, add it.
-5. Does the todo-list read model's field set avoid a `status` flag (membership in the list is the state)?
+4. If it's a **worker** automation sitting right after a translation automation, does its own COMMAND make a genuinely new decision the internal EVENT didn't already carry? If its fields and logic just restate the internal EVENT's own data under a new name, it's a redundant stage — remove the worker automation, its todo list, and its resulting event, and have downstream consumers project a state-view READMODEL directly off the internal EVENT instead.
+5. If it's a real worker automation, does its todo list have a proper closing edge from its own resulting event? If not, add it.
+6. Does the todo-list read model's field set avoid a `status` flag (membership in the list is the state)?
 
 List the result (connected / chain-resolved) for every automation checked — this is the evidence that `eventmodeling-identifying-outputs`'s later per-node verification pass (which re-checks automations defensively) finds nothing left to do here.
 
@@ -125,7 +140,8 @@ List the result (connected / chain-resolved) for every automation checked — th
 
 - [ ] Every AUTOMATION has an incoming `READMODEL → AUTOMATION` connection to a todo-list read model — no exemption, even for a simple relay
 - [ ] No automation's todo list is opened directly by another system's (second-swimlane) EVENT unless that automation is itself the translation automation
-- [ ] Every externally-triggered automation is modeled as two chained automations (translation + worker), never one
+- [ ] Every externally-triggered automation has a translation automation ahead of it — never triggered by the external EVENT directly
+- [ ] A worker automation exists after the translation stage only when it makes a genuinely new decision — not merely to keep a fixed "two automations" shape when the internal EVENT already is the business-relevant fact
 - [ ] Every **worker**-stage todo-list read model's opening and closing events are identified, including the automation's own resulting event as a closing event
 - [ ] Every **translation**-stage todo-list read model has an opening event (the external EVENT) and **no closing event at all** — no backward arrow from its own internal EVENT back to its own todo list
 - [ ] No todo-list read model uses a `status` field instead of list membership