kataster 0.3.0 → 0.4.0

package/.claude/skills/user-stories/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: user-stories
-description: Rules, format and splitting patterns for user stories, spikes and tech tasks in docs/stories/ – frontmatter, INVEST, Gherkin, status workflow, and the local mirror when a Jira or GitHub tracker is configured.
+description: Rules, format and splitting patterns for stories, chores, tasks, spikes and tech tasks in docs/stories/ – frontmatter, the 1-command rule, three spec lenses, Gherkin, status workflow, the deterministic spec linter, and the local mirror when a Jira or GitHub tracker is configured.
 ---
 
 # User Stories
@@ -11,6 +11,39 @@ of truth and `docs/stories/` is its local mirror – the `backlog` skill owns th
 the artifact this skill describes, and `docs/stories/BACKLOG.md` is generated from it by a hook – never edit it
 manually.
 
+## The spec engineer (main session)
+
+There is no requirements subagent. The main session writes the stories, because it already holds the grilling, the
+event storming and the user's decisions – handing them to another agent only adds friction and summary loss
+(user, 2026-11-03).
+
+While writing, hold **three lenses at once**:
+
+1. **Domain** – is the behaviour unambiguous? One command, one actor, one observable outcome per scenario. No soft
+   wording ("fast", "user-friendly"), no hidden second behaviour.
+2. **Architecture** – does it fit the bounded context, the aggregate and the events in `docs/domain/events.yaml`?
+   Does the command belong to the aggregate named in the story? Does it need a new event or invariant first?
+3. **Testability** – can every scenario become exactly one red → green test named `ST-NNN: <scenario title>`? Is the
+   *When* the real entry point and is every *Then* an assertion with a literal from the scenario?
+
+If a lens fails, fix the model (`CONTEXT.md`, `events.yaml`, an ADR) before writing the story. A story that hides an
+open decision is a story that will be decided in code.
+
+## The 1-command rule
+
+**One story = one command + the events it produces on one aggregate.** Do not merge several domain commands into one
+story to "save a ticket"; that is what made stories unpredictable. A second command is a second story (or a
+dependency), not a second scenario set.
+
+Mechanically enforced by the linter for `type: domain`:
+
+- `aggregate: AGG-…` and `command: CMD-…` are required and must exist in `events.yaml`;
+- the command must belong to the stated aggregate;
+- `events` must be exactly what that command produces – no more, no fewer.
+
+**At most 4 Gherkin scenarios** per domain story: one happy path and up to three edge/error cases. More means the
+story merges commands, restates a UX guideline pattern, or should be split.
+
 ## Derivation from the Event Storming
 | Source in `events.yaml` | typically becomes |
 |---|---|
@@ -18,72 +51,81 @@ manually.
 | Policy (automatic) | Story from the beneficiary's perspective ("… I am notified when …") |
 | Read model | Story about finding/seeing information |
 | Hotspot | Spike (question + timebox) or `[OPEN]` in the story |
-| External system | Story or tech task for the integration |
+| External system | Story or task for the integration |
 
-Every story links the affected events (`events: [EVT-…]`). Commands without a story = gap → report it.
+Every domain story links the affected events (`events: [EVT-…]`). Commands without a story = gap → report it.
 
 ## File & Frontmatter
 File: `docs/stories/ST-NNN-short-title.md` (three-digit number, consecutive, never reused).
 Template: `templates/story-template.md`. Schema: `schema/story.schema.json`.
 
-| Field | Required | Who sets it |
+| Field | Required | Meaning |
 |---|---|---|
-| `id`, `title`, `type`, `context`, `events` | yes | requirements-engineer |
-| `priority` (`must/should/could/wont`) | yes | product-owner (initially `should`) |
-| `size` (`XS–XL`), `risk`, `depends_on` | before `ready` | lead-dev |
-| `labels` | no | anyone (lowercase, e.g. `mvp`, `feature:<slug>`) |
-| `status` | yes | see workflow |
+| `id`, `title`, `type`, `status` | yes | identity and workflow state |
+| `priority` (`must/should/could/wont`) | yes | backlog order; starts as `should` |
+| `aggregate` (`AGG-…`), `command` (`CMD-…`) | for `type: domain` | the 1-command rule, cross-checked against `events.yaml` |
+| `events` (`EVT-…`) | for `type: domain` | exactly the command's `produces` |
+| `context` (`BC-…`) | for `type: domain` | the bounded context |
+| `ui` (`true`) | no | story has a frontend part; triggers the on-demand UX utility |
+| `size`, `risk`, `depends_on` | no | optional planning hints; no sizing gate |
+| `labels` | no | lowercase, e.g. `mvp`, `feature:<slug>` |
 | `external` | with a tracker | backlog sync – never by hand |
 
 With `backlog.provider` = `github` or `jira`, `external` holds the tracker key (`external.key`) and URL. The sync writes
 it; a story must have it before it reaches `ready`. `ST-NNN` stays the stable id – never renumber a story to follow an
 issue key, and never use a label that starts with the management prefix (`kataster-` by default).
 
-**No implementation foundation inside a domain story** (user, 2026-10-01). A story describes behaviour a person
-can observe; technical groundwork that several stories need is its own **tech task**, with its own `depends_on`.
+**No implementation foundation inside a domain story** (user, 2026-10-01). A story describes behaviour a person can
+observe; technical groundwork that several stories need is its own `task`/`tech-task`, with its own `depends_on`.
 A checklist of files to create, layers to convert or configs to set is an implementation plan, not acceptance
 criteria – it is neither the user's language nor a testable outcome, and it hides the real size of the story.
-*Why this is a rule:* a story once carried a seven-item checklist that converted **every command built so far** to an
-event catalogue. That made an M story an L, put a retrofit nine dependencies deep, and the cost grew with every
-command built before it. The grooming pulled it out as its own tech task and the story went back to M.
-The exception is a tech task or a spike – there a checklist *is* the acceptance criteria.
 
-**The `ui` label** marks every story with a frontend part – a screen, a form, a flow a person walks through.
-`/review-stories` and `/groom-backlog` route those to the `ux-designer`, so a missing label means a story nobody
-reviews from that side. What such a story has to say about the interface (and what it must not) is in the
-`ux-design` skill; the decisions it is measured against are `docs/product/ux-guidelines.md`.
+## Types: domain, fast lane, tech task, spike
 
-## Backlog Order
+| `type` | Use for | Path in `/implement` |
+|---|---|---|
+| `domain` (default) | behaviour in the domain model: one command, one aggregate, Gherkin scenarios | full: TDD per scenario, traceability, diff-scaled review |
+| `chore` | UI tweak, refactoring, dependency bump, small cleanup | fast lane: no Gherkin matching, no formal reviews |
+| `task` | setup or a small non-domain change that is not a chore | fast lane (same as `chore`) |
+| `tech-task` | deliberate technical groundwork several stories need, with a checklist | full: checklist evidence + acceptance tester |
+| `spike` | a timeboxed question, checklist of what to answer | no TDD; evidence in the checklist |
 
-`docs/stories/BACKLOG.md` is generated (`scripts/render-backlog.ts`) and the order is **derived on every render,
-never stored**. `backlogOrder` in `.claude/lib/discovery.ts` sorts:
+`chore` and `task` have a `## Task` section and acceptance as a short checklist (`- [ ] …`) or, if they really have
+observable behaviour, at most 4 scenarios. They do not need `aggregate`, `command`, `context` or `events`.
 
-1. by `priority` – `must`, `should`, `could`, `wont`;
-2. within the same priority **by story ID, ascending**;
-3. then dependencies first – a story that a listed story depends on is pulled in front of it.
+`story` is the legacy name of `domain` and still validates. The linter reports it as a warning and relaxes the strict rules
+(missing `aggregate`/`command`, more than 4 scenarios) so an upgrade does not turn an existing backlog red – new work
+uses `domain`.
 
-What follows from that, and has caught us out before (story review 2026-09-29):
+## The `ui` flag
 
-- **Numbers decide within a priority.** A story with a higher ID never overtakes a lower one, so a new tech task
-  always lands *behind* the older stories it is meant to precede. Raising it to `must` does not help when those
-  are `must` too.
-- **`depends_on` is the only thing that really moves a story forward** – and it is for real dependencies, not
-  for planning wishes. Do not invent one to force an order.
-- **So say it out loud when a story is built out of turn**: `/implement ST-NNN` with the ID, never the bare
-  `/implement` (which follows this very order via `next-story.ts`), and record the intended order in the
-  story's Notes so the next person sees why.
+`ui: true` marks a story with a frontend part – a screen, a form, a flow a person walks through. It is the **only**
+trigger for the on-demand `ux-designer`: component/layout proposals, Figma/design-token logic or a prototype. The UX
+utility never gates the story; a missing decision comes back as a proposal, not as a blocker.
 
-There is no script that re-sorts the backlog, because there is nothing to sort – only story files and this rule.
+The old `labels: [ui]` is still recognised as equivalent. New stories set the flag.
 
 ## Status Workflow
-`draft` (in progress) → `review` (finished, waiting for the story review) → `ready` (after user approval; `size` set, no `[OPEN]`) → `in-progress` → `done`.
-
-Discovery ends at `ready`. The engineering workflow (`/implement`) sets `in-progress` and `done` with `node .claude/skills/implement/scripts/story-status.ts`; the validation hook enforces the same rules when the file is edited directly:
+`draft` (in progress) → `review` (written, waiting for the linter) → `ready-for-human-review` (spec linter green) →
+`ready` (the user approved it) → `in-progress` → `done`.
+
+- **The linter is the gate**: `node .claude/skills/user-stories/scripts/lint-story.ts <file>`. Only when it is green
+  does the story move to `ready-for-human-review`; there is no LLM review pass before implementation.
+- **`ready` is the user's decision**, not the agent's.
+- Discovery ends at `ready`. The engineering workflow (`/implement`) sets `in-progress` and `done` with
+  `node .claude/skills/implement/scripts/story-status.ts`; the validation hook enforces the same rules when the file
+  is edited directly.
 - `in-progress` and `done` need all `depends_on` stories `done`.
-- `done` needs a test titled `ST-NNN: <scenario title>` for every scenario (story), or every checklist item ticked `- [x]` (spike, tech task).
-- A story that turns out wrong during implementation goes from `in-progress` (or `ready`) back to `review`, with `[OPEN]` + an entry in `OPEN_QUESTIONS.md`; it is revised and approved again.
+- `done` for a domain story needs a test titled `ST-NNN: <scenario title>` for every scenario; for a chore, task,
+  tech task or spike every checklist item is ticked `- [x]`.
+- A story that turns out wrong during implementation goes from `in-progress` (or `ready`) back to `review`, with
+  `[OPEN]` + an entry in `OPEN_QUESTIONS.md`; the main session revises it and the linter/approval runs again.
 - `done` is final. A change to finished behaviour is a new story.
-- `superseded` – a story that is not built as written, before it was started: its work was done elsewhere (a direct change, another story), or a new planning replaces it. Set from `draft`, `review` or `ready`, never from `in-progress`. Its first paragraph says where the work went or what replaces it; the file stays as the record other documents link to. Final like `done`, listed in its own section of the backlog and counted in no progress (user, 2026-10-25). Set it with `node .claude/skills/implement/scripts/story-status.ts ST-NNN superseded`.
+- `superseded` – a story that is not built as written, before it was started: its work was done elsewhere (a direct
+  change, another story), or a new planning replaces it. Set from `draft`, `review`, `ready-for-human-review` or
+  `ready`, never from `in-progress`. Its first paragraph says where the work went or what replaces it; the file stays
+  as the record other documents link to. Final like `done`, listed in its own section of the backlog and counted in
+  no progress (user, 2026-10-25).
 
 ## Body Structure
 ```
@@ -110,26 +152,42 @@ Scenario: <Error or edge case>
 ## Out of Scope
 ## Open Questions
 ```
-Scenario titles are unique within a story and become test titles (`ST-NNN: <scenario title>`). Renaming a scenario of an `in-progress` or `done` story breaks that link – the test must be renamed too (`verify.ts` reports it).
+Scenario titles are unique within a story and become test titles (`ST-NNN: <scenario title>`). Renaming a scenario
+of an `in-progress` or `done` story breaks that link – the test must be renamed too (`verify.ts` reports it).
 
-Spikes: `## Question`, `## Timebox`, `## Acceptance Criteria` (checklist `- [ ] …`).
-Tech tasks: `## Task`, `## Acceptance Criteria` (checklist).
+Chore/task/tech-task: `## Task`, `## Acceptance Criteria` (checklist `- [ ] …`).
+Spike: `## Question`, `## Timebox`, `## Acceptance Criteria` (checklist).
 
 ## Quality Rules
 - **INVEST**: independent, negotiable, valuable, estimable, small, testable.
-- Gherkin in English (`Given / When / Then / And / But`). At least a happy path + one error/edge case.
+- Gherkin in English (`Given / When / Then`); every scenario has all three steps. At least a happy path + one
+  error/edge case, at most 4 scenarios.
 - Scenarios describe **behavior**, not UI details ("clicks the blue button" ✗) and not technology.
-- **At most 10 scenarios** per story – each one is a red → green cycle in `/implement`. Spend them on domain behavior and real rejections. A pattern `docs/product/ux-guidelines.md` already defines (grouping, collapsing, kept choices after a rejection) is a G-number in the Context, tested once where the pattern is built, not restated as scenarios. More left → split (patterns below). The validator warns in `draft` and refuses `review`.
+- Spend the scenarios on domain behavior and real rejections. A pattern `docs/product/ux-guidelines.md` already
+  defines (grouping, collapsing, kept choices after a rejection) is a G-number in the Context, tested once where the
+  pattern is built, not restated as scenarios.
 - Measurable outcomes: "Then the item has the status 'out of order'" instead of "Then it works".
 - Non-functional requirements as concrete scenarios or checklist items with a number.
 - Terms exactly as in the glossary `CONTEXT.md`; never use an `_Avoid_` synonym.
 
-## Splitting Patterns (if larger than M)
-By workflow step · by business rule · happy path first, special cases later · by data variant · by role · "manual first, automated later".
+## Splitting Patterns (one command per story)
+By command · by business rule · happy path first, special cases later · by data variant · by role ·
+"manual first, automated later". If two commands share a screen, that is two stories and one `depends_on`, not one
+story with two `When`s.
+
+## Validation (deterministic, no LLM)
+The spec linter is the gate before `ready-for-human-review`:
+
+```bash
+node .claude/skills/user-stories/scripts/lint-story.ts            # all stories
+node .claude/skills/user-stories/scripts/lint-story.ts ST-012     # one story
+kataster lint-story docs/stories/ST-012-*.md                      # from the CLI
+```
+
+It checks frontmatter syntax and required fields, the aggregate/command/event cross-check against
+`docs/domain/events.yaml`, Gherkin `Given/When/Then`, at most 4 scenarios and unique scenario titles. A PostToolUse
+hook runs the same rules after every write and regenerates `BACKLOG.md`; `verify.ts` runs them for the whole backlog.
 
-## Validation
-A hook checks every written story automatically and regenerates `BACKLOG.md`. Full check of all stories:
-`node .claude/skills/user-stories/scripts/validate-stories.ts`
 After deleting or renaming story files, regenerate the backlog:
 `node .claude/skills/user-stories/scripts/render-backlog.ts`
 

package/.claude/skills/user-stories/schema/story.schema.json

@@ -3,12 +3,15 @@
   "title": "Story frontmatter (docs/stories/ST-NNN-*.md)",
   "type": "object",
   "additionalProperties": false,
-  "required": ["id", "title", "type", "context", "priority", "status"],
+  "required": ["id", "title", "type", "priority", "status"],
   "properties": {
     "id": { "type": "string", "pattern": "^ST-[0-9]{3,}$" },
     "title": { "type": "string", "minLength": 5, "maxLength": 120 },
-    "type": { "enum": ["story", "spike", "tech-task"] },
+    "type": { "enum": ["domain", "chore", "task", "tech-task", "spike", "story"] },
     "context": { "type": "string", "pattern": "^BC-[A-Za-z0-9]+$" },
+    "aggregate": { "type": "string", "pattern": "^AGG-[A-Za-z0-9]+$" },
+    "command": { "type": "string", "pattern": "^CMD-[A-Za-z0-9]+$" },
+    "ui": { "type": "boolean" },
     "priority": { "enum": ["must", "should", "could", "wont"] },
     "size": { "enum": ["XS", "S", "M", "L", "XL", null] },
     "risk": { "enum": ["low", "medium", "high", null] },
@@ -34,6 +37,6 @@
         "url": { "type": "string" }
       }
     },
-    "status": { "enum": ["draft", "review", "ready", "in-progress", "done", "superseded"] }
+    "status": { "enum": ["draft", "review", "ready-for-human-review", "ready", "in-progress", "done", "superseded"] }
   }
 }

package/.claude/skills/user-stories/scripts/lint-story.ts

@@ -0,0 +1,56 @@
+/**
+ * The story spec linter – deterministic, no LLM, no tokens.
+ *
+ * It is the gate before `ready-for-human-review`: a story only leaves `review` when this exits 0.
+ * The rules live in `lib/discovery.ts`, so the PostToolUse hook, `validate-stories.ts`, `story-status.ts`
+ * and `verify.ts` all enforce the same checks. This script is the human/CI entry point.
+ *
+ *   node .claude/skills/user-stories/scripts/lint-story.ts            # every story
+ *   node .claude/skills/user-stories/scripts/lint-story.ts ST-012     # one story by id
+ *   node .claude/skills/user-stories/scripts/lint-story.ts docs/stories/ST-012-*.md
+ *   node .claude/skills/user-stories/scripts/lint-story.ts --json     # machine-readable
+ *
+ * Checks: frontmatter syntax and required fields (`id`, `title`, `type`, `status`; `aggregate` and `command`
+ * for `type: domain`), referential integrity against `docs/domain/events.yaml` (aggregate, command, events =
+ * what the command produces), Gherkin Given/When/Then, at most 4 scenarios, unique scenario titles.
+ */
+import { existsSync } from "node:fs";
+import { basename, resolve } from "node:path";
+import * as d from "../../../lib/discovery.ts";
+
+const args = process.argv.slice(2);
+const json = args.includes("--json");
+const target = args.find((a) => !a.startsWith("-"));
+
+let only: string | null = null;
+if (target) {
+  if (/^ST-\d{3,}$/i.test(target)) {
+    const path = d.storyFiles().find((f) => basename(f).toUpperCase().startsWith(target.toUpperCase()));
+    if (!path) {
+      console.error(`No story file found for '${target}' in docs/stories/.`);
+      process.exit(1);
+    }
+    only = path;
+  } else {
+    only = resolve(target);
+    if (!existsSync(only)) {
+      console.error(`Story file not found: ${target}`);
+      process.exit(1);
+    }
+  }
+}
+
+const report = new d.Report();
+d.validateStories(report, only);
+
+if (json) {
+  console.log(JSON.stringify({ ok: report.ok, errors: report.errors, warnings: report.warnings }, null, 2));
+} else {
+  for (const line of report.lines()) console.log(line);
+  if (report.ok) {
+    console.log(`Spec linter OK${only ? ` – ${d.rel(only)}` : ""}${report.warnings.length ? ` (${report.warnings.length} warning(s))` : ""}.`);
+  } else {
+    console.log(`\nSpec linter FAILED: ${report.errors.length} error(s). Fix the story; it does not reach 'ready-for-human-review' before this is green.`);
+  }
+}
+process.exit(report.ok ? 0 : 1);

package/.claude/skills/user-stories/templates/story-template.md

@@ -1,8 +1,11 @@
 ---
 id: ST-001
 title: Short, domain-level title
-type: story
+type: domain
 context: BC-Example
+aggregate: AGG-Example
+command: CMD-Example
+ui: false
 priority: should
 size: null
 risk: null
@@ -17,7 +20,7 @@ status: draft
 As a <role>, I want <goal>, so that <benefit>.
 
 ## Context
-<Trigger, preconditions, business rules>
+<Trigger, preconditions, business rules – from the command's rules and its aggregate's invariants>
 
 ## Acceptance Criteria
 

package/.claude/skills/ux-design/SKILL.md

@@ -38,9 +38,10 @@ Everything else a person triggers has a screen, and if nobody designs it, it get
 act, and what they see afterwards? If any of the three is unclear, the feature has an open UX question – raise it
 in the grilling round, don't settle it while writing code.
 
-Stories with a frontend part carry the label **`ui`**. `/review-stories` (the lead-dev's UX lens) and
-`/groom-backlog` (the `ux-designer`) pick them by that label, so a missing label means a story nobody looks at from
-this side.
+Stories with a frontend part carry **`ui: true`** (the legacy label `ui` is still recognised). It is the trigger for
+the on-demand `ux-designer` – component/layout proposals, Figma/design-token logic, a prototype – and for the UI
+warnings in the spec linter. It is not a gate: a missing flag means a story nobody looks at from this side, not a
+story that cannot ship.
 
 ## The UX frontier – what to grill
 
@@ -70,10 +71,34 @@ cannot be asked before the domain decision it serves.
 A question whose answer is already in `docs/product/ux-guidelines.md` is not asked again – quote the guideline
 instead. That is what makes the yardstick pay off.
 
+## When paper is not enough – the prototype
+
+Most UX questions are settled in words: entry, job, states, wording. A few are not – which of three
+structurally different layouts works, or whether a state model still feels right once it is pushed through the
+awkward cases. For those, propose a **prototype**: the `prototype` skill, owned by the `ux-designer`.
+
+Propose it in the grilling round, with a recommended answer, when the question is:
+
+- a structural layout choice (not colour, spacing or copy),
+- a state model or a flow that is hard to reason about on paper,
+- a screen that does not exist yet and whose shape decides how the stories are cut.
+
+Do not propose one for polish, or for a question a guideline or the vision already answers. State the one
+question, the branch (`ui` or `logic`), the variants or scenarios, and the timebox. The user decides.
+
+The verdict goes into `docs/product/ux-guidelines.md` as a G-number when it is a recurring rule, and into the
+story's `## Context` (`Prototype: prototype/<slug> – <question> – <verdict>`). The prototype itself is
+throwaway: it lives under `docs/prototypes/<slug>/`, is captured on a throwaway branch, and is never merged.
+Details: `.claude/skills/prototype/SKILL.md`.
+
+At story review, a `ui: true` story whose screen shape is still open is not `ready`: send it back to `/feature` for a
+prototype (or a spike), rather than approving it and deciding it in code. The `ux-designer` advises; the user
+approves.
+
 ## What goes into the story, and what does not
 
-Stories stay at the level of observable behaviour. The `lead-dev` rule holds for UX too: no implementation detail
-in a story, no markup, no component names, no pixel values.
+Stories stay at the level of observable behaviour. No implementation detail in a story: no markup, no pixel values.
+Component proposals belong to the `ux-designer` reply and the engineering conventions, not to the story.
 
 - **Into the Gherkin**: what a person sees and can do, in terms a test can check. "Then the open cases of the
   item are listed, newest first" – yes. "Then a card component with a muted description is rendered" – no.

package/.opencode/agents/acceptance-tester.md

@@ -25,7 +25,7 @@ permissions:
 
 Before you start, load the skill `user-stories` with the `skill` tool.
 
-You are the acceptance tester of this project. You check whether **one story** is really done from the user's point of view. You report gaps; you never write or change tests, code or stories – in this project tests are written test-first by whoever implements the story.
+You are the acceptance tester of this project. You check whether **one story** is really done from the user's point of view. You report gaps; you never write or change tests, code or stories – in this project tests are written test-first by whoever implements the story. You never create follow-up stories: a gap is either fixed in this story or handed back as an open question.
 You have NO context from the main conversation – the task gives you the story ID, the base ref and, if one exists, the preview deployment URL. Write in the artifact language (`languages.artifacts` in `.claude/project.json`, default English).
 
 ## Steps
@@ -35,7 +35,7 @@ You have NO context from the main conversation – the task gives you the story
    - the *Given* is really set up (test data builders, fixed clock for time-based rules),
    - the *When* goes through the real entry point (the command, the page), not a helper behind it,
    - every *Then* line is asserted, with expected values taken from the scenario (literals), not recomputed.
-4. **Run the tests** of the story (e.g. `npm test -- -t "ST-NNN"`; browser tests with the project's e2e script, against the preview URL if given). Use the shell only for read-only commands and test runs.
+4. **Run the tests** of the story (e.g. `npm test -- -t "ST-NNN"`; browser tests with the project's e2e script, against the preview URL if given). Use Bash only for read-only commands and test runs.
 5. **Definition of done** (`docs/engineering/conventions.md` and `docs/product/ux-guidelines.md`): usable at the
    project's design size, lists fast with realistic data, every command writes its journal entry, texts from the
    message catalogs, no personal data in logs, critical security advisories of the stack applied within 48 hours.
@@ -57,8 +57,13 @@ Date: YYYY-MM-DD · Tests run: <command> → <passed/failed counts> · Preview:
 | Item | Applies | Evidence | OK? |
 
 ## Edge cases not covered by the story
-| Case | Expected by a rule? (cite) | Recommendation: fix now / new story / question |
+| Case | Expected by a rule? (cite) | Recommendation: fix now / question |
 ```
 
 End with a verdict: `accepted`, `accepted with remarks` or `not accepted` (a scenario without a real test, a failing test, or a violated rule). **Your verdict is the acceptance** (user, 2026-10-27): on `accepted` and `accepted with remarks` the story goes to `done` and the user only merges, so don't accept what you would want the user to look at first.
+
+## Boundaries
+- You never create, split or revise stories, and never delegate to another agent. An uncovered edge case is a **question** for the developer or a line in the review file – not a new ticket.
+- A story the linter accepted is still built as written: if a scenario itself is wrong, say so; the developer sends the story back to `review` instead of deciding it in code.
+
 Reply to the main session with the verdict, the gaps and the file path.

package/.opencode/agents/code-reviewer.md

@@ -28,11 +28,11 @@ permissions:
 
 Before you start, load the skills `codebase-design` and `tdd` with the `skill` tool.
 
-You are the code reviewer of this project. You review the changes of **one story** against the project's documented decisions and write your findings down. You never change code, tests or stories.
+You are the code reviewer of this project. You review the changes of **one story** against the project's documented decisions and write your findings down. You never change code, tests or stories, and you never create follow-up stories: a finding is either fixed inside this story or handed back as an open question to the developer.
 You have NO context from the main conversation – the task gives you the story ID, the base ref (usually `main`) and the paths you need. Write in the artifact language (`languages.artifacts` in `.claude/project.json`, default English).
 
 ## Inputs
-- The diff: `git diff <base>...HEAD` and `git log <base>..HEAD --oneline`. Use the shell only for read-only commands (git, the scripts below, running tests) – never to write files.
+- The diff: `git diff <base>...HEAD` and `git log <base>..HEAD --oneline`. Use Bash only for read-only commands (git, the scripts below, running tests) – never to write files.
 - The context pack: `node .claude/skills/implement/scripts/story-context.ts ST-NNN` (story, events, commands with rules, aggregates with invariants, glossary, data model, ADRs).
 - ADRs in `docs/adr/`, glossary in `CONTEXT.md`, the engineering conventions in `docs/engineering/conventions.md` (once it exists – it overrides general preferences).
 
@@ -63,7 +63,12 @@ Base: <ref> · Commits: <n> · Date: YYYY-MM-DD
 |---|---|---|---|---|---|---|
 ```
 
-Severity: **blocker** (violates an ADR, a domain rule, security or a scenario – must be fixed before merge), **major** (should be fixed in this story), **minor** (judgement call, the main session decides), **follow-up** (worth a tech-task story, too big for this one).
+Severity: **blocker** (violates an ADR, a domain rule, security or a scenario – must be fixed before merge), **major** (should be fixed in this story), **minor** (judgement call, the main session decides), **question** (needs a decision the developer must make – no story, no ticket, just the question and the evidence).
 End with a two-line verdict: `ready to merge` / `fix blockers first`, and the single most important finding.
 
+## Boundaries
+- You never create, split, re-scope or revise stories, and never delegate to another agent. A finding that is too big for this story is a **question** in the review file with the evidence and the options – the developer decides whether to widen the story, open a question in `OPEN_QUESTIONS.md`, or fix it now.
+- You review the diff, not the whole codebase. Read the surrounding code only where the diff needs it to be judged.
+- Do not restate what lint, types or tests already enforce. Report what a machine cannot see.
+
 Reply to the main session with the verdict, the counts per severity and the file path.

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

@@ -1,5 +1,5 @@
 ---
-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: On-demand UX utility – component and layout proposals, Figma/design-token logic, UX guidelines and throwaway prototypes. Invoked only when a story carries `ui: true` or while the prototyping phase runs; it never gates a story and never writes stories, tests or production code.
 mode: subagent
 color: pink
 permissions:
@@ -10,7 +10,7 @@ permissions:
     resource: docs/product/ux-guidelines.md
     effect: allow
   - action: edit
-    resource: docs/reviews/*
+    resource: docs/prototypes/**
     effect: allow
   - action: shell
     resource: "*"
@@ -28,56 +28,61 @@ permissions:
     resource: ux-design
     effect: allow
   - action: skill
-    resource: user-stories
+    resource: prototype
     effect: allow
 ---
 
-Before you start, load the skills `ux-design` and `user-stories` with the `skill` tool.
+Before you start, load the skills `ux-design` and `prototype` with the `skill` tool.
 
-You are the UX/UI designer of this project, whose interface its users meet in the situations
-`docs/product/vision.md` describes. You have NO context from the main conversation – everything relevant is in `docs/` and in the code.
-Write in the artifact language (`languages.artifacts` in `.claude/project.json`, default English); the UI texts you propose are in the project UI language (`languages.ui` in `.claude/project.json`).
+You are the UX utility of this project. You are **not a gatekeeper**: a story is never blocked on your review, and
+`/implement` never waits for you. The main session calls you when a story has `ui: true`, when the prototyping phase
+runs, or when the user asks a concrete interface question. You have NO context from the main conversation – everything
+relevant is in `docs/` and in the code. Write in the artifact language (`languages.artifacts` in
+`.claude/project.json`, default English); the UI texts you propose are in the project UI language (`languages.ui`).
 
 ## Yardstick
-- `docs/product/ux-guidelines.md` – the decisions already made. **Your file.** If it does not exist yet, say so
-  and propose its first content instead of judging against rules nobody agreed to.
+- `docs/product/ux-guidelines.md` – the decisions already made. **Your file.** If it does not exist yet, say so and
+  propose its first content instead of judging against rules nobody agreed to.
 - `docs/product/vision.md` – user groups, devices, constraints, non-goals
 - `CONTEXT.md` – the glossary; UI terms use the `_UI (<lang>)_` wording exactly
-- `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`.
+- `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 and question set: the preloaded skill `ux-design`. The prototype method: `prototype`.
 
-## Tasks
-1. **Story review** – per story with a frontend part: is the screen's job clear, is the entry point named, do the
-   empty, rejected and no-permission cases have a scenario, is the UI wording decided and does it match the
-   glossary? Name what is missing as concrete scenarios or Context lines the requirements-engineer can apply.
-2. **Screen review** – read the page, the form and the message catalog in the code (`repo.codeRoots` in `.claude/project.json`), and judge in the order the
-   skill gives. Findings only; you never change application code.
-3. **Guidelines** – after the user approves a decision, write it into `docs/product/ux-guidelines.md` as a rule,
-   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?
+## What you deliver
+1. **Component proposals** – for a `ui: true` story: which components the screen is built from, which existing
+   component or pattern it reuses, the states (empty, full, rejected, no permission) and the UI wording. Concrete
+   enough to build from, not a mood board.
+2. **Figma/design logic** – when the project has a design file: the frame, variants, component properties and the
+   token/mapping notes the implementation needs. Never invent a second design system; reuse what exists.
+3. **Guidelines** – after the user approves a decision, write it into `docs/product/ux-guidelines.md` as a rule with
+   the date and the reason. Keep it short enough that someone reads it before writing a page.
+4. **Prototype** – when the main session delegates a 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>`).
+5. **Screen audit (on request only)** – when asked to compare an existing screen with the guidelines, report findings
+   and proposed fixes; do not turn it into a backlog item.
 
 ## 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.
-- 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
-  recommended answer, as the `grilling` skill requires.
-- Don't invent domain terms. A term that is missing belongs in `CONTEXT.md` first, through the domain-model skill
-  – say so, don't use a synonym.
+- **No gatekeeping.** You never approve, block or re-scope a story. You may be asked for advice on a `ui: true`
+  story; you answer as a proposal. The main session and the user decide.
+- **You never write stories.** No `docs/stories/`, no `OPEN_QUESTIONS.md` rows, no tickets. If a story is missing a
+  UI decision, return it as a concrete proposal to the main session.
+- **You never write production code, tests or the engineering conventions.** Component names and props in your
+  proposal are design language; the implementation follows `docs/engineering/conventions.md`.
+- A prototype is throwaway: it lives under `docs/prototypes/`, is captured on a throwaway branch and is never
+  merged. It is not application code.
+- Don't invent domain terms. A missing term belongs in `CONTEXT.md` first, through the domain-model skill – say so,
+  don't use a synonym.
 - Never edit `docs/stories/BACKLOG.md`; it is generated.
 
 ## Output (reply to the main session)
-A table of findings:
+A short proposal per request:
 
-| Story / screen | Level (job / understanding / states / language / consistency / polish) | Severity (blocker, major, minor) | Finding | What to do instead |
+| Screen / story | Component or pattern | States covered | UI wording | Open question |
+|---|---|---|---|---|
 
-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.
-
-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.
-Be honest about the difference; calling polish a blocker costs you the next argument.
+Below it: the Figma/token notes, the 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>`).
+No verdict on the story itself.

package/.opencode/commands/bootstrap.md

@@ -1,5 +1,5 @@
 ---
-description: Greenfield entry point – grills the vision, runs a big-picture event storming, builds the domain model and architecture with ADRs, sets the UX yardstick and derives the foundation stories and first vertical slice.
+description: Greenfield entry point – grills the vision, runs a big-picture event storming, builds the domain model and architecture with ADRs, sets the UX yardstick and writes the foundation tasks and first vertical slice as stories (spec engineer, linted before ready).
 ---
 
 Load the `bootstrap` skill with the `skill` tool and follow it exactly. Do not restate it.

package/.opencode/commands/feature.md

@@ -1,5 +1,5 @@
 ---
-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.
+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, writes the stories itself as spec engineer (1 command, max. 4 scenarios, spec linter) and runs the review gate; bug tickets go to a regression story; `--prototype` adds a throwaway prototype before the stories.
 ---
 
 Load the `feature` skill with the `skill` tool and follow it exactly. Do not restate it.

package/.opencode/commands/groom-backlog.md

@@ -1,5 +1,5 @@
 ---
-description: Periodic grooming of the open backlog – challenges whether stories are still worth building, whether dependencies still hold and whether the priorities still match what the product needs now.
+description: Periodic grooming of the open backlog – challenges whether stories are still worth building, whether dependencies still hold and whether the priorities still match what the product needs now. Runs in the main session; the UX utility is on demand only.
 ---
 
 Load the `groom-backlog` skill with the `skill` tool and follow it exactly. Do not restate it.

package/.opencode/commands/implement.md

@@ -1,5 +1,5 @@
 ---
-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/ on its own branch, verifies, reviews scaled to the diff, refactors and hands the pull request to the user; `type: chore`/`task` (or `--fast`) takes the fast lane without Gherkin matching or formal reviews; `--prototype` settles an open UI question first.
 ---
 
 Load the `implement` skill with the `skill` tool and follow it exactly. Do not restate it.