kataster 0.0.0-stage → 0.2.0

package/.claude/skills/event-storming/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: event-storming
+description: Facilitates an interactive event storming with the user (big picture or a single process) and maintains docs/domain/events.yaml and the glossary in CONTEXT.md. Starts by grilling the user on the vision. For domain exploration and new business processes.
+disable-model-invocation: true
+argument-hint: "[process/focus, e.g. 'order fulfilment' – empty = big picture]"
+---
+
+# Facilitating Event Storming
+
+You are the facilitator, the user is the domain expert. You propose, they decide.
+Focus of this session: the arguments from the invocation (empty = big picture across the whole domain).
+
+## Preparation
+1. Call the `skill` tool for `grilling` and `domain-model`. Grilling sets how you ask questions; domain-model sets how you guard the language in `CONTEXT.md`.
+2. Read `docs/product/vision.md`, `CONTEXT.md`, `docs/domain/events.yaml`, `docs/domain/context-map.md`.
+3. Format reference: `templates/events.example.yaml` in this skill folder (unrelated example domain – copy the format only, no content).
+
+## Facilitation Rules
+- **Ask like the grilling skill**: numbered questions in rounds, each with your recommended answer; a round asks the whole frontier (everything answerable now). Facts you can look up are your job, decisions are the user's.
+- **Events** are business facts in the past tense: "Order placed", not "Button clicked", and not CRUD ("Record saved").
+- Uncertainties the user can't settle now, conflicts, "it depends" → capture immediately as a **hotspot** (`HS-n`), don't argue them away.
+- **Language**: challenge terms against `CONTEXT.md`, sharpen fuzzy words, and add resolved terms to `CONTEXT.md` the moment they're settled (domain-model skill).
+- No technology: no tables, endpoints, frameworks, screens.
+- Write in the artifact language. IDs: CamelCase with prefix (`EVT-OrderPlaced`); names in plain words using the glossary terms ("Order placed").
+- Write `docs/domain/events.yaml` after **every phase**. The hook validates it and renders `docs/domain/event-storming.md`. If it reports errors: fix them immediately. Warnings are normal in early phases.
+- At the end of each phase: a 3–5 line summary + checkpoint ("Continue with phase X?").
+
+## Phases
+0. **Grill the vision** – Entry point. Grill the user on whatever the focus needs and `docs/product/vision.md` doesn't settle yet: problem, user groups, goals, non-goals, success criteria, constraints (big picture); trigger, participants, outcome and scope boundaries (single process). Continue until the frontier is empty and the user confirms a shared understanding, then update `vision.md` (remove answered `[OPEN]`s) and `CONTEXT.md`.
+1. **Chaotic exploration** – Propose 8–15 suspected events as a starting point. The user deletes, corrects, adds. Ask specifically about exceptions, failure cases and rare events.
+2. **Timeline** – Order events into `flows` (one flow per business process). Mark pivotal events (phase changes) with `pivotal: true`.
+3. **Hotspots** – Systematically collect gaps and contradictions along the timeline, then grill them: resolve the ones the user can decide now (`status: resolved` + `resolution`), keep the rest open.
+4. **Commands & actors** – What triggers each event, and who does it? Capture external systems (`EXT-`). Business rules of the command go into `rules` – only what the command adds beyond the `invariants` of its aggregate, which are stated once, there (user, 2026-10-01).
+5. **Policies** – "Whenever <event>, then <command>". Include time-triggered ones (event with `origin: time`) and manual routines.
+6. **Read models** – What information does an actor need to trigger the command? (`fed_by`, `used_by`, `fields`)
+7. **Aggregates (proposal)** – Which rules must be protected consistently? Rough assignment of commands/events. Detailed work is done by `domain-architect`.
+8. **Bounded contexts (proposal)** – Where do language or responsibility change? Propose rough boundaries.
+
+When focusing on a single process: phases 0–6 for that process (phase 0 only for what the vision doesn't cover yet), 7–8 only if something new emerges.
+
+## Wrap-up
+- Output: number of events/commands/policies/read models, open hotspots, glossary terms added or changed.
+- Run `node .claude/skills/event-storming/scripts/validate-events.ts` and show the result.
+- Propose the next step: `@domain-architect` for context map, aggregates, data model and ADRs.

package/.claude/skills/event-storming/schema/events.schema.json

@@ -0,0 +1,124 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Event storming model (docs/domain/events.yaml)",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "domain", "events"],
+  "properties": {
+    "version": { "const": 1 },
+    "domain": { "type": "string", "minLength": 1 },
+    "actors": { "type": "array", "items": { "$ref": "#/$defs/actor" } },
+    "external_systems": { "type": "array", "items": { "$ref": "#/$defs/external" } },
+    "bounded_contexts": { "type": "array", "items": { "$ref": "#/$defs/context" } },
+    "aggregates": { "type": "array", "items": { "$ref": "#/$defs/aggregate" } },
+    "events": { "type": "array", "items": { "$ref": "#/$defs/event" } },
+    "commands": { "type": "array", "items": { "$ref": "#/$defs/command" } },
+    "policies": { "type": "array", "items": { "$ref": "#/$defs/policy" } },
+    "read_models": { "type": "array", "items": { "$ref": "#/$defs/readModel" } },
+    "hotspots": { "type": "array", "items": { "$ref": "#/$defs/hotspot" } },
+    "flows": { "type": "array", "items": { "$ref": "#/$defs/flow" } }
+  },
+  "$defs": {
+    "text": { "type": "string", "minLength": 1 },
+    "idList": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
+    "actor": {
+      "type": "object", "additionalProperties": false, "required": ["id", "name"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^ACT-[A-Za-z0-9]+$" },
+        "name": { "$ref": "#/$defs/text" },
+        "description": { "type": "string" }
+      }
+    },
+    "external": {
+      "type": "object", "additionalProperties": false, "required": ["id", "name"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^EXT-[A-Za-z0-9]+$" },
+        "name": { "$ref": "#/$defs/text" },
+        "description": { "type": "string" }
+      }
+    },
+    "context": {
+      "type": "object", "additionalProperties": false, "required": ["id", "name", "purpose"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^BC-[A-Za-z0-9]+$" },
+        "name": { "$ref": "#/$defs/text" },
+        "purpose": { "$ref": "#/$defs/text" }
+      }
+    },
+    "aggregate": {
+      "type": "object", "additionalProperties": false, "required": ["id", "name"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^AGG-[A-Za-z0-9]+$" },
+        "name": { "$ref": "#/$defs/text" },
+        "context": { "type": "string" },
+        "invariants": { "type": "array", "items": { "$ref": "#/$defs/text" } },
+        "description": { "type": "string" }
+      }
+    },
+    "event": {
+      "type": "object", "additionalProperties": false, "required": ["id", "name"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^EVT-[A-Za-z0-9]+$" },
+        "name": { "$ref": "#/$defs/text" },
+        "aggregate": { "type": "string" },
+        "context": { "type": "string" },
+        "origin": { "enum": ["command", "external", "time"] },
+        "pivotal": { "type": "boolean" },
+        "data": { "type": "array", "items": { "$ref": "#/$defs/text" } },
+        "description": { "type": "string" }
+      }
+    },
+    "command": {
+      "type": "object", "additionalProperties": false, "required": ["id", "name", "produces"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^CMD-[A-Za-z0-9]+$" },
+        "name": { "$ref": "#/$defs/text" },
+        "actor": { "type": "string" },
+        "aggregate": { "type": "string" },
+        "produces": { "$ref": "#/$defs/idList", "minItems": 1 },
+        "rules": { "type": "array", "items": { "$ref": "#/$defs/text" } },
+        "description": { "type": "string" }
+      }
+    },
+    "policy": {
+      "type": "object", "additionalProperties": false, "required": ["id", "name", "when", "then"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^POL-[A-Za-z0-9]+$" },
+        "name": { "$ref": "#/$defs/text" },
+        "when": { "$ref": "#/$defs/idList" },
+        "then": { "$ref": "#/$defs/idList" },
+        "description": { "type": "string" }
+      }
+    },
+    "readModel": {
+      "type": "object", "additionalProperties": false, "required": ["id", "name", "fed_by"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^RM-[A-Za-z0-9]+$" },
+        "name": { "$ref": "#/$defs/text" },
+        "fed_by": { "$ref": "#/$defs/idList" },
+        "used_by": { "$ref": "#/$defs/idList" },
+        "fields": { "type": "array", "items": { "$ref": "#/$defs/text" } },
+        "description": { "type": "string" }
+      }
+    },
+    "hotspot": {
+      "type": "object", "additionalProperties": false, "required": ["id", "question"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^HS-[0-9]+$" },
+        "question": { "$ref": "#/$defs/text" },
+        "refs": { "$ref": "#/$defs/idList" },
+        "status": { "enum": ["open", "resolved"] },
+        "resolution": { "type": "string" }
+      }
+    },
+    "flow": {
+      "type": "object", "additionalProperties": false, "required": ["id", "name", "sequence"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^FLOW-[A-Za-z0-9]+$" },
+        "name": { "$ref": "#/$defs/text" },
+        "description": { "type": "string" },
+        "sequence": { "$ref": "#/$defs/idList", "minItems": 1 }
+      }
+    }
+  }
+}

package/.claude/skills/event-storming/scripts/render-event-storming.ts

@@ -0,0 +1,11 @@
+/** Renders docs/domain/event-storming.md from docs/domain/events.yaml (only if the model is valid). */
+import * as d from "../../../lib/discovery.ts";
+
+const report = new d.Report();
+const model = d.validateEvents(report);
+if (!report.ok || model === null) {
+  for (const line of report.lines()) console.log(line);
+  console.log("Not rendered – fix the errors first.");
+  process.exit(1);
+}
+console.log(`Written: ${d.rel(d.writeEventStormingMd(model))}`);

package/.claude/skills/event-storming/scripts/validate-events.ts

@@ -0,0 +1,11 @@
+/** Validates docs/domain/events.yaml (schema + references). Exit 1 on errors. */
+import * as d from "../../../lib/discovery.ts";
+
+const report = new d.Report();
+const model = d.validateEvents(report);
+for (const line of report.lines()) console.log(line);
+if (report.ok && model !== null) {
+  const counts = d.LIST_KEYS.map((k) => [k, Array.isArray(model[k]) ? model[k].length : 0] as const).filter(([, n]) => n);
+  console.log("OK – " + counts.map(([k, n]) => `${k}: ${n}`).join(", "));
+}
+process.exit(report.ok ? 0 : 1);

package/.claude/skills/event-storming/templates/events.example.yaml

@@ -0,0 +1,91 @@
+# FORMAT EXAMPLE (unrelated domain: bike rental). Copy the structure only!
+version: 1
+domain: Bike Rental
+
+actors:
+  - id: ACT-Customer
+    name: Customer
+  - id: ACT-Mechanic
+    name: Mechanic
+
+external_systems:
+  - id: EXT-Payment
+    name: Payment provider
+
+bounded_contexts:
+  - id: BC-Rental
+    name: Rental
+    purpose: Renting out and returning bikes
+  - id: BC-Workshop
+    name: Workshop
+    purpose: Maintaining the fleet
+
+aggregates:
+  - id: AGG-Bike
+    name: Bike
+    context: BC-Rental
+    invariants:
+      - A bike can only be rented out once at a time
+      - A bike marked as damaged cannot be rented out
+  - id: AGG-RepairOrder
+    name: Repair order
+    context: BC-Workshop
+
+events:
+  - id: EVT-BikeRented
+    name: Bike rented
+    aggregate: AGG-Bike
+    pivotal: true
+    data: [Bike number, Customer, Start time]
+  - id: EVT-DamageReported
+    name: Damage reported
+    aggregate: AGG-Bike
+    data: [Bike number, Description, Photo]
+  - id: EVT-RepairOrderOpened
+    name: Repair order opened
+    aggregate: AGG-RepairOrder
+  - id: EVT-InspectionDue
+    name: Inspection due
+    origin: time
+    context: BC-Workshop
+
+commands:
+  - id: CMD-RentBike
+    name: Rent bike
+    actor: ACT-Customer
+    aggregate: AGG-Bike
+    produces: [EVT-BikeRented]
+    rules: [Customer has a valid payment method]
+  - id: CMD-ReportDamage
+    name: Report damage
+    actor: ACT-Customer
+    aggregate: AGG-Bike
+    produces: [EVT-DamageReported]
+  - id: CMD-OpenRepairOrder
+    name: Open repair order
+    aggregate: AGG-RepairOrder
+    produces: [EVT-RepairOrderOpened]
+
+policies:
+  - id: POL-DamageCreatesRepair
+    name: Damage creates repair order
+    when: [EVT-DamageReported, EVT-InspectionDue]
+    then: [CMD-OpenRepairOrder]
+
+read_models:
+  - id: RM-AvailableBikes
+    name: Available bikes
+    fed_by: [EVT-BikeRented, EVT-DamageReported]
+    used_by: [ACT-Customer]
+    fields: [Bike number, Location, Type]
+
+hotspots:
+  - id: HS-1
+    question: May a bike with reported minor damage still be rented out?
+    refs: [EVT-DamageReported, AGG-Bike]
+    status: open
+
+flows:
+  - id: FLOW-DamageToRepair
+    name: From damage to repair
+    sequence: [ACT-Customer, CMD-ReportDamage, EVT-DamageReported, POL-DamageCreatesRepair, CMD-OpenRepairOrder, EVT-RepairOrderOpened]

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

@@ -0,0 +1,86 @@
+---
+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.
+disable-model-invocation: true
+argument-hint: "<idea | ST-NNN | #issue | PROJ-123 | URL>"
+---
+
+# 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>`.
+
+## 0. Intake – when the argument is a reference
+
+A reference is `ST-NNN`, `#123`, `PROJ-123`, a GitHub/Jira URL, or a Jira issue passed with `--from <issue.json>`.
+Resolve it before asking anything:
+
+```bash
+node .claude/skills/feature/scripts/intake.ts <reference> --json
+# Jira: fetch the issue with jira_get_issue, write it as JSON, then
+node .claude/skills/feature/scripts/intake.ts PROJ-123 --from <issue.json> --json
+```
+
+The script is read-only. It returns the source, a matching local story (by id or `external`), signals and a `route`.
+Follow the route:
+
+| `route` | What to do |
+|---|---|
+| `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>`. |
+| `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. |
+
+Before grilling, summarize the source in 3–5 lines and ask the user to confirm it – problem, requested behaviour,
+acceptance hints, contradictions. A ticket is **evidence, not a specification**: grill its acceptance criteria,
+separate solution language from the problem, and record contradictions with `CONTEXT.md`, `events.yaml`, ADRs or the
+UX guidelines. Record the source in every derived story as `Source: <ref> (<url>)` under `## Context`. Never write
+`external` by hand – the backlog sync owns it.
+
+### Bug path
+
+A bug is behaviour that contradicts what the model already documents. Check `CONTEXT.md`, `events.yaml`, accepted
+ADRs and `docs/product/ux-guidelines.md` first.
+
+- **Documented behaviour, code deviates** → one story, `type: story`, label `bug`, with a regression scenario that
+  reproduces the report and at least one edge case. No new events or commands; link the affected event if one
+  exists. Then `/review-stories` and `/implement` as usual.
+- **The documented rule itself is wrong** → this is a feature: the rule changes, so run the normal pipeline and say
+  so in the wrap-up.
+- **No model yet** (brownfield not adopted) → do not invent one from the bug; record the finding and point to
+  `/adopt`.
+
+Do not run an event storming for a bug and do not create a feature slug unless the rule changes.
+
+## 1. Preparation
+Read `docs/product/vision.md`, `CONTEXT.md`, `docs/domain/events.yaml`, `docs/domain/context-map.md`, `docs/architecture/data-model.md`, `docs/adr/`, `docs/stories/BACKLOG.md`. Find out what already exists for this idea (events, stories, hotspots) before asking anything. With an intake result, use its source and matching story instead of searching from scratch. If a linked story exists, pull the tracker first (`/backlog-sync pull`) so the mirror is current.
+
+## 2. Grill the idea
+Call the `skill` tool four times, for `grilling`, `domain-model`, `architect` and `ux-design` (the first three are the set of `/grill-with-docs`, which can't be called from a skill). Grill the user until the frontier is empty and they confirm a shared understanding. The grilling carries the three perspectives the story review later only checks – product owner, lead dev, UX. With an intake result, the ticket's claims and the intake's `signals` seed the frontier; unresolved comments and contradictions are the first questions. Typical branches:
+- **PO**: Which problem, for which user group, and what value? Measurable outcome? Does it fit the vision, or touch a non-goal? If it changes scope → update `docs/product/vision.md` with the user. Must vs. could – what ships first?
+- **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`.
+- 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.
+
+## 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.
+
+## 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.
+
+## 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.