@eventmodelers/cli 1.0.11 → 1.0.13

package/README.md

@@ -312,13 +312,16 @@ npx @eventmodelers/cli listen --port 4000            # same, on a different port
 ```bash
 npx @eventmodelers/cli re-init                      # refresh the installed build kit (.build-kit/) + its skills
 npx @eventmodelers/cli re-init --modeling            # refresh the modeling kit (.agent-modeling-kit/) + its skills
+npx @eventmodelers/cli re-init --stack supabase      # override which stack to refresh from (manifest missing/stale, or switching stacks)
 ```
 
 `re-init` re-runs `init` against whichever stack `install-manifest.json` says was installed (no need to pass `--stack` again), but skips step 2 of `init` entirely — the root project scaffold (`package.json`, `src/`, `server.ts`, `docker-compose.yml`, etc.) and the root `CLAUDE.md` router are never touched. Use it after upgrading the CLI to pick up fixes to `ralph.js`/`ralph.sh`/skills without re-scaffolding a project you've since built on top of.
 
+Pass `--stack <name>` to override the stack instead of relying on the manifest — useful if the manifest is missing/stale, or you want to point a `.build-kit` install at a different built-in stack's templates. It's mutually exclusive with `--modeling`.
+
 Credentials are left alone unless you pass `--force` — same rule `init` already follows when everything required is already configured. `--global` defaults to however skills were originally installed; pass it explicitly to move them.
 
-If the kit dir predates install-manifest.json tracking, or was installed via `init --git <url>` (a community/custom stack, not one of the built-in `STACKS` keys), `re-init` can't tell what to re-copy and tells you to re-run the original `init` command by hand instead.
+If the kit dir predates install-manifest.json tracking, or was installed via `init --git <url>` (a community/custom stack, not one of the built-in `STACKS` keys), and you don't pass `--stack` yourself, `re-init` can't tell what to re-copy and tells you to re-run the original `init` command by hand instead.
 
 ### Uninstall
 

package/cli.js

@@ -1635,12 +1635,23 @@ credentialFlags(program
   .command('re-init')
   .description('Refresh an already-installed kit from the current CLI version — re-copies skills and the kit dir (.build-kit or .agent-modeling-kit) so you pick up script/skill updates after upgrading. Unlike `init`, never touches the project root scaffold or the root CLAUDE.md router, and leaves existing credentials alone unless --force is passed.')
   .option('--modeling', 'Refresh the modeling kit (.agent-modeling-kit) instead of a build kit')
+  .option('--stack <name>', `Override which stack to refresh from (${Object.keys(REINITIABLE_STACKS).join(', ')}) instead of the one recorded in install-manifest.json — use this when the manifest is missing/stale, or to switch a .build-kit install to a different stack`)
   .option('--global', 'Re-install skills into ~/.claude/skills/ instead of the project — defaults to however they were originally installed')
   .option('-f, --force', 'Re-prompt for credentials even if a config already has everything required — overwrites the existing config.json'))
   .action(async (opts, command) => {
     const globalOpts = command.optsWithGlobals();
     const targetDir = process.cwd();
 
+    if (opts.modeling && opts.stack) {
+      console.error('❌ --modeling and --stack are mutually exclusive — pick one.');
+      process.exit(1);
+    }
+
+    if (opts.stack && !REINITIABLE_STACKS[opts.stack]) {
+      console.error(`❌ Unknown stack "${opts.stack}". Available: ${Object.keys(REINITIABLE_STACKS).join(', ')}`);
+      process.exit(1);
+    }
+
     const kitDirName = opts.modeling ? MODELING_KIT.kitDirName : STACKS.node.kitDirName;
     const kitDir = join(targetDir, kitDirName);
 
@@ -1650,12 +1661,12 @@ credentialFlags(program
     }
 
     const manifest = readJsonSafe(join(kitDir, '.eventmodelers', 'install-manifest.json'));
-    const stackKey = opts.modeling ? MODELING_KIT.key : manifest.stack;
+    const stackKey = opts.modeling ? MODELING_KIT.key : (opts.stack || manifest.stack);
     const stackCfg = stackKey ? REINITIABLE_STACKS[stackKey] : null;
 
     if (!stackCfg) {
       console.error(`❌ Can't tell which stack ${relative(targetDir, kitDir)} was installed from (${manifest.stack ? `"${manifest.stack}" isn't one re-init recognizes — likely a --git community stack` : 'its install manifest predates this tracking, or is missing'}).`);
-      console.error('   Re-run the original `init --git <url> --stack <name>` command by hand instead.');
+      console.error('   Pass --stack <name> explicitly, or re-run the original `init --git <url> --stack <name>` command by hand instead.');
       process.exit(1);
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventmodelers/cli",
-  "version": "1.0.11",
+  "version": "1.0.13",
   "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/stacks/axon/templates/.claude/skills/build-automation/SKILL.md

@@ -55,6 +55,9 @@ If the Event Modeling artifact includes slice details with `## Scenarios (GWTs)`
 test cases. GWT format for automations: `Given (events) → Then (command | NOTHING)`. Events in
 Given include read-model-building events first, trigger event last.
 
+`slice.json` may also carry an optional `storylines[]` array — see the "Storyline-Derived Tests"
+section under Step 5 for how a trigger-event beat in one of these can add a supplementary test.
+
 If the slice details contain `## Implementation Guidelines`, **follow them**.
 
 ### Stateless vs With Read Model Decision
@@ -387,6 +390,25 @@ class {AutomationName}ProcessorTest {
 | Command in Then | `verify(commandDispatcher).send(eq(expectedCommand), any())` |
 | NOTHING in Then | `verifyNoInteractions(commandDispatcher)` |
 
+### Storyline-Derived Tests (Optional)
+
+`slice.json` may also carry a `storylines[]` array — narrated walkthroughs with an ordered
+`elements[]` "beats" sequence (EVENT/COMMAND/READMODEL/...). This is a secondary, supplementary
+source; `specifications[]` above stays the primary and default source of test cases. Most slices
+have no `storylines[]` — skip silently when there's nothing relevant.
+
+A storyline embedded in this slice's slice.json already belongs entirely to this slice — no need
+to match beats against `events[]`/`commands[]` by id/title. Find a beat whose `type` is `EVENT`
+immediately followed by a `COMMAND` beat. That pair is a ready-made test: `given` = the cumulative
+preceding `EVENT` beats (setup events) through the trigger beat, `then` =
+`verify(commandDispatcher).send(eq(...), any())` built from the command beat's fields — same shape
+as the "Mapping GWT Scenarios to Tests" row above, just sourced from the storyline instead of
+`specifications[]`.
+
+If the beat following the trigger event isn't a COMMAND this automation dispatches (e.g. it's a
+READMODEL or SCREEN beat), don't force a test — leave it undocumented rather
+than fabricating an assertion.
+
 ## References
 
 - [Stateless Automation Example](references/automation-test-example.md) — Complete Java test example
@@ -403,5 +425,6 @@ Before marking this slice as `Done`, verify the implementation against slice.jso
 - [ ] The command dispatched matches the target command defined in slice.json
 - [ ] All fields mapped from trigger event to command come from the event fields defined in slice.json — no invented mappings
 - [ ] Every GWT scenario in `specifications[]` maps to a test case in the test class
+- [ ] If `storylines[]` is present: every trigger-EVENT→target-COMMAND beat pair for this automation has a storyline test — or was deliberately skipped as untraceable
 - [ ] No filtering conditions were invented — all conditions come from slice.json `description` or `comments`
 - [ ] No field names were assumed or guessed — if a field is not in slice.json, it is not in the code

package/stacks/axon/templates/.claude/skills/build-state-change/SKILL.md

@@ -30,6 +30,8 @@ Read `.build-kit/.slices/{context}/{slicename}/slice.json`. Extract, and use **o
 - `specifications[]` (GWT scenarios) → one test method per scenario
 - Which command field(s) have `idAttribute: true` — these carry `@TargetEntityId` (see Step 1) and the
   matching event field(s) carry `@EventTag`
+- `storylines[]` (optional, may be absent) → narrated walkthroughs with ordered `elements[]` "beats";
+  see Step 7b for how a COMMAND beat in one of these can add a supplementary test
 
 Never invent a field, business rule, or event that isn't in slice.json.
 
@@ -384,6 +386,36 @@ Fluent API cheat sheet and known gotchas (wrong `EventCriteria`/`Tag` package, a
 was renamed between AF5 patch versions, `Customization.disableAxonServer()` not existing in 5.1.1):
 see [references/axon-test-fixture-patterns.md](references/axon-test-fixture-patterns.md).
 
+## Step 7b: Storyline-Derived Tests (Optional)
+
+`slice.json` may carry a `storylines[]` array alongside `specifications[]` — narrated walkthroughs
+where an ordered sequence of `elements[]` "beats" (EVENT/COMMAND/READMODEL/...) shows one use case
+end to end. This is a secondary, supplementary source — `specifications[]` (Step 7) stays the
+primary and default source of test methods. Most slices have no `storylines[]`; skip this step
+silently when there's nothing relevant.
+
+A storyline embedded in this slice's slice.json already belongs entirely to this slice — no need
+to match beats against `commands[]` by id/title. Find beats whose `type` is `COMMAND`. For each such
+beat, the storyline gives you a ready-made `AxonTestFixture` test: `given` =
+the cumulative ordered `EVENT` beats preceding it in the storyline, `when` = the command built from
+the beat's `fields`, `then` = the `EVENT` beat(s) immediately following it in the storyline.
+
+```java
+@Test
+@DisplayName("Storyline: {storyline.title} — {commandBeat.title}")
+void storylineBeat() {
+    fixture.given().event(new {PrecedingEventName}(/* fields from earlier beats */))
+           .when().command(new {SliceName}Command(/* fields from the command beat */))
+           .then().success()
+           .events(new {EventName}(/* fields from the following event beat */));
+}
+```
+
+Do **not** try to also assert read-model state in this same test — that half (the following
+EVENT→READMODEL beats) belongs to `build-state-view`'s own storyline step, since this fixture never
+touches a projector. If the beat immediately after the command isn't an EVENT, don't force a test —
+leave it undocumented rather than fabricating an assertion.
+
 ## Final Verification
 
 Before considering the slice done:
@@ -391,6 +423,7 @@ Before considering the slice done:
 - [ ] Every field in slice.json's `commands[]` is in the Command record — no invented fields, none missing
 - [ ] Every field in slice.json's `events[]` is in the Event record — no invented fields, none missing
 - [ ] Every `specifications[]` scenario has a corresponding test method
+- [ ] If `storylines[]` is present: every COMMAND beat for this slice's command has a storyline test — or was deliberately skipped as untraceable
 - [ ] No business rule exists in the handler that isn't traceable to slice.json's `description`/`comments`
 - [ ] `mvn compile -q`, then run the slice's own tests only
 - [ ] If checks pass, commit with `feat: {Slice Name}` and set slice status to `Done`

package/stacks/axon/templates/.claude/skills/build-state-view/SKILL.md

@@ -204,6 +204,48 @@ Do not design your own test cases unless specifically instructed to do so.
 | Event in Given | call `projector.on(event)` |
 | Information in Then | `assertThat(result.items()).containsExactlyInAnyOrder(...)` |
 
+## Step 4b: Storyline-Derived Tests (Optional)
+
+`slice.json` may also carry a `storylines[]` array — narrated walkthroughs where the *same* read
+model appears as multiple ordered "beats" across one flow (see `elements[]` on each storyline).
+This is a secondary, supplementary source: `specifications[]` (Step 4) remains the primary and
+default source of test cases. Most slices have no `storylines[]` — skip this step silently when
+there's nothing relevant.
+
+A storyline embedded in this slice's slice.json already belongs entirely to this slice — no need
+to match beats against `readmodels[]` by id/title. For each storyline, find beats whose `type` is
+`READMODEL`. Two such beats **adjacent with only `EVENT` beat(s) between them** describe one clean,
+isolable projection test:
+
+- events = the cumulative ordered `EVENT` beats from the start of the storyline through the
+  intervening event(s)
+- expected result = the later `READMODEL` beat's `fields`/`examples`/`expectEmptyList`
+
+Write these as ordinary `@Test` methods (Step 5's `projector.on(event)` / `projector.handle(query)`
+pattern applies unchanged), but keep them in a clearly separate `@Nested` class named after the
+storyline's title, so they never get confused with the exhaustive `specifications[]` suite:
+
+```java
+@Nested
+@DisplayName("Storyline: {storyline.title}")
+class StorylineTests {
+    @Test
+    @DisplayName("after {EventName}, read model shows {expected state}")
+    void beatTransition() {
+        projector.on(new {EventName}(/* fields from the intervening beat(s) */));
+
+        var result = projector.handle(new Get{SliceName}(/* filter */));
+
+        assertThat(result.items()).containsExactly(/* expected shape from the later beat */);
+    }
+}
+```
+
+If a beat between two read-model states is a `COMMAND` rather than an `EVENT`, that half belongs
+to `build-state-change` (its own command-handler test), not here — only project the `EVENT`→
+`READMODEL` half. If a storyline segment involves a `SCREEN`/other untraceable beat, don't force a
+test — leave it undocumented in code rather than fabricating an assertion.
+
 ## Step 5: Implement the Slice Test
 
 Pure unit tests — instantiate the projector directly, no Spring context needed.
@@ -278,5 +320,6 @@ Before marking this slice as `Done`, verify the implementation against slice.jso
 - [ ] Every field in the read model / query result definition in slice.json has a field in `{SliceName}Summary` — no invented fields
 - [ ] Every event type in `events[]` has an `@EventHandler` in the projector — no events missed or assumed
 - [ ] Every GWT scenario in `specifications[]` maps to a test case in `{SliceName}ProjectorTest`
+- [ ] If `storylines[]` is present: every adjacent READMODEL↔READMODEL beat pair for this slice's read model (with only EVENT beats between) has a `@Nested` storyline test — or was deliberately skipped as untraceable
 - [ ] No extra query parameters or filter logic were added beyond what slice.json defines
 - [ ] No field names were assumed or guessed — if a field is not in slice.json, it is not in the code

package/stacks/cratis-csharp/templates/.claude/skills/build-automation/SKILL.md

@@ -36,6 +36,7 @@ slice, which services are available for side effects, and how existing translati
 | **Target command** | For translation: which command to `Execute`, and how its fields map from the event |
 | **Idempotency** | The reaction must be safe to run more than once (replay/recovery) |
 | **Specifications** | Each scenario → an executable spec |
+| **Storylines** (optional) | `storylines[]` — ordered walkthrough "beats"; an event-triggering-this-reactor transition is a supplementary spec source, see Step 4a |
 
 If a command field has no source in the trigger event or an injected service, do not invent it.
 
@@ -86,6 +87,26 @@ command); for automations, assert the side-effect service was invoked. Cover ide
 slice calls for it. One spec per scenario. Run `dotnet test --filter "FullyQualifiedName~<SliceName>"`.
 See [references/patterns.md](references/patterns.md).
 
+## Step 4a — Storyline-derived specs (optional)
+
+If `storylines[]` is non-empty — a storyline embedded in this slice's slice.json already belongs
+entirely to this slice, no need to match beats against `events[]`/`commands[]` by id/title — look
+for an `EVENT → (COMMAND | EVENT)` transition: a trigger event beat, followed by the command it
+triggers (translation) or a further event/side-effect signal (automation).
+
+- **Establish** — append the trigger event (and any preceding events in the storyline needed to
+  reach it).
+- **Because** — invoke/replay the reactor.
+- **should_\*** — for a translation, assert `ICommandPipeline.Execute` was called with the mapped
+  command from the beat's `fields`; for a plain automation, assert the mocked side-effect service
+  was invoked.
+
+If the storyline continues past the triggered command into that command's own event, or into a
+read model, those halves belong to **build-state-change** / **build-state-view** respectively — a
+reactor spec only covers the event-in → reaction-out step.
+
+Skip silently when the beat sequence can't be isolated (e.g. no traceable trigger event).
+
 ## Final verification — does the implementation match `slice.json`?
 
 - [ ] The reactor observes exactly the trigger event(s) named in the slice.
@@ -93,6 +114,8 @@ See [references/patterns.md](references/patterns.md).
 - [ ] No new events written via `IEventLog` — only via `ICommandPipeline`.
 - [ ] The reaction is idempotent; the reactor is stateless.
 - [ ] Every scenario → an executable spec; `dotnet build` clean; specs pass.
+- [ ] A `storylines[]` transition triggering this reactor has a spec, or was deliberately skipped
+      (not silently ignored).
 
 ## References
 - [references/patterns.md](references/patterns.md) — full reactor/translation code and reactor specs.

package/stacks/cratis-csharp/templates/.claude/skills/build-state-change/SKILL.md

@@ -49,6 +49,7 @@ Extract, regardless of input format:
 | **Business rules** | Preconditions, invariants, idempotency — from `description` / `comments` only |
 | **State needed for rules** | Which read model must be inspected (DCB) to evaluate a rule |
 | **Specifications** | Each GWT / scenario maps 1:1 to an executable spec |
+| **Storylines** (optional) | `storylines[]` — ordered walkthrough "beats"; a `COMMAND → EVENT` transition in one is a supplementary spec source, see Step 5a |
 
 **If a field is not in `slice.json`, it does not go in the code.** If requirements are unclear, ask
 the user before proceeding.
@@ -142,6 +143,31 @@ Chronicle integration specs use `Given<context>` + `ChronicleOutOfProcessFixture
 
 Run `dotnet test --filter "FullyQualifiedName~<SliceName>"`. Fix all failures.
 
+## Step 5a — Storyline-derived specs (optional)
+
+If `storylines[]` is non-empty — a storyline embedded in this slice's slice.json already belongs
+entirely to this slice, no need to match beats against `commands[]` by id/title — look for a
+`COMMAND → EVENT` transition: a `type: "COMMAND"` beat, followed by its resulting event beat(s) —
+possibly followed by a READMODEL beat after that.
+
+- **Establish** — append every event from the storyline's start up to (not including) the command
+  beat.
+- **Because** — `Handle()` the command, built from the beat's `fields`.
+- **should_\*** — assert the expected event(s) (the beat(s) immediately following the command).
+
+Only the `COMMAND → EVENT` half lives here — if the storyline continues `EVENT → READMODEL`, that
+half is a separate spec in **build-state-view** (its Step 4a). Don't chase a single spec across
+both a command dispatch and a read-model assertion unless the project already has an established
+pattern doing that — Chronicle integration specs assert appended events, not read-model state,
+and vice versa for projection specs.
+
+Place these alongside the `specifications[]`-derived specs but in their own
+`and_<storyline-title>.cs` file, so a reader can tell at a glance which specs are exhaustive
+coverage and which are one narrated walkthrough.
+
+Skip silently (no spec) when the transition isn't isolable — e.g. the command beat has no
+traceable preceding events.
+
 ## Step 6 — Frontend (only if the command is UI-triggered)
 
 After `dotnet build` generated the proxy (co-located next to the `.cs`), add
@@ -155,6 +181,8 @@ page. See the shared conventions doc's React section and [references/patterns.md
 - [ ] Every `events[]` entry → an `[EventType]` record; names match exactly; fields match.
 - [ ] Every specification / GWT scenario → an executable spec.
 - [ ] No business rule in `Handle()` that is absent from the slice `description` / `comments`.
+- [ ] A `storylines[]` `COMMAND → EVENT` transition for this command has a spec, or was
+      deliberately skipped (not silently ignored).
 - [ ] `dotnet build` is clean (0 warnings / 0 errors); slice specs pass.
 
 ## References

package/stacks/cratis-csharp/templates/.claude/skills/build-state-view/SKILL.md

@@ -36,6 +36,7 @@ state-change skill's Step 0 for the resolve endpoint).
 | **Source events** | Which events feed each field (projections **join events, never read models**) |
 | **Queries** | The queries to expose; whether each is snapshot or real-time (observable) |
 | **Specifications** | Each scenario → an executable spec proving the projection result |
+| **Storylines** (optional) | `storylines[]` — ordered walkthrough "beats"; a read-model chain in one is a supplementary spec source, see Step 4a |
 
 If a field has no source event in `slice.json`, do not invent one. One read model per use case —
 never reuse a model across slices.
@@ -100,6 +101,32 @@ Write specs proving the projection/reducer produces the expected read model from
 one spec per scenario in `slice.json`. Run `dotnet test --filter "FullyQualifiedName~<SliceName>"`.
 See [references/patterns.md](references/patterns.md).
 
+## Step 4a — Storyline-derived specs (optional)
+
+If the slice's `storylines[]` array (in `slice.json`, alongside `specifications[]`) is non-empty —
+a storyline embedded in this slice's slice.json already belongs entirely to this slice, no need to
+match beats against `readmodels[]` by id/title — look for a **read-model chain**: two beats of
+`type: "READMODEL"`, with only `EVENT` beat(s) between them. That's a self-contained projection
+spec:
+
+- **Establish** — append every event from the storyline's start up through the intervening
+  event(s), in order.
+- **Because** — run the projection.
+- **should_\*** — assert against the *later* beat's `fields`/`examples`/`expectEmptyList`.
+
+Put these in their own `for_<ReadModel>/when_<storyline-title>/` folder (not `when_<behavior>/`),
+so they're never confused with the exhaustive `specifications[]` suite — a storyline is a
+narrated walkthrough, not exhaustive coverage.
+
+If the storyline's transition into this read model is instead `COMMAND → EVENT → READMODEL`, only
+the `EVENT → READMODEL` half belongs here — the `COMMAND → EVENT` half is a separate spec in
+**build-state-change** (see its Step 5a). Don't try to assert read-model state from a dispatched
+command in one spec unless the project already has an established pattern for that.
+
+Skip a beat sequence entirely — no spec, no placeholder — if it can't be isolated (e.g. a SCREEN
+beat with no traceable event). A storyline is source material for tests, not a mandate to write
+one for every beat.
+
 ## Step 5 — Frontend
 
 Add `<Module>/<Feature>/<Slice>/<Component>.tsx` importing the co-located generated query proxy from
@@ -113,6 +140,8 @@ feature's composition page; add routing in `App.tsx` if it's a new page.
 - [ ] Every source event used exists; projections map from **events**, never read models.
 - [ ] Every query in the slice is exposed as a static method; observable where the slice wants live data.
 - [ ] Every scenario → an executable spec.
+- [ ] A `storylines[]` read-model chain for this read model has a spec, or was deliberately
+      skipped (not silently ignored).
 - [ ] `dotnet build` clean; specs pass.
 
 ## References

package/stacks/node/templates/.claude/skills/build-automation/SKILL.md

@@ -43,6 +43,7 @@ From the slice definition, extract:
   - `processorId` — unique kebab-case identifier
 - **commands[]** — command data fields
 - **events[]** — events emitted by the command
+- **storylines[]** (optional) — present only when the board author built an explicit walkthrough for this flow; most slices have none. See the note at the end of Step 2.
 > **Comments & description**: Each element (commands, events, readmodels, processors, screens, tables) carries a `comments: string[]` array (board comments on that node) and a `description` field. The slice itself also has `comments: string[]`. Use these as implementation hints — pass them as code comments, documentation, or validation logic where they add value. When done, resolve each used comment: `POST <BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/nodes/<nodeId>/comments/<commentId>/resolve` (get comment IDs first via GET on the same path without the last two segments).
 
 
@@ -58,6 +59,10 @@ Follow the **build-state-change** skill to create:
 
 Refer to the build-state-change skill for the full command handler structure.
 
+### Storyline-derived tests
+
+If `storylines[]` includes a beat sequence running through this automation's trigger event → this slice's command, the command-handler test for that segment is already covered by build-state-change's own "Storyline-derived tests" step — it runs as part of following that skill above. This skill has no separate reactor-test format: the processor's event-to-command field mapping is exercised only indirectly, through that command-handler test, never by a dedicated `processor.test.ts`.
+
 ---
 
 ## Step 3 — Ensure the trigger event type exists
@@ -263,4 +268,5 @@ src/common/
 - [ ] Every processor in `processors[]` has a corresponding `processor.ts` implementation
 - [ ] Command data fields map exclusively from fields available on the trigger event per slice.json — no invented mappings
 - [ ] No filtering conditions were invented — all conditions come from slice.json `description` or `comments`
-- [ ] No field names were assumed or guessed — if a field is not in slice.json, it is not in the code
+- [ ] No field names were assumed or guessed — if a field is not in slice.json, it is not in the code
+- [ ] If `storylines[]` is present, its command-handler segment was covered via build-state-change's storyline-derived tests (no separate reactor test needed)

package/stacks/node/templates/.claude/skills/build-state-change/SKILL.md

@@ -26,6 +26,7 @@ From the slice definition, extract:
 - **commands[]** — list of commands with their data fields
 - **events[]** — list of events emitted by each command
 - **specifications[]** — test scenarios (given/when/then)
+- **storylines[]** (optional) — present only when the board author built an explicit walkthrough for this flow; most slices have none. See "Storyline-derived tests" under Step 4.
 > **Comments & description**: Each element (commands, events, readmodels, processors, screens, tables) carries a `comments: string[]` array (board comments on that node) and a `description` field. The slice itself also has `comments: string[]`. Use these as implementation hints — pass them as code comments, documentation, or validation logic where they add value. When done, resolve each used comment: `POST <BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/nodes/<nodeId>/comments/<commentId>/resolve` (get comment IDs first via GET on the same path without the last two segments).
 
 
@@ -227,6 +228,16 @@ describe('{SliceName} Specification', () => {
 
 Add one test per specification in the slice.json. If the spec has no precondition events, use `given([])`.
 
+### Storyline-derived tests (optional)
+
+`storylines[]` in slice.json (optional — only present when the board author built an explicit walkthrough) can also supply command-handler tests, in addition to the specifications-derived ones above. A storyline embedded in this slice's slice.json already belongs entirely to this slice — no need to match beats against `commands[]` by id/title. Just scan each storyline's ordered `elements` for a `type: COMMAND` beat, followed by its emitted EVENT beat(s):
+
+- `given` — the cumulative ordered events from the start of the storyline up to (not including) the command beat
+- `when` — the command, built from that beat's `fields`
+- `then` — the following EVENT beat(s)' data
+
+Put these in their own `describe` block named after the storyline (same pattern as build-state-view's Storyline-derived tests section). Don't try to also assert read-model state in this test — a `DeciderSpecification` test only sees emitted events, never a materialized read model; the READMODEL half of the same storyline segment is build-state-view's job, not this skill's.
+
 ---
 
 ## Step 5 — Create `routes.ts`
@@ -341,4 +352,5 @@ Before marking this slice as `Done`, verify the implementation against slice.jso
 - [ ] Every field in each event's data has a corresponding field in the TypeScript event type
 - [ ] Every entry in `specifications[]` maps to a test case in `{SliceName}.test.ts`
 - [ ] No business rules, defaults, or constraints were added that do not appear in slice.json `description` or `comments`
-- [ ] No field names were assumed or guessed — if a field is not in slice.json, it is not in the code
+- [ ] No field names were assumed or guessed — if a field is not in slice.json, it is not in the code
+- [ ] If `storylines[]` is present, a storyline-derived test was added for every COMMAND beat matching this slice's command

package/stacks/node/templates/.claude/skills/build-state-view/SKILL.md

@@ -22,6 +22,7 @@ From the slice definition, extract:
 - **context** — bounded context
 - **events[]** — events this projection handles (its `canHandle` list)
 - **readModel / fields** — the columns of the output table
+- **storylines[]** (optional) — present only when the board author built an explicit walkthrough for this flow; most slices have none. See "Storyline-derived tests" under Step 5.
 > **Comments & description**: Each element (commands, events, readmodels, processors, screens, tables) carries a `comments: string[]` array (board comments on that node) and a `description` field. The slice itself also has `comments: string[]`. Use these as implementation hints — pass them as code comments, documentation, or validation logic where they add value. When done, resolve each used comment: `POST <BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/nodes/<nodeId>/comments/<commentId>/resolve` (get comment IDs first via GET on the same path without the last two segments).
 
 
@@ -324,6 +325,27 @@ describe('{SliceName} Specification', () => {
 
 Write one `it` block per specification in the slice.json. Use `given([events]).when([]).then(assertReadModel)`.
 
+### Storyline-derived tests (optional)
+
+`storylines[]` in slice.json is optional — present only when the board author explicitly built a walkthrough for this flow; most slices have none. When present, mine it for **additional** read-model-chain tests, on top of (never instead of) the specifications-derived tests above.
+
+A storyline is `{ id, title, elements: [...] }`, where `elements` is an ordered list of beats — the same element can repeat to show its state at different points in the flow. A storyline embedded in this slice's slice.json already belongs entirely to this slice — no need to match beats against `readmodels[]` by id/title. Just scan for a pair of adjacent beats that are both `type: READMODEL`, with only EVENT beat(s) between them and no COMMAND beat in that run. That pair is one self-contained projection test:
+
+- `given` — the cumulative ordered events from the start of the storyline through the intervening event beat(s)
+- `then` — assert the read model matches the later READMODEL beat's `fields`/`examples`/`expectEmptyList`, same as a specifications-derived assertion
+
+Put these in their own `describe` block, named after the storyline, so they're never confused with the exhaustive `specifications[]` suite:
+
+```typescript
+describe('{SliceName} Storyline: {storyline.title}', () => {
+    it('spec: {storyline.title} — after {EventA}', async () => {
+        // same given([...]).when([]).then(assertReadModel) shape as above
+    });
+});
+```
+
+Skip a beat pair when a COMMAND beat sits in between (that half belongs to build-state-change's command-handler test, not this one) or when the run includes a SCREEN/AUTOMATION beat with no traceable event — don't fabricate a test for those; a one-line comment noting the storyline segment exists is enough.
+
 ---
 
 ## Step 6 — Create `routes.ts`
@@ -415,4 +437,5 @@ src/common/
 o- [ ] Every field in the read model definition in slice.json has a column in the migration and a field in the TypeScript type — no invented columns
 - [ ] Every event type in `events[]` is listed in the projection's `canHandle` — no assumed events
 - [ ] No extra columns or fields were added beyond what slice.json defines
-- [ ] No field names were assumed or guessed — if a field is not in slice.json, it is not in the code
+- [ ] No field names were assumed or guessed — if a field is not in slice.json, it is not in the code
+- [ ] If `storylines[]` is present, a storyline-derived test was added for every isolable read-model-chain transition (adjacent READMODEL beats with only EVENT beats between them)

package/stacks/supabase/templates/.claude/skills/build-automation/SKILL.md

@@ -43,6 +43,7 @@ From the slice definition, extract:
   - `processorId` — unique kebab-case identifier
 - **commands[]** — command data fields
 - **events[]** — events emitted by the command
+- **storylines[]** (optional) — narrated walkthroughs; see the note in Step 2
 > **Comments & description**: Each element (commands, events, readmodels, processors, screens, tables) carries a `comments: string[]` array (board comments on that node) and a `description` field. The slice itself also has `comments: string[]`. Use these as implementation hints — pass them as code comments, documentation, or validation logic where they add value. When done, resolve each used comment: `POST <BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/nodes/<nodeId>/comments/<commentId>/resolve` (get comment IDs first via GET on the same path without the last two segments).
 
 
@@ -58,6 +59,8 @@ Follow the **build-state-change** skill to create:
 
 Refer to the build-state-change skill for the full command handler structure.
 
+> **Storyline-derived tests**: if slice.json has a `storylines[]` array, build-state-change's Step 4b applies here too — treat the trigger EVENT beat as the "given" and the fired command's resulting EVENT beat(s) as "then", exactly as it would for an ordinary command-change slice. Skip silently if there's nothing relevant.
+
 ---
 
 ## Step 3 — Ensure the trigger event type exists
@@ -260,6 +263,7 @@ src/common/
 - [ ] `schema.migrate()` is called in `loadPostgresEventstore.ts`
 - [ ] No `routes.ts` created (automations are not exposed via HTTP)
 - [ ] Command handler tests cover idempotency (what happens if the command fires twice)
+- [ ] If `storylines[]` is present, storyline-derived command-handler tests were added per build-state-change's Step 4b (or skipped with a documented reason)
 - [ ] Every processor in `processors[]` has a corresponding `processor.ts` implementation
 - [ ] Command data fields map exclusively from fields available on the trigger event per slice.json — no invented mappings
 - [ ] No filtering conditions were invented — all conditions come from slice.json `description` or `comments`

package/stacks/supabase/templates/.claude/skills/build-state-change/SKILL.md

@@ -26,6 +26,7 @@ From the slice definition, extract:
 - **commands[]** — list of commands with their data fields
 - **events[]** — list of events emitted by each command
 - **specifications[]** — test scenarios (given/when/then)
+- **storylines[]** (optional) — narrated walkthroughs that may yield additional command-handler tests; see Step 4b
 > **Comments & description**: Each element (commands, events, readmodels, processors, screens, tables) carries a `comments: string[]` array (board comments on that node) and a `description` field. The slice itself also has `comments: string[]`. Use these as implementation hints — pass them as code comments, documentation, or validation logic where they add value. When done, resolve each used comment: `POST <BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/nodes/<nodeId>/comments/<commentId>/resolve` (get comment IDs first via GET on the same path without the last two segments).
 
 
@@ -229,6 +230,23 @@ Add one test per specification in the slice.json. If the spec has no preconditio
 
 ---
 
+## Step 4b — Storyline-derived tests (optional)
+
+Some slices also have a `storylines[]` array in slice.json — narrated walkthroughs of one use case as an ordered sequence of beats (`elements[]`). Most slices have no storylines; skip this step silently when `storylines[]` is empty or absent.
+
+A storyline embedded in this slice's slice.json already belongs entirely to this slice — no need to match beats against `commands[]` by id/title. For each storyline, find a `type: COMMAND` beat directly followed by its EVENT beat(s). That pair is a command-handler test — the same shape as the specifications-derived tests above:
+- `given` — the cumulative ordered EVENT beats from the start of the storyline up to (but not including) the command beat
+- `when` — the command, built from the beat's `fields`
+- `then` — the event(s) immediately following the command beat, built from their `fields`
+
+Add these alongside the specifications-derived tests in the same `describe` block, or in their own block named after the storyline's `title` if it helps distinguish them.
+
+A storyline walking COMMAND → EVENT → READMODEL is **not** one test here: the READMODEL half belongs to **build-state-view** — `DeciderSpecification` can only assert emitted events, never read-model state.
+
+Skip (do not fabricate) a segment when the command beat has no immediately-following event beat relevant to this slice, or when the beat's fields don't give enough to construct a valid command.
+
+---
+
 ## Step 5 — Create `routes.ts`
 
 File: `src/slices/{context}/{SliceName}/routes.ts`
@@ -340,5 +358,6 @@ Before marking this slice as `Done`, verify the implementation against slice.jso
 - [ ] Every event in `events[]` has a corresponding type in `{Context}Events.ts` — names match exactly
 - [ ] Every field in each event's data has a corresponding field in the TypeScript event type
 - [ ] Every entry in `specifications[]` maps to a test case in `{SliceName}.test.ts`
+- [ ] If `storylines[]` is present, each command-to-event transition relevant to this slice has a corresponding test (or a documented reason it was skipped)
 - [ ] No business rules, defaults, or constraints were added that do not appear in slice.json `description` or `comments`
 - [ ] No field names were assumed or guessed — if a field is not in slice.json, it is not in the code

package/stacks/supabase/templates/.claude/skills/build-state-view/SKILL.md

@@ -22,6 +22,7 @@ From the slice definition, extract:
 - **context** — bounded context
 - **events[]** — events this projection handles (its `canHandle` list)
 - **readModel / fields** — the columns of the output table
+- **storylines[]** (optional) — narrated walkthroughs that may yield additional projection tests; see Step 5b
 > **Comments & description**: Each element (commands, events, readmodels, processors, screens, tables) carries a `comments: string[]` array (board comments on that node) and a `description` field. The slice itself also has `comments: string[]`. Use these as implementation hints — pass them as code comments, documentation, or validation logic where they add value. When done, resolve each used comment: `POST <BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/nodes/<nodeId>/comments/<commentId>/resolve` (get comment IDs first via GET on the same path without the last two segments).
 
 
@@ -306,6 +307,22 @@ Write one `it` block per specification in the slice.json. Use `given([events]).w
 
 ---
 
+## Step 5b — Storyline-derived tests (optional)
+
+Some slices also have a `storylines[]` array in slice.json — narrated walkthroughs where the *same* read model repeats across several beats in one ordered `elements[]` list, showing its state at different points in a single flow. Most slices have no storylines; skip this step silently when `storylines[]` is empty or absent.
+
+A storyline embedded in this slice's slice.json already belongs entirely to this slice — no need to match beats against `readmodels[]` by id/title. For each storyline, scan `elements[]` for pairs of adjacent `type: 'READMODEL'` beats with only EVENT beat(s) in between. Each such pair is a clean, self-contained projection test — the same shape as the specifications-derived tests above:
+- `given` — the cumulative ordered EVENT beats from the start of the storyline through the intervening event(s), not just the two beats either side (earlier events in the same storyline still apply to accumulated state)
+- `then` — assert the read model matches the later beat's shape, using its `fields`/`examples`/`expectEmptyList` exactly like a specifications-derived assertion
+
+Put these in their own `describe` block per storyline, named after the storyline's `title` (e.g. `describe('Storyline: {storyline.title}', ...)`) — never merge them into the `specifications[]` suite; storylines are a supplementary narrative check, not a replacement for scenario coverage.
+
+Skip (do not fabricate) a segment when:
+- a COMMAND beat sits between two read-model beats — that half belongs to **build-state-change** (the command → event transition); only the event → read-model half after it is testable here
+- a beat (e.g. SCREEN) can't be traced to an event affecting the read model
+
+---
+
 ## Step 6 — Create `routes.ts`
 
 File: `src/slices/{context}/{SliceName}/routes.ts`
@@ -390,6 +407,8 @@ src/common/
 - [ ] `finally { await db.destroy() }` present in every `evolve` handler
 - [ ] Tests use `runFlywayMigrations()` to apply the real schema
 - [ ] One test scenario per specification in slice.json
+- [ ] If `storylines[]` is present, each read-model-to-read-model transition relevant to this slice has a corresponding storyline test (or a documented reason it was skipped)
+- [ ] Storyline-derived tests live in their own `describe` block, separate from the specifications suite
 - [ ] Every field in the read model definition in slice.json has a column in the migration and a field in the TypeScript type — no invented columns
 - [ ] Every event type in `events[]` is listed in the projection's `canHandle` — no assumed events
 - [ ] No extra columns or fields were added beyond what slice.json defines