@bonesofspring/ai-rules 0.2.15 → 0.2.17

package/presets/claude/android-kotlin/hooks/examples/README.md

@@ -0,0 +1,18 @@
+# Hooks cookbook (examples)
+
+Optional scripts under `hooks/examples/`. **Not** referenced from default `hooks.json` (only `guard-shell-command.sh` + `chain-team-phases.sh`).
+
+| Script | Purpose |
+|--------|---------|
+| `secret-guard.example.sh` | Fail if staged diff looks like secrets |
+| `format-edited.example.sh` | Stack formatter / linter on edited files |
+| `test-on-save.example.sh` | Scoped tests for the stack |
+
+## Wiring (Cursor)
+
+1. Copy an example into `hooks/` (drop `.example` suffix), e.g. `cp hooks/examples/secret-guard.example.sh hooks/secret-guard.sh`.
+2. `chmod +x hooks/secret-guard.sh`.
+3. Add a hook entry in `.cursor/hooks.json` (e.g. `beforeShellExecution` or `afterFileEdit` — see Cursor hooks docs).
+4. Keep cookbook scripts **out** of the default preset `hooks.json` when contributing back upstream.
+
+Stack: **android-kotlin** — recipes must stay stack-safe (no cross-stack lint/test commands).

package/presets/claude/android-kotlin/hooks/examples/format-edited.example.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# Optional cookbook: ktlint / detekt on edited Kotlin files.
+# NOT wired in default hooks.json — copy into a custom hook if desired.
+
+set -euo pipefail
+
+if command -v ktlint >/dev/null 2>&1; then
+  git diff --name-only --diff-filter=ACMR HEAD 2>/dev/null | grep -E '\.(kt|kts)$' | while read -r f; do
+    [[ -f "$f" ]] && ktlint -F "$f" || true
+  done
+fi
+
+# detekt — only if the repo already configures it; do not invent a gate here.

package/presets/claude/android-kotlin/hooks/examples/secret-guard.example.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# Optional cookbook: block committing likely secrets in staged diffs.
+# NOT wired in default hooks.json — copy to hooks/ and register manually.
+set -euo pipefail
+PATTERN='(AKIA[0-9A-Z]{16}|-----BEGIN (RSA |OPENSSH )?PRIVATE KEY-----|api[_-]?key\s*[:=]\s*['\''\"][^'\''\"]{12,})'
+if git diff --cached -U0 2>/dev/null | grep -Eiq "$PATTERN"; then
+  echo "secret-guard: possible secret in staged diff — review before commit" >&2
+  exit 1
+fi
+exit 0

package/presets/claude/android-kotlin/hooks/examples/test-on-save.example.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# Optional: ./gradlew test slice for the active scheme (adjust SCHEME/DEST).
+# NOT in default hooks.json. No Playwright / yarn lint.
+set -euo pipefail
+SCHEME="${XCODE_SCHEME:-App}"
+DEST="${XCODE_DESTINATION:-platform=Android Simulator,name=iPhone 16}"
+./gradlew test -scheme "$SCHEME" -destination "$DEST" -quiet 2>/dev/null || true
+exit 0

package/presets/claude/android-kotlin/hooks/guard-shell-command.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# Lightweight shell guard for Android Kotlin preset projects.
+# Android: do NOT blanket-block mvn test / ./gradlew test / compiler/IDE inspections / configured static analysis / repo static analysis.
+# Package-manager mismatch checks apply only when a JS lockfile/package.json exists.
+
+set -euo pipefail
+# ANDROID_PRESET_GUARD: allow ./gradlew compile/test; no Playwright/XCUITest assumptions
+
+input=$(cat)
+
+INPUT="$input" node <<'NODE'
+const fs = require('fs');
+
+const raw = process.env.INPUT || '';
+let event;
+try {
+  event = JSON.parse(raw);
+} catch {
+  process.stdout.write('{ "permission": "allow" }');
+  process.exit(0);
+}
+
+const command = String(event.command || event.input?.command || '');
+if (!command.trim()) {
+  process.stdout.write('{ "permission": "allow" }');
+  process.exit(0);
+}
+
+function out(permission, userMessage, agentMessage) {
+  process.stdout.write(JSON.stringify({
+    permission,
+    user_message: userMessage,
+    agent_message: agentMessage || userMessage,
+  }));
+}
+
+const dangerousGit = /\bgit\s+(reset\s+--hard|clean\s+-[^\n]*f|push\s+--force|push\s+-f|checkout\s+--\s+)/;
+if (dangerousGit.test(command)) {
+  out(
+    'ask',
+    'This command looks destructive for git state. Review it before continuing.',
+    'A project hook flagged a destructive git command. Ask the user before running it.',
+  );
+  process.exit(0);
+}
+
+const managerByFile = [
+  ['yarn.lock', 'yarn'],
+  ['pnpm-lock.yaml', 'pnpm'],
+  ['package-lock.json', 'npm'],
+].find(([file]) => fs.existsSync(file));
+
+let expected = managerByFile?.[1];
+if (!expected && fs.existsSync('package.json')) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8'));
+    const pm = typeof pkg.packageManager === 'string' ? pkg.packageManager : '';
+    expected = pm.split('@')[0] || undefined;
+  } catch {
+    // Ignore invalid package.json in the hook; the agent can diagnose it later.
+  }
+}
+
+if (!expected) {
+  process.stdout.write('{ "permission": "allow" }');
+  process.exit(0);
+}
+
+const used = command.match(/(^|[;&|]\s*)(npm|yarn|pnpm)\s+/)?.[2];
+if (used && used !== expected) {
+  out(
+    'ask',
+    `This repository appears to use ${expected}, but the command uses ${used}. Confirm before continuing.`,
+    `Use ${expected} for package scripts and installs unless the user explicitly approves ${used}.`,
+  );
+  process.exit(0);
+}
+
+process.stdout.write('{ "permission": "allow" }');
+NODE

package/presets/claude/android-kotlin/mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp"]
+    },
+    "figma": {
+      "type": "http",
+      "url": "https://mcp.figma.com/mcp"
+    }
+  }
+}

package/presets/claude/android-kotlin/rules/README.md

@@ -0,0 +1,65 @@
+# `.claude/rules` (preset android-kotlin)
+
+In Claude Code all `.md` files under `rules/` are **discovered recursively**. Bodies are **derived** from Cursor SoT; indexes are not a second SoT.
+
+## SoT sync
+
+| Principle | Detail |
+|-----------|--------|
+| **SoT** | `presets/cursor/android-kotlin/rules/*.mdc` — edit here first |
+| **Derive** | Claude topic `.md` = body + `paths:` (from Cursor `globs:` / requestable triggers) |
+| **Drop** | Cursor-only keys (`alwaysApply`); keep short `description` |
+| **Checklist** | change Cursor → update Claude twin **same PR** (**FAIL** if missing — see `preset-twin-sync` / build-verifier) |
+
+## Loading budget
+
+- **Session-start (no `paths:`):** exactly **3** — `android-app-core`, `boundaries`, `code-quality` (≤140 body lines total)
+- **Everything else** — with `paths:`
+- **Soft twin depth:** domain rules ≥15 body lines; thin aliases (`agent-team-intake`, `technical-retro`) may be shorter
+
+## Cursor → Claude mapping
+
+| Cursor `.mdc` (SoT) | Claude topic |
+|---------------------|--------------|
+| `android-app-core.mdc` | `stack/android-app-core.md` |
+| `kotlin-conventions.mdc` | `stack/kotlin-conventions.md` |
+| `architecture-boundaries.mdc` | `architecture/boundaries.md` |
+| `feature-delivery-workflow.mdc` | `architecture/feature-delivery.md` |
+| `reference-features.mdc` | `architecture/reference-features.md` |
+| `product-specs.mdc` | `architecture/product-specs.md` |
+| `product-specs-authoring.mdc` | `architecture/product-specs-authoring.md` | Generate/Bootstrap; requestable |
+| `module-public-api.mdc` | `architecture/module-public-api.md` |
+| `di-dagger-feature-holders.mdc` | `architecture/di-dagger-feature-holders.md` |
+| `networking-data.mdc` | `api-and-data/networking.md` |
+| `persistence-data.mdc` | `api-and-data/persistence.md` |
+| `compose-ui.mdc` | `ui-and-accessibility/compose.md` |
+| `state-and-viewmodels.mdc` | `ui-and-accessibility/viewmodels.md` |
+| `navigation-feature-launcher.mdc` | `ui-and-accessibility/navigation.md` |
+| `tests-unit.mdc` | `testing/unit.md` |
+| `tests-ui.mdc` | `testing/ui.md` |
+| `code-quality-and-refactoring.mdc` | `tooling-and-review/code-quality.md` |
+| `anti-sycophancy-discipline.mdc` | `tooling-and-review/anti-sycophancy-discipline.md` |
+| `design-guidance.mdc` | `tooling-and-review/design-guidance.md` |
+| `code-review-mr.mdc` | `tooling-and-review/code-review.md` |
+| `post-change-build.mdc` | `tooling-and-review/post-change-build.md` |
+| `gradle-tooling.mdc` | `tooling-and-review/gradle-tooling.md` |
+| `security-android.mdc` | `tooling-and-review/security-android.md` |
+| `agent-team-intake.mdc` | `tooling-and-review/agent-team-intake.md` |
+| `agent-team-orchestrator.mdc` | `tooling-and-review/agent-team-orchestrator.md` |
+| `technical-retro.mdc` | `tooling-and-review/technical-retro.md` |
+| `preset-layering.mdc` | `tooling-and-review/preset-layering.md` |
+| `preset-twin-sync.mdc` | `tooling-and-review/preset-twin-sync.md` |
+| `preset-token-budget.mdc` | `tooling-and-review/preset-token-budget.md` |
+| `preset-pr-checklist.mdc` | `tooling-and-review/preset-pr-checklist.md` |
+| `preset-no-cross-stack-leakage.mdc` | `tooling-and-review/preset-no-cross-stack-leakage.md` |
+
+## Folders
+
+| Folder | About |
+|--------|--------|
+| `stack/` | Stack, Kotlin conventions |
+| `architecture/` | Boundaries, feature-delivery, reference-features, module API, DI |
+| `api-and-data/` | Networking, persistence |
+| `testing/` | JVM unit, instrumentation UI |
+| `ui-and-accessibility/` | Compose, ViewModels, navigation |
+| `tooling-and-review/` | Quality, review, build, security, tooling, agent-team, retro, **preset meta** |

package/presets/claude/android-kotlin/rules/api-and-data/README.md

@@ -0,0 +1,10 @@
+# API and data
+
+Networking layer, persistence, DTOs, mappers. Index only — bodies live in topic `.md` files.
+
+| File | Cursor SoT |
+|------|------------|
+| [`networking.md`](./networking.md) | `networking-data.mdc` |
+| [`persistence.md`](./persistence.md) | `persistence-data.mdc` |
+
+Sync: change Cursor → update Claude twin same PR. Full map: [`../README.md`](../README.md).

package/presets/claude/android-kotlin/rules/api-and-data/networking.md

@@ -0,0 +1,30 @@
+---
+description: Networking and DTO→domain mapping in the data layer
+paths:
+  - "**/data/**"
+  - "**/network/**"
+---
+
+# Networking / data
+
+- HTTP clients, serializers, and DTOs live in the **data** layer (or data packages under `features/<name>/impl`).
+- Map DTO → domain at the data boundary; domain and presentation must not see transport DTOs.
+- Prefer the stack already in the repo (OkHttp, Ktor, Retrofit, etc.) — do not introduce a second client “for cleanliness”.
+- Errors: translate transport failures into domain/application error types used by the feature.
+- Timeouts, interceptors, and auth headers follow existing client configuration.
+
+# Boundaries
+
+- No Compose / ViewModel imports in networking code.
+- No business rules beyond mapping and orchestration already established in repositories/use cases.
+
+# Agent requirements
+
+- Colocate new endpoints/mappers next to analogs.
+- Secrets and TLS policy — see `tooling-and-review/security-android`; never hard-code tokens.
+
+# Resilience
+
+- Retries/backoff only when the repo already has a shared policy — do not invent per-call retries.
+- Cancellation must propagate with coroutines; do not swallow `CancellationException`.
+- Pagination/cursors follow neighboring repository patterns.

package/presets/claude/android-kotlin/rules/api-and-data/persistence.md

@@ -0,0 +1,29 @@
+---
+description: Local persistence and datastore patterns in the data layer
+paths:
+  - "**/data/local/**"
+  - "**/database/**"
+---
+
+# Persistence / local data
+
+- Room / DataStore / SQLDelight / file cache — **use what the repo already uses**.
+- Persistence models stay in data; map to domain entities before crossing upward.
+- Migrations and schema changes follow existing migration patterns and CI checks.
+- Do not block the main thread; use the repo’s dispatcher / coroutine patterns.
+
+# Boundaries
+
+- Domain defines repository ports; data implements them with local + remote sources as needed.
+- UI must not query DAOs directly.
+
+# Agent requirements
+
+- Prefer the narrowest change that preserves schema compatibility.
+- Cover mappers and critical repository branches with JVM unit tests when feasible.
+
+# Consistency
+
+- Transactions follow existing DAO/helper patterns.
+- Cache invalidation belongs with the repository that owns the source of truth.
+- Prefer idempotent writes when syncing remote → local.

package/presets/claude/android-kotlin/rules/architecture/README.md

@@ -0,0 +1,9 @@
+# architecture
+
+| File | Cursor SoT |
+|------|------------|
+| [`boundaries.md`](./boundaries.md) | `architecture-boundaries.mdc` |
+| [`feature-delivery.md`](./feature-delivery.md) | `feature-delivery-workflow.mdc` |
+| [`reference-features.md`](./reference-features.md) | `reference-features.mdc` |
+| [`module-public-api.md`](./module-public-api.md) | `module-public-api.mdc` |
+| [`di-dagger-feature-holders.md`](./di-dagger-feature-holders.md) | `di-dagger-feature-holders.mdc` |

package/presets/claude/android-kotlin/rules/architecture/boundaries.md

@@ -0,0 +1,27 @@
+---
+description: Clean Architecture boundaries, api/impl modules, and DI summary for Android
+---
+
+# Layer boundaries
+
+- **Presentation** (Compose, ViewModels): may use domain entities/use-case ports and design-system; must not import data HTTP clients/DTOs or map DTO→domain.
+- **Domain**: may use shared core types; must not import Android UI, networking, or concrete repositories.
+- **Data**: implements domain ports; must not import Compose/ViewModels.
+
+# Module boundaries (api / impl)
+
+- Direction: **presentation → domain ← data** inside `features/<name>/impl/`.
+- Other features depend only on **`features/<name>/api`** (public contracts / launcher ports) — never deep-import `impl`.
+- App shells under `applications/` wire graphs; navigation across features via public launcher-style ports.
+- Shared kernels live under `core/` — do not put feature business rules there.
+
+# DI summary
+
+- Feature-scoped **Dagger** holders/components (see `architecture/di-dagger-feature-holders`).
+- **No Hilt by default** unless the consumer repo already standardized on it.
+- ViewModels receive ports/use cases, not concrete data types.
+
+# Agent requirement
+
+- Place files in matching layers/modules; do not short-circuit api/impl for speed.
+- Load `architecture/module-public-api` and `ui-and-accessibility/navigation` when editing public contracts.

package/presets/claude/android-kotlin/rules/architecture/di-dagger-feature-holders.md

@@ -0,0 +1,34 @@
+---
+description: Feature-scoped Dagger holders/components; no Hilt by default
+paths:
+  - "**/di/**"
+  - "**/*Holder*.kt"
+  - "**/*Component*.kt"
+---
+
+# Dagger feature holders
+
+- Prefer **feature-scoped** Dagger components / holders owned by `features/<name>/impl` (or the repo’s equivalent DI package).
+- Expose only what the feature needs; do not create god-components that wire the whole app.
+- App shells under `applications/` provide application-wide dependencies; features pull those via component dependencies / holder APIs already used in the repo.
+- ViewModels and use cases are constructed via the holder/component — not via static globals.
+
+# No Hilt by default
+
+- **Do not introduce Hilt** unless the consumer repository already standardized on it.
+- If the repo is Dagger-manual / holders, keep that pattern; do not “migrate to Hilt” as drive-by work.
+
+# Boundaries
+
+- DI graph assembly may import adapters for wiring only — no business rules inside modules/components.
+- Other features consume public `api` contracts, not another feature’s DI internals.
+
+# Agent requirements
+
+- Follow neighboring `*Holder*` / `*Component*` patterns before inventing a new DI shape.
+- Local holder type names belong in consumer `team/conventions.md`, not in this preset.
+
+# Testing
+
+- Provide test/fake holders or override bindings using the repo’s existing test DI pattern.
+- Do not construct production graphs inside unit tests when a lightweight fake port suffices.

package/presets/claude/android-kotlin/rules/architecture/feature-delivery.md

@@ -0,0 +1,45 @@
+---
+description: End-to-end checklist for Android features (domain → data → DI → presentation)
+paths:
+  - .claude/commands/**/*
+  - .claude/agents/**/*
+  - .claude/team/tasks/**/*
+  - "features/**"
+  - "**/*.{kt,kts}"
+---
+
+<!-- shared-core: architecture/feature-delivery-workflow.md -->
+
+# Feature delivery (Android Kotlin)
+
+Deliver features in layer order. Prefer neighboring `features/<name>/` analogs.
+
+## Checklist
+
+1. **Public API** — contracts / launcher ports in `features/<name>/api` when other modules will depend on them (`architecture/module-public-api`).
+2. **Domain** — entities, use-case ports; no Android UI / HTTP DTOs (`architecture/boundaries`).
+3. **Data** — repository implementations, DTO mappers, persistence (`api-and-data/networking`, `api-and-data/persistence`).
+4. **DI** — feature Dagger holder/component wiring (`architecture/di-dagger-feature-holders`); **no Hilt by default**.
+5. **Presentation** — ViewModel MVI/UDF + Compose screens (`ui-and-accessibility/viewmodels`, `ui-and-accessibility/compose`).
+6. **Navigation** — wire launcher ports / host (`ui-and-accessibility/navigation`).
+7. **Tests** — JVM unit tests; instrumentation when UI AC requires (`testing/unit`, `testing/ui`).
+8. **Gate** — invoke **`tooling-and-review/post-change-build`** + **`tooling-and-review/gradle-tooling`**.
+
+## Layer → rule matrix
+
+| Layer | Rules |
+|-------|-------|
+| api / contracts | `module-public-api`, `navigation` |
+| domain / data | `boundaries`, `networking`, `persistence` |
+| di | `di-dagger-feature-holders` |
+| presentation | `viewmodels`, `compose` |
+| tests | `unit`, `ui`, skill `instrumentation-ui-e2e` |
+
+## Agent requirements
+
+- Skill `feature-delivery` owns the end-to-end path; do not skip api/impl boundaries for speed.
+- Local type names only in consumer `team/conventions.md`.
+
+## Related
+
+- Product behavior discovery: requestable **`product-specs`** (`docs/specs/INDEX.md`) — do not paste the discovery algorithm here.

package/presets/claude/android-kotlin/rules/architecture/module-public-api.md

@@ -0,0 +1,29 @@
+---
+description: Public api module contracts for Android multimodule features
+paths:
+  - "**/api/**"
+  - "**/*Api.kt"
+---
+
+# Module public API
+
+- `features/<name>/api` (or equivalent) holds **public** contracts: models safe to share, navigation/launcher ports, public facades.
+- Implementation details stay in `impl` — other modules must not depend on `impl`.
+- Prefer stable, minimal surfaces; expanding a public API is a deliberate contract change.
+- Do not leak DTOs, database entities, or Compose UI types through `api` unless the repo already does so intentionally.
+
+# Cross-feature access
+
+- Consume another feature only via its `api` artifacts (Gradle dependency on the api module).
+- Navigation between features uses launcher-style ports declared in `api` (`ui-and-accessibility/navigation`).
+
+# Agent requirements
+
+- When adding a symbol used outside the feature, place it in `api` and keep `impl` private.
+- Breaking api changes need explicit AC / review — do not silently widen visibility.
+
+# Versioning mindset
+
+- Treat api module changes as consumer-facing even inside a monorepo.
+- Prefer additive changes; renames/removals need migration notes in the task brief.
+- Keep Gradle `api` vs `implementation` dependencies consistent with visibility intent.

package/presets/claude/android-kotlin/rules/architecture/product-specs-authoring.md

@@ -0,0 +1,121 @@
+---
+paths:
+  - docs/specs/**/*
+---
+
+<!-- shared-core: architecture/product-specs-authoring.md -->
+
+# 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)
+
+
+## Stack notes
+
+- Author via skill `spec-authoring`; templates from package assets / consumer `docs/specs/_templates/`.
+- Field semantics match discovery stem (`routes` = deep links; `e2e` = instrumentation). **No** web Playwright / iOS XCUITest recipes.
+- Requestable — not always-on / session-start.

package/presets/claude/android-kotlin/rules/architecture/product-specs.md

@@ -0,0 +1,62 @@
+---
+paths:
+  - docs/specs/**/*
+---
+
+<!-- shared-core: architecture/product-specs.md -->
+
+# 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.
+
+
+## Stack notes
+
+- `routes`: deep links / screen ids. `ui` / `store`: feature presentation / ViewModel (`features/**` or `features/<name>/impl/**/presentation/`) — **not** web `app/src/ui` or iOS `Features/**`. `e2e`: instrumentation test paths.
+- Requestable / `docs/specs/**` globs — not always-on / session-start.

package/presets/claude/android-kotlin/rules/architecture/reference-features.md

@@ -0,0 +1,28 @@
+---
+description: Placeholder reference feature paths for Android multimodule repos
+paths:
+  - "features/**"
+---
+
+# Reference features (placeholders)
+
+Use these **placeholder** paths when pointing agents at analogs. Replace with real module names in the consumer repo (and optionally document local names in `team/conventions.md`).
+
+| Concern | Placeholder path |
+|---------|------------------|
+| App shell | `applications/<app>/` |
+| Shared kernel | `core/` |
+| Feature public API | `features/<name>/api/` |
+| Feature implementation | `features/<name>/impl/` |
+| DI holders | `features/<name>/impl/**/di/` |
+| Presentation | `features/<name>/impl/**/presentation/` |
+| Data | `features/<name>/impl/**/data/` |
+| Convention plugins | `build-logic/` |
+| Version catalog | `gradle/libs.versions.toml` |
+| JVM tests | `**/src/test/**` |
+| Instrumentation | `**/src/androidTest/**` |
+
+# Agent requirements
+
+- Copy patterns from the closest neighboring feature — do not invent a parallel layout.
+- Never cite private consumer monorepo or vendor names in shared preset text.

package/presets/claude/android-kotlin/rules/stack/README.md

@@ -0,0 +1,6 @@
+# stack
+
+| File | Cursor SoT |
+|------|------------|
+| [`android-app-core.md`](./android-app-core.md) | `android-app-core.mdc` |
+| [`kotlin-conventions.md`](./kotlin-conventions.md) | `kotlin-conventions.mdc` |