kataster 0.2.1 → 0.3.1

package/.claude/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,69 @@
+# Third-party notices
+
+Kataster's workflow is partly derived from other people's work. This file says what came from where, so the credit
+travels with the payload: it is copied into every installation together with the skills.
+
+Everything not listed here is original to Kataster.
+
+## Matt Pocock – Skills for Real Engineers
+
+- Upstream: <https://github.com/mattpocock/skills>
+- Site: <https://www.aihero.dev/skills>
+- License: MIT, Copyright (c) 2026 Matt Pocock (full text below)
+
+The grilling interview, the deep-module vocabulary, the test-first loop, the architecture survey, the throwaway
+prototype and the `writing-for-agents` reference are his. Some files are copied verbatim, others are adapted to
+Kataster's artifacts (`CONTEXT.md` instead of `GLOSSARY.md`, the `skill` tool name in OpenCode, the seam catalog,
+the review agents):
+
+| In Kataster | Upstream | State |
+|---|---|---|
+| `.claude/skills/grilling/SKILL.md` | `skills/productivity/grilling/SKILL.md` | adapted (naming, sub-agent wording) |
+| `.claude/skills/grill-me/SKILL.md` | `skills/productivity/grill-me/SKILL.md` | copied (tool name) |
+| `.claude/skills/grill-with-docs/SKILL.md` | `skills/engineering/grill-with-docs/SKILL.md` | adapted |
+| `.claude/skills/writing-for-agents/SKILL.md` | `skills/productivity/writing-for-agents/SKILL.md` | copied verbatim |
+| `.claude/skills/writing-for-agents/SKILL-MECHANICS.md` | `skills/productivity/writing-for-agents/SKILL-MECHANICS.md` | copied verbatim |
+| `.claude/skills/codebase-design/SKILL.md` | `skills/engineering/codebase-design/SKILL.md` | copied verbatim |
+| `.claude/skills/codebase-design/DEEPENING.md` | `skills/engineering/codebase-design/DEEPENING.md` | copied verbatim |
+| `.claude/skills/codebase-design/DESIGN-IT-TWICE.md` | `skills/engineering/codebase-design/DESIGN-IT-TWICE.md` | adapted |
+| `.claude/skills/tdd/SKILL.md` | `skills/engineering/tdd/SKILL.md` | adapted (glossary, seam catalog) |
+| `.claude/skills/improve-codebase-architecture/SKILL.md` | `skills/engineering/improve-codebase-architecture/SKILL.md` | adapted (glossary, tool name) |
+| `.claude/skills/retro/SKILL.md` | `skills/engineering/retro/SKILL.md` | adapted |
+| `.claude/skills/domain-model/SKILL.md` | `skills/engineering/domain-modeling/SKILL.md` | adapted (contexts, aggregates, data model) |
+| `.claude/skills/prototype/SKILL.md` | `skills/engineering/prototype/SKILL.md` | adapted (standalone HTML in discovery, story/guideline capture, timebox) |
+| `.claude/skills/prototype/UI.md` | `skills/engineering/prototype/UI.md` | adapted (standalone default, in-app exception, Kataster artifacts) |
+| `.claude/skills/prototype/LOGIC.md` | `skills/engineering/prototype/LOGIC.md` | adapted (Kataster artifacts) |
+
+Agents and commands built on top of them (`/implement`, `/feature`, `/review-stories`, `/groom-backlog`,
+`/shape`, the review agents in `.claude/agents/`) are Kataster's own, but they stand on the same ideas: grilling as
+a design-tree interview on the frontier, facts looked up rather than asked, decisions left to the user.
+
+## Other ideas
+
+- **John Ousterhout**, *A Philosophy of Software Design* – "Design It Twice" is the model for the parallel-interface
+  exercise in `codebase-design`; depth, seam and the deletion test shape its vocabulary.
+- **Eric Evans**, *Domain-Driven Design* – ubiquitous language, bounded contexts and aggregates shape the domain
+  model and the glossary in `CONTEXT.md`.
+- **Martin Fowler** – the smell baseline behind the review agents.
+
+## MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/.claude/agents/lead-dev.md

@@ -35,6 +35,8 @@ In a **story review** (task from `/review-stories`) add two lenses:
 8. **UX lens** (label `ui` only): the screen's job and entry point are named; the empty, rejected and
    no-permission cases have a scenario; UI wording matches the glossary's `_UI (<lang>)_`. A pattern the
    guidelines already define is referenced by its G-number, not restated as scenarios – name restated ones.
+   A screen whose structural shape is still open is not `ready`: recommend a prototype (`/feature --prototype`
+   or a spike) instead of approving it.
 
 ## Boundaries
 - In stories you only change `size`, `risk`, `depends_on` and – in a story review – `priority`. Return everything else as a recommendation.

package/.claude/agents/ux-designer.md

@@ -1,18 +1,19 @@
 ---
 name: ux-designer
-description: UX/UI designer. Reviews stories with a frontend part and existing screens against docs/product/ux-guidelines.md, and maintains those guidelines. Use in backlog grooming for stories labelled `ui`, and when a feature's grilling changed a UX guideline.
+description: UX/UI designer. Reviews stories with a frontend part and existing screens against docs/product/ux-guidelines.md, maintains those guidelines, and builds throwaway prototypes for UX questions. Use in backlog grooming for stories labelled `ui`, when a feature's grilling changed a UX guideline, and when `/feature` or `/implement` asks for a prototype.
 tools: Read, Glob, Grep, Write, Edit
 model: sonnet
 color: pink
 skills:
   - ux-design
   - user-stories
+  - prototype
 hooks:
   PreToolUse:
     - matcher: "Write|Edit"
       hooks:
         - type: command
-          command: 'node "$CLAUDE_PROJECT_DIR/.claude/hooks/path-guard.ts" docs/product/ux-guidelines.md docs/reviews/'
+          command: 'node "$CLAUDE_PROJECT_DIR/.claude/hooks/path-guard.ts" docs/product/ux-guidelines.md docs/reviews/ docs/prototypes/'
 ---
 
 You are the UX/UI designer of this project, whose interface its users meet in the situations
@@ -27,6 +28,7 @@ Write in the artifact language (`languages.artifacts` in `.claude/project.json`,
 - `docs/engineering/conventions.md` – the page frame, the design size, component rules, where the
   message catalogs live. What is decided there is not yours to re-decide.
 - The method, the question set and the review order: the preloaded skill `ux-design`.
+- The prototype method, its two branches and its capture rules: the preloaded skill `prototype`.
 
 ## Tasks
 1. **Story review** – per story with a frontend part: is the screen's job clear, is the entry point named, do the
@@ -38,11 +40,18 @@ Write in the artifact language (`languages.artifacts` in `.claude/project.json`,
    with the date and the reason. Keep it short enough that someone reads it before writing a page.
 4. **Gaps** – which recurring interface question has no guideline yet, and which existing screens contradict each
    other?
+5. **Prototype** – when the main session delegates a UX question that cannot be settled on paper, build the
+   throwaway prototype under `docs/prototypes/<slug>/`: state the question and the branch (`ui` or `logic`) at
+   the top, use the domain language, no tests, no persistence, no application code. Return the verdict and the
+   branch pointer (`prototype/<slug>`).
 
 ## Boundaries
 - **You never write stories.** Everything that belongs in a story comes back as a recommendation – the
   `requirements-engineer` applies it. The same rule the product-owner and the lead-dev follow.
-- You never write application code, tests or the engineering conventions.
+- You never write **production** application code, tests or the engineering conventions. A prototype is
+  throwaway: it lives under `docs/prototypes/`, is captured on a throwaway branch and is never merged. A
+  question that needs the real application page is built by the main session; you define the question and the
+  variants and review the result.
 - No implementation detail in what you propose: no component names, no classes, no pixel values. Observable
   behaviour and words, not markup.
 - Make no assumptions where the vision or the guidelines are silent: return them as questions, each with a
@@ -57,7 +66,8 @@ A table of findings:
 | Story / screen | Level (job / understanding / states / language / consistency / polish) | Severity (blocker, major, minor) | Finding | What to do instead |
 
 Below it: the scenarios or Context lines you propose per story (ready for the requirements-engineer to apply), the
-guidelines you would add, and at most 3 questions for the user, each with a recommended answer.
+guidelines you would add, and at most 3 questions for the user, each with a recommended answer. When you built a
+prototype, add its question, branch, verdict and pointer (`prototype/<slug>`) so the main session can pass it on.
 
 Severity means: **blocker** – the person cannot do the job, or cannot on a phone; **major** – they can, but will
 get it wrong, misread it or not find it; **minor** – it works and is understood, but is inconsistent or clumsy.

package/.claude/skills/feature/SKILL.md

@@ -1,14 +1,16 @@
 ---
 name: feature
-description: Entry point for a new feature or change once the initial discovery is done – accepts a free-text idea, an existing story (`ST-NNN`) or a ticket (`#123`, `PROJ-123`, URL), grills the idea, runs a focused event storming, updates domain model and ADRs, derives stories into the backlog (local, or the tracker mirror) and runs the story review; bug tickets go to a regression story instead.
+description: Entry point for a new feature or change once the initial discovery is done – accepts a free-text idea, an existing story (`ST-NNN`) or a ticket (`#123`, `PROJ-123`, URL), grills the idea, runs a focused event storming, updates domain model and ADRs, derives stories into the backlog (local, or the tracker mirror) and runs the story review; bug tickets go to a regression story instead; `--prototype` adds a throwaway prototype before the stories.
 disable-model-invocation: true
-argument-hint: "<idea | ST-NNN | #issue | PROJ-123 | URL>"
+argument-hint: "<idea | ST-NNN | #issue | PROJ-123 | URL> [--prototype[=ui|logic]]"
 ---
 
 # New Feature
 
 The argument is a feature idea, an existing story or a ticket. Empty → ask the user for it first.
 Pick a short kebab-case slug for it (e.g. `order-photos`); stories get the label `feature:<slug>`.
+`--prototype[=ui|logic]` is a flag, not part of the idea: strip it before resolving a reference. It asks for a
+prototype before the stories are written; without a branch the `prototype` skill picks it from the question.
 
 ## 0. Intake – when the argument is a reference
 
@@ -28,7 +30,7 @@ Follow the route:
 |---|---|
 | `continue-story` | Read that story and treat it as the idea. Its open questions are the first grilling frontier. Do not create a parallel feature. |
 | `review-story` | Stop; run `/review-stories <id>` (or revise the story if it is still being written). |
-| `implement-story` | Stop; the next command is `/implement <id>`. |
+| `implement-story` | Stop; the next command is `/implement <id>` – with `--prototype` if the user asked for one. |
 | `new-story` | Finished behaviour is final; continue as a new feature and name the old story as the predecessor. |
 | `bug` | Use the bug path below, not the feature pipeline. |
 | `feature` | Continue with step 1. |
@@ -63,24 +65,48 @@ Call the `skill` tool four times, for `grilling`, `domain-model`, `architect` an
 - **Lead dev**: Which existing code, data and stories change? Is there a migration? What is hard to test? Where does it cut into stories – each a vertical slice of at most ~10 scenarios?
 - Which existing processes, events and stories does it change? What's explicitly out of scope?
 - **UX – does a person see anything?** Almost always yes – then the UX frontier of `ux-design` belongs in the rounds: entry point, the screen's one job, what is shown before acting, what happens afterwards, the rejected, empty, full and no-permission cases, and the UI wording. A feature whose screens nobody named gets them by accident. Stories with a frontend part get the label `ui`.
+- **Prototype – is paper enough?** When the UX frontier leaves a structural layout choice, a flow or a state model that cannot be settled in words, the UX lens proposes a prototype: one question, the branch (`ui` or `logic`), the variants or scenarios, and a timebox. The user decides. `--prototype` makes it explicit. Do not propose one for polish or for a question a guideline already answers. If it is agreed, run step 2b before the event storming.
 - New or changed terms → `CONTEXT.md` inline.
 - An architectural trade-off → ADR (`status: proposed`) only if the architect skill's three criteria hold.
 
 Don't move on before the user confirms.
 
+## 2b. Prototype (optional)
+
+Only when the user asked (`--prototype`) or the grilling agreed on it. Load the `prototype` skill and follow
+it. In short:
+
+1. **Question and branch.** Name the one question and pick `ui` (what should it look like) or `logic` (does
+   the state model feel right). Write both at the top of the prototype and in its `README.md`.
+2. **Delegate to `ux-designer`** with the question, the branch, the variants/scenarios, the timebox and the
+   target `docs/prototypes/<slug>/`. It writes a self-contained HTML prototype there – no application code,
+   no tests, no persistence, no shell.
+3. **The user looks and decides.** Open the file, flip the variants or press the buttons. The verdict is the
+   user's, not the agent's.
+4. **Capture.** The decision goes to `ux-designer` for `docs/product/ux-guidelines.md` (a G-number when it is
+   a recurring rule). Commit `docs/prototypes/<slug>/` on a throwaway branch `prototype/<slug>`, push it only
+   if the user wants to share it, then return to the branch you were on. The branch is never merged.
+5. **Into the story.** Pass the verdict and the branch pointer to `requirements-engineer` in section 5: the
+   story's `## Context` gets `Prototype: prototype/<slug> – <question> – <verdict>`, and the scenarios reflect
+   the decision. The `ux-designer` never writes the story itself.
+
+If the question needs the real application (an existing page, real data), say so: that is an in-app prototype
+and belongs to `/implement`, not to discovery. If the prototype does not answer the question within its
+timebox, stop and record what is known.
+
 ## 3. Focused event storming
 Read `.claude/skills/event-storming/SKILL.md` and follow it with the feature as focus: phases 1–6 (phase 0 is covered by step 2), 7–8 only if aggregates or contexts are affected. Capture the feature as its own flow (`FLOW-<FeatureName>`) and write `docs/domain/events.yaml` after every phase.
 
 ## 4. Domain model & architecture
 - Contexts, aggregates or the data model affected → delegate to `domain-architect` with the file paths, the changed/new IDs from `events.yaml` and a clear task.
 - An architectural trade-off came up that wasn't recorded during grilling → offer an ADR per the architect skill's three criteria (`status: proposed`, the user accepts).
-- A UX decision changes or adds a guideline → delegate to `ux-designer`: write exactly these decisions into `docs/product/ux-guidelines.md`. The audit of existing screens belongs to `/groom-backlog`, not to the feature.
+- A UX decision changes or adds a guideline → delegate to `ux-designer`: write exactly these decisions into `docs/product/ux-guidelines.md`. A prototype verdict is a decision like any other; the branch pointer and the verdict go into the story through step 5. The audit of existing screens belongs to `/groom-backlog`, not to the feature.
 
 ## 5. Stories
-Delegate to `requirements-engineer`: derive stories for the feature's new or changed commands, policies and read models; name the event/command IDs, the label `feature:<slug>`, the label `ui` for every story with a frontend part, the label `bug` for the bug path, the source reference (`Source: <ref> (<url>)`) for every story derived from a ticket, the UX decisions from step 2 (with the G-numbers of the guidelines they reference), the story cut from step 2, and existing stories that need revising. Finished stories get `status: review`; have it report the IDs of all stories it created or revised.
+Delegate to `requirements-engineer`: derive stories for the feature's new or changed commands, policies and read models; name the event/command IDs, the label `feature:<slug>`, the label `ui` for every story with a frontend part, the label `bug` for the bug path, the source reference (`Source: <ref> (<url>)`) for every story derived from a ticket, the UX decisions from step 2 (with the G-numbers of the guidelines they reference), the prototype verdict and branch pointer from step 2b, the story cut from step 2, and existing stories that need revising. Finished stories get `status: review`; have it report the IDs of all stories it created or revised.
 
 ## 6. Review
 Read `.claude/skills/review-stories/SKILL.md` and follow it with the story IDs from step 5 as the arguments (only this feature's stories, not everything in `review`). The user still approves every change and every `ready`.
 
 ## 7. Wrap-up
-Summarize: the source and the route taken (idea, ticket, existing story or bug), glossary changes, new/changed events, ADRs proposed, stories created and their review outcome (`ready` vs. still open), open hotspots/questions. Point to `docs/stories/BACKLOG.md`, where `ready` stories are queued for the engineering workflow. For a bug, say which documented rule was restored, or that the rule changed and became a feature.
+Summarize: the source and the route taken (idea, ticket, existing story or bug), glossary changes, new/changed events, ADRs proposed, a prototype run and its verdict (if any), stories created and their review outcome (`ready` vs. still open), open hotspots/questions. Point to `docs/stories/BACKLOG.md`, where `ready` stories are queued for the engineering workflow. For a bug, say which documented rule was restored, or that the rule changed and became a feature.

package/.claude/skills/groom-backlog/SKILL.md

@@ -50,7 +50,8 @@ Start in **one** message, with the full file paths, the scope and the change lis
   smaller because the foundation is there, which bigger? Which dependency is technical fiction? Which story should
   be split, merged or dropped?
 - `ux-designer` – only for stories with the label `ui` (or an obvious frontend part): does the story still match
-  `docs/product/ux-guidelines.md`, and which one builds a screen that a newer story has replaced?
+  `docs/product/ux-guidelines.md`, which one builds a screen that a newer story has replaced, and is there an open
+  UX question that needs a prototype (the `prototype` skill) before the story can be reviewed again?
 
 Tell each one explicitly: **recommend, don't rewrite** – they change only the frontmatter fields they own
 (`priority` for the PO, `size`/`risk`/`depends_on` for the lead dev), everything else comes back as a proposal.

package/.claude/skills/implement/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: implement
-description: Engineering workflow – implements one story from docs/stories/ test-first on its own branch, verifies, has it reviewed by code-reviewer and acceptance-tester, refactors, and sets it `done` on the acceptance tester's verdict and hands the pull request to the user to merge.
+description: Engineering workflow – implements one story from docs/stories/ test-first on its own branch, verifies, has it reviewed by code-reviewer and acceptance-tester, refactors, and sets it `done` on the acceptance tester's verdict and hands the pull request to the user to merge; `--prototype` settles an open UI question first.
 disable-model-invocation: true
-argument-hint: "[ST-NNN – empty = next ready story]"
+argument-hint: "[ST-NNN – empty = next ready story] [--prototype[=ui|logic]]"
 ---
 
 # Implement a Story
 
-Story: the arguments from the invocation (empty → `node .claude/skills/implement/scripts/next-story.ts`; a story already `in-progress` is finished first).
+Story: the arguments from the invocation (empty → `node .claude/skills/implement/scripts/next-story.ts`; a story already `in-progress` is finished first). `--prototype[=ui|logic]` is a flag, not the story ID: strip it before resolving the story. It asks for a prototype before the test plan; see *Prototype (only when asked)*.
 
-The main session writes the code; subagents only review. One checkpoint belongs to the user: the **merge** (step 7). Everything before it runs without asking – a `ready` story is good enough to build up to the pull request, and the acceptance tester accepts the story, not the user – unless the story turns out to be wrong (see *When the story is wrong*) or a seam is missing from the catalog (step 2).
+The main session writes the code; subagents only review. One checkpoint belongs to the user: the **merge** (step 7). Everything before it runs without asking – a `ready` story is good enough to build up to the pull request, and the acceptance tester accepts the story, not the user – unless the story turns out to be wrong (see *When the story is wrong*), a seam is missing from the catalog (step 2), or the user asked for a prototype (step 1b – the verdict is theirs).
 
 Engineering conventions: `docs/engineering/conventions.md` – read it if it exists; it describes the module layout, how commands and read models are built, and the **seam catalog**.
 
@@ -22,6 +22,25 @@ Project profile: `.claude/project.json` – default branch, code roots, commands
 3. `node .claude/skills/implement/scripts/story-context.ts ST-NNN` – the context pack: story, exact test titles, dependencies, events/commands/rules/invariants, glossary, data model, ADRs. Read it completely; it is your source, not memory.
 4. `git switch -c st-NNN-<slug>` (slug from the file name), then `node .claude/skills/implement/scripts/story-status.ts ST-NNN in-progress` and commit `ST-NNN: start`.
 
+## 1b. Prototype (only when asked)
+
+Only with `--prototype`, or when the user explicitly asks during the story. A `ui` story whose screen shape is
+still open was not `ready`; this is the exception that settles it before the test plan. Load the `prototype`
+skill and follow it.
+
+1. **Standalone first.** Delegate to `ux-designer`: question, branch (`ui` or `logic`), variants/scenarios,
+   timebox, target `docs/prototypes/<slug>/`. It writes the self-contained HTML file. The user decides.
+2. **In-app only when the question needs the real page** – an existing route, real data, the real header and
+   sidebar. You build the throwaway route or the `?variant=` gate yourself, following the project's routing
+   convention; the `ux-designer` defines the question and variants and reviews the result. The prototype stays
+   out of the production path and is captured on `prototype/<slug>`.
+3. **Capture.** Commit `docs/prototypes/<slug>/` (or the in-app prototype) on `prototype/<slug>`, return to the
+   story branch, and pass the verdict to `requirements-engineer`: `Prototype: prototype/<slug> – <question> –
+   <verdict>` in `## Context`; a recurring rule goes to `ux-designer` for `docs/product/ux-guidelines.md`.
+4. **Then decide.** If the prototype only settles layout and the scenarios still hold, continue with step 2.
+   If it changes behaviour or a scenario, the story goes back to `review` (see *When the story is wrong*),
+   `requirements-engineer` revises it and `/review-stories` approves it again. The branch stays.
+
 ## 2. Test plan
 Call the `skill` tool for `tdd` (and `codebase-design` when a new module or interface is involved).
 Show one table and go on to step 3 without waiting:
@@ -102,6 +121,8 @@ Summarize in a few lines: scenarios implemented, review findings fixed/skipped,
 
 ## Spikes
 A spike answers its **Question** within its **Timebox** – no test plan, no TDD for throwaway experiments.
+- A UX or state-model spike is a prototype: load the `prototype` skill, keep the question and timebox in the
+  story, and capture the verdict the same way (step 1b).
 - Before starting, tell the user the timebox and what will be kept (skeleton code that becomes the application gets tests and passes verify).
 - Tick each checklist item in the story file as it is answered; write results where the item says (an ADR's consequences, `OPEN_QUESTIONS.md`). A new decision → ADR with `status: proposed` (architect skill); the user accepts.
 - Timebox exhausted → stop, document what is known, and ask the user how to continue.

package/.claude/skills/prototype/LOGIC.md

@@ -0,0 +1,101 @@
+# Logic Prototype
+
+A single, self-contained HTML file (a **shareable demo**) that lets anyone drive a state model by clicking
+buttons. Use this when the question is about **business logic, state transitions, or data shape**: the kind of
+thing that looks reasonable on paper but only feels wrong once you push it through real cases.
+
+Because it is one file with nothing to install, you can hand it to a non-developer (a designer, a PM, a domain
+expert) and let them feel the model for themselves. So it speaks their language, not the code's.
+
+## When this is the right shape
+
+- "I'm not sure if this state machine handles the edge case where X then Y."
+- "Does this data model actually let me represent the case where ..."
+- "I want to feel out what the API should look like before writing it."
+- Anything where someone wants to **press buttons and watch state change**.
+
+If the question is "what should this look like," this is the wrong branch. Use [UI.md](UI.md).
+
+## Process
+
+### 1. State the question
+
+Before writing code, write down what state model and what question you are prototyping. One paragraph, at the
+top of the demo (in a visible intro, not just a comment) and in the `README.md`. A logic prototype that answers
+the wrong question is pure waste, so make the question explicit so it can be checked later.
+
+### 2. Isolate the logic in a portable module
+
+Put the actual logic (the bit that is answering the question) in a single `<script>` block written as a small,
+pure module that could be lifted out and dropped into the real codebase later. The page around it is throwaway;
+this module isn't.
+
+The right shape depends on the question:
+
+- **A pure reducer**: `(state, action) => state`. Good when actions are discrete events and state is a single
+  value.
+- **A state machine**: explicit states and transitions. Good when "which actions are even legal right now" is
+  part of the question.
+- **A small set of pure functions** over a plain data type. Good when there is no implicit current state, just
+  transformations.
+- **A class or module with a clear method surface** when the logic genuinely owns ongoing internal state.
+
+Pick whichever shape best fits the question being asked, *not* whichever is easiest to wire to a page. Keep it
+pure: no DOM, no `document`, no button handlers reaching inside it. The page calls into it; nothing flows the
+other direction. This is what makes the prototype useful past its own lifetime: once the question is answered,
+the validated reducer / machine / function set lifts into the real module on its own.
+
+### 3. Build the shareable HTML file
+
+One file, plain HTML/CSS/JS: no framework, no bundler, no server, everything inline so it opens by double-click
+and survives being emailed around. Anyone should be able to run it by opening it.
+
+Write it for a non-developer. Every label is in **domain language** from `CONTEXT.md`, not code: buttons and
+state read like the business, not like the reducer. Explain in plain words what is happening.
+
+Lay it out with a clean hierarchy, top to bottom:
+
+1. **Title and one-line explanation** of what this demo lets you explore (the question from step 1).
+2. **Current state**: the full relevant state, rendered as a readable panel (labelled fields, not a raw JSON
+   dump), re-rendered after every click so the change is visible. Where it helps a non-developer follow, call
+   out what just changed.
+3. **Free-play buttons**: one button per action, always available, so anyone can poke at the model in any
+   order. Each click dispatches its action and re-renders the state.
+4. **Guided walkthroughs**: a set of **scenarios**, one per tab. Each tab holds a short plain-language
+   description of the scenario (the situation it sets up and what to watch for) and underneath it, the ordered
+   **buttons to press** for that scenario. Each step is a real button: clicking it performs that action and
+   moves to the next step. Starting a walkthrough resets to a known initial state so the scenario runs the same
+   way every time.
+
+Choose scenarios that demonstrate the awkward cases, the ones hard to reason about on paper: the happy path, a
+tricky edge case, an attempt at something that should be illegal.
+
+Keep it beautiful but restrained: clean typography, generous spacing, one accent colour. No animations, no
+gimmicks: nothing that competes with the state and the buttons.
+
+### 4. Hand it over
+
+Send them the file, or open it for them. They will click through the walkthroughs and free-play whenever they
+get to it; the interesting moments are when they say "wait, that shouldn't be possible" or "huh, I assumed X
+would be different"; those are the bugs in the *idea*, which is the whole point. If they want new actions or a
+new scenario, add them. Prototypes evolve.
+
+### 5. Capture the answer and the prototype
+
+Once the prototype has answered its question, capture the answer, then capture the prototype the way the
+[SKILL](SKILL.md) describes. The logic-specific mapping: the validated reducer / machine / function set lifts
+into the real module (the decision, absorbed); the HTML shell rides along to the throwaway branch that keeps
+the prototype as a primary source, and being one self-contained file, it stays trivially re-runnable there.
+
+## Anti-patterns
+
+- **Don't add tests.** A prototype that needs tests is no longer a prototype.
+- **Don't wire it to the real database.** Use in-memory state unless the question is specifically about
+  persistence.
+- **Don't generalise.** No "what if we wanted to support X later." The prototype answers one question.
+- **Don't blur the logic and the page together.** If the pure module references the DOM, `document`, or button
+  handlers, it is no longer liftable. Keep the page as a thin shell over a pure module.
+- **Don't reach for a framework, bundler, or server.** One file the recipient double-clicks; a framework app or a
+  dev server defeats "shareable".
+- **Don't ship the HTML shell into production.** The page is optimised for being clicked through by hand. The
+  logic module behind it is the bit worth keeping.

package/.claude/skills/prototype/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: prototype
+description: Build a throwaway prototype to answer one design question – a self-contained HTML file for a logic/state question, or several radically different UI variants switchable in one file. Use when a UX or domain question cannot be settled on paper, and in /feature or /implement when the user asks for a prototype.
+---
+
+# Prototype
+
+A prototype is **throwaway code that answers a question**. The question decides the shape. It is not a first
+draft of the feature: no tests, no persistence, no polish, no production path. The decision it settles is the
+only thing that survives; the code is captured on a throwaway branch and never merged.
+
+## When this is the right tool
+
+Use it when the question is one of these, and the user agrees:
+
+- **"What should this look like?"** – a structural layout choice: three genuinely different information
+  hierarchies, not three colour variants.
+- **"Does this logic / state model feel right?"** – a state machine, a set of rules or a data shape pushed
+  through cases that are hard to reason about on paper.
+- **"How should this flow feel?"** – a sequence a person walks through, where the order and the feedback are
+  the question.
+
+Do **not** prototype a question a guideline, the vision or the domain model already answers. Do not prototype
+polish (colour, spacing, copy), and do not use it to avoid a grilling decision. The grilling comes first; the
+prototype is evidence for one open branch of it.
+
+## Pick a branch
+
+Identify which question is being answered – from the user's prompt, the story, the surrounding code, or by
+asking if the user is around:
+
+- **"Does this logic / state model feel right?"** → [LOGIC.md](LOGIC.md). One self-contained HTML file with
+  free-play buttons and tabbed guided walkthroughs that push the state model through the awkward cases. A
+  non-developer can drive it.
+- **"What should this look like?"** → [UI.md](UI.md). Several radically different variants in one
+  self-contained HTML file, switchable via a `?variant=` URL search param and a floating bottom bar.
+
+The two branches produce very different artifacts, so getting this wrong wastes the whole prototype. If the
+question is genuinely ambiguous and the user isn't reachable, default to whichever branch better matches the
+surrounding code (a backend module → logic; a page or component → UI) and state the assumption at the top of
+the prototype.
+
+## Where it lives
+
+In discovery, the prototype is **standalone**: `docs/prototypes/<slug>/index.html`, written by the
+`ux-designer`, with a short `README.md` next to it (question, branch, variants/scenarios, timebox, verdict).
+No application code, no framework, no build step, no shell. The user opens the file in a browser.
+
+A question that genuinely needs the real application – an existing page, real data, the real header and
+sidebar – is an **in-app prototype**. That is the exception: it is built by the main session during
+`/implement` (see [UI.md](UI.md)), not by the `ux-designer`, and it follows the project's routing convention
+with a clearly marked throwaway route. The same capture rules apply.
+
+## Rules that apply to both
+
+1. **Throwaway from day one, and clearly marked as such.** The path or the first line says `PROTOTYPE`. Name
+   it so a casual reader cannot mistake it for production.
+2. **Trivial to run.** Standalone: double-click the HTML file. In-app: one command from the project's task
+   runner. No thinking required to start it.
+3. **No persistence by default.** State lives in memory. Persistence is the thing the prototype is *checking*,
+   not something it depends on. If the question explicitly involves a database, use a scratch database or a
+   local file with a clear "PROTOTYPE, wipe me" name.
+4. **Skip the polish.** No tests, no error handling beyond what makes the prototype runnable, no abstractions.
+   The point is to learn something fast.
+5. **Surface the state.** After every action (logic) or on every variant switch (UI), render the full relevant
+   state so the user can see what changed.
+6. **One question, one timebox.** Write the question at the top, in the user's language, and agree a timebox
+   with the user (one working session is the default). If the timebox expires without an answer, stop and
+   record what is known – a second prototype needs a new question, not more polish.
+7. **Capture the answer, not the code.** Fold the validated decision into the real artifact – the story's
+   `## Context`, `docs/product/ux-guidelines.md` (a G-number when it is a recurring rule) or the domain model.
+   Then capture the prototype itself as a **primary source**: commit `docs/prototypes/<slug>/` on a throwaway
+   branch `prototype/<slug>`, push it only if the user wants to share it, and return to the branch you were
+   on. The branch is never merged. The story carries `Prototype: prototype/<slug> – <question> – <verdict>`.
+
+## How it plugs into the workflow
+
+- **`/feature`** – the UX lens proposes a prototype when the frontier leaves a structural UI, flow or state
+  question. The user decides. `--prototype[=ui|logic]` makes it explicit. The verdict goes to the
+  `ux-designer` (guidelines) and to the `requirements-engineer` (story), before the stories are reviewed.
+- **`/implement`** – only when the user asks (`--prototype`) or a spike's question is a UX/state question. A
+  `ui` story whose screen shape is still open was not `ready`; the prototype settles it, then the story goes
+  back to `review` if its behaviour changed. The engineering rule holds: never decide a story in the code.
+- **The `ux-designer`** owns the skill and builds the standalone prototype. It never writes production code,
+  tests or stories. The main session captures the branch and passes the verdict on.

package/.claude/skills/prototype/UI.md

@@ -0,0 +1,130 @@
+# UI Prototype
+
+Generate **several radically different UI variations** in one self-contained HTML file, switchable from a
+floating bottom bar. The user flips between variants in the browser, picks one (or steals bits from each), then
+throws the rest away.
+
+If the question is about logic/state rather than what something looks like, this is the wrong branch. Use
+[LOGIC.md](LOGIC.md).
+
+## When this is the right shape
+
+- "What should this page look like?"
+- "I want to see a few options for this dashboard before committing."
+- "Try a different layout for the settings screen."
+- Any time the user would otherwise spend a day picking between three vague mockups in their head.
+
+## Two sub-shapes: standalone first
+
+A UI prototype is easier to judge when it butts up against the rest of the app – real header, real sidebar,
+real data, real density. A variant in a vacuum looks fine in isolation. But in discovery there is no app code
+yet, and the `ux-designer` must not write it. So the default is standalone; the in-app shape is the exception.
+
+### Sub-shape A: standalone HTML (default in discovery)
+
+One file, `docs/prototypes/<slug>/index.html`, with inline CSS and JS. No framework, no bundler, no server. It
+opens by double-click and survives being emailed around.
+
+- Use sample data that matches the domain (`CONTEXT.md`), not `foo`/`bar`.
+- Give each variant a clear component name in the file: `VariantA`, `VariantB`, `VariantC`.
+- Keep the page frame realistic: the header, the navigation and the density the real page will have. A blank
+  page hides design problems that a populated one exposes.
+- If the feature will live inside an existing screen, render that screen's frame around the variants.
+
+### Sub-shape B: in-app throwaway route (only in `/implement`)
+
+Only when the question genuinely needs the real application: an existing page, real data, the real header and
+sidebar. The main session builds it, not the `ux-designer`. Follow the project's routing convention; do not
+invent a new top-level structure. Name the route or the file so it is obviously a prototype. Same `?variant=`
+pattern and the same switcher. Never wire it to real mutations; read-only is fine.
+
+## Process
+
+### 1. State the question and pick N
+
+Default to **3 variants**. More than 5 stops being radically different and starts being noise, so cap there.
+
+Write down the plan in one line, at the top of the file and in the `README.md`:
+
+> "Three variants of the settings page, switchable via `?variant=`, on the existing `/settings` route."
+
+### 2. Generate radically different variants
+
+Draft each variant. Hold each one to:
+
+- The page's purpose and the data it has access to.
+- The project's component library / styling system if the prototype is in-app; plain CSS if it is standalone.
+- A clear component name in the file, e.g. `VariantA`, `VariantB`, `VariantC`.
+
+Variants must be **structurally different**: different layout, different information hierarchy, different
+primary affordance, not just different colours. Three slightly-tweaked card grids isn't a UI prototype, it's
+wallpaper. If two drafts come out too similar, redo one with explicit "do not use a card grid" guidance.
+
+### 3. Wire them together
+
+Create a single switcher in the file:
+
+```js
+// pseudo-code, adapt to the file
+const variant = new URLSearchParams(location.search).get("variant") ?? "A";
+render(
+  variant === "A" ? VariantA(data) :
+  variant === "B" ? VariantB(data) :
+  VariantC(data)
+);
+renderSwitcher(["A", "B", "C"], variant);
+```
+
+For sub-shape B (in-app), keep all the existing data fetching above the switcher; only the rendered subtree
+changes per variant.
+
+### 4. Build the floating switcher
+
+A small fixed-position bar at the bottom-centre of the screen with three pieces:
+
+- **Left arrow**: cycles to the previous variant (wraps around).
+- **Variant label**: shows the current variant key and, if the variant exports a name, that name too. e.g.
+  `B (Sidebar layout)`.
+- **Right arrow**: cycles forward (wraps around).
+
+Behaviour:
+
+- Clicking an arrow updates the URL search param (`history.replaceState` in a standalone file, the framework's
+  router in-app) so the variant is shareable and reload-stable.
+- Keyboard: `←` and `→` arrow keys also cycle. Don't intercept arrow keys when an `<input>`, `<textarea>`, or
+  `[contenteditable]` is focused.
+- Visually distinct from the page (e.g. high-contrast pill, subtle shadow) so it is obviously not part of the
+  design being evaluated.
+- In-app only: hidden in production builds, gated on `process.env.NODE_ENV !== "production"` or an equivalent
+  check, so a stray prototype merge cannot ship the bar to users. A standalone file never enters the build.
+
+### 5. Hand it over
+
+Surface the file path or the URL (and the `?variant=` keys). The user will flip through whenever they get to
+it. The interesting feedback is usually **"I want the header from B with the sidebar from C"**, which is the
+actual design they want.
+
+### 6. Capture the answer and clean up
+
+Once a variant has won, capture the answer (which variant and why), then capture the prototype the way the
+[SKILL](SKILL.md) describes. Fold the winner into the real code and move the rest onto the throwaway branch,
+not into main:
+
+- **Standalone**: the decision goes into the story and, when it is a recurring rule, into
+  `docs/product/ux-guidelines.md`. The whole `docs/prototypes/<slug>/` folder goes to `prototype/<slug>`.
+- **In-app**: fold the winner into the existing page; drop the losing variants and the switcher from the story
+  branch. The full set goes to `prototype/<slug>`.
+
+The full set of variants is the primary source, so it lands on the throwaway branch, not the bin. Variant
+components and the switcher left in the main branch rot fast and confuse the next reader.
+
+## Anti-patterns
+
+- **Variants that differ only in colour or copy.** That's a tweak, not a prototype. Real variants disagree
+  about structure.
+- **Sharing too much code between variants.** A shared header is fine; a shared layout defeats the point.
+  Each variant should be free to throw out the layout.
+- **Wiring variants to real mutations.** Read-only prototypes are fine. If a variant needs to mutate, point it
+  at a stub: the question is "what should this look like", not "does the backend work".
+- **Promoting the prototype directly to production.** The variant code was written under prototype
+  constraints (no tests, minimal error handling). Rewrite it properly when you fold it in.