kataster 0.3.0 → 0.4.0

package/.opencode/commands/review-stories.md

@@ -1,5 +1,5 @@
 ---
-description: Has stories checked in one lead-dev pass (value, build, UX), applies the small fixes and guides the user to approval (status ready).
+description: Runs the deterministic spec linter on finished stories, fixes mechanical gaps, moves green stories to ready-for-human-review and guides the user to approval (status ready). No subagent review pass.
 ---
 
 Load the `review-stories` skill with the `skill` tool and follow it exactly. Do not restate it.

package/AGENTS.md

@@ -19,3 +19,20 @@ Rules:
 - A file the installer manages is tracked in `.claude/install.json`; project content (`CONTEXT.md`, `docs/`,
   `project.json`, `AGENTS.md` block) is not. Never make an upgrade overwrite user content.
 - Run `npm test` and `npm run typecheck --prefix .claude` before committing.
+
+## Workflow contract (0.4)
+
+The workflow is spec-driven and mechanical, not a simulated organisation:
+
+- **No product-owner, requirements-engineer or lead-dev subagents.** The main session writes stories as a spec
+  engineer with three lenses (domain, architecture, testability). Only the `ux-designer` remains on demand
+  (`ui: true` / prototyping), and it never gates.
+- **1-command rule:** one `type: domain` story = one command + its events on one aggregate, at most 4 Gherkin
+  scenarios. `aggregate` and `command` are required frontmatter and are cross-checked against `docs/domain/events.yaml`.
+- **Spec linter:** `.claude/skills/user-stories/scripts/lint-story.ts` (also `kataster lint-story`) is the gate.
+  Green → `ready-for-human-review`; the user approves `ready`. No LLM pre-implementation review.
+- **Fast lane:** `type: chore` / `type: task`; `/implement` skips Gherkin matching and formal reviews.
+- **Reviewers report, never plan:** `code-reviewer` and `acceptance-tester` create no stories. Findings are fixed in
+  the story or handed back as open questions.
+- The installer prunes the retired workflow files named in `OBSOLETE` (only manifest-tracked, unmodified ones), so a
+  removed agent disappears on upgrade without touching optional extras or user files.

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 0.4.0 – 2026-11-03
+
+- **Spec-driven instead of corporate roleplay.** The `product-owner`, `requirements-engineer` and `lead-dev`
+  subagents are gone (Claude Code and OpenCode). The main session writes stories as a spec engineer with three
+  lenses – domain, architecture, testability – instead of handing them to simulated roles. The `ux-designer` stays
+  as an on-demand utility for `ui: true` stories and the prototyping phase; it never gates.
+- **1-command rule.** One `type: domain` story = one command + its events on one aggregate, at most 4 Gherkin
+  scenarios. `aggregate` and `command` are required frontmatter and are cross-checked against
+  `docs/domain/events.yaml`; the events must be exactly what the command produces. `type: story` remains valid as a
+  legacy alias and is reported as a warning.
+- **Deterministic spec linter.** `node .claude/skills/user-stories/scripts/lint-story.ts [ST-NNN|file]` and
+  `kataster lint-story` check frontmatter, required fields, referential integrity, `Given/When/Then`, the scenario
+  limit and unique titles – no LLM, no tokens. The same rules run in the PostToolUse hook, `story-status.ts` and
+  `verify.ts`. Green → `ready-for-human-review`; only the user approves `ready`.
+- **Fast lane.** `type: chore` and `type: task` for UI tweaks, refactorings, dependencies and setup.
+  `/implement --fast` (or automatic detection) does branch → implement → lint/typecheck/unit tests → pull request,
+  without Gherkin matching or formal subagent reviews. `type: tech-task` and `type: spike` keep their behaviour.
+- **Reviews report, they do not plan.** `code-reviewer` and `acceptance-tester` no longer create, split or revise
+  stories; a finding is fixed in the story or handed back as an open question. Review effort follows the diff, not a
+  T-shirt size. `size` is no longer a gate.
+- **Installer prunes retired workflow files.** `upgrade` deletes the manifest-tracked files named in `OBSOLETE`
+  (the removed agents). Locally modified files are kept and reported; `--force` backs them up first. Optional
+  extras and user-added agents are never pruned.
+
+## 0.3.1 – 2026-11-02
+
+- **Optional prototyping, owned by the UX designer.** New `prototype` skill (adapted from Matt Pocock's, MIT) builds
+  a throwaway self-contained HTML prototype for one design question: several structurally different UI variants
+  (`ui`) or a clickable state model (`logic`). `/feature --prototype[=ui|logic]` – or a proposal from the UX frontier
+  during grilling – runs it between grilling and the stories; `/implement --prototype` settles an open UI question
+  before the test plan. The verdict goes into the story (`Prototype: …`) and, when it is a recurring rule, into
+  `docs/product/ux-guidelines.md` as a G-number. The prototype lives under `docs/prototypes/<slug>/`, is captured on
+  a throwaway branch `prototype/<slug>` and is never merged.
+- **Credit where the workflow comes from.** `.claude/THIRD_PARTY_NOTICES.md` lists which skills are derived from
+  [Matt Pocock's skills](https://github.com/mattpocock/skills) – some adapted, some copied verbatim – and carries his
+  MIT license text. The file ships with the payload and lands in every installation; the README has a Credits
+  section.
+
 ## 0.3.0 – 2026-10-31
 
 - **Removed the optional extras and the vendored `shadcn` skill.** `--with` is gone; the CLI fails with a clear

package/README.md

@@ -78,7 +78,7 @@ npx kataster init . --yes --name "Acme" --ui-language de --artifacts en
   skills/               the workflow skills (grilling, event-storming, domain-model, architect, backlog, …)
   skills/adopt/scripts/ repository map and per-package docs for brownfield adoption
   skills/feature/scripts/ read-only intake: story, GitHub/Jira ticket or URL → route
-  agents/               review agents for Claude Code
+  agents/               review agents and the on-demand UX utility (Claude Code)
   hooks/                plain-Node guardrails and validators
   lib/                  deterministic domain/story/backlog logic
 .opencode/
@@ -92,6 +92,8 @@ docs/
   workflow.md           the map: sources of truth, commands, phases, rules
   product/vision.md     the vision, grilled with you
   product/initiatives/  proposals for large ideas from /shape (no stories)
+  product/ux-guidelines.md   the interface yardstick
+  prototypes/           throwaway prototypes on their own branch; the default branch keeps the README
   domain/events.yaml    the event storming model (empty is valid)
   domain/context-map.md
   architecture/data-model.md
@@ -114,15 +116,39 @@ Existing `CONTEXT.md` and `docs/` are never touched.
 | `/grill-me` | Relentless interview on a plan, decision or idea |
 | `/grill-with-docs` | The same, writing glossary and ADRs as you go |
 | `/event-storming [process]` | Big-picture or single-process event storming |
-| `/feature <idea \| ST-NNN \| #123 \| PROJ-123>` | New feature from an idea, an existing story or a ticket: intake and routing, grilling, focused storming, model, stories, review; bugs become a regression story |
+| `/feature <idea \| ST-NNN \| #123 \| PROJ-123>` | New feature from an idea, an existing story or a ticket: intake and routing, grilling, focused storming, model, stories, review; bugs become a regression story; `--prototype` adds a throwaway prototype before the stories |
 | `/shape <idea \| ticket> [--dry-run]` | Before a large feature: frame, place (existing/new context, shared library), impact, slices, rough cost range, recommendation; creates no stories |
-| `/review-stories [ST-…]` | One lead-dev pass (value, build, UX) before a story is `ready` |
+| `/review-stories [ST-…]` | Spec linter gate → `ready-for-human-review`; the user approves `ready` |
 | `/backlog-sync [status\|pull\|push]` | Keep `docs/stories/` in sync with GitHub Issues or Jira |
 | `/groom-backlog [scope]` | Periodic challenge: is this backlog still worth building? |
-| `/implement [ST-NNN]` | Test-first implementation of one story, review, refactor, PR |
+| `/implement [ST-NNN] [--fast]` | One story on its branch: domain = test-first, diff-scaled review, acceptance; `chore`/`task` or `--fast` = fast lane without Gherkin matching or formal reviews; `--prototype` settles an open UI question first |
 | `/improve-codebase-architecture` | Scan for deepening opportunities, present them, grill one |
 | `/retro` | Retrospective on a session, proposing rule changes |
 
+### Spec-driven stories, fast lane
+
+Stories are written by the main session as a **spec engineer**, not by simulated roles. Three lenses at once –
+domain, architecture, testability – and one mechanical rule: **one story = one command + its events on one
+aggregate**, at most four Gherkin scenarios. `aggregate` and `command` are required frontmatter and are cross-checked
+against `docs/domain/events.yaml`.
+
+The **spec linter** is the gate and costs no LLM tokens:
+
+```bash
+kataster lint-story                      # all stories
+kataster lint-story ST-012               # one story
+node .claude/skills/user-stories/scripts/lint-story.ts docs/stories/ST-012-*.md
+```
+
+Frontmatter and required fields, aggregate/command/event references, Gherkin `Given/When/Then`, the scenario limit
+and unique titles. Green → `ready-for-human-review`; only you approve `ready`. The same rules run in the PostToolUse
+hook and in `verify.ts`.
+
+Non-domain work takes the **fast lane**: `type: chore` (UI tweak, refactor, dependency) or `type: task` (setup).
+`/implement` detects it (or takes `--fast`) and does branch → implement → lint/typecheck/unit tests → PR, without
+Gherkin matching or formal review agents. `type: tech-task` keeps its checklist and acceptance; `type: spike` is a
+timeboxed question.
+
 ### Starting from a ticket
 
 `/feature` also accepts a reference: `/feature #123` (GitHub), `/feature PROJ-123` (Jira, with the issue fetched
@@ -149,11 +175,26 @@ The brief lands in `docs/product/initiatives/<slug>.md` (`proposed` until you ac
 existing monorepo is treated as a new context in an existing landscape, not as a greenfield project; a similar
 service is used as evidence and as the cost anchor, never as a template.
 
+### Prototyping an open question
+
+When a UI, flow or state question cannot be settled on paper, `/feature --prototype` (or a proposal from the UX
+lens during grilling) runs a throwaway prototype before the stories are written. The `ux-designer` builds one
+self-contained HTML file under `docs/prototypes/<slug>/` – several structurally different UI variants or a
+clickable state model. The verdict goes into the story and, when it is a recurring rule, into the UX guidelines;
+the prototype is captured on a throwaway branch and never merged. `/implement --prototype` does the same for an
+open UI question during engineering; if the prototype changes the story, the story goes back to `review`.
+
+```bash
+/feature "checkout with saved cards" --prototype=ui
+/feature PROJ-123 --prototype=logic
+/implement ST-042 --prototype
+```
+
 ## Greenfield, end to end
 
 1. `npx kataster init --greenfield` → review `.claude/project.json`.
 2. `/bootstrap` → vision grilled, event storming, contexts/aggregates/data model, tech-stack ADR, UX guidelines.
-3. `/review-stories` → the first foundation tech tasks and the first vertical slice become `ready`.
+3. `/review-stories` → the spec linter turns finished stories into `ready-for-human-review`; you approve `ready`.
 4. `/implement` → one story at a time, test-first, reviewed, merged by you.
 5. `/feature <idea>` for everything after that.
 
@@ -287,8 +328,9 @@ For Jira, `jira-plan.ts` prints the exact MCP calls, `jira-record.ts` writes the
   ```
 - **`verify.ts`** is the one gate: project checks, artifact validity, scenario ↔ test traceability, domain IDs in
   the code, glossary language.
-- **Review agents** never write code: `code-reviewer` and `acceptance-tester` report, the acceptance verdict decides
-  whether a story is `done`.
+- **Review agents** never write code or stories: `code-reviewer` and `acceptance-tester` report findings, the
+  acceptance verdict decides whether a domain story is `done`, and a finding is fixed in the story or handed back
+  as an open question. `ux-designer` is an on-demand utility (`ui: true`), never a gate.
 
 ## Upgrading
 
@@ -323,6 +365,21 @@ The toolkit is maintained in the open: bug reports, a skill that fills a real ga
 [SECURITY.md](SECURITY.md) is the way to report a vulnerability privately. Participation is covered by the
 [Code of Conduct](CODE_OF_CONDUCT.md).
 
+## Credits
+
+Kataster stands on other people's work:
+
+- **Matt Pocock** – [skills](https://github.com/mattpocock/skills), [aihero.dev](https://www.aihero.dev). The grilling
+  interview (`grilling`, `grill-me`, `grill-with-docs`), test-driven development (`tdd`), the deep-module vocabulary
+  (`codebase-design`), the architecture survey (`improve-codebase-architecture`), the throwaway prototype
+  (`prototype`), the retro, the domain-modeling discipline and `writing-for-agents` come from his skill repository –
+  partly adapted, partly copied verbatim under MIT. The per-file mapping and the license text are in
+  [.claude/THIRD_PARTY_NOTICES.md](.claude/THIRD_PARTY_NOTICES.md).
+- **John Ousterhout**, *A Philosophy of Software Design* – "Design It Twice" and the depth, seam and deletion-test
+  vocabulary.
+- **Eric Evans**, *Domain-Driven Design* – ubiquitous language, bounded contexts, aggregates.
+- **Martin Fowler** – the smell baseline the review agents work from.
+
 ## License
 
 MIT

package/guide/brownfield.md

@@ -103,8 +103,8 @@ that fails on existing behaviour – that would be a story.
 
 **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`.
+`/adopt <scope> --stories` (or an explicit "turn these into stories") turns the selected gaps into stories in the
+main session (spec engineer, spec linter gate).
 
 **Behaviour that already works does not become a story.** That turns the backlog into a description of the past.
 

package/guide/concepts.md

@@ -26,9 +26,10 @@ Two rules make it work:
 | `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/stories/` | The backlog. One Markdown file per story; `BACKLOG.md` is generated. With a tracker, this is the local mirror | main session as spec engineer; spec linter; `/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 |
+| `docs/prototypes/<slug>/` | Throwaway prototypes on their own branch; only the README stays on the default branch | ux-designer; verdict in the story and the guidelines |
 
 ## Events, commands, aggregates
 
@@ -45,15 +46,21 @@ 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`).
+A story is a vertical slice of observable behaviour: `draft → review → ready-for-human-review → ready →
+in-progress → done` (plus `superseded`).
 
+- **The linter is the gate.** `lint-story.ts` checks the spec deterministically. Green → `ready-for-human-review`;
+  the user approves `ready`.
 - **Discovery ends at `ready`.** Engineering moves `ready → in-progress → done`.
+- **1-command rule.** One domain story = one command + its events on one aggregate, at most 4 scenarios. A second
+  command is a second story.
+- **Fast lane.** `type: chore`/`task` for UI tweaks, refactors, dependencies and setup – no Gherkin matching, no
+  formal reviews.
 - **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.
+- **A scenario title becomes a test title**: `ST-NNN: <scenario title>`. `verify.ts` checks the link for domain
+  stories.
 
 ### Stories from tickets
 
@@ -75,6 +82,20 @@ An initiative is **not** a work item: no `ready`/`done`, no stories, no second b
 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.
 
+## Prototypes
+
+A **prototype** is throwaway code that answers one design question. It is not a first draft: no tests, no
+persistence, no production path. The question decides the branch – `ui` (what should it look like) or `logic`
+(does the state model feel right). In discovery it is one self-contained HTML file under
+`docs/prototypes/<slug>/`, built by the `ux-designer`; a question that needs the real application page is built
+by the main session during `/implement`.
+
+`/feature --prototype` (or a proposal from the UX frontier during grilling) adds the phase between grilling and
+the stories. The verdict goes into the story (`Prototype: prototype/<slug> – <question> – <verdict>`) and, when
+it is a recurring rule, into `ux-guidelines.md` as a G-number. The code is captured on a throwaway branch
+`prototype/<slug>` and never merged. `/implement --prototype` does the same for an open UI question during
+engineering; if it changes the story, the story goes back to `review`.
+
 ## The seam catalog
 
 A **seam** is where a test attaches. Testing everything everywhere is not affordable, so the project agrees up front

package/guide/greenfield.md

@@ -62,12 +62,13 @@ Two kinds of work, kept apart:
 - **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`.
+One story = one command on one aggregate, at most 4 scenarios; no implementation plan inside a domain story; every domain story links `aggregate`, `command` and 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`).
+`/review-stories` – the spec linter checks frontmatter, aggregate/command/events, Gherkin and the scenario limit.
+Green → `ready-for-human-review`; you approve every `ready`. With a tracker, pull before the review and push the
+approved stories afterwards (`/backlog-sync`).
 
 ## Phase 7 – Build
 

package/guide/release.md

@@ -11,7 +11,7 @@
 npm install --prefix .claude --no-audit --no-fund
 npm run typecheck --prefix .claude
 npm test
-npm pack --dry-run        # 147 files, 215 kB – no examples/, no node_modules, no state/
+npm pack --dry-run        # 148 files, 218 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kataster",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Agent workflow for domain-driven discovery and delivery – drop it into a greenfield or brownfield repository and build the domain by grilling.",
   "keywords": [
     "agents",

package/src/cli.mjs

@@ -1,6 +1,6 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
-import { basename, join, resolve } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { stdin, stdout } from "node:process";
 import { Installer, VERSION } from "./install.mjs";
@@ -12,6 +12,8 @@ const HELP = `Kataster ${VERSION} – agent workflow for domain-driven discovery
 Usage:
   kataster init [dir]      Install the workflow into a repository (default: .)
   kataster upgrade [dir]   Update the workflow, keep project content and local changes
+  kataster lint-story [ST-NNN|file]
+                           Deterministic spec linter for stories (no LLM); empty = all stories
   kataster doctor [dir]    Check the installation
   kataster --version
   kataster --help
@@ -99,8 +101,8 @@ Useful commands afterwards:
   /grill-me /grill-with-docs   sharpen a plan and write the docs as you go
   /event-storming              explore a process or the whole domain
   /feature <idea>              add a feature through grilling, storming, stories
-  /review-stories              one lead-dev pass before a story is ready
-  /implement [ST-NNN]          test-first implementation of one story
+  /review-stories              linter gate + human approval before a story is ready
+  /implement [ST-NNN]          test-first implementation of one story (--fast for chore/task)
   /backlog-sync                pull/push the backlog mirror (Jira or GitHub Issues)
   /retro                       retrospective on a session
 `);
@@ -219,6 +221,36 @@ async function upgrade(options) {
   console.log("\nUpgrade complete. Project content (CONTEXT.md, docs/domain, docs/stories, ADRs) was not touched.");
 }
 
+/** Nearest directory that has the story linter installed (the repository of the given file, or an ancestor). */
+function findInstallRoot(start) {
+  let dir = resolve(start);
+  if (dir.endsWith(".md")) dir = dirname(dir);
+  for (;;) {
+    if (existsSync(join(dir, ".claude", "skills", "user-stories", "scripts", "lint-story.ts"))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * `kataster lint-story [ST-NNN|file]` – delegates to the installed spec linter. Deterministic: the same checks
+ * the hook, `/review-stories` and `verify.ts` run, without an LLM.
+ */
+function lintStory(options) {
+  const arg = options._[1];
+  const root = findInstallRoot(arg && arg.endsWith(".md") ? arg : (arg && /^ST-/i.test(arg) ? process.cwd() : (arg || process.cwd())));
+  if (!root) {
+    throw new Error("No Kataster installation found (missing .claude/skills/user-stories/scripts/lint-story.ts) – run `kataster init` first.");
+  }
+  const script = join(root, ".claude", "skills", "user-stories", "scripts", "lint-story.ts");
+  const args = [script];
+  if (arg) args.push(arg.endsWith(".md") ? resolve(arg) : arg);
+  if (options.json) args.push("--json");
+  const r = spawnSync(process.execPath, args, { cwd: root, stdio: "inherit" });
+  process.exitCode = r.status ?? 1;
+}
+
 function doctor(options) {
   const root = resolve(options._[1] ?? ".");
   const checks = [];
@@ -230,6 +262,11 @@ function doctor(options) {
   add("Install manifest", Boolean(manifest), manifest ? `version ${manifest.version}` : "missing – run init");
   const leftovers = existsSync(join(root, ".laguardia")) || existsSync(join(root, ".opencode", "plugins", "laguardia"));
   add("No leftovers from the old name", !leftovers, leftovers ? "run upgrade to migrate them" : "");
+  const retired = [
+    ".claude/agents/product-owner.md", ".claude/agents/requirements-engineer.md", ".claude/agents/lead-dev.md",
+    ".opencode/agents/product-owner.md", ".opencode/agents/requirements-engineer.md", ".opencode/agents/lead-dev.md",
+  ].filter((file) => existsSync(join(root, file)));
+  add("No retired role-play agents", retired.length === 0, retired.join(", ") || "clean");
   const profile = readJson(join(root, ".claude", "project.json"));
   add("Project profile", Boolean(profile?.name), profile?.name ?? "missing");
 
@@ -238,7 +275,7 @@ function doctor(options) {
   add("Backlog provider", ["local", "github", "jira"].includes(provider), provider);
   if (provider === "jira") {
     add("Backlog: Jira project", Boolean(backlog.jira?.project), backlog.jira?.project || "backlog.jira.project is missing");
-    const statuses = ["draft", "review", "ready", "in-progress", "done", "superseded"];
+    const statuses = ["draft", "review", "ready-for-human-review", "ready", "in-progress", "done", "superseded"];
     const missingStatuses = statuses.filter((status) => !backlog.jira?.statusMap?.[status]);
     add("Backlog: Jira status map", missingStatuses.length === 0, missingStatuses.join(", ") || "all statuses mapped");
     const priorities = ["must", "should", "could", "wont"];
@@ -296,6 +333,7 @@ export async function main(argv) {
   const command = options._[0];
   if (command === "init") return init(options);
   if (command === "upgrade") return upgrade(options);
+  if (command === "lint-story") return lintStory(options);
   if (command === "doctor") return doctor(options);
   throw new Error(`Unknown command '${command}'. Try --help.`);
 }

package/src/install.mjs

@@ -1,5 +1,5 @@
 import { spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readdirSync, renameSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, renameSync, rmSync } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import {
@@ -58,8 +58,7 @@ const HOOK_EVENTS = {
 const ALLOW = [
   "Bash(node .claude/skills/event-storming/scripts/validate-events.ts)",
   "Bash(node .claude/skills/event-storming/scripts/render-event-storming.ts)",
-  "Bash(node .claude/skills/user-stories/scripts/validate-stories.ts)",
-  "Bash(node .claude/skills/user-stories/scripts/render-backlog.ts)",
+  "Bash(node .claude/skills/user-stories/scripts/*)",
   "Bash(node .claude/skills/adopt/scripts/*)",
   "Bash(node .claude/skills/backlog/scripts/*)",
   "Bash(node .claude/skills/implement/scripts/*)",
@@ -70,6 +69,21 @@ const ALLOW = [
   "Bash(git log *)",
 ];
 
+/**
+ * Files earlier versions shipped and 0.4 removed. `upgrade` deletes them from an existing installation – but only
+ * when the manifest tracks them and the local copy is unmodified, so a project that customised one keeps it.
+ * Add a path here whenever a workflow file is retired; never prune by "not in the payload", because files from
+ * optional extras and user-added agents are not the installer's to delete.
+ */
+const OBSOLETE = [
+  ".claude/agents/product-owner.md",
+  ".claude/agents/requirements-engineer.md",
+  ".claude/agents/lead-dev.md",
+  ".opencode/agents/product-owner.md",
+  ".opencode/agents/requirements-engineer.md",
+  ".opencode/agents/lead-dev.md",
+];
+
 export class Installer {
   constructor(root, { dryRun = false, force = false, log = () => {} } = {}) {
     this.root = resolve(root);
@@ -165,17 +179,52 @@ export class Installer {
   }
 
   copyWorkflowDirs() {
+    const present = new Set();
     for (const dir of WORKFLOW_DIRS) {
       const source = join(PKG, dir);
       if (!existsSync(source)) continue;
       for (const file of walk(source)) {
         const name = toPosix(relative(source, file));
         if (name.split("/").some((part) => SKIP.has(part))) continue;
-        const content = read(file);
+        const key = relPosix(this.root, join(this.root, dir, name));
+        present.add(key);
         // settings.json and opencode.jsonc are merged, not replaced
         if (file === join(source, "settings.json") || file === join(source, "opencode.jsonc")) continue;
-        this.put(join(this.root, dir, name), content);
+        this.put(join(this.root, dir, name), read(file));
+      }
+    }
+    this.pruneObsolete(present);
+  }
+
+  /**
+   * Removes the retired workflow files listed in OBSOLETE (e.g. the deleted corporate-roleplay agents).
+   *
+   * Only files recorded in the manifest are candidates, so project content and files from other tools are never
+   * touched. A file the user edited is kept and reported as a conflict – unless `--force` is given, which backs it
+   * up first. This is what makes a removed agent actually disappear from an existing installation on upgrade.
+   */
+  pruneObsolete(present) {
+    for (const key of OBSOLETE) {
+      if (present.has(key)) continue;
+      if (!(key in (this.manifest?.files ?? {}))) continue;
+
+      const path = join(this.root, key);
+      if (!existsSync(path)) {
+        delete this.files[key];
+        continue;
+      }
+
+      const known = this.manifest.files[key];
+      const local = sha(read(path));
+      if (local !== known && !this.force) {
+        this.conflicts.push(key);
+        this.record("conflict", path, "retired, but locally modified – kept");
+        continue;
       }
+      if (this.force) this.backup(path);
+      if (!this.dryRun) rmSync(path, { force: true });
+      delete this.files[key];
+      this.record("remove", path, "retired workflow file");
     }
   }
 
@@ -391,9 +440,16 @@ This repository runs the Kataster workflow. Discovery lives in \`.claude/skills/
 - **Project checks:** \`docs/engineering/checks.yaml\` – what runs at edit time and Stop/CI; architecture boundaries
   in \`docs/architecture/boundaries.yaml\` with existing debt in the baseline (only new violations fail).
 - **Language:** domain terms exactly as in \`CONTEXT.md\`; UI words from its \`_UI (<lang>)_\` lines.
-- **Traceability:** every scenario has a test titled \`ST-NNN: <scenario title>\`; domain IDs come from
+- **1-command rule:** one story = one command + its events on one aggregate, at most 4 Gherkin scenarios. Full
+  domain stories are \`type: domain\`; UI tweaks, refactors, dependencies and setup use the fast lane
+  (\`type: chore\` or \`type: task\`).
+- **Spec gate:** \`node .claude/skills/user-stories/scripts/lint-story.ts <file>\` must be green. A story the linter
+  accepts becomes \`ready-for-human-review\`; only the user approves \`ready\`.
+- **Traceability:** every domain scenario has a test titled \`ST-NNN: <scenario title>\`; domain IDs come from
   \`docs/domain/events.yaml\`.
 - **ADRs:** new ones are \`proposed\`; only the user sets \`accepted\`. A \`done\` story is never reopened.
+- **Reviews:** \`/implement\` scales review to the diff. \`code-reviewer\` and \`acceptance-tester\` report findings and
+  never create stories; fast-lane stories skip the formal review pass.
 - **Gate:** \`node .claude/skills/implement/scripts/verify.ts\`.
 
 Keep this block short: it is loaded into every session. Put rules into the skill that owns them, not here.

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

@@ -4,6 +4,8 @@
   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.
+  A prototype verdict that becomes a recurring rule lands here as a G-number; the prototype itself stays on
+  its throwaway branch (`docs/prototypes/<slug>/`).
 
   Format:
   ## G1 – <short rule>

package/templates/docs/prototypes/README.md

@@ -0,0 +1,9 @@
+# Prototypes
+
+Throwaway code that answers one design question. The method is `.claude/skills/prototype/SKILL.md`.
+
+- A prototype lives in `docs/prototypes/<slug>/` on a throwaway branch `prototype/<slug>`; it is never merged.
+- The default branch keeps this README only. The prototype itself is a primary source on its branch.
+- The decision it settled goes into the story (`Prototype: prototype/<slug> – <question> – <verdict>` in
+  `## Context`) and, when it is a recurring rule, into `docs/product/ux-guidelines.md` as a G-number.
+- One question, one self-contained HTML file, one timebox. No tests, no persistence, no production code.

package/templates/docs/stories/README.md

@@ -4,9 +4,16 @@ One Markdown file per story: `ST-NNN-short-title.md`. `BACKLOG.md` is generated
 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`.
+Workflow: `draft → review → ready-for-human-review → ready → in-progress → done` (plus `superseded`).
+
+- The **spec linter** is the gate: `node .claude/skills/user-stories/scripts/lint-story.ts <file>` (or
+  `kataster lint-story`). It checks frontmatter, `aggregate`/`command`/events against `docs/domain/events.yaml`,
+  Gherkin `Given/When/Then` and the scenario limit – deterministically, no LLM.
+- Green → `ready-for-human-review`; **the user approves `ready`**. `/implement` only picks up `ready`.
+- **1-command rule:** one `type: domain` story = one command + its events on one aggregate, at most 4 scenarios.
+- **Fast lane:** `type: chore` or `type: task` for UI tweaks, refactorings, dependencies and setup – no Gherkin
+  matching, no formal reviews. `type: tech-task` keeps its checklist; `type: spike` is a timeboxed question.
+- `ui: true` marks a story with a frontend part; it triggers the on-demand UX utility, never a gate.
 - 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.