kataster 0.0.0-stage → 0.2.1

package/guide/brownfield.md

@@ -0,0 +1,242 @@
+# Brownfield: adopting an existing repository
+
+The repository already works. The goal is not a rewrite and not a documentation exercise – it is to recover the
+domain the code encodes, in the user's language, and then decide what to build next.
+
+```bash
+npx kataster init --brownfield
+# in the harness
+/adopt                      # map the repository, then choose a slice
+/adopt apps/billing         # adopt one package
+/adopt libs/shared-kernel   # adopt a shared library
+```
+
+## Adopt in slices, not in one pass
+
+A monorepo with eighty packages cannot be understood in one session. `/adopt` therefore works in two levels:
+
+1. **Repository map** – deterministic, no questions: which build tool drives the repository, where the packages
+   are, how they depend on each other, which ones change most.
+2. **One slice** – one domain plus at most one shared library. Deep evidence, grilling, package docs, checks.
+   Then the next slice in a later session.
+
+The map is generated from manifests and git history:
+
+- `docs/architecture/repo-map.json` – packages, paths, kinds, internal dependencies, consumers, adoption ranking
+- `docs/architecture/repo-map.md` – the same as a readable map, plus dependency edges and a suggested first slice
+- the **repository block in `AGENTS.md`** – tooling, layout, commands, adopted slices
+- `.claude/project.json` → `repo.tooling` – Nx, Turborepo, Bazel, pnpm/npm/yarn workspaces, Go, Cargo, Gradle, Maven
+
+The map is facts, not domain. It says where code lives, never what a word means.
+
+## What `/adopt` does
+
+### 1. Chooses the slice with you
+
+The ranking weighs recent churn, fan-in and kind – not size. The suggested slice is usually one domain plus the
+shared library it uses most. You can pick another; the rule stays: **one domain, at most one shared library**.
+
+A simple repository without monorepo tooling is one slice – then the whole repository is in scope.
+
+### 2. Reads before it analyses
+
+`CONTEXT.md`, `docs/`, `README*`, `AGENTS.md`/`CLAUDE.md`, existing ADRs. Existing documentation is **primary
+evidence** and outranks inference from code. Contradictions between docs and code are findings.
+
+### 3. Dispatches read-only analysts for the slice
+
+A monorepo gets three lenses:
+
+| Lens | Typical evidence |
+|---|---|
+| Structure, data and entry points | manifests, entry points, schema, migrations, enums, external services, jobs, the slice's dependencies and consumers |
+| Language, behaviour and tests | types, routes, UI texts, errors, validations, permissions, tests as executable specifications |
+| Architecture, dependencies and history | layering and import direction from the repo map, build tooling, config that encodes a decision, `git log` hotspots |
+
+A small repository without monorepo tooling gets the five classic lenses: structure and stack, domain language,
+data and integrations, behaviour and tests, history and decisions.
+
+Each analyst returns facts with `path:line`, candidate vocabulary, candidate events/commands/read models,
+contradictions, and questions with a recommended answer. Confidence is `high`, `medium` or `low`.
+
+### 4. Drafts the slice
+
+- `CONTEXT.md` – the slice's terms, competing spellings under `_Avoid_`
+- `docs/domain/events.yaml` – 10–25 candidate events, commands, actors, read models, flows, hotspots
+- `docs/domain/context-map.md`, `docs/architecture/data-model.md` (as-is)
+- `docs/engineering/conventions.md` – how the code actually works today, including the monorepo tooling
+- `docs/adr/` – de-facto decisions worth recording (`status: proposed`)
+- **package docs** – `<package>/AGENTS.md` plus `<package>/CLAUDE.md`, written by
+  `node .claude/skills/adopt/scripts/package-doc.ts <path>`
+
+Everything uncertain is marked. The draft is a proposal, not a verdict.
+
+### 5. Grills you against the draft
+
+This is the core. Rounds of numbered questions on the frontier, each with a recommended answer:
+
+> **Q1 – One concept, three names.** You call it `Order`, `Purchase` and `Checkout` in three places
+> (`src/orders/*`, `src/api/checkout.ts`, `messages/en.json`). Is it one concept, and which is the domain word?
+>
+> ➡️ One concept, "Order"; `Checkout` is the UI action, `Purchase` should be avoided.
+
+Answers update `CONTEXT.md`, `events.yaml` and the package's `AGENTS.md` immediately. Resolved hotspots get a
+resolution; new uncertainty becomes a new hotspot.
+
+### 6. Builds the safety net
+
+For every confirmed hard rule, choose the cheapest deterministic enforcement: type system, lint/boundary check,
+architecture or characterization test, hook, or documentation only. Brownfield checks start **report-only** with a
+baseline of existing violations; only new violations fail. A hook that is red on day one gets switched off.
+
+`/adopt` may add characterization tests and tooling. It never changes production code, and it never writes a test
+that fails on existing behaviour – that would be a story.
+
+### 7. Records the gap – stories only on request
+
+| Class | Default |
+|---|---|
+| Exists and is intended | Documentation (data model, context map) – no action |
+| Exists but contradicts the model | Candidate in the gap register |
+| Missing | Candidate in the gap register |
+| Dead | Candidate: removal or an explicit "leave it" |
+
+**The first adoption pass creates no stories.** It records the gap in `docs/domain/adoption-report.md` (and open
+questions in `OPEN_QUESTIONS.md`), so the model can be reviewed before anyone commits to work. Only
+`/adopt <scope> --stories` (or an explicit "turn these into stories") delegates the selected gaps to
+`requirements-engineer`.
+
+**Behaviour that already works does not become a story.** That turns the backlog into a description of the past.
+
+### 8. Writes the report and marks the slice adopted
+
+`docs/domain/adoption-report.md`: scope, map and slice, facts, confirmed model, package docs, contradictions, rules
+and checks, gaps, what was deliberately left alone, open hotspots, next slice.
+
+```bash
+node .claude/skills/adopt/scripts/repo-map.ts --adopt apps/billing
+```
+
+The next session sees the progress in `AGENTS.md` and the map, and starts the next slice with
+`/adopt <path>`.
+
+## What lives where
+
+| File | Loaded | Contains |
+|---|---|---|
+| `AGENTS.md` (root) | every session | repository structure, commands, hard conventions, links – **no domain** |
+| `<package>/AGENTS.md` | when working in that package | purpose, key entities or public API, interfaces, pitfalls, boundaries |
+| `<package>/CLAUDE.md` | same, for Claude Code | one line: `@AGENTS.md` |
+| `<group>/AGENTS.md` | when working under that group | rules for a whole group, e.g. `libs/**` – plus `<group>/CLAUDE.md` |
+| `.claude/rules/*.md` | when a matching file is touched (both harnesses) | path-scoped rules for patterns a directory cannot express |
+| `docs/architecture/boundaries.yaml` | on demand / on check | allowed and forbidden dependency edges (first match wins) |
+| `docs/architecture/boundaries.baseline.json` | on check | existing violations, so only new ones fail |
+| `docs/engineering/checks.yaml` | on check | what runs at edit time and at Stop/CI |
+| `docs/architecture/repo-map.md` | on demand | generated map: packages, edges, consumers, ranking |
+| `CONTEXT.md` | every session | the domain language |
+
+Nested `AGENTS.md` is loaded on demand by OpenCode; Claude Code loads the nested `CLAUDE.md` when it reads or
+edits a file there. That is why every package gets both files.
+
+## Monorepos and shared libraries
+
+The detected tool is used, not re-implemented:
+
+| Tool | One package | Affected only |
+|---|---|---|
+| Nx | `nx run <project>:test` | `nx affected -t test` |
+| Turborepo | `turbo run test --filter=<package>` | `turbo run test --filter='...[HEAD^1]'` |
+| Bazel | `bazel test //<package>/...` | – (query at work time) |
+| pnpm | `pnpm --filter <package> test` | `pnpm -r --filter '...[HEAD^1]' test` |
+| npm/yarn workspaces | `npm run test --workspace <package>` / `yarn workspace <package> test` | – |
+| Go / Cargo / Gradle / Maven | language-specific, in the package doc | – |
+
+When a shared library changes, its consumers from the map are the first thing to check; run their tests or the
+affected set. The library's `AGENTS.md` records its public API, consumers and compatibility rules.
+
+The map asks the build tool for its own graph and stores it as an optional `toolGraph` next to the manifest
+graph – Turborepo via `turbo run <task> --dry=json`, Nx via `nx graph --file=<temp>`, Bazel from the `deps`
+attributes in `BUILD`/`BUILD.bazel`. The fast loop then uses it:
+
+```bash
+# which packages are affected by these files, including shared-library dependents?
+node .claude/skills/implement/scripts/affected.ts --changed libs/shared-kernel/src/index.ts
+
+# or against a base ref; the tool's native affected filter is emitted
+node .claude/skills/implement/scripts/affected.ts --base origin/main
+
+# execute the printed command
+node .claude/skills/implement/scripts/affected.ts --changed apps/billing/src/index.ts --run
+```
+
+The output is a native command: Turborepo gets `turbo run test --filter=…`, Nx `nx run-many -p …` or
+`nx affected`, Bazel `bazel test //pkg/...`, and so on. Nx project names are resolved from the graph, so
+`billing` and `@acme/billing` do not have to match. If the tool is not installed (or does not answer), the
+manifest graph is used instead – the workflow never depends on the tool being present.
+
+## Rules, boundaries and checks
+
+Confirmed architecture rules become deterministic, not prose:
+
+```bash
+node .claude/skills/adopt/scripts/boundary-check.ts --init
+# edit docs/architecture/boundaries.yaml with the rules the user confirmed
+node .claude/skills/adopt/scripts/boundary-check.ts --update-baseline
+node .claude/skills/adopt/scripts/boundary-check.ts
+```
+
+`boundaries.yaml` holds edges, not stories:
+
+```yaml
+version: 1
+engine: auto          # scan JS/TS imports, or command for your own tool
+command: ""
+rules:
+  - id: shared-libs-are-leaves
+    from: "libs/**"
+    to: ["apps/**", "services/**"]
+    effect: deny
+    reason: "Shared libraries never import applications or services."
+```
+
+Rules are evaluated in order; the first matching `from` → `to` pair decides, no match means allow. The `scan`
+engine reads JS/TS imports; `command` runs dependency-cruiser, Nx module boundaries, Bazel, ArchUnit,
+import-linter or your own script and ratchets its failure output.
+
+**Baseline/ratchet:** `--update-baseline` freezes what already exists. After that only new violations fail, so a
+brownfield repository is green on day one and the baseline shrinks over time. The checks are wired once through
+`project-check.ts`; `docs/engineering/checks.yaml` decides which check runs at edit time (changed file only) and
+which at Stop/CI.
+
+Path-scoped rules that a directory cannot express get a file with `paths:`:
+
+```bash
+node .claude/skills/adopt/scripts/rule-doc.ts libs-shared --paths "libs/**" --title "Shared libraries"
+```
+
+A rule for a whole directory belongs in `<dir>/AGENTS.md` (plus its one-line `CLAUDE.md`) – that is the mechanism
+both harnesses load on demand. Path-scoped rules are read natively by Claude Code; in OpenCode the plugin attaches
+the matching rule as session context as soon as a file under its globs is read or written.
+
+## Rules that make adoption work
+
+- **Adopt in slices.** One bounded context completely beats the whole repository shallowly.
+- **Code names are evidence, not language.** `OrderService.place()` suggests "Order placed"; the user decides.
+- **Never change production code.** The output is language, model, decisions, docs and checks.
+- **An 80% confirmed model with 20% hotspots beats a 100% invented one.**
+- **The user owns the language.** Propose a better word; don't rename the domain alone.
+- **The root `AGENTS.md` stays free of domain.** Structure and commands only.
+
+## After adoption
+
+```bash
+git diff                    # only CONTEXT.md, docs/, package docs and tooling changed
+/adopt <next>               # next slice
+/adopt <scope> --stories    # turn the selected gaps into stories, when you want a backlog
+/feature <idea | ticket>    # next work, now that the domain has a language
+/shape <large idea>         # new service/context/migration: placement, impact, slices, cost range
+/implement                  # once a story is ready
+```
+
+With a tracker (`backlog.provider` = `github` or `jira`), pull before adopting or reviewing and push the derived
+stories afterwards. The tracker is the source of truth; `docs/stories/` is the mirror.

package/guide/concepts.md

@@ -0,0 +1,109 @@
+# Concepts
+
+The vocabulary the workflow uses, and why each piece exists.
+
+## Grilling
+
+An interview in **rounds**. The **frontier** is every decision whose prerequisites are settled – the questions that
+can be asked now without guessing at answers you haven't heard. Each question is numbered and carries a recommended
+answer, worded so that "yes" accepts it. Answers reshape the tree and push the frontier outward.
+
+Two rules make it work:
+
+- **Facts are the agent's job, decisions are the user's.** Files, code, docs, history – look it up. Never ask the
+  user something you could find yourself.
+- **Do not act until the frontier is empty** and the user confirms a shared understanding.
+
+`/grill-me` is the pure form. `/grill-with-docs` adds the glossary and ADRs. Every discovery command embeds it.
+
+## The artifacts
+
+| Artifact | What it is | Who owns it |
+|---|---|---|
+| `CONTEXT.md` | Glossary – the ubiquitous language. One canonical word per concept, alternatives under `_Avoid_` | user, maintained by the agent |
+| `docs/domain/events.yaml` | Event storming model: actors, contexts, aggregates, events, commands, policies, read models, hotspots, flows | user, written by the agent |
+| `docs/domain/context-map.md` | Bounded contexts and their relationships (DDD patterns) | domain-architect |
+| `docs/architecture/data-model.md` | Logical, stack-neutral model per aggregate; lifecycle and ER diagrams | domain-architect |
+| `docs/engineering/conventions.md` | How code is built here, including the seam catalog | user |
+| `docs/adr/` | Architecture decisions. `proposed` until the user accepts; accepted ones are superseded, never edited | user |
+| `docs/stories/` | The backlog. One Markdown file per story; `BACKLOG.md` is generated. With a tracker, this is the local mirror | requirements-engineer, PO, lead-dev; `/backlog-sync` with a tracker |
+| `docs/product/vision.md` | Problem, user groups, goals, non-goals, success criteria | user |
+| `docs/product/ux-guidelines.md` | The interface yardstick, as numbered rules with date and reason | ux-designer, approved by user |
+
+## Events, commands, aggregates
+
+- An **event** is a business fact in the past tense: "Order placed". Not a button click, not "Record saved".
+- A **command** is an intent that produces events: "Place order". It has an actor (or a policy) and rules.
+- A **policy** is "whenever <event>, then <command>" – including time-triggered ones.
+- A **read model** is what an actor needs to decide to send a command.
+- An **aggregate** protects the invariants that must be consistent *immediately*. Everything else is eventually
+  consistent via events and policies.
+- An **invariant** is stated once, on the aggregate. A command's rules list only what it adds beyond them.
+
+IDs are prefixed and stable: `ACT-`, `EXT-`, `BC-`, `AGG-`, `EVT-`, `CMD-`, `POL-`, `RM-`, `HS-`, `FLOW-`, `ST-`.
+The code carries the same IDs, which is what makes traceability checkable.
+
+## Stories
+
+A story is a vertical slice of observable behaviour: `draft → review → ready → in-progress → done` (plus
+`superseded`).
+
+- **Discovery ends at `ready`.** Engineering moves `ready → in-progress → done`.
+- **A story that turns out wrong goes back to `review`** with an `[OPEN]` and a row in `OPEN_QUESTIONS.md` – never
+  guessed into shape during implementation.
+- **`done` is final.** A change to finished behaviour is a new story.
+- **At most 10 scenarios.** Each is one red → green cycle. More means split.
+- **A scenario title becomes a test title**: `ST-NNN: <scenario title>`. `verify.ts` checks the link.
+
+### Stories from tickets
+
+`/feature` can start from an `ST-NNN`, a GitHub issue (`#123` or URL), a Jira key or a pasted ticket. The ticket is
+**evidence, not a specification**: its acceptance criteria are grilled like any other claim, contradictions with the
+model are findings, and the source is recorded in the story (`Source: …`). A bug gets one regression story with the
+label `bug`; if the documented rule itself is wrong, it is a feature, because the rule changes. The intake is
+read-only – it never writes stories, `external` links or sync state.
+
+## Initiatives
+
+An **initiative** is a proposal for an idea larger than one feature: a new service, a new bounded context, a
+migration, a cross-context capability. `/shape` writes it to `docs/product/initiatives/<slug>.md` after the user
+confirms the summary. It answers four questions: should we, where does it belong, what changes vs. what is new, and
+what does it roughly cost. It ends with one recommendation: go, go with slice 1, spike first, needs discovery, park
+or no-go.
+
+An initiative is **not** a work item: no `ready`/`done`, no stories, no second backlog. The cost is always a range
+with a basis and a confidence – an analogue service is evidence, not a template. Each accepted slice then goes
+through `/feature`, which creates the stories and runs the review.
+
+## The seam catalog
+
+A **seam** is where a test attaches. Testing everything everywhere is not affordable, so the project agrees up front
+which kind of code is tested at which seam – pure rule, command, read model, page. That catalog lives in
+`docs/engineering/conventions.md`. `/implement` only stops for the user when a story needs a seam that is not in it.
+
+## Review lanes
+
+Review effort follows the risk of the diff, not a fixed checklist:
+
+- **Light lane** – small, no domain events, no command, no migration, no input handling, no new dependency:
+  acceptance tester only.
+- **Normal lane** – code reviewer and acceptance tester in parallel, plus a bug-focused or security-focused pass when
+  the diff touches shared platform code or input/auth/uploads.
+
+## The acceptance verdict
+
+The **acceptance tester decides** whether a story is done, not the user. The user reviews the pull request and
+merges. That keeps one checkpoint with the user (merge) instead of two.
+
+## Why a local mirror
+
+One Markdown file per story, versioned with the code, validated by a hook, rendered into `BACKLOG.md`. The agent can
+read and write it deterministically, and the domain model and the stories can be checked against each other.
+
+That is the whole answer for `backlog.provider: "local"`. Teams that already work in a tracker get the same properties
+with `"github"` or `"jira"`: the tracker is the source of truth, `docs/stories/` is a synchronized mirror, and the
+mirror is what validation, test traceability and offline work run on. The story keeps its `ST-NNN` id; the tracker key
+lives in `external`. Only the backlog core syncs – reviews and open questions stay local. The tracker wins a conflict;
+the local file is backed up before it is overwritten.
+
+GitHub syncs through `gh`; Jira through `mcp-atlassian`, because MCP is reachable only from the agent.

package/guide/greenfield.md

@@ -0,0 +1,84 @@
+# Greenfield: starting a new project
+
+```bash
+npx kataster init --greenfield
+# in the harness
+/bootstrap
+```
+
+The order is fixed: **vision → domain → architecture → UX → stories**. Technology comes after the domain, never
+before it.
+
+For an idea that is larger than one project – several services, a new product line – `/shape` can frame it first.
+Without a domain model it will stop at `unknown` placement and send you back here; that is the correct answer, not
+a failure.
+
+## Phase 1 – Vision
+
+The frontier is every `[OPEN]` in `docs/product/vision.md`: problem, user groups, goals, non-goals, success criteria,
+constraints, the domain in one paragraph. Grilled in rounds, each question with a recommended answer.
+
+Two rules that do the most work:
+
+- **No technology in this phase.** If the user starts with a framework, park it: that is an ADR after the domain,
+  and the domain may change the answer.
+- **Force a non-goal.** A vision without a "we will not do this" is a wish list.
+
+## Phase 2 – Event storming
+
+Big-picture storming, phases 1–6 of the `event-storming` skill:
+
+1. 8–15 suspected events, in the user's words, past tense
+2. Timeline into flows, pivotal events marked
+3. Hotspots, grilled where the user can decide now
+4. Commands and actors
+5. Policies, including time-triggered ones
+6. Read models
+
+`docs/domain/events.yaml` is written after every phase and validated by a hook.
+
+## Phase 3 – Domain model and architecture
+
+`domain-architect` proposes bounded contexts, the context map, aggregates with testable invariants, and the
+logical data model. Then, in this order:
+
+1. **Shape** – the simplest architecture that meets the documented requirements. A monolith is the default;
+   anything distributed cites a requirement.
+2. **Tech stack** – one ADR, `status: proposed`, driving requirements cited. Only the user sets `accepted`.
+3. **Other decisions** – only the ones that pass the architect's three criteria.
+
+## Phase 4 – UX yardstick
+
+Devices and design size, UI language(s), the states every screen needs (empty, full, rejected, no permission), and
+the recurring patterns worth a guideline number. Written as rules into `docs/product/ux-guidelines.md`, with date
+and reason.
+
+## Phase 5 – Foundation stories and the first slice
+
+Two kinds of work, kept apart:
+
+- **Foundation tech tasks** – repository skeleton, one quality command (`verify`), CI, test harness, auth/roles if
+  the vision needs them, deployment. Minimal, with `depends_on`, just in time.
+- **The first vertical slice** – the smallest set of stories that delivers one real end-to-end path from the
+  vision, each with Gherkin scenarios.
+
+At most 10 scenarios per story; no implementation plan inside a domain story; every story links its `events`.
+
+## Phase 6 – Review
+
+`/review-stories` – one lead-dev pass over value, buildability and UX. The user approves every `ready`. With a tracker,
+pull before the review and push the approved stories afterwards (`/backlog-sync`).
+
+## Phase 7 – Build
+
+```bash
+node .claude/skills/implement/scripts/verify.ts   # should be green
+/implement                                        # first foundation story
+```
+
+Then `/feature <idea | ticket>` for everything after that, `/groom-backlog` once the first bounded context is complete.
+
+## Checkpoints
+
+After vision, after storming, after the model, after the stories – summarize in 3–5 lines and ask whether to
+continue. A bootstrap that runs to the end without a checkpoint produces a beautiful model nobody agreed to.

package/guide/install.md

@@ -0,0 +1,144 @@
+# Install, upgrade, troubleshoot
+
+## Install
+
+```bash
+npx kataster init [dir]
+```
+
+| Option | Effect |
+|---|---|
+| `--brownfield` / `--greenfield` | Sets the starting path (default: detected from the code) |
+| `--name <name>` | Project name (default: `package.json` name, else directory name) |
+| `--ui-language <lang>` | Language of the user interface (default `en`) |
+| `--artifacts <lang>` | Language of docs, stories, code comments (default `en`) |
+| `--backlog <provider>` | Where stories live: `local` (default), `github`, `jira` |
+| `--jira-project <key>` | Jira project key (with `--backlog jira`) |
+| `--github-repo <repo>` | `owner/name` for a GitHub backlog (default: the current repository) |
+| `--with <list>` | Optional extras, comma-separated (`shadcn`) |
+| `--yes`, `-y` | Non-interactive: accept the detected defaults |
+| `--no-install` | Skip `npm install --prefix .claude` |
+| `--dry-run` | Show what would happen, write nothing |
+
+The installer:
+
+- copies `.claude/`, `.opencode/`, `AGENTS.md` and the `docs/` skeleton,
+- **merges** into an existing `AGENTS.md` (marker block), `.claude/settings.json` (hooks and permissions) and
+  `.opencode/opencode.jsonc` (watcher ignore list),
+- detects stack, package manager, code roots and commands into `.claude/project.json`,
+- records the backlog backend in `.claude/project.json` (`local`, `github` or `jira`),
+- adds `.claude/node_modules/`, `.claude/state/` and `.kataster/` to `.gitignore`,
+- installs the tooling dependency (`yaml`) into `.claude/`,
+- records every managed file with a hash in `.claude/install.json`.
+
+Existing `CONTEXT.md` and `docs/` are never overwritten.
+
+## Verify the installation
+
+```bash
+npx kataster doctor
+```
+
+Checks Node version, workflow files, manifest, profile, tooling dependencies, the docs skeleton, whether
+`docs/domain/events.yaml` validates, and the backlog backend (Jira project/MCP server or GitHub CLI/auth).
+
+## Upgrade
+
+```bash
+npx kataster upgrade
+```
+
+- Workflow files that you did not change are replaced.
+- Workflow files you **did** change are kept and listed as conflicts; `--force` overwrites them and writes a backup
+  to `.kataster/backup/<timestamp>/`.
+- Project content (`CONTEXT.md`, `docs/`, `.claude/project.json`) is never touched.
+- An installation made under the old name (La Guardia) is migrated in place: `.laguardia/` becomes `.kataster/`, the
+  OpenCode adapter moves to `.opencode/plugins/kataster/`, and the marker blocks in `AGENTS.md`/`CLAUDE.md` are
+  rewritten. `backlog.labelPrefix` in `project.json` is kept, so labels already in GitHub or Jira stay valid.
+- An existing `project.json` keeps its content. If it predates the backlog backend, add the `backlog` section by hand
+  (see the README) – without it the provider stays `local`.
+- `--with` can add extras on upgrade.
+
+## Harness setup
+
+### OpenCode
+
+Nothing to configure. `.opencode/commands/` provides the slash commands, `.opencode/agents/` the subagents, and
+`.opencode/plugins/kataster/index.ts` wires the `.claude/hooks/*.ts` scripts into OpenCode's hook events.
+`.opencode/opencode.jsonc` only holds watcher ignores.
+
+### Claude Code
+
+`.claude/settings.json` wires the same hooks (`SessionStart`, `PreToolUse`, `PostToolUse`, `Stop`). Skills in
+`.claude/skills/` and agents in `.claude/agents/` are discovered automatically. Approve the project hooks once when
+Claude Code asks.
+
+### Both
+
+Both harnesses read `AGENTS.md`. Claude Code reads `CLAUDE.md` first; the installer creates one containing
+`@AGENTS.md`, or adds that import block to an existing `CLAUDE.md` without touching your house rules. The workflow
+lives in `.claude/`; `.opencode/` is an adapter. An existing `.claude/` is merged: skills, rules and settings that
+do not collide with a workflow file are left alone.
+
+**Models.** OpenCode agents inherit the session's model; set `model:` in `.opencode/agents/*.md` if you want a
+specific one per role (the review agents are the ones where a stronger model pays off). Claude Code agents use the
+aliases `sonnet`/`opus` in `.claude/agents/*.md`; adjust them to the models you have.
+
+### Backlog backends
+
+`local` needs nothing. `github` needs the `gh` CLI, authenticated with the `repo` scope; set
+`backlog.github.repo` if it is not the current repository. `jira` needs the `mcp-atlassian` server in your harness and
+a real `backlog.jira.project`; the status and priority maps must match the project's workflow.
+
+- Claude Code: add the server to `.mcp.json` and approve it once.
+- OpenCode: add it to the `mcp` block in `opencode.jsonc`.
+
+```jsonc
+{
+  "mcp": {
+    "mcp-atlassian": {
+      "type": "local",
+      "command": ["uvx", "mcp-atlassian"],
+      "enabled": true,
+      "environment": { "JIRA_URL": "https://…", "JIRA_USERNAME": "…", "JIRA_API_TOKEN": "…" }
+    }
+  }
+}
+```
+
+Then `/backlog-sync pull|push` (or the `backlog` skill) keeps `docs/stories/` in step with the tracker. The tracker is
+the source of truth; the local directory is the mirror that validation and test traceability run on. Reviews and open
+questions stay local.
+
+## Troubleshooting
+
+**"Tooling dependencies are missing"** – run `npm install --prefix .claude`. The validators and hooks need `yaml`.
+
+**Hooks don't run in OpenCode** – the plugin spawns the project's `node`. If Node is not on `PATH`, set
+`KATASTER_NODE` to the binary.
+
+**`verify` skips project checks** – `commands` in `.claude/project.json` are empty. Fill in `lint`, `typecheck`,
+`test` (and `e2e`) with the commands this repository actually uses.
+
+**The stack detection is wrong** – it is a starting point. Edit `.claude/project.json`; nothing else reads the
+detection.
+
+**The backlog sync fails** – `npx kataster doctor` checks the provider. GitHub: `gh auth status`. Jira: the
+`mcp-atlassian` server must be configured in the harness and `backlog.jira.project` must be set.
+`node .claude/skills/backlog/scripts/backlog-status.ts` shows what is linked and what drifted.
+
+**An accepted ADR can't be edited** – by design. Write a new ADR and set the old one's status to
+`superseded by ADR-NNNN`. The hook allows exactly that.
+
+**Upgrade reports conflicts** – those are files you changed. Review the diff, then either keep your version or run
+`upgrade --force` (a backup is written to `.kataster/backup/`).
+`upgrade --force` (backup is written).
+
+## Uninstall
+
+```bash
+rm -rf .claude .opencode .kataster
+# keep CONTEXT.md and docs/ – they are your project's domain
+```
+
+Remove the Kataster block from `AGENTS.md` and the `.gitignore` entries if you want a clean slate.

package/guide/release.md

@@ -0,0 +1,92 @@
+# Release
+
+## 1. Prepare
+
+1. Bump `version` in `package.json`. The package is `0.x`: a breaking change – a renamed command, a removed flag, a
+   moved directory – bumps the minor number, everything else the patch number.
+2. Move the `Unreleased` section of `CHANGELOG.md` under the new version.
+3. Check the tree:
+
+```bash
+npm install --prefix .claude --no-audit --no-fund
+npm run typecheck --prefix .claude
+npm test
+npm pack --dry-run        # 162 files, 256 kB – no examples/, no node_modules, no state/
+```
+
+4. Install the tarball once and start a throwaway project with it – a tarball that installs is not the same as a
+   tarball that works:
+
+```bash
+npm pack
+npm install -g --prefix "$(mktemp -d)" ./kataster-*.tgz
+kataster init /tmp/smoke --yes
+kataster doctor /tmp/smoke
+```
+
+## 2. Publish
+
+### Through CI (the normal case)
+
+The tag publishes. `v0.2.0` starts `.github/workflows/release.yml`, which checks that the tag matches
+`package.json`, runs the type check and the suite, then publishes over OIDC – no npm token in the repository, no
+one-time password, and provenance attestations are written automatically.
+
+```bash
+git push origin main
+git tag -a v0.2.0 -m "Kataster 0.2.0"
+git push origin v0.2.0
+gh run watch
+```
+
+If the tag and `package.json` disagree, the workflow fails before it publishes – bump the version first, then tag.
+
+### The first time only: trusted publisher
+
+npm has to know which workflow may publish. On npmjs.com → `kataster` → Settings → **Trusted publishing** →
+GitHub Actions:
+
+| Field | Value |
+|---|---|
+| Organization or user | `hemi1986` |
+| Repository | `kataster` |
+| Workflow filename | `release.yml` |
+| Environment name | – (leave empty) |
+| Allowed actions | **Allow npm publish** (the default `npm stage publish` alone is not enough) |
+
+The first publish has to succeed within **two days**, otherwise the configuration expires and has to be created
+again. Once it works, lock the old path down: Settings → **Publishing access** → "Require two-factor authentication
+and disallow tokens". Trusted publishers keep working; tokens and OTP stop working.
+
+### By hand (fallback)
+
+If CI is unavailable or a version has to go out without a tag:
+
+```bash
+npm login                 # once per machine
+npm publish --access public
+```
+
+`prepublishOnly` runs the test suite, so a red suite cannot be published.
+
+## 3. Verify
+
+```bash
+npm view kataster version
+npx kataster@latest --version
+```
+
+The package page shows a provenance badge (`built and signed on GitHub Actions`) and the workflow run is linked to
+the tag. A missing badge means the publish did not go through trusted publishing.
+
+## What ships
+
+`package.json` → `files` decides:
+
+- `bin/`, `src/` – the CLI and installer
+- `.claude/`, `.opencode/` – the payload the installer copies
+- `templates/`, `extras/` – docs skeleton and optional skills
+- `guide/`, `README.md`, `AGENTS.md`, `CHANGELOG.md`, `LICENSE`
+
+Not shipped: `test/`, `examples/`, `.github/`. `examples/` contains project-specific facts and is reference material
+for the repository only.