@bonesofspring/ai-rules 0.2.24 → 0.2.26

package/presets/mavis/ios-swift/rules/product-specs-authoring.md

@@ -0,0 +1,112 @@
+<!-- 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`**.
+
+**Optional prefix:** when the user or AC asks **research-before-spec**, load skill **`spec-discovery`** first (subset of methods; **claim-ledger** mandatory). Not the default `/task` consume path and not a new pipeline step.
+
+## 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`; `schemas/frontmatter-v1.schema.json` is a documentation artifact — the checker does not evaluate it).
+
+**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`; optional skill `spec-discovery` when research-before-spec |
+| **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
+- Skill `spec-discovery` — opt-in research-before-spec (not default)
+- Optional consumer script `scripts/check-product-specs.sh` (ships in the npm package; WARN default; `--strict` FAIL). Bash checks INDEX links, required frontmatter keys, and body headings — it does **not** evaluate `frontmatter-v1.schema.json`

package/presets/mavis/ios-swift/rules/product-specs.md

@@ -0,0 +1,56 @@
+<!-- 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`).
+
+**Pipeline `specMode`:** `consume` (this stem) · `generate` (authoring stem) · `none` (spike/research — skip INDEX row requirement; do not invent a dummy INDEX). Primary field: `brief.md` `## Spec mode`; optional `pipeline.json` `specMode`.
+
+## 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 |
+| **None** (`specMode: none`) | Spike / research / preset-only | Skip INDEX requirement and author mode; no dummy INDEX row |
+
+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 `specMode` is **`none`** → do **not** require an INDEX row; continue from brief/AC. Do not invent INDEX.
+- 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** and `specMode` is not `none` → 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 (skip when `specMode: none`).
+2. Resolve the entry by: route, stable `id`, PageName / alias, or domain folder.
+3. Read the **linked page** spec and, when INDEX or page Related links it, the optional domain `feature.md`. Do **not** dump the whole `docs/specs/**` tree into the prompt — locator = those linked files.
+
+## 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.
+- Skill `spec-discovery` — opt-in research-before-spec (author mode only; not default consume).
+- `reference-features` — code structure mirror (how to layout files), not product behavior.
+- Consumer `.ai/context/**` when present — review/domain glossary; cross-link, do not replace.

package/presets/mavis/ios-swift/rules/reference-features.md

@@ -0,0 +1,45 @@
+<!-- shared-core: architecture/reference-features.template.md -->
+
+# Reference features
+
+Before implementing, find a feature of the same type and **mirror its structure**; do not invent a new file organization.
+
+## Reference table
+
+Replace placeholders with **real** paths after `ai-rules init` / team agreement:
+
+| Layer | Reference | What to copy |
+|-------|-----------|--------------|
+| UI / Presentation | **TBD** | components, styles/data helpers, barrel |
+| State / ViewModel | **TBD** | slice/VM, selectors, types |
+| API / Data | **TBD** | service/repo, mappers, barrel |
+| Domain / Types | **TBD** | domain types, public export |
+| Unit tests | **TBD** | `*.spec` / XCTest naming |
+| E2E / UI tests | **TBD** | cases/plans, page objects / accessibility IDs |
+
+## How to use
+
+1. Identify affected layers from `decomposition.md` or the task.
+2. Open the reference from the table (after paths are filled).
+3. Mirror naming, file order, import patterns, and tests.
+4. If there is no reference — pick the **closest** existing feature of the same layer and record the choice in the handoff.
+
+## Living conventions
+
+After init the team maintains **local** gotchas, patterns, and decisions in a consumer-owned store (not in shared core and not only in root `AGENTS.md`):
+
+| Section | What to record |
+|---------|----------------|
+| Gotchas | Recurring traps, fragile spots, “do not do X in this repo” |
+| Patterns | Local patterns beyond the reference table |
+| Decisions | Short ADR links / product decisions that affect code |
+
+Path pointer and stack tables — in the preset adapter (`.ai.local/conventions.md`). The file is **not** always-on.
+
+## Related rules
+
+- `code-quality-and-refactoring` — repeat patterns, no deep-import.
+- `feature-delivery-workflow` — layer order.
+- skill `feature-delivery` — end-to-end scenario.
+
+> Concrete path tables, globs, and dogfood checklists live in the stack adapter **Stack notes**.

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

@@ -0,0 +1,24 @@
+# Security (iOS)
+
+## Secrets and config
+
+- No API keys / tokens in sources or git; use Keychain, xcconfig (not in VCS), CI secrets.
+- Debug-only ATS / SSL bypass — `#if DEBUG` only and never in Release.
+
+## ATS and networking
+
+- ATS exceptions in Info.plist — minimal, with rationale; prefer HTTPS.
+- Certificate pinning — only if already adopted in the repo.
+
+## PII and logs
+
+- Do not log tokens, passwords, full card/document numbers.
+- Crash/APM: scrub PII per repo policy.
+
+## Keychain / biometrics
+
+- Accessibility levels and `kSecAttrAccessible` — intentional; Face ID/Touch ID — via LocalAuthentication as in the repo.
+
+## Agent requirement
+
+For auth/forms/payments — check this rule and `code-review-mr.md`. Involve security-reviewer for sensitive features.

package/presets/mavis/ios-swift/rules/state-and-viewmodels.md

@@ -0,0 +1,37 @@
+# General principles
+
+- ViewModel is the **single orchestration point** for a screen: load, submit, validation, navigation intents.
+- Store and expose to the View **domain models** and UI-specific state (loading, error message, selected tab).
+- `@MainActor` on ViewModel; heavy work — in use case / repository (`async`); do not block the main thread.
+- Unidirectional flow: View → intent → ViewModel → use case → state update → View.
+
+# State
+
+- Explicit enum or struct for UI state where appropriate:
+  - `idle`, `loading`, `loaded(Data)`, `failed(Error)` — or the repo’s analog.
+- Avoid many unsynchronized `@Published` flags when one enum covers the scenario.
+- `@Observable` / `ObservableObject` — as in the project; do not mix styles in one feature without reason.
+
+# Use cases and repositories
+
+- ViewModel depends on **protocols** (`LoadOrdersUseCase`, `OrderRepository`), not `*RepositoryImpl`.
+- One use case — one business operation; do not inflate ViewModels to hundreds of lines — extract use cases into Domain.
+- Caching and offline — in repository/Data, not in ViewModel.
+
+# Side effects
+
+- Analytics, haptics, deep links — via injected services or a middleware pattern, not hardcoded singletons.
+- `Task` in ViewModel: cancel on `deinit` / `onDisappear` when needed (`task(id:)`, store `Task?` with cancel).
+
+# Testability
+
+- ViewModel initializer takes protocols (DI); no hidden network/DB singletons.
+- Cover business branches with unit tests using mock use cases.
+
+# Agent requirement
+
+When creating a ViewModel:
+- Do not call `URLSession` / API client directly.
+- Do not parse JSON or declare DTOs in the ViewModel.
+- Naming: `FeatureViewModel`, methods as verbs (`loadOrders()`, `submitOrder()`).
+- Follow the style of existing ViewModels in the same feature.

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

@@ -0,0 +1,55 @@
+# Naming and API design
+
+- Types: `UpperCamelCase`; methods, properties, enum cases: `lowerCamelCase`.
+- Protocols that describe a capability: `-able`, `-ing`, or `Protocol` suffix — as in the repo.
+- Avoid abbreviations in names except common ones (URL, ID, HTTP).
+
+# Optionals and errors
+
+```swift
+// ❌ Bad
+let name = user!.name
+
+// ✅ Good
+guard let name = user?.name else { return }
+```
+
+- `throws` + typed errors instead of `Result` where that is the layer convention; stay consistent within a module.
+- `guard` for early exit; do not nest deep `if let` pyramids.
+
+# Concurrency
+
+- UI types — `@MainActor`.
+- Shared mutable state — `actor` or isolation via a queue; document thread expectations.
+- `Task { }` in ViewModel: account for cancellation; `[weak self]` in escaping closures when retain cycles are possible (default when capturing `self` in escaping work).
+- Prefer `async/await` over completion handlers for new code.
+
+## Anti-hallucination (Swift / concurrency)
+
+| ❌ Avoid | ✅ Prefer |
+|---------|----------|
+| Force unwrap (`!`) for normal control flow | `guard let` / `if let` / typed throws |
+| Invented Combine/Rx APIs when the feature uses Swift Concurrency | Match neighboring ViewModels (`async/await`, `@MainActor`) |
+| Unstructured `Task {}` without cancellation awareness | Cooperative cancel; prefer `.task` in Views (`swiftui-ui.md`) |
+| Global mutable singletons for request state | DI / actors / existing composition root |
+| APIs not available for the project’s Swift / iOS deployment target | Check package / Xcode settings; mark `VERIFY` if unsure |
+
+# Access control
+
+- Minimum necessary level: `private` / `fileprivate` by default for implementation details.
+- Feature public API — explicit types and protocols; do not export DTOs outside the module.
+
+# Value semantics
+
+- Prefer `struct` for models and state where there is no identity semantics.
+- `class` — when identity, inheritance, or Objective-C interop is required.
+
+# Extensions
+
+- Group extensions by type; do not dump unrelated helpers into one unstructured `Extensions.swift`.
+- Protocol extensions for shared default behavior.
+
+# Agent requirement
+
+- Style gate: **SwiftLint** (and SwiftFormat when configured) — prefer fixing lint over prose style essays; `// swiftlint:disable` only with an explicit reason.
+- New code — Swift Concurrency-ready (`Sendable` where the project compiler/linter requires it).

package/presets/mavis/ios-swift/rules/swiftui-ui.md

@@ -0,0 +1,63 @@
+# General View rules
+
+- **SwiftUI** preferred; UIKit only by repo convention (wrapper, legacy).
+- Views must be **thin**:
+  - render state from the ViewModel;
+  - delegate actions through ViewModel methods/closures;
+  - contain no business logic, DTO mapping, or network calls.
+- Before a new custom control — look for a component in `DesignSystem/` or existing features.
+- Extract repeated UI logic into `ViewModifier`, `@ViewBuilder` helpers, or subviews.
+
+# ViewModel and binding
+
+- ViewModel — `@MainActor`, `@Observable` (iOS 17+) or `ObservableObject` — as adopted in the project.
+- The View reads state and calls **explicit ViewModel methods** (`submit()`, `load()`); it does not mutate internal state directly.
+- For navigation — coordinator/router or a route enum in the ViewModel, not scattered `NavigationLink`s with business conditions in the View.
+
+# Lifecycle, ownership, hit testing
+
+- Prefer **`.task(id:)`** (auto-cancel) over `.onAppear { Task { … } }` for async loads tied to the view lifetime.
+- `@StateObject` / owned observable — **only where the view owns** the instance; prefer DI / parent-injected ViewModels over `@EnvironmentObject` sprawl.
+- Shared mutable services — `actor` (or existing isolation); default `[weak self]` in escaping closures that capture ViewModel/`self`.
+- Transparent stacks that should receive taps: `.contentShape(Rectangle())`.
+- High-frequency visual updates — prefer `TimelineView` (or repo pattern) over ad-hoc `Timer` in Views.
+
+# File structure
+
+For a feature screen:
+- `FeatureView.swift` — subview composition.
+- `FeatureViewModel.swift` — state + intents.
+- `FeatureView+Subviews.swift` — for a large tree (optional).
+- `FeatureRoute.swift` — navigation (when used).
+
+For a Design System component:
+- Folder `ComponentName/`:
+  - `ComponentName.swift`
+  - `ComponentName+Preview.swift` (optional)
+  - `ComponentNameStyle.swift` — styles/variants (optional)
+
+# Styles and Design System
+
+- Colors, fonts, spacing — from project **tokens/Theme** (`DesignSystem`, `Assets`, generated tokens).
+- Avoid:
+  - “magic” literals (`.padding(17)`, `Color(red: 0.2, ...)`) when tokens exist;
+  - duplicating styles already covered by primitives.
+- `Preview` — for components and screens with a mock ViewModel.
+
+# Accessibility
+
+- Interactive elements: meaningful `accessibilityLabel`, `accessibilityHint` where needed.
+- For UI tests — stable `accessibilityIdentifier` on key elements (align with `tests-ui.md`).
+- Support Dynamic Type and contrast; do not break layout at large text sizes.
+
+# Previews and localization
+
+- UI strings via `String(localized:)` / `LocalizedStringKey`, not hardcoded in production without reason.
+- `#Preview` with realistic mock data; for ViewModels — stub use cases.
+
+# Agent requirement
+
+When creating/changing UI:
+- Follow existing screens and components as the reference.
+- Do not import the Data layer into View/ViewModel.
+- Extract a subview when body exceeds ~40–60 lines or repeats.

package/presets/mavis/ios-swift/rules/technical-retro.md

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

@@ -0,0 +1,37 @@
+# UI test structure
+
+- UI Test target: `*UITests/` — end-user flow scenarios.
+- Page Object (or Screen Object) — one class per screen: selectors + actions (`LoginScreen`, `OrderHistoryScreen`).
+- Shared helpers — `UITestSupport/`, base classes, launch arguments.
+
+# Selectors and stability
+
+- **Priority:** `accessibilityIdentifier` for key elements; then label/trait where stable.
+- Align identifiers with the Presentation layer (`swiftui-ui.md`): `{screen}__{element}`.
+  - Example: `order-history__submit-button`, `login__email-field`.
+- Avoid absolute coordinates and brittle XPath-like chains.
+
+# Scenarios and naming
+
+- Test names — **in the product locale** (Russian when UI copy is Russian), with an entity prefix:
+  <!-- i18n-keep: E5 -->
+  - `OH-001 Отображается список заказов` (prefix — entity initials, number — three digits).
+- One test — one user scenario; do not combine unrelated checks.
+
+# Launch and environment
+
+- `-UITesting`, mock server URL, state reset — via `launchArguments` / `launchEnvironment`, as in the repo.
+- Do not depend on production backend in CI; use staging/mock.
+
+# Sync with UI
+
+- When UI changes, update identifiers in Views and selectors in page objects.
+- Do not weaken assertions against business expectations just to keep CI green.
+
+# Agent requirement
+
+When adding UI tests:
+- Reuse page objects; do not duplicate queries in every test.
+- Add `accessibilityIdentifier` in SwiftUI via `.accessibilityIdentifier(...)` for new interactive elements.
+- Follow existing UITest files as the reference.
+- Planning / generation / heal — agents `xcuitest-test-{planner,generator,healer}` and skill `xcuitest-e2e` (not Playwright).

package/presets/mavis/ios-swift/rules/tests-unit.md

@@ -0,0 +1,35 @@
+# General testing rules
+
+- **Framework** — XCTest or Swift Testing, as in the project.
+- Goal: verify **behavior and business rules**, not implementation details and private API.
+- Naming:
+  - `test` / `@Test` descriptions and `XCTContext` — **in the product locale** (Russian when UI copy is Russian), as clear business phrases.
+  - Descriptions **start with a capital letter**.
+
+# ViewModel and use case
+
+- Mock repository / use case protocols; do not hit the real network.
+- Assert state transitions: loading → success/failure, validation errors, edge cases.
+- Test `@MainActor` ViewModels with `@MainActor` test methods or `await MainActor.run`.
+
+# Mappers and domain
+
+- Mapper functions — unit tests with case tables: nil fields, empty arrays, boundary values.
+- Regressions on business rules (discounts, statuses, date formatting).
+
+# Isolation
+
+- Do not mock the subject under test (e.g. the mapper itself when testing the mapper).
+- Fixtures — in `TestSupport/`, `Mocks/`, or colocated per repo convention; do not inline large JSON without need.
+
+# File structure
+
+- `FeatureViewModelTests.swift`, `OrderMapperTests.swift` — `Tests` suffix on type/file name per Xcode style.
+- Do not create deep `Tests/Tests/` nesting; follow the project target structure.
+
+# Agent requirement
+
+When adding tests:
+- Copy patterns from existing test files in the repo.
+- Add tests for new logic branches and regressions.
+- Use DTO fixtures from the Data layer and domain types from Domain; do not duplicate types in tests.

package/presets/mavis/ios-swift/rules/ux-design.md

@@ -0,0 +1,99 @@
+<!-- shared-core: review/ux-design.md -->
+
+# UX design checklist
+
+On-demand behavioral UX checklist (IA, named flows, state matrix). **Procedure:** skill `ux-design`. **Producer:** `task-analyst` (not a pipeline agent). Do not inline this checklist into the analyst prompt.
+
+Stack-agnostic: no app-source globs, Playwright, or `xcodebuild`. Form-factor **examples** live in adapter **Stack notes** only.
+
+## When to load
+
+- Standalone `/task` intent `ux-design` (modes `synthesize` | `review`; profile `light`; steps only `task-analyst`)
+- Embedded on a UI-capable stack when **required-signal** or advisory UI AC fires on `feature` / `refactor` / `spike` / `spec-gen`
+- Required-signal (any one): the user asked for UX, **or** AC explicitly require flows/states, **or** intent is `spec-gen` / `/spec-start` for a **page/feature**. Else **advisory** (notes only; skip if no UI surface)
+- **Do not** load for backend-only AC even on a UI stack. Classify `mockup-review` (Figma) before `ux-design` before `review-only`
+
+## Inputs
+
+1. Task `artifact-manifest.json`, then prompt / `brief.md` / `decomposition.md` when present
+2. Skill `ux-design` + this rule
+3. Approved `docs/specs` only as product-behavior SoT **after** UX synthesis maps via Spec feed — do not write INDEX here
+
+## Forbidden Figma MCP
+
+Do **not** call Figma MCP. Only `mockup-reviewer` reads Figma. Forbidden by name: `get_metadata`, `get_design_context`, `get_screenshot`, `search_design_system`, `get_variable_defs`, `use_figma`, `create_new_file`, `generate_*`.
+
+When `figma.com` is present and required-signal fires, emit a **thin** `ux-design.md` from AC only (IA/flows the mockup must cover; no visual or DS claims). If the user only pasted a URL and AC are visual, the UX file may be omitted; `mockup-review.md` coverage stands.
+
+Do **not** write BMAD-style `DESIGN.md` or a second visual spine. One experience artifact: `ux-design.md`.
+
+## Modes
+
+| Mode | When |
+|------|------|
+| `synthesize` | Design UX from a brief/AC (standalone «разработай UX» / embedded required-signal) | <!-- i18n-keep: E4 -->
+| `review` | Critique a brief/wireframe/description **without** Figma («ревью UX»). Figma + review-not-implement remains intent `mockup-review` | <!-- i18n-keep: E4 -->
+
+## Required vs advisory
+
+- **Required** when required-signal fires (user-asked-ux / ac-requires-flows-states / spec-gen-page-feature)
+- **Advisory** otherwise (UI AC without those signals). Advisory `INCOMPLETE` → notes only; DoR may complete
+- Skip the skill when there is no UI surface or the prompt is empty of UX-relevant AC
+
+## Verdicts
+
+`PASS` | `PASS_WITH_NOTES` | `INCOMPLETE`. Never copy the mockup FAIL-only hook (`changes_requested` + do-not-retry-developer). Incomplete UX is an analyst/DoR problem.
+
+| Verdict | Required step | Advisory step | Standalone intent `ux-design` |
+|---------|---------------|---------------|-------------------------------|
+| `PASS` / `PASS_WITH_NOTES` | Analysis may complete DoR | Analysis may complete | `completed` |
+| `INCOMPLETE` | DoR **not** met: `open_questions` / blocked analysis; existing `after:task-analyst` gate | Notes only; DoR may complete | `completed` (report-only) |
+
+**Block (`INCOMPLETE` as DoR failure) only when the step was required and primary flows *or* the empty/error/loading matrix are missing.** Isolated missing microcopy or optional protagonist names never block.
+
+## Surface-closure
+
+Each stated need → a surface; each surface → a flow that lands there. If closure fails, list probes under **Open probes** — **do not invent** screens, flows, or copy to fill gaps.
+
+## Spec feed
+
+Analyst remains the **only** writer of `docs/specs` INDEX and page/feature files. Map `ux-design.md` → templates **after** UX synthesis (UX before `spec-authoring` author mode):
+
+| `ux-design.md` heading | Page template | Feature template |
+|------------------------|---------------|------------------|
+| Scope + IA | **Overview** | **Overview** |
+| Entry / actors | **Entry / actors** | — (page-level) |
+| Primary flows | **Primary flows** | **Shared behavior / constraints** when a flow is cross-page |
+| States | **States** (loading/empty/error/success) | **Cross-cutting states** when shared |
+| Interaction notes + microcopy direction | Inform **Acceptance criteria**; leftover → **Edge cases** | Shared constraints |
+| Accessibility floor (behavioral) | Testable AC without pixels; else Edge cases | Shared constraints |
+| Surface-closure probes | Analyst `open_questions` — **do not** invent spec rows | Same |
+
+## Manifest
+
+When produced, append `ux-design.md` to the **`analysis`** entry `authoritativePaths` and `evidencePaths`. Do **not** add a new default producer row for v1 (`ux-designer` is deferred).
+
+## Report headings
+
+Write `ux-design.md` with these headings (must match the architecture artifact contract):
+
+```markdown
+# UX design: <slug>
+## Mode
+synthesize | review
+## Verdict
+PASS | PASS_WITH_NOTES | INCOMPLETE
+## Scope
+- Form factor: web | ios | android | mixed
+- Figma present: yes | no
+- Required-signal: user-asked-ux | ac-requires-flows-states | spec-gen-page-feature | advisory
+## Information architecture
+## Entry / actors
+## Primary flows
+## States
+## Interaction notes
+## Microcopy direction
+## Accessibility floor (behavioral)
+## Spec feed
+## Open probes
+```

package/presets/mavis/ios-swift/rules/xcode-tooling.md

@@ -0,0 +1,15 @@
+# Xcode tooling (terminal)
+
+Before **`xcodebuild` / `swift build` / `swift test` / SwiftLint / SwiftFormat / `simctl`**, detect the repository toolchain and **use only it**.
+
+## How to detect
+
+1. **Workspace / project:** `.xcworkspace` (CocoaPods) → workspace; else `.xcodeproj`; SPM-only — `Package.swift`.
+2. **Scheme / destination:** as in CI, `Makefile`, `fastlane`, `scripts/` — do not guess.
+3. **Lint:** `.swiftlint.yml` / `SwiftLint` on PATH or Mint/mise — if there is no config, do not run a foreign lint.
+4. **Format:** `.swiftformat` / SwiftFormat — only if adopted in the repo.
+5. **Simulator:** `xcrun simctl list` + destination from CI; do not hardcode UDID.
+
+Examples: `xcodebuild -scheme App -destination 'platform=iOS Simulator,name=iPhone 16' build`, `swiftlint lint --quiet`, `swiftformat . --lint`.
+
+Long builds and DerivedData are normal; do not block `xcodebuild`/`simctl`/`xcrun` with the shell guard.

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

@@ -0,0 +1,18 @@
+# `.mavis/skills` (preset ios-swift)
+
+| Skill | Purpose |
+|-------|---------|
+| `feature-delivery` | Domain → Data → VM → View → tests → post-change-build |
+| `spec-authoring` | Author or bootstrap docs/specs (INDEX, page/feature templates); `/spec-start` / analyst author mode |
+| `spec-discovery` | Opt-in research-before-spec in analyst author mode (claim ledger; not default `/task` consume) |
+| `mockup-review` | Figma mockup review: DS, coverage, viewports (standalone or embedded) |
+| `ux-design` | Behavioral UX synthesis/review via task-analyst (standalone or embedded; no Figma MCP) |
+| `code-review` | iOS MR checklist |
+| `unit-testing` | XCTest / Swift Testing |
+| `xcuitest-e2e` | XCUITest plan/generate/heal (← next `playwright-e2e`) |
+| `debug-investigation` | Runtime evidence before fix |
+| `ci-investigation` | iOS CI red |
+| `technical-retro` | Retro facilitation |
+| `write-adr` | Architecture Decision Record (context / decision / consequences) |
+
+Copied to `.mavis/skills/` on init.