kataster 0.2.1 → 0.3.1

package/.claude/skills/ux-design/SKILL.md

@@ -70,6 +70,29 @@ cannot be asked before the domain decision it serves.
 A question whose answer is already in `docs/product/ux-guidelines.md` is not asked again – quote the guideline
 instead. That is what makes the yardstick pay off.
 
+## When paper is not enough – the prototype
+
+Most UX questions are settled in words: entry, job, states, wording. A few are not – which of three
+structurally different layouts works, or whether a state model still feels right once it is pushed through the
+awkward cases. For those, propose a **prototype**: the `prototype` skill, owned by the `ux-designer`.
+
+Propose it in the grilling round, with a recommended answer, when the question is:
+
+- a structural layout choice (not colour, spacing or copy),
+- a state model or a flow that is hard to reason about on paper,
+- a screen that does not exist yet and whose shape decides how the stories are cut.
+
+Do not propose one for polish, or for a question a guideline or the vision already answers. State the one
+question, the branch (`ui` or `logic`), the variants or scenarios, and the timebox. The user decides.
+
+The verdict goes into `docs/product/ux-guidelines.md` as a G-number when it is a recurring rule, and into the
+story's `## Context` (`Prototype: prototype/<slug> – <question> – <verdict>`). The prototype itself is
+throwaway: it lives under `docs/prototypes/<slug>/`, is captured on a throwaway branch, and is never merged.
+Details: `.claude/skills/prototype/SKILL.md`.
+
+At story review, a `ui` story whose screen shape is still open is not `ready`: send it back to `/feature` for a
+prototype (or a spike), rather than approving it and deciding it in code.
+
 ## What goes into the story, and what does not
 
 Stories stay at the level of observable behaviour. The `lead-dev` rule holds for UX too: no implementation detail

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

@@ -52,6 +52,8 @@ In a **story review** (task from `/review-stories`) add two lenses:
 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.

package/.opencode/agents/ux-designer.md

@@ -1,5 +1,5 @@
 ---
-description: UX/UI designer. Reviews stories with a frontend part and existing screens against docs/product/ux-guidelines.md, and maintains those guidelines. Use in backlog grooming for stories labelled `ui`, and when a feature's grilling changed a UX guideline.
+description: UX/UI designer. Reviews stories with a frontend part and existing screens against docs/product/ux-guidelines.md, maintains those guidelines, and builds throwaway prototypes for UX questions. Use in backlog grooming for stories labelled `ui`, when a feature's grilling changed a UX guideline, and when `/feature` or `/implement` asks for a prototype.
 mode: subagent
 color: pink
 permissions:
@@ -12,6 +12,9 @@ permissions:
   - action: edit
     resource: docs/reviews/*
     effect: allow
+  - action: edit
+    resource: docs/prototypes/**
+    effect: allow
   - action: shell
     resource: "*"
     effect: deny
@@ -30,9 +33,12 @@ permissions:
   - action: skill
     resource: user-stories
     effect: allow
+  - action: skill
+    resource: prototype
+    effect: allow
 ---
 
-Before you start, load the skills `ux-design` and `user-stories` with the `skill` tool.
+Before you start, load the skills `ux-design`, `user-stories` and `prototype` with the `skill` tool.
 
 You are the UX/UI designer of this project, whose interface its users meet in the situations
 `docs/product/vision.md` describes. You have NO context from the main conversation – everything relevant is in `docs/` and in the code.
@@ -46,6 +52,7 @@ Write in the artifact language (`languages.artifacts` in `.claude/project.json`,
 - `docs/engineering/conventions.md` – the page frame, the design size, component rules, where the
   message catalogs live. What is decided there is not yours to re-decide.
 - The method, the question set and the review order: the preloaded skill `ux-design`.
+- The prototype method, its two branches and its capture rules: the preloaded skill `prototype`.
 
 ## Tasks
 1. **Story review** – per story with a frontend part: is the screen's job clear, is the entry point named, do the
@@ -57,11 +64,18 @@ Write in the artifact language (`languages.artifacts` in `.claude/project.json`,
    with the date and the reason. Keep it short enough that someone reads it before writing a page.
 4. **Gaps** – which recurring interface question has no guideline yet, and which existing screens contradict each
    other?
+5. **Prototype** – when the main session delegates a UX question that cannot be settled on paper, build the
+   throwaway prototype under `docs/prototypes/<slug>/`: state the question and the branch (`ui` or `logic`) at
+   the top, use the domain language, no tests, no persistence, no application code. Return the verdict and the
+   branch pointer (`prototype/<slug>`).
 
 ## Boundaries
 - **You never write stories.** Everything that belongs in a story comes back as a recommendation – the
   `requirements-engineer` applies it. The same rule the product-owner and the lead-dev follow.
-- You never write application code, tests or the engineering conventions.
+- You never write **production** application code, tests or the engineering conventions. A prototype is
+  throwaway: it lives under `docs/prototypes/`, is captured on a throwaway branch and is never merged. A
+  question that needs the real application page is built by the main session; you define the question and the
+  variants and review the result.
 - No implementation detail in what you propose: no component names, no classes, no pixel values. Observable
   behaviour and words, not markup.
 - Make no assumptions where the vision or the guidelines are silent: return them as questions, each with a
@@ -76,7 +90,8 @@ A table of findings:
 | Story / screen | Level (job / understanding / states / language / consistency / polish) | Severity (blocker, major, minor) | Finding | What to do instead |
 
 Below it: the scenarios or Context lines you propose per story (ready for the requirements-engineer to apply), the
-guidelines you would add, and at most 3 questions for the user, each with a recommended answer.
+guidelines you would add, and at most 3 questions for the user, each with a recommended answer. When you built a
+prototype, add its question, branch, verdict and pointer (`prototype/<slug>`) so the main session can pass it on.
 
 Severity means: **blocker** – the person cannot do the job, or cannot on a phone; **major** – they can, but will
 get it wrong, misread it or not find it; **minor** – it works and is understood, but is inconsistent or clumsy.

package/.opencode/commands/feature.md

@@ -1,5 +1,5 @@
 ---
-description: Entry point for a new feature or change once the initial discovery is done – accepts a free-text idea, an existing story (`ST-NNN`) or a ticket (`#123`, `PROJ-123`, URL); grills the idea, runs a focused event storming, updates domain model and ADRs, derives stories into the backlog (local, or the tracker mirror) and runs the story review; bug tickets go to a regression story.
+description: Entry point for a new feature or change once the initial discovery is done – accepts a free-text idea, an existing story (`ST-NNN`) or a ticket (`#123`, `PROJ-123`, URL); grills the idea, runs a focused event storming, updates domain model and ADRs, derives stories into the backlog (local, or the tracker mirror) and runs the story review; bug tickets go to a regression story; `--prototype` adds a throwaway prototype before the stories.
 ---
 
 Load the `feature` 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.
+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.
 ---
 
 Load the `implement` skill with the `skill` tool and follow it exactly. Do not restate it.

package/AGENTS.md

@@ -1,12 +1,12 @@
 # Kataster – development entry point
 
-This repository is the **toolkit**, not an installation of it. `.claude/`, `.opencode/`, `templates/` and
-`extras/` are the payload that `npx kataster init` copies into a target repository.
+This repository is the **toolkit**, not an installation of it. `.claude/`, `.opencode/` and `templates/` are the
+payload that `npx kataster init` copies into a target repository.
 
 - **Installer:** `src/cli.mjs` (commands, prompts), `src/install.mjs` (copy, merge, manifest, upgrade),
   `src/detect.mjs` (stack detection), `src/repo.mjs` (monorepo tooling and workspaces), `src/util.mjs`.
 - **Payload:** `.claude/` (skills, agents, hooks, lib, settings), `.opencode/` (commands, agents, plugin),
-  `templates/` (docs skeleton, project profile defaults, conventions template), `extras/` (optional skills).
+  `templates/` (docs skeleton, project profile defaults, conventions template).
 - **Tests:** `npm test` (installs into temp directories and asserts the result).
 - **Docs for users:** `README.md` and `guide/`.
 

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 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
+  message instead of reading the value as a directory. The payload no longer ships third-party content: install a
+  UI skill such as shadcn/ui in the project that needs it. An installation made with `--with shadcn` keeps the files
+  under `.claude/skills/shadcn/`; `upgrade` leaves them alone and drops the stale `workflow.extras` field from
+  `.claude/project.json`.
+
 ## 0.2.1 – 2026-10-31
 
 - Releases are published from CI with npm trusted publishing (OIDC): pushing a `v*` tag runs the type check and the

package/README.md

@@ -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,12 +116,12 @@ 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` |
 | `/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]` | Test-first implementation of one story, review, refactor, PR; `--prototype` prototypes an open UI question first |
 | `/improve-codebase-architecture` | Scan for deepening opportunities, present them, grill one |
 | `/retro` | Retrospective on a session, proposing rule changes |
 
@@ -149,6 +151,21 @@ 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`.
@@ -301,10 +318,6 @@ npx kataster doctor
 overwrite files you changed locally – it lists them instead. `--force` overwrites and writes a backup to
 `.kataster/backup/`.
 
-## Optional extras
-
-- `--with shadcn` installs the shadcn/ui skill for projects that use it.
-
 ## Design notes
 
 - **`.claude/` is the source of truth.** OpenCode and Claude Code share skills, agents and hooks; `.opencode/` is an
@@ -327,6 +340,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/concepts.md

@@ -29,6 +29,7 @@ Two rules make it work:
 | `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 |
+| `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
 
@@ -75,6 +76,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/install.md

@@ -15,7 +15,6 @@ npx kataster init [dir]
 | `--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 |
@@ -57,7 +56,8 @@ npx kataster upgrade
   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.
+- An extra installed by an older version (`--with shadcn`, up to 0.2.1) stays on disk as a project file; upgrade no
+  longer touches it. Delete `.claude/skills/shadcn/` if you do not want it.
 
 ## Harness setup
 

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        # 162 files, 256 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
@@ -77,7 +77,8 @@ 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.
+the tag. A missing badge means the publish did not go through trusted publishing. The registry can take a minute or
+two before a new version appears; `npm view kataster version` is the source of truth, not the cache in `npx`.
 
 ## What ships
 
@@ -85,7 +86,7 @@ the tag. A missing badge means the publish did not go through trusted publishing
 
 - `bin/`, `src/` – the CLI and installer
 - `.claude/`, `.opencode/` – the payload the installer copies
-- `templates/`, `extras/` – docs skeleton and optional skills
+- `templates/` – docs skeleton
 - `guide/`, `README.md`, `AGENTS.md`, `CHANGELOG.md`, `LICENSE`
 
 Not shipped: `test/`, `examples/`, `.github/`. `examples/` contains project-specific facts and is reference material

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kataster",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "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",
@@ -40,7 +40,6 @@
     "bin",
     "src",
     "templates",
-    "extras",
     "guide",
     ".claude",
     ".opencode",

package/src/cli.mjs

@@ -25,7 +25,6 @@ Options:
   --backlog <provider>  Where stories live: local (default), github, jira
   --jira-project <key>  Jira project key (with --backlog jira)
   --github-repo <repo>  GitHub repository owner/name (with --backlog github; default: this repo)
-  --with <list>         Optional extras, comma-separated (available: shadcn)
   --force               Overwrite locally modified workflow files (backup is kept)
   --no-install          Do not run "npm install --prefix .claude"
   --yes, -y             Non-interactive: accept the detected defaults
@@ -34,7 +33,7 @@ Options:
 
 function parse(argv) {
   const options = { _: [] };
-  const takesValue = new Set(["name", "ui-language", "artifacts", "with", "backlog", "jira-project", "github-repo"]);
+  const takesValue = new Set(["name", "ui-language", "artifacts", "backlog", "jira-project", "github-repo"]);
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (!arg.startsWith("-")) {
@@ -49,6 +48,9 @@ function parse(argv) {
     else if (arg === "--no-install") options.noInstall = true;
     else if (arg === "--yes" || arg === "-y") options.yes = true;
     else if (arg === "--dry-run") options.dryRun = true;
+    else if (arg === "--with" || arg.startsWith("--with=")) {
+      throw new Error("--with was removed in 0.3.0 – install an extra such as shadcn/ui directly in your project.");
+    }
     else if (arg.startsWith("--") && arg.includes("=")) {
       const [key, ...rest] = arg.slice(2).split("=");
       options[camel(key)] = rest.join("=");
@@ -104,9 +106,9 @@ Useful commands afterwards:
 `);
 }
 
-function printSummary(installer, extras) {
+function printSummary(installer) {
   const { created, updated, conflicts } = installer.summary();
-  console.log(`\nDone: ${created} created, ${updated} updated${extras.length ? `, extras: ${extras.join(", ")}` : ""}.`);
+  console.log(`\nDone: ${created} created, ${updated} updated.`);
   if (conflicts.length) {
     console.log(`\n${conflicts.length} file(s) kept because they were modified locally:`);
     for (const c of conflicts) console.log(`  - ${c}`);
@@ -117,7 +119,6 @@ function printSummary(installer, extras) {
 async function init(options) {
   const root = resolve(options._[1] ?? ".");
   const detection = detectProject(root);
-  const extras = String(options.with ?? "").split(",").map((s) => s.trim()).filter(Boolean);
 
   banner();
   if (existsSync(join(root, ".claude", "install.json"))) {
@@ -147,7 +148,7 @@ async function init(options) {
     : "";
 
   const profile = buildProfile(root, {
-    name, kind, uiLanguage, artifactLanguage, detection, extras,
+    name, kind, uiLanguage, artifactLanguage, detection,
     backlog, jiraProject, githubRepo,
   });
   profile.workflow.version = VERSION;
@@ -163,7 +164,6 @@ async function init(options) {
   installer.putClaudeMd(profile);
   installer.putProfile(profile);
   installer.putConventions(profile);
-  installer.installExtras(extras);
   installer.updateGitignore();
   installer.writeManifest();
 
@@ -177,7 +177,7 @@ async function init(options) {
     if (!result.ok) console.log("\nTooling dependencies could not be installed – run: npm install --prefix .claude");
   }
 
-  printSummary(installer, extras);
+  printSummary(installer);
   nextSteps(root, profile);
 }
 
@@ -190,7 +190,6 @@ async function upgrade(options) {
     return init({ ...options, _: ["init", root] });
   }
   const profile = readJson(join(root, ".claude", "project.json")) ?? {};
-  const extras = options.with ? String(options.with).split(",").map((s) => s.trim()).filter(Boolean) : profile.workflow?.extras ?? [];
 
   console.log(`Upgrading ${root} from ${installer.manifest.version ?? "?"} to ${VERSION}\n`);
   installer.migrateLegacy();
@@ -202,12 +201,12 @@ async function upgrade(options) {
   installer.putContext(profile);
   installer.putClaudeMd(profile);
   installer.putConventions(profile);
-  installer.installExtras(extras);
   installer.updateGitignore();
   installer.writeManifest();
 
   if (profile.name && !options.dryRun) {
-    profile.workflow = { ...(profile.workflow ?? {}), version: VERSION, extras };
+    profile.workflow = { ...(profile.workflow ?? {}), version: VERSION };
+    delete profile.workflow.extras;
     write(join(root, ".claude", "project.json"), `${JSON.stringify(profile, null, 2)}\n`);
   }
 
@@ -216,7 +215,7 @@ async function upgrade(options) {
     return;
   }
   if (!options.noInstall) installer.installToolingDependencies();
-  printSummary(installer, extras);
+  printSummary(installer);
   console.log("\nUpgrade complete. Project content (CONTEXT.md, docs/domain, docs/stories, ADRs) was not touched.");
 }
 

package/src/detect.mjs

@@ -157,7 +157,7 @@ export function detectProject(root) {
   };
 }
 
-export function buildProfile(root, { name, kind, uiLanguage, artifactLanguage, detection, extras = [], backlog = "local", jiraProject = "", githubRepo = "" }) {
+export function buildProfile(root, { name, kind, uiLanguage, artifactLanguage, detection, backlog = "local", jiraProject = "", githubRepo = "" }) {
   const stackSummary = [
     ...detection.languages,
     ...detection.frameworks,
@@ -230,7 +230,6 @@ export function buildProfile(root, { name, kind, uiLanguage, artifactLanguage, d
     },
     workflow: {
       version: "0.1.0",
-      extras,
       installedAt: new Date().toISOString(),
     },
   };

package/src/install.mjs

@@ -341,19 +341,6 @@ export class Installer {
     });
   }
 
-  installExtras(names = []) {
-    for (const name of names) {
-      const source = join(PKG, "extras", "skills", name);
-      if (!existsSync(source)) {
-        this.record("skip", source, `unknown extra '${name}'`);
-        continue;
-      }
-      for (const file of walk(source)) {
-        this.put(join(this.root, ".claude", "skills", name, relative(source, file)), read(file));
-      }
-    }
-  }
-
   installToolingDependencies() {
     if (this.dryRun) return { ok: true, skipped: true };
     if (!existsSync(join(this.root, ".claude", "package.json"))) return { ok: true, skipped: true };

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/workflow.md

@@ -17,6 +17,7 @@ is what to read when you are unsure where something belongs.
 | Vision, user groups, scope | `docs/product/vision.md` | user + `product-owner` |
 | Initiative briefs (proposals, no stories) | `docs/product/initiatives/<slug>.md` | `/shape`; user accepts |
 | UI/UX decisions (yardstick) | `docs/product/ux-guidelines.md` | `ux-designer` (user approves) |
+| Prototypes (throwaway, on branch `prototype/<slug>`) | `docs/prototypes/<slug>/` | `ux-designer`; verdict in the story and `ux-guidelines.md` |
 | Glossary (ubiquitous language) | `CONTEXT.md` | `domain-model` skill |
 | Event storming model | `docs/domain/events.yaml` | event storming / `domain-architect` |
 | Visualization (generated!) | `docs/domain/event-storming.md` | hook – never edit manually |
@@ -49,12 +50,13 @@ is what to read when you are unsure where something belongs.
 | `affected.ts` | monorepo fast loop: changed files or `--base` → affected packages + native test command |
 | `grilling` (`/grill-me`) | relentless interview in rounds with recommended answers – how we ask questions |
 | `/grill-with-docs` | grilling + `domain-model` + `architect`: writes glossary and ADRs as it goes |
-| `/event-storming [process]`, `/feature <idea \| ST-NNN \| ticket>` | discovery entry points; both start by grilling. `/feature` resolves a story or ticket read-only and routes bugs to a regression story |
+| `/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 |
 | `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 |
+| `/implement [ST-NNN]` | one story test-first, verify, review, refactor, acceptance, pull request; `--prototype` prototypes 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 |
@@ -100,6 +102,10 @@ is what to read when you are unsure where something belongs.
   source is recorded in the story (`Source: …`), its acceptance criteria are grilled like any other claim, and
   `external` is still written only by the backlog sync. A bug is a story with the label `bug`, not a separate type; a
   change to a documented rule is a feature, because the rule changes.
+- **Prototypes are throwaway.** One question, one self-contained HTML file under `docs/prototypes/<slug>/`,
+  captured on a throwaway branch `prototype/<slug>` and never merged. The decision lands in the story
+  (`Prototype: …`) and, when it is a recurring rule, in `ux-guidelines.md` as a G-number. No tests, no
+  persistence, no production code.
 - **Initiatives are not a backlog.** `docs/product/initiatives/` holds proposals from `/shape`; they have no
   `ready`/`done` and create no stories. Only `docs/stories/` is work. Cost is a range with a basis and a
   confidence – never a single number, never a commitment.
@@ -110,11 +116,14 @@ is what to read when you are unsure where something belongs.
 Discovery, first time: `/bootstrap` (greenfield) or `/adopt` (existing code), then `/review-stories` until stories
 are `ready`. A monorepo is adopted slice by slice: finish one domain plus its shared library, then run
 `/adopt <next path>` – the map keeps track of what is adopted. Later features: `/feature <idea | ticket>`; an idea
-larger than one feature goes through `/shape` first and then `/feature` per slice.
+larger than one feature goes through `/shape` first and then `/feature` per slice. When a UI, flow or state
+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**. Start the next story in a fresh session.
+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.
 
 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