@eventmodelers/cli 1.0.137 → 1.0.139

package/README.md

@@ -23,6 +23,7 @@ npx @eventmodelers/cli init --stack umadb            # UmaDB (Java)
 npx @eventmodelers/cli init --stack kurrent          # Kurrent (Java, KurrentDB)
 npx @eventmodelers/cli init --stack react            # React (frontend, board-polling sync) — TODO-marked, not yet filled in
 npx @eventmodelers/cli init --stack supabase-react   # React + Supabase (frontend, UI-only, realtime sync)
+npx @eventmodelers/cli init --stack classic          # Existing codebase (any language, typically CRUD) — no scaffold
 ```
 
 The installer prompts for your API token, Organization ID, and Board ID from [app.eventmodelers.ai/account](https://app.eventmodelers.ai/account), scaffolds the stack into your project, and writes `.eventmodelers/config.json` with your credentials.
@@ -65,6 +66,15 @@ npx @eventmodelers/cli fetch --context <name>
 
 This writes the current slice/event/command detail for that context to disk and prints a summary — no agent loop, no listener, just a one-shot pull.
 
+**Adding slices to an existing codebase (`classic`):**
+
+```bash
+cd my-existing-app
+npx @eventmodelers/cli init --stack classic
+```
+
+`classic` scaffolds nothing into your project root — it assumes the code is already there, in whatever language and architecture it uses (typically a layered CRUD app, but not necessarily). Before the first slice, the coding agent (Claude, Codex, or any `--agent`) runs `learn-architecture`: it traces one or two existing features end to end and writes `.build-kit/ARCHITECTURE.md` — layout, reference implementations, test style, build/test commands, and how Event Modeling maps onto this code (COMMAND → service method + endpoint, EVENT → the persisted state change, READMODEL → query + DTO, AUTOMATION → the existing listener/consumer/scheduler). The `build-*` skills then implement every slice by copying those reference features, never by introducing a new framework or event store. Review and commit `ARCHITECTURE.md` after the first run — it's the one file that steers every later slice.
+
 **Checking what's installed or which credentials are active:**
 
 ```bash
@@ -93,6 +103,8 @@ your-project/
 
 The six backend stacks (`node`, `supabase`, `axon`, `opencqrs`, `umadb`, `kurrent`) also scaffold a real project skeleton into your project root (`templates/root/`) — source layout, build files, migrations, etc.
 
+`classic` ships no `templates/root/` at all — it installs only `.build-kit/` and the skills into an existing codebase (see "Adding slices to an existing codebase" above).
+
 `react` and `supabase-react` are two more registered stacks (installable the same way). `supabase-react` is real, filled-in content — a Vite + React 19 + TypeScript scaffold that authenticates and issues command POSTs via a Supabase session (`src/lib/api.ts`/`src/lib/supabase.ts`), plus `init-style-guide`/`learn-styleguide` skills so generated UI stays on-brand. It's UI-only: `.build-kit/CLAUDE.md` only routes `STATE_CHANGE`/`STATE_VIEW` slices to `build-state-change`/`build-state-view` — an `AUTOMATION` slice has no UI counterpart and gets flagged via `request-feedback` instead, since it belongs to whichever backend stack is installed alongside this one. It needs no overrides at all and uses `shared/build-kit`'s realtime agent as-is.
 
 `react` (the plain-REST/board-polling variant, no Supabase) is still in the same state as a fresh `init --build-kit` scaffold — CLAUDE.md, the `build-*` skills, and `templates/root/` are all TODO-marked placeholders, not real content, pending an equivalent reference implementation. It overrides `lib/ralph.js` (+ `ralph-claude.js`/`ralph-local-ai.js`/`package.json`/`README.md`) for board-polling sync. Fill in the TODOs (and add a real `templates/root/` scaffold) against an actual project before relying on it.

package/cli.js

@@ -197,6 +197,17 @@ const STACKS = {
     useShared: true,
     needsBoardId: true,
   },
+  // Installs into an existing codebase instead of scaffolding one — it ships no
+  // templates/root, so nothing is spread into the project root. Its learn-architecture
+  // skill analyzes the code once into .build-kit/ARCHITECTURE.md, and the build-* skills
+  // implement each slice the way that codebase already works (typically CRUD).
+  classic: {
+    label: 'Classic — existing codebase (any language, typically CRUD), slices built to match its architecture',
+    kitSubdir: 'build-kit',
+    kitDirName: '.build-kit',
+    useShared: true,
+    needsBoardId: true,
+  },
 };
 
 // Not a stack — no backend scaffold, just skills + the agent loop. Installed via

package/package.json

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

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

@@ -710,10 +710,12 @@ Append Given-When-Then scenario(s) to a column's spec node — the node is creat
 A step given as `{title, type}` is resolved server-side, so the names you already know need **no `get_spec_info`/`get_nodes` call first**. A title matching more than one element is rejected (`SCENARIO_ITEM_AMBIGUOUS`) with the candidates rather than guessed at, and resolution runs before anything is written — a bad name leaves no empty spec node behind.
 
 **Validation rules**:
+- `context`: only READMODELs (the state the command decides against)
 - `given`: only EVENTs from same timeline
 - `when`: max one COMMAND; must be empty when `then` contains a READMODEL (use an inline QUERY item for a state-view)
 - `then`: all EVENTs OR exactly one READMODEL — never mixed
 - All referenced nodes must belong to the same chapter/timeline
+- Each section is checked against the node's real type: a COMMAND lives only in `when`, a READMODEL only in `then`/`context`, an EVENT only in `given`/`then`. A step's `type`, when sent, must match the node (`SCENARIO_ITEM_TYPE_MISMATCH`); when omitted, the node's type is stored on the step
 
 **Response**:
 - `201` — `{ specNodeId, scenarios, added, isNewNode: boolean }`

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

@@ -0,0 +1,94 @@
+---
+name: build-automation
+description: Implements an automation slice (react to a state change, issue a command) inside an existing codebase, using whatever reactive mechanism it already has per .build-kit/ARCHITECTURE.md — listener, after-commit hook, message consumer or scheduled job
+---
+
+# Build Automation Slice
+
+> Before doing anything else, read the slice definition from `.slices/{Context}/{slicename}/slice.json`. This file is the **source of truth** for which trigger drives the automation and what command it fires — never invent fields not defined there.
+
+> Then read `.build-kit/ARCHITECTURE.md` (run `/learn-architecture` if it is missing). Its **AUTOMATION** mapping decides which reactive mechanism this codebase uses.
+
+---
+
+## What an Automation Slice is
+
+An automation reacts to something that happened (a trigger event, or entries showing up in a todo-list read model) and issues a command in response — without a user doing it.
+
+In a CRUD codebase there is usually no event stream to subscribe to. The automation is built with whatever already reacts to state changes there: an in-process domain/application event listener, an after-commit hook, a message consumer, or a scheduled job that queries for pending work. An automation slice is a **state-change slice with a trigger**: build the command first, then wire the trigger.
+
+---
+
+## Step 1 — Read the slice.json
+
+From the slice definition, extract:
+- **sliceName** — the command being fired by the automation
+- **context** — bounded context
+- **processors[]** — the reactions this slice implements: the trigger event (or todo-list read model) and the command each one issues
+- **commands[]** / **events[]** — the command fired and what it records
+- **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 2.
+
+> **Comments & description**: each element carries a `comments: string[]` array (board comments) and a `description` field — use them as implementation hints, and resolve consumed comments via `POST <BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/nodes/<nodeId>/comments/<commentId>/resolve`.
+
+---
+
+## Step 2 — Build the command
+
+Follow `/build-state-change` for this slice's command and events — all of its steps, tests and checks apply. If the command already exists (built by another slice), reuse it; do not duplicate it.
+
+### Storyline-derived tests
+
+If `storylines[]` includes a beat sequence running through this automation's trigger → this slice's command, the command test for that segment is already covered by build-state-change's own "Storyline-derived tests" step.
+
+## Step 3 — Find the trigger point
+
+Locate where the trigger event's state change happens in the code — the **Slice map** in `ARCHITECTURE.md` names the code of the Done slice that produces it. If the map has a Done automation slice, build this one the way that one is built (same mechanism, registration and test style); otherwise pick the mechanism from `ARCHITECTURE.md`:
+
+| Codebase has | Build the automation as |
+|---|---|
+| in-process application/domain events (e.g. Spring `ApplicationEventPublisher`, MediatR notifications, Node `EventEmitter`) | a listener on the existing event for the trigger — or publish a new one from the trigger's service method the same way others are published |
+| transactional outbox / message broker | a consumer on the existing topic/queue, registered like the reference consumer |
+| scheduler / job framework | a scheduled job that queries the todo-list read model (or the trigger's persisted state) for pending items and fires the command per item |
+| none of the above | the least invasive option consistent with the codebase: a direct call from the trigger's service method after it commits, or a scheduled job if the reaction must be decoupled/retried. Record the choice in `progress.txt` and in `ARCHITECTURE.md` so later automations reuse it |
+
+Rules:
+- Map trigger fields → command fields exactly as slice.json defines; no extra fields.
+- The reaction must be **idempotent**: reprocessing the same trigger must not issue the command twice (check the resulting state, a processed-marker, or the todo-list query condition — whatever the codebase already uses).
+- Follow the codebase's transaction boundaries: the command must not run inside a transaction that can still roll back the trigger unless the reference does exactly that.
+- Never add a new messaging/scheduling library just for this slice.
+- **Isolated and deletable**: the listener/consumer/job is its own class in the slice's own place (see *New slices — isolation*). Prefer subscribing to an existing event or querying for pending work over editing the trigger's service method; if a hook in that method is unavoidable (no event mechanism exists), keep it to a single call and list it under `Shared seams`.
+
+## Step 4 — Register it
+
+Register the listener/consumer/job the same way the reference one is (annotation, DI registration, scheduler config, worker entry point). Do not touch application bootstrap beyond what that registration requires.
+
+## Step 5 — Write the tests
+
+Besides the command tests from Step 2, write one test per `specifications[]` entry that exercises the **trigger**: set up the given state, fire the trigger the way it happens in production (publish the event, run the job once, call the consumer), and assert the command's effect — or that nothing happened when the spec expects no reaction. Follow the reference test style.
+
+## Step 6 — Quality gate
+
+Run the build command and the single-test command from `ARCHITECTURE.md` for the tests this slice added or changed. Do not run the full suite.
+
+## Step 7 — Record the slice in the Slice map
+
+Add (or update) this slice's row in the **Slice map** of `ARCHITECTURE.md`, with the trigger and every shared file it touched under `Shared seams`. Commit it with the slice.
+
+## Step 8 — Record the evidence on the board
+
+After the commit, invoke `/record-evidence`: it writes this slice's element → code mapping, field mapping, specification → test mapping, files, seams, assumptions and commit as a markdown note into the slice's column (chapter lane `Implementation`). Only then is the slice set to `Done`.
+
+---
+
+## Checklist
+
+- [ ] The command was built (or reused) via build-state-change, with all its specifications tested
+- [ ] The trigger uses the codebase's existing reactive mechanism, registered like the precedent automation slice (or the reference)
+- [ ] The automation is its own class; any hook into existing code is listed under `Shared seams` in its Slice map row
+- [ ] Trigger → command field mapping matches slice.json exactly
+- [ ] Reprocessing the same trigger does not issue the command twice
+- [ ] Every specification has a passing test
+- [ ] If `storylines[]` is present, its command segment is covered via build-state-change's storyline-derived tests
+- [ ] No new framework, library or architectural style was introduced; any first-time mechanism choice is recorded in `ARCHITECTURE.md`
+- [ ] The evidence note exists in the slice's column on the board (`/record-evidence`)

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

@@ -0,0 +1,114 @@
+---
+name: build-state-change
+description: Implements a state-change slice (command → validated state transition) inside an existing codebase, following the architecture recorded in .build-kit/ARCHITECTURE.md — typically a CRUD service method + endpoint + persistence, not necessarily event-sourced
+---
+
+# Build State Change Slice
+
+> Before doing anything else, read the slice definition from `.slices/{Context}/{slicename}/slice.json`. This file is the **source of truth** for all fields, events, and metadata — never invent fields not defined there.
+
+> Then read `.build-kit/ARCHITECTURE.md` (run `/learn-architecture` if it is missing). It decides **how** the slice is built: which layers, which reference feature to copy, how events map onto persistence, how tests look, and which commands to run.
+
+---
+
+## What a State Change Slice is
+
+A state-change slice accepts a command, checks it against the current state and the business rules in its specifications, and — if it is allowed — records the resulting state transition (the slice's event(s)).
+
+In this codebase that usually means: an entry point (endpoint/handler/action) receives the command's fields, a service method validates them against the current persisted state, and the change is written through the existing persistence layer. Only if `ARCHITECTURE.md` says the codebase is event-based are the events materialized as event objects.
+
+---
+
+## Step 1 — Read the slice.json
+
+From the slice definition, extract:
+- **sliceName** — the slice title (names the command/use case)
+- **context** — the bounded context (maps to the module/package/feature area named in `ARCHITECTURE.md`)
+- **commands[]** — list of commands with their data fields
+- **events[]** — list of events emitted by each command — their fields are the state the command must persist
+- **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 5.
+
+> **Comments & description**: each element carries a `comments: string[]` array (board comments) and a `description` field — use them as implementation hints, and resolve consumed comments via `POST <BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/nodes/<nodeId>/comments/<commentId>/resolve`.
+
+---
+
+## Step 2 — Find the precedent slices
+
+This codebase is usually a legacy system whose event model was built from its code, so most neighbouring slices already exist in the code. Before writing anything, find out how they were built:
+
+1. **Is this slice itself already in the code?** Look it up in the **Slice map** of `ARCHITECTURE.md` and search for the command name, event names, the entity and the key fields (also under their code names from *Code vs. board terms*). If it exists — a slice that reappears as `Planned`, or one the analysis found but never marked `Done` — this skill is a **diff**: update the existing code to match slice.json field by field, add missing specifications, remove fields slice.json no longer has. Never dismiss a mismatch as harmless drift, and don't rebuild it next to the existing code.
+2. **Which existing slices are its neighbours?** From the Slice map and the context's `index.json`, pick the `Done` slices closest to this one — same context, same entity/aggregate, same events (e.g. the slice that produces this slice's `given` events, or another status transition on the same entity), same type. Read their `slice.json` and the code the map lists for them, **side by side**: that is exactly how a COMMAND, its EVENTs and its specifications from this board become code here. If no Done slice is close, fall back to the reference implementation in `ARCHITECTURE.md`.
+3. **What does the slice build on?** Events this slice reads in its `given`/specifications that other Done slices produce are already persisted somewhere — reuse that entity/table, never re-implement or duplicate it.
+
+If a Done slice in this context has no row in the Slice map, run `/learn-architecture slices` first.
+
+## Step 3 — Map the slice the way its precedent is mapped
+
+Take the precedent slice from Step 2 (or the **write** reference implementation from `ARCHITECTURE.md`) and build the same shape for this slice — same layers, naming, validation, error mapping and test style — placed as described in *New slices — isolation* of `ARCHITECTURE.md`:
+
+| From slice.json | Becomes (per `ARCHITECTURE.md`) |
+|---|---|
+| command + its fields | input DTO/request type and the entry point that receives it, with the same validation style as the reference |
+| business rules (from specifications whose `then` is an error, plus `description`/`comments`) | checks in the service/use case, failing the way the codebase fails (exception type, result type, error response) |
+| event(s) + their fields | the persisted state change: entity fields/columns set, rows inserted/updated/deleted. In an event-based codebase: the event types, appended/published the existing way |
+| event that represents a status transition (`...Approved`, `...Cancelled`) | the field/status column update the codebase uses for such transitions |
+
+Rules:
+- **Isolated and deletable**: the slice's code lives in its own files (its own package/folder where the layout allows — see *New slices — isolation*), not as new methods appended to an existing shared service, controller or repository. Shared files are touched only at the seams `ARCHITECTURE.md` names (registration, routing, a new migration), each as one small, recognisable change. No other code may start depending on this slice's internals; it reaches shared state through the existing entity/repository. Removing the slice should mean deleting its files and reverting its seams.
+- Every command field, every event field ends up somewhere concrete — persisted, validated or returned. A field with no destination is a gap: record your assumption.
+- No fields that are not in slice.json. Technical columns the codebase always adds (ids, timestamps, version, audit) are fine if every comparable entity has them.
+- Schema changes go through the codebase's migration mechanism — add a new migration, never edit an existing one.
+- Follow the codebase's transaction, auth and error-mapping conventions exactly as the reference does.
+
+## Step 4 — Expose it
+
+Expose the command the way comparable writes are exposed (REST endpoint, RPC method, message handler, UI/server action, ...), including whatever registration, routing, API documentation or permission config the reference has. If comparable writes are not exposed externally (pure domain service), don't add an entry point.
+
+## Step 5 — Write the tests
+
+Write one executable test per entry in `specifications[]`, in the test style and location of the reference test:
+
+- **given** — each given event becomes pre-existing state: insert the equivalent rows via the codebase's fixtures/builders/repositories, or execute the earlier commands that produce that state if that is how the reference tests set up data. An empty `given` means a clean state.
+- **when** — invoke the command through the same layer the reference tests use (service call, HTTP request, handler).
+- **then** — for events: assert the persisted state (or the published events, in an event-based codebase) carries exactly the event fields and example values; for an error: assert the codebase's failure (exception, error result, status code).
+
+Name each test after the specification title so it can be traced back to the board.
+
+### Storyline-derived tests (optional)
+
+`storylines[]` in slice.json (optional — only present when the board author built an explicit walkthrough) can supply additional tests. 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. Scan each storyline's ordered `elements` for a `type: COMMAND` beat followed by its EVENT beat(s):
+
+- `given` — the cumulative ordered events from the start of the storyline up to (not including) the command beat, set up as state as above
+- `when` — the command, built from that beat's `fields`
+- `then` — the following EVENT beat(s)' data, asserted on the resulting state
+
+Group these separately (own test class/`describe`/region, named after the storyline), on top of — never instead of — the specification tests.
+
+## Step 6 — Quality gate
+
+Run the build command and the single-test command from `ARCHITECTURE.md` for the tests this slice added or changed. Do not run the full suite.
+
+## Step 7 — Record the slice in the Slice map
+
+Add (or update) this slice's row in the **Slice map** of `ARCHITECTURE.md`: entry point, persistence, tests, and every shared file it touched under `Shared seams` — that column is the checklist for deleting the slice later. Commit it with the slice.
+
+## Step 8 — Record the evidence on the board
+
+After the commit, invoke `/record-evidence`: it writes this slice's element → code mapping, field mapping, specification → test mapping, files, seams, assumptions and commit as a markdown note into the slice's column (chapter lane `Implementation`). Only then is the slice set to `Done`.
+
+---
+
+## Final Verification: Does the Implementation Match slice.json?
+
+- [ ] Every command field is received and used (validated, persisted or passed on)
+- [ ] Every event field is persisted (or published) with the expected value
+- [ ] Every specification has exactly one corresponding, passing test
+- [ ] If `storylines[]` is present, a storyline-derived test was added for every COMMAND beat
+- [ ] No business rules, defaults, or constraints were added that do not appear in slice.json `description`, `comments` or specifications
+- [ ] No field names were assumed or guessed — if a field is not in slice.json, it is not in the code
+- [ ] The new code mirrors its precedent slice (or the reference implementation): layout, naming and conventions; no new framework, library or architectural style was introduced
+- [ ] Data produced by existing slices was reused, not duplicated
+- [ ] The slice lives in its own files; shared files were touched only at the seams in `ARCHITECTURE.md`, and its Slice map row lists them
+- [ ] Assumptions are recorded in `progress.txt` and as code comments
+- [ ] The evidence note exists in the slice's column on the board (`/record-evidence`)

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

@@ -0,0 +1,116 @@
+---
+name: build-state-view
+description: Implements a state-view slice (read model served from previously recorded state) inside an existing codebase, following the architecture recorded in .build-kit/ARCHITECTURE.md — typically a query + response DTO + read endpoint over existing tables, not necessarily a projection
+---
+
+# Build State View Slice
+
+> Before doing anything else, read the slice definition from `.slices/{Context}/{slicename}/slice.json`. This file is the **source of truth** for all fields, events, and metadata — never invent fields not defined there.
+
+> Then read `.build-kit/ARCHITECTURE.md` (run `/learn-architecture` if it is missing). It decides **how** the slice is built: which layers, which reference feature to copy, where reads come from, how tests look, and which commands to run.
+
+---
+
+## What a State View Slice is
+
+A state-view slice answers a question with data that earlier state changes recorded: the read model's fields are derived from the events that feed it.
+
+In a CRUD codebase there is usually no projection to maintain — the events were persisted as rows by their state-change slices, so the read model is a **query** over those tables plus a response DTO and a read entry point. A dedicated table, view or projection is only justified when `ARCHITECTURE.md` says the codebase uses them, or the read genuinely can't be answered from existing data.
+
+---
+
+## Step 1 — Read the slice.json
+
+From the slice definition, extract:
+- **sliceName** — the slice title (names the query/read model)
+- **context** — the bounded context (maps to the module/package/feature area named in `ARCHITECTURE.md`)
+- **readmodels[]** / **projections[]** / **queries[]** — the read model(s) this slice serves, with their fields
+- the **events** feeding each read model — they tell you which persisted state the fields come from
+- **specifications[]** — test scenarios (given events → expected read model)
+- **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 6.
+
+> **Comments & description**: each element carries a `comments: string[]` array (board comments) and a `description` field — use them as implementation hints, and resolve consumed comments via `POST <BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/nodes/<nodeId>/comments/<commentId>/resolve`.
+
+---
+
+## Step 2 — Find the precedent slices
+
+This codebase is usually a legacy system whose event model was built from its code, so most neighbouring slices already exist in the code. Before writing anything:
+
+1. **Is this read already in the code?** Look the slice up in the **Slice map** of `ARCHITECTURE.md` and search for the read model name, its fields and the endpoint (also under the code names from *Code vs. board terms*). If it exists, this skill is a **diff** (see Step 3) — don't build a second query next to it.
+2. **Which existing slices are its neighbours?** Pick the closest `Done` slices — the state-change slices that produce this read model's events (they show where the data is persisted), and another state-view slice in the same context or over the same entity (it shows how reads are built here). Read their `slice.json` and the code the map lists for them side by side. If no Done state-view is close, fall back to the read reference implementation in `ARCHITECTURE.md`.
+
+If a Done slice in this context has no row in the Slice map, run `/learn-architecture slices` first.
+
+## Step 3 — Locate the source data
+
+For every read model field, find where the feeding event's data is persisted (the entity/table/column written by that event's state-change slice). Search by event name, entity and field names.
+
+- **Found** → the field is read from there.
+- **Not persisted anywhere** (the state-change slice isn't built yet, or never stored that field) → do not invent a parallel store. Add the missing column/entity the way the reference does (new migration) only if it clearly belongs to this read; otherwise record the gap as an assumption in `progress.txt` and as a code comment.
+
+If the slice reappears as `Planned` and a query for it already exists, treat this skill as a **diff** against slice.json: add missing fields, remove fields slice.json no longer has, add missing specifications.
+
+## Step 4 — Map the slice the way its precedent is mapped
+
+Take the precedent state-view slice from Step 2 (or the **read** reference implementation from `ARCHITECTURE.md`) and build the same shape, with the same naming, placed as described in *New slices — isolation* of `ARCHITECTURE.md` — its own query class/DTO/endpoint files (own package/folder where the layout allows), not new methods appended to a shared repository or controller when a separate class works just as well. Shared files are touched only at the seams `ARCHITECTURE.md` names, and the query reads existing tables without changing them for other readers:
+
+| From slice.json | Becomes (per `ARCHITECTURE.md`) |
+|---|---|
+| read model + its fields | response DTO with exactly these fields |
+| how events shape the read model (list vs. single item, filters, status mapping, latest-wins) | the query: joins, filters, ordering, status derivation — in the codebase's query style (repository method, ORM query, SQL, ...) |
+| key/id fields and how the read is addressed | query parameters / path variables, matching how comparable reads are addressed |
+| list-shaped read models | pagination/sorting the way comparable list endpoints do it — only if they do |
+
+In an event-based codebase (per `ARCHITECTURE.md`), build the projection/read-model updater the existing way instead and register it like the reference does.
+
+## Step 5 — Expose it
+
+Expose the read the way comparable reads are exposed (REST endpoint, RPC, UI loader, ...), including registration, routing, API documentation and permission config, mirroring the reference. If the read is only consumed internally (e.g. by an automation's todo list), a service/repository method is enough.
+
+## Step 6 — Write the tests
+
+Write one executable test per entry in `specifications[]`, in the test style and location of the reference test:
+
+- **given** — the given events become pre-existing state: insert the equivalent rows via the codebase's fixtures/builders/repositories, or run the commands that produce them if that's how the reference tests set up data.
+- **when** — run the query through the same layer the reference tests use.
+- **then** — assert the returned read model matches the expected fields and example values exactly (including an empty result where the spec expects one).
+
+Name each test after the specification title.
+
+### Storyline-derived tests (optional)
+
+`storylines[]` in slice.json is optional — present only when the board author explicitly built a walkthrough for this flow. When present, mine it for **additional** tests, on top of (never instead of) the specification tests.
+
+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. 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 test:
+
+- `given` — the cumulative ordered events from the start of the storyline through the intervening event beat(s), set up as state
+- `then` — the second READMODEL beat's fields
+
+Group these separately, named after the storyline. Skip a beat pair when a COMMAND beat sits in between (that half belongs to build-state-change) or when the run includes a SCREEN/AUTOMATION beat with no traceable event — a one-line comment noting the storyline segment exists is enough.
+
+## Step 7 — Quality gate
+
+Run the build command and the single-test command from `ARCHITECTURE.md` for the tests this slice added or changed. Do not run the full suite.
+
+## Step 8 — Record the slice in the Slice map
+
+Add (or update) this slice's row in the **Slice map** of `ARCHITECTURE.md`, including every shared file it touched under `Shared seams`. Commit it with the slice.
+
+## Step 9 — Record the evidence on the board
+
+After the commit, invoke `/record-evidence`: it writes this slice's element → code mapping, field mapping, specification → test mapping, files, seams, assumptions and commit as a markdown note into the slice's column (chapter lane `Implementation`). Only then is the slice set to `Done`.
+
+---
+
+## Checklist
+
+- [ ] Every read model field is returned, sourced from where its feeding event's data is persisted
+- [ ] No extra fields in the response that are not in slice.json
+- [ ] No parallel data store was invented for data that already exists
+- [ ] Every specification has exactly one corresponding, passing test
+- [ ] If `storylines[]` is present, a storyline-derived test was added for every isolable read-model transition (adjacent READMODEL beats with only EVENT beats between them)
+- [ ] The new code mirrors its precedent slice (or the reference implementation): layout, naming and conventions; no new framework, library or architectural style was introduced
+- [ ] The slice lives in its own files; shared files were touched only at the seams in `ARCHITECTURE.md`, and its Slice map row lists them
+- [ ] Assumptions and data gaps are recorded in `progress.txt` and as code comments
+- [ ] The evidence note exists in the slice's column on the board (`/record-evidence`)

package/stacks/classic/templates/.claude/skills/learn-architecture/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: learn-architecture
+description: Analyzes the existing codebase once and writes .build-kit/ARCHITECTURE.md — layers, feature layout, persistence, how writes/reads/background work are built, test style, build/test commands, and the slice map — which code every existing (Done) slice on the board corresponds to, and the mapping pattern they share. Run before the first slice is built, when ARCHITECTURE.md is missing or stale, or with `slices` when Done slices are missing from the slice map.
+---
+
+# Learn Architecture
+
+The classic build kit implements slices inside a codebase it did not create. Before any slice is built, the agent has to know how *this* codebase builds a feature — otherwise every slice drifts toward a generic pattern. This skill finds that out once and writes it down in `.build-kit/ARCHITECTURE.md`, which every `build-*` skill reads instead of re-exploring.
+
+**The typical situation is a legacy system.** Someone ran a code base analysis (`analyze-code-base`), built the event model from the existing code, and now extends it. Most slices on the board therefore *already exist in the code* — usually in status `Done` — and their elements' `description`s carry code references (`path/to/File.java:57`, `Class#method`, tables, endpoints). Those slices are the most valuable input this skill has: each one is a worked example of how a COMMAND, EVENT, READMODEL or AUTOMATION from *this* board is realized in *this* code. The mapping is learned from them first, and from generic code reading only where no slice covers it.
+
+**Arguments** (optional):
+- `refresh` — re-analyze and rewrite `ARCHITECTURE.md` even if it exists.
+- `slices` — keep everything else, only bring the **Slice map** up to date (Steps 2–3, then only the **Slice map** and *Code vs. board terms* sections in Step 6): add Done slices that are missing from it, re-check rows whose code moved.
+
+If `.build-kit/ARCHITECTURE.md` exists and neither argument was passed: read it, then compare its **Slice map** against the `Done` slices in the local `index.json` files. If every Done slice has a row, return. Otherwise run as `slices`.
+
+---
+
+## Step 1 — Identify the stack
+
+Read the build/dependency files at the project root and one level down (`package.json`, `pom.xml`, `build.gradle*`, `*.csproj`/`*.sln`, `pyproject.toml`, `go.mod`, `Gemfile`, `composer.json`, `Cargo.toml`, ...), plus `README*`, any existing `CLAUDE.md`/`AGENTS.md`/`CONTRIBUTING.md`, `docker-compose*`, and CI config (`.github/workflows/*`, `.gitlab-ci.yml`, ...).
+
+Record: language + version, framework(s), persistence (database, ORM/query layer, migration tool), messaging if any, test framework(s), and the exact commands to build, run all tests, and run a **single** test file/class. Prefer what CI actually runs over what a README claims. Do not guess a command — if one can't be determined, say so in `ARCHITECTURE.md`.
+
+## Step 2 — Collect the existing slices
+
+Make sure the slice files are present (`/load-slice` without arguments refreshes all of them), then read every `.build-kit/.slices/*/index.json`. This is read-only reference work, so it covers **all** contexts, not only the current one.
+
+Every slice with status `Done` is already implemented — treat it as a precedent. Slices in other statuses (`Created`, `Planned`, ...) may also carry code references from the analysis (the code exists, the slice was just never marked Done); include them when their descriptions point at code. Sort each slice by type the way `CLAUDE.md` *Building a Slice* does (state-change / state-view / automation / translation).
+
+For each such slice, read its `slice.json` and collect the code references from:
+- the `description` (and `comments`) of the slice and of every command, event, read model, screen and processor — paths with line numbers, `Class#method`, tables, endpoints, tests, templates;
+- if the board is reachable and the chapter has them: the `Legacy Sources — <Chapter>` note (*Where this flow lives*) and the `Decisions — <column>` notes in the chapter's **Decisions** lane (`get_nodes { boardId, type: "MARKDOWN", projection: "line" }` for the ids, then read only the notes of chapters you need). They map elements to code with exact references and record code-vs-board term differences (`PetType` → *Species*).
+
+A slice without any reference is located by search instead (Step 3).
+
+## Step 3 — Map each existing slice onto its code
+
+For every slice from Step 2, find the code that implements it. Open the referenced files (or search for the command/event/read model names, their fields, and the code terms from the Decisions notes) and record, per slice:
+
+- **COMMAND** → entry point (endpoint/handler/action) + input DTO + service method
+- **EVENT** → what it writes: entity/table + columns, status column + value, or the published event class
+- **READMODEL** → query/repository method + response DTO + endpoint
+- **AUTOMATION / processor** → listener/consumer/job + what it calls
+- **Specifications** → the test class/method that covers them, if any
+
+Verify, don't copy: a line number may be stale, a file may have moved. Fix the reference in the map; if a slice's code can't be found at all, record it as `not found` — never treat it as a feature to build, and never invent a location.
+
+Then **look for the pattern across slices**. The same board construct is usually realized the same way every time — e.g. every `... Registered` event is an insert into the aggregate's table, every `... Approved/Cancelled` event is an update of a `status` column, every read model is a repository method + DTO in the same package, every automation is a `@Scheduled` job. That shared pattern *is* the Event Modeling mapping of this codebase (Step 5). Where slices are realized differently (two persistence styles, an old and a new module), record both and which slices use which, so a new slice can follow its nearest neighbour.
+
+Do not read the whole codebase — follow the references.
+
+## Step 4 — Fill the gaps with reference features
+
+Only for what the existing slices don't cover (no Done slices at all, or e.g. no automation among them) pick **one or two existing features** that look like the slices the board will produce — something that accepts input and changes state, something that only reads/lists data. A recently changed, ordinary feature is a better reference than the oldest or the most special one (`git log --stat -20` helps). When existing slices cover a path, the best-mapped Done slice of that type *is* the reference implementation.
+
+Trace each one end to end, reading only the files on that path:
+
+- **Write path**: entry point (controller/route/handler/form action) → input DTO + validation → service/use case → domain object/entity → repository/DAO → schema/migration → response and error mapping.
+- **Read path**: entry point → query/repository → response DTO → pagination/filtering conventions.
+- **Background/reactive work**: anything that reacts to a state change — event listeners, after-commit hooks, message consumers, schedulers/cron jobs, outbox. Note if there is none.
+- **Tests**: where they live, unit vs. integration, how state is set up (fixtures, builders, factories, test containers, in-memory DB, mocks), how assertions are written.
+
+Do not read the whole codebase. Search (`grep`/glob) for a concept, then follow references.
+
+## Step 5 — Decide the Event Modeling mapping
+
+Decide how each board element is built **in this codebase**, based on what the existing slices show (Step 3) and, only where they say nothing, on the reference features (Step 4) — not on Event Modeling theory:
+
+- **Is it event-based?** Only if the code already persists or publishes events (event store, domain events, outbox, audit log of facts). Otherwise it is state-based (typically CRUD) and board EVENTs become the state transitions a command persists, not new event classes.
+- **COMMAND** → which entry point + DTO + service method shape, and where business-rule violations go (exception type, result type, validation error).
+- **EVENT** → the persisted change (tables/columns written), or the existing event mechanism if there is one.
+- **READMODEL** → query + response DTO; when a new table/view/materialized projection is justified versus querying existing tables.
+- **AUTOMATION / processor** → the existing reactive mechanism (or, if none exists, the least invasive option consistent with the codebase — usually a direct call or a scheduled job; note that choice explicitly).
+- **Specification (given/when/then)** → how `given` events become pre-existing state in a test, and what `then` asserts on.
+
+Then decide **where a new slice goes so it stays isolated and deletable**. Existing slices show how the code *is* built; new slices follow those conventions but are placed as self-contained as the codebase allows — ideally, removing a slice means deleting its own files plus undoing a short, known list of registrations. Settle, from what the codebase tolerates:
+
+- **Own unit per slice** — the most local place the layout allows: a package/folder per slice inside the context's module (best), otherwise own files (controller, DTOs, service/handler, query, test) next to the comparable ones — never new methods appended to an existing shared service, controller or repository when a separate class registered the same way works just as well.
+- **Shared seams** — the unavoidable touch points (router/DI registration, a menu entry, a schema migration, an existing entity that must gain a column) and how to keep each one to a single, small, recognisable change.
+- **Dependencies between slices** — a new slice reads shared state through the existing entity/repository (or the codebase's query style), never by calling another slice's internals; no other slice depends on the new one.
+- **Data** — new state goes into a new table or new columns via a new migration; existing columns are not repurposed.
+
+Where the codebase genuinely forces a shared file (one big controller per aggregate, a central route file), follow it — and record that the slice touches it.
+
+## Step 6 — Write `.build-kit/ARCHITECTURE.md`
+
+Keep it short and concrete — paths, class names and commands, not prose. Use this structure:
+
+```markdown
+# Architecture
+
+## Stack
+- Language/framework/persistence/test framework (with versions)
+- Architecture style: e.g. layered CRUD (controller → service → JPA repository), or event-sourced, or ...
+
+## Commands
+- Build: `...`
+- All tests: `...`
+- Single test: `...` (with a concrete example)
+- Other checks CI runs (lint, format, typecheck): `...`
+
+## Where a feature lives
+- Layout of one feature, with the reference feature as a concrete tree
+- Naming conventions (classes, files, endpoints, tables, columns)
+
+## Reference implementations
+Prefer a mapped Done slice per type; a plain feature only where no slice covers the type.
+- Write: slice *Register Owner* — `path/to/Controller` → `path/to/Service` → `path/to/Repository` (+ migration)
+- Read: ...
+- Background: ... (or "none")
+- Tests: `path/to/ReferenceTest` — how state is set up and asserted
+
+## Event Modeling mapping
+Derived from the slices in the Slice map — cite the slices that show each row.
+| Board element | Built as | Seen in |
+|---|---|---|
+| COMMAND | ... | *Register Owner*, *Book Visit* |
+| EVENT (creation) | ... | ... |
+| EVENT (status transition) | ... | ... |
+| READMODEL | ... | ... |
+| AUTOMATION | ... | ... |
+| Specification | ... | ... |
+
+## Code vs. board terms
+| Code | Board |
+|---|---|
+| `PetType` | *Species* |
+
+## Slice map
+Every slice that exists in the code. One row per slice; paths relative to the repo root. `Shared seams` lists the shared files a slice changed — for slices built by the kit it is the deletion checklist.
+| Slice | Context | Type | Status | Command / entry point | Persistence (events) | Read / query | Trigger | Tests | Shared seams |
+|---|---|---|---|---|---|---|---|---|---|
+| Register Owner | owners | state-change | Done | `OwnerController#processCreationForm` → `OwnerService#register` | `owners` insert | — | — | `OwnerControllerTests` | legacy |
+| Owner Details | owners | state-view | Done | `GET /owners/{id}` | — | `OwnerRepository#findById` → `OwnerDto` | — | ... | legacy |
+| Remind Visit | visits | automation | Done | `VisitService#remind` | `visits.reminded_at` | — | `VisitReminderJob` (`@Scheduled`) | ... | legacy |
+
+## New slices — isolation
+- Placement: e.g. `src/main/java/org/acme/<context>/<slicename>/` with `<Slice>Controller`, `<Slice>Request`, `<Slice>Handler`, `<Slice>Test`
+- Shared seams (the only shared files a slice may touch): `RouteConfig.java` (one line), `db/migration/V<n>__<slice>.sql` (new file), ...
+- Codebase constraints that force sharing, and what to do then
+
+## Rules
+- Conventions a new slice must follow (transactions, validation, error mapping, auth, migrations append-only, ...)
+- Files a slice must not touch (app bootstrap, global config, lockfiles, ...)
+```
+
+## Step 7 — Verify the commands
+
+Run the build command and the single-test command against one existing test. If either fails for reasons unrelated to the code (missing service, missing env var), record the prerequisite under **Commands**. Do not "fix" the project to make it pass.
+
+Commit `ARCHITECTURE.md` on its own: `chore: document architecture for build kit` (with `slices`: `chore: update slice map`).
+
+## Keeping the slice map current
+
+The `build-*` skills add a row for every slice they build, so the map grows with the code. When a later code base analysis puts new Done slices on the board, the next build notices the missing rows and runs this skill with `slices` — only those slices are mapped, the rest of `ARCHITECTURE.md` stays as it is.