@eventmodelers/cli 1.0.36 → 1.0.38

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

@@ -1,6 +1,6 @@
 ---
 name: eventmodeling-designing-event-models
-description: "Designs event-sourced domain models. Maps business processes to immutable events and state projections. Events are the source of truth; state is derived from events for command validation. Use when designing event streaming architectures from domain analysis. Do not use for: brainstorming events from scratch (use eventmodeling-brainstorming-events), optimizing stream sizing or snapshotting (use eventmodeling-optimizing-stream-design), or translating external system events (use eventmodeling-translating-external-events)."
+description: "Designs the event model for a business process — maps Commands, Events, and Read Models with clear causality. Events are business facts; Read Models are projections built from them. Use when designing the Command/Event/Read-Model structure from domain analysis. Do not use for: brainstorming events from scratch (use eventmodeling-brainstorming-events), or checking whether an event belongs to the right entity/timeline (use eventmodeling-optimizing-stream-design)."
 allowed-tools:
   - AskUserQuestion
   - Write
@@ -11,487 +11,87 @@ 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.
 
-## Interview Phase (Optional)
-
-**When to Interview**: Skip if the user has specified: stream identity strategy, command-specific state needs, and read model requirements. Interview when stream boundaries or state design are unclear.
-
-**Interview Strategy**: Establish stream identity and per-command state boundaries before designing. Ambiguous boundaries are the primary cause of the DDD aggregate anti-pattern appearing in event-sourced models.
-
-### Critical Questions
-
-1. **Stream Identity** (Impact: Determines how events are grouped into streams)
-   - Question: "What's the entity that owns events? (e.g., orderId, reviewId, customerId) What's the lifetime? Single transaction or years?"
-   - Why it matters: Wrong stream identity causes design problems; correct identity keeps streams appropriately scoped
-   - Follow-up triggers: If multiple candidates → ask "Which entity's identity would you use to load events for a single command decision?"
-
-2. **Minimal State vs Bundled State** (Impact: Prevents DDD aggregate anti-pattern)
-   - Question: "Will different commands need different state? Or does every command need the same full state?"
-   - Why it matters: Each command should have minimal, command-specific state—not bundled DDD aggregates
-   - Follow-up triggers: If "same full state" → walk through two commands and ask what each actually reads during validation
-
-### Interview Flow
-
-**Conditional Entry**:
-```text
-If user has provided:
-  - Stream identity (which entity ID anchors the stream)
-  - AND at least two commands with explicitly different state needs documented
-  - AND read model requirements (what queries the UI or processors make)
-
-Then: Skip interview, proceed directly to design
-
-Else: Conduct interview
-```
-
-**Phase 1: Stream Boundaries** (Question 1)
-- Confirm which entity anchors the stream
-- Establish stream lifetime expectations
-- Identify whether multiple candidate roots exist and resolve them
-
-**Phase 2: State Design** (Question 2)
-- Confirm per-command state isolation
-- Identify whether DDD aggregate thinking is present upfront
-- Establish minimal state shapes for at least two commands
-
-### 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
-## Designing Event Models (eventmodeling-designing-event-models)
-
-### Stream Identity
-[From Q1: Which entity? What identity key? Lifetime?]
-
-### Per-Command State Decisions
-[From Q2: Which commands need different state? Initial minimal state shapes?]
-
-### Design Decisions
-- Stream root: [entity name] identified by [id field]
-- State isolation: [confirmed / DDD pattern caught and corrected]
-```
-
-Update Interview Trail:
-```markdown
-| Design | eventmodeling-designing-event-models | Done | Stream identity, per-command state shapes |
-```
-
----
-
-## Core Architectural Rule
-
- **NEVER use a "DDD Aggregate Root" (bundled state) for command validation** Every command handler has its own minimal state projection. What DDD calls an "aggregate root" is actually a **read model**, not command-validation state.
-
-```text
- WRONG: Using DDD Aggregate as command state
-OrderAggregate { orderId, customerId, items[], total, status, paymentId, address, shippedAt, cancelledAt, ... }
-    ↑ This is a READ MODEL, not command state
-    ↓ NEVER use for command validation
-  handleConfirmOrder(OrderAggregate)
-  handleShipOrder(OrderAggregate)
-  handleCancelOrder(OrderAggregate)
-
- CORRECT: Minimal state per command
-ConfirmOrderState { status, orderId }
-    ↓
-  handleConfirmOrder(ConfirmOrderState)
-
-ShipOrderState { status, orderId, paymentId }
-    ↓
-  handleShipOrder(ShipOrderState)
-
-CancelOrderState { status, orderId, createdAt }
-    ↓
-  handleCancelOrder(CancelOrderState)
-
-OrderSummaryView { orderId, customerId, items[], total, status, paymentId, ... }
-    ↑ This is for UI queries, NOT command validation
-```
+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.
 
 ## Purpose
-Converts domain analysis into the event sourcing architecture pattern:
 
-**UI/Processor** → **Command** → [Command State Read Model] → **Event** → **Query Read Models** - **UI/Processor**: Entry points that trigger intent
-- **Command**: Intent data (can be rejected)
-- **Stream Root**: Logical grouping of immutable events (NOT a DDD aggregate bundle)
-- **Command State Read Model**: Minimal projection derived from events, optimized for this specific command's validation. Each command gets its own read model interface. Different commands = different shapes. (Categorized as "Command State" for semantic clarity)
-- **Event**: Result of successful command (immutable fact: command data + implicit context)
-- **Query Read Models**: Rich projections of events optimized for UI/Processor queries. Separate from command state. (Categorized as "Query Models" for semantic clarity)
+Converts domain analysis into the event modeling structure:
 
-## Workflow
+**UI/Processor** → **Command** → **Event** → **Read Model** → **UI/Processor**
 
-Given a domain analysis, design a complete event-sourced model:
+- **UI/Processor**: entry points that trigger intent
+- **Command**: business intent, expressed in business language, can be rejected
+- **Event**: a business fact — the result of a successful command
+- **Read Model**: a projection of events, shaped for a specific query need
 
-### 1. Design Event Streams
-Events are the immutable source of truth. Each stream holds facts about one entity:
-- **Stream Name**: Entity type + identity (Order:order-123)
-- **Event Type**: What changed? (past tense: Created, Confirmed, Shipped)
-- **Event Data**: Combines command input + implicit stream state facts
-- **Causality**: Triggered by which command?
+## Workflow
 
-Format:
-```text
-Stream: Order:order-123
+Given a domain analysis, design the event model:
 
-Events (chronological):
-1. OrderCreated
-   Triggered by: CreateOrder command
-   Data: customerId, items[], total, shippingAddress, createdAt
-   (from command: customerId, items[], shippingAddress)
-   (implicit: total calculated from items)
+### 1. Design Events
 
-2. OrderConfirmed
-   Triggered by: ConfirmOrder command
-   Data: paymentId, confirmedAt
-   (from command: paymentId)
-   (implicit: orderId from stream, previous status verified)
+Events are business facts, not technical occurrences:
+- **Event Type**: what changed, in past tense business language (Created, Confirmed, Shipped)
+- **Event Data**: the business fields, noting which came directly from the triggering command versus which are implicit context (e.g. a calculated total, or the entity's identity)
+- **Causality**: which command triggered it
 
-3. OrderShipped
-   Triggered by: ShipOrder command
-   Data: shipmentId, shippedAt
-   (from command: shipmentId)
-   (implicit: orderId, confirmed status verified)
-```
+Document each entity's events as a chronological list, giving each event's triggering command and its data. A full worked example (an Order) is in `references/examples.md`.
 
 **Key Rules**:
-- Events are **immutable facts** from successful commands
-- Event data = command input + implicit stream state context
-- Stream identity is explicit (Order:order-123)
-- Event order matters for state reconstruction
-- Never modify or delete events
-- Events only exist if command succeeded
-
-### 2. Design Command State Read Models (Minimal Per-Command)
-
- **Critical Rule: Each command must have its own read model (command state). NEVER share read models between commands.** **Naming Convention (for Automation)**:
-- `[CommandName]State` = Implemented command state read model
-- `[CommandName]StateToDo` = Planned command state read model (marked for implementation)
-
-Examples:
-- `PublishReviewState` = implemented
-- `EditReviewStateToDo` = planned, needs implementation
-- `SellerRespondState` = implemented
-
-**Semantic Categorization**: These are read models, but categorized as "Command State" based on their purpose (command validation, not UI queries).
-
-Command state read models are **derived** from events and **minimal**:
-- Read only events needed for a specific command's decision
-- Build state by replaying only relevant events
-- **ENFORCEMENT**: Different commands = different read model interfaces. Period.
-- Each command handler defines what state projection it needs (and ONLY what it needs)
-- Projection can be regenerated from events at any time
-
-Example for Order stream with separate command state read model for EACH command:
-
-```text
-## ConfirmOrder Command (IMPLEMENTED)
-State interface: ConfirmOrderState { status, orderId }
-Builder: buildConfirmOrderState(events)
-Naming: [CommandName]State = implemented
-- OrderCreated event → Set status='Draft'
-- OrderConfirmed event → Set status='Confirmed'
-(SKIP: items, total, shipping - not needed for this command)
-
-## ShipOrder Command (IMPLEMENTED)
-State interface: ShipOrderState { status, orderId, paymentId }
-Builder: buildShipOrderState(events)
-Naming: [CommandName]State = implemented
-(DIFFERENT from ConfirmOrderState)
-- OrderCreated event → (skip)
-- OrderConfirmed event → Set status='Confirmed', set paymentId
-- OrderShipped event → Set status='Shipped'
-
-## CancelOrder Command (PLANNED - NOT IMPLEMENTED)
-State interface: CancelOrderStateToDo { status, orderId, createdAt }
-Builder: buildCancelOrderStateToDo(events) [STUB - TODO]
-Naming: [CommandName]StateToDo = planned, needs implementation
-(DIFFERENT from both above)
-- OrderCreated event → Set status='Draft', createdAt
-- OrderCancelled event → Set status='Cancelled'
-```
-
-**Enforcement Rule**:
-- ConfirmOrderState used ONLY by handleConfirmOrder
-- ShipOrderState used ONLY by handleShipOrder
-- NEVER share state between commands
-- NEVER create a single "OrderState" for all Order commands
+- Events are immutable business facts
+- Events use past tense, business language
+- Event order matters — it tells the story
+- Never modify or delete an event once it exists
+- Events only exist if the triggering command succeeded
 
-This is **NOT** a full aggregate state bundle—it's minimal, command-specific state access.
+### 2. Design Commands
 
-### 3. Design Commands
-Commands are **intent data from UI or Processor**:
-- Represent what user/system wants to do
+Commands are business intent from a UI or Processor:
+- Represent what a user or system wants to do
 - Can be rejected (validation failure)
-- Only UI or Processor can issue commands
-- Load current stream state for validation
+- Only a UI or Processor can issue a command
 - Produce events if valid, or reject if invalid
 
-Format:
-```text
-Command: ConfirmOrder
-Source: UI or Processor (only these can issue)
-Input: orderId, paymentId
-
-Processing:
-    1. Load current state from Order:orderId stream
-    2. Validate preconditions:
-       - state.status === 'Draft' (reject: already confirmed)
-       - paymentId is valid (reject: invalid payment)
-    3. If all valid:
-       - Produce: OrderConfirmed event
-         - Data: paymentId, confirmedAt
-         - Implicit: orderId (from stream), previous status (from state)
-    4. If any validation fails:
-       - Reject: return error (no event created)
-
-Outcomes:
-     Success: OrderConfirmed event appended to stream
-     Rejection: Error returned, no event created
-```
+Document each command's source, its input fields, the preconditions it's checked against, the event(s) it produces on success (noting which data comes from the command versus implicit context), and its rejection outcomes. A full worked example (ConfirmOrder) is in `references/examples.md`.
 
 **Key Rules**:
-- Only UI or Processor can issue commands (entry points)
+- Only a UI or Processor can issue commands (entry points)
 - One command per UI/Processor action
-- Commands validate against stream state
 - Successful command → Event(s) created
 - Failed validation → Command rejected, no event
-- Commands are synchronous decision logic (pure)
-
-### 4. Design Read Models
-Read models are **projections of events for UI/Processor queries**:
-- Built from events (only source is events)
-- Optimized for specific query patterns
-- Consumed by UI or Processor (for display/decision)
-- Can be regenerated from events anytime
-
-Format:
-```text
-ReadModel: OrderSummaryView
-Purpose: UI displays customer order list, Processor checks order status
-
-Subscribed to events:
-  - OrderCreated
-  - OrderConfirmed
-  - OrderShipped
-  - OrderCancelled
-
-Data (optimized for queries):
-  {
-    orderId: string
-    customerId: string
-    total: number
-    status: string
-    createdAt: Date
-    confirmedAt?: Date
-    shippedAt?: Date
-  }
 
-Update from events:
-  - OrderCreated → Insert row (id, customer, total, status='Draft')
-  - OrderConfirmed → Update status='Confirmed', set confirmedAt
-  - OrderShipped → Update status='Shipped', set shippedAt
-  - OrderCancelled → Update status='Cancelled'
+### 3. Design Read Models
 
-Consumed by:
-  - UI: displays list of orders
-  - Processor: checks if order can be shipped
-```
+Read models are projections of events, built for UI/Processor queries:
+- Built from events (their only source)
+- Optimized for a specific query pattern
+- Consumed by UI (for display) or Processor (for a decision)
+- Can be regenerated from events at any time
 
-### 5. Document Event Causality
-Show how events relate to each other:
+Document each read model's purpose, which events it subscribes to, its query-shaped data, how each subscribed event updates that data, and who consumes it. A full worked example (OrderSummaryView) is in `references/examples.md`.
 
-```text
-Command Flow:
-CreateOrder command
-    → OrderCreated event
-       ↓ (may trigger external process)
-ConfirmOrder command (reads OrderCreated state)
-    → OrderConfirmed event
-       ↓ (may trigger)
-ShipOrder command (reads OrderCreated + OrderConfirmed state)
-    → OrderShipped event
-```
+### 4. Document Event Causality
 
-### 6. Document State Transitions
-Show valid state transitions:
+Trace the causal chain from the first command through the events and downstream commands it can trigger, showing how a later command's decision depends on events produced earlier. A full worked example (an Order create→confirm→ship chain) is in `references/examples.md`.
 
-```text
-Order Stream State Transitions:
+### 5. Document State Transitions
 
-Initial state: (empty stream)
-  ↓
-CreateOrder → OrderCreated
-  ↓
-State: Draft
-
-Draft state:
-  → ConfirmOrder → OrderConfirmed → State: Confirmed
-  → CancelOrder → OrderCancelled → State: Cancelled
-
-Confirmed state:
-  → ShipOrder → OrderShipped → State: Shipped
-  → CancelOrder (rejected - already confirmed)
-
-Shipped state:
-  → No more transitions allowed
-```
+Map the valid states a process can be in, which command causes which transition, and which transitions are invalid from a given state (e.g. cancelling an already-shipped order), ending at any terminal states. A full worked example (Order transitions) is in `references/examples.md`.
 
 ### Output Format
 
-Present complete model as:
-
-```markdown
-# Event Model: [Domain]
-
-## Event Streams
-
-### Stream: Order
-
-**Identity**: orderId
-
-**Events**:
-- OrderCreated: Initial event creating the order
-Data: customerId, items[], total, shippingAddress
-
-- OrderConfirmed: Payment confirmed
-Data: paymentId, confirmedAt
-
-- OrderShipped: Order shipped
-Data: shipmentId, shippedAt
-
-- OrderCancelled: Order cancelled
-Data: cancelledAt, reason
-
-**State Projection (Human Example)**:
-For the ConfirmOrder command, we need minimal state:
-```text
-ConfirmOrderState:
-  - orderId: 'order-123'
-  - status: 'Draft'
-```
-
-For the ShipOrder command, we need different data:
-```text
-ShipOrderState:
-  - orderId: 'order-123'
-  - status: 'Confirmed'
-  - paymentId: 'payment-456'
-```
-
----
-
-## Commands
-
-### Command: CreateOrder
-- Input: customerId, items[], shippingAddress
-- Validation: Items valid, customerId exists
-- Events produced: OrderCreated
-- Possible outcomes: Success (OrderCreated) or Validation error
-
-### Command: ConfirmOrder
-- Input: orderId, paymentId
-- Validation: Order in Draft status, payment validated
-- Events produced: OrderConfirmed
-- Possible outcomes: Success or "Already confirmed" error
-
----
-
-## Read Models (Optional)
-
-### ReadModel: OrderSummaryView
-- Purpose: Quick lookup of order status
-- Events: OrderCreated, OrderConfirmed, OrderShipped, OrderCancelled
-- Queries served: GetOrder(orderId), ListOrdersByCustomer(customerId)
-
----
-
-## Implementation Notes
-- All state is derived from events
-- Commands validate against derived state
-- No transaction across streams
-- Events are source of truth
-- Read models can be rebuilt from events
-```
-
-## Key Event Sourcing Principles
-
-1. **Events are Facts**: Events describe what happened, not what might happen
-2. **Immutable Event Log**: Events are appended, never modified
-3. **State is Minimal and Command-Driven**: State is built by replaying events, but ONLY for what a specific command needs to validate. Not all stream fields are needed for all commands.
-4. **Not DDD Aggregates**: Stream roots group events logically, but aren't bundles of related data like DDD aggregates. State is determined per-command, not designed upfront for the whole stream.
-5. **Commands are Pure**: No side effects, just decision logic against minimal state
-6. **Read Models are Separate**: Read models (projections) are separate from command-validation state. Read models can have rich data; command state stays minimal.
-7. **Event Causality**: Commands → [minimal state] → Events → [read models]
-
-## Design Patterns
-
-### Compensation Pattern
-Handle errors by appending compensation events:
-```text
-Command: ProcessPayment failed
-  → PaymentFailed event
-    (triggered by external error)
-  → OrderCancelled event (compensation)
-    (or retry logic)
-```
-
-### Temporal Queries
-Answer "what was the state at time T?":
-```text
-Replay events up to timestamp T
-  → Get historical state
-```
-
-## Best Practices for Event Model Design
-
-### 1. Design Minimal State Per Command
-Each command handler only loads the state it needs:
-- "LoadOrderState loads { id, items, total, shipping, customer, payment, status, ... }"
-- "ConfirmOrderState loads { status, orderId }"
-- "ShipOrderState loads { status, orderId, paymentConfirmed }"
-
-### 2. Separate Command State from Query Models
-Keep command-validation state and read models strictly separate:
-- **Command State** (minimal): Used by handlers to validate commands
-- **Query Models** (rich): Used by UI/Processor to display/query data
-- Never share between them
-
-### 3. Name State Interfaces by Command
-Use the pattern `[CommandName]State` to make the relationship explicit:
-- `PublishReviewState` for PublishReview command
-- `EditReviewState` for EditReview command
-- `ReviewState` (ambiguous - which command?)
-
-### 4. Document State Transitions Clearly
-Show what state changes trigger what commands:
-- Include initial state
-- Show all valid transitions
-- Mark impossible transitions (and why)
-- Document rejection conditions
+Present the complete model as a markdown document with sections for Events (per entity, chronological, each with its triggering command), Commands (input, preconditions, events produced, rejection outcomes), and Read Models (purpose, subscribed events, consumers). A full worked example of this document structure is in `references/examples.md`.
 
-### 5. Make All Constraints Explicit
-Transform "obvious" business rules into documented invariants:
-- "Obviously can't ship an unconfirmed order"
-- "ShipOrder validation: requires status='Confirmed' with paymentId"
+## Key Principles
 
-### 6. Keep Event Data Factual
-Events record facts, not derived values:
-- "OrderCreated { items, total }" (total is computed from items)
-- "OrderCreated { items[] with unitPrice, shippingAddress }" (total computed in projection)
+See `eventmodeling-core-rules` for the element definitions and causality rules this design must follow (events are immutable facts, commands are checked against documented preconditions, read models never drive command validation).
 
 ## Quality Checklist
 
-- [ ] All events are immutable facts (past tense)
-- [ ] Events contain only captured data, no computed fields
-- [ ] State projection is deterministic from events
-- [ ] Each command validates against current state
-- [ ] Commands either produce events or reject
-- [ ] Event causality is clear
-- [ ] State transitions are documented
-- [ ] No references between streams in events
-- [ ] Read models are optional, not required
-- [ ] All logic is state → events (pure functions)
+- [ ] All events are immutable business facts (past tense)
+- [ ] Events contain only captured business data, no computed fields
+- [ ] Each command's preconditions are documented explicitly
+- [ ] Commands either produce events or are rejected — no silent failures
+- [ ] Event causality is clear and traceable end to end
+- [ ] State transitions are documented, including which ones are invalid and why
+- [ ] Read models are optional — nothing requires one to exist