create-cmp-cli 0.2.0 → 0.3.1

package/README.md

@@ -2,11 +2,12 @@
 
 # create-cmp
 
-**Scaffold a green-building Kotlin/Compose Multiplatform app (Android + iOS) in minutes — not hours.**
+**The AI delivery harness for Kotlin/Compose Multiplatform — scaffold a green-building app (Android + iOS) in minutes, with best practices your AI is mechanically held to.**
 
-Toolchain auto-bootstrapped · Navigation & insets pre-solved · Clean Architecture wired · Appium harness ready.
+Toolchain auto-bootstrapped · Navigation & insets pre-solved · Clean Architecture wired · Test pyramid + E2E flows included · AI-native inspector & verification lane.
 
 [![CI](https://github.com/kvdm-co-pilot/create-cmp/actions/workflows/ci.yml/badge.svg)](https://github.com/kvdm-co-pilot/create-cmp/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/create-cmp-cli.svg)](https://www.npmjs.com/package/create-cmp-cli)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
 [![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING.md)
 [![Kotlin Multiplatform](https://img.shields.io/badge/Kotlin-Multiplatform-7F52FF.svg?logo=kotlin&logoColor=white)](https://kotlinlang.org/docs/multiplatform.html)
@@ -27,6 +28,14 @@ to React Native.
 freehand-generate your project), bootstraps the toolchain, and **proves a green build** before it
 reports success.
 
+And it goes further than scaffolding: `create-cmp` is an **AI delivery harness**. In the age of
+AI-driven development, the scarce thing isn't code — it's a machine-enforceable definition of
+*correct*. Every generated project ships the architecture patterns as running exemplars (with
+tests), the best practices as executable conformance checks, generation tools so the AI extends
+the app right-by-construction, an AI-native structural inspector, and a verification lane that
+refuses "done" without evidence. See [`docs/HARNESS-PLAN.md`](./docs/HARNESS-PLAN.md) for the
+full product definition.
+
 ## Contents
 
 - [Quick start](#quick-start)
@@ -73,7 +82,7 @@ except `create` works on **any** KMP project, not only ones it scaffolded:
 | Command | What it does |
 |---|---|
 | `create-cmp [dir]` / `create-cmp create` | Scaffold a new app from the frozen golden template (the default command). |
-| `create-cmp doctor [--fix]` | Toolchain preflight (JDK/SDK/Xcode/Appium, consent-gated installs) **plus** project diagnosis when run inside a Gradle project: kotlin↔ksp lockstep, drift vs proven-green sets, the KSP2/iOS catch-22, sdk.dir, `~/.konan` bloat, disk space. `--fix` applies the safe heals. |
+| `create-cmp doctor [--fix]` | Toolchain preflight (JDK/SDK/Xcode/Appium — legacy driver install for the pre-Maestro path, consent-gated installs) **plus** project diagnosis when run inside a Gradle project: kotlin↔ksp lockstep, drift vs proven-green sets, the KSP2/iOS catch-22, sdk.dir, `~/.konan` bloat, disk space. `--fix` applies the safe heals. |
 | `create-cmp upgrade [--dry-run]` | Migrate `gradle/libs.versions.toml` to the next proven-green version set — diff table first, surgical in-place edits with `.bak-upgrade` backups, kotlin↔ksp lockstep guardrail, `--verify` to prove the result. |
 | `create-cmp clean` | Cache & build-output hygiene: stale `~/.konan` toolchains + project `build/`/`.gradle/` dirs (sizes shown, consent-gated); `~/.gradle/caches` is size-reported only. |
 | `create-cmp verify [--target-dir .]` | Run the green-build gate (Android, and iOS on macOS) against an existing project. |
@@ -103,10 +112,25 @@ per run, so it can't silently drift:
   presentation{components,theme,navigation,<feature>} / di` with Koin modules registered and **one
   example feature wired end-to-end** as the copy-paste pattern.
 - **Theme & tokens** — `<Prefix>Theme`, `<Prefix>Tokens`, `<Prefix>Colors`, DM Sans.
-- **An Appium harness** — an Appium client + smoke runner and a sample smoke asserting the bottom nav
-  renders, so "done" can be proven on a device.
+- **The test pyramid, pre-built** — unit exemplars (Turbine + fakes), dependency-free architecture
+  conformance gates, Compose UI Tests, golden-tree structural baselines, and Maestro E2E flows —
+  bound to a committed behavior spec (`specs/*.spec.md`, Given/When/Then, stable clause ids) so a
+  `specCoverage` gate catches untested or untraceable behavior — plus the verify lane
+  (`qa/verify.mjs`) that runs it all and emits a typed PASS/FAIL/SKIP verdict + evidence receipt.
+- **Extend it with Claude Code, no plugin required** — every generated project ships its own
+  `add-feature`/`add-screen`/`add-repository` skills (backed by the deterministic
+  `qa/scaffold-feature.mjs` stamper) that clone the exemplar feature end-to-end: Screen →
+  ViewModel → UseCase → Repository → DI → nav, tests at every layer, golden baseline included.
+- **Mechanically enforced, not honor-system** — a generated `.claude/settings.json` Stop hook
+  refuses "done" unless a fresh, evidence-bound PASS receipt covers the changed surface (content-
+  hash bound, rebase/merge-proof), and CI independently re-checks the committed receipt still
+  attests `HEAD`. Proven against real violations: hardcoded colors, illegal layer imports, deleted
+  spec tests, and structural regressions are each refused and named by clause, 4/4 in the
+  repo's refusal-demo script.
 - **A toolchain doctor** — diagnoses *and* heals JDK, Android SDK + AVD, Xcode/CLT, CocoaPods,
-  XcodeGen, Appium + drivers, Node. Idempotent, OS-aware, consent-gated.
+  XcodeGen, Appium + drivers (the legacy pre-Maestro path), Node. Idempotent, OS-aware, consent-gated.
+  The E2E flows themselves run on Maestro — install with
+  `curl -fsSL https://get.maestro.mobile.dev | bash`.
 - **AI-inspectable by default** — every generated app ships a debug-only live inspector
   (`127.0.0.1:9500`, loopback, structurally absent from release). An agent runs `connect_live` and
   reads the running UI as JSON — hierarchy, geometry, resolved design tokens, real navigation
@@ -134,7 +158,7 @@ placeholders and clear "drop your Firebase config here" instructions.
 | Auth | `email` / `phone` / `both` / `none` | `both` |
 | Firebase services | Firestore · Storage · Functions · FCM | all on |
 | Room local cache | on / off | on |
-| Appium harness | on / off | on |
+| E2E flows (Maestro) | on / off | on |
 | Bottom-nav tabs | label + icon, any count | Home, Profile |
 
 _(Web/PWA is intentionally out of scope — Android + iOS only.)_
@@ -149,6 +173,10 @@ shared engine, two front doors. Install from the bundled marketplace:
 /plugin install create-cmp
 ```
 
+No `/plugin` UI available (headless/non-interactive sessions)? See
+[the settings.json fallback in `docs/USAGE.md`](./docs/USAGE.md#2-setup) — it's a real two-step
+install (marketplace registration, then plugin install), not a one-line tweak.
+
 It bundles eight skills (plus the `cmp-inspector` MCP server), each with a deterministic engine
 behind it:
 
@@ -164,9 +192,10 @@ behind it:
 - **cmp-firebase-connect** — post-scaffold onboarding: create/reuse a Firebase project, register
   the app, and replace the placeholder config via the Firebase CLI (consent-gated), proven by a
   green build.
-- **cmp-test** — generate the Appium regression suite by *observing* the app: read the running
-  UI's semantics tree and emit tests in the shipped harness style.
-- **cmp-qa-prep** — brings up the emulator + Appium session + smoke.
+- **cmp-test** — generate the regression suite by *observing* the app: read the running UI's
+  semantics tree and emit Maestro E2E flows plus golden-tree snapshots in the shipped harness style.
+- **cmp-qa-prep** — brings up the emulator + Maestro flow run + smoke (legacy Appium bring-up
+  path also supported).
 
 ## Why CMP, not React Native
 
@@ -179,8 +208,8 @@ app is **time-to-first-green-build**, and that's a tooling problem, not a merits
 - **Native performance and platform access** without the RN bridge tax.
 - **Reproducible by construction.** A frozen, version-locked, CI-gated template means the build that
   was green yesterday is green today — the exact property ad-hoc CMP setups lack.
-- **Proven, not assumed.** Every scaffold ends on a real build (and an Appium smoke), with a
-  GREEN/FAIL verdict.
+- **Proven, not assumed.** Every scaffold ends on the verify lane — real build + the full JVM
+  test tier — with a typed GREEN/FAIL verdict and an evidence receipt.
 
 If `create-next-app` made React the default for the web by removing setup friction, the goal here is
 the same for multiplatform mobile.
@@ -191,35 +220,44 @@ the same for multiplatform mobile.
 Front doors:  npx create-cmp-cli   +   Claude Code plugin (cmp-new / cmp-doctor / cmp-qa-prep)
                                   │  one shared engine, two front doors
 Engine (Node, deterministic):     copy → token-replace → rename packages → toggle features → VERIFY
-Golden template (frozen, CI'd):   pinned versions · iOS shell · nav+insets · Clean Arch · DI · Appium
+Golden template (frozen, CI'd):   pinned versions · iOS shell · nav+insets · Clean Arch · DI · test pyramid
 ```
 
 The engine never puts an LLM in the hot path: it copies the template, replaces placeholders in file
 contents *and* paths, atomically renames package directories, toggles features (Firebase / auth type
-/ Room / Appium), and runs the verify build. Determinism is the moat. See
-[`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) for the full design.
+/ Room / the e2e harness — feature key `e2e`, renamed from `appium` in 0.3.0; the old
+`--no-appium` flag still works as a deprecated alias), and runs the verify
+build. Determinism is the moat. See
+[`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) for the full design, and
+[`docs/DOCUMENTATION.md`](./docs/DOCUMENTATION.md) for the map of every doc — what's
+authoritative for what, and the standards each implements.
 
 ## Requirements
 
 - **Node.js ≥ 18** to run the scaffolder.
 - **macOS** for iOS output (Xcode, CocoaPods, XcodeGen). Android output works on macOS or Linux.
-- Everything else — JDK 17, Android SDK + emulator, CocoaPods, XcodeGen, Appium + drivers — the
-  built-in `doctor` detects and (with your consent) installs. Xcode itself must be installed from the
-  App Store; the doctor surfaces that as the one manual step.
+- Everything else — JDK 17, Android SDK + emulator, CocoaPods, XcodeGen, Appium + drivers (legacy
+  e2e path) — the built-in `doctor` detects and (with your consent) installs. The E2E flows
+  themselves run on Maestro, installed separately with
+  `curl -fsSL https://get.maestro.mobile.dev | bash`. Xcode itself must be installed from the App
+  Store; the doctor surfaces that as the one manual step.
 
 ## Roadmap
 
 The full plan — six pillars from scaffold to store release, and the sequencing — lives in
-[`docs/ROADMAP.md`](./docs/ROADMAP.md). Near-term:
-
-- [ ] Publish to npm as `create-cmp-cli` (`npx create-cmp-cli`) — release cut, publish pending.
-- [ ] Record the asciinema demo (`npx create-cmp-cli` → green Android + iOS).
-- [ ] Full Android + iOS build matrix in CI (currently CI runs the engine unit tests).
+[`docs/ROADMAP.md`](./docs/ROADMAP.md). The AI delivery harness itself (exemplars → conformance
+gates → in-project generation → mechanical enforcement → observability) is **complete** — see
+[`docs/HARNESS-PLAN.md`](./docs/HARNESS-PLAN.md) for the per-layer detail. Near-term:
+
+- [x] Publish to npm as `create-cmp-cli` (`npx create-cmp-cli@latest`) — **live on the registry**;
+      `0.3.0` (the harness release) is prepared and pending its own publish.
+- [x] AI-native Compose inspector — read a running app's hierarchy, geometry, and *resolved design
+      tokens* as structured JSON (no screenshots), including **live on-device inspection** over a
+      loopback debug server. See [`docs/INSPECTOR-PLAN.md`](./docs/INSPECTOR-PLAN.md).
+- [x] Android build matrix in CI on every push; iOS matrix runs on manual dispatch.
+- [ ] Publish `create-cmp-cli@0.3.0` to npm (needs an interactive OTP session) + record the
+      asciinema demo (scaffold → `add-feature` → gate refuses a violation → fix → PASS).
 - [ ] More example features and nav shapes.
-- **AI-native Compose inspector** — read a running app's hierarchy, geometry, and *resolved design
-  tokens* as structured JSON (no screenshots). **Phase 0 (headless host-JVM render → inspect) is
-  built and verified**; live-emulator inspection is next. See
-  [`docs/INSPECTOR-PLAN.md`](./docs/INSPECTOR-PLAN.md).
 
 ## Contributing
 

package/bin/create-cmp.mjs

@@ -74,8 +74,9 @@ function printHelp() {
       `create (scaffold) flags:\n` +
       `  --name --package --bundle-id --region --theme-prefix\n` +
       `  --ios/--no-ios  --firebase/--no-firebase  --auth <email|phone|both|none>\n` +
-      `  --room/--no-room  --appium/--no-appium  --inspector/--no-inspector\n` +
+      `  --room/--no-room  --e2e/--no-e2e  --inspector/--no-inspector\n` +
       `  --dev-client/--no-dev-client   (desktop JVM window + Compose Hot Reload)\n` +
+      `  (--appium/--no-appium accepted as deprecated aliases for --e2e/--no-e2e)\n` +
       `  --tabs Home:home,Profile:person\n` +
       `  --target-dir  --verify/--no-verify  --yes  --force  --dry-run-verify\n\n` +
       `doctor flags:  --yes  --dry-run  --no-ios  --no-install  --target-dir <dir>  --fix\n` +

package/options.schema.json

@@ -14,7 +14,7 @@
     "platforms",
     "firebase",
     "room",
-    "appium",
+    "e2e",
     "inspector",
     "devClient",
     "tabs",
@@ -78,7 +78,10 @@
       }
     },
     "room": { "type": "boolean" },
-    "appium": { "type": "boolean" },
+    "e2e": {
+      "type": "boolean",
+      "description": "Device-level E2E harness (Maestro flows in qa/e2e/). Feature key renamed from `appium` to `e2e` in 0.3.0."
+    },
     "inspector": {
       "type": "boolean",
       "description": "Live on-device inspector: debug-only loopback HTTP server (127.0.0.1:9500) serving the Compose semantics tree + design-token catalog to the cmp-inspector MCP. Structurally absent from release builds."

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-cmp-cli",
-  "version": "0.2.0",
-  "description": "Scaffold a production-ready Kotlin/Compose Multiplatform app (Android + iOS) that builds green in minutes — toolchain auto-bootstrapped, navigation/insets pre-solved, Clean Architecture wired, Appium harness ready. Installs the `create-cmp` command.",
+  "version": "0.3.1",
+  "description": "The AI delivery harness for Kotlin/Compose Multiplatform — scaffolds a green-building app (Android + iOS) in minutes and holds AI-driven changes to a machine-enforced verify lane with a committed evidence receipt. Installs the `create-cmp` command.",
   "type": "module",
   "bin": {
     "create-cmp": "bin/create-cmp.mjs",

package/src/commands/create.mjs

@@ -4,6 +4,29 @@
 
 import { flagBool } from "../lib/args.mjs";
 
+// --- deprecated-flag compat -------------------------------------------------
+
+/**
+ * Tri-state boolean flag with a deprecated alias: prefers `name`/`no-name`;
+ * if that's absent but the alias is present, uses it and prints a one-line
+ * deprecation warning. `--appium/--no-appium` was renamed to `--e2e/--no-e2e`
+ * in 0.3.0 (ADR-0002) — this keeps the old flag working.
+ */
+function flagBoolWithAlias(flags, name, aliasName, dflt) {
+  const primarySet = flags[name] !== undefined || flags[`no-${name}`] !== undefined;
+  if (primarySet) return flagBool(flags, name, dflt);
+
+  const aliasSet = flags[aliasName] !== undefined || flags[`no-${aliasName}`] !== undefined;
+  if (aliasSet) {
+    process.stderr.write(
+      `Warning: --${aliasName}/--no-${aliasName} is deprecated; use --${name}/--no-${name} instead.\n`
+    );
+    return flagBool(flags, aliasName, dflt);
+  }
+
+  return dflt;
+}
+
 // --- name helpers ------------------------------------------------------------
 
 function parseTabs(str) {
@@ -61,7 +84,7 @@ function buildConfigFromFlags(flags, positional) {
       fcm: flagBool(flags, "fcm", firebase),
     },
     room: flagBool(flags, "room", true),
-    appium: flagBool(flags, "appium", true),
+    e2e: flagBoolWithAlias(flags, "e2e", "appium", true),
     inspector: flagBool(flags, "inspector", true),
     devClient: flagBool(flags, "dev-client", true),
     tabs: parseTabs(flags.tabs) || [
@@ -135,7 +158,7 @@ async function interactiveConfig(positional) {
   const extras = await prompts(
     [
       { type: "confirm", name: "room", message: "Room local cache?", initial: true },
-      { type: "confirm", name: "appium", message: "Appium test harness?", initial: true },
+      { type: "confirm", name: "e2e", message: "E2E test harness (Maestro)?", initial: true },
       {
         type: "confirm",
         name: "inspector",
@@ -173,7 +196,7 @@ async function interactiveConfig(positional) {
     platforms: { android: true, ios: base.ios },
     firebase: { enabled: base.firebase, auth, firestore, storage, functions, fcm },
     room: extras.room,
-    appium: extras.appium,
+    e2e: extras.e2e,
     inspector: extras.inspector,
     devClient: extras.devClient,
     tabs: parseTabs(extras.tabs) || [{ label: "Home", icon: "home" }],

package/src/lib/toggle.mjs

@@ -86,7 +86,7 @@ export function stripFeatureBlocks(content, disabledFeatures) {
 
 /**
  * Map an engine config object to the set of DISABLED feature names that the
- * manifest understands: ios, firebase, room, appium, inspector, dev-client.
+ * manifest understands: ios, firebase, room, e2e, inspector, dev-client.
  * @param {object} config
  * @returns {Set<string>}
  */
@@ -95,7 +95,7 @@ export function disabledFeaturesFromConfig(config) {
   if (!config.platforms?.ios) disabled.add("ios");
   if (!config.firebase?.enabled) disabled.add("firebase");
   if (!config.room) disabled.add("room");
-  if (!config.appium) disabled.add("appium");
+  if (!config.e2e) disabled.add("e2e");
   if (!config.inspector) disabled.add("inspector");
   if (!config.devClient) disabled.add("dev-client");
   return disabled;

package/template/.claude/settings.json

@@ -0,0 +1,12 @@
+{
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          { "type": "command", "command": "node qa/receipt-check.mjs --hook" }
+        ]
+      }
+    ]
+  }
+}

package/template/.claude/skills/add-feature/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: add-feature
+description: >-
+  Add a new conforming vertical-slice feature (Screen + ViewModel + UseCase + Repository + spec
+  + tests + golden tree + nav route + DI wiring) to this Compose Multiplatform app, cloned
+  deterministically from the `home` exemplar. Use this when the user wants to "add a feature",
+  "add a screen with data", "scaffold a feature", "create a new screen backed by a repository",
+  "add a list screen", or names a new domain noun they want a screen for (e.g. "add a Favorites
+  feature", "I need a Bookmarks screen"). Works with NO create-cmp plugin installed — the
+  stamper (`qa/scaffold-feature.mjs`) and this skill both ship inside the generated project.
+---
+
+# add-feature — stamp a conforming vertical slice
+
+> Spec-first, deterministic-stamp, gate-proven. The script (`qa/scaffold-feature.mjs`) does the
+> mechanical work — copy the `home` exemplar file set, whole-word identifier rename, anchor
+> injection into the three shared files. You (the AI) only refine spec wording and adapt the
+> feature to its real shape. You are not done until `node qa/verify.mjs` PASSes and the receipt
+> is committed — see this project's `CLAUDE.md`.
+
+## Why a stamper and not hand-written files
+
+This project's whole thesis is that determinism beats freehand generation for anything
+architecturally load-bearing (see `docs/adr/0001-*.md` if present, or just: every hand-written
+file is a drift chance). `qa/scaffold-feature.mjs` produces a **conforming skeleton by
+construction** — it passes the architecture conformance gates before you write a line of
+feature-specific logic. Your job is to make it *behave* like the real feature, not to make it
+*structurally correct* — that part is already done.
+
+## The flow
+
+### 1. Interview
+
+Ask the human for the feature name (PascalCase, plural-ish noun — e.g. `Favorites`,
+`Bookmarks`). Propose a singular entity name by stripping a trailing `s`/`ies` (`Favorites` →
+`Favorite`, `Categories` → `Category`). Naive de-pluralization is unreliable for irregular nouns
+— **always show your proposed entity name and let the human confirm or override it** before
+proceeding (`--entity <EntityName>`).
+
+### 2. Dry-run
+
+Run:
+
+```
+node qa/scaffold-feature.mjs <FeatureName> --entity <EntityName> --dry-run
+```
+
+Show the human the file plan and the anchor-injection diffs it prints. Confirm before stamping
+for real — this is the last chance to catch a wrong entity name or a naming collision.
+
+### 3. Stamp
+
+Run the same command without `--dry-run`:
+
+```
+node qa/scaffold-feature.mjs <FeatureName> --entity <EntityName>
+```
+
+This writes the new Screen/ViewModel/UseCase/Repository(+impl)/tests/fake, wires them into
+`di/AppModule.kt`, `presentation/navigation/Screen.kt`, and `presentation/navigation/AppNavHost.kt`
+at their `// cmp:anchor` markers, and writes `specs/<feature>.spec.md` with a default six-clause
+set (`<FEATURE>-01..06`: loading, success, error, reload-after-failure, tap-navigates, golden
+tree) — copied verbatim from the `home` exemplar's shape.
+
+If it exits non-zero, read the message — it is actionable (name already taken, an anchor marker
+is missing, or a name isn't a valid Kotlin identifier). Do not hand-edit around a stamper
+failure; if an anchor is genuinely missing from a shared file, that is a template defect worth
+flagging, not something to route around by hand-splicing.
+
+### 4. Refine the spec, then the behavior
+
+The default spec clauses are placeholders shaped like the `home` exemplar (a plain list of
+title/subtitle rows). **Rewrite the clause prose** in `specs/<feature>.spec.md` to describe the
+feature's real behavior — the six clause **ids stay fixed** (`specCoverage` binds tests to ids,
+not prose), only the wording changes. Propose the rewritten clauses to the human; get them
+confirmed before moving on — this project's contract is spec-first.
+
+Then adapt the generated code to match:
+
+- If the feature isn't shaped like "a list of `{id, title, subtitle}`", update the entity's
+  fields in `domain/model/<Entity>.kt`, the sample data in `<Entity>RepositoryImpl.kt`, and the
+  screen's rendering in `presentation/<feature>/<Feature>Screen.kt` together — keep them
+  consistent with each other and with the tests.
+- Update the copied tests (`<Feature>ViewModelTest.kt`, `<Feature>ScreenTest.kt`) to match
+  whatever you changed. The gate (step 6) will tell you exactly what you missed — a compile
+  error names the mismatch; a spec-coverage failure names an orphaned clause or tag.
+- Leave the DI wiring, nav route, and screen scaffold as stamped unless the feature genuinely
+  needs a different shape (e.g. no navigation-on-tap — then remove the `-05` clause's
+  citing test and strike the clause through, don't leave it dangling).
+- The new screen is reachable via `Screen.<Feature>` but is **not** wired into a bottom-nav tab
+  by this generator (MVP scope — pushed-route only). Promoting it to a tab is a manual edit to
+  `appTabs()` + `AppShell` call sites; a future `--tab` flag may automate this.
+
+### 5. Capture the golden tree
+
+The golden baseline is **not** copied by the stamper (a copied one would silently mismatch the
+adapted screen). Generate it fresh once the screen renders the real behavior:
+
+```
+UPDATE_GOLDEN=1 ./gradlew :composeApp:desktopTest --tests "*<Feature>GoldenTree*"
+```
+
+Review `qa/golden/<feature>.json` briefly — it should reflect the structure you intended, not a
+copy-paste artifact. Commit it alongside the feature.
+
+### 6. Gate
+
+```
+node qa/verify.mjs
+```
+
+This must PASS. It proves: the spec's six clauses are all bound to a citing test
+(`specCoverage`), the build compiles, unit tests pass (ViewModel + UseCase + Repository +
+fakes), architecture conformance holds (`presentation` doesn't import `data`, the new
+`*Screen.kt` carries a `testTag`, the new `*ViewModel.kt` has a matching test), the golden tree
+matches what you just captured, and accessibility holds. **Not done until this is PASS and the
+evidence receipt (`qa/evidence/latest.json`) is committed with your change** — this is this
+project's standing definition of done (see `CLAUDE.md`).
+
+If it fails: read the failing step's reason (it is worded for exactly this), fix the actual
+behavior or spec/test binding, and re-run. Do not delete or weaken a test to reach green.
+
+## Guardrails
+
+- This flow works identically with or without the create-cmp Claude Code plugin installed —
+  everything it needs (`qa/scaffold-feature.mjs`, this file) ships inside the generated project.
+- Respect whichever toggles this project was stamped with (e.g. if Room or Appium/Maestro were
+  disabled at scaffold time, don't reintroduce them for the new feature).
+- `add-feature` generates a pushed-nav-route screen, not a bottom-nav tab, and does not generate
+  a "tap → detail" destination (the exemplar's `DetailScreen.kt` is intentionally not copied —
+  MVP scope). Both are documented future extensions, not omissions to silently work around.

package/template/.claude/skills/add-repository/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: add-repository
+description: >-
+  Add a data/domain slice ONLY — model, repository interface + impl, use case, and a
+  hand-written fake — to this Compose Multiplatform app, cloned deterministically from the
+  `home` exemplar's data layer. No screen, no ViewModel, no nav route, no spec clauses. Use this
+  when the user wants to "add a repository", "add a data source", "model a new entity", "new
+  entity with a repository", or names a domain noun they want backed by data before any UI exists
+  (e.g. "add a Tag repository", "I need a data source for Bookmarks"). Works with NO create-cmp
+  plugin installed — the stamper (`qa/scaffold-feature.mjs --preset repository`) and this skill
+  both ship inside the generated project.
+---
+
+# add-repository — stamp a data/domain slice only
+
+> Deterministic-stamp, gate-proven. The script (`qa/scaffold-feature.mjs --preset repository`)
+> does the mechanical work — copy the `home` exemplar's data/domain files, whole-word identifier
+> rename, DI injection for the repository + use case only. You (the AI) only customize the
+> entity's fields and its sample data. You are not done until `node qa/verify.mjs` PASSes and the
+> receipt is committed — see this project's `CLAUDE.md`.
+
+This is the `repository` subset of `add-feature` — same stamper, same rename mechanic, filtered
+to just the 5 data/domain files. Use it when you want the data layer to exist before any screen
+consumes it (e.g. you're modeling several entities up front, or a screen for this entity will
+come later via `add-screen`).
+
+## Why a stamper and not hand-written files
+
+Every hand-written file is a drift chance in this project's architecture. `qa/scaffold-feature.mjs
+--preset repository` produces a **conforming skeleton by construction** for the data/domain
+layer: a domain model, a domain repository interface, a use case, a data-layer impl, and a
+hand-written fake for tests — wired into Koin. Your job is to make the entity's shape and sample
+data real, not to make the wiring correct — that part is already done.
+
+## The flow
+
+### 1. Name the entity
+
+Ask the human for the entity name — PascalCase, singular (e.g. `Tag`, `Bookmark`, `Category`).
+Unlike `add-feature`/`add-screen`, there is no feature name and no `--entity` flag here: the
+positional argument **is** the entity.
+
+### 2. Dry-run
+
+```
+node qa/scaffold-feature.mjs <Entity> --preset repository --dry-run
+```
+
+Show the human the file plan (5 files: `domain/model/<Entity>.kt`,
+`domain/repository/<Entity>Repository.kt`, `domain/usecase/Get<Entity>sUseCase.kt`,
+`data/remote/<Entity>RepositoryImpl.kt`, `testing/fakes/Fake<Entity>Repository.kt`) and the DI
+injection diffs (repository binding + use case factory only — no ViewModel, no nav). Confirm
+before stamping for real.
+
+### 3. Stamp
+
+```
+node qa/scaffold-feature.mjs <Entity> --preset repository
+```
+
+If it exits non-zero, read the message — it is actionable (entity name already taken, or not a
+valid Kotlin identifier). Do not hand-edit around a stamper failure.
+
+### 4. Customize the entity and its data
+
+The generated shape mirrors `home`'s `Item` (an `{id, title, subtitle}` list entity). Adapt it to
+the real entity:
+
+- Update the fields in `domain/model/<Entity>.kt` to match the real shape.
+- Update the sample/seed data in `<Entity>RepositoryImpl.kt` accordingly.
+- Update `Fake<Entity>Repository.kt` (`testing/fakes/`) to match the model's new fields — it's
+  the hand-written fake every future test against this entity will use.
+- Leave the DI wiring (`di/AppModule.kt`) as stamped unless you're renaming something — it's
+  already correct: `single<<Entity>Repository> { <Entity>RepositoryImpl() }` and
+  `factory { Get<Entity>sUseCase(get()) }`.
+
+**No spec clauses are added by this preset, and that's intentional** — a bare repository has no
+observable behavior to specify yet (no screen, no user-facing flow). Clauses attach once a
+screen consumes this entity; that's `add-screen`'s job (`FEATURE-01..06` bound to the repository
+you just built).
+
+### 5. Gate
+
+```
+node qa/verify.mjs
+```
+
+This must PASS. It proves: the build compiles, unit tests pass (use case + repository + fake),
+and architecture conformance holds (`domain` imports nothing app-internal, `data` implements the
+`domain` interface). specCoverage is untouched by this preset — expect the same clause/tag counts
+as before you ran the stamper. **Not done until this is PASS and the evidence receipt
+(`qa/evidence/latest.json`) is committed with your change.**
+
+If it fails: read the failing step's reason and fix the actual behavior. Do not delete or weaken
+a test to reach green.
+
+## Guardrails
+
+- Works identically with or without the create-cmp Claude Code plugin installed — everything it
+  needs (`qa/scaffold-feature.mjs`, this file) ships inside the generated project.
+- Respect whichever toggles this project was stamped with (e.g. Room disabled at scaffold time
+  stays disabled — this preset never introduces Room coupling, matching the exemplar's
+  dependency-light `RepositoryImpl` pattern).
+- This preset stamps data/domain only. If the human actually wants a screen too, either run
+  `add-feature` (the full slice) instead, or follow up with `add-screen --entity <Entity>` once
+  this repository exists.