@eventmodelers/cli 1.0.10 → 1.0.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventmodelers/cli",
-  "version": "1.0.10",
+  "version": "1.0.11",
   "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

@@ -48,6 +48,7 @@ Server name: `eventmodelers`. Every tool takes `boardId` explicitly; none need `
 | `get_slice_data` | `boardId`, `contextName?`, `contextId?`, `sliceId?` | Full element graph for slices in a context | §8 `GET /slicedata` |
 | `get_spec_info` | `boardId`, `timelineId` | EVENT/COMMAND/READMODEL nodes valid in GWT steps | §6 `GET .../spec-info` |
 | `add_scenario` | `boardId`, `timelineId`, `columnId`, `scenarios[]` | Append GWT scenario(s) to a column's spec node | §6 `POST .../scenarios` |
+| `add_storyline` | `boardId`, `timelineId`, `columnId`, `storylines[]` | **Experimental — only use when explicitly asked for a storyline/walkthrough.** Append storyline(s) (ordered, branchable beats over existing elements) to a column's spec node | §6 `POST .../storylines` |
 | `set_connection` | `boardId`, `source`, `target`, `action` (`'connect'\|'remove'`) | Add or remove a type-checked directed edge | — (via `edges` on §3 events) |
 | `auto_connect_node` | `boardId`, `nodeId` | Re-run auto-connect for a node | §3 `POST .../nodes/:nodeId/auto-connect` |
 | `add_comment` | `boardId`, `nodeId`, `text`, `type?` (`'COMMENT'\|'TASK'\|'QUESTION'`), `author?` | Add a comment — `QUESTION` flags gaps/edge cases during review | — (via comment events) |
@@ -523,6 +524,48 @@ Get valid elements for a specific slice.
 
 ---
 
+### Storylines (experimental)
+
+> **Only create a storyline when the user's request explicitly asks for one** — the word
+> "storyline", "walkthrough", or "narrative" (or equivalent) must appear in what they asked for.
+> Otherwise keep creating normal GWT scenarios via `add_scenario`/`POST .../scenarios` as before.
+
+An ordered, branchable walkthrough of existing board elements ("beats"), stored alongside GWT
+scenarios on the same SCENARIO spec node, in a sibling `meta.storylines` collection.
+
+### POST `/api/org/:orgId/boards/:boardId/timelines/:timelineId/columns/:columnId/storylines`
+Append one or more storylines to a column's spec node. The spec node is auto-created if missing
+(shared with scenarios).
+
+**Request body**: a single storyline object or an array:
+```typescript
+{
+  id: string
+  title: string          // must be unique within the spec node
+  description?: string
+  layout?: 'horizontal' | 'vertical'
+  beats: Array<{
+    instanceId: string   // unique per beat, even when refId repeats
+    refId: string        // board node id — must belong to the same timeline
+    type?: string
+    title?: string
+    isError?: boolean    // marks an alternate/error branch off the previous beat
+    fields?: unknown[]
+    expectEmptyList?: boolean
+    exampleMode?: string
+    examples?: unknown[]
+  }>
+}
+```
+
+**Response**:
+- `201` — `{ specNodeId, storylines, added, isNewNode }`
+- `400` — validation error
+- `404` — timeline, column, or referenced node not found
+- `409` — duplicate storyline title
+
+---
+
 ## 7. Config Import
 
 **File**: `src/slices/change/config-import/routes.ts`

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-elaborating-scenarios/SKILL.md

@@ -13,6 +13,61 @@ allowed-tools:
 
 Prefer `mcp__eventmodelers__*` tools when available (registered by the `connect` skill) — the curl blocks below are the fallback for sessions without MCP connected.
 
+## Storylines — an On-Demand Alternative to GWT Scenarios (Experimental)
+
+**By default, this skill always produces GWT scenarios.** Storylines are a separate, experimental
+artifact — only build one when the user's request explicitly asks for a "storyline", "walkthrough",
+or "narrative". Never generate a storyline as a side effect of ordinary scenario elaboration.
+
+A GWT scenario asserts one isolated transition: a single precondition, a single action, a single
+resulting outcome. A storyline instead narrates one specific use case as an ordered sequence of
+**beats**, where the *same* element (usually a read model) is walked through multiple states across
+one flow — something no single GWT scenario can express, since GWT only ever asserts one
+before/after pair at a time.
+
+**Example** — a customer-activation walkthrough of a Todos read model:
+1. **Beat 1** — the Todos read model, starting empty.
+2. **Beat 2** — after a `CustomerRegistered` event, the same Todos read model now shows one entry
+   (an "activate your account" todo).
+3. **Beat 3** — after a `CustomerActivated` event, the same Todos read model is empty again (the
+   todo was completed and removed).
+
+Three separate GWT scenarios could each assert one of those transitions in isolation, but a
+storyline threads all three together as one narrated walkthrough of the read model's lifecycle —
+useful for a stakeholder-facing walkthrough of a use case, not for exhaustive GWT coverage. Keep
+producing ordinary Given/When/Then scenarios for everything else.
+
+### Storyline data shape
+
+```json
+{
+  "id": "<uuid>",
+  "title": "Customer activation walkthrough",
+  "description": "Optional narrative summary",
+  "layout": "horizontal",
+  "beats": [
+    { "instanceId": "<uuid>", "refId": "<readmodel-node-id>", "type": "READMODEL", "title": "Todos", "exampleMode": "list", "expectEmptyList": true, "examples": [] },
+    { "instanceId": "<uuid>", "refId": "<event-node-id>", "type": "EVENT", "title": "CustomerRegistered" },
+    { "instanceId": "<uuid>", "refId": "<readmodel-node-id>", "type": "READMODEL", "title": "Todos", "exampleMode": "list", "examples": [{"task": "Activate your account"}] },
+    { "instanceId": "<uuid>", "refId": "<event-node-id-2>", "type": "EVENT", "title": "CustomerActivated" },
+    { "instanceId": "<uuid>", "refId": "<readmodel-node-id>", "type": "READMODEL", "title": "Todos", "exampleMode": "list", "expectEmptyList": true, "examples": [] }
+  ]
+}
+```
+
+- `layout`: `"horizontal"` or `"vertical"` — how the beats are laid out in the storyline editor.
+- Each beat has an `instanceId` (unique per beat, even when the same `refId` repeats — this is what
+  lets the *same* element, like the Todos read model above, appear multiple times across the
+  walkthrough, once per state) and a `refId` (the board node this beat walks through — any element
+  type, not just EVENT/COMMAND/READMODEL — e.g. a SCREEN beat to show the resulting UI).
+- `isError` marks a beat as an alternate/error branch off the previous beat.
+- `fields`, `expectEmptyList`, `exampleMode`, `examples` mirror the same fields GWT scenario steps
+  use, letting a beat show concrete example data the same way a "then" readmodel step does.
+
+Post storylines via `POST .../timelines/:tl/columns/:col/storylines` (see `learn-eventmodelers-api`
+for the full endpoint contract) — the same auto-create-if-missing SCENARIO spec node scenarios use,
+in a sibling `meta.storylines` collection.
+
 ## Interview Phase (Optional)
 
 **When to Interview**: Skip if the user has already specified: scenario coverage depth (happy path + validation + state violations), known edge cases to include, and stakeholders available for review. Interview when coverage goals are unclear or edge cases haven't been identified.