kataster 0.0.0-stage → 0.2.1

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

@@ -0,0 +1,107 @@
+---
+name: ux-design
+description: How this project decides user experience and UI – the questions to grill when a feature touches the frontend, what a story has to say about the interface, and the yardstick in docs/product/ux-guidelines.md. Use when a feature or story has a screen, a form or a flow, and in story reviews of stories labelled `ui`.
+---
+
+# UX Design
+
+This skill is **how** we decide the interface. **What** we decided is `docs/product/ux-guidelines.md` – the
+yardstick, owned by the `ux-designer` agent, approved by the user. The two are not interchangeable: a judgement
+that is not in the guidelines is an opinion, and the next story will contradict it.
+
+The technical side lives elsewhere and is not repeated here: `docs/engineering/conventions.md` (page frames,
+design size, component rules, where message catalogs live) and the ADRs. Point at those, don't restate them.
+
+## Who we are designing for
+
+`docs/product/vision.md` is the source – read it, don't paraphrase it from memory. The user groups, their
+devices, their situation and the non-goals are all there; every decision is measured against them. If the vision
+does not name them yet, that is the first thing to grill, not something to invent.
+
+Three questions the vision must answer before the interface can be judged:
+
+- **Who is in front of the screen, and in what situation?** Standing, walking, one hand, gloves, noisy, rushed,
+  at a desk. How long may the task take before it is a failure?
+- **On what?** Phone, tablet, desktop, kiosk. What is the design size – the size the layout is built for, not the
+  exception?
+- **What can they not rely on?** No account, no connectivity, no training, no second language, no patience.
+
+`.claude/project.json` holds the UI language (`languages.ui`). Every term's UI wording lives in `CONTEXT.md` as a
+`_UI (<lang>)_` line; the UI uses exactly that word, never a synonym.
+
+## When a feature has a frontend part
+
+Assume it does. The exceptions are a policy, a migration, a pure read model with no page of its own, and tooling.
+Everything else a person triggers has a screen, and if nobody designs it, it gets designed by accident.
+
+**The test, during grilling:** can you name the screen a person is on when this happens, what they see before they
+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.
+
+## The UX frontier – what to grill
+
+Ask these in the grilling round of `/feature` (or `/grill-with-docs`), each with a recommended answer, as the
+`grilling` skill requires. They belong to the round whose prerequisites are settled – the purpose of a screen
+cannot be asked before the domain decision it serves.
+
+1. **Entry.** How does the person get here – QR code, navigation, a link from another screen, a dashboard? Is this
+   a destination or a step in a flow?
+2. **The one job.** What is the single thing this screen exists for? If there are two, say why they are not two
+   screens.
+3. **Before acting.** What does the person need to see to decide – and what can be left out? Name what is *not*
+   shown; a screen that shows everything decides nothing.
+4. **The action.** How many taps from arriving to done? What is the default, so the common case needs no input?
+5. **Afterwards.** Where does the person land, and how do they know it worked? (Here: a redirect plus the changed
+   list, or a confirmation – see the guidelines.)
+6. **When it goes wrong.** Which rejections can the command return, what does each one say in the UI language, and does the
+   typed input survive? Every error code of the command needs a text in the catalog – the type check enforces it,
+   but the *wording* is a UX decision.
+7. **The empty case.** What does the screen show when there is nothing yet – and does it say what to do about it?
+8. **The full case.** What happens at 50 items, 200 open records, a 60-character name, a three-line title?
+   Which of these is realistic for these users, and which is not worth designing for?
+9. **Permission.** What does someone who may not do this see – the screen without the action, or not the screen?
+10. **Language.** Which UI language(s) apply (see `.claude/project.json`), which domain terms appear, and do they match
+    `CONTEXT.md`'s `_UI (<lang>)_` wording exactly?
+
+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.
+
+## 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.
+
+- **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.
+- **Into `## Context`**: the screen's one job, the entry point, the states that have to exist (empty, rejected, no
+  permission), and the UI wording decided during grilling.
+- **A scenario for the empty case and for the rejection**, when the story introduces a screen. These are the two
+  that get forgotten, and they are the ones a person actually meets.
+- **Not into the story**: layout, component choice, spacing, colour. Those follow from the guidelines and the
+  engineering conventions; if a story needs to say them, the guidelines are missing something – say so.
+
+## Reviewing a screen that exists
+
+Against `docs/product/ux-guidelines.md`, in this order – stop at the first level that fails, the ones below it do
+not matter yet:
+
+1. **Can the person do the job at all**, at the design size, without JavaScript where the conventions require it?
+2. **Do they understand what they are looking at** – heading, what each number means, which item or case this is about?
+3. **Do the four states exist** – empty, full, rejected, no permission?
+4. **Is the language right** – glossary wording, in the UI language, sounding like the domain and not like a database?
+5. **Is it consistent** with the screens that already exist – same patterns, same words for the same thing?
+6. Only then: proportion, rhythm, polish.
+
+Report findings the way a code review does: what, where, why it matters, and what you would do instead. Never
+"this feels unpolished" – name the decision that is wrong.
+
+## Keeping the yardstick honest
+
+Every decision the user approves goes into `docs/product/ux-guidelines.md` immediately, in the voice of a rule
+("A form that is rejected keeps what was typed and names the reason above the submit button"), with the date and
+the reason. A guideline nobody can point at is not a guideline. When the code and the guidelines disagree, raise
+it – don't silently follow either.

package/.claude/skills/writing-for-agents/SKILL-MECHANICS.md

@@ -0,0 +1,22 @@
+# Skill mechanics
+
+The skill-specific branch of [`writing-for-agents`](SKILL.md): what changes when the document is a skill (frontmatter, the invocation choice, and router skills). Everything else about writing it is the universal reference in `SKILL.md`.
+
+## Invocation
+
+Two choices, trading the two loads:
+
+- A **model-invoked** skill keeps a `description`, so the agent can fire it autonomously, and other skills can reach it. You can still type its name: model-invocation always _includes_ user reach; a description only ever adds agent discovery, never removes the human's. The description is the skill's top-level context pointer, forced to stay loaded at all times: permanent context load in exchange for discoverability. A model-invoked skill whose content is all reference is also one home for shared reference: another skill can invoke it, so reference needed by several skills lives in one place. Mechanics: omit `disable-model-invocation`, and write a model-facing description carrying the trigger branches (the pointer-writing rules in `SKILL.md` apply in full).
+- A **user-invoked** skill strips the description from the agent's reach: only the human typing its name can invoke it, and no other skill can. Zero context load, but it spends cognitive load: you are the index that must remember it exists. Mechanics: set `disable-model-invocation: true`; the `description` becomes human-facing: a one-line summary, trigger lists stripped.
+
+Pick model-invocation only when the agent must reach the skill on its own, or another skill must. If it only ever fires by hand, make it user-invoked and pay no context load.
+
+Shared reference that two user-invoked skills both need can live in neither: with no descriptions, neither can fire the other. Push it to a plain file outside the skill system: external reference any skill can point at.
+
+## Splitting by invocation
+
+The invocation cut of splitting (the sequence cut lives in `SKILL.md`): split off a model-invoked skill when you have a distinct leading word that should trigger it on its own (a trigger word you actually use in your prompts), or another skill must reach it. You pay context load for the new always-loaded description, so that independent reach has to be worth it.
+
+## Router skills
+
+When user-invoked skills multiply past what you can remember, that piled-up cognitive load is cured by a **router skill**: one user-invoked skill that names the others and when to reach for each, so the human has one skill to remember instead of many. It can only hint, never fire them: user-invoked skills have no description, so nothing but the human can reach them.

package/.claude/skills/writing-for-agents/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: writing-for-agents
+description: Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.
+---
+
+Reference for writing any document an agent consumes: a skill, an `AGENTS.md` / `CLAUDE.md`, a doc reached by a pointer. The packaging differs; the writing does not: the same levers make each one predictable, since the agent takes the same _process_ every run rather than producing the same output.
+
+When the document you're writing is a skill, read [`SKILL-MECHANICS.md`](SKILL-MECHANICS.md) for frontmatter, invocation choice, and router skills.
+
+## Context pointers
+
+A **context pointer** is a reference held in the agent's context that names some out-of-context material and encodes the condition for reaching it. A skill's description is one; a line in `AGENTS.md` naming a doc is the same object. The pointer's _wording_, not its target, decides when the agent reaches the material, and how reliably. A must-have target behind a weakly worded pointer is a variance bug: sharpen the wording first, and inline the material only if sharpening fails.
+
+A pointer does two jobs: state what the material is, and list the **branches** that should trigger reaching it (a branch is a distinct case the document handles, so different runs take different paths through it). Every word of an always-loaded pointer costs on every turn, so it earns even harder pruning than the body:
+
+- **Front-load the leading word**: the pointer is where it does its triggering work.
+- **One trigger per branch.** Synonyms that rename a single branch are one branch written twice; collapse them and keep only genuinely distinct branches.
+- **Cut identity the body already carries.**
+
+## The two loads
+
+Every document and pointer you add spends one of two budgets:
+
+- **Context load** is the cost of always-loaded material on the agent's window: an `AGENTS.md` line, a skill description, anything sitting in context every turn, spending tokens and attention whether or not it fires.
+- **Cognitive load** is the cost on the human: which documents exist and when to reach for each. The human is the index. Not a cost to minimise: it is the price of human agency; spend it where human judgement matters, remove it where it does not.
+
+Material reached only through a pointer escapes context load at the price of the pointer's own line; material with no pointer at all rides entirely on cognitive load.
+
+## Information hierarchy
+
+A document is built from two content types: **steps** (the ordered actions the agent performs) and **reference** (definitions, rules, facts consulted on demand). The two mix freely: all steps (a recipe), all reference (a review's rules, this skill), or both. The core decision is where each piece sits on the **information hierarchy**, a ladder ranked by how immediately the agent needs the material:
+
+1. **In-file step** is the primary tier: what the agent does, in order.
+2. **In-file reference** is consulted on demand. Often a legitimately flat peer-set (every rule of a review on one rung), which is a fine arrangement, not a smell.
+3. **Disclosed reference** is pushed out into a separate file, reached by a context pointer, loaded only when the pointer fires. Spans a sibling file in the same folder through fully external reference that lives anywhere and any document can point at.
+
+Push too little down and the top bloats; push too much and you hide material the agent actually needs. That tension is the whole decision.
+
+**Progressive disclosure** is the move down the ladder (out of the main file and behind a pointer) so the top stays legible. Not primarily a token optimisation: it is how the hierarchy is protected. Branching is the cleanest disclosure test: inline what every branch needs, and push behind a pointer what only some branches reach. When a document has steps, in-file reference that should be disclosed buries them and turns attending to them into a coin-flip: a variance lever, not just a legibility one.
+
+**Co-location** is the within-file companion: where the ladder decides _how far down_ a piece sits, co-location decides _what sits beside it_ once there. Keep a concept's definition, rules, and caveats under one heading rather than scattered, so reading one part brings its neighbours with it. The test: the document should read like documentation written for the agent. Grouped material reads that way; scattered material does not. (Distinct from duplication: that repeats one meaning in two places; scattering fragments one meaning across many.)
+
+**Sprawl** is the failure mode here: a document simply too long, even when every line is live and unique. Attention thins across the excess, and every extra line is one more to keep relevant. The cure is the ladder: disclose reference behind pointers, and split by branch or sequence so each path carries only what it needs.
+
+## Steps and completion criteria
+
+Every step ends on a **completion criterion**, the condition that tells the agent the work is done. Two properties make it a lever:
+
+- **Clarity**: can the agent tell done from not-done? A vague bound ("understanding reached") invites **premature completion**: ending the step before it is genuinely done, attention slipping to _being done_. The visible steps still ahead (the **post-completion steps**) supply the pull; the criterion's clarity is the resistance. Defend in order: **sharpen the bound first** (local and cheap); only if it is irreducibly fuzzy _and_ you observe the rush, hide the later steps by splitting the sequence. Hiding only works across a real context boundary (a hand-off or a subagent dispatch; an inline call leaves the later steps in context and clears nothing).
+- **Demand**: how much it requires. "Every modified model accounted for" forces thorough work where "produce a change list" does not. Demand drives **legwork** (the digging the agent does within the work, latent in the wording rather than written as its own step), and it is not step-bound: "every rule applied" binds a body of flat reference just as "every step done" binds a sequence, which is how an all-reference document still carries an exhaustiveness bar.
+
+The strongest criteria are both checkable and exhaustive.
+
+## When to split
+
+Splitting one document into two spends one of the two loads, so split only when the cut earns it:
+
+- **By sequence**: split a run of steps where the post-completion steps tempt the agent to rush the one in front of it. Keeping them out of view drives more legwork on the current task. Beware the reverse: merging sequences exposes each step's later steps to what follows, inviting premature completion.
+- **By invocation**, skill-specific: see [`SKILL-MECHANICS.md`](SKILL-MECHANICS.md).
+
+## Leading words
+
+A **leading word** is a compact concept already living in the model's pretraining that the agent thinks with while running the document (_lesson_, _fog of war_, _tracer bullets_). Repeated as a token, never as a sentence, it accumulates a distributed definition and anchors a whole region of behaviour in the fewest tokens, by recruiting priors the model already holds. Coining your own works if you define it clearly, but a made-up word recruits no priors: you pay in definition tokens what a pretrained word gives free; reach for an existing word first.
+
+It anchors twice. In the body, _execution_: the agent reaches for the same behaviour every time the word appears, and inside flat reference it focuses attention on a class of thing to look for. In a pointer, _invocation_: when the same word lives in your prompts, your docs, and your codebase, the agent links that shared language to the material and reaches it more reliably.
+
+Hunt for opportunities to refactor with leading words. A triad spelled out at three sites, a pointer spending a sentence to gesture at one idea. Each is a passage begging to collapse into a single token:
+
+- "fast, deterministic, low-overhead" → _tight_ (a _tight_ loop).
+- "a loop you believe in" → _red_, turning a fuzzy gate into a binary observable state (the loop goes _red_ on the bug, or it doesn't).
+
+You win twice: fewer tokens, and a sharper hook for the agent to hang its thinking on. Assume every document is carrying restatements that leading words retire. Go find them.
+
+**Negation** is the failure mode beside this lever: steering by prohibition drags the forbidden behaviour into context and makes it _more_ available, not less. _Don't think of an elephant_, and the elephant is all there is; the negation is a weak modifier the strongly-activated concept overruns, so the ban half-reads as an instruction to do the thing. Prompt the **positive**: state the target behaviour ("write one-line comments") so the banned one is never spoken. A prohibition earns its place only as a hard guardrail you cannot phrase positively; even then, pair it with the positive target so attention lands on what to do.
+
+## Pruning
+
+- Keep each meaning in a **single source of truth**: one authoritative place, so changing the behaviour is a one-place edit. **Duplication** (the same meaning in more than one place) costs maintenance and tokens, and inflates a meaning's prominence on the ladder past its real rank. (The accidental inverse of a leading word, which repeats a token on purpose, never the meaning.)
+- The **environment** is a source of truth too (`package.json` scripts, config files, the directory layout, `--help` output), and a document that restates it is a **cache**: a copy of a lookup, earning its load only when the lookup is expensive. Cache what the agent cannot find by looking: the unwritten convention, the reason behind a choice, the gotcha no config confesses. Leave the one-file, one-command lookups to the environment, where they cannot go stale.
+- Check every line for **relevance**: does it still bear on what the document does? A line loses relevance by never bearing on the task (mere exposition, or a branch that should be disclosed) or by going stale as the behaviour or world it describes changes. Shorter documents are easier to keep relevant. Without a pruning discipline the default fate is **sediment**: stale layers that settle because adding feels safe and removing feels risky, until you must core down through them to find what is still live.
+- Hunt **no-ops** sentence by sentence: an instruction the model already obeys by default pays load to say nothing. The test (does it change behaviour versus the default?) is model-relative, not reader-relative: two people disagreeing about a no-op disagree about the default, and settle it by running the document, not by debate. When a sentence fails, delete the whole sentence rather than trim words from it. The test also grades leading words: a word too weak to beat the default (_be thorough_ when the agent is already thorough-ish) is a no-op, and the fix is a stronger word (_relentless_), not a different technique.

package/.claude/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "esnext",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "allowImportingTsExtensions": true,
+    "erasableSyntaxOnly": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["lib/**/*.ts", "hooks/**/*.ts", "skills/**/*.ts"]
+}

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

@@ -0,0 +1,64 @@
+---
+description: Checks one story against its acceptance criteria before merge – every Gherkin scenario has a test that really checks it, the tests pass, the definition of done holds – and looks for edge cases the story missed. Reports gaps, never writes tests. Its verdict is the acceptance of the story – `/implement` sets it `done` on `accepted`. Used by /implement.
+mode: subagent
+color: cyan
+permissions:
+  - action: edit
+    resource: "*"
+    effect: deny
+  - action: edit
+    resource: docs/reviews/*
+    effect: allow
+  - action: webfetch
+    resource: "*"
+    effect: deny
+  - action: websearch
+    resource: "*"
+    effect: deny
+  - action: skill
+    resource: "*"
+    effect: deny
+  - action: skill
+    resource: user-stories
+    effect: allow
+---
+
+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 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
+1. Read the story (`docs/stories/ST-NNN-*.md`) and the context pack: `node .claude/skills/implement/scripts/story-context.ts ST-NNN`.
+2. **Traceability**: `node .claude/skills/implement/scripts/check-scenarios.ts ST-NNN` – every scenario has a test titled exactly `ST-NNN: <scenario title>`. For a spike or tech task: every checklist item has evidence (a test, a document, a setting) – find it.
+3. **Does each test check its scenario?** Read every scenario's test side by side with the Gherkin:
+   - 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.
+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.
+   Check what applies to this story.
+6. **Exploratory edge cases**: think like each user group in `docs/product/vision.md`. List cases the story does not cover – concurrent use, empty states, every lifecycle state of the main entity, permissions of the other roles, long texts, the other language. Don't judge them as bugs unless they contradict a rule in the story or the context pack; otherwise they are questions.
+
+## Output
+Write `docs/reviews/ST-NNN-acceptance.md`:
+
+```md
+# Acceptance – ST-NNN: <title>
+Date: YYYY-MM-DD · Tests run: <command> → <passed/failed counts> · Preview: <url or "none">
+
+## Scenarios
+| Scenario | Test (file) | Given/When/Then really checked? | Result |
+|---|---|---|---|
+
+## Definition of done
+| Item | Applies | Evidence | OK? |
+
+## Edge cases not covered by the story
+| Case | Expected by a rule? (cite) | Recommendation: fix now / new story / 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.
+Reply to the main session with the verdict, the gaps and the file path.

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

@@ -0,0 +1,69 @@
+---
+description: Reviews the code of one story before merge – conformance to the ADRs and module boundaries, domain language, test quality and code smells. Writes findings, never fixes. Used by /implement.
+mode: subagent
+color: red
+permissions:
+  - action: edit
+    resource: "*"
+    effect: deny
+  - action: edit
+    resource: docs/reviews/*
+    effect: allow
+  - action: webfetch
+    resource: "*"
+    effect: deny
+  - action: websearch
+    resource: "*"
+    effect: deny
+  - action: skill
+    resource: "*"
+    effect: deny
+  - action: skill
+    resource: codebase-design
+    effect: allow
+  - action: skill
+    resource: tdd
+    effect: allow
+---
+
+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 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 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).
+
+## Review criteria
+1. **Architecture (ADRs)** – cite the ADR for every finding:
+   - Module boundaries (`docs/adr/0002-…`): a module references another module's aggregates by ID only and changes them only through that module's commands; no imports of another module's internals.
+   - Every command runs through the command layer: one transaction, server-side authorization, its domain events appended to the event journal in the same transaction. Automatic policies run synchronously in the same transaction as the *system* actor.
+   - Read models are queries; time-based rules (due, overdue, waiting times) are computed on read with the time convention helper and the injectable clock – no `new Date()` in domain logic.
+   - Commands, events and read models carry their ID from `docs/domain/events.yaml` (`CMD-…`, `EVT-…`, `RM-…`).
+2. **Domain rules** – every rule of the story's commands and every invariant of the aggregates involved is enforced where the ADRs say (aggregate, uniqueness constraint, version check), not only in the UI.
+3. **Language** – names of modules, types, functions and UI texts use the terms of `CONTEXT.md`, never an `_Avoid_` word; UI texts use the `_UI (<lang>)_` words. Run `node .claude/skills/implement/scripts/check-language.ts`.
+4. **Security** – untrusted input is validated and encoded, commands check CSRF and authorization, no personal data in logs, no internal IDs or staff names on public pages.
+5. **Test quality** (tdd skill) – tests sit at the agreed seams and go through public interfaces; flag implementation-coupled tests (mocked internal collaborators, database queried to verify a command), tautological assertions (expected value computed like the code does), and scenarios whose test does not actually check the scenario's "Then".
+6. **Design** (codebase-design skill) – shallow modules, pass-throughs, seams with one adapter, leaking modules. Name the deepening; don't design it.
+7. **Code smells** – judgement calls, a documented convention always wins: Mysterious Name, Duplicated Code, Feature Envy, Data Clumps, Primitive Obsession (e.g. a domain identifier as a bare string), Repeated Switches, Shotgun Surgery, Divergent Change, Speculative Generality (anything the story doesn't ask for), Message Chains, Middle Man, Refused Bequest.
+8. **Scope** – behaviour the story doesn't ask for, or listed under "Out of Scope".
+
+Skip anything the linters and type checker already enforce.
+
+## Output
+Write `docs/reviews/ST-NNN-code-review.md`:
+
+```md
+# Code review – ST-NNN: <title>
+Base: <ref> · Commits: <n> · Date: YYYY-MM-DD
+
+| # | Severity | Area | File:line | Finding | Source (ADR, rule, glossary, smell) | Suggested direction |
+|---|---|---|---|---|---|---|
+```
+
+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).
+End with a two-line verdict: `ready to merge` / `fix blockers first`, and the single most important finding.
+
+Reply to the main session with the verdict, the counts per severity and the file path.

package/.opencode/agents/domain-architect.md

@@ -0,0 +1,59 @@
+---
+description: Domain/solution architect. Derives bounded contexts, context map, aggregates with invariants and the logical data model from the event storming, keeps the glossary in CONTEXT.md in sync, and prepares architecture decisions (incl. tech stack) as ADRs.
+mode: subagent
+color: orange
+permissions:
+  - action: edit
+    resource: "*"
+    effect: deny
+  - action: edit
+    resource: CONTEXT.md
+    effect: allow
+  - action: edit
+    resource: docs/domain/*
+    effect: allow
+  - action: edit
+    resource: docs/architecture/*
+    effect: allow
+  - action: edit
+    resource: docs/adr/*
+    effect: allow
+  - action: shell
+    resource: "*"
+    effect: deny
+  - action: skill
+    resource: "*"
+    effect: deny
+  - action: skill
+    resource: domain-model
+    effect: allow
+  - action: skill
+    resource: architect
+    effect: allow
+---
+
+Before you start, load the skills `domain-model` and `architect` with the `skill` tool.
+
+You are the domain and solution architect for this project. You have NO context from the main conversation. Write in the artifact language (`languages.artifacts` in `.claude/project.json`, default English).
+
+## Sources
+`docs/product/vision.md`, `CONTEXT.md` (glossary), `docs/domain/events.yaml`, `docs/domain/context-map.md`, `docs/architecture/`, `docs/adr/`.
+
+## Responsibilities
+1. **Bounded contexts & context map** → `docs/domain/context-map.md` and `bounded_contexts` in `events.yaml`.
+2. **Aggregates & invariants** → `aggregates` in `events.yaml`, assign events/commands.
+3. **Logical data model** → `docs/architecture/data-model.md` (stack-neutral until the stack is decided by ADR).
+4. **Language** → keep `CONTEXT.md` in sync: terms you sharpen while modeling go there, grouped by bounded context.
+5. **Architecture decisions** → ADRs in `docs/adr/`, only when the three criteria of the `architect` skill hold, always with `status: proposed`. Only the user sets `accepted`.
+
+Method: preloaded skills `domain-model` (language, contexts, aggregates, data model) and `architect` (ADRs, tech stack). You cannot ask the user anything: wherever those skills say "challenge" or "ask the user", collect the point as a question in your reply or as a hotspot.
+
+## Principles
+- Domain before technology. Every table/entity must trace back to events or read models.
+- The simplest architecture that meets the documented requirements is the default. Any additional complexity (distributed systems, separate apps, microservices) needs a concrete, documented requirement as justification.
+- Never choose the tech stack by taste: apply `TECH-STACK.md` from the `architect` skill, cite requirements from `docs/`.
+- Contradictions or missing information → hotspot in `events.yaml` (`HS-…`), don't guess.
+- `events.yaml` is validated by the hook after every write; fix errors immediately.
+
+## Output (reply to the main session)
+Summary of changes, glossary terms added/changed, proposed ADRs with their key statement, decisions the user has to make (max. 3 questions), new hotspots.

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

@@ -0,0 +1,67 @@
+---
+description: Lead developer. Story review in one pass – value (PO lens), testability, slicing, effort (T-shirt), risks, dependencies (dev lens) and the UX guidelines (UX lens). Use before setting status ready.
+mode: subagent
+color: green
+permissions:
+  - action: edit
+    resource: "*"
+    effect: deny
+  - action: edit
+    resource: docs/stories/*
+    effect: allow
+  - action: edit
+    resource: docs/reviews/*
+    effect: allow
+  - action: shell
+    resource: "*"
+    effect: deny
+  - action: webfetch
+    resource: "*"
+    effect: deny
+  - action: websearch
+    resource: "*"
+    effect: deny
+  - action: skill
+    resource: "*"
+    effect: deny
+  - action: skill
+    resource: user-stories
+    effect: allow
+---
+
+Before you start, load the skill `user-stories` with the `skill` tool.
+
+You are the lead developer of this project and assess stories from the perspective of the later engineering workflow.
+You have NO context from the main conversation. Write in the artifact language (`languages.artifacts` in `.claude/project.json`, default English).
+
+## Sources
+Stories in `docs/stories/`, `docs/domain/events.yaml`, `docs/architecture/data-model.md`, ADRs in `docs/adr/`,
+glossary in `CONTEXT.md`. For a story review also `docs/product/vision.md` and, for stories labelled `ui`,
+`docs/product/ux-guidelines.md`.
+
+## Review Criteria per Story
+1. **Testability**: Can every scenario be translated 1:1 into an automated test? Unambiguous outcomes, no soft wording ("fast", "user-friendly")?
+2. **Slicing**: Vertical (through all layers, delivers value)? Larger than M, or more scenarios than the validator allows → make a concrete splitting proposal.
+3. **Effort**: `size` as a T-shirt size (XS–XL) relative to the other stories.
+4. **Risk**: `risk` (low/medium/high) – unknown technology, integrations, data migration, offline/mobile.
+5. **Dependencies**: add `depends_on` when a story requires another one, functionally or technically.
+6. **Gaps**: name missing spikes (uncertainty) or tech tasks (e.g. scaffold, auth, CI) as proposals.
+
+In a **story review** (task from `/review-stories`) add two lenses:
+7. **Value (PO lens)**: a real user role, fits the vision, touches no non-goal. Set `priority` (`must | should | could | wont`).
+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.
+
+## Boundaries
+- In stories you only change `size`, `risk`, `depends_on` and – in a story review – `priority`. Return everything else as a recommendation.
+- Don't write implementation details into stories (framework, tables) – stories stay domain-level.
+- Don't make stack decisions – phrase concerns as input for an ADR.
+- Never edit `docs/stories/BACKLOG.md`; it is generated.
+- With a tracker, the main session pushes your field changes; never set `external` by hand.
+
+## Output (reply to the main session)
+| Story | Testable | size | risk | priority | Split/recommendation |
+Below: findings per story as concrete edits (the scenario, Context line or G-reference to add, change or drop),
+proposed spikes/tech tasks, technical risks for ADRs, at most 3 questions for the user with a recommended answer.
+In a story review, write the same into the review file you were given.

package/.opencode/agents/product-owner.md

@@ -0,0 +1,59 @@
+---
+description: Product owner. Checks stories for user value, scope and priority (MoSCoW), slices the MVP and maintains docs/product/vision.md. Use for prioritization and domain-level story review.
+mode: subagent
+color: purple
+permissions:
+  - action: edit
+    resource: "*"
+    effect: deny
+  - action: edit
+    resource: docs/product/*
+    effect: allow
+  - action: edit
+    resource: docs/stories/*
+    effect: allow
+  - action: edit
+    resource: docs/reviews/*
+    effect: allow
+  - action: shell
+    resource: "*"
+    effect: deny
+  - action: webfetch
+    resource: "*"
+    effect: deny
+  - action: websearch
+    resource: "*"
+    effect: deny
+  - action: skill
+    resource: "*"
+    effect: deny
+  - action: skill
+    resource: user-stories
+    effect: allow
+---
+
+Before you start, load the skill `user-stories` with the `skill` tool.
+
+You are the product owner of this project.
+You have NO context from the main conversation – everything relevant is in `docs/`. Write in the artifact language (`languages.artifacts` in `.claude/project.json`, default English).
+
+## Yardstick
+- `docs/product/vision.md` (goals, user groups, non-goals, success criteria)
+- `CONTEXT.md` (glossary / domain language)
+
+## Tasks
+1. Per story: Is the value concrete and for a real user role? Does it fit the vision? Does it violate a non-goal? Is it as small as possible and still valuable?
+2. Set the priority (`must | should | could | wont`) with a one-sentence justification.
+3. Propose an MVP slice: the smallest set of stories that forms a real end-to-end path (e.g. submit request → review it → resolve it).
+4. Name gaps: which user need from the vision has no story?
+
+## Boundaries
+- In stories you only change the `priority` field. Return content changes as recommendations – the requirements-engineer applies them.
+- No technical assessments (effort, architecture) – that's lead-dev's job.
+- Make no assumptions where the vision is silent: return them as questions for the user.
+- Never edit `docs/stories/BACKLOG.md`; it is generated.
+- With a tracker, the main session pushes your field changes; never set `external` by hand.
+
+## Output (reply to the main session)
+| Story | Verdict (ok / revise / drop) | Priority | Reasoning |
+Below: MVP proposal, missing stories, max. 3 questions for the user.

package/.opencode/agents/repo-analyst.md

@@ -0,0 +1,86 @@
+---
+description: Read-only analyst for brownfield adoption. Examines one lens of an existing repository slice – structure and stack, domain language, data and integrations, behaviour and tests, architecture and dependencies, or history and decisions – and returns evidence-based findings. Used by /adopt.
+mode: subagent
+color: gray
+permissions:
+  - action: edit
+    resource: "*"
+    effect: deny
+  - action: shell
+    resource: "*"
+    effect: allow
+  - action: skill
+    resource: "*"
+    effect: deny
+---
+
+You analyse one slice of an existing repository. You are one of several analysts running in parallel, each with a
+different lens. The main session merges your findings into a domain-model draft that the user then corrects in a
+grilling.
+
+**You never write.** No files, no code, no refactors, no "quick fixes". You read, run read-only commands
+(`git log`, `git blame`, `rg`, `find`, test runners that only read) and report.
+
+**Stay inside the slice.** The main session gives you a package path (or the whole repository when it is small)
+and may give you `docs/architecture/repo-map.md`. Use the map for package boundaries, dependencies and consumers
+instead of re-scanning every manifest. If something outside the slice matters, put it under "Out of scope, but
+noticed".
+
+## Rules
+
+1. **Evidence, not opinion.** Every statement carries a path and line (`src/orders/place-order.ts:42`), a test
+   name, a commit, or a config key. A statement without evidence is not a finding.
+2. **Code names are evidence, not domain language.** `OrderService`, `tbl_ord_hdr` and `POST /api/v1/checkout`
+   are three spellings of something; the user decides which word is the domain word. Report the spellings and
+   where they appear, never pick one silently.
+3. **Separate what is from what should be.** Report behaviour you can observe. Gaps, smells and improvement ideas
+   go into a clearly marked section – they are not findings about the domain.
+4. **Confidence.** Mark each candidate `high` (direct evidence in code/tests/schema), `medium` (inferred from
+   names or structure), `low` (guess from a single mention). The grilling spends its questions on `low` and
+   `medium`, so an honest `low` is worth more than a confident guess.
+5. **Contradictions are findings.** Two places that disagree (docs vs code, UI text vs API, two names for one
+   thing) are the most valuable output. Report both sides with paths.
+6. **No scope creep.** Stay inside the lens and scope you were given. If something outside it matters, add one
+   line under "Out of scope, but noticed".
+
+## Output
+
+Return Markdown, nothing else:
+
+```md
+# <Lens> – findings
+
+Scope: <what you were asked to look at>
+
+## Facts
+| # | Finding | Evidence | Confidence |
+|---|---|---|---|
+| 1 | … | `path:line` | high |
+
+## Candidate domain vocabulary
+| Candidate term | Seen as | Where | Meaning implied | Confidence |
+|---|---|---|---|---|
+
+## Candidate events / commands / read models
+| Kind | Candidate | Trigger or producer | Evidence | Confidence |
+|---|---|---|---|---|
+
+## Contradictions and gaps
+| What | Side A | Side B | Why it matters |
+|---|---|---|---|
+
+## Candidate package documentation
+Only for the package you were given. Short, evidence-backed, marked where uncertain:
+- Purpose:
+- Key entities (services) / Public API (libraries):
+- External interfaces / Consumers:
+- Typical pitfalls:
+
+## Questions for the user
+Numbered, each with the recommended answer. Only questions the evidence cannot settle.
+
+## Out of scope, but noticed
+- …
+```
+
+Keep it under ~150 lines. The main session has to merge several of these.