@bonesofspring/ai-rules 0.2.15 → 0.2.17

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 ## Unreleased
 
+### Product specs authoring (Phases A–E)
+
+- **Generation modes** (shared-core): **Consume** (default discovery, soft-fail on miss) · **Generate** (explicit intent / AC / `/spec-start` with existing tree) · **Bootstrap** (same triggers when `docs/specs/` absent). Greenfield policy: no INDEX/spec invention without explicit intent; conflict precedence human > brief AC > approved spec > code.
+- Split requestable stems: lean `architecture/product-specs.md` (Consume) + `architecture/product-specs-authoring.md` (Generate / Bootstrap, INDEX + frontmatter v1, body checklist). Both ×20 Cursor + Claude adapters (`alwaysApply: false` / Claude `paths: docs/specs/**/*`); Stack notes map `routes` / `ui` / `store` / `e2e` per stack class (mcp-ts: tool names; empty `ui`/`store`).
+- **Assets SoT:** `presets/_shared/assets/docs-specs/` — INDEX stub, `_templates/page.md` / `feature.md`, optional `schemas/frontmatter-v1.schema.json`.
+- **CLI seed policy:** on `init`, when consumer `docs/specs/` directory is **absent**, copy INDEX stub + `_templates/*` from assets (idempotent; **never overwrite** existing INDEX). If the directory already exists (even empty), seed is skipped — remove the folder or copy templates manually if you created an empty tree before first `init`.
+- **Author surface:** extend **task-analyst** (primary author; **mcp-ts analyst-only** — no tech-writer) + **tech-writer** post-delivery sync (9 stacks); requestable skill **`spec-authoring`**; **feature-developer** / **feature-delivery** treat approved specs as behavior SoT.
+- **Pipeline:** optional `/spec-start` (spec-gen → analyst author mode → human gate); task-router `spec-gen` / bootstrap signals; orchestrator passes spec paths + INDEX diff (no dedicated `spec-author` agent).
+- **Validation severity:** code-reviewer **WARN** code/spec drift, **FAIL** broken INDEX links or missing required frontmatter on touched `docs/specs/**`; build-verifier **FAIL** missing shared assets / broken twins / non-requestable stems; optional `scripts/check-product-specs.sh` (**WARN** default, **`--strict`** FAIL) — not mandatory consumer CI.
+- **Dogfood:** `dogfood/mcp-ts-sample/docs/specs/` (INDEX + `domains/echo/echo-tool.md`; sample spec human-promoted to `active`). Soft WARN in `check:preset-structure` + GitHub `preset-structure` workflow (`yarn check:product-specs:dogfood`, `continue-on-error`).
+- **Follow-ups:** dogfood `.cursor/` re-synced from next; removed ambiguous `**mcp-ts:**` footnote from non–mcp-ts `task-analyst` twins (mcp-ts analyst-only wording kept on mcp-ts only).
+- **Consumers:** after publish, re-run `npx @bonesofspring/ai-rules init cursor|claude --preset <stack>` to pick up new stems, `/spec-start`, and `spec-authoring` skill; preset files under `.cursor/` / `.claude/` are overwritten on init — existing consumer `docs/specs/` trees are **not** overwritten.
+
+### Product specs stem (`product-specs`)
+
+- New shared-core embed stem `architecture/product-specs.md`: stack-agnostic `docs/specs` INDEX discovery, soft-fail on miss, authoring/INDEX same-PR, non-goals vs `.ai/context` / `reference-features`.
+- Requestable Cursor + Claude adapters ×10 stacks (`product-specs.mdc` / `architecture/product-specs.md`) with frontend / mobile / backend Stack notes (no cross-stack UI-path leakage).
+- Agent one-liners: `task-analyst`, `feature-developer`, orchestrator adapters; `tech-writer` (stacks with tech-writer agent; mcp-ts excluded); `feature-delivery` skill early INDEX step; optional Related on `feature-delivery-workflow`.
+- Token budget: `alwaysApply: false` / Claude `paths: docs/specs/**` — not session-start.
+- Consumers: after publish, re-run `npx @bonesofspring/ai-rules init cursor|claude --preset <stack>` to pick up the stem.
+- Follow-up polish: android-kotlin Stack notes use `features/**` (not iOS `Features/**`); Claude next/nuxt/ios/android feature-delivery INDEX step numbering aligned with Cursor; next `code-reviewer` checks `docs/specs/**` drift via `product-specs`.
+
+
+### Android Kotlin preset (`android-kotlin`)
+
+- New installable preset **`android-kotlin`** (Cursor + Claude twins): Clean Architecture multimodule Android/Kotlin — Compose Material 3, MVI/UDF ViewModels, Dagger feature holders (no Hilt by default), `api`/`impl` modules, Gradle convention plugins / version catalog discovery, instrumentation UI-test agents.
+- Agent surface: `instrumentation-test-{planner,generator,healer}` + skill `instrumentation-ui-e2e`; gates `post-change-build` + `gradle-tooling` + `build-verifier`.
+- Structure scripts include `android-kotlin` (`STACKS` + `ANDROID_FORBIDDEN_*`); other stacks forbid `instrumentation-test-*` stems; shared-core `preset-*` matrices updated and embeds re-synced.
+- Install: `npx @bonesofspring/ai-rules init cursor|claude --preset android-kotlin`.
+- Dogfood default remains **`next`** (no switch to android-kotlin).
+
 ### Preset EN translation polish (patch)
 
 - Hardened `check-preset-i18n.sh`: ±3-line keep-marker window (matches style guide), scans `.md`/`.mdc` plus hook/script suffixes; wired as hard gate via `check:preset-i18n` and `check-preset-structure` / CI.

package/README.md

@@ -50,10 +50,27 @@ Where things go on `init`:
 | MCP | `mcp.json` → `.cursor/mcp.json`, `MCP.md` → `.cursor/` | `mcp.json` → **`.mcp.json`** (project root), `MCP.md` → `.claude/` |
 | tool map | `AGENTS.md` → `.cursor/AGENTS.md`, `BUGBOT.md` | `CLAUDE.md` → `.claude/CLAUDE.md` |
 | **repo-root agents** | `REPO_AGENTS.md` → **`<cwd>/AGENTS.md`** | same |
+| **docs/specs seed** | When `<cwd>/docs/specs/` is **absent**, copy INDEX stub + `_templates/*` from `presets/_shared/assets/docs-specs/` (never overwrite existing INDEX) | same |
 
-Skills of note: `write-adr` (all stacks); `react-performance` (**next only**); `vue-performance` (**nuxt only**); `svelte-performance` (**svelte only**). Living gotchas: `team/conventions.md`. Opt-in rule samples eval: `yarn check:rule-eval` (workflow `rule-eval.yml`; not part of `check:preset-structure`).
+Skills of note: `write-adr` (all stacks); `spec-authoring` (Generate/Bootstrap `docs/specs`); `react-performance` (**next only**); `vue-performance` (**nuxt only**); `svelte-performance` (**svelte only**). Optional command `/spec-start`. Living gotchas: `team/conventions.md`. Opt-in rule samples eval: `yarn check:rule-eval` (workflow `rule-eval.yml`; not part of `check:preset-structure`). Optional consumer specs check: `yarn check:product-specs` (WARN default; `--strict` FAIL).
 
-The package ships presets including **`next`** (Next.js stack), **`nuxt`** (Nuxt 3 / Vue 3 / Pinia), **`svelte`** (SvelteKit / Svelte 5 / TypeScript / `store-svelte`), **`ios-swift`** (iOS apps on Swift / SwiftUI), **`go`** (Go backends with hexagonal architecture), **`java`** (Java / Spring Boot hexagonal backends), **`mcp-ts`** (TypeScript MCP servers with `@modelcontextprotocol/sdk`), **`php-hexagonal`** (PHP / Composer hexagonal backends), and **`php-laravel`** (Laravel backend/API with Eloquent, Form Requests, Policies, Actions/Services). Other preset names: see `presets/` in the [repo](https://github.com/bonesofspring/ai-rules). Name is a single path segment, no `/` or `.`.
+## Product specs (`docs/specs/`)
+
+Presets support **behavior specs** under `docs/specs/**` (INDEX, frontmatter v1, page/feature templates). Three modes:
+
+| Mode | Trigger | Agent behavior |
+|------|---------|----------------|
+| **Consume** | Default when working on listed routes/features | Discover via INDEX; soft-fail on miss; do not invent product behavior |
+| **Generate** | Brief AC, `/spec-start`, or router `spec-gen` with existing tree | **task-analyst** authors/updates specs + INDEX (skill **`spec-authoring`**) |
+| **Bootstrap** | Same triggers when `docs/specs/` absent | Create INDEX + templates + first domain spec |
+
+**First-time seed:** `init` copies INDEX stub + `_templates/*` from package assets when `<cwd>/docs/specs/` is **absent** (see table above). **Troubleshooting:** if you created an empty `docs/specs/` folder before `init`, seed is skipped — delete the folder and re-run `init`, or copy from `presets/_shared/assets/docs-specs/` manually.
+
+**After a package upgrade:** re-run `init` for your stack to refresh rules, `/spec-start`, and `spec-authoring` skill. Agent-generated specs default to `status: draft` until a human promotes them.
+
+**Optional validation** (from `packages/ai-rules/`): `yarn check:product-specs <repo-root>` (WARN) or `--strict` (FAIL). Monorepo dogfood example: `dogfood/mcp-ts-sample/docs/specs/`.
+
+The package ships presets including **`next`** (Next.js stack), **`nuxt`** (Nuxt 3 / Vue 3 / Pinia), **`svelte`** (SvelteKit / Svelte 5 / TypeScript / `store-svelte`), **`ios-swift`** (iOS apps on Swift / SwiftUI), **`android-kotlin`** (Android multimodule Kotlin / Compose / Gradle), **`go`** (Go backends with hexagonal architecture), **`java`** (Java / Spring Boot hexagonal backends), **`mcp-ts`** (TypeScript MCP servers with `@modelcontextprotocol/sdk`), **`php-hexagonal`** (PHP / Composer hexagonal backends), and **`php-laravel`** (Laravel backend/API with Eloquent, Form Requests, Policies, Actions/Services). Other preset names: see `presets/` in the [repo](https://github.com/bonesofspring/ai-rules). Name is a single path segment, no `/` or `.`.
 
 ```bash
 npx @bonesofspring/ai-rules init cursor --preset nuxt
@@ -62,6 +79,8 @@ npx @bonesofspring/ai-rules init cursor --preset svelte
 npx @bonesofspring/ai-rules init claude --preset svelte
 npx @bonesofspring/ai-rules init cursor --preset ios-swift
 npx @bonesofspring/ai-rules init claude --preset ios-swift
+npx @bonesofspring/ai-rules init cursor --preset android-kotlin
+npx @bonesofspring/ai-rules init claude --preset android-kotlin
 npx @bonesofspring/ai-rules init cursor --preset go
 npx @bonesofspring/ai-rules init claude --preset go
 npx @bonesofspring/ai-rules init cursor --preset java
@@ -80,7 +99,7 @@ Help: `ai-rules --help`.
 
 Presets are developed in this monorepo under `presets/`. If you add or change rules, agents, or platform artifacts:
 
-- **Taxonomy & layers:** [`presets/_shared/README.md`](presets/_shared/README.md) — shared core (`_shared/core`), stack adapters, platform packaging
+- **Taxonomy & layers:** [`presets/_shared/README.md`](presets/_shared/README.md) — shared core (`_shared/core`), stack adapters, platform packaging (includes requestable embed stem `architecture/product-specs` for consumer `docs/specs` INDEX discovery)
 - **Contribution guide:** [`docs/PRESET-CONTRIBUTION.md`](docs/PRESET-CONTRIBUTION.md) — SoT, twin sync, embed vs lineage, token budget (≤3 always-on), PR checklist, new stack preset, platform-only files (`BUGBOT.md`, `CLAUDE.md`)
 - **Dogfood / drift scripts:** [`scripts/sync-dogfood-cursor.sh`](scripts/sync-dogfood-cursor.sh) (also syncs root `AGENTS.md` from `REPO_AGENTS.md`; seeds `team/conventions.md` if absent), [`scripts/check-shared-core-drift.sh`](scripts/check-shared-core-drift.sh)
 - **Preset structure CI gates** (exit non-zero on FAIL): `yarn check:preset-structure` (or `bash scripts/check-preset-structure.sh`) — twin map, session-start budget (Option A), leakage, shared-core drift (`AI_RULES_DRIFT_FAIL=1`)

package/bin/cli.js

@@ -64,6 +64,7 @@ Notes:
   Cursor init copies rules, commands, agents, hooks, skills, team, hooks.json, BUGBOT.md, AGENTS.md → .cursor/AGENTS.md, MCP.md, mcp.json → .cursor/mcp.json.
   Claude init copies rules, commands, skills, agents, hooks, team, CLAUDE.md, MCP.md, and mcp.json → .mcp.json (project root).
   Both tools also copy REPO_AGENTS.md → <cwd>/AGENTS.md (repo-root cross-tool agents file; overwrite).
+  When <cwd>/docs/specs/ is absent, init also seeds INDEX.md stub + _templates/* from package assets (never overwrites an existing INDEX).
   clean removes tool dirs/files and <cwd>/AGENTS.md (shared across tools — re-init the other tool to restore).
   Command forms: "init cursor --preset next", "init cursor next", "--preset next init cursor", "cursor init --preset next".
 
@@ -73,6 +74,7 @@ Examples:
   npx @bonesofspring/ai-rules init cursor --preset nuxt
   npx @bonesofspring/ai-rules init cursor --preset svelte
   npx @bonesofspring/ai-rules init cursor --preset ios-swift
+  npx @bonesofspring/ai-rules init cursor --preset android-kotlin
   npx @bonesofspring/ai-rules init cursor --preset go
   npx @bonesofspring/ai-rules init cursor --preset java
   npx @bonesofspring/ai-rules init cursor --preset mcp-ts
@@ -82,6 +84,7 @@ Examples:
   npx @bonesofspring/ai-rules init claude --preset nuxt
   npx @bonesofspring/ai-rules init claude --preset svelte
   npx @bonesofspring/ai-rules init claude --preset ios-swift
+  npx @bonesofspring/ai-rules init claude --preset android-kotlin
   npx @bonesofspring/ai-rules init claude --preset go
   npx @bonesofspring/ai-rules init claude --preset java
   npx @bonesofspring/ai-rules init claude --preset mcp-ts
@@ -221,6 +224,40 @@ function copyDir(src, dest) {
   }
 }
 
+/**
+ * Seed consumer docs/specs when the tree is absent.
+ * Idempotent: never overwrite existing INDEX; skip entirely if docs/specs exists.
+ */
+function seedDocsSpecsIfAbsent(packageRoot, cwd) {
+  const destRoot = path.join(cwd, 'docs', 'specs');
+  if (fs.existsSync(destRoot)) {
+    console.log('Skipped docs/specs seed (directory already exists)');
+    return false;
+  }
+  const assetsRoot = path.join(
+    packageRoot,
+    'presets',
+    '_shared',
+    'assets',
+    'docs-specs'
+  );
+  if (!fs.existsSync(assetsRoot)) {
+    console.log('Skipped docs/specs seed (package assets missing)');
+    return false;
+  }
+  fs.mkdirSync(destRoot, { recursive: true });
+  const indexSrc = path.join(assetsRoot, 'INDEX.md');
+  if (fs.existsSync(indexSrc)) {
+    fs.copyFileSync(indexSrc, path.join(destRoot, 'INDEX.md'));
+  }
+  const templatesSrc = path.join(assetsRoot, '_templates');
+  if (fs.existsSync(templatesSrc)) {
+    copyDir(templatesSrc, path.join(destRoot, '_templates'));
+  }
+  console.log('Seeded docs/specs/ (INDEX stub + _templates)');
+  return true;
+}
+
 function getOptionalDirs(cfg) {
   return cfg.optionalCursorDirs || cfg.optionalClaudeDirs || [];
 }
@@ -420,6 +457,10 @@ function cmdInit(tool, preset, cwdOption) {
         copiedSteps++;
       }
     }
+
+    if (seedDocsSpecsIfAbsent(packageRoot, cwd)) {
+      copiedSteps++;
+    }
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     console.error(`init failed: ${msg}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bonesofspring/ai-rules",
-  "version": "0.2.15",
+  "version": "0.2.17",
   "description": "Presets of Cursor and Claude rules/commands for Revy Ross personal use",
   "license": "MIT",
   "author": "Revy Ross",
@@ -31,6 +31,8 @@
     "check:preset-leakage": "bash scripts/check-preset-leakage.sh",
     "check:preset-i18n": "AI_RULES_I18N_FAIL=1 AI_RULES_I18N_SOFT=0 bash scripts/check-preset-i18n.sh",
     "check:shared-core-drift": "bash scripts/check-shared-core-drift.sh",
+    "check:product-specs": "bash scripts/check-product-specs.sh",
+    "check:product-specs:dogfood": "bash scripts/check-product-specs.sh ../../dogfood/mcp-ts-sample",
     "check:rule-eval": "node scripts/check-rule-eval.mjs"
   },
   "engines": {

package/presets/_shared/README.md

@@ -1,6 +1,6 @@
 # Shared preset core (`presets/_shared`)
 
-Stack-agnostic **prose and checklists** for all installable presets: `next`, `nuxt`, `ios-swift`, `go`, `java`, `mcp-ts`, `php-hexagonal`, and `php-laravel` (`cursor/<stack>`, `claude/<stack>`).
+Stack-agnostic **prose and checklists** for all installable presets: `next`, `nuxt`, `svelte`, `ios-swift`, `android-kotlin`, `go`, `java`, `mcp-ts`, `php-hexagonal`, and `php-laravel` (`cursor/<stack>`, `claude/<stack>`).
 
 **Not an installable preset.** CLI `init` copies only under `presets/cursor/<name>/` or `presets/claude/<name>/` — this sibling is never shipped to consumer apps.
 
@@ -38,7 +38,7 @@ Do **not** expect lineage adapters to byte-match core. Embed adapters should mat
 |-----|----------|
 | `core/quality/` | Boy-scout + Principles (always-on slim); requestable `anti-sycophancy-discipline` (~17 rules); requestable `design-guidance` (smells ≤12 + GoF ≤8) |
 | `core/agent-team/` | Orchestrator + intake (pipeline language) |
-| `core/architecture/` | Feature-delivery abstract + reference-features template |
+| `core/architecture/` | Feature-delivery abstract + reference-features template + product-specs (+ product-specs-authoring) + assets/docs-specs templates |
 | `core/review/` | Code-review MR + technical-retro alias |
 | `core/meta/` | Author-facing preset meta-rules |
 

package/presets/_shared/assets/docs-specs/INDEX.md

@@ -0,0 +1,9 @@
+# Product specs INDEX
+
+Discovery table for `docs/specs/**`. Agents start here when the file exists.
+
+| id | type | domain | title | path | routes | aliases | status |
+|----|------|--------|-------|------|--------|---------|--------|
+| <!-- example-row: example-page | page | example | Example page | docs/specs/domains/example/example-page.md | /example | ExamplePage | draft --> |
+
+<!-- Add one row per page/feature spec. Keep `id` and `path` in sync with frontmatter. -->

package/presets/_shared/assets/docs-specs/_templates/feature.md

@@ -0,0 +1,32 @@
+---
+id: example-feature
+type: feature
+domain: example
+routes: []
+ui: []
+store: []
+api: []
+aliases: []
+e2e: []
+status: draft
+owners: []
+related: []
+---
+
+# Example feature
+
+## Overview
+
+Cross-page shared behavior for this domain. Prefer `type: feature` on backend/MCP stacks.
+
+## Shared behavior / constraints
+
+- Invariants that apply across related pages/tools.
+
+## Related pages
+
+- Link page specs in this domain (or N/A).
+
+## Cross-cutting states
+
+N/A

package/presets/_shared/assets/docs-specs/_templates/page.md

@@ -0,0 +1,47 @@
+---
+id: example-page
+type: page
+domain: example
+routes: []
+ui: []
+store: []
+api: []
+aliases: []
+e2e: []
+status: draft
+owners: []
+related: []
+---
+
+# Example page
+
+## Overview
+
+Short product behavior summary. Replace placeholders from brief AC / user / labeled sources.
+
+## Entry / actors
+
+Who enters this page and from where.
+
+## Primary flows
+
+1. Happy path steps.
+
+## States
+
+- Loading: …
+- Empty: …
+- Error: …
+- Success: …
+
+## Acceptance criteria
+
+- [ ] Link or restated AC from brief / product source.
+
+## Edge cases
+
+N/A
+
+## Related specs
+
+- (optional feature.md or sibling page ids)

package/presets/_shared/assets/docs-specs/schemas/frontmatter-v1.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://bonesofspring.github.io/ai-rules/schemas/frontmatter-v1.schema.json",
+  "title": "Product spec frontmatter v1",
+  "type": "object",
+  "required": ["id", "type", "domain", "routes", "ui", "store", "api", "aliases", "e2e"],
+  "properties": {
+    "id": { "type": "string", "minLength": 1 },
+    "type": { "type": "string", "enum": ["page", "feature"] },
+    "domain": { "type": "string", "minLength": 1 },
+    "routes": { "type": "array", "items": { "type": "string" } },
+    "ui": { "type": "array", "items": { "type": "string" } },
+    "store": { "type": "array", "items": { "type": "string" } },
+    "api": { "type": "array", "items": { "type": "string" } },
+    "aliases": { "type": "array", "items": { "type": "string" } },
+    "e2e": { "type": "array", "items": { "type": "string" } },
+    "status": { "type": "string", "enum": ["draft", "active", "deprecated"] },
+    "owners": { "type": "array", "items": { "type": "string" } },
+    "related": { "type": "array", "items": { "type": "string" } }
+  },
+  "additionalProperties": true
+}

package/presets/_shared/core/architecture/product-specs-authoring.md

@@ -0,0 +1,107 @@
+# Product specs authoring
+
+Load when **Generate** or **Bootstrap** is requested (`/spec-start`, router `spec-gen`, brief AC, or analyst author mode). Discovery-only work stays on **`product-specs`**.
+
+## Modes
+
+1. **Consume** — default; never invent INDEX/specs (see `product-specs`).
+2. **Generate** — create/update page/feature specs + INDEX rows from brief AC, user intent, Figma, or code archaeology. Inventing *product* behavior is forbidden without a stated source (AC / user / UI copy / code-observed behavior labeled `status: draft` or `inferred`).
+3. **Bootstrap** — create `INDEX.md` + `_templates/` copies + first domain spec under greenfield policy.
+
+## Greenfield policy
+
+Agents **may** create INDEX + first specs **only when** one of:
+
+1. User runs `/spec-start` or explicitly asks to bootstrap `docs/specs`.
+2. Brief/AC includes generation or bootstrap language.
+3. Router detects `spec-gen` intent.
+
+Otherwise: missing INDEX → optional tree; do **not** invent INDEX merely because discovery loaded.
+
+## Conflict precedence
+
+1. **Human gate** decision (approved brief/spec edits).
+2. **Current task `brief.md` AC** — if AC contradicts an existing spec, analyst must reconcile (update spec as `draft` or revise AC) before developer; no silent contradiction.
+3. **Approved `docs/specs/**`** — behavior SoT for feature-developer once gate passed.
+4. **Code / `.ai/context`** — discovery evidence only; never override approved spec without gate.
+
+Label inferred-from-code lines with `status: draft` until human promotes.
+
+## INDEX.md contract (v1)
+
+| Column | Required | Notes |
+|--------|----------|-------|
+| `id` | yes | Stable kebab/id matching frontmatter `id` |
+| `type` | yes | `page` \| `feature` |
+| `domain` | yes | Domain folder under `docs/specs/domains/<domain>/` |
+| `title` | yes | Human label |
+| `path` | yes | Repo-relative path to markdown file |
+| `routes` | no | Summary; may duplicate frontmatter |
+| `aliases` | no | Comma-separated PageName / deep-link aliases |
+| `status` | no | `draft` \| `active` \| `deprecated` |
+
+Layout: `docs/specs/domains/<domain>/<id>.md` (page) and optional `docs/specs/domains/<domain>/feature.md`. Adding/renaming/removing a linked file **must** update INDEX in the **same change set**.
+
+## Frontmatter v1
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `id` | string | yes | Unique; matches INDEX |
+| `type` | enum `page` \| `feature` | yes | Backend/MCP: prefer `feature` |
+| `domain` | string | yes | |
+| `routes` | string[] | yes (may be `[]`) | Web: URL paths; mobile: deep links/screens; backend: HTTP paths; mcp-ts: tool names |
+| `ui` | string[] | yes (may be `[]`) | Component/screen refs; empty on backend/mcp |
+| `store` | string[] | yes (may be `[]`) | Slice/module refs; empty when N/A |
+| `api` | string[] | yes (may be `[]`) | Services/ports/tools |
+| `aliases` | string[] | yes (may be `[]`) | |
+| `e2e` | string[] | yes (may be `[]`) | Stack-appropriate test paths |
+| `status` | enum | no | default `draft` on agent generate |
+| `owners` | string[] | no | |
+| `related` | string[] | no | Spec ids or paths |
+
+Arrays are **always present** (empty allowed). Do not omit keys for N/A stacks.
+
+## Body headings (minimum)
+
+**`page` required:** Overview; Entry / actors; Primary flows; States (loading / empty / error / success as applicable — mark N/A explicitly); Acceptance criteria (links or bullets to brief AC / product source).
+
+**`page` optional:** Analytics, Accessibility, Edge cases, Related specs.
+
+**`feature` required:** Overview; Shared behavior / constraints; Related pages (links).
+
+**`feature` optional:** Cross-cutting states, Analytics.
+
+Compliant = valid frontmatter + all required headings present (non-empty prose or explicit `N/A`) + INDEX row with resolvable `path`.
+
+## Templates & assets
+
+**Package SoT:** `packages/ai-rules/presets/_shared/assets/docs-specs/` (`INDEX.md` stub, `_templates/page.md`, `_templates/feature.md`; optional `schemas/frontmatter-v1.schema.json`).
+
+**CLI `init`:** when consumer `docs/specs/` is **absent**, copy INDEX stub + `_templates/*` (idempotent; **never overwrite** existing INDEX). When the tree already exists, skip seed entirely.
+
+**Skill fallback:** if consumer `_templates/` missing during author mode, copy from package/skill assets before authoring.
+
+## Author roles
+
+| Role | Responsibility |
+|------|----------------|
+| **task-analyst** | Primary author (Generate + Bootstrap); INDEX bootstrap; brief **Related specs** + **Spec gaps / generation requested**; loads this stem + skill `spec-authoring` |
+| **tech-writer** | Post-delivery sync where present; never invent product behavior without AC/code source |
+| **feature-developer** | Consumes approved specs as SoT; mechanical INDEX/frontmatter fixes only on renames |
+| **mcp-ts** | No tech-writer — author + post-sync via **task-analyst** only |
+
+## Self-check before handoff (soft block)
+
+Block handoff via `open_questions` until fixed:
+
+- [ ] Required frontmatter keys present; arrays always present (may be `[]`)
+- [ ] Required body headings present (or explicit `N/A`)
+- [ ] INDEX row added/updated with resolvable `path` in the **same change set**
+- [ ] Sources cited; invented product behavior absent (or labeled `draft` / `inferred`)
+- [ ] Conflict with brief AC reconciled or flagged
+
+## Related
+
+- `product-specs` — discovery / consume
+- Skill `spec-authoring` — procedural checklist
+- Optional consumer script `scripts/check-product-specs.sh` (WARN default; `--strict` FAIL)

package/presets/_shared/core/architecture/product-specs.md

@@ -0,0 +1,49 @@
+# Product specs (docs/specs)
+
+Product page/feature **behavior** specs live under the consumer repo `docs/specs/**`. This stem covers **discovery and presence** — not layer implementation order (see `feature-delivery-workflow`) and not code-structure mirroring (see `reference-features`).
+
+**Authoring** (Generate / Bootstrap modes, INDEX/frontmatter v1, body checklist, greenfield, conflict precedence) → load **`product-specs-authoring`** when generation is requested (`/spec-start`, brief AC, or router `spec-gen`).
+
+## Modes (summary)
+
+| Mode | When | Behavior |
+|------|------|----------|
+| **Consume** (default) | INDEX exists or globs hit `docs/specs/**` without generate intent | Discover via INDEX; soft-fail on miss; **never invent** INDEX/specs |
+| **Generate** | Explicit generate intent / AC / `/spec-start` with existing tree | Create/update page/feature specs + INDEX from stated sources |
+| **Bootstrap** | Explicit bootstrap / `/spec-start` when tree absent | Create INDEX + templates + first domain spec |
+
+Greenfield: agents may create INDEX/specs **only** on explicit intent, AC, or `/spec-start`. Missing INDEX alone does **not** authorize inventing the tree.
+
+## Presence policy
+
+- If `docs/specs/INDEX.md` is **missing** → the tree is **optional** (greenfield OK for *consume*). Continue with code/brief discovery; do not invent an INDEX solely because this stem loaded.
+- If INDEX **exists** → it is the **required discovery path** for work that touches a listed page, feature, route, or alias.
+
+## Discovery algorithm
+
+1. Always start at `docs/specs/INDEX.md` when present.
+2. Resolve the entry by: route, stable `id`, PageName / alias, or domain folder.
+3. Read the linked page spec (and optional domain `feature.md` when the INDEX or page Related links it).
+
+## Miss policy (INDEX present, row or file missing)
+
+- Record the gap in `open_questions` / handoff gaps.
+- Fall back to code discovery and consumer `.ai/context/**` when present.
+- **Do not invent** product behavior, states, interactions, or contracts.
+- Hard-fail / block only when the task’s acceptance criteria explicitly require a named spec that is absent (human/gate decision).
+
+## Authoring pointer
+
+Same-changeset INDEX updates, frontmatter v1, required body headings, templates, and conflict precedence live in **`product-specs-authoring`**. Do not paste the full checklist here.
+
+## Non-goals
+
+- Not a replacement for `.ai/context/**` (external AI Code Review glossary) or `reference-features` (file-layout mirror).
+- Not Tessl / an external host as primary SoT.
+- No stack filesystem path recipes in this core body — path examples belong only in adapter **Stack notes**.
+
+## Related
+
+- `product-specs-authoring` — generation modes, contracts, self-check.
+- `reference-features` — code structure mirror (how to layout files), not product behavior.
+- Consumer `.ai/context/**` when present — review/domain glossary; cross-link, do not replace.

package/presets/_shared/core/meta/preset-layering.md

@@ -13,7 +13,7 @@ Rules for **preset authors** (`packages/ai-rules/presets/**`). Not always-on in
 ## Where to put a new rule
 
 1. Shared principles for all stacks → **core** + adapters with `<!-- shared-core: … -->`.
-2. Only one of the installable stacks (`next` / `nuxt` / `svelte` / `ios-swift` / `go` / `java` / `mcp-ts` / `php-hexagonal` / `php-laravel`) → **stack-specific** (not in `_shared`).
+2. Only one of the installable stacks (`next` / `nuxt` / `svelte` / `ios-swift` / `android-kotlin` / `go` / `java` / `mcp-ts` / `php-hexagonal` / `php-laravel`) → **stack-specific** (not in `_shared`).
 3. Only Cursor or only Claude packaging → platform artifact / frontmatter; do not duplicate semantics.
 
 ## SoT

package/presets/_shared/core/meta/preset-no-cross-stack-leakage.md

@@ -4,11 +4,12 @@ Ban leakage of stack-specific names, paths, and handoff stems across presets.
 
 ## Principles
 
-- `next` must not require iOS-only agents/tooling (`xcuitest-*`, `xcodebuild` as required handoff, Keychain-only rules).
-- `nuxt` must not require iOS-only agents/tooling (`xcuitest-*`, `xcodebuild` as required handoff, Keychain-only rules).
-- `svelte` must not require iOS-only agents/tooling (`xcuitest-*`, `xcodebuild` as required handoff, Keychain-only rules).
-- `ios-swift` must not ship Playwright handoffs or Next lint recipes as required commands.
-- `go` / `java` / `php-hexagonal` / `php-laravel` / `mcp-ts` must not ship Playwright, XCUITest, Next lint recipes, or `xcodebuild`/`SwiftLint` as required handoffs.
+- `next` must not require iOS-only or Android-only agents/tooling (`xcuitest-*`, `instrumentation-test-*`, `xcodebuild` as required handoff, Keychain-only rules).
+- `nuxt` must not require iOS-only or Android-only agents/tooling (`xcuitest-*`, `instrumentation-test-*`, `xcodebuild` as required handoff, Keychain-only rules).
+- `svelte` must not require iOS-only or Android-only agents/tooling (`xcuitest-*`, `instrumentation-test-*`, `xcodebuild` as required handoff, Keychain-only rules).
+- `ios-swift` must not ship Playwright handoffs, Android `instrumentation-test-*` handoffs, or Next lint recipes as required commands.
+- `android-kotlin` must not ship Playwright, XCUITest, `xcodebuild`, or Next lint recipes as required handoffs.
+- `go` / `java` / `php-hexagonal` / `php-laravel` / `mcp-ts` must not ship Playwright, XCUITest, Android instrumentation agents, Next lint recipes, or `xcodebuild`/`SwiftLint` as required handoffs.
 - `mcp-ts` must not ship Go tool commands (`go test`, `go vet`, `golangci-lint`) or `integration-test-*` agents as required delivery gates.
 - Shared core must not embed stack paths (`app/src/**`, `Features/**`, `playwright`, `xcodebuild`).
 
@@ -17,25 +18,37 @@ Ban leakage of stack-specific names, paths, and handoff stems across presets.
 In ios-swift `chain-team-phases.sh` / agent handoffs (Cursor + Claude):
 
 - `playwright-test-`, `playwright-agents`, `playwright-e2e`, `user-playwright`
+- `instrumentation-test-` as required Android handoffs
 - `app/__tests__/e2e` as a required path
 - Positive yarn recipes `lint:js` / `lint:css` as commands to run (negation prose alone is weak — prefer zero occurrences)
 
 Required instead: `xcuitest-test-*` stems; build-verifier mentions `xcodebuild` or `post-change-build` / `xcode-tooling`.
 
+## Forbidden in android-kotlin hooks/agents (FAIL)
+
+In android-kotlin `chain-team-phases.sh` / agent handoffs (Cursor + Claude):
+
+- `playwright-test-`, `playwright-agents`, `playwright-e2e`, `user-playwright`
+- `app/__tests__/e2e` as a required path
+- `xcuitest-test-`, positive `xcodebuild` / `SwiftLint` as required handoffs
+- Positive yarn recipes `lint:js` / `lint:css` as commands to run
+
+Required instead: `instrumentation-test-*` stems; build-verifier mentions `gradle-tooling` and/or `post-change-build` (Gradle wrapper discovery — not `xcodebuild` as the default gate).
+
 ## Forbidden in next hooks/agents (FAIL when present as required)
 
-- `xcuitest-test-` as handoff stems
+- `xcuitest-test-` / `instrumentation-test-` as handoff stems
 - Requiring `xcodebuild` / SwiftLint as the default post-change gate for Next app work
 
 ## Forbidden in nuxt hooks/agents (FAIL when present as required)
 
-- `xcuitest-test-` as handoff stems
+- `xcuitest-test-` / `instrumentation-test-` as handoff stems
 - Requiring `xcodebuild` / SwiftLint as the default post-change gate for Nuxt app work
 - Frontend profile mirrors `next`: Playwright / `lint:js` / `lint:css` allowed
 
 ## Forbidden in svelte hooks/agents (FAIL when present as required)
 
-- `xcuitest-test-` as handoff stems
+- `xcuitest-test-` / `instrumentation-test-` as handoff stems
 - Requiring `xcodebuild` / SwiftLint as the default post-change gate for SvelteKit app work
 - Frontend profile mirrors `next` / `nuxt`: Playwright / `lint:js` / `lint:css` allowed
 
@@ -45,7 +58,7 @@ Shared backend-stack bans (`go`, `java`, `php-hexagonal`, and `php-laravel`):
 
 - `playwright-test-`, `playwright-e2e`, `user-playwright`, `app/__tests__/e2e`
 - Positive yarn recipes `lint:js` / `lint:css`
-- `xcuitest-test-`, `xcodebuild`, `SwiftLint` as required handoffs
+- `xcuitest-test-`, `instrumentation-test-`, `xcodebuild`, `SwiftLint` as required handoffs
 - Agent file `accessibility-reviewer` (no UI surface)
 
 Required instead: `integration-test-*`; build-verifier / `post-change-test` plus stack tooling — `go-tooling` (`go test`, `go vet`), `java-tooling` (`mvn test` / `./gradlew test`), or `php-tooling` (`php artisan test` / `composer test` / `vendor/bin/phpunit`).
@@ -56,9 +69,9 @@ Same UI/mobile bans as backend stacks, plus:
 
 - `playwright-test-`, `playwright-agents`, `playwright-e2e`, `user-playwright`, `app/__tests__/e2e`
 - Positive yarn recipes `lint:js` / `lint:css` as required gates
-- `xcuitest-test-`, `xcodebuild`, `SwiftLint` as required handoffs
+- `xcuitest-test-`, `instrumentation-test-`, `xcodebuild`, `SwiftLint` as required handoffs
 - Go tool commands as required MCP delivery gates: `go test`, `go vet`, `golangci-lint`
-- Agent files: `playwright-test-*`, `xcuitest-test-*`, `integration-test-*`, `accessibility-reviewer`
+- Agent files: `playwright-test-*`, `xcuitest-test-*`, `instrumentation-test-*`, `integration-test-*`, `accessibility-reviewer`
 
 Required instead: package-manager–discovered typecheck/test (`mcp-ts-tooling`, `post-change-test`); Phase 1 gates `build-verifier` + `security-reviewer`.
 
@@ -69,4 +82,4 @@ Required instead: package-manager–discovered typecheck/test (`mcp-ts-tooling`,
 
 ## Chain fork
 
-`hooks/chain-team-phases.sh` must differ **byte-wise** pairwise among `next`, `nuxt`, `svelte`, `ios-swift`, `go`, `java`, `mcp-ts`, `php-hexagonal`, and `php-laravel` (per platform).
+`hooks/chain-team-phases.sh` must differ **byte-wise** pairwise among `next`, `nuxt`, `svelte`, `ios-swift`, `android-kotlin`, `go`, `java`, `mcp-ts`, `php-hexagonal`, and `php-laravel` (per platform).

package/presets/_shared/core/meta/preset-pr-checklist.md

@@ -6,7 +6,7 @@ Checklist for PRs that touch `packages/ai-rules/presets/**` (and dogfood `.curso
 
 - [ ] **SoT:** edits in `packages/…` (not only root `.cursor/`)
 - [ ] **Core:** if `_shared/core/**` changed — all `<!-- shared-core: … -->` consumers updated (or documented intentional fork)
-- [ ] **Twin:** Cursor change → Claude twin **same PR** (**FAIL** if missing on next, nuxt, svelte, ios-swift, go, java, mcp-ts, php-hexagonal, and php-laravel — see `preset-twin-sync`)
+- [ ] **Twin:** Cursor change → Claude twin **same PR** (**FAIL** if missing on next, nuxt, svelte, ios-swift, android-kotlin, go, java, mcp-ts, php-hexagonal, and php-laravel — see `preset-twin-sync`)
 - [ ] **Mapping:** `claude/<stack>/rules/README.md` mapping table is current
 - [ ] **Token budget:** alwaysApply / session-start ≤ 3; meta rules not always-on
 - [ ] **Leakage:** no foreign stack agent stems / handoff strings (`preset-no-cross-stack-leakage`)

package/presets/_shared/core/meta/preset-twin-sync.md

@@ -15,6 +15,7 @@ Cursor `.mdc` — **SoT per stack**. Claude topic `.md` — derived twin.
 | `mcp-ts` | `presets/cursor/mcp-ts/rules/*.mdc` | `presets/claude/mcp-ts/rules/<topic>/` | Keep in `claude/mcp-ts/rules/README.md` |
 | `php-hexagonal` | `presets/cursor/php-hexagonal/rules/*.mdc` | `presets/claude/php-hexagonal/rules/<topic>/` | Keep in `claude/php-hexagonal/rules/README.md` |
 | `php-laravel` | `presets/cursor/php-laravel/rules/*.mdc` | `presets/claude/php-laravel/rules/<topic>/` | Keep in `claude/php-laravel/rules/README.md` |
+| `android-kotlin` | `presets/cursor/android-kotlin/rules/*.mdc` | `presets/claude/android-kotlin/rules/<topic>/` | Keep in `claude/android-kotlin/rules/README.md` |
 
 ## Same-PR checklist
 
@@ -39,5 +40,6 @@ Cursor `.mdc` — **SoT per stack**. Claude topic `.md` — derived twin.
 - **mcp-ts:** missing Claude twin for a changed Cursor rule → **FAIL** (same as next / ios-swift / go / java; mapping table required).
 - **php-hexagonal:** missing Claude twin for a changed Cursor rule → **FAIL** (same as next / ios-swift / go / java / mcp-ts; mapping table required).
 - **php-laravel:** missing Claude twin for a changed Cursor rule → **FAIL** (same as next / ios-swift / go / java / mcp-ts / php-hexagonal; mapping table required).
+- **android-kotlin:** missing Claude twin for a changed Cursor rule → **FAIL** (same as next / ios-swift / go / java / mcp-ts / php-*; mapping table required).
 
 Dogfood: sync packages → root `.cursor/` after Cursor SoT changes (not the reverse). Use `packages/ai-rules/scripts/sync-dogfood-cursor.sh`.

package/presets/claude/android-kotlin/CLAUDE.md

@@ -0,0 +1,38 @@
+# Android Kotlin stack — project instructions
+
+Short Claude Code entry point. Detailed rules — modular topic `.md` files under `rules/` (derived from Cursor SoT).
+
+**Repo-root agents:** see [`AGENTS.md`](../../AGENTS.md) at the project root (cross-tool setup, commands, security, living conventions pointers).
+
+See @rules/README.md for mapping and loading strategy.
+
+## Conventions
+
+- One topic per file; path scope — frontmatter `paths:`.
+- **Session-start rules** (no `paths:`) — exactly **three**: `android-app-core`, `boundaries`, `code-quality`.
+- Requestable / paths: orchestrator, intake, feature-delivery, code-review, post-change-build, gradle-tooling, reference-features, security-android, technical-retro, domain globs.
+- Slash commands — `commands/`; skills — `skills/`; subagents — `agents/`.
+
+## Quick start
+
+| Task | Where to look |
+|------|----------------|
+| Work request | `commands/task.md` + `tooling-and-review/agent-team-orchestrator.md` |
+| End-to-end feature | skill `feature-delivery` + `architecture/feature-delivery.md` |
+| Reference modules | `architecture/reference-features.md` (placeholders `applications/`, `features/<name>/`) |
+| Stack | `stack/android-app-core.md` |
+| Toolchain | `tooling-and-review/gradle-tooling.md` |
+| After Kotlin edits | `tooling-and-review/post-change-build.md` (requestable, required) |
+| UI tests | skill `instrumentation-ui-e2e` |
+| Security | `tooling-and-review/security-android.md` |
+| Validation | agent `build-verifier` |
+| How does X work? | agent `codebase-analyzer` (explain-as-is) |
+| Retro | `commands/technical-retro.md` |
+
+## Install
+
+```bash
+npx @bonesofspring/ai-rules init claude --preset android-kotlin
+```
+
+Copies `CLAUDE.md`, `rules/**`, `commands/**`, `agents/**`, `skills/**`, `hooks/**`, `team/**`, `MCP.md` into `.claude/`, plus `mcp.json` → **`.mcp.json`** and `REPO_AGENTS.md` → root **`AGENTS.md`**. Skill: `write-adr` (on-demand).