kataster 0.3.1 → 0.4.0

package/.opencode/commands/groom-backlog.md

@@ -1,5 +1,5 @@
 ---
-description: Periodic grooming of the open backlog – challenges whether stories are still worth building, whether dependencies still hold and whether the priorities still match what the product needs now.
+description: Periodic grooming of the open backlog – challenges whether stories are still worth building, whether dependencies still hold and whether the priorities still match what the product needs now. Runs in the main session; the UX utility is on demand only.
 ---
 
 Load the `groom-backlog` skill with the `skill` tool and follow it exactly. Do not restate it.

package/.opencode/commands/implement.md

@@ -1,5 +1,5 @@
 ---
-description: Engineering workflow – implements one story from docs/stories/ test-first on its own branch, verifies, has it reviewed by code-reviewer and acceptance-tester, refactors, and sets it done on the acceptance tester's verdict and hands the pull request to the user to merge; `--prototype` prototypes an open UI question first.
+description: Engineering workflow – implements one story from docs/stories/ on its own branch, verifies, reviews scaled to the diff, refactors and hands the pull request to the user; `type: chore`/`task` (or `--fast`) takes the fast lane without Gherkin matching or formal reviews; `--prototype` settles an open UI question first.
 ---
 
 Load the `implement` skill with the `skill` tool and follow it exactly. Do not restate it.

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,29 @@
 # 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

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/
@@ -118,13 +118,37 @@ Existing `CONTEXT.md` and `docs/` are never touched.
 | `/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; `--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; `--prototype` prototypes an open UI question first |
+| `/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
@@ -170,7 +194,7 @@ open UI question during engineering; if the prototype changes the story, the sto
 
 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.
 
@@ -304,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
 

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,7 +26,7 @@ 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 |
@@ -46,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
 

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kataster",
-  "version": "0.3.1",
+  "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/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.
 

package/templates/docs/workflow.md

@@ -14,7 +14,7 @@ is what to read when you are unsure where something belongs.
 
 | Artifact | File | Owner |
 |---|---|---|
-| Vision, user groups, scope | `docs/product/vision.md` | user + `product-owner` |
+| Vision, user groups, scope | `docs/product/vision.md` | user + main session |
 | 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) |
 | Prototypes (throwaway, on branch `prototype/<slug>`) | `docs/prototypes/<slug>/` | `ux-designer`; verdict in the story and `ux-guidelines.md` |
@@ -30,12 +30,12 @@ is what to read when you are unsure where something belongs.
 | 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 |
+| Stories | `docs/stories/ST-NNN-*.md` | main session as spec engineer; linter gate; 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` |
+| Reviews | `docs/reviews/` | spec linter and `acceptance-tester`/`code-reviewer` (domain lane only; findings, no stories) |
 | 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` |
 
@@ -51,12 +51,12 @@ is what to read when you are unsure where something belongs.
 | `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; `--prototype` adds a throwaway prototype before the stories |
-| `user-stories`, `/review-stories` | story format, validation, review |
+| `user-stories`, `/review-stories` | story format, 1-command rule, spec linter, human approval |
 | `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 |
 | `prototype` | throwaway HTML prototype for a UI or logic question; the verdict goes into the story and the guidelines |
 | `/groom-backlog` | periodic challenge of the open backlog |
-| `/implement [ST-NNN]` | one story test-first, verify, review, refactor, acceptance, pull request; `--prototype` prototypes an open UI question first |
+| `/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 |
 | `tdd` | red → green loop, good tests, seams |
 | `codebase-design` | vocabulary for deep modules |
 | `/improve-codebase-architecture` | periodic scan for deepening opportunities, then grilling |
@@ -79,8 +79,22 @@ is what to read when you are unsure where something belongs.
   `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.
+- **1-command rule.** One story = one command + its events on one aggregate, at most 4 Gherkin scenarios. A second
+  command is a second story, never a second scenario set. `type: domain` requires `aggregate` and `command` and the
+  linter cross-checks them against `events.yaml`.
+- **Fast lane.** `type: chore` and `type: task` cover UI tweaks, refactorings, dependencies and setup. `/implement`
+  takes the fast lane automatically (or with `--fast`): branch → implement → lint/typecheck/tests → pull request, no
+  Gherkin matching and no formal review pass. `type: tech-task` keeps its checklist and acceptance; `type: spike` is
+  a timeboxed question.
+- **The spec linter is the gate.** `node .claude/skills/user-stories/scripts/lint-story.ts <file>` (or
+  `kataster lint-story`) checks frontmatter, required fields, aggregate/command/event references, Gherkin and the
+  scenario limit – deterministically, without an LLM. Green → `ready-for-human-review`; the user approves `ready`.
+- **Traceability in the code**: every Gherkin scenario of a `domain` story 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. Chore/task stories are covered by their checklist and unit tests.
+- **Reviews report, they do not plan.** `code-reviewer` and `acceptance-tester` find problems; they never create,
+  split or revise stories. A finding is fixed in the story or becomes an open question to the developer. Review
+  effort follows the diff (light lane for texts/layout, normal lane otherwise).
 - **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.
@@ -120,10 +134,12 @@ larger than one feature goes through `/shape` first and then `/feature` per slic
 question cannot be settled on paper, `/feature --prototype` adds a throwaway prototype between grilling and the
 stories; the verdict goes into the story and the UX guidelines.
 
-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**. `--prototype` settles an open UI question
-first; if it changes the story, the story goes back to `review`. Start the next story in a fresh session.
+Engineering, story by story: `/implement [ST-NNN]` (empty = next ready story whose dependencies are done). Domain
+lane: prepare → test plan → red/green per scenario → `verify.ts` → review lane scaled to the diff → refactor →
+acceptance tester's verdict → `done` + pull request. Fast lane (`chore`/`task`, or `--fast`): prepare → implement →
+lint/typecheck/tests → `verify.ts` → pull request. **The user only merges.** `--prototype` settles an open UI
+question first; if it changes the story, the story goes back to `review`, through the linter and the user again.
+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

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

@@ -1,52 +0,0 @@
----
-name: lead-dev
-description: Lead developer. Story review in one pass – value (PO lens), testability, slicing, effort (T-shirt), risks, dependencies (dev lens) and the UX guidelines (UX lens). Use before setting status ready.
-tools: Read, Glob, Grep, Write, Edit
-model: sonnet
-color: green
-skills:
-  - user-stories
-hooks:
-  PreToolUse:
-    - matcher: "Write|Edit"
-      hooks:
-        - type: command
-          command: 'node "$CLAUDE_PROJECT_DIR/.claude/hooks/path-guard.ts" docs/stories/ docs/reviews/'
----
-
-You are the lead developer of this project and assess stories from the perspective of the later engineering workflow.
-You have NO context from the main conversation. Write in the artifact language (`languages.artifacts` in `.claude/project.json`, default English).
-
-## Sources
-Stories in `docs/stories/`, `docs/domain/events.yaml`, `docs/architecture/data-model.md`, ADRs in `docs/adr/`,
-glossary in `CONTEXT.md`. For a story review also `docs/product/vision.md` and, for stories labelled `ui`,
-`docs/product/ux-guidelines.md`.
-
-## Review Criteria per Story
-1. **Testability**: Can every scenario be translated 1:1 into an automated test? Unambiguous outcomes, no soft wording ("fast", "user-friendly")?
-2. **Slicing**: Vertical (through all layers, delivers value)? Larger than M, or more scenarios than the validator allows → make a concrete splitting proposal.
-3. **Effort**: `size` as a T-shirt size (XS–XL) relative to the other stories.
-4. **Risk**: `risk` (low/medium/high) – unknown technology, integrations, data migration, offline/mobile.
-5. **Dependencies**: add `depends_on` when a story requires another one, functionally or technically.
-6. **Gaps**: name missing spikes (uncertainty) or tech tasks (e.g. scaffold, auth, CI) as proposals.
-
-In a **story review** (task from `/review-stories`) add two lenses:
-7. **Value (PO lens)**: a real user role, fits the vision, touches no non-goal. Set `priority` (`must | should | could | wont`).
-8. **UX lens** (label `ui` only): the screen's job and entry point are named; the empty, rejected and
-   no-permission cases have a scenario; UI wording matches the glossary's `_UI (<lang>)_`. A pattern the
-   guidelines already define is referenced by its G-number, not restated as scenarios – name restated ones.
-   A screen whose structural shape is still open is not `ready`: recommend a prototype (`/feature --prototype`
-   or a spike) instead of approving it.
-
-## Boundaries
-- In stories you only change `size`, `risk`, `depends_on` and – in a story review – `priority`. Return everything else as a recommendation.
-- Don't write implementation details into stories (framework, tables) – stories stay domain-level.
-- Don't make stack decisions – phrase concerns as input for an ADR.
-- Never edit `docs/stories/BACKLOG.md`; it is generated.
-- With a tracker, the main session pushes your field changes; never set `external` by hand.
-
-## Output (reply to the main session)
-| Story | Testable | size | risk | priority | Split/recommendation |
-Below: findings per story as concrete edits (the scenario, Context line or G-reference to add, change or drop),
-proposed spikes/tech tasks, technical risks for ADRs, at most 3 questions for the user with a recommended answer.
-In a story review, write the same into the review file you were given.