@eventmodelers/cli 1.0.53 → 1.0.55

package/stacks/supabase-react/templates/.claude/skills/init-style-guide/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: init-style-guide
+description: Interview the user for CSS, design tokens, brand documents, or any existing style guide material, and persist it as references inside the learn-styleguide skill so UI-generating skills (build-state-change, build-state-view) stay on-brand
+---
+
+# Init Style Guide
+
+Run this whenever the user wants to give this project a design system to follow — "here's our
+style guide", "add our brand CSS", "use this doc for the UI" — or wants to add more material to
+one already started. This skill only collects and files material; it does not itself apply any
+styling to code.
+
+## Step 1 — Ask what they have
+
+Ask the user what they'd like to provide. Accept any of:
+- An existing CSS/SCSS file (a path) — design tokens, a component library stylesheet, a Tailwind
+  config, etc.
+- A brand/style guide document (Markdown, PDF, plain text, a Figma export, ...) — a path.
+- Pasted text/tokens directly in the conversation (e.g. a color palette, font stack, spacing
+  scale).
+- A URL to a live, publicly reachable style guide page — only if the user gives the URL
+  themselves; never search for or guess one.
+
+If they have nothing to add right now, stop — do not create empty placeholder files.
+
+## Step 2 — Persist each item as a reference, verbatim
+
+For every item provided, write it into `.claude/skills/learn-styleguide/references/`. **Never
+summarize, rewrite, or supplement** what was given — this is a store of source material, not an
+interpretation of it.
+
+- **A file path** → copy the file as-is into `references/<original-filename>`, preserving its
+  extension (`.css`, `.scss`, `.md`, `.pdf`, ...).
+- **A URL** → fetch it and save the raw content into `references/<slugified-title-or-host>.md`,
+  with a one-line header noting the source URL and the fetch date.
+- **Pasted text/tokens** → write into `references/<short-slug>.md`, wrapped in a fenced code block
+  when it's CSS/code, with a one-line header noting what it is and the date provided.
+
+Pick filenames that describe the content (`brand-colors.css`, `component-library.md`,
+`voice-and-tone.pdf`), never generic names like `input1`.
+
+If `references/` already has files from a previous run, list them back to the user first so they
+know what's already covered, then only add what's new. Never delete or overwrite an existing
+reference unless the user confirms that specific file should be replaced.
+
+## Step 3 — Refresh learn-styleguide's index
+
+In `.claude/skills/learn-styleguide/SKILL.md`, replace the `## References` section's contents with
+one bullet per file now in `references/` — filename plus a short (one-line) description of what it
+contains, based on a quick read of the file, never invented. Leave everything else in that file
+(frontmatter, the "How to use this skill" section) untouched.
+
+## Step 4 — Confirm
+
+Tell the user what was saved and where, e.g.:
+```
+Saved to .claude/skills/learn-styleguide/references/:
+  - brand-colors.css     (CSS custom properties: primary/secondary palette, spacing scale)
+  - voice-and-tone.md    (brand document — tone, terminology to avoid)
+```

package/stacks/supabase-react/templates/.claude/skills/learn-styleguide/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: learn-styleguide
+description: This project's visual style guide / design system reference material — read before generating or redesigning any UI (screens, components). Populated and kept up to date by the init-style-guide skill.
+---
+
+# Style Guide References
+
+## References
+
+_None yet — run `init-style-guide` to add CSS, design tokens, or brand documents._
+
+## How to use this skill
+
+Before turning a marked screen fragment into a component (`build-state-change`/`build-state-view`
+Step 2), or designing any new screen, read whichever file(s) under `references/` are relevant to
+the task at hand — colors/typography/spacing before styling, a component-library doc before
+choosing markup patterns, a voice-and-tone doc before writing copy.
+
+Prefer these references over values invented on the spot, and prefer them over an existing screen
+mockup's own ad hoc inline styles when the two disagree — the mockup gives structure and content,
+this skill gives the real visual language.
+
+Do not invent references that aren't listed above. If the current task needs a design decision
+these references don't cover, fall back to what the mockup/task already gives you rather than
+guessing a brand rule — or ask the user, if the choice materially affects business logic.
+
+This skill's content is entirely sourced from what the user provided via `init-style-guide` —
+never add, rewrite, or supplement it with invented material.

package/stacks/supabase-react/templates/.claude/skills/learn-styleguide/references/README.md

@@ -0,0 +1,5 @@
+# References
+
+Source material dropped here by `init-style-guide`, verbatim — CSS/SCSS files, brand or style
+guide documents, saved pages, or pasted design tokens. Each file is exactly what the user provided;
+nothing here is generated or summarized. See `../SKILL.md` for how these get used.

package/stacks/supabase-react/templates/build-kit/CLAUDE.md

@@ -0,0 +1,149 @@
+# Project Configuration
+
+Read `src/slices` to understand the global structure — each subdirectory is one board slice; there is no other domain code in this project.
+
+This stack is UI-only: it only builds **state-change** (command → event, write side) and
+**state-view** (read model, read side) slices. Translation slices default to
+`build-state-change`. Automations/processors have no UI counterpart here — if a slice's
+`processors` array is non-empty, that slice belongs to a backend stack, not this one; do
+not attempt to build it, flag it via `request-feedback` instead.
+
+## File Structure Constraints
+
+- **Strict Path Limitation**: `src/slices/{contextSlug}/{laneSlug}/{slicename}/*` — the one
+  exception is `src/pages/`, where multiple slices sharing one screen get composed together (see
+  guideline 8 below)
+- **Slice Organization**: Each feature/domain should be organized as a separate slice
+
+## Code Standards
+
+- **Language**: TypeScript
+- **Module System**: ESM
+- **Type Safety**: TypeScript, strict mode (see `tsconfig.app.json`)
+
+## Development Guidelines
+
+1. Each slice should be self-contained and focused on a specific domain
+2. Maintain clear separation of concerns within each slice
+3. Headers, auth, `fetch`, and Supabase table access live exclusively in `src/lib/api.ts` — a
+   slice component never imports `src/lib/supabase.ts` itself, never calls `fetch`, and never
+   calls `supabase.from(...)` directly; it calls `postCommand`/`queryReadModel` and only contains
+   business logic (validation, request-body shaping, response handling)
+4. A command's/read-model's screen markup (`meta.pages` on its actor HTML_SCREEN node, scoped to
+   this slice's `meta.marks` when the screen is shared) is the visual blueprint — translate it into
+   JSX rather than redesigning it; see `build-state-change`/`build-state-view` Step 2
+5. A slice's business logic lives in its component by default (plain `useState`, no ceremony). Only
+   split it into a colocated `use<Name>.ts` hook when that's genuinely warranted — reused by more
+   than one sibling component, or non-rendering logic large enough that separating it clearly helps
+   — never by default or "for consistency"; see `build-state-change`/`build-state-view` Step 3.
+6. **Design every slice for deletability**: its folder must be removable wholesale without
+   leaving dangling imports elsewhere.
+   - Local state shared only *within* one slice's sub-components (e.g. a multi-step command, a
+     list + submit bar) — and *only* when a single component's own `useState` genuinely can't hold
+     it — gets its own `<Name>Context.tsx`, colocated in that same slice folder, never in
+     `src/lib`, never imported by another slice. This is the exception, not the default; most
+     slices need no Context at all. Follow the same `createContext`/`XProvider`/`useX` shape used
+     in this pattern's origin, `miro-eventmodeling` (e.g. `useReadOnly`/`ReadOnlyProvider`,
+     `useUser`/`UserProvider`): a context object, a `<Name>Provider>` component owning the state,
+     and a `use<Name>` hook wrapping `useContext` — throwing if the value is missing when there's
+     no sensible default (slice-scoped state always throws), returning a plain default only for
+     something genuinely app-wide.
+   - Only concerns that are truly cross-cutting (current session, theme, feature flags — things
+     every slice might need) get a shared provider under `src/lib/`, composed once where the app
+     mounts its providers (e.g. `src/main.tsx`), the same way `miro-eventmodeling`'s root layout
+     nests `UserProvider`/`OrganizationProvider`/etc.
+   - A slice component must never import from another slice's folder — the one place that's allowed
+     to is `src/pages/` (guideline 7). If two slices seem to need the same state, that state belongs
+     in a `src/lib` provider, not a cross-slice import.
+7. **A screen's title is the page name.** Several slices can each hold their own copy of one shared
+   visual screen (one node per slice, each with a different mark, per the `html-screen` skill) —
+   when their screens share a `title`, their components belong on one real page together, arranged
+   as the marks show. The count of *distinct* screen titles across the board is a direct hint at how
+   many pages this app needs, not one page per slice. That composition lives at
+   `src/pages/<ScreenTitle>.tsx`, translating the screen's whole unmarked markup into JSX and
+   substituting each marked position with that slice's actual component; see
+   `build-state-change`/`build-state-view`'s page-composition step for the full procedure.
+8. **A screen's lane is reflected in the folder.** The actor row (lane) a slice's screen is placed
+   in on the board — e.g. "Admin" vs. "Customer" — becomes a folder segment between context and
+   slice: `src/slices/<contextSlug>/<laneSlug>/<sliceFolder>/`. Resolve it via
+   `mcp__eventmodelers__get_board_outline` on the screen's chapter (returns `{id, type, title,
+   lane}` per node); see `build-state-change`/`build-state-view` Step 2. Omit the segment only for
+   the rare slice with no screen at all.
+9. **Every component is testable in isolation, with samples.** A component must render sensibly
+   with no data (an empty/background state, not a crash), and must be exercisable with no real
+   backend running. Every slice ships a colocated `samples/sample-<N>.json` per numbered scenario
+   (`sample-1.json`, `sample-2.json`, ...) — for a STATE_VIEW component, shaped exactly like the
+   row(s) its `queryReadModel` call returns; for a STATE_CHANGE component, a full set of prop
+   values. `src/lib/api.ts`'s `postCommand`/`queryReadModel` are mock-aware: set
+   `VITE_DATA_MODE=mock` and every read is served from `samples/sample-<VITE_MOCK_SAMPLE>.json`
+   instead of Supabase, and every command POST resolves locally instead of hitting the network —
+   flipping one env var is the "switch between samples" mechanism, nothing per-component to wire.
+   The same number across different components' samples represents one coherent scenario across
+   the app, not an arbitrary per-component index. See `build-state-change`/`build-state-view`'s
+   samples step for the full convention.
+
+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.**
+
+**If, at any point below, the slice's requirements are genuinely ambiguous, contradictory, or missing
+a decision you need in order to proceed — do not guess, and do not build anyway.** Invoke the
+`request-feedback` skill with the specific question; it posts the question as a comment on the slice
+and marks it `Blocked`, and you then stop work on this slice for this run. This is an escalation path,
+not a routine step — read `slice.json` and the matching build skill's own instructions fully first;
+most slices are fully specified and need none of this.
+
+**Exception: a missing `apiEndpoint`** (no backend endpoint/table decided yet) is a partial version of
+this — flag it, but don't fully stop. `build-state-change`/`build-state-view` Step 1 cover the exact
+mechanics: post a comment on the slice and mark it `Blocked` (same as `request-feedback`), but then
+keep going — build the slice normally against a provisional mock path/table name with meaningful
+sample data. The slice ends this run `Blocked` (step 6 below does not flip it to `Done`), but the code
+is there, mocked, ready to be pointed at the real API once one exists.
+
+When asked to build a slice, always follow this flow:
+
+1. Read the slice definition from `.build-kit/.slices/<contextSlug>/<sliceFolder>/slice.json`.
+2. Determine the slice type from `sliceType`:
+   - **`STATE_CHANGE`** → invoke `/build-state-change`
+   - **`STATE_VIEW`** → invoke `/build-state-view`
+   - **`AUTOMATION`** → not this stack's job (no UI counterpart) — invoke `request-feedback`
+     rather than building it; it belongs to whichever backend stack is installed alongside this one
+3. Invoke the matching skill and follow its instructions completely. Do not deviate.
+4. **Verify against slice.json**: After the skill completes, check that every command field, event field, and specification in slice.json appears in the implementation. No invented fields — if it is not in slice.json, it must not be in the code.
+5. Run `npm run build` and `npm run lint` (both must pass clean), then the slice's own tests only, if any exist.
+6. If checks pass, commit with `feat: [Slice Name]` and set slice status to `Done` — **unless** the
+   matching build skill flagged a missing `apiEndpoint` and already marked the slice `Blocked`
+   (Step 1 exception above); in that case, commit as normal but leave the status `Blocked`.
+
+After you are done, automatically run the tests for the slice that was edited.
+
+## Example Slice Structure
+
+```
+src/lib/supabase.ts                                # Supabase client singleton — imported ONLY by api.ts
+src/lib/api.ts                                     # postCommand/queryReadModel + auth headers + mock-mode switch (shared, not per-slice)
+src/lib/<CrossCutting>Provider.tsx                  # only for concerns every slice might need (session, theme, ...)
+src/pages/<ScreenTitle>.tsx                         # only when >1 slice shares a screen title — composes their components
+src/slices/<contextSlug>/<laneSlug>/<sliceFolder>/
+  <CommandTitle>.tsx                                # STATE_CHANGE slice — component (logic inline by default)
+  use<CommandTitle>.ts                              # only if the logic was genuinely worth splitting out
+  <CommandTitle>Context.tsx                         # only if sibling components must share state
+  <ReadModelTitle>.tsx                              # STATE_VIEW slice — component (logic inline by default)
+  samples/
+    sample-1.json                                   # one numbered scenario per file — props (STATE_CHANGE) or query result (STATE_VIEW)
+    sample-2.json
+```
+
+Everything under one `<sliceFolder>/` is deletable as a unit — nothing outside it should import
+from it except the parent that renders the slice's top-level component, or `src/pages/` when this
+slice's screen is composed into a shared page.
+
+`contextSlug`/`sliceFolder` are derived exactly as in the `load-slice` skill, and `laneSlug` per
+guideline 8 above — so a slice's frontend code nests one level deeper than the staging data at
+`.build-kit/.slices/<contextSlug>/<sliceFolder>/slice.json` (which has no lane concept), rather
+than mirroring it 1:1.

package/stacks/supabase-react/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/supabase-react/templates/build-kit/lib/backend-prompt.md

@@ -0,0 +1,139 @@
+# 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.
+
+The structure defined in the Project-Skills is relevant.
+
+## 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.
+- 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. Focus on the tasks in this description.
+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` (check Codebase Patterns section first)
+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 quality checks — `npm run build` (typecheck + build) and `npm run lint`. No test runner is configured in this stack yet; if a slice's specifications demand behavioral tests, flag it via `request-feedback` instead of inventing a test setup ad hoc.
+14. If checks pass, commit ALL changes with message: `feat: [Slice Name]` and merge back to main as FF merge (update first)
+15. 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).
+16. Append your progress to `progress.txt` after each step in the iteration.
+17. 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.
+18. Finish the iteration.
+
+## Escalating Ambiguity
+
+**If the slice's requirements are genuinely ambiguous, contradictory, or missing a decision you need
+in order to proceed — do not guess, and do not build anyway.** Invoke `/request-feedback` with the
+specific question; it posts the question as a comment on the slice and marks it `Blocked` on the
+board (overriding the `InProgress` set in step 5), then stop this iteration without finishing the
+build — reply `<promise>DONE</promise>` as if the iteration's work was to raise the question, not to
+implement the slice. This is an escalation path, not a routine step — read the slice.json and the
+matching build skill's own instructions fully first; most slices are fully specified and need none of
+this.
+
+## 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
+- TODO: an example of a your stack-specific reusable pattern once you have 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)
+- TODO: your stack's build command
+- TODO: your stack's test command
+- Do NOT commit broken code
+- Keep changes focused and minimal
+- Follow existing code patterns
+
+## 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/supabase-react/templates/build-kit/lib/prompt.md

@@ -0,0 +1,145 @@
+# 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. Read the slice definition from `.build-kit/.slices/<contextSlug>/<sliceFolder>/slice.json` (written by `/load-slice`).
+
+3. Determine the **slice type** from `sliceType` in the slice.json:
+   - **`STATE_CHANGE`** → invoke `/build-state-change`
+   - **`STATE_VIEW`** → invoke `/build-state-view`
+   - **`AUTOMATION`** → not this stack's job (no UI counterpart) — invoke `/request-feedback`
+     rather than building it
+
+4. Invoke the matching skill and follow its instructions **completely**. Do NOT implement the slice manually.
+
+5. **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.
+
+6. Run `npm run build` and `npm run lint` (both must pass clean) — plus the slice's own tests only, if any exist.
+
+7. If checks pass, commit all changes with message: `feat: [Slice Name]`.
+
+8. Call `/update-slice-status` to set the slice to `Done` on the board — **unless** the matching
+   build skill flagged a missing `apiEndpoint` and already marked the slice `Blocked` (see
+   "Escalating Ambiguity" below); in that case, skip this step and leave it `Blocked`.
+
+#### `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
+
+**If the slice's requirements are genuinely ambiguous, contradictory, or missing a decision you need
+in order to proceed — do not guess, and do not build anyway.** Invoke `/request-feedback` with the
+specific question; it posts the question as a comment on the slice and marks it `Blocked` on the
+board (overriding the `InProgress` set earlier), then stop this iteration without finishing the
+build — reply `<promise>DONE</promise>` as if the iteration's work was to raise the question, not to
+implement the slice. This is an escalation path, not a routine step — read the slice.json and the
+matching build skill's own instructions fully first; most slices are fully specified and need none of
+this.
+
+**Exception: a missing `apiEndpoint`** (no backend endpoint/table decided yet) is a partial version of
+this — flag it, but don't fully stop. `build-state-change`/`build-state-view` Step 1 cover the exact
+mechanics: post a comment on the slice and mark it `Blocked` (same as `/request-feedback`), but then
+keep going — build the slice normally against a provisional mock path/table name with meaningful
+sample data. The slice ends this run `Blocked` (step 8 above does not apply for this case — leave it
+`Blocked` instead of setting `Done`), but the code is there, mocked, ready to be pointed at the real
+API once one exists.
+
+## 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.

package/stacks/supabase-react/templates/root/.env.example

@@ -0,0 +1,12 @@
+# Supabase project this app authenticates against and issues commands as.
+VITE_SUPABASE_URL=
+VITE_SUPABASE_ANON_KEY=
+
+# Base URL of the backend that receives command POSTs (empty for same-origin/relative paths).
+VITE_API_BASE=
+
+# Set to "mock" to serve every component's samples/sample-<N>.json instead of hitting
+# Supabase/the backend at all — lets any slice component be tested/previewed in isolation.
+VITE_DATA_MODE=
+# Which numbered sample set is active when VITE_DATA_MODE=mock, e.g. "1", "2".
+VITE_MOCK_SAMPLE=1

package/stacks/supabase-react/templates/root/.oxlintrc.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "plugins": ["react", "typescript", "oxc"],
+  "ignorePatterns": [".build-kit/**"],
+  "rules": {
+    "react/rules-of-hooks": "error",
+    "react/only-export-components": ["warn", { "allowConstantExport": true }]
+  }
+}

package/stacks/supabase-react/templates/root/README.md

@@ -0,0 +1,49 @@
+# Project
+
+A React (Vite + TypeScript) frontend, built slice-by-slice from an eventmodelers board.
+
+## Stack
+
+- [Vite](https://vite.dev) + React 19 + TypeScript
+- [oxlint](https://oxc.rs/docs/guide/usage/linter.html) for linting
+- [Supabase](https://supabase.com) for auth — every command POST is authenticated with the
+  current Supabase session's JWT (see `src/lib/api.ts` / `src/lib/supabase.ts`)
+
+## Scripts
+
+```bash
+npm install     # install dependencies
+npm run dev     # start the dev server
+npm run build   # type-check and build for production
+npm run preview # preview the production build
+npm run lint    # lint with oxlint
+```
+
+## Structure
+
+- `src/lib/api.ts` / `src/lib/supabase.ts` — the **only** place that knows about base URLs, auth
+  headers, and the Supabase client. Slice components never call `fetch` or read the Supabase
+  session directly — they call `postCommand(path, body)` and handle only their own request/response
+  shape.
+- `src/slices/` — one directory per board slice, generated by the `build-state-change` /
+  `build-state-view` skills from `.build-kit/.slices/<context>/<slice>/slice.json`. Do not
+  hand-edit slice code without reading the matching `slice.json` first.
+- `.build-kit/` — Ralph's runtime: the agent loop, realtime board subscription, and the
+  build skills under `.build-kit/lib/`. See `.build-kit/README.md`.
+- `.claude/skills/` — Claude skills used to build slices (`connect`, `learn-eventmodelers-api`,
+  `load-slice`, `build-state-change`, `build-state-view`, `update-slice-status`,
+  `request-feedback`) plus `init-style-guide` / `learn-styleguide` for keeping generated UI
+  on-brand — run `init-style-guide` once to hand over CSS/design tokens/brand docs.
+
+## Environment
+
+Copy `.env.example` to `.env` and fill in:
+- `VITE_SUPABASE_URL` / `VITE_SUPABASE_ANON_KEY` — the Supabase project this app authenticates
+  against.
+- `VITE_API_BASE` — base URL of the backend that receives command POSTs (leave empty for
+  same-origin/relative paths).
+
+This stack is UI-only: it builds **state-change** (command → event) and **state-view**
+(read model) slices. Automations/processors are a backend concern and are handled by
+whatever backend stack is installed alongside this one — see the note in
+`.build-kit/CLAUDE.md`.