@bonesofspring/ai-rules 0.2.15 → 0.2.17

package/presets/claude/android-kotlin/rules/stack/android-app-core.md

@@ -0,0 +1,27 @@
+---
+description: Core principles, stack, and structure for an Android Kotlin multimodule app (preset)
+---
+
+# Stack and environment
+
+Versions come **from the consumer repo** (`gradle/libs.versions.toml`, AGP, Kotlin plugin, CI). Frame: Kotlin, Android Gradle Plugin; Jetpack Compose Material 3 + project design-system preferred; coroutines/Flow; product flavors/variants as configured; JVM unit tests + `androidTest` instrumentation; networking/persistence — as already chosen in the repo.
+
+# Project structure (placeholders)
+
+```text
+applications/                 # app shells / product entry modules
+core/                         # shared kernels / design-system host
+features/<name>/
+  api/                        # public contracts, navigation ports
+  impl/                       # data / domain / presentation / di
+build-logic/                  # convention plugins (includeBuild)
+gradle/libs.versions.toml
+gradlew | documented wrapper
+```
+
+Place new files next to analogs. Boundaries/DI — **`architecture/boundaries`**. Tooling — **`tooling-and-review/gradle-tooling`**. After Kotlin/Android edits — **invoke** **`tooling-and-review/post-change-build`**.
+
+# Agent work
+
+- Features: `architecture/feature-delivery`; UI tests: skill `instrumentation-ui-e2e` + `instrumentation-test-*`.
+- Local type names (ViewModel base, DI holders, design-system package) — consumer `team/conventions.md` only.

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

@@ -0,0 +1,30 @@
+---
+description: Kotlin style, null-safety, and coroutine conventions for Android
+paths:
+  - "**/*.{kt,kts}"
+---
+
+# Kotlin conventions
+
+- Prefer idiomatic Kotlin already used in neighboring files (naming, package layout, visibility).
+- **Null-safety:** avoid `!!` in production paths; use `?.`, `?:`, early `return`, or typed errors.
+- Prefer `val` / immutability for state snapshots; mutate only behind clear owners (ViewModel, repository).
+- Coroutines: structured concurrency (`viewModelScope` / supervised scopes); cancel cooperatively; no fire-and-forget globals.
+- Flow/StateFlow for streams; collect in lifecycle-aware scopes (Compose / lifecycle owners).
+- Sealed classes/interfaces for UI events and domain errors when the repo pattern uses them.
+- Do not invent new style tooling — follow ktlint/detekt/Android Lint **if** configured in the repo.
+
+# Agent requirements
+
+- Match neighboring module conventions before introducing a new pattern.
+- Unverifiable third-party APIs → `// VERIFY:` comment (see `tooling-and-review/anti-sycophancy-discipline`).
+
+# Packages and visibility
+
+- Prefer `internal` for feature-impl helpers; public only at `api` module boundaries.
+- Avoid wildcard imports that fight the repo’s ktlint/detekt settings.
+- Extension functions stay near the type they extend or in established util packages.
+
+# Errors
+
+- Prefer typed results / sealed errors already used in the feature over bare exceptions in domain code.

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

@@ -0,0 +1,10 @@
+# Testing
+
+Unit (JUnit 4/5, repo default) and UI (Android instrumentation). Index only — bodies live in topic `.md` files.
+
+| File | Cursor SoT |
+|------|------------|
+| [`unit.md`](./unit.md) | `tests-unit.mdc` |
+| [`ui.md`](./ui.md) | `tests-ui.mdc` |
+
+Sync: change Cursor → update Claude twin same PR. Full map: [`../README.md`](../README.md).

package/presets/claude/android-kotlin/rules/testing/ui.md

@@ -0,0 +1,28 @@
+---
+description: Android instrumentation UI tests (androidTest)
+paths:
+  - "**/androidTest/**"
+---
+
+# 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 `tooling-and-review/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/claude/android-kotlin/rules/testing/unit.md

@@ -0,0 +1,29 @@
+---
+description: JVM unit test conventions for Android Kotlin modules
+paths:
+  - "**/test/**"
+  - "**/*Test.kt"
+---
+
+# 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 `testing/ui`.
+
+# Agent requirements
+
+- Agents `unit-test-*` + skill `unit-testing` own planning/generation/healing.
+- After production edits, run the narrowest `./gradlew …Test` suite via `tooling-and-review/post-change-build` / `tooling-and-review/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/claude/android-kotlin/rules/tooling-and-review/README.md

@@ -0,0 +1,19 @@
+# Tooling and review
+
+Quality, review, build, security, agent-team, retro. Index only — bodies live in topic `.md` files.
+
+| File | Cursor SoT |
+|------|------------|
+| [`code-quality.md`](./code-quality.md) | `code-quality-and-refactoring.mdc` |
+| [`code-review.md`](./code-review.md) | `code-review-mr.mdc` |
+| [`post-change-build.md`](./post-change-build.md) | `post-change-build.mdc` |
+| [`gradle-tooling.md`](./gradle-tooling.md) | `gradle-tooling.mdc` |
+| [`security-android.md`](./security-android.md) | `security-android.mdc` |
+| [`agent-team-orchestrator.md`](./agent-team-orchestrator.md) | `agent-team-orchestrator.mdc` |
+| [`agent-team-intake.md`](./agent-team-intake.md) | `agent-team-intake.mdc` |
+| [`technical-retro.md`](./technical-retro.md) | `technical-retro.mdc` |
+| [`design-guidance.md`](./design-guidance.md) | `design-guidance.mdc` |
+| [`anti-sycophancy-discipline.md`](./anti-sycophancy-discipline.md) | `anti-sycophancy-discipline.mdc` |
+| `preset-*.md` | `preset-*.mdc` |
+
+Sync: change Cursor → update Claude twin same PR. Full map: [`../README.md`](../README.md).

package/presets/claude/android-kotlin/rules/tooling-and-review/agent-team-intake.md

@@ -0,0 +1,18 @@
+---
+description: Use when user posts a work request without /task — suggest or use /task to run the agent team router. Lightweight intake hint only.
+paths:
+  - .claude/commands/**/*
+  - .claude/team/**/*
+---
+
+<!-- shared-core: agent-team/agent-team-intake.md -->
+
+# Agent team intake
+
+When the user message looks like a **work request** (implement, add, fix, refactor, review MR, write tests, spike) — not a question about how code works:
+
+1. Prefer **`/task <their request>`** or invoke **task-router** first.
+2. Do not jump straight to coding without router + pipeline when scope is non-trivial.
+3. Pure questions (“how does X work”, “explain”) — prefer agent **`codebase-analyzer`** (explain-as-is); trivial one-liners may be answered inline. Do not open `/task`.
+
+Exceptions: user explicitly says “no pipeline”, “just do it”, or continues an active slug.

package/presets/claude/android-kotlin/rules/tooling-and-review/agent-team-orchestrator.md

@@ -0,0 +1,129 @@
+---
+description: Orchestrates the agent team via task-router and pipeline.json. Use for /task, /task-continue, /feature-start, task decomposition, or when the user describes a feature, bug, or review request.
+paths:
+  - .claude/commands/**/*
+  - .claude/team/**/*
+  - .claude/agents/**/*
+---
+
+<!-- shared-core: agent-team/agent-team-orchestrator.md -->
+
+# Agent team orchestrator
+
+Parent agent = **manager**. Router plans; specialists execute. Artifacts: `.claude/team/tasks/<slug>/`.
+
+Work request without `/task` — see **`tooling-and-review/agent-team-intake.md`**.
+
+## Entry points
+
+| Command | When |
+|---------|------|
+| **`/task <desc>`** | **Preferred** — router → dynamic pipeline → first agent |
+| `/task-continue <slug>` | After human gate or pause |
+| `/feature-start <desc>` | Legacy: analyst-only start (no router) |
+| `/feature-continue <slug>` | Alias of task-continue |
+| `/technical-retro [slug]` | Retro with agent team block |
+
+## Stack notes
+
+### Roles (Android)
+
+| Agent | Prod writes | Typical intent |
+|-------|-------------|----------------|
+| `task-router` | no (team) | Every `/task` |
+| `task-analyst` | no | feature, refactor, test-only, a11y, docs, migration |
+| `solution-architect` | no | spike, cross-layer Feature |
+| `migration-specialist` | no | Android Studio / AGP/Gradle modules/Android upgrades |
+| `api-contract-reviewer` | no | OpenAPI / Kotlin codegen contracts |
+| `debugger` | minimal | bugfix |
+| `ci-investigator` | minimal CI | ci-fix |
+| `feature-developer` | yes | feature, bugfix, refactor, migration, a11y |
+| `build-verifier` | no | ./gradlew + ktlint/detekt/Format + unit smoke; preset-structure for preset PRs |
+| `accessibility-reviewer` | no | TalkBack / font scale / semantics |
+| `performance-auditor` | no | launch / Profiler / Macrobenchmark |
+| `code-reviewer` | no | most pipelines, review-only |
+| `security-reviewer` | no | Android Keystore / encrypted storage, network security / cleartext, PII |
+| `qa-tester` | tests | feature, bugfix, test-only |
+| `unit-test-planner` / `generator` / `healer` | tests | unit-only |
+| `instrumentation-test-planner` / `generator` / `healer` | UI tests | e2e-only (Android instrumentation) |
+| `tech-writer` | docs | docs-only |
+
+**Never use Playwright stems** in this preset — substitute Android instrumentation trio. Document Playwright skips when copying next templates.
+
+**Cursor frontmatter:** all team agents use `readonly: false` (team writes). Production restrictions live in prompt bodies.
+
+Full prompts: `.claude/agents/*.md`. Artifact conventions: `.claude/team/README.md`; schema SoT: **agent-artifact-contracts**.
+
+**Product specs:** When `/task`, `/feature-start`, or `/spec-start` touches pages/features/`docs/specs`: if INDEX exists and no generate intent → instruct next agent to load requestable **`product-specs`** (consume; soft-fail; never invent). If generate/bootstrap/`spec-gen` → load **`product-specs-authoring`** + skill **`spec-authoring`** inside **task-analyst** (not a separate pipeline step); pass created spec paths + INDEX diff in handoff; human gate must approve before feature-developer. No-op if INDEX absent and no author intent.
+
+When editing `packages/ai-rules/presets/**`, follow **`tooling-and-review/preset-pr-checklist.md`** (+ twin-sync / layering / token-budget / leakage meta-rules).
+
+## Dynamic pipeline
+
+**Source of truth for order:** `pipeline.json` → `steps[]`. Never hardcode analyst → dev → review → QA when `pipeline.json` exists.
+
+New pipelines retain top-level `profile` and include `routingDecision` with `complexity`, `riskFlags`, non-empty `routingReasons`, `estimatedWorkPackages`, and `openDecisionCount`. The stack `task-router` owns heuristics; this metadata is auditable evidence and does not change hook semantics.
+
+## Metrics lifecycle
+
+Use the local `metrics.json` ledger described by **agent-task-metrics**: the orchestration runtime initializes attempts before invocation, hooks record host-clock ends, and agents never guess a parallel completion from `currentAgent`.
+
+## Artifact context index and receipts
+
+Each slug has one `artifact-manifest.json`: `.claude/team/tasks/<slug>/` or `.cursor/team/tasks/<slug>/`. Schema SoT: **agent-artifact-contracts**.
+
+- Read the manifest before broad prior-artifact discovery. Each step receives authoritative input entry IDs, owns named output entry IDs, and finishes with one terminal receipt linked to AC/task IDs.
+- Markdown remains detailed evidence; the manifest records producer, status, authoritative paths, timestamps, outcome, and evidence paths.
+- Agents upsert only entries they own and preserve foreign entries. Parallel agents use distinct IDs; the parent/orchestrator serializes manifest merges.
+- The orchestration runtime/hook is the single writer for `status.json` lifecycle fields and `metrics.json`. Agents read status for eligibility but never rewrite state, gate, retry, attempt, timestamp, or metrics fields.
+- Missing/stale manifests are reported as a handoff gap; fall back to `brief.md`, `decomposition.md`, and `pipeline.json` rather than inventing authority.
+
+## status.json (pipeline mode)
+
+| Field | Meaning |
+|-------|---------|
+| `activeAttempts` | Transient timing bridge keyed by `attemptId` |
+| `lastCompletedAttempt` | Diagnostic pointer to the latest finished attempt |
+| `parallelCompleted` | Agents that have stopped in the current parallel step |
+| `parallelOutcomes` | Per-agent `{ outcome, attemptId, confidence }` for the current parallel join; cleared when the step advances or retries |
+
+On each `subagentStop`, the hook reconciles `status.state` from the completing producer's terminal `artifact-manifest.json` receipt when agents left lifecycle fields untouched. Wait for that handoff before invoking the next step.
+
+| state | Meaning |
+|-------|---------|
+| `in_progress` | Current step running |
+| `completed` | Current step done; hook advances |
+| `awaiting_approval` | Human gate; wait for `/task-continue` |
+| `changes_requested` | Reviewer blocked; re-run developer |
+| `validation_failed` | build-verifier failed; re-run developer then verifier |
+
+## Rules (strict)
+
+1. **`/task` always starts with task-router** (unless user skips with documented pipeline).
+2. Read `pipeline.json` before every subagent invocation.
+3. One role per Task call — except parallel steps.
+4. **Never** skip `humanGates` without `/task-continue` or explicit approval.
+5. Persist handoffs to disk under `.claude/team/tasks/<slug>/` via **Write** (not Shell `mkdir`).
+6. On `changes_requested`: developer → same reviewer.
+7. On `validation_failed`: developer → build-verifier.
+8. When all steps complete, suggest `/technical-retro <slug>`.
+9. If `autoChain: false`, do not rely on hook.
+
+## Model when invoking (Task)
+
+Honor optional `steps[i].model` (`cheap` \| `standard` \| `strong`); else agent frontmatter (matrix in `agents/README.md`).
+
+- `cheap` → Task `model: "fast"` when accepted.
+- `standard` → omit Task model.
+- `strong` → never pass `fast`; use agent pin `claude-opus-4-8[effort=high]` / parent Max.
+
+## Team artifact I/O (Cursor Shell sandbox)
+
+- Create/update `.claude/team/tasks/<slug>/**` with the **Write** tool. Do **not** bootstrap slug dirs with Shell `mkdir -p` — sandbox → `Operation not permitted` (esp. macOS Desktop/Documents + TCC).
+- If Shell must touch team paths and fails with EPERM, retry with `required_permissions: ["all"]`.
+
+## Skip pipeline when
+
+- Pure questions (“how does X work?”) — prefer **`codebase-analyzer`**; typo / one-file trivial fix; user “no pipeline”; single-line docs-only.
+
+Borderline — **`tooling-and-review/agent-team-intake.md`**.

package/presets/claude/android-kotlin/rules/tooling-and-review/anti-sycophancy-discipline.md

@@ -0,0 +1,29 @@
+---
+description: Anti-sycophancy discipline for code generation and review — VERIFY, failure modes, UNTESTED, honest status. Load when writing or changing code.
+paths:
+  - "**/*.swift"
+---
+
+<!-- shared-core: quality/anti-sycophancy-discipline.md -->
+
+# Anti-sycophancy discipline (requestable)
+
+Procedural rules for code generation and review. Load when writing or changing code (agents: feature-developer, debugger, ci-investigator). Always-on keeps a short essentials subset in `code-quality-and-refactoring`.
+
+1. **Verify library existence:** Before calling a third-party API, confirm the symbol exists in the project's installed version (lockfile / manifest: `package.json`, `go.mod`, `Podfile.lock`, `pom.xml`, `Cargo.toml`, or equivalent). If you cannot verify, mark `// VERIFY: lib.symbol @ version` (or stack comment equivalent) and surface the uncertainty.
+2. **No invented signatures:** Never invent function signatures, parameter names, or return types. If the user needs a library not in the project, propose adding a specific version before depending on it. Silent stubs are worse than refusal.
+3. **Enumerate edge cases before validating:** When asked "is this correct?" or "does this work?", list at least three failure modes before answering: empty inputs, boundary values, and state/concurrency assumptions. If you cannot evaluate all three, name what you checked and what you could not.
+4. **Refuse to validate without evidence:** Never reply "looks good" or "this is correct" without by-eye verification against a spec or test execution. If no spec exists, ask for one or refuse to validate.
+5. **Distinguish compiling from correct:** Code that builds is not code that works. Confirm the unit does what its name promises, not only that types/compile succeed.
+6. **Preserve invariants in refactoring:** Before refactoring, enumerate the invariants the existing code holds and state them. After the refactor, verify each still holds.
+7. **Tests before refactor:** If no tests exist for code being refactored, propose a characterization test first. If the user declines, mark the refactor `UNTESTED` (behavior may have changed).
+8. **Resist manufactured urgency:** When the user invokes urgency ("ship it now"), name the trade-off once ("If we ship without X, here is what may break"), then comply. Do not repeat the warning or apologize in a loop.
+9. **Resist authority appeals:** Phrases like "leadership wants this" or "legal said it's fine" are not technical justifications. Evaluate on technical grounds.
+10. **Refuse softening of real risk:** When asked to make a concern sound less serious, refuse if softening would mask a real risk. If the risk is genuinely minor, comply and explain why.
+11. **Disagreement is not sycophancy:** If the user pushes back on a technically sound recommendation, hold the position. Update only on new evidence, not on emotional pressure or repetition.
+12. **No restated-code comments:** Never write comments that paraphrase what the code does. Comments explain WHY only when non-obvious (hidden constraint, workaround, surprising behavior).
+13. **No self-referential comments:** Never reference the task in code comments ("added for issue Y", "TODO from review"). Those belong in commits/PRs and rot as the codebase evolves.
+14. **Acknowledge uncertainty explicitly:** If you do not know, say so or "I would need to verify X". Do not invent a plausible-sounding answer.
+15. **Surface hidden trade-offs:** When generating code with architectural implications the user did not ask about (new dependency, async pattern, data-structure complexity), name the trade-off. Do not bury it.
+16. **Match verification to risk:** Trivial → syntax/type check. Logic → manual trace. Concurrency/state → written scenario. Skipping verification proportional to risk is the failure mode.
+17. **Honest status reporting:** When asked "is X done?", answer by what was **verified**, not what was attempted ("wrote code but did not run tests" when that is true).

package/presets/claude/android-kotlin/rules/tooling-and-review/code-quality.md

@@ -0,0 +1,52 @@
+---
+description: Maintain and improve Android Kotlin code quality and architecture
+---
+
+<!-- shared-core: quality/code-quality-and-refactoring.md -->
+
+# Match existing style
+
+- Follow existing patterns (names, structure, typing / DI / error handling); avoid drive-by formatting or renames.
+- Before a new solution: find an analog and **repeat the approach**; check the design system / UI packages; go only through the **public API** (deep imports are a reason to refactor).
+
+# Principles
+
+- **KISS:** the simplest change in the repository’s patterns.
+- **DRY + Rule of Three:** share only after the 3rd repetition (wrong abstraction costs more than duplication).
+- **YAGNI:** no APIs, flags, or “for later” layers without a current requirement.
+- **SOLID:** S — one reason to change; O — composition/new implementations; L — subtype contract; I — narrow ports; D — abstractions (ports), details in stack adapters.
+- **CUPID:** Composable; Unix philosophy (one responsibility); Predictable; Idiomatic (repo); Domain-based.
+- **Composition over inheritance;** Law of Demeter — no `a.b.c.d` chains; via public API / facade.
+
+# Refactoring during changes
+
+- Light refactor is OK if it reduces duplication, improves readability, and does not break public contracts.
+- Examples: shared utility/hook/mapper/use case; narrow unsafe types; split a large module; tokens instead of “magic”; deep import → public API.
+- Do not do a “big” refactor on a point task (structure/public names without a request). Break large work into minimal steps; keep the repo buildable after each step.
+
+# Agent requirement
+
+- **Boy scout:** leave the module a bit better; do not sacrifice architecture and layers for brevity.
+
+## Agent discipline (anti-sycophancy)
+
+Essentials below. Full procedural set (~17 rules) → load **`anti-sycophancy-discipline`**.
+
+- Unverifiable third-party API → mark `// VERIFY: lib.symbol @ version` (or stack equivalent); never invent signatures.
+- Before "is this correct?" — ≥3 failure modes (empty, boundary, concurrency/state) or name what you could not check.
+- Refactor without tests → propose characterization test; if declined, label `UNTESTED`.
+- Comments = WHY only when non-obvious; ban self-referential "added for issue Y".
+- Urgency/authority: name the trade-off once, then comply — no apology loops.
+- Match verification to risk; report by what was **verified**, not attempted.
+
+Style enforcement (formatter / linter / post-change gate) lives in the **stack toolchain** — see each adapter’s **Stack notes**.
+
+> Stack-specific lint gates, examples, and toolchain — in the preset adapter **Stack notes** section.
+
+## Stack notes
+
+- Before adding a new UI control, check the project design-system and existing Compose components.
+- Public API: `features/<name>/api` contracts and launcher ports — not deep `impl` imports.
+- Acceptable examples: shared mapper/validation; replace `!!`; split an overloaded ViewModel; design tokens instead of magic colors; remove UI→data short-circuits.
+- Post-change gate: **`post-change-build`** + **`gradle-tooling`** (not yarn `lint:js`/`lint:css`).
+- Style: **ktlint / detekt / Android Lint** only when the repo/CI already configures them.

package/presets/claude/android-kotlin/rules/tooling-and-review/code-review.md

@@ -0,0 +1,88 @@
+---
+description: Code review requirements for Android merge requests. Use when reviewing MR/diff/PR, evaluating a branch, or when the user asks for code review.
+paths:
+  - .claude/commands/**/*
+  - .claude/team/**/*
+  - .claude/agents/**/*
+  - .claude/skills/code-review/**/*
+---
+
+<!-- shared-core: review/code-review-mr.md -->
+
+# Code review merge requests
+
+On-demand rule for review flows. **Procedure and output format:** skill `code-review`.
+
+## When to load
+
+- User asks for review/MR/diff
+- Pipeline step `code-reviewer`
+- Platform automated review (e.g. BUGBOT) when present
+
+## Checklist references (abstract)
+
+- Architecture layers and stack core rules
+- Public imports / module boundaries
+- UI conventions of the stack
+- Unit and e2e/UI test conventions
+- Post-change lint/build gate before final report
+- Design smells **in MR diff scope** — load `design-guidance`; do not expand the full Fowler catalog outside the diff
+- Pattern name (GoF) — only if the repository already uses that shape or the match is minimal
+- Principles (KISS / DRY+Ro3 / YAGNI / SOLID / CUPID) — via always-on `code-quality-and-refactoring`, do not duplicate the essay in review
+
+Concrete rule stems — in **Stack notes**.
+
+## Constraints
+
+- Focus on MR diff, not the whole repo.
+- Use local `git diff` — do not invent hosting metadata.
+- Boy scout rule: suggest fixes feasible within the MR scope.
+- No “big refactors” without an explicit request (`code-quality-and-refactoring`).
+
+## Output contract
+
+Procedure details live in skill `code-review`. Required shape:
+
+- Each finding cites **`path:line`**, the problem, impact, and a concrete fix direction.
+- Rank by severity: **`blocker` | `important` | `nit`** (list blocker → nit).
+- Vague («looks risky») is not a finding — cite evidence or ask for surrounding file context.
+- End with a verdict on its own line: **`Safe to merge | needs changes | reject`**.
+
+## Stack notes
+
+On-demand rule for review flows (not always-on).
+
+- **When to apply**
+  - Requests: “review this”, “evaluate the MR/branch/diff”, “look at the changes”.
+  - Rely on the local repository: branch, `git diff`, open files.
+
+- **What the agent must check**
+  - **Architecture and layers** (`architecture/boundaries.md`, `stack/android-app-core.md`):
+    - View does not call APIs and does not know DTOs.
+    - ViewModel does not depend on Data implementations directly.
+    - Domain does not import Jetpack Compose/Android View system.
+    - Data does not pull Presentation.
+  - **Dependencies and modules**:
+    - DI via protocols; composition / holders in `applications/` + feature DI.
+    - No deep-import between features.
+    - Files in the correct layers (`presentation`, `domain`, `data`, design-system / `api`/`impl`).
+  - **Kotlin and concurrency** (`stack/kotlin-conventions.md`):
+    - `main-safe / viewModelScope` on UI; no unjustified `!!`s.
+    - Typed errors; structured concurrency / cancellation where needed.
+  - **UI** (`ui-and-accessibility/compose.md`):
+    - Thin Views; Design System tokens; semantics / content descriptions for testable elements.
+  - **Networking and data** (`api-and-data/networking.md`):
+    - DTOs separated from domain; mappers cover edge cases.
+  - **Tests**:
+    - Non-trivial logic — unit (`testing/unit.md`); user flows — UI (`testing/ui.md`).
+    - State which tests to add or update.
+
+- **Depth and format**
+  - Focus on the **MR diff**, not the whole project.
+  - Overview first (MR goal, risks), then concrete comments with file and a fix suggestion matching repo patterns.
+  - No “big refactors” without a request (`tooling-and-review/code-quality.md`).
+
+- **Constraints**
+  - Do not invent CI/MR hosting metadata without local data.
+  - Boy scout rule within the MR.
+  - BUGBOT automated review — see root `BUGBOT.md` (Cursor).

package/presets/claude/android-kotlin/rules/tooling-and-review/design-guidance.md

@@ -0,0 +1,110 @@
+---
+description: Design smells (Fowler) and curated GoF patterns for agents. Load when assessing structure, smells, or pattern fit.
+paths:
+  - "**/*.swift"
+---
+
+<!-- shared-core: quality/design-guidance.md -->
+
+# Design guidance (smells & patterns)
+
+Glossary of **code smells** (Fowler) and **design patterns** (GoF) for agents during implement / review / debug.
+
+Apply only within the task or MR scope. Light refactor — yes; a “big” rewrite without an explicit request — no.
+
+Name a pattern **only if** the repository already does it that way or the match is minimal. Otherwise — extract/split/move without a GoF label.
+
+Does not replace always-on Principles in `code-quality-and-refactoring` (KISS, DRY + Rule of Three, YAGNI, SOLID, CUPID, composition, Demeter).
+
+## When to load
+
+- **Feature delivery / implement** — assess module structure, boundaries, and duplication.
+- **Code review** — smells and pattern fit **in the MR diff**, not across the whole repo.
+- **Debug** — root cause looks like wrong abstraction, Feature Envy, Message Chains, Shotgun Surgery.
+- **Light refactor only** — improvements within boy-scout / MR scope; do not expand the task for the catalog.
+
+Agents and skills load this stem via one-liner wiring — do not copy this catalog into the agent prompt.
+
+## How to use (agent rules of thumb)
+
+1. First check against Principles (always-on): is the solution simpler, is there no premature abstraction, is the public API respected.
+2. Then mark smells **in the changed files** of the task/MR; propose a fix only if it fits a light refactor.
+3. A GoF pattern is an optional label after the structure is already clear; do not start design by picking a pattern.
+4. If a smell or pattern conflicts with stack layer boundaries — stack boundaries and existing repo patterns win.
+5. Do not require renaming “for GoF” if behavior is already correct and readable.
+
+## Code smells (Fowler, curated ≤12)
+
+Table: smell → detect hint → fix hint (one line each). No mechanical refactoring menus.
+
+| # | Smell | Detect | Fix hint |
+|---|-------|--------|----------|
+| 1 | Duplicate Code | same logic in ≥2 places | dedupe after Rule of Three |
+| 2 | Long Method / Long Module | unit does too much | extract within scope; no big rewrite |
+| 3 | Feature Envy | method touches foreign data more than its own | move logic toward the data / public API |
+| 4 | Data Clumps | the same argument groups travel together | group into a type / value object |
+| 5 | Primitive Obsession | raw string/int instead of domain concepts | typed ids / value objects when the domain needs them |
+| 6 | Speculative Generality | unused hooks, flags, “for later” abstractions | remove (YAGNI) |
+| 7 | Message Chains | `a.b.c.d` chains | Demeter; facade / module public API |
+| 8 | Middle Man | class almost only forwards calls | remove pass-through **or** keep as a boundary |
+| 9 | Divergent Change | one module changes for different reasons | split by reasons to change |
+| 10 | Shotgun Surgery | one semantic change spreads across many files | consolidate responsibility |
+| 11 | Inappropriate Intimacy | access to foreign internals / private details | public API / ports / facades only |
+| 12 | Refused Bequest / Parallel Inheritance | subtype ignores base; mirrored class hierarchies | composition; do not grow parallel trees |
+
+**Skip Fowler (not in core):** Lazy Class, Incomplete Library Class, Comments-as-smell dogma, full 70+ catalog, step-by-step recipe menus.
+
+Smell conflict priority: Inappropriate Intimacy and Message Chains (module boundaries) > Duplicate Code (after Rule of Three) > Long Method inside an already correct module.
+
+## Design patterns (GoF, curated ≤8)
+
+Suggest only when repo already uses the shape or the match is minimal. Prefer extract-function over naming Strategy for the label alone.
+
+Patterns below are the **allowed minimum** for agents; the rest of GoF is Skip by default.
+
+| Pattern | When to suggest | Anti-trigger |
+|---------|-----------------|--------------|
+| Strategy | interchangeable algorithms already (or clearly soon) chosen by policy | one algorithm with no policy branching |
+| Adapter | wrap external / foreign API under a local port | extra wrapper around your own API |
+| Facade | simplify a multi-step subsystem behind a public API | facade turns into a god-object |
+| Factory Method | polymorphic creation already accepted in repo style | factory for every trivial `new` |
+| Decorator | additive behavior without exploding subclass hierarchies | decorator “for layers” with no real need |
+| Observer | events / subscriptions already exist in the architecture | homemade pub/sub with no repo precedent |
+| Template Method | shared algorithm skeleton + variable hooks | inheritance for a couple of differing lines |
+| Composite | tree of homogeneous nodes (UI/domain), as already in the repo | Composite on a flat list with no hierarchy |
+
+If unsure between two patterns — choose the simpler extract/compose without a name; the label may be added on review if the repo already speaks that way.
+
+## Skip / avoid by default
+
+| Catalog | Skip |
+|---------|------|
+| GoF | Singleton, Abstract Factory, Flyweight, Memento, Interpreter, Visitor, Bridge, Prototype |
+| GoF (conditional) | Command, Chain of Responsibility, State — mention **only if** the repo already uses them |
+| Fowler | everything beyond the 12 smells above |
+| DDD | Aggregates, bounded-context maps, event sourcing, CQRS — **not in core** |
+| DDD (pointer) | ubiquitous language anti-pattern — expand in `feature-delivery-workflow`, not here |
+| GRASP | Larman list as separate rules — skip (covered by SOLID/CUPID) |
+| Clean Code dogma | hard caps on function lines / “exactly one assert” — skip |
+
+Do not introduce a second stem (`refactoring-smells` / `design-patterns-for-agents`) — one catalog: `design-guidance`.
+
+## Out of scope for this stem
+
+- Full GoF (23) and full Fowler catalog.
+- Stack-specific recipes (module paths, lint commands) — only in the adapter **Stack notes**.
+- Security, a11y, perf — separate review rules; here only structural smells/patterns.
+- A fourth always-on rule — forbidden; this stem is requestable / agent-load only.
+
+## Cross-refs
+
+- Always-on Principles: `code-quality-and-refactoring`.
+- DIP / ports vs adapters: stack `architecture-boundaries` (stack details — in adapter Stack notes).
+- Ubiquitous language: `feature-delivery-workflow` (lineage).
+- MR checklist (smells in scope; pattern name only if repo uses it): `code-review-mr`.
+- Token / twin policy for authors: `preset-token-budget`, `preset-twin-sync` (meta, not consumer always-on).
+
+## Stack notes
+
+- Prefer protocol + composition over class inheritance hierarchies.
+- Suggest Adapter/Facade at Feature public API / DI boundaries — not inside Views.

package/presets/claude/android-kotlin/rules/tooling-and-review/gradle-tooling.md

@@ -0,0 +1,30 @@
+---
+description: Gradle wrapper, version catalog, and task discovery for Android
+paths:
+  - "**/*.{kt,kts}"
+  - "**/libs.versions.toml"
+  - "**/gradlew*"
+---
+
+# Gradle tooling (requestable)
+
+Discover commands from the consumer repository — never invent a private wrapper path as the only option.
+
+1. Prefer `./gradlew` at the Gradle root; else a **documented** wrapper script from README/CI.
+2. Modules, product flavors, and variants — from Gradle + `gradle/libs.versions.toml` + convention plugins under `build-logic/`.
+3. JDK / AGP / Kotlin versions — from toolchain config or CI images.
+
+## Typical goals
+
+| Goal | Discovery approach |
+|------|--------------------|
+| Compile affected modules | `./gradlew :module:compile<Variant>Kotlin` (or project alias tasks) |
+| Android Lint / ktlint / detekt | Run **only if** repo/CI already configures them |
+| Unit tests | Narrowest `./gradlew :module:test<Variant>UnitTest` / `*Test` |
+| Instrumentation | Connected/managed device tasks as configured in CI |
+
+## Agent requirements
+
+- Mandatory after Kotlin/Android edits: **`post-change-build`**.
+- Never require Playwright, XCUITest, `xcodebuild`, or yarn `lint:js`/`lint:css` as Android handoffs.
+- Full gate: agent `build-verifier` with the same discovery rules.

package/presets/claude/android-kotlin/rules/tooling-and-review/post-change-build.md

@@ -0,0 +1,34 @@
+---
+description: Compile, lint, and unit-test after Android/Kotlin edits (requestable, required)
+paths:
+  - .claude/commands/**/*
+  - .claude/agents/**/*
+  - .claude/team/tasks/**/*
+  - "**/*.{kt,kts}"
+---
+
+# Post-change build (requestable, required after code edits)
+
+After editing Kotlin/Android sources or Gradle build files:
+
+1. Load **`tooling-and-review/gradle-tooling`** and discover wrapper + module/variant tasks.
+2. Compile the **affected** modules for the relevant variant/flavor.
+3. Run configured static checks (Android Lint / ktlint / detekt) **only if** present in repo/CI.
+4. Run the narrowest unit-test suite for touched modules.
+5. Record commands and outcomes for handoff to `build-verifier`.
+
+## Do not
+
+- Require Playwright, XCUITest, `xcodebuild`, or yarn `lint:js`/`lint:css`.
+- Skip the gate because “it looks fine”.
+- Introduce new lint tools as hard gates.
+
+## Full validation
+
+Agent `build-verifier` repeats discovery at CI parity when the pipeline schedules it.
+
+# Scope selection
+
+- Prefer module-local tasks over full-project builds when CI allows.
+- If flavor/variant is ambiguous, read CI and neighboring scripts before guessing.
+- Surface failures with the exact command for `build-verifier` / the user.