@bonesofspring/ai-rules 0.2.15 → 0.2.17

package/presets/cursor/android-kotlin/rules/preset-twin-sync.mdc

@@ -0,0 +1,56 @@
+---
+description: Preset authoring: Cursor SoT → Claude twin same PR. Use when editing preset rules.
+globs:
+  - packages/ai-rules/presets/**/*
+  - .cursor/rules/**/*
+  - .cursor/team/tasks/**/*
+alwaysApply: false
+---
+
+<!-- shared-core: meta/preset-twin-sync.md -->
+
+# Preset twin sync
+
+Cursor `.mdc` — **SoT per stack**. Claude topic `.md` — derived twin.
+
+## Matrix
+
+| Stack | Cursor SoT | Claude derive | Mapping table |
+|-------|------------|---------------|---------------|
+| `next` | `presets/cursor/next/rules/*.mdc` | `presets/claude/next/rules/<topic>/` | **Required** in `claude/next/rules/README.md` |
+| `nuxt` | `presets/cursor/nuxt/rules/*.mdc` | `presets/claude/nuxt/rules/<topic>/` | **Required** in `claude/nuxt/rules/README.md` |
+| `svelte` | `presets/cursor/svelte/rules/*.mdc` | `presets/claude/svelte/rules/<topic>/` | **Required** in `claude/svelte/rules/README.md` |
+| `ios-swift` | `presets/cursor/ios-swift/rules/*.mdc` | `presets/claude/ios-swift/rules/<topic>/` | Keep in `claude/ios-swift/rules/README.md` |
+| `go` | `presets/cursor/go/rules/*.mdc` | `presets/claude/go/rules/<topic>/` | Keep in `claude/go/rules/README.md` |
+| `java` | `presets/cursor/java/rules/*.mdc` | `presets/claude/java/rules/<topic>/` | Keep in `claude/java/rules/README.md` |
+| `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
+
+1. Edit Cursor rule first (body + frontmatter).
+2. Update Claude twin: body + `paths:` (from Cursor `globs:` / requestable triggers); drop `alwaysApply`.
+3. Update mapping table row if stem/path changed.
+4. If body embeds core (`<!-- shared-core: … -->`), sync core consumers across stacks when core changed.
+
+## Twin depth
+
+- **Domain** rules: ≥15 body lines (FAIL if thin without documented alias reason).
+- **Thin aliases** (`agent-team-intake`, `technical-retro`): may be shorter (soft) if they only point to a command/skill.
+
+## Severity (build-verifier)
+
+- **next:** missing Claude twin for a changed Cursor rule → **FAIL** (mapping table required).
+- **nuxt:** missing Claude twin for a changed Cursor rule → **FAIL** (mapping table required).
+- **svelte:** missing Claude twin for a changed Cursor rule → **FAIL** (mapping table required).
+- **ios-swift:** missing Claude twin for a changed Cursor rule → **FAIL**.
+- **go:** missing Claude twin for a changed Cursor rule → **FAIL** (same as next / ios-swift; mapping table required).
+- **java:** missing Claude twin for a changed Cursor rule → **FAIL** (same as next / ios-swift / go; mapping table required).
+- **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/cursor/android-kotlin/rules/product-specs-authoring.mdc

@@ -0,0 +1,123 @@
+---
+description: Author/generate product specs (docs/specs) — modes, INDEX/frontmatter, checklist
+globs:
+  - docs/specs/**/*
+alwaysApply: false
+---
+
+<!-- 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/cursor/android-kotlin/rules/product-specs.mdc

@@ -0,0 +1,64 @@
+---
+description: Product page/feature specs under docs/specs — INDEX discovery for agents
+globs:
+  - docs/specs/**/*
+alwaysApply: false
+---
+
+<!-- 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/cursor/android-kotlin/rules/reference-features.mdc

@@ -0,0 +1,29 @@
+---
+description: Placeholder reference feature paths for Android multimodule repos
+globs:
+  - "features/**"
+alwaysApply: false
+---
+
+# 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/cursor/android-kotlin/rules/security-android.mdc

@@ -0,0 +1,30 @@
+---
+description: Android secrets, TLS, and build-wrapper security policy (generic)
+globs:
+  - "**/network/**"
+  - "**/security/**"
+  - "**/*NetworkSecurity*"
+alwaysApply: false
+---
+
+# Security (Android, generic)
+
+- **Secrets:** never commit API keys, keystore passwords, or tokens; use CI secrets / local untracked properties already used by the repo.
+- **TLS:** prefer platform HTTPS defaults; network security config changes must be explicit and reviewed.
+- **Storage:** sensitive tokens go to Android Keystore / encrypted storage patterns already in the repo — not plain `SharedPreferences`/files.
+- **Build wrappers:** treat `gradlew` / documented wrappers as the supported entry; do not download unsigned wrapper JARs ad hoc.
+- **Logging:** never log PII, tokens, or Authorization headers.
+
+# Agent requirements
+
+- `security-reviewer` on auth/storage/network changes.
+- Do not weaken TLS or cleartext policy without explicit AC.
+
+# IPC & exports
+
+- Exported components and deep links must match existing permission/export patterns.
+- Do not broaden `exported=true` or cleartext traffic without explicit AC.
+- Certificate pinning — only when the repo already uses it; do not invent a pinning stack.
+
+- Review ProGuard/R8 keep rules when touching reflection/serialization used for auth.
+- Backup/export rules must not unintentionally expose encrypted stores.

package/presets/cursor/android-kotlin/rules/state-and-viewmodels.mdc

@@ -0,0 +1,28 @@
+---
+description: MVI/UDF state on the project ViewModel base
+globs:
+  - "**/*ViewModel*.kt"
+alwaysApply: false
+---
+
+# State and ViewModels
+
+- Follow the repo’s **MVI / unidirectional** pattern on the project ViewModel base (name lives in consumer `team/conventions.md`).
+- Single source of UI state (StateFlow / immutable state holder); reduce via pure updates where practical.
+- Expose intents/events for user actions; do not mutate state from composables directly.
+- Side effects (navigation, one-shots) follow existing effect channels — do not invent a parallel bus.
+- ViewModels depend on domain/use-case ports — not concrete data clients.
+
+# Agent requirements
+
+- Keep mapping/DTO work out of ViewModels when mappers already exist in data.
+- Cover reducers/state transitions with JVM unit tests when non-trivial.
+- Avoid `!!` and unchecked casts in state plumbing.
+
+# Lifecycle
+
+- Use `viewModelScope` (or the project equivalent); do not launch unstructured globals.
+- Clear one-shot effects after handling to avoid replay on recomposition/rotation.
+- Keep mapping of domain models → UI models next to existing presenters/mappers.
+
+- Document non-obvious state machine transitions in the brief or a short KDoc on the reducer.

package/presets/cursor/android-kotlin/rules/technical-retro.mdc

@@ -0,0 +1,16 @@
+---
+description: Agent role for a technical retrospective (retro) of the team / sprint. On-demand — prefer the /technical-retro slash command.
+alwaysApply: false
+---
+
+<!-- shared-core: review/technical-retro.md -->
+
+# Technical retro — rule alias
+
+Full scenario (including the **“Agent work”** block for a slug from team tasks) lives in the slash command:
+
+**`commands/technical-retro.md`** → `/technical-retro`
+
+When a task has `metrics.json`, use the local aggregation script and state the cohort, sample size, incomplete artifacts, attribution confidence, active attempt duration, and human-gate wait separately. Do not score malformed artifacts or gate wait as agent work.
+
+Use this rule only if the command is unavailable. Do not duplicate the command contents in the response — follow the command file and skill `technical-retro`.

package/presets/cursor/android-kotlin/rules/tests-ui.mdc

@@ -0,0 +1,29 @@
+---
+description: Android instrumentation UI tests (androidTest)
+globs:
+  - "**/androidTest/**"
+alwaysApply: false
+---
+
+# UI tests (instrumentation)
+
+- Default agent surface: **Android instrumentation** under `androidTest` (devices/emulators/CI as configured).
+- Discover the concrete framework from the consumer repo (Espresso, Compose UI Test, or project-chosen alternatives) — do not mandate a single library in always-on rules.
+- Stable semantics / test tags / content descriptions aligned with presentation conventions.
+- Keep tests behavior-focused; avoid brittle sleep-based synchronization when idling strategies exist.
+
+# Agent team
+
+- Plan/generate/heal via `instrumentation-test-{planner,generator,healer}` and skill `instrumentation-ui-e2e`.
+- Do **not** require Playwright, XCUITest, or yarn `lint:js`/`lint:css` as Android UI-test handoffs.
+
+# Agent requirements
+
+- Prefer page objects / robot patterns already used in the repo.
+- Wire flavors/variants via Gradle tasks discovered in `gradle-tooling`.
+
+# Data & isolation
+
+- Use test fixtures/fakes already adopted by the module; avoid hitting production backends.
+- Clean state between tests when sharing an app process.
+- Record the Gradle task used (`connected*` / managed device) in the plan/receipt.

package/presets/cursor/android-kotlin/rules/tests-unit.mdc

@@ -0,0 +1,30 @@
+---
+description: JVM unit test conventions for Android Kotlin modules
+globs:
+  - "**/test/**"
+  - "**/*Test.kt"
+alwaysApply: false
+---
+
+# Unit tests (JVM)
+
+- Prefer fast JVM unit tests under `src/test` for domain, mappers, ViewModel reducers, and pure use cases.
+- Use the repo’s stack (JUnit4/5, MockK, Turbine, Truth/AssertJ — **as already configured**).
+- Fake ports over heavy Android instrumentation for logic tests.
+- Name tests after behavior; keep arrange/act/assert clear.
+
+# Scope
+
+- Do not require device/emulator for pure logic.
+- UI flows belong in `androidTest` / instrumentation agents — see `tests-ui`.
+
+# Agent requirements
+
+- Agents `unit-test-*` + skill `unit-testing` own planning/generation/healing.
+- After production edits, run the narrowest `./gradlew …Test` suite via `post-change-build` / `gradle-tooling`.
+
+# Flakes & determinism
+
+- Control clocks/dispatchers when testing coroutines/Flow.
+- Avoid relying on real Android framework types in JVM tests unless Robolectric is already standard.
+- Prefer table-driven cases for mapper edge inputs.

package/presets/cursor/android-kotlin/skills/README.md

@@ -0,0 +1,14 @@
+# `.cursor/skills` (preset android-kotlin)
+
+| Skill | Purpose |
+|-------|---------|
+| `feature-delivery` | Domain → Data → VM → View → tests → post-change-build |
+| `code-review` | Android MR checklist |
+| `unit-testing` | JUnit 4/5 (repo default) |
+| `instrumentation-ui-e2e` | Android instrumentation plan/generate/heal (← next `playwright-e2e`) |
+| `debug-investigation` | Runtime evidence before fix |
+| `ci-investigation` | Android CI red |
+| `technical-retro` | Retro facilitation |
+| `write-adr` | Architecture Decision Record (context / decision / consequences) |
+
+Copied to `.cursor/skills/` on init.

package/presets/cursor/android-kotlin/skills/ci-investigation/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: ci-investigation
+description: Investigates failing CI checks on PRs and branches — ./gradlew, ktlint/detekt, unit, Android instrumentation — with local reproduction and minimal fixes. Use when CI is red or for ci-fix pipeline tasks.
+---
+
+# CI Investigation (Android)
+
+## Workflow
+
+1. Identify the **first failing check** (compile, lint, unit, Android instrumentation, signing, Gradle modules).
+2. Capture error output — ignore cascading failures until root cause is found.
+3. Reproduce locally with the same scheme/destination CI uses (`gradle-tooling.mdc`):
+   - `./gradlew build` / `./gradlew test`
+   - ktlint/detekt / ktlint format scripts as in repo CI
+   - affected Android instrumentation if UI job failed
+4. Inspect git diff for changed files related to the failure.
+5. Apply **minimal fix** — no unrelated refactors.
+
+## Artifact
+
+Write `ci-report.md` under the task slug folder (`.cursor/team/tasks/<slug>/`):
+
+- Failed check name and log excerpt
+- Root cause classification
+- Fix applied (or handoff to feature-developer)
+- `resolved: true|false`
+- Validation commands and results
+
+## Handoff Rules
+
+- Config-only or one-line fixes → fix in place, re-run check.
+- Missing tests or architecture work → document and route to `feature-developer` or `qa-tester`.
+- Flaky Android instrumentation → prefer `instrumentation-test-healer` after ci-investigator identifies the case.
+
+## Validation
+
+Always re-run the failing command locally before marking complete. If environment blocks execution (no simulator), state the exact command and blocker.
+
+Never run yarn/`lint:js`/Playwright — wrong stack.

package/presets/cursor/android-kotlin/skills/code-review/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: code-review
+description: Reviews pull requests, merge requests, git diffs, and branch changes using Android architecture, Jetpack Compose, networking, and testing standards. Use when the user asks for review or when code-reviewer runs in an agent pipeline.
+---
+
+# Code Review (Android)
+
+## Inputs
+
+Use the local repository as the source of truth: `git status`, `git diff`, task artifacts under `.cursor/team/tasks/<slug>/` when present, and opened files. Do not invent hosting metadata such as labels, CI status, or reviewers.
+
+## Review Order
+
+1. Understand the intent and affected Feature layers (Presentation / Domain / Data).
+2. Check correctness and regressions first.
+3. Verify architecture boundaries (`architecture-boundaries.mdc`): View ≠ API/DTO; ViewModel ≠ Data impl; Domain ≠ Jetpack Compose; Data ≠ Presentation.
+4. Check DI composition in `applications/`, Gradle modules public API (`module-public-api.mdc`), and no deep-imports across Features.
+5. Review Kotlin concurrency and conventions (`kotlin-conventions.mdc`): `main-safe / viewModelScope`, typed errors, `!!`.
+6. Review Jetpack Compose thinness, Design System usage, `testTag` / semantics / contentDescription (`compose-ui.mdc`).
+7. Check tests: unit for mapper/domain/VM (`tests-unit.mdc`); Android instrumentation for user flows (`tests-ui.mdc`).
+8. **Reuse lens:** flag new helpers that duplicate existing Feature/shared utilities; prefer public module APIs over copy-paste.
+9. **Efficiency lens:** unnecessary work on main thread, redundant network/persistence, hot-path bloat, missing cancellation/cleanup.
+10. Report validation gaps: `./gradlew`, ktlint/detekt, or relevant tests not run (`gradle-tooling.mdc`, `post-change-build.mdc`).
+
+## Output
+
+Lead with findings ordered by severity. Required shape (also in `code-review-mr`):
+
+- Each finding: **`path:line`** — problem — impact — concrete fix direction.
+- Severity: **`blocker` | `important` | `nit`** (list blocker → nit).
+- Vague («looks risky») is not a finding — cite evidence or ask for surrounding context.
+- End with a verdict line: **`Safe to merge | needs changes | reject`**.
+- If there are no findings, say so and call out remaining test or validation risk.
+
+For agent team tasks, write `.cursor/team/tasks/<slug>/review.md` and upsert the owned terminal receipt (`completed` or `changes_requested`); do not mutate `status.json`.
+
+## Design guidance
+
+- Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.

package/presets/cursor/android-kotlin/skills/debug-investigation/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: debug-investigation
+description: Investigates bugs, failing tests, crashes, and incorrect behavior with runtime evidence before applying minimal fixes. Use for bugfix tasks, debugger agent runs, regressions, and flaky test diagnosis.
+---
+
+# Debug Investigation (Android)
+
+## Process
+
+1. Reproduce the issue or collect the closest available evidence: Android Studio / AGP console, lldb backtrace, crash log, failing JUnit/Android instrumentation output, Profiler note, or user steps.
+2. Define expected vs actual behavior in one sentence.
+3. Trace the failing path through the smallest relevant Feature slice (Presentation → Domain → Data).
+4. Identify the root cause before editing. Avoid broad refactors during bugfixes.
+5. Apply the smallest fix that preserves existing architecture and public contracts.
+6. Add or update a regression JUnit when the behavior is domain/VM logic or likely to recur.
+7. Run the narrow failing check first (`./gradlew test` for the affected target), then broader build validation if needed (`gradle-tooling.mdc`).
+
+## Artifacts
+
+For agent team tasks, write `.cursor/team/tasks/<slug>/debug-report.md` with:
+
+- Reproduction steps or evidence source.
+- Root cause.
+- Fix scope (`fixApplied`).
+- Regression coverage.
+- Remaining risk.
+
+Upsert the owned terminal receipt in `artifact-manifest.json` when complete; do not mutate `status.json`.
+
+Do not use browser e2e tooling — this is an Android Studio / AGP stack.
+
+## Design guidance
+
+- Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.

package/presets/cursor/android-kotlin/skills/feature-delivery/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: feature-delivery
+description: Delivers Android Kotlin/Jetpack Compose features end-to-end across Domain, Data, ViewModels, Views, tests, and post-change-build validation. Use when implementing or extending a feature, especially through /task or feature-developer.
+---
+
+# Feature Delivery (Android)
+
+1. Read task brief, acceptance criteria, and decomposition if present.
+2. If `docs/specs/INDEX.md` exists **or** brief/handoff lists approved generated specs, resolve via **`product-specs`** and treat approved specs as behavior SoT before layer work (soft-fail on miss — do not invent behavior). If generation was requested but not yet approved, stop for human gate — do not implement against draft-only gaps.
+3. Read `feature-delivery-workflow.mdc` and `reference-features.mdc` — Domain → Data → ViewModel → View → tests; mirror the closest Feature.
+4. Wire DI in `applications/` composition root; keep Views thin; keep DTOs out of ViewModels.
+5. Add or update focused JUnit for mappers / use cases / ViewModels (`tests-unit.mdc`).
+6. After Kotlin edits: **invoke** `post-change-build.mdc` (+ `gradle-tooling.mdc`). Pipeline: scoped build OK if next step is `build-verifier`.
+
+## Do / Don't
+
+- **Do** follow existing Feature folder layout and public module APIs.
+- **Do** add Compose `testTag` + `contentDescription` for new interactive UI when UI tests / a11y are in scope.
+- **Don't** invent alternate architecture or persistence stacks (e.g. MVI frameworks, Room vs SQLDelight) unless the repo already uses them.
+- **Don't** use yarn, browser e2e, or `app/src` paths — wrong stack.
+
+## Scope discipline
+
+Implement only the current AC / decomposition task. Clarify ambiguity before coding; do not add unrelated hardening, polish, or drive-by refactors. See `feature-developer` → **Zero improvisation**.
+
+## Preset packaging note
+
+When editing **ai-rules android-kotlin preset** sources (agents, hooks, rules) rather than an app Feature: keep Cursor and Claude trees in sync where applicable, and **fork / verify hook handoffs** (`hooks/chain-team-phases.sh`, guard scripts, team path conventions) so Cursor (`.cursor/team`) and Claude (`.claude/team`) do not regress against each other or against the next preset templates.
+
+## Handoff
+
+Summarize by layer, validation results, and known gaps. Agent team: upsert the owned terminal receipt in `artifact-manifest.json`; do not mutate `status.json`.
+
+## Design guidance
+
+- Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.

package/presets/cursor/android-kotlin/skills/instrumentation-ui-e2e/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: instrumentation-ui-e2e
+description: Plan, generate, and heal Android instrumentation UI tests using androidTest sources, project robots/page objects, and Gradle-discovered tasks. Use for instrumentation planning, generation, or fixing flaky UI tests.
+---
+
+# Instrumentation UI e2e (Android)
+
+1. Read brief/AC and existing `androidTest` analogs.
+2. Discover framework and helpers from the consumer repo (Espresso, Compose UI Test, or project-chosen alternatives).
+3. Prefer stable semantics / test tags aligned with presentation conventions (`compose-ui` / `tests-ui`).
+4. Plan → generate → heal via agents `instrumentation-test-{planner,generator,healer}`.
+5. Run the narrowest Gradle instrumentation task via `gradle-tooling` when the environment allows; otherwise document the command for CI.
+
+## Do not
+
+- Require Playwright, XCUITest, or yarn frontend lint recipes.
+- Mandate a single UI-test library by name in always-on rules — discovery stays repo-driven.

package/presets/cursor/android-kotlin/skills/spec-authoring/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: spec-authoring
+description: Author or bootstrap consumer docs/specs (INDEX, page/feature templates, frontmatter v1). Use with task-analyst author mode, /spec-start, or when brief AC requests Generate/Bootstrap.
+---
+
+# Spec authoring
+
+Requestable — not always-on. Load **`product-specs`** + **`product-specs-authoring`** first.
+
+## Steps
+
+1. **Resolve mode** — Generate (tree exists) vs Bootstrap (create INDEX + templates + first spec). Refuse inventing INDEX without explicit intent/AC/`/spec-start`.
+2. **Ensure templates** — if consumer `docs/specs/_templates/` missing, copy from package SoT `presets/_shared/assets/docs-specs/_templates/` (or seeded init assets).
+3. **Fill frontmatter v1** — all array keys present (may be `[]`); prefer `type: feature` on backend/MCP; default `status: draft`.
+4. **Fill required body headings** — page: Overview, Entry/actors, Primary flows, States, Acceptance criteria; feature: Overview, Shared behavior/constraints, Related pages. Use `N/A` explicitly when needed.
+5. **Update INDEX** in the **same change set** (columns: id, type, domain, title, path, optional routes/aliases/status).
+6. **Self-check** against `product-specs-authoring` checklist; put blockers in `open_questions`.
+7. **Handoff** — list created/updated paths + INDEX diff for human gate (`after:task-analyst`). Approve before feature-developer.
+
+## Sources
+
+Cite AC / user / Figma / labeled code inference. Do not invent product behavior.
+
+## mcp-ts
+
+Analyst-only path (no tech-writer). `routes` = tool names; `ui`/`store` = `[]`.