@eventmodelers/cli 0.0.1

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-orchestrating-event-modeling/references/project-planning-with-event-modeling.md

@@ -0,0 +1,341 @@
+# Project Planning with Event Modeling
+
+## Overview
+
+One of the most significant benefits of Event Modeling is the **flat cost curve** for features. Unlike traditional development where each new feature becomes increasingly complex and expensive, Event Modeling enables teams to deliver features at a consistent cost.
+
+## The Flat Cost Curve
+
+### Traditional Development Cost Pattern
+
+```
+Feature Cost
+  ^
+       Feature 3 (hardest, most expensive)
+          /\
+         /  \
+        /    \
+       /      Feature 2 (harder, expensive)
+      /        /\
+     /        /  \
+    /        /    \
+   /  Feature 1   /
+   /____/\______/_____ Time
+
+Problem: Cost increases with each feature
+  - Feature 1: 2 weeks, 2 people
+  - Feature 2: 4 weeks, 3 people
+  - Feature 3: 8 weeks, 5 people
+
+Reason: Increasing technical debt and coupling
+```
+
+### Event Modeling Cost Pattern
+
+```
+Feature Cost
+  ^
+    Feature 1  Feature 2  Feature 3  Feature 4
+      /\        /\        /\        /\
+     /  \      /  \      /  \      /  \
+    /    \    /    \    /    \    /    \
+   /______\  /______\  /______\  /______\___ Time
+  
+Consistent: Each feature = ~2 weeks, ~2 people
+
+Reason: Clear contracts between steps enable parallel work
+```
+
+### Why the Flat Curve?
+
+The article explains:
+
+> "The biggest impact of using Event Modeling is the flat cost curve of the average feature cost. This is due to the fact that the effort of building each workflow step is not impacted by the development of other workflows."
+
+**Key Insight**: When you have explicit contracts, teams can work independently.
+
+```
+Team A builds Step 1 (Create Order)
+  - Produces: OrderCreated event with specific fields
+  - Contract: "If OrderCreated exists, these fields are guaranteed"
+
+Team B builds Step 2 (Confirm Order)
+  - Precondition: OrderCreated event exists
+  - Can start IMMEDIATELY while Team A finishes
+  - Mocks OrderCreated event in tests
+  - When Step 1 ready, tests pass immediately
+
+Team C builds Step 3 (Authorize Payment)
+  - Precondition: OrderConfirmed event exists
+  - Can start immediately
+  - Works independently
+
+Result: 3 features in parallel instead of sequential!
+Cost per feature: Constant
+Delivery speed: 3x faster
+```
+
+## Velocity-Based Estimation
+
+Instead of story points, estimate using workflow steps.
+
+### Measuring Velocity
+
+```
+Definition: Velocity = Number of workflow steps completed per sprint
+
+Example Sprint:
+Week 1:
+    Team A: Completed CreateOrder command (1 step)
+    Team B: Completed ConfirmOrder command (1 step)
+    Team C: Completed AuthorizePayment processor (1 step)
+
+Velocity: 3 workflow steps per sprint
+
+Historical data:
+Sprint 1: 3 steps
+Sprint 2: 3 steps
+Sprint 3: 2 steps (one complex step slowed us down)
+Sprint 4: 3 steps
+
+Average velocity: ~3 steps per sprint
+```
+
+### Estimating Projects
+
+```
+New Feature: E-Commerce with Reviews
+
+Event Model:
+Workflow steps identified:
+    Step 1: Create Order
+    Step 2: Confirm Order
+    Step 3: Authorize Payment
+    Step 4: Reserve Inventory
+    Step 5: Create Shipment
+    Step 6: Deliver Package
+    Step 7: Submit Review
+    Step 8: Moderate Review
+    Step 9: Calculate Ratings (read model)
+
+Total: 9 workflow steps
+
+Team velocity: 3 steps per sprint
+
+Estimate: 9 ÷ 3 = 3 sprints = ~12 weeks
+
+Without Event Modeling:
+    - Estimate: 4-6 months (guess)
+    - Actual: Often 6-9 months due to coupling issues
+
+With Event Modeling:
+    - Estimate: 3 sprints (confident)
+    - Actual: Usually matches or beats estimate
+```
+
+### Benefits of Velocity-Based Estimation
+
+1. **Empirical**: Based on actual history, not guesses
+2. **Objective**: Not influenced by opinion
+3. **Consistent**: Same factors each time
+4. **Scalable**: Works for teams and organizations
+5. **Improvable**: You can identify and fix bottlenecks
+
+## Project Planning Spreadsheet
+
+```
+Project: Order Management System
+Team Velocity: 3 steps per sprint
+
+Feature Planning:
+
+ Feature                              Steps  Sprints   Timeline 
+
+ Core Order Flow                        3    1 sprint  Week 1-4 
+ Payment Processing                     2    1 sprint  Week 5-8 
+ Inventory Management                   2    1 sprint  Week 9-12
+ Fulfillment & Shipping                 2    1 sprint  Week 13-16
+ Order Tracking (read model)            1    0.3 spr   Week 17  
+ Customer Reviews                       2    1 sprint  Week 18-21
+ Analytics Dashboard                    1    0.3 spr   Week 22  
+
+ TOTAL                                 13    4 sprints ~22 weeks
+
+
+With parallel teams:
+  - Team A: Weeks 1-4 (Orders)
+  - Team B: Weeks 1-4 (Payments) ← Parallel!
+  - Team C: Weeks 1-4 (Inventory) ← Parallel!
+  - Team D: Weeks 5-8 (Fulfillment) ← After steps 1-3
+
+Result: All work done in ~8 weeks with proper parallelization
+Without parallelization: ~22 weeks (1 team, sequential delivery)
+```
+
+## Scaling to Organization Level
+
+### Velocity per Team
+
+```
+Organization has 3 teams:
+
+Team A (Order Processing): 3 steps/sprint
+Team B (Payment): 2 steps/sprint
+Team C (Fulfillment): 3 steps/sprint
+
+Organization velocity: 8 steps/sprint
+
+Can deliver projects worth 8 workflow steps in parallel per sprint!
+```
+
+### Multi-Team Project Planning
+
+```
+Large Project: Complete E-Commerce Platform
+
+Identify all workflow steps:
+Phase 1 (must complete first):
+    - Create Order (Step 1)
+    - Confirm Order (Step 2)
+    - Authorize Payment (Step 3)
+    → 3 steps, 1 sprint with 3 teams
+
+Phase 2 (depends on Phase 1):
+    - Reserve Inventory (Step 4)
+    - Create Shipment (Step 5)
+    - Deliver Package (Step 6)
+    → 3 steps, 1 sprint with 3 teams
+
+Phase 3 (independent from 1-2):
+    - Customer Reviews (Step 7-8)
+    - Rating Calculations (Step 9)
+    → 3 steps, 1 sprint with 3 teams
+
+Total: 9 steps, 3 sprints, 3 teams working in parallel = 3 sprints total
+
+Without parallelization: 9 steps × 1 team = 9 sprints sequential
+With proper contracts: 3 sprints with 3 teams
+Speedup: 3x faster!
+```
+
+## Handling Variable Complexity
+
+Some workflow steps are more complex:
+
+```
+Typical workflow step: 1 week, 1 developer
+Complex workflow step: 2 weeks, 1-2 developers
+Simple workflow step (read model): 0.5 weeks, 1 developer
+
+Velocity calculation (realistic):
+Sprint 1:
+    - CreateOrder (typical): 1 step
+    - ComplexPaymentValidation (complex): 0.5 steps
+    - Notifications (simple): 1 step
+    → Velocity: 2.5 steps/sprint
+
+Using this more accurate velocity:
+  9-step project = 9 ÷ 2.5 = 3.6 sprints
+More realistic estimate!
+```
+
+## Capacity Planning
+
+```
+Team has 1 developer available
+Velocity: ~2.5 steps/sprint
+
+Project needs 13 workflow steps delivered
+Timeline: 13 ÷ 2.5 = 5.2 sprints = ~5.5 months
+
+Add another developer:
+Team velocity: ~5 steps/sprint
+Timeline: 13 ÷ 5 = 2.6 sprints = ~2.5 months
+Cost reduction: 50% reduction in calendar time
+
+Add processes/tools:
+Better test infrastructure: +0.5 steps/sprint
+Better CI/CD: +0.5 steps/sprint
+New velocity: ~6 steps/sprint
+Timeline: 13 ÷ 6 = 2.2 sprints = ~2 months
+```
+
+## Common Estimation Mistakes
+
+###  Mistake 1: Counting All Features as Equal Weight
+
+```
+Wrong: "Feature A = 8 points, Feature B = 8 points" (same complexity?)
+Right: "Feature A = 3 workflow steps, Feature B = 5 workflow steps"
+       (Different complexity reflected)
+```
+
+###  Mistake 2: Including Non-Workflow-Step Work
+
+```
+Wrong: "8 points for order system" (includes meetings, planning, docs)
+Right: "5 workflow steps for order system" (measure implementation only)
+       Add separate budget for: Planning (1 week), Testing (1 week), Deployment (0.5 week)
+```
+
+###  Mistake 3: Ignoring Workflow Step Dependencies
+
+```
+Wrong: "Project = 10 steps, 2 teams, 5 sprints"
+Right: Identify dependencies:
+       - Steps 1-3 can run in parallel (3 sprints)
+       - Steps 4-5 depend on 1-3 (sequential after)
+       - Steps 6-10 can run in parallel with 4-5
+       → 5-6 sprints with proper dependency management
+```
+
+## Retrospectives & Velocity Improvement
+
+Use completed projects to improve estimation:
+
+```
+Sprint Retrospective:
+
+Planned: 3 workflow steps
+Completed: 2.5 workflow steps
+Blocking issue: "Couldn't start step C until step B was fully integrated"
+
+Action: Better integration earlier → Next sprint, improve parallelization
+
+Track over time:
+Sprint 1 velocity: 2.5
+Sprint 2 velocity: 2.8 (better parallelization)
+Sprint 3 velocity: 3.2 (developers more comfortable with patterns)
+Sprint 4 velocity: 3.0 (added new junior developer, slower)
+
+Trend: Improving as team gets comfortable (minus new hires)
+```
+
+## Key Metrics
+
+| Metric | Calculation | What It Tells You |
+|--------|-----------|-------------------|
+| **Velocity** | Workflow steps completed / sprint | Team throughput |
+| **Step Complexity** | Actual time / 1 week | Which steps take longer |
+| **Parallelization Rate** | Teams working on independent steps / total teams | How well we're using resources |
+| **Estimation Accuracy** | Planned steps / completed steps | How good our estimates are |
+
+## Summary: From Estimates to Reality
+
+```
+Traditional Approach:
+Project scope → [Guess complexity] → Estimate → [Often wrong]
+
+Event Modeling Approach:
+Project scope → [Count workflow steps] → [Use historical velocity] →
+Estimate → [Usually accurate] → Deliver on time
+
+Traditional accuracy: ±50% (at best)
+Event Modeling accuracy: ±10% (with historical data)
+```
+
+## Further Reading
+
+- Article section: "Flat Cost Curve"
+- Article section: "Estimates without Estimating"
+- Article section: "Strong Contracts"

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

@@ -0,0 +1,153 @@
+---
+name: eventmodeling-plotting-events
+description: "Step 2 of Event Modeling - Arrange events chronologically in logical narrative sequence. Create timeline showing event flow and dependencies. Use after brainstorming events. Do not use for: brainstorming new events (use eventmodeling-brainstorming-events) or designing command/read model architecture (use eventmodeling-designing-event-models)."
+allowed-tools:
+  - Write
+  - Bash
+---
+
+# Plotting Events
+
+> **Before doing anything else**, invoke the `connect` skill to resolve `TOKEN`, `BOARD_ID`, `ORG_ID`, and `BASE_URL`. Then invoke the `learn-eventmodelers-api` skill to load the full API reference. Do not proceed until both skills have been loaded.
+
+Arrange all brainstormed events chronologically to create a logical sequence that makes sense as a narrative timeline. Show how events flow and depend on each other.
+
+## Workflow
+
+Given a list of brainstormed events, create the chronological plot:
+
+### 1. Sequence Events Chronologically
+Order events in time-based narrative:
+- What happens first?
+- What depends on what?
+- What's the causal chain?
+
+Format:
+```
+Timeline: Order Processing
+
+1. Customer initiates → OrderCreated
+   (Event: OrderCreated)
+
+2. Order confirmed → OrderConfirmed
+   Depends on: OrderCreated happened
+   (Event: OrderConfirmed)
+
+3. Payment processed → PaymentAuthorized
+   Depends on: OrderConfirmed happened
+   (Event: PaymentAuthorized)
+
+4. Inventory reserved → InventoryReserved
+   Depends on: PaymentAuthorized happened
+   (Event: InventoryReserved)
+
+5. Order shipped → OrderShipped
+   Depends on: InventoryReserved happened
+   (Event: OrderShipped)
+
+6. Delivery confirmed → DeliveryConfirmed
+   Depends on: OrderShipped happened
+   (Event: DeliveryConfirmed)
+```
+
+### 2. Show Dependencies and Causality
+Document what triggers each event:
+```
+Event: OrderConfirmed
+Can only happen after: OrderCreated
+Triggered by: Customer confirms order
+Precondition: Order in Draft state
+
+Event: PaymentAuthorized
+Can only happen after: OrderConfirmed
+Triggered by: Payment gateway authorizes
+Precondition: Order confirmed and payment submitted
+```
+
+### 3. Identify Alternative Paths
+Show events that can diverge:
+```
+After OrderCreated:
+Path A: Customer confirms → OrderConfirmed
+Path B: Customer cancels → OrderCancelled
+
+After PaymentAuthorized:
+Path A: Payment succeeds → PaymentProcessed
+Path B: Payment fails → PaymentFailed → OrderCancelled
+```
+
+### 4. Create Timeline Diagram
+Visual representation of event flow:
+
+```
+
+ Time →                                           
+
+ OrderCreated                                     
+    ↓                                             
+ OrderConfirmed                                   
+    → PaymentAuthorized                          
+        → InventoryReserved                     
+            → OrderShipped                     
+                 → DeliveryConfirmed           
+        → PaymentFailed → OrderCancelled        
+    → OrderCancelled (rejected before payment)   
+
+```
+
+## Chapters and Timelines
+
+Timelines (chapters) are **created and assigned during Step 1 (Brainstorming)**. This step does not create new chapters. Each plotting pass operates on a **single timeline** — the one the user is currently focusing on.
+
+Before placing events, resolve the target timeline:
+
+```bash
+curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
+  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=CHAPTER"
+```
+
+If multiple timelines exist, ask the user which one to work on now. Never reorder events across timelines in a single pass.
+
+## Output Format
+
+Instead of writing a markdown document, **place every event on the board** using the `place-element` skill.
+
+Work within the chosen timeline only. For each event in the final chronological order, invoke `place-element` with:
+
+| Parameter | Value |
+|-----------|-------|
+| `elementType` | `EVENT` |
+| `title` | `<EventName>` |
+| `boardId` | `BOARD_ID` |
+| `timelineId` | the chapter this event belongs to |
+
+Reuse existing empty columns, do not blindly create new ones.
+
+Process events in order, one at a time. Do not skip any event.
+
+After all events are placed, summarise to the user:
+- Chapter(s)/timeline ID(s) with their titles
+- Numbered list of events placed per chapter
+- Key insights: critical path, decision points, terminal events
+- Any errors
+
+## Quality Checklist
+
+- [ ] **Working on a single named timeline** — not mixing events from different chapters
+- [ ] **No new chapters created here** — chapter structure was fixed in Step 1 (Brainstorming)
+- [ ] Every event has clear predecessor
+- [ ] Dependencies are explicitly documented
+- [ ] Alternative paths are shown
+- [ ] Flow forms a coherent narrative
+- [ ] No events without trigger
+- [ ] Terminal states are clear
+- [ ] Compensation/cancellation flows are complete
+- [ ] Timeline makes business sense
+
+## Principles
+
+1. **Narrative Coherence**: Events tell a story
+2. **Dependency Clarity**: What must come before what
+3. **Alternative Paths**: Show all possible flows (happy path + errors)
+4. **Natural Sequence**: Order matches business domain logic
+5. **Completeness**: Every brainstormed event appears

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

@@ -0,0 +1,136 @@
+---
+name: eventmodeling-slicing-event-models
+description: "Identify feature slices directly from a completed event model's timeline and create slice definitions on the board — each COMMAND becomes a state-change slice, each READMODEL becomes a state-view slice, each AUTOMATION becomes an automation slice. Use after completing event modeling to define slice boundaries and note event dependencies between them. Do not use for: organizational team structure based on Conway's Law (use eventmodeling-applying-conways-law) or planning before the event model is complete (complete the full model first using eventmodeling-orchestrating-event-modeling)."
+allowed-tools:
+  - AskUserQuestion
+  - Write
+  - Bash
+---
+
+# Slicing Event Models
+
+> **Before doing anything else**, invoke the `connect` skill to resolve `TOKEN`, `BOARD_ID`, `ORG_ID`, and `BASE_URL`. Then invoke the `learn-eventmodelers-api` skill to load the full API reference (in particular the **Slices** section). Do not proceed until both skills have been loaded.
+
+**Purpose**: Turn a completed event model's timeline into explicit slice definitions on the board, and note the event dependencies between them.
+
+**When to Use**:
+- After completing the full event model (commands, events, read models are in place)
+- To make slice boundaries explicit on the board before implementation
+- To see which slices' events other slices depend on
+
+---
+
+## Core Concept: A Slice Is One Command, One Read Model, or One Automation — Never Combined
+
+A **Feature Slice** is the thinnest possible vertical cut through the model — exactly one decision or one query:
+
+```
+state-change slice = SCREEN/Processor → COMMAND → EVENT(s)
+state-view slice   = EVENT(s) → READMODEL → SCREEN/Processor
+automation slice   = EVENT(s) → AUTOMATION → COMMAND → EVENT(s)
+```
+
+A slice never mixes a COMMAND and a READMODEL — the platform models these as two distinct slice types (`state-change` and `state-view`). If a "feature" needs both a command and a read model (e.g. "place an order" needs the `PlaceOrder` command *and* an `OrderDetailView` read model), that's **two slices**, not one.
+
+**Key characteristics**:
+- Exactly one COMMAND (state-change), exactly one READMODEL (state-view), or one AUTOMATION's command — never combined
+- Named after that command, read model, or automation
+- Independently deployable
+- Communicates with other slices via events only
+
+---
+
+## Slices Already Exist in the Timeline
+
+By the time an event model is complete, the slices are already implied by the timeline's structure. This skill's job is to make them explicit on the board — not to invent broader groupings.
+
+Walk the timeline column by column:
+- Every **COMMAND** → one `state-change` slice, named after the command
+- Every **READMODEL** → one `state-view` slice, named after the read model
+- Every **AUTOMATION** → one `automation` slice, named after the automation (or the command it issues)
+
+---
+
+## Step 1: Resolve the Timeline
+
+`$TL` (the timeline/chapter UUID) is required for every call below. If it wasn't given up front, resolve it before doing anything else:
+
+```bash
+curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=CHAPTER"
+```
+
+- **Exactly one chapter** → use it automatically, tell the user which one was selected.
+- **Multiple chapters** → list them by name/ID and use `AskUserQuestion` to ask which one to slice.
+- **No chapters** → stop and tell the user to create a chapter/timeline first (e.g. via the `/timeline` skill).
+
+## Step 2: Enumerate Commands, Read Models, and Automations
+
+Use `spec-info` (or existing board knowledge) to list every COMMAND, READMODEL, and AUTOMATION node across the resolved timeline:
+
+```bash
+curl "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/timelines/$TL/spec-info" -H "x-token: $TOKEN"
+# → { timelineId, elements: [{ id, title, type }] }
+```
+
+Filter to `type` in `COMMAND`, `READMODEL`, `AUTOMATION`.
+
+`spec-info` doesn't include the column each element sits in, so fetch the chapter node to resolve it:
+
+```bash
+curl -s "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes/$TL" -H "x-token: $TOKEN"
+# → meta.timelineData.columns: [{ id, index }]
+# → meta.timelineData.cells:   [{ id: "<rowId>-<columnId>", nodeId }]
+```
+
+For each filtered element, find the cell whose `nodeId` matches the element's `id` — the `columnId` is the cell `id` with the leading `<rowId>-` (36 chars + hyphen) stripped off. Record `{ elementId, elementType, title, columnId }` for every COMMAND, READMODEL, and AUTOMATION.
+
+Check which columns already have a slice, so you don't create duplicates:
+
+```bash
+curl $BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/slicedata/slices -H "x-token: $TOKEN"
+# → { slices: [{ id, title, status }] }
+```
+
+A column already has a slice if its element's title matches an existing slice's title.
+
+## Step 3: Define slices
+
+For each column from Step 2 that doesn't already have a matching slice, mark that **existing** column as a slice via the **slice-definitions** endpoint:
+
+```bash
+curl -X POST $BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/timelines/$TL/slice-definitions \
+  -H "x-token: $TOKEN" -H "Content-Type: application/json" \
+  -d '{"columnId":"<colId>","title":"PlaceOrder"}'
+# → 200 { nodeId, timelineId, columnId, title }
+```
+
+- COMMAND column → title = command name (state-change slice)
+- READMODEL column → title = read model name (state-view slice)
+- AUTOMATION column → title = automation name, or the command it issues (automation slice)
+
+Use **`slice-definitions`**, never the plain **`slices`** endpoint here — `slices` creates a brand-new column with its own swimlane/content nodes, which would duplicate the element already placed on the timeline. `slice-definitions` only adds a `SLICE_BORDER` node to the column you already resolved in Step 2. `title` always comes from the request body — it is never derived automatically from the command/read model/automation node.
+
+## Step 4 (Optional): Note Dependencies Between Slices
+
+Slices depend on each other only through events — never directly:
+
+- **Event dependency** — slice B's command or read model needs an event that slice A produces.
+- **No dependency** — slices work off entirely separate events.
+
+This is useful to surface back to the user (e.g. "`OrderDetailView` depends on `PlaceOrder`'s `OrderPlaced` event"). Slicing itself does not require planning team allocation, sprint sizing, or effort estimates — that's a separate concern from defining the slices.
+
+---
+
+## Quality Checklist
+
+- [ ] Every slice contains exactly one COMMAND (state-change), one READMODEL (state-view), or one AUTOMATION — never a COMMAND and a READMODEL together
+- [ ] Slice name matches the command/read model/automation title exactly
+- [ ] No slice was created for an element that already has one
+- [ ] Dependencies are expressed as events only, never as direct slice-to-slice calls or shared state
+
+---
+
+## Reference Documentation
+
+- **[patterns.md](references/patterns.md)** — naming, boundaries, cross-slice communication patterns
+- **[examples.md](references/examples.md)** — worked example of deriving slices from a timeline