kataster 0.0.0-stage → 0.2.0

package/templates/conventions.md

@@ -0,0 +1,63 @@
+# Engineering conventions – {{project}}
+
+<!--
+  How the code is built here. The ADRs decide WHAT; this file says HOW. `/adopt` fills it from the
+  existing codebase; a greenfield project writes it after the first foundation stories, when the shapes
+  actually exist (not before).
+
+  Keep it factual and short enough to be read before writing a story. When code and this file disagree,
+  raise it – don't silently follow either.
+
+  It must answer, for this repository:
+-->
+
+## Module layout
+
+[OPEN] Which directories exist, what belongs in each, and which imports are allowed across them?
+
+## Monorepo and shared libraries
+
+[OPEN] Which tool builds and tests across packages (Nx, Turborepo, Bazel, pnpm/npm/yarn workspaces, Go, Cargo,
+Gradle, Maven)? How do you run one package, and how do you run only affected tests? What may a shared library
+import, and who are its consumers? The generated overview is in `docs/architecture/repo-map.md`; `repo-map`
+stores the build tool's graph (Turbo, Nx, Bazel) and `affected.ts` turns changed files into the native command.
+
+## Architecture enforcement
+
+[OPEN] Which rules are checked deterministically, and where? `docs/architecture/boundaries.yaml` holds the
+allowed/forbidden edges (first match wins), `docs/engineering/checks.yaml` decides what runs at edit time and at
+Stop/CI, and `.claude/rules/*.md` holds path-scoped rules a directory cannot express. Existing violations live in
+`docs/architecture/boundaries.baseline.json`; only new ones fail. Name the engine for non-JS/TS stacks
+(dependency-cruiser, Nx module boundaries, Bazel, ArchUnit, import-linter).
+
+## Commands and events
+
+[OPEN] How does a command run (transaction, authorization, version check)? Where do domain events go?
+How are automatic policies triggered? What is the ID convention?
+
+## Read models
+
+[OPEN] Where do queries live, and how do they stay out of the write path?
+
+## Time-based rules
+
+[OPEN] How is "now" injected, so due/overdue rules are testable?
+
+## UI and texts
+
+[OPEN] Where do texts live, which language(s), which shared components/frames exist?
+
+## Test data and seams
+
+[OPEN] Test data builders, fixed clock, database per test run.
+
+### Seam catalog
+
+Which seam each kind of code is tested at. `/implement` only stops for the user when a seam is missing here.
+
+| Kind of code | Seam | Test type | Example |
+|---|---|---|---|
+| Pure domain rule | the rule's public function | unit | – |
+| Command | the command through its public interface | integration | – |
+| Read model | the query | integration | – |
+| Page, form, flow | the browser | e2e | – |

package/templates/docs/adr/README.md

@@ -0,0 +1,7 @@
+# Architecture decisions
+
+`NNNN-slug.md`, sequential, never reused. Format and when to write one:
+`.claude/skills/architect/ADR-FORMAT.md`.
+
+New ADRs start as `proposed`; **only the user sets `accepted`**. Accepted ADRs are never edited – they are
+superseded by a new ADR. The hooks enforce that.

package/templates/docs/architecture/data-model.md

@@ -0,0 +1,31 @@
+# Logical data model – {{project}}
+
+<!--
+  Stack-neutral until an ADR decides the stack. Per aggregate: root entity, entities, value objects,
+  attributes with domain types, required/optional. Lifecycle as a Mermaid stateDiagram-v2, overall view
+  as an erDiagram. Every attribute traces back to an event's `data` or a read model's `fields`;
+  anything without a source is a hotspot.
+-->
+
+## Aggregates
+
+<!--
+### AGG-Example – <name>
+| Attribute | Type | Required | Source |
+|---|---|---|---|
+| … | … | yes | EVT-… |
+-->
+
+## Lifecycle
+
+```mermaid
+stateDiagram-v2
+  %% [*] --> Example
+```
+
+## Overview
+
+```mermaid
+erDiagram
+  %% AGG_EXAMPLE ||--o{ AGG_OTHER : references
+```

package/templates/docs/domain/context-map.md

@@ -0,0 +1,21 @@
+# Context map – {{project}}
+
+<!--
+  One section per bounded context: purpose, core terms, owner role. Relationships as a Mermaid flowchart
+  using the DDD patterns: Customer/Supplier, Conformist, Anti-Corruption Layer, Shared Kernel,
+  Published Language. 2–4 contexts are typical for a small system.
+-->
+
+```mermaid
+flowchart LR
+  %% BC-ExampleA -->|Customer/Supplier| BC-ExampleB
+```
+
+## Contexts
+
+<!--
+### BC-Example – <name>
+Purpose: …
+Core terms: …
+Owner role: …
+-->

package/templates/docs/domain/events.yaml

@@ -0,0 +1,23 @@
+# Event storming model
+#
+# Single source of truth for events, commands, policies, read models, aggregates and bounded contexts.
+# Format: .claude/skills/event-storming/templates/events.example.yaml
+# Schema: .claude/skills/event-storming/schema/events.schema.json
+#
+# Written by /bootstrap, /adopt, /event-storming and /feature. Validated and rendered to
+# docs/domain/event-storming.md after every write. An empty model is valid: it grows during discovery.
+
+version: 1
+domain: {{project}}
+
+events: []
+
+# actors: []
+# external_systems: []
+# bounded_contexts: []
+# aggregates: []
+# commands: []
+# policies: []
+# read_models: []
+# hotspots: []
+# flows: []

package/templates/docs/product/initiatives/README.md

@@ -0,0 +1,41 @@
+# Initiatives
+
+Proposals for ideas larger than one feature, written by `/shape`. An initiative is **not** a work item: it has no
+`ready`/`done`, creates no stories and never replaces `docs/stories/`. It answers four questions and ends with a
+recommendation:
+
+1. Should we do this at all?
+2. Where does it belong – an existing bounded context, a new one, a shared library?
+3. What changes, and what is genuinely new?
+4. What does it roughly cost – in scope, range and risk?
+
+File: `<slug>.md`, one per initiative. Status is `proposed` until the user accepts it; `parked` and `rejected` are
+final until a new initiative replaces them. On handoff to `/feature`, set `promoted: <slug>` and let the stories
+carry the label `feature:<slug>`.
+
+```markdown
+---
+status: proposed          # proposed | accepted | parked | rejected
+created: YYYY-MM-DD
+source: ""                # optional ticket reference
+promoted: ""              # feature:<slug> once slices are handed to /feature
+---
+
+# Initiative: <title>
+
+## Problem & outcome
+## Fit with the vision
+## Placement
+| Capability | Context | New/existing | Why | Confidence |
+## Impact – change vs. build new
+| Dimension | Change | New | Evidence |
+## Slices
+1. …
+## Rough cost
+| Currency | Estimate | Confidence | Basis |
+## Risks & open questions
+## Recommendation
+```
+
+Cost is always a range with a basis and a confidence – never a single number. An unknown is a line in the brief,
+not a silent percentage.

package/templates/docs/product/ux-guidelines.md

@@ -0,0 +1,27 @@
+# UX guidelines – {{project}}
+
+<!--
+  The yardstick, not the method. The method is `.claude/skills/ux-design/SKILL.md`.
+  Every guideline is a rule someone can point at, with the date and the reason it was decided.
+  `ux-designer` maintains this file; the user approves a guideline before it is written here.
+
+  Format:
+  ## G1 – <short rule>
+  <One or two sentences, in the voice of a rule.> (YYYY-MM-DD – reason)
+-->
+
+## Devices and context
+
+[OPEN] Which devices, which screen sizes, which situations? Is there a design size?
+
+## Language
+
+UI language: {{uiLanguage}}. [OPEN] Which terms appear, and which pages are in another language?
+
+## The states every screen needs
+
+[OPEN] Empty, full, rejected, no permission – how does each one look and what does it say?
+
+## Patterns
+
+[OPEN] Recurring decisions (forms keep input after a rejection, lists newest first, …) become G-numbers here.

package/templates/docs/product/vision.md

@@ -0,0 +1,36 @@
+# Vision – {{project}}
+
+<!--
+  Source of truth for scope. `/bootstrap` and `/adopt` grill this file with the user and remove every
+  answered `[OPEN]`. Keep it short enough that someone reads it before a decision.
+-->
+
+## Problem
+
+[OPEN] Which problem does the software solve, for whom, and what happens today without it?
+
+## User groups
+
+| Group | What they need | Where they are |
+|---|---|---|
+| [OPEN] | | |
+
+## Goals
+
+- [OPEN] What must be true for this to be worth building? Make it measurable.
+
+## Non-goals
+
+- [OPEN] What is explicitly out of scope? (As valuable as the goals.)
+
+## Success criteria
+
+- [OPEN] How do we know in three months that this worked?
+
+## Constraints
+
+- [OPEN] Devices, connectivity, languages, legal, budget, deadlines, existing systems.
+
+## Domain in one paragraph
+
+[OPEN] The business in plain language: what moves through the system, who decides what.

package/templates/docs/stories/OPEN_QUESTIONS.md

@@ -0,0 +1,8 @@
+# Open questions
+
+Decisions that block a story or an artifact. One row per question; the answer is written here and the
+`[OPEN]` marker is removed from the artifact.
+
+| Story/artifact | Question | Since | Answer |
+|---|---|---|---|
+| – | – | – | – |

package/templates/docs/stories/README.md

@@ -0,0 +1,26 @@
+# Stories
+
+One Markdown file per story: `ST-NNN-short-title.md`. `BACKLOG.md` is generated – never edit it by hand.
+Rules, format and splitting: `.claude/skills/user-stories/SKILL.md`.
+Template: `.claude/skills/user-stories/templates/story-template.md`.
+
+Workflow: `draft → review → ready → in-progress → done` (plus `superseded`).
+
+- Discovery ends at `ready`; `/implement` moves a story to `in-progress` and `done`.
+- A story that turns out wrong goes back to `review` with an `[OPEN]` and a row in `OPEN_QUESTIONS.md`.
+- `done` is final: a change to finished behaviour is a new story.
+
+## Backlog backend
+
+`docs/stories/` is the backlog when `.claude/project.json` has `backlog.provider: "local"` (the default). With
+`"github"` or `"jira"`, the tracker is the source of truth and this directory is its **local mirror**:
+
+- a story keeps its stable `ST-NNN` id and carries `external: { provider, key, url }`
+- pull before reviewing or implementing, push after creating, changing or approving a story
+- a story must be linked before it reaches `ready`
+- the tracker wins on conflict; the local copy is backed up, never silently lost
+- reviews and `OPEN_QUESTIONS.md` stay local; `BACKLOG.md` is generated from the mirror
+
+Sync with `/backlog-sync`; the rules are in `.claude/skills/backlog/SKILL.md`.
+
+Start with `/bootstrap` (greenfield) or `/adopt` (brownfield), then `/feature` for new work.

package/templates/docs/workflow.md

@@ -0,0 +1,135 @@
+# Workflow – {{project}}
+
+The map of this repository's agent workflow. `AGENTS.md` is the short version loaded into every session; this file
+is what to read when you are unsure where something belongs.
+
+## Two phases
+
+- **Discovery** produces the domain artifacts in `docs/` – including the backlog of stories as Markdown files. It
+  continues for every new feature (`/feature`).
+- **Engineering** implements the `ready` stories one by one with `/implement`. Code and discovery artifacts live in
+  the same repository and change together.
+
+## Sources of truth
+
+| Artifact | File | Owner |
+|---|---|---|
+| Vision, user groups, scope | `docs/product/vision.md` | user + `product-owner` |
+| Initiative briefs (proposals, no stories) | `docs/product/initiatives/<slug>.md` | `/shape`; user accepts |
+| UI/UX decisions (yardstick) | `docs/product/ux-guidelines.md` | `ux-designer` (user approves) |
+| Glossary (ubiquitous language) | `CONTEXT.md` | `domain-model` skill |
+| Event storming model | `docs/domain/events.yaml` | event storming / `domain-architect` |
+| Visualization (generated!) | `docs/domain/event-storming.md` | hook – never edit manually |
+| Context map | `docs/domain/context-map.md` | `domain-architect` |
+| Logical data model | `docs/architecture/data-model.md` | `domain-architect` |
+| Repository map (generated!) | `docs/architecture/repo-map.json`, `docs/architecture/repo-map.md` | `repo-map.ts` – never edit manually |
+| Package docs (loaded on demand) | `<package>/AGENTS.md` + `<package>/CLAUDE.md` | `/adopt`, user confirms the prose |
+| Path-scoped rules | `.claude/rules/*.md` (both harnesses) | `/adopt`, user approves |
+| Architecture boundaries | `docs/architecture/boundaries.yaml` | user confirms; checked by `boundary-check.ts` |
+| Existing boundary debt (generated) | `docs/architecture/boundaries.baseline.json` | `boundary-check.ts --update-baseline` |
+| Project checks (what runs when) | `docs/engineering/checks.yaml` | `/adopt`, user approves |
+| Architecture decisions (ADRs) | `docs/adr/` | `architect` skill / `domain-architect` (user accepts) |
+| Stories | `docs/stories/ST-NNN-*.md` | `requirements-engineer`; status by `/implement`; with a tracker this is the mirror |
+| Backlog backend | `.claude/project.json` → `backlog.provider` – `local`, `github` or `jira` | user |
+| Backlog mirror (with a tracker) | `docs/stories/` | `/backlog-sync` |
+| Backlog (generated!) | `docs/stories/BACKLOG.md` | hook – never edit manually |
+| Open questions | `docs/stories/OPEN_QUESTIONS.md` | everyone |
+| Reviews | `docs/reviews/` | `review-stories`, `acceptance-tester`, `code-reviewer` |
+| Engineering conventions, seam catalog | `docs/engineering/conventions.md` | written after the foundation, user approves |
+| Application code and tests | `repo.codeRoots` in `.claude/project.json` | `/implement` |
+
+## Commands
+
+| Command | Covers |
+|---|---|
+| `/bootstrap` | greenfield: vision → event storming → model → architecture → UX → stories |
+| `/adopt [scope] [--stories]` | brownfield: repo map → one slice (domain + shared library) → evidence → domain draft → package docs → grilling → gap register; stories only with `--stories`; repeat per slice |
+| `/shape <idea \| ticket>` | before a large feature: frame, place (existing/new context, shared library), impact, slices, rough cost range, recommendation; creates no stories; `--dry-run` writes nothing |
+| `boundary-check.ts` | architecture boundaries: `--init`, `--update-baseline`, `--changed`, `--json` |
+| `affected.ts` | monorepo fast loop: changed files or `--base` → affected packages + native test command |
+| `grilling` (`/grill-me`) | relentless interview in rounds with recommended answers – how we ask questions |
+| `/grill-with-docs` | grilling + `domain-model` + `architect`: writes glossary and ADRs as it goes |
+| `/event-storming [process]`, `/feature <idea \| ST-NNN \| ticket>` | discovery entry points; both start by grilling. `/feature` resolves a story or ticket read-only and routes bugs to a regression story |
+| `user-stories`, `/review-stories` | story format, validation, review |
+| `backlog`, `/backlog-sync` | local / GitHub Issues / Jira mirror, sync and conflict rules |
+| `ux-design` | how we decide the interface: the UX frontier, what a story says about a screen, review order |
+| `/groom-backlog` | periodic challenge of the open backlog |
+| `/implement [ST-NNN]` | one story test-first, verify, review, refactor, acceptance, pull request |
+| `tdd` | red → green loop, good tests, seams |
+| `codebase-design` | vocabulary for deep modules |
+| `/improve-codebase-architecture` | periodic scan for deepening opportunities, then grilling |
+| `/retro` | retrospective on a session; the user picks the changes |
+| `writing-for-agents` | how to write skills, agent files and `AGENTS.md` |
+
+## Rules
+
+- **Language.** Artifacts and code are in the artifact language (`languages.artifacts`), UI texts in the UI language
+  (`languages.ui`) – both in `.claude/project.json`. IDs are CamelCase with a prefix (`EVT-OrderPlaced`).
+- **Domain terms exactly as in `CONTEXT.md`**, never an `_Avoid_` synonym – in docs and in code. A new term goes into
+  `CONTEXT.md` first.
+- **Don't guess.** Capture anything unclear as a hotspot (`HS-n` in `events.yaml`) or `[OPEN]` plus a row in
+  `OPEN_QUESTIONS.md`. During implementation, a wrong or unclear story goes back to `review` – never decided in code.
+- **`events.yaml` and stories are validated by a hook after every write**, including status changes. Fix errors
+  immediately; never work around them.
+- **Tech stack only after event storming and domain model**, via ADR. New ADRs are `proposed`; only the user sets
+  `accepted`. Accepted ADRs are never edited, only superseded (a hook enforces it).
+- **The backlog is local by default.** `docs/stories/` is the backlog and no issue tracker is required. With
+  `backlog.provider` = `jira` or `github` in `.claude/project.json`, the tracker is the source of truth and
+  `docs/stories/` is its local mirror; sync through `/backlog-sync` and never edit `BACKLOG.md` by hand. Reviews and
+  open questions stay local. `ST-NNN` stays the stable id; the tracker key lives in `external`.
+- **Traceability in the code**: every Gherkin scenario has a test titled exactly `ST-NNN: <scenario title>`;
+  commands, events, read models and policies carry their ID from `events.yaml`. `verify.ts` checks both.
+- **Status changes** go through `node .claude/skills/implement/scripts/story-status.ts`. A `done` story is never
+  reopened – changes become a new story.
+- **Never weaken or delete a test to get green.** One branch and one pull request per story; the user merges.
+- **Subagents don't know the conversation**: when delegating, pass file paths and a clear task.
+- **Adopt in slices.** One domain plus at most one shared library per session; never the whole monorepo. The
+  ranking in `docs/architecture/repo-map.md` suggests where to start.
+- **The root `AGENTS.md` has no domain.** Structure, commands, hard conventions and links. Domain language lives
+  in `CONTEXT.md`, package reality in `<package>/AGENTS.md` – loaded only when someone works there.
+- **Directory docs before glob rules.** Rules that apply to a directory belong in its `AGENTS.md`; `.claude/rules/`
+  with `paths:` is for patterns a directory cannot express. Claude Code scopes it natively, OpenCode's plugin
+  attaches it when a matching file is read or written – one file, both harnesses.
+- **Checks are green on day one.** Brownfield checks start report-only with a baseline and only new violations
+  fail; a red hook gets switched off. `docs/engineering/checks.yaml` decides what runs at edit time and at
+  Stop/CI; the `project-check.ts` dispatcher is wired once and never per package.
+- **Boundaries are data, not prose.** `docs/architecture/boundaries.yaml` lists the allowed/forbidden edges
+  (first match wins); `boundary-check.ts` enforces them. Existing debt lives in
+  `boundaries.baseline.json` and only shrinks.
+- **A ticket is evidence, not a specification.** When `/feature` starts from an `ST-NNN`, `#issue` or Jira key, the
+  source is recorded in the story (`Source: …`), its acceptance criteria are grilled like any other claim, and
+  `external` is still written only by the backlog sync. A bug is a story with the label `bug`, not a separate type; a
+  change to a documented rule is a feature, because the rule changes.
+- **Initiatives are not a backlog.** `docs/product/initiatives/` holds proposals from `/shape`; they have no
+  `ready`/`done` and create no stories. Only `docs/stories/` is work. Cost is a range with a basis and a
+  confidence – never a single number, never a commitment.
+- **At most 3 questions to the user at once** – except in grilling rounds, which ask the whole frontier.
+
+## Workflow
+
+Discovery, first time: `/bootstrap` (greenfield) or `/adopt` (existing code), then `/review-stories` until stories
+are `ready`. A monorepo is adopted slice by slice: finish one domain plus its shared library, then run
+`/adopt <next path>` – the map keeps track of what is adopted. Later features: `/feature <idea | ticket>`; an idea
+larger than one feature goes through `/shape` first and then `/feature` per slice.
+
+Engineering, story by story: `/implement [ST-NNN]` (empty = next ready story whose dependencies are done):
+prepare → test plan → red/green per scenario → `verify.ts` → review lane scaled to risk → refactor → acceptance
+tester's verdict → `done` + pull request; **the user only merges**. Start the next story in a fresh session.
+
+With a tracker: pull before `/review-stories`, `/groom-backlog` and `/implement`; push after changing or approving
+stories and after `done`. The tracker leads on conflict; `docs/stories/` is the mirror and `BACKLOG.md` stays
+generated from it.
+
+Periodic: `/improve-codebase-architecture` and `/groom-backlog` after a bounded context or about every 8–10 done
+domain stories – not in between. Progress is measured in done domain stories and scenarios, not in story count.
+
+## Tool access
+
+- **`gh`** (optional): with it, `/implement` opens the pull request itself and a GitHub backlog syncs; without it, push
+  and hand the user the compare URL. The session-start hook reports what is missing.
+- **`mcp-atlassian`** (optional, for a Jira backlog): configured in the harness. Jira reads and writes go through the
+  MCP tools; the local mirror keeps validation and traceability deterministic.
+- **Preview provider** (optional, `review.preview` in `.claude/project.json`): with it, acceptance testing uses the
+  branch preview; without it, the reviewers work from the code.
+- Never work around missing access silently (no token in a file, no login in the background) – report it and let the
+  user decide.