@bonesofspring/ai-rules 0.2.25 → 0.2.27

package/presets/mavis/ios-swift/mcp.json

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

package/presets/mavis/ios-swift/rules/README.md

@@ -0,0 +1,16 @@
+# Mavis iOS Swift rules
+
+Plain Markdown. MiniMax does not auto-load these files; root `AGENTS.md` and
+`.mavis/AGENTS.md` reference them explicitly.
+
+## Essential (entry-critical)
+
+`ios-app-core`, `architecture-boundaries`, `code-quality-and-refactoring`,
+`ai-local-overlay`.
+
+## Requestable
+
+All other `*.md` files in this directory. Read when the task matches the
+catalog in the Cursor source `rules/README.md` (same stems).
+
+Shared-core markers (`<!-- shared-core: … -->`) are preserved from Cursor.

package/presets/mavis/ios-swift/rules/agent-team-intake.md

@@ -0,0 +1,11 @@
+<!-- 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/mavis/ios-swift/rules/agent-team-orchestrator.md

@@ -0,0 +1,214 @@
+<!-- shared-core: agent-team/agent-team-orchestrator.md -->
+
+# Agent team orchestrator
+
+Parent agent = **manager**. Router plans; specialists execute. Artifacts: `.ai.local/team/tasks/<slug>/`.
+
+Work request without `/task` — see **agent-team-intake** (when to suggest the router instead of coding directly).
+
+## Entry points
+
+| Command | When |
+|---------|------|
+| **`/task <desc>`** | **Preferred** — router → dynamic pipeline → first agent |
+| `/task-continue <slug>` | After human gate or pause |
+| `/spec-start [desc]` | Generate/bootstrap `docs/specs` — router intent `spec-gen` → analyst author mode → human gate |
+| `/technical-retro [slug]` | Retro with agent team block |
+
+## Roles (shared catalog)
+
+Roster of specialists is **stack-specific** (agent names and write scopes differ). See **Stack notes** in the stack adapter for the live Roles table. Common patterns:
+
+| Kind | Examples (names vary by stack) |
+|------|--------------------------------|
+| Planning | `task-router`, `task-analyst` (plus skill `ux-design` for behavioral UX **where the stack has a UI surface**), `solution-architect`, `migration-specialist` |
+| Implementation | `feature-developer`, `debugger`, `ci-investigator` |
+| Gates / review | `build-verifier`, `code-reviewer`, `security-reviewer`, `performance-auditor`; plus stack-native a11y/UI reviewer and `mockup-reviewer` **only when the stack has a UI surface** |
+| Tests | unit planner/generator/healer; e2e/UI planner/generator/healer (stack-native) |
+| Docs | `tech-writer` |
+
+**Mavis packaging:** team pipeline agents are plain Markdown with no YAML frontmatter (`name`, `readonly`, `model`). Attach with `mcode exec --file`. Production/app restrictions live in the agent prompt body. See `agents/README.md`.
+
+Full prompts: stack `agents/*.md`. Artifact conventions: stack `team/README.md`; schema SoT: **agent-artifact-contracts**.
+
+## Stack notes
+
+Roles and write scopes — **`agents/README.md`**. Mavis agents have no YAML `readonly` / `model` frontmatter.
+
+## Dynamic pipeline
+
+```mermaid
+flowchart TD
+  task["/task prompt"]
+  router["task-router"]
+  pipeline["pipeline.json"]
+  step0["steps 0..N"]
+  gate{"humanGates?"}
+  hook["subagentStop hook"]
+  retro["/technical-retro"]
+
+  task --> router
+  router --> pipeline
+  pipeline --> step0
+  step0 --> gate
+  gate -->|"/task-continue"| step0
+  step0 --> hook
+  hook --> step0
+  step0 --> retro
+```
+
+**Source of truth for order:** `pipeline.json` → `steps[]`. Never hardcode analyst → dev → review → QA when `pipeline.json` exists.
+
+## Routing decision contract
+
+Keep top-level `profile` (`light` | `standard` | `full`) and add a top-level `routingDecision` object:
+
+```json
+{
+  "profile": "standard",
+  "routingDecision": {
+    "complexity": "moderate",
+    "riskFlags": ["behavior-regression"],
+    "routingReasons": [
+      "The failure needs root-cause analysis before a bounded fix.",
+      "Behavior changes require validation and independent review."
+    ],
+    "estimatedWorkPackages": 1,
+    "openDecisionCount": 0
+  }
+}
+```
+
+| Field | Contract |
+|-------|----------|
+| `complexity` | `low` \| `moderate` \| `high`; classify scope and coordination, not perceived coding difficulty |
+| `riskFlags` | Array of concrete signals such as `public-contract`, `cross-layer`, `security-sensitive`, `migration`, `destructive`, `concurrency-state`, `external-dependency`, `unclear-acceptance-criteria`, `broad-test-surface`, `behavior-regression` |
+| `routingReasons` | Non-empty, auditable facts from the request; each reason explains a profile, gate, specialist, skip, or checkpoint choice |
+| `estimatedWorkPackages` | Integer ≥1; count meaningful independently verifiable delivery scopes, not files or agents |
+| `openDecisionCount` | Integer ≥0; unresolved product/architecture/contract choices at routing time |
+
+Rubric:
+
+- `low`: one bounded scope, explicit acceptance criteria, reversible change, no risk flags or open decisions. Use `light` only when stack verification policy permits.
+- `moderate`: several files or adjacent concerns, a regression/refactor with known boundaries, or one contained risk flag. Usually `standard`.
+- `high`: cross-layer/public-contract work, migration/destructive/security/concurrency risk, broad test surface, multiple work packages, or unclear acceptance criteria. Usually `full`.
+- Increase the profile when risk, open decisions, or required checkpoints demand it; do not lower complexity merely because the implementation is familiar.
+- Do not write generic reasons such as “standard by default.” Name the observed signal and the routing consequence.
+
+Existing pipelines without `routingDecision` remain valid; routers emit it for new pipelines. The block is documentary routing evidence in P0 and does not change hook behavior.
+
+## Metrics lifecycle
+
+For local metrics policy and the `metrics.json` ledger, see **agent-task-metrics**. The orchestration runtime records `task_started` and one `attempt_started` before each invocation; the hook records host-clock terminal and human-gate events. Keep active attempt identities in `status.json.activeAttempts` so parallel completions can be bound safely.
+
+Do not calculate durations in agents. For parallel steps, never attribute a stop using `currentAgent` alone: use a stable runtime identity, the sole active attempt, or an explicit receipt marked with fallback confidence.
+
+## Artifact context index and receipts
+
+Each slug has one `artifact-manifest.json` at `.ai.local/team/tasks/<slug>/`. The full schema and completion conventions live in **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 points to authoritative paths and records producer, status, 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 unrelated 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)
+
+```json
+{
+  "slug": "...",
+  "intent": "feature",
+  "pipelineIndex": 0,
+  "currentAgent": "task-analyst",
+  "phase": "executing",
+  "state": "in_progress",
+  "awaitingHumanGate": false,
+  "activeAttempts": {},
+  "lastCompletedAttempt": null,
+  "parallelCompleted": [],
+  "parallelOutcomes": {}
+}
+```
+
+| 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 |
+
+| 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 (`retryAfterFix`) |
+| `validation_failed` | build-verifier failed; re-run developer then build-verifier |
+
+On each `subagentStop`, the hook reconciles `status.state` from the completing producer's terminal `artifact-manifest.json` receipt (`completed` \| `changes_requested` \| `validation_failed`) when agents left lifecycle fields untouched. Parent orchestrators must wait for that handoff before invoking the next step.
+
+## Pipeline step options
+
+| Field | Use |
+|-------|-----|
+| `skipIf` | `debugger.fixed` / `ci-investigator.resolved` — hook skips step when artifact says fix applied |
+| `parallel: true` | `agent` is array — invoke **all** agents in one parent turn; each appends to `parallelCompleted` |
+| `scope` | e.g. `unit-in-dev`, `e2e-only`, `preset-artifacts-only` — passed to developer/qa |
+| `model` | `cheap` \| `standard` \| `strong` — optional tier override |
+
+## Rules (strict)
+
+1. **`/task` always starts with task-router** (except user says "skip router" with documented pipeline).
+2. Read `pipeline.json` before every subagent invocation.
+3. One role per Task call — **except** parallel steps: multiple Task calls in one message.
+4. **Never** skip `humanGates` without `/task-continue` or explicit user approval.
+5. Persist handoffs to disk (`brief.md`, `decomposition.md`, `debug-report.md`, `validation-report.md`, `architecture.md`, `migration-plan.md`, `ci-report.md`, `a11y-review.md`, `perf-report.md`, `security-review.md`, `api-contract-review.md`, `unit-test-plan.md`, `documentation.md`, `review.md`, `mockup-review.md`, `ux-design.md`) and update the producer-owned terminal receipt in `artifact-manifest.json`.
+6. On `changes_requested` from reviewers: hook sets `retryAfterFix` → developer → same reviewer. Exception: embedded `mockup-reviewer` FAIL (`changes_requested` while the completed/current agent is `mockup-reviewer`) → `awaiting_approval` / `/task-continue` only — do **not** `retryAfterFix` to developer.
+7. On `validation_failed` from `build-verifier`: hook sets `retryAfterFix: build-verifier` → developer → build-verifier.
+8. When all steps complete, suggest `/technical-retro <slug>`.
+9. If `autoChain: false` in pipeline, do not rely on hook — manual step only.
+
+## Team artifact I/O
+
+- Create/update team task dirs with the **Write** tool (parents are created automatically). Do **not** bootstrap slug dirs with Shell `mkdir -p` — default sandbox returns `Operation not permitted` (worse on macOS Desktop/Documents with TCC).
+- If Shell must touch team paths and fails with EPERM, retry with `required_permissions: ["all"]`. Prefer Write for artifacts.
+- Prefer repo under `~/Projects` / `WebstormProjects` over `~/Desktop` when using agent team heavily.
+
+## Invoking agents
+
+Use Task tool or `/agent-name`. Pass: slug, artifact paths, step `scope` if set.
+
+### Model when invoking (Task)
+
+1. Read `steps[i].model` if present; else use the agent’s frontmatter `model` (see `agents/README.md` matrix).
+2. Map abstract tiers:
+   - **`cheap`** → pass Task `model: "fast"` when the tool accepts it (or rely on agent `fast`).
+   - **`standard`** → omit Task `model` (frontmatter `inherit` / mid default).
+   - **`strong`** → **never** pass `fast`; rely on agent pin or parent Max model.
+3. Parallel steps: apply the step-level `model` to **each** agent in the array (or omit → each agent’s own frontmatter).
+
+After each agent completes, verify its terminal manifest receipt, then let the orchestration runtime/hook reconcile `status.json` (`completed`, a blocking outcome, or `awaiting_approval`) from that receipt. Do not ask the agent to mutate shared lifecycle fields, and do not invoke the next specialist until the hook has written the handoff / updated `status.json`.
+
+## Legacy mode
+
+If `pipeline.json` is missing, fall back to fixed phases: analysis → development → review → testing. Hook supports both.
+
+## Skip pipeline when
+
+Do **not** run `/task` + router for:
+
+- Pure questions («как работает X» (how does X work), «объясни» (explain)) — prefer agent **`codebase-analyzer`** for deep traces; inline OK for trivial one-liners. <!-- i18n-keep: E4 -->
+- Typo / one-file fix / trivial config with no architecture risk.
+- User explicitly says «без pipeline» (no pipeline), «просто сделай» (just do it), or continues an active slug. <!-- i18n-keep: E4 -->
+- Single-line `docs-only` with no code impact.
+
+Borderline work requests — see **agent-team-intake**.
+
+## Auto-detection (optional)
+
+When user describes a **non-trivial task** (not a question), suggest `/task <message>` or run router if they agree.
+
+## Preset authoring
+
+When the work edits `packages/ai-rules/presets/**` (or dogfood `.cursor/` sync of presets), follow meta-rules: **preset-pr-checklist**, **preset-twin-sync**, **preset-layering**, **preset-token-budget**, **preset-no-cross-stack-leakage**.

package/presets/mavis/ios-swift/rules/ai-local-overlay.md

@@ -0,0 +1,37 @@
+# Local overlay (`.ai.local/`) — MANDATORY
+
+This rule is mandatory. **You MUST** obey it on every turn, without exception.
+
+## On every turn
+
+1. **Probe** — before answering, run `ls -la .ai.local` from the repository root.
+2. **Walk** — if `.ai.local/` exists at multiple levels (monorepo), read every level from root to leaf. **Deeper wins** in practice: more specific rules appear later in the assembled context and take precedence.
+3. **Apply** — treat every `.ai.local/rules/*.md` and `.ai.local/conventions.md` as a higher-priority rule for this repo. Do **not** load `.ai.local/team/**` as rules (shared pipeline artifacts). The block below ("Authoring `.ai.local/rules/*.md`") defines the conventions.
+4. **Conflict** — if a local rule conflicts with a preset rule, **the local rule wins**. If a local rule body contains `override: kill <preset-rule-name>`, drop that preset rule from your context window entirely.
+5. **Acknowledge** — when answering a user question, briefly state which `.ai.local/` rules apply to the current task (one line is enough). Format: `Using .ai.local: <rule-name>(, <rule-name>)*`. If no `.ai.local/` exists, do NOT mention this rule.
+
+If `.ai.local/` does not exist → **no-op**, do not error. Do not produce any log line about its absence.
+
+## Authoring `.ai.local/rules/*.md` (consumer-side reference)
+
+Each `.ai.local/rules/<name>.md` is a plain-markdown rule body. The model parses it as:
+
+- Lines before `## Body` are scope metadata. Only `glob:` / `globs:` / `override:` lines are recognised.
+- Everything from `## Body` onward is the rule body.
+- `glob: always` → always-on. Counts against your context budget.
+- `globs: <comma-separated globs>` → on-demand; applies only when matching files are in focus.
+- `override: kill <preset-rule-name>` → drop that preset rule from context.
+
+Keep files ≤ 120 lines. Match the style of preset rules (short sections, bullets, code examples).
+
+## Limitations (read this)
+
+- Cursor/Claude do **not** natively read `.ai.local/`. This rule is a **prompt-only** mechanism: it asks you, the model, to read and apply the files. Reliability is high but not 100%.
+- If a user adds a file to `.ai.local/` mid-session, **restart the session** to be sure it is picked up.
+- "Priority" is **contextual**, not enforced. Always re-read the local rule before answering questions that touch it.
+
+## Pointers
+
+- Authoring guide: `docs/LOCAL-OVERLAY.md` in the `@bonesofspring/ai-rules` package.
+- Living gotchas: `.ai.local/conventions.md`. Pipeline artifacts: `.ai.local/team/` (do not load as rules).
+- Root `AGENTS.md` reinforces this rule with a `MANDATORY` section.

package/presets/mavis/ios-swift/rules/anti-sycophancy-discipline.md

@@ -0,0 +1,23 @@
+<!-- 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 that is not enough and Context7 MCP is available, load **`mcp-usage`** and query docs for the **installed major**. If you still 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/mavis/ios-swift/rules/architecture-boundaries.md

@@ -0,0 +1,29 @@
+# Layer boundaries
+
+- **Presentation** (Views, ViewModels, DesignSystem):
+  - May: Domain (entities, use case protocols), DesignSystem, Core (non-UI).
+  - Must not: import Data (repositories, DTOs, API clients); know HTTP/Codable/endpoints; map DTO → domain.
+- **Domain**:
+  - May: Core (base types, protocols).
+  - Must not: import SwiftUI, UIKit, networking; know concrete repository implementations.
+- **Data**:
+  - May: Domain (protocols, entities), Core.
+  - Must not: import SwiftUI/UIKit; depend on View/ViewModel.
+
+# Dependencies and modules
+
+- Direction: **Presentation → Domain ← Data**.
+- Shared code — in Core / DesignSystem; to another feature — only **public API** (protocol, facade, coordinator), not deep-import.
+- SPM: Domain does not link Data; Data implementations are wired via DI in `App/`.
+- Feature layout — as in `ios-app-core.md` / neighboring `Features/*` in the repo (Presentation / Domain / Data + tests).
+
+# DI and composition root
+
+- Graph assembly — in `App/` (or `DI/` / CompositionRoot), not in the View.
+- ViewModel receives **protocols** (use case / repository), not concrete Data types.
+- Previews and tests — mock/stub implementations.
+
+# Agent requirement
+
+- Place files in the matching layers; repository protocols in Domain, implementations in Data.
+- Do not “short-circuit” layers (API from a View “for speed”).

package/presets/mavis/ios-swift/rules/code-quality-and-refactoring.md

@@ -0,0 +1,54 @@
+<!-- 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.
+
+# Over-abstraction guardrails
+
+- **No unnecessary constants:** do not hoist a one-off literal, string, or boolean into a named constant. Inline it, or use an existing token/enum when the value is meaningful and reused. Named constants are for shared, semantic, or repeated values.
+- **No invented utilities:** do not add a `utils`/helper for a single call site or a thin pass-through wrapper. Inline it or extend the existing helper; a new shared utility is justified only after the Rule of Three.
+- **Decompose over conditionals:** a unit (function, component, hook) that accumulates several branches (`if` / ternary / `switch`) should be split into smaller units with one reason to change instead of piling up conditions.
+
+# 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 → if Context7 is up, load **`mcp-usage`** and query the installed major; else 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 DesignSystem and existing components.
+- Public API: protocols and facades between features.
+- Acceptable examples: shared mapper/validation; replace force unwrap; split an overloaded ViewModel into use cases; design tokens instead of magic numbers/colors; remove a direct View→Data dependency in favor of a protocol.
+- Post-change gate: **`post-change-build.mdc`** + `xcode-tooling.mdc` (not yarn lint).
+- Style: **SwiftLint** (+ SwiftFormat when configured) — authoritative style gate; do not duplicate linter rules in prose.

package/presets/mavis/ios-swift/rules/code-review-mr.md

@@ -0,0 +1,79 @@
+<!-- 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.mdc`, `ios-app-core.mdc`):
+    - View does not call APIs and does not know DTOs.
+    - ViewModel does not depend on Data implementations directly.
+    - Domain does not import SwiftUI/UIKit.
+    - Data does not pull Presentation.
+  - **Dependencies and modules**:
+    - DI via protocols; composition root in App.
+    - No deep-import between features.
+    - Files in the correct layers (`Presentation`, `Domain`, `Data`, `DesignSystem`).
+  - **Swift and concurrency** (`swift-conventions.mdc`):
+    - `@MainActor` on UI; no unjustified force unwraps.
+    - Typed errors; correct Task cancellation where needed.
+  - **UI** (`swiftui-ui.mdc`):
+    - Thin Views; Design System tokens; accessibility identifiers for testable elements.
+  - **Networking and data** (`networking-services.mdc`):
+    - DTOs separated from domain; mappers cover edge cases.
+  - **Tests**:
+    - Non-trivial logic — unit (`tests-unit.mdc`); user flows — UI (`tests-ui.mdc`).
+    - 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 (`code-quality-and-refactoring.mdc`).
+
+- **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/mavis/ios-swift/rules/design-guidance.md

@@ -0,0 +1,104 @@
+<!-- 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.