@eventmodelers/cli 1.0.137 → 1.0.139

package/stacks/classic/templates/.claude/skills/record-evidence/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: record-evidence
+description: Writes the implementation evidence for a built slice onto the board — a markdown note in the slice's own column, in the chapter's "Implementation" feedback lane — listing the files, the board-element → code mapping, the specification → test mapping, the shared seams touched, assumptions and the commit. Run after the slice is committed, before it is set to Done. Also usable to document where an existing (legacy) Done slice lives in the code.
+---
+
+# Record Evidence
+
+> **Before doing anything else**, invoke the `connect` skill — if not already connected — to resolve `TOKEN`, `BOARD_ID`, `ORG_ID`, and `BASE_URL`. Do not proceed until the connect skill has completed.
+
+Prefer `mcp__eventmodelers__*` tools when available (registered by the `connect` skill) — the curl blocks below are the fallback for sessions without MCP connected. Send `x-agent-id: $EVENTMODELERS_AGENT_ID` on every write when it is set.
+
+The evidence note is how a human reviewing the board sees **where** a slice lives in the code and **how** each modeled element and scenario was realized, without opening the repository. It is proof, not prose: every line names a concrete file, class, method, endpoint, table or test that exists in the commit.
+
+---
+
+## Step 1 — Collect the evidence
+
+From the slice you just built (or, for a legacy slice, from its row in the **Slice map** of `.build-kit/ARCHITECTURE.md` and the code it names):
+
+| Item | Source |
+|------|--------|
+| `SLICE_ID`, slice title | `slice.json` → `id`, `title` |
+| Commit | `git rev-parse --short HEAD` after the `feat: [Slice Name]` commit (`legacy` for a slice that pre-dates the kit) |
+| Files created / modified | `git show --stat --format= HEAD` — repo-relative paths, split into *created* and *modified* |
+| Element → code mapping | every COMMAND, EVENT, READMODEL, SCREEN and AUTOMATION in `slice.json` (with its `id`) and the code that realizes it |
+| Field → code mapping | every command / event / read-model field and the parameter, property or column it maps to |
+| Specification → test mapping | every entry in `specifications[]` (and storyline-derived tests) and the test class + method that covers it |
+| Shared seams | the `Shared seams` column of the slice's Slice map row |
+| Assumptions | the lines this slice added to `progress.txt` |
+| Quality checks | the build and test commands from `ARCHITECTURE.md` you ran, and their result |
+
+Only list what is really in the code. If an element has no counterpart (e.g. a modeled event the CRUD codebase has no equivalent for), say so explicitly — `— (persisted as the row insert, no event class)` — instead of leaving it out.
+
+## Step 2 — Write the note
+
+Reference board elements with `ref:<nodeId>` (the element ids from `slice.json`) so the note links back to them and keeps their current titles. Put code in backticks. Use this structure:
+
+```markdown
+# Implementation — <Slice Title>
+
+**Commit** `<sha>` · **Type** <state-change|state-view|automation> · **Recorded** <YYYY-MM-DD> · **Checks** <build ✅ / tests ✅ (n passed)>
+
+## Element → Code
+| Element | Code | Where |
+|---------|------|-------|
+| ref:<commandId> | `RegisterMicrochipController#processCreationForm` — `POST /owners/{ownerId}/pets/{petId}/microchip/new` | `src/main/kotlin/.../microchip/RegisterMicrochipController.kt` |
+| ref:<eventId> | insert into `microchips` via `MicrochipRepository#save` | `src/main/kotlin/.../microchip/MicrochipRepository.kt` |
+
+## Fields
+| Element | Field | Code |
+|---------|-------|------|
+| ref:<commandId> | `microchipNumber` | request param → `Microchip.microchipNumber` → column `microchips.microchip_number` |
+
+## Specifications → Tests
+| Specification | Test |
+|---------------|------|
+| <spec title> | `RegisterMicrochipControllerTest#<method>` |
+
+## Files
+**Created**
+- `path/to/NewFile.kt`
+
+**Modified (shared seams)**
+- `path/to/schema.sql` — <what changed: new table / route / registration>
+
+## Assumptions
+- <one line each, or "none">
+```
+
+Keep it compact: one row per element, field and specification — no code excerpts, no narrative. Paths are repo-relative.
+
+## Step 3 — Locate the slice's column
+
+The slice border carries its chapter and column: `parentId` is the chapter (timeline) id, `data.colId` the column id.
+
+Prefer MCP:
+
+```
+mcp__eventmodelers__get_node { "boardId": "<BOARD_ID>", "nodeId": "<SLICE_ID>" }
+```
+
+**Fallback (no MCP):**
+
+```bash
+curl -s -H "x-token: <TOKEN>" -H "x-user-id: record-evidence-skill" \
+  "<BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/nodes/<SLICE_ID>"
+```
+
+Save `parentId` as `CHAPTER_ID` and `data.colId` (or `meta.colId`) as `COLUMN_ID`.
+
+## Step 4 — Find or add the "Implementation" lane
+
+Read the chapter's grid:
+
+```
+mcp__eventmodelers__get_node { "boardId": "<BOARD_ID>", "nodeId": "<CHAPTER_ID>", "projection": "cells" }
+```
+
+```bash
+curl -s -H "x-token: <TOKEN>" -H "x-user-id: record-evidence-skill" \
+  "<BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/nodes/<CHAPTER_ID>?projection=cells"
+```
+
+In `rows`, look for a row with `type: "feedback"` and label `Implementation` (case-insensitive). Save its `id` as `ROW_ID`.
+
+**Never write into any other feedback lane** — other lanes (e.g. `Decisions`) belong to the modeling kit or to people. If there is no `Implementation` lane, add one:
+
+```
+mcp__eventmodelers__add_lane { "boardId": "<BOARD_ID>", "timelineId": "<CHAPTER_ID>", "lanes": [{ "type": "feedback", "label": "Implementation" }] }
+```
+
+```bash
+curl -s -X POST "<BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/timelines/<CHAPTER_ID>/lanes" \
+  -H "Content-Type: application/json" -H "x-token: <TOKEN>" -H "x-user-id: record-evidence-skill" \
+  -d '{"type":"feedback","label":"Implementation"}'
+```
+
+and take `ROW_ID` from the response.
+
+Then check `cells` for an entry with `rowId == ROW_ID` and `colId == COLUMN_ID`. If there is one, save its `nodeId` as `NOTE_ID` — this slice already has an evidence note (from an earlier build) and it gets **replaced**, not duplicated.
+
+## Step 5 — Create or update the note
+
+The note's content lives in `meta.description` (markdown source) — **not** `meta.content`, which is stored but never rendered.
+
+**No note yet** — create it in the cell `<ROW_ID>-<COLUMN_ID>`:
+
+```bash
+curl -s -X POST "<BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/nodes/events" \
+  -H "Content-Type: application/json" -H "x-token: <TOKEN>" -H "x-user-id: record-evidence-skill" \
+  -d '[{
+    "id": "<new-random-uuid>",
+    "eventType": "node:created",
+    "nodeId": "<new-random-uuid>",
+    "chapterId": "<CHAPTER_ID>",
+    "cellId": "<ROW_ID>-<COLUMN_ID>",
+    "meta": {
+      "type": "MARKDOWN",
+      "title": "Implementation — <Slice Title>",
+      "description": "<markdown from step 2, JSON-escaped>"
+    }
+  }]'
+```
+
+**Note exists (`NOTE_ID`)** — replace its content:
+
+```bash
+curl -s -X POST "<BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/nodes/events" \
+  -H "Content-Type: application/json" -H "x-token: <TOKEN>" -H "x-user-id: record-evidence-skill" \
+  -d '[{
+    "id": "<new-random-uuid>",
+    "eventType": "node:changed",
+    "nodeId": "<NOTE_ID>",
+    "changedAttributes": ["meta.title", "meta.description"],
+    "meta": {
+      "type": "MARKDOWN",
+      "title": "Implementation — <Slice Title>",
+      "description": "<markdown from step 2, JSON-escaped>"
+    }
+  }]'
+```
+
+With MCP, send the same event through `mcp__eventmodelers__submit_node_events { "boardId": "<BOARD_ID>", "events": [ ... ], "autoConnect": false }`.
+
+Build the JSON body with a tool that escapes properly (e.g. `jq -n --arg d "$(cat note.md)" ...` or a short script) — never hand-escape newlines and quotes.
+
+## Step 6 — Verify and report
+
+Read the note back (`GET .../nodes/<noteId>`) and check that `meta.description` is non-empty and every `ref:` id is one from `slice.json`. Then report:
+
+```
+Recorded evidence for "<Slice Title>" (<SLICE_ID>)
+Note: <noteId> in lane Implementation, column <COLUMN_ID> (created|updated)
+Commit: <sha>
+```
+
+A failed write here never undoes the build: log it in `progress.txt` and continue with the status update — but do not skip this step silently.

package/stacks/classic/templates/build-kit/CLAUDE.md

@@ -0,0 +1,69 @@
+# Project Configuration
+
+This build kit was installed into an **existing codebase** — it ships no scaffold, no framework and no fixed file layout. Slices are implemented the way this codebase already builds features.
+
+The codebase is typically a classic application (layered, CRUD, a relational database behind services/repositories) — but not necessarily: it may already use domain events, messaging, or event sourcing. Never assume; look.
+
+The usual situation is a **legacy system being extended**: a code base analysis built the event model from the existing code, so most slices on the board — typically those in status `Done` — already exist in the code, and their elements' descriptions reference it. Those slices are the map from board to code: every new slice is built the way its closest existing slice is built.
+
+## Architecture First
+
+`.build-kit/ARCHITECTURE.md` describes how this codebase works: language, layers, where a feature's files go, persistence and migrations, how state changes are exposed (REST, RPC, UI actions), how reads are served, how background/reactive work is wired, the test style, the exact build/test commands — and the **Slice map**: which code every existing slice corresponds to, plus where a new slice goes so it stays isolated.
+
+- If `.build-kit/ARCHITECTURE.md` does not exist, run `/learn-architecture` before building anything.
+- If a `Done` slice in the local `index.json` files has no row in the Slice map, run `/learn-architecture slices` before building.
+- Treat it as the authority for *how* to build. Treat `slice.json` as the authority for *what* to build.
+- If the code contradicts `ARCHITECTURE.md` (a moved folder, a renamed base class, a wrong command), fix `ARCHITECTURE.md` in the same iteration rather than working around it.
+
+## Code Standards
+
+- **Match the codebase**: language, module system, naming, layering, error handling, validation, DI, logging and test style all come from the existing code — copy the closest existing feature, not a textbook pattern.
+- **No new architecture**: never introduce a new framework, library, persistence technology or architectural style (event store, CQRS bus, mediator, ...) to build a slice. If the codebase is CRUD, the slice is CRUD.
+- **No dependency changes**: do not add or upgrade dependencies unless slice.json or a slice prompt explicitly asks for it.
+- **Minimal footprint**: touch only the files the slice needs. Do not refactor, reformat or "clean up" unrelated code.
+- **Isolated and deletable**: build each new slice as self-contained as the codebase allows — its own files (its own package/folder where the layout permits), shared files touched only at the seams `ARCHITECTURE.md` names (registration, routing, a new migration), no other code depending on its internals. Deleting a slice should mean deleting its files and reverting the seams listed in its Slice map row. Conventions still come from the codebase; isolation decides *where* the code goes, not *how* it is written.
+
+Ignore case for files and slices in prompts. "CartItems" slice is the same as "cartitems".
+
+Do not change existing tests unless explicitly instructed, or the change brings the test in line with slice.json (e.g. step 4's field/spec diff).
+
+At the start of every session, read `.build-kit/AGENTS.md` if it exists to load accumulated project learnings.
+
+When starting to work on a slice, invoke the `update-slice-status` skill with `InProgress` status before doing anything else.
+
+## Building a Slice
+
+**CRITICAL: You MUST always use the provided skills to build slices. NEVER implement a slice manually.**
+**ALL fields, event names, command names, and business rules MUST come exclusively from slice.json. Do NOT invent, assume, or guess any field or logic not present in the slice definition.**
+
+**Default: make a reasonable assumption and build the slice.** If a detail is unclear or missing (an example value, a field type, a status mapping, a referenced event that isn't modeled yet, where a file should live, ...), pick the most sensible interpretation from `slice.json`, its specifications, the surrounding model and the existing code, build it, and record each assumption in one line in `progress.txt` and as a code comment. Ambiguity alone is never a reason to stop. **Only if the slice literally cannot be built** — nothing runnable can be produced even with sensible assumptions — invoke `/request-feedback` with the specific question; it posts the question as a comment on the slice and marks it `Blocked`. That must be the absolute exception; a `Blocked` slice should mean "impossible without a human", never "the agent preferred to ask".
+
+When asked to build a slice, always follow this flow:
+
+1. Read the slice definition from `.build-kit/.slices/<context>/<slicename>/slice.json`.
+2. Make sure `.build-kit/ARCHITECTURE.md` exists and its Slice map covers every `Done` slice — run `/learn-architecture` (or `/learn-architecture slices`) if not.
+3. Determine the slice type:
+   - **Translation** — `sliceType === "TRANSLATION"` → read `description` and `notes` from slice.json for hints; default to `/build-automation` if nothing else is specified
+   - **Automation** — `processors` array is non-empty → invoke `/build-automation`
+   - **State-view** — `projections` or `queries` array is non-empty → invoke `/build-state-view`
+   - **State-change** — default (has `commands` / `events`) → invoke `/build-state-change`
+4. Invoke the matching skill and follow its instructions completely. Do not deviate.
+5. **Verify against slice.json**: After the skill completes, check that every command field, event field, read model field and specification in slice.json has its counterpart in the implementation. No invented fields — if it is not in slice.json, it must not be in the code. This applies even when the slice was previously `Done` and reappears as `Planned` — never dismiss a mismatch as "already implemented" or harmless drift; diff slice.json against the code field by field and update the code to match every change.
+6. Run the quality checks from `.build-kit/ARCHITECTURE.md` (build/compile, then only the tests this slice touched).
+7. If checks pass, make sure the slice's row in the Slice map is added/updated and commit with `feat: [Slice Name]`.
+8. Invoke `/record-evidence` — it writes the implementation evidence (element → code mapping, files, specification → test mapping, seams, assumptions, commit) as a markdown note into the slice's column, in the chapter's `Implementation` feedback lane.
+9. Set slice status to `Done`.
+
+After you are done, automatically run the tests for the slice that was edited.
+
+## How Event Modeling maps onto this codebase
+
+The board speaks Event Modeling; the codebase may not. `/learn-architecture` derives the concrete mapping from the existing slices and records it in `ARCHITECTURE.md` — that mapping, and the closest `Done` slice's code, always beat the defaults below. The default for a CRUD codebase, used only where no existing slice shows the way, is:
+
+| Board element | Typical CRUD counterpart |
+|---|---|
+| COMMAND | An input DTO/request + the service/use-case method that validates and applies it, exposed the way the codebase exposes writes (endpoint, RPC, form action, ...) |
+| EVENT | The state transition the command persists — the rows/columns written. A real domain/integration event only if the codebase already publishes them |
+| READMODEL | A query + response DTO (and endpoint) answering from the tables those events were persisted to; a dedicated table/view only if the read can't be served from existing data |
+| AUTOMATION / processor | Whatever already reacts to state changes here: an in-process event listener, after-commit hook, message consumer or scheduled job |
+| Specification (given/when/then) | A test in the codebase's own style: `given` events → pre-existing data (fixtures, repositories, or earlier commands), `when` → the command/query, `then` → resulting state, returned data or the expected error |

package/stacks/classic/templates/build-kit/lib/AGENT.md

@@ -0,0 +1,47 @@
+# Agent Learnings
+
+Patterns and gotchas discovered during task processing. Update this file whenever you encounter something reusable.
+
+## tasks.json
+
+- Tasks are objects with `id`, `createdAt`, and `payload` (a `SliceChangedPayload`).
+- After completing a task, remove it from the array entirely — do not add a status field.
+- Write `[]` to `tasks.json` if the last task is completed.
+
+## SliceChangedPayload fields
+
+```
+event           always "slice:changed"
+organizationId  org UUID or null
+boardId         board UUID
+sliceId         SLICE_BORDER node UUID — use this with /load-slice
+sliceTitle      human-readable slice name (may be null)
+sliceStatus     e.g. "Created", "InProgress", "Done", "Blocked" (may be null)
+timestamp       unix ms when the change was emitted
+```
+
+## Slice files
+
+The realtime agent writes one file per slice on startup and after each `slice:changed` event:
+
+```
+.slices/<context>/<sliceName>.json
+```
+
+- `<context>` is the slice's context value, or `default` if none.
+- `<sliceName>` is the slice title lowercased with spaces and the `"slice:"` prefix removed (e.g. `"slice: Enable User"` → `enableuser`).
+
+These files are always up to date — read them directly before invoking any skill.
+
+## Skill Usage
+
+- Always run `/connect` first to load credentials from `.eventmodelers/config.json` before calling any other skill.
+- `/load-slice sliceId=<uuid>` re-fetches all slices from the API, refreshes the slice files, and returns the requested slice. Use it when you need a guaranteed-fresh view of a specific slice.
+- Read `.slices/<context>/<sliceName>.json` directly when you already know the context and name and the file is recent enough.
+
+## Board API
+
+- The `boardId` and `organizationId` from each payload provide full context — pass them to skills.
+- Node events use `node:created`, `node:changed`, `node:deleted` — always POST to `/api/org/:orgId/boards/:boardId/nodes/events`.
+- Slice metadata (title, status) lives on the SLICE_BORDER node under `meta.sliceStatus` and `meta.title`.
+- `/update-slice-status` rejects moving a slice into a status it's already in — this is a concurrency guard, not a bug. It means another agent already claimed the slice. Treat it as `ALREADY_IN_STATUS`, skip that slice, and move on to the next `Planned` one instead of erroring out.

package/stacks/classic/templates/build-kit/lib/backend-prompt.md

@@ -0,0 +1,138 @@
+# Ralph Agent Instructions
+
+You are an autonomous coding agent working on a software project. You apply your skills to build software slices. You only work on one slice at a time.
+
+This kit runs inside an **existing codebase** — nothing was scaffolded for you. The code is not necessarily event-sourced; typically it is a classic layered/CRUD application. The slice describes *what* must happen (commands, events, read models, specifications); the existing code decides *how* it is built. `.build-kit/ARCHITECTURE.md` is the record of how this codebase works — if it does not exist yet, run `/learn-architecture` before anything else.
+
+Usually this is a legacy system being extended: the event model was built from the existing code, so most slices — typically those in status `Done` — already exist in the code. The **Slice map** in `ARCHITECTURE.md` says where; every new slice is built the way its closest existing slice is built, and placed as isolated and deletable as the codebase allows.
+
+## Context Boundary (READ FIRST — NON-NEGOTIABLE)
+
+You work within **exactly ONE context at a time** — the one named in `.build-kit/.slices/current_context.json`.
+
+- **ONLY** look for and build slices inside `.build-kit/.slices/<currentContext>/`.
+- **NEVER** read, scan, or build slices from any other context directory, even if it has "Planned" slices, and even if the current context has no work left.
+- A "Planned" slice in a *different* context is **NOT yours to build**. Ignore it completely.
+- The one exception is **reading** `Done` slices of other contexts as precedents (through the Slice map in `ARCHITECTURE.md`, or by `/learn-architecture` building that map) — they show how the codebase builds things, they are never built.
+- If the current context has no "Planned" slice, you are **done for this iteration** — reply `<promise>NO_TASKS</promise>` and stop. Do not go looking elsewhere. The context is only ever changed on the board, never by you.
+
+## Your Task
+
+0. Do not read the entire code base. `.build-kit/ARCHITECTURE.md` tells you where to look; read the code of the precedent slices its Slice map names and the files the slice actually touches. If a `Done` slice has no row in the Slice map, run `/learn-architecture slices` first.
+1. Read `.build-kit/.slices/current_context.json` to find the active context name, then read `.build-kit/.slices/<contextName>/index.json`. Every item in status "planned" is a task.
+2. Read the progress log at `progress.txt` **if it exists** (check Codebase Patterns section first) — it is absent until the first slice is built, which is not an error; create it when you write your first entry
+3. Make sure you are on the right branch "feature/<slicename>", if unsure, start from main.
+5. Pick the **highest priority** slice where status is **exactly** "Planned" (case insensitive). This becomes your PRD. Set the status "InProgress" in the index.json **and** update the slice status on the eventmodelers board using the `update-slice-status` skill (or MCP if available).
+   **IMPORTANT: Only work on slices with status "Planned" in the CURRENT context. Never pick up a slice that is "InProgress", "Done", "Blocked", "Created", or any other status — even if it looks incomplete. If no slice has status "Planned" in the current context, reply with:**
+   <promise>NO_TASKS</promise> and stop immediately. Do not work on other slices and do not switch to another context.
+   **Claim conflict**: the board rejects the status update if the slice is already in the target status — this is expected: another agent claimed it first, racing you for the same slice. This is NOT an error. Do not stop, do not retry the same slice. Re-read `index.json` (or re-fetch via `load-slice`), pick the next-highest-priority slice still "Planned", and try claiming that one instead. Repeat until a claim succeeds or no "Planned" slice remains, in which case reply `<promise>NO_TASKS</promise>`.
+6. Pick the slice definition from `.build-kit/.slices/<contextName>/<folder>/slice.json` as defined in the prd. Never work on more than one slice per iteration.
+7. A slice can define additional prompts as codegen/backendPrompt. Any additional prompts defined in backend are hints for the implementation of the slice and have to be taken into account. If you use the additional prompt, add a line in progress.txt
+7. Determine the slice type and invoke the matching skill as defined in the **Building a Slice** section of `.build-kit/CLAUDE.md`. Do NOT implement manually.
+8. Write a short progress one liner after each step to progress.txt
+9. Analyze and Implement that single slice, making use of the skills in the skills directory plus your previously collected knowledge. Make a TODO list for what needs to be done, and adjust the implementation according to the JSON definition. Carefully inspect events, fields and compare against the implemented slice. JSON is the desired state. ATTENTION: a "planned" task can also be just added specifications. So always look at the slice itself, but also the specifications. If specifications were added in json which are not on code, you need to add them in code.
+10. The slice in the json is always true, the code follows what is defined in the json
+11. Slice is only 'Done' if business logic is implemented as defined in the JSON, APIs are implemented, all scenarios in JSON are implemented in code and it fulfills the slice.json. There must be no specification in json that has no equivalent in code.
+12. Make sure to write the ui-prompt.md as defined if defined in the skill
+13. Run the quality checks listed in `.build-kit/ARCHITECTURE.md` — build/compile, then only the tests touched by this slice (do not run all tests).
+14. If checks pass, commit ALL changes with message: `feat: [Slice Name]` and merge back to main as FF merge (update first)
+15. Invoke `/record-evidence` to write the implementation evidence (element → code mapping, files, specification → test mapping, seams, assumptions, commit) as a note into the slice's column, in the chapter's `Implementation` feedback lane.
+16. Update the PRD to set `status: Done` for the completed story in index.json **and** update the slice status on the eventmodelers board using the `update-slice-status` skill (or MCP if available).
+17. Append your progress to `progress.txt` after each step in the iteration.
+18. Append your new learnings to `.build-kit/AGENTS.md` in a compressed form, reusable for future iterations. Only add learnings if they are not already there.
+19. Finish the iteration.
+
+## Escalating Ambiguity
+
+**Default: make a reasonable assumption and build the slice.** If a detail is unclear or missing (an example value, a field type, a status mapping, a referenced event that isn't modeled yet, ...), pick the most sensible interpretation from `slice.json`, its specifications and the surrounding model, build it, and record each assumption in one line in `progress.txt` and as a code comment. Ambiguity alone is never a reason to stop. **Only if the slice literally cannot be built** — nothing runnable can be produced even with sensible assumptions — invoke `/request-feedback` with the specific question; it posts the question as a comment on the slice and marks it `Blocked`. That must be the absolute exception; a `Blocked` slice should mean "impossible without a human", never "the agent preferred to ask".
+
+## Progress Report Format
+
+APPEND to progress.txt (never replace, always append):
+
+```
+## [Date/Time] - [Slice]
+
+- What was implemented
+- Files changed
+- **Learnings for future iterations:**
+  - Patterns discovered (e.g., "this codebase uses X for Y")
+  - Gotchas encountered (e.g., "don't forget to update Z when changing W")
+  - Useful context (e.g., "the evaluation panel is in component X")
+---
+```
+
+The learnings section is critical - it helps future iterations avoid repeating mistakes and understand the codebase better.
+
+## Consolidate Patterns
+
+If you discover a **reusable pattern** that future iterations should know, add it to the `## Codebase Patterns` section at the TOP of progress.txt (create it if it doesn't exist).
+
+```
+## Codebase Patterns
+- Example: "Services are transactional at the class level — never open a transaction in the controller"
+- Example: "New tables need a Flyway migration in db/migration, never edit an existing one"
+```
+
+Only add patterns that are **general and reusable**, not story-specific details.
+
+## Update AGENTS.md Files
+
+Before committing, check if any edited files have learnings worth preserving in nearby AGENTS.md files — API patterns/conventions, gotchas, dependencies between files, testing approaches, configuration/environment requirements.
+
+**Do NOT add:**
+
+- Slice specific implementation details
+- Story-specific implementation details
+- Temporary debugging notes
+- Information already in progress.txt
+- Task-specific learnings
+
+Only update AGENTS.md if you have **genuinely reusable knowledge** that would help future work
+
+## Quality Requirements
+
+- ALL commits must pass this project's quality checks (typecheck/compile, lint, test)
+- Use the build and test commands recorded in `.build-kit/ARCHITECTURE.md`
+- If a command there turns out to be wrong, fix it in `ARCHITECTURE.md` in the same iteration
+- Do NOT commit broken code
+- Keep changes focused and minimal
+- Follow existing code patterns — match the architecture, naming and test style already in the codebase (the closest `Done` slice's code first); never introduce a new framework, library or architectural style to build a slice
+- Keep each slice isolated and deletable: its own files, shared files only at the seams `ARCHITECTURE.md` names, listed in the slice's Slice map row
+
+## Skills
+
+Use the provided skills in the skills folder as guidance.
+Update skill definitions if you find an improvement you can make.
+
+## Specifications
+
+For every specification added to the Slice, you need to implement one executable Specification in Code.
+
+A Slice is not complete if specifications are missing or can't be executed.
+
+## Stop Condition
+
+**After completing ONE slice, always stop — regardless of whether more slices are Planned.** The ralph loop will invoke you again for the next slice. Never chain multiple slices in one iteration.
+
+If the slice was completed and committed successfully, reply with:
+<promise>DONE</promise>
+
+If no slice has status "Planned" in the current context, reply with:
+<promise>NO_TASKS</promise>
+(Do NOT switch to another context to find work — stop here.)
+
+If ALL slices in the current context are Done, reply with:
+<promise>COMPLETE</promise>
+
+## Important
+
+- If `.build-kit/.eventmodelers/config.json` is absent, skip all platform communication (MCP calls, `update-slice-status`, board sync) and continue working locally.
+- Work on ONE slice per iteration
+- Commit frequently
+- update progress.txt frequently
+- Read the Codebase Patterns section in progress.txt before starting
+
+## When an iteration completes
+
+Use all the key learnings from the progress.txt and update the `.build-kit/AGENTS.md` file with those learnings.

package/stacks/classic/templates/build-kit/lib/prompt.md

@@ -0,0 +1,132 @@
+# Agent Task Instructions
+
+You are an autonomous agent reacting to slice status change events on an Eventmodelers board.
+
+## Your Loop
+
+1. Read `AGENT.md` to load accumulated learnings before doing anything else.
+2. Read `.build-kit/tasks.json`.
+3. If `tasks.json` is empty or missing, reply with:
+   <promise>IDLE</promise>
+   and stop.
+4. Pick the **oldest task** (earliest `createdAt`).
+5. Execute the task — see the Execution section below.
+6. After execution, remove that task from the array and write `.build-kit/tasks.json` back.
+7. Append a progress entry to `progress.txt` (create if missing).
+8. Update `AGENT.md` with any new reusable learnings discovered this iteration.
+9. Reply normally so the next iteration can pick up the next task.
+
+## Execution
+
+Each task has a single `payload` of type `SliceChangedPayload`:
+
+```
+{
+  event:          "slice:changed"
+  organizationId: string | null
+  boardId:        string
+  sliceId:        string   ← SLICE_BORDER node UUID
+  sliceTitle:     string | null
+  sliceStatus:    string | null   ← e.g. "InProgress", "Done", "Blocked"
+  timestamp:      number
+}
+```
+
+### Step 1 — Load credentials
+
+Run `/connect` to resolve `TOKEN`, `BOARD_ID`, `ORG_ID`, and `BASE_URL` from `.eventmodelers/config.json`.
+
+### Step 2 — Load the slice
+
+Run `/load-slice sliceId=<payload.sliceId>` to fetch full slice details (title, status, raw node record).
+
+### Step 3 — Act on the change
+
+Inspect the `sliceStatus` in the payload:
+
+#### `Planned` — build the slice
+
+This is the build trigger. Setting `InProgress` and building are one atomic step:
+
+1. Immediately call `/update-slice-status` to set the slice to `InProgress` on the board.
+
+   **Claim conflict**: if this call reports the slice is already in `InProgress` (or any status other than `Planned`), another agent already claimed it first — this is expected, not an error. Log it in `progress.txt`, drop this task without building, and continue the loop (the next task will naturally cover the next slice). Do not retry.
+
+2. Run `/load-slice sliceId=<payload.sliceId>` to fetch the full slice, then read the slice definition from `.build-kit/.slices/<contextSlug>/<sliceFolder>/slice.json`. The runner keeps a `slice.json` fresh from a summary endpoint, so a file holding only `id`, `title`, `status` and `sliceType` is that stub, not an empty slice — never conclude a slice has no elements from it. Only if the full fetch itself returns no commands/events/read models/fields is the slice actually empty.
+
+3. Make sure `.build-kit/ARCHITECTURE.md` exists — if it is missing, run `/learn-architecture` first; if a `Done` slice has no row in its Slice map, run `/learn-architecture slices`. This kit installs into an existing codebase — usually a legacy system whose event model was built from its code, so most `Done` slices already exist in it. That file records how *this* project is built (layers, persistence, naming, tests, build/test commands) and which code each existing slice maps to; every `build-*` skill implements the slice the way its closest existing slice is built, kept as isolated and deletable as the codebase allows.
+
+4. Determine the **slice type** from the slice.json:
+   - **Translation** — `sliceType === "TRANSLATION"` → read `description` and `notes` from slice.json for hints; default to `/build-automation` if nothing else is specified
+   - **Automation** — `processors` array is non-empty → invoke `/build-automation`
+   - **State-view** — `projections` or `queries` array is non-empty → invoke `/build-state-view`
+   - **State-change** — default (has `commands` / `events`) → invoke `/build-state-change`
+
+5. Invoke the matching skill and follow its instructions **completely**. Do NOT implement the slice manually.
+
+6. **Verify against slice.json**: cross-check the implementation — every command field, event field, and specification in slice.json must appear in the code. No invented fields — if it is not in slice.json, it must not be in the code.
+
+7. Run the quality checks listed in `.build-kit/ARCHITECTURE.md` (build/compile, then only the tests touched by this slice — not the full suite).
+
+8. If checks pass, commit all changes with message: `feat: [Slice Name]`.
+
+9. Call `/record-evidence` to write the implementation evidence (element → code mapping, files, specification → test mapping, seams, assumptions, commit) as a note into the slice's column on the board.
+
+10. Call `/update-slice-status` to set the slice to `Done` on the board.
+
+#### `InProgress`
+Another agent is already building this slice. Log it and skip — do not build.
+
+#### `Done`
+Summarize what was completed and update `progress.txt`.
+
+#### `Blocked`
+Log the blocker in `progress.txt`.
+
+#### `Review`
+Fetch slice details and prepare a review summary in `progress.txt`.
+
+#### Any other status (`Created`, etc.)
+Load the slice and log the state transition in `progress.txt`. No build action.
+
+Use the skills available in `.claude/skills/` to interact with the board.
+
+## Updating tasks.json
+
+After completing a task, remove it from the array and write the updated array back to `.build-kit/tasks.json`. If the array is now empty, write `[]`.
+
+## Escalating Ambiguity
+
+**Default: make a reasonable assumption and build the slice.** If a detail is unclear or missing (an example value, a field type, a status mapping, a referenced event that isn't modeled yet, ...), pick the most sensible interpretation from `slice.json`, its specifications and the surrounding model, build it, and record each assumption in one line in `progress.txt` and as a code comment. Ambiguity alone is never a reason to stop. **Only if the slice literally cannot be built** — nothing runnable can be produced even with sensible assumptions — invoke `/request-feedback` with the specific question; it posts the question as a comment on the slice and marks it `Blocked`. That must be the absolute exception; a `Blocked` slice should mean "impossible without a human", never "the agent preferred to ask".
+
+## Progress Report Format
+
+APPEND to `progress.txt` (never replace):
+```
+## [ISO timestamp] — Task [task.id]
+
+Slice: [sliceTitle] ([sliceId])
+Status change: [sliceStatus]
+
+Action taken:
+- [what was done in response to the slice change]
+
+Learnings:
+- [any patterns, gotchas, or reusable knowledge discovered]
+---
+```
+
+## Stop Condition
+
+If `.build-kit/tasks.json` is empty (`[]`) or does not exist, reply with:
+<promise>IDLE</promise>
+
+## Updating AGENT.md
+
+After completing a task, add any **reusable** learnings to `AGENT.md` — patterns, gotchas, API quirks, or skill behaviour that future iterations should know. Only add things that are general and applicable beyond this single task. Do not duplicate what is already there.
+
+## Important
+
+- Process **one task per iteration**.
+- Read `AGENT.md` first — it contains patterns from previous iterations.
+- Always start with `/connect` if credentials are not yet loaded.