@bonesofspring/ai-rules 0.2.17 → 0.2.19

package/presets/cursor/android-kotlin/rules/product-specs-authoring.mdc

@@ -11,6 +11,8 @@ alwaysApply: false
 
 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`).
@@ -84,7 +86,7 @@ Compliant = valid frontmatter + all required headings present (non-empty prose o
 
 ## Templates & assets
 
-**Package SoT:** `packages/ai-rules/presets/_shared/assets/docs-specs/` (`INDEX.md` stub, `_templates/page.md`, `_templates/feature.md`; optional `schemas/frontmatter-v1.schema.json`).
+**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.
 
@@ -94,7 +96,7 @@ Compliant = valid frontmatter + all required headings present (non-empty prose o
 
 | Role | Responsibility |
 |------|----------------|
-| **task-analyst** | Primary author (Generate + Bootstrap); INDEX bootstrap; brief **Related specs** + **Spec gaps / generation requested**; loads this stem + skill `spec-authoring` |
+| **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 |
@@ -113,8 +115,8 @@ Block handoff via `open_questions` until fixed:
 
 - `product-specs` — discovery / consume
 - Skill `spec-authoring` — procedural checklist
-- Optional consumer script `scripts/check-product-specs.sh` (WARN default; `--strict` FAIL)
-
+- 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`
 
 ## Stack notes
 

package/presets/cursor/android-kotlin/rules/product-specs.mdc

@@ -13,6 +13,8 @@ Product page/feature **behavior** specs live under the consumer repo `docs/specs
 
 **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 |
@@ -20,19 +22,21 @@ Product page/feature **behavior** specs live under the consumer repo `docs/specs
 | **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** → it is the **required discovery path** for work that touches a listed page, feature, route, or alias.
+- 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.
+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 optional domain `feature.md` when the INDEX or page Related links it).
+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)
 
@@ -54,10 +58,10 @@ Same-changeset INDEX updates, frontmatter v1, required body headings, templates,
 ## 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.
 
-
 ## Stack notes
 
 - `routes`: deep links / screen ids. `ui` / `store`: feature presentation / ViewModel (`features/**` or `features/<name>/impl/**/presentation/`) — **not** web `app/src/ui` or iOS `Features/**`. `e2e`: instrumentation test paths.

package/presets/cursor/android-kotlin/rules/ux-design.mdc

@@ -0,0 +1,108 @@
+---
+description: Behavioral UX design checklist (IA, flows, states). On-demand — load via task-analyst / skill ux-design.
+alwaysApply: false
+---
+
+<!-- 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
+```
+
+## Stack notes
+
+Form-factor **android**: navigation chrome, system back, TalkBack / font-scale intent. Same `ux-design.md` schema as web; put sw/window-size examples here only — do not FAIL on exact dp.

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

@@ -3,6 +3,10 @@
 | 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` | Android MR checklist |
 | `unit-testing` | JUnit 4/5 (repo default) |
 | `instrumentation-ui-e2e` | Android instrumentation plan/generate/heal (← next `playwright-e2e`) |

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

@@ -26,6 +26,14 @@ Write `ci-report.md` under the task slug folder (`.cursor/team/tasks/<slug>/`):
 - `resolved: true|false`
 - Validation commands and results
 
+
+## MCP usage
+
+Load requestable rule `mcp-usage` when verifying third-party library APIs (Context7) or when a local overlay MCP is present and the task fits. Discover tools at runtime; do not invent schemas. Overlay absence is not a blocker unless the user required that MCP as source of truth.
+
+If a Sentry/Datadog (or similar) MCP is ready and the task is a production error, event, or trace, use it. Do not invent telemetry.
+
+
 ## Handoff Rules
 
 - Config-only or one-line fixes → fix in place, re-run check.

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

@@ -29,6 +29,14 @@ Upsert the owned terminal receipt in `artifact-manifest.json` when complete; do
 
 Do not use browser e2e tooling — this is an Android Studio / AGP stack.
 
+
+## MCP usage
+
+Load requestable rule `mcp-usage` when verifying third-party library APIs (Context7) or when a local overlay MCP is present and the task fits. Discover tools at runtime; do not invent schemas. Overlay absence is not a blocker unless the user required that MCP as source of truth.
+
+If a Sentry/Datadog (or similar) MCP is ready and the task is a production error, event, or trace, use it. Do not invent telemetry.
+
+
 ## Design guidance
 
 - Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.

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

@@ -19,6 +19,9 @@ description: Delivers Android Kotlin/Jetpack Compose features end-to-end across
 - **Don't** invent alternate architecture or persistence stacks (e.g. MVI frameworks, Room vs SQLDelight) unless the repo already uses them.
 - **Don't** use yarn, browser e2e, or `app/src` paths — wrong stack.
 
+- If the prompt or brief contains a `figma.com` URL, load requestable skill `mockup-review` and do not start UI work until the mockup-reviewer step is completed or the user continued past FAIL/`BLOCKED_MCP`.
+- When required-signal (user asked UX, AC require flows/states, or spec-gen page/feature) and **no** `figma.com` URL: `ux-design.md` must exist on the analysis manifest entry (verdict not `INCOMPLETE`) before UI work. If missing, **blocked** — hand back to `task-analyst`. Parallel to the mockup gate when Figma exists.
+
 ## Scope discipline
 
 Implement only the current AC / decomposition task. Clarify ambiguity before coding; do not add unrelated hardening, polish, or drive-by refactors. See `feature-developer` → **Zero improvisation**.
@@ -31,6 +34,12 @@ When editing **ai-rules android-kotlin preset** sources (agents, hooks, rules) r
 
 Summarize by layer, validation results, and known gaps. Agent team: upsert the owned terminal receipt in `artifact-manifest.json`; do not mutate `status.json`.
 
+
+## MCP usage
+
+Load requestable rule `mcp-usage` when verifying third-party library APIs (Context7) or when a local overlay MCP is present and the task fits. Discover tools at runtime; do not invent schemas. Overlay absence is not a blocker unless the user required that MCP as source of truth.
+
+
 ## Design guidance
 
 - Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.

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

@@ -0,0 +1,29 @@
+---
+name: mockup-review
+description: Reviews a Figma mockup for design-system compliance, feature coverage, and viewport matrix via Figma MCP. Use for standalone mockup-review intent or when a feature/refactor/spike/spec-gen task includes a figma.com URL.
+---
+
+# Mockup review
+
+Requestable procedure for agent `mockup-reviewer`. Checklist lives in rule `mockup-review` — do not duplicate it here.
+
+## When to run
+
+- Standalone `/task` intent `mockup-review` (report-only; profile `light`; steps only `mockup-reviewer`).
+- Embedded: `feature` / `refactor` / `spike` / `spec-gen` whose prompt or `brief.md` contains a `figma.com` URL on a UI stack — after `task-analyst` (when present), before architect and developer.
+
+## MCP OAuth preflight
+
+Confirm Figma MCP is configured (see `MCP.md`). Do not ship secrets. If MCP is down or auth fails, write `mockup-review.md` with verdict `BLOCKED_MCP` and receipt `blocked`. Do not invent DS claims. Embedded skip-forward is `/task-continue` (explicit «proceed without MCP»).
+
+## Plugin skills
+
+If plugin skills `figma-design-to-code` / `figma-use` are installed, load them for MCP invocation recipes; do not paste their bodies; do not run design-to-code. Preset owns the checklist, agent, and routing; plugin owns MCP recipes.
+
+## Load the checklist
+
+Load requestable rule `mockup-review` and follow its review dimensions, node caps, and report headings.
+
+## Output
+
+Write `.cursor/team/tasks/<slug>/mockup-review.md` and upsert manifest entry id `mockup-review` (producer `mockup-reviewer`). Receipt mapping is in the agent prompt.

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

@@ -0,0 +1,58 @@
+---
+name: spec-discovery
+description: Opt-in research-before-spec for task-analyst author mode. 11 named methods plus a mandatory claim ledger. Use when the user or AC asks discovery before generating docs/specs — not default /task consume.
+---
+
+# Spec discovery
+
+Requestable — **not** always-on. Load **only** in **task-analyst author mode** when the user or AC asks research-before-spec (including `/spec-start` with that intent). Never default consume `/task`. Not a pipeline step.
+
+Load **`product-specs`** (and **`product-specs-authoring`** after this skill if authoring follows). Do **not** invent product behavior. Do **not** create a second spec-file tree.
+
+## Load policy
+
+1. Pick a **subset** of methods that fit the task — not all 11 every time.
+2. **`claim-ledger` is mandatory** whenever this skill runs.
+3. Write chronological notes to `.cursor/team/tasks/<slug>/.memlog.md` (append-only). Do **not** mutate `status.json` / `metrics.json`.
+4. Discovery output lives in memlog + `brief.md` sections. Then hand off to skill **`spec-authoring`** (or stop if `specMode: none`).
+
+Backend / MCP stacks: skip UI-only examples; prefer `analog-scan`, `code-archaeology`, `problem-define`, `assumption-audit`, `claim-ledger`.
+
+## Methods
+
+| Method | Produces | Skip when |
+|--------|----------|-----------|
+| **intake-capture** | Raw idea, origin, first unknowns → memlog + brief Research inputs | User prompt + AC already complete |
+| **index-locator** | Related INDEX rows + linked spec paths + gaps | `specMode: none` or INDEX absent without consume intent |
+| **code-archaeology** | Observed behavior labeled `inferred`/`draft` with path citations | Greenfield with no relevant code |
+| **research-pack-scan** | Claims from `team/tasks/<slug>/research/**` or user-supplied paths | No research paths cited |
+| **evidence-against** | Reasons the idea may fail | Internal spike with no product/external risk |
+| **problem-define** | Who hurts, goals, non-goals, cost of inaction → brief | Brief Goal + Out of scope already exhaustive |
+| **concept-shape** | 2–3 approach options + appetite (small/medium/large); no API design | `architecture.md` exists or one obvious path |
+| **working-backwards-check** | Headline + 5 customer objections + verdict `forged` / `needs-heat` / `cracked` | Consume mode with approved specs |
+| **assumption-audit** | Assumption register → brief Assumptions + `open_questions` | Never skip in author mode (keep lightweight) |
+| **analog-scan** | 2–3 repo analogs via `reference-features` / code search | No plausible analog |
+| **claim-ledger** | Markdown table `source → claim` for every product-behavior claim | **Never skip** when this skill is loaded |
+
+## Claim ledger (required)
+
+Block spec authoring until every product-behavior claim has a source:
+
+```markdown
+| Source | Claim |
+|--------|-------|
+| brief AC-3 | Checkout shows empty cart copy |
+| code-archaeology inferred | Empty state uses an illustration |
+```
+
+Sources: AC / user / UI copy / labeled code inference / research path. Unsourced claims → `open_questions`.
+
+## Memlog
+
+Path: `.cursor/team/tasks/<slug>/.memlog.md`. Chronological `## YYYY-MM-DD` headings. Optional tags: `decision`, `assumption`, `override`, `event`, `claim`.
+
+## Forbidden
+
+- 108-technique catalogs, HTML composers, party-mode, five `assess.*` slash commands, Python memlog runtime.
+- Dummy INDEX rows when `specMode: none`.
+- Dumping the whole `docs/specs/**` tree — locator is INDEX → linked page + optional `feature.md`.

package/presets/cursor/android-kotlin/skills/ux-design/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: ux-design
+description: Behavioral UX synthesis and review for task-analyst. Modes synthesize|review. Standalone intent ux-design or embedded required-signal / advisory UI AC. No Figma MCP; no DESIGN.md.
+---
+
+# UX design
+
+Requestable procedure for **task-analyst** (not a pipeline agent). Checklist lives in rule `ux-design` — do not duplicate it here.
+
+**Not** a Figma workflow: do not call Figma MCP; do not write `DESIGN.md`. Visual/DS/viewport audit stays with `mockup-reviewer` / skill `mockup-review`.
+
+## When to run
+
+- Standalone `/task` intent `ux-design` (report-only; profile `light`; steps only `task-analyst`; modes `synthesize` | `review`; `humanGates: []`).
+- Embedded: `feature` / `refactor` / `spike` / `spec-gen` on a UI stack when required-signal or advisory UI AC fires — inside the analyst step (no new pipeline agent). Required-signal: user asked UX, or AC require flows/states, or spec-gen page/feature.
+
+## Modes
+
+- `synthesize` — elicit IA, named primary flows, empty/error/loading matrix from the brief/AC.
+- `review` — critique a brief/wireframe/description **without** Figma. A `figma.com` URL with review-not-implement language is intent `mockup-review`, not this skill.
+
+## Order
+
+UX synthesis **before** skill `spec-authoring` / author mode when both apply. Analyst remains the only INDEX writer. Map headings via the rule's Spec feed table; do not paste the whole UX file into `docs/specs`.
+
+## Forbidden Figma MCP
+
+Do not call `get_metadata`, `get_design_context`, `get_screenshot`, `search_design_system`, `get_variable_defs`, `use_figma`, `create_new_file`, `generate_*`. Only `mockup-reviewer` reads Figma.
+
+## Load the checklist
+
+Load requestable rule `ux-design` and follow its required-signal vs advisory rules, forbidden MCP list, verdicts, surface-closure, and report headings.
+
+## Output
+
+Write `.cursor/team/tasks/<slug>/ux-design.md` and append that path to the **`analysis`** manifest entry (`authoritativePaths` / `evidencePaths`). Do **not** create a new producer row. Receipt stays on `analysis`: required `INCOMPLETE` (missing primary flows or empty/error/loading matrix) → DoR not met; advisory `INCOMPLETE` → notes only. Never copy the mockup FAIL-only hook.

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

@@ -13,6 +13,7 @@ Artifact directory for the Android agent-team pipeline.
     status.json
     brief.md
     decomposition.md
+    .memlog.md
     …
 ```
 
@@ -34,6 +35,13 @@ Artifact directory for the Android agent-team pipeline.
 
 Bootstrap `tasks/<slug>/` by **writing** artifacts (Write tool), not Shell `mkdir`. Cursor sandbox → `Operation not permitted` otherwise (worse on Desktop/Documents).
 
+
+## specMode, applyReadiness, memlog
+
+- **`specMode`:** `consume` | `generate` | `none` — primary in `brief.md` `## Spec mode`; optional top-level `pipeline.json` `specMode`. `none` skips INDEX/author mode (spike/research).
+- **`applyReadiness`:** YAML frontmatter on developer `implementation.md`; JSON-shaped `{ "state": "blocked"|"ready"|"all_done", "contextFiles": [] }` on the analyst receipt (analyst may emit `blocked` pre-gate). See `agent-artifact-contracts`.
+- **Memlog:** `.cursor/team/tasks/<slug>/.memlog.md` (Claude: `.claude/team/tasks/<slug>/.memlog.md`) — append-only, agent-written; `/task-continue` may read. Hook does not parse it. Example: `fixtures/memlog.example.md`.
+
 ## Artifact manifest and receipts
 
 Each slug stores one context index at `.cursor/team/tasks/<slug>/artifact-manifest.json`. Schema v1 is defined by shared core `agent-team/agent-artifact-contracts.md`: every entry declares its producer, status, authoritative paths, acceptance-criteria IDs, decomposition task IDs, timestamps, and a terminal completion receipt.

package/presets/cursor/android-kotlin/team/fixtures/artifact-manifest.example.json

@@ -0,0 +1,25 @@
+{
+  "schemaVersion": 1,
+  "slug": "example-mockup-review",
+  "updatedAt": "2026-07-31T12:05:45.000Z",
+  "artifacts": [
+    {
+      "id": "mockup-review",
+      "producer": "mockup-reviewer",
+      "status": "completed",
+      "authoritativePaths": ["mockup-review.md"],
+      "acceptanceCriteriaIds": ["AC-4", "AC-5", "AC-6", "AC-7", "AC-8"],
+      "taskIds": [],
+      "timestamps": {
+        "createdAt": "2026-07-31T12:05:30.000Z",
+        "updatedAt": "2026-07-31T12:05:45.000Z",
+        "completedAt": "2026-07-31T12:05:45.000Z"
+      },
+      "receipt": {
+        "outcome": "completed",
+        "summary": "Mockup review completed with verdict PASS_WITH_NOTES.",
+        "evidencePaths": ["mockup-review.md"]
+      }
+    }
+  ]
+}

package/presets/cursor/android-kotlin/team/fixtures/feature-full.json

@@ -1,6 +1,7 @@
 {
   "slug": "example-feature-full",
   "intent": "feature",
+  "specMode": "consume",
   "profile": "full",
   "summary": "Multi-layer feature with Android instrumentation coverage",
   "steps": [

package/presets/cursor/android-kotlin/team/fixtures/feature-with-figma-url.json

@@ -0,0 +1,17 @@
+{
+  "slug": "example-feature-with-figma",
+  "intent": "feature",
+  "profile": "full",
+  "summary": "Feature with Figma mockup URL — mockup-reviewer after analyst, before architect and developer",
+  "steps": [
+    { "agent": "task-analyst", "label": "Clarify and decompose" },
+    { "agent": "mockup-reviewer", "label": "Figma mockup review", "model": "strong" },
+    { "agent": "solution-architect", "label": "Design boundaries", "model": "strong" },
+    { "agent": "feature-developer", "label": "Implement" },
+    { "agent": "build-verifier", "label": "Validation gate", "model": "cheap" },
+    { "agent": "code-reviewer", "label": "Code review", "model": "cheap" }
+  ],
+  "humanGates": ["after:task-analyst"],
+  "autoChain": true,
+  "skipped": []
+}

package/presets/cursor/android-kotlin/team/fixtures/feature-with-ux-no-figma.json

@@ -0,0 +1,17 @@
+{
+  "slug": "example-feature-with-ux-no-figma",
+  "intent": "feature",
+  "profile": "standard",
+  "summary": "Feature with required-signal UX and no Figma URL — task-analyst loads skill ux-design; no mockup-reviewer step",
+  "steps": [
+    { "agent": "task-analyst", "label": "Clarify, UX design, decompose" },
+    { "agent": "feature-developer", "label": "Implement" },
+    { "agent": "build-verifier", "label": "Validation gate", "model": "cheap" },
+    { "agent": "code-reviewer", "label": "Code review", "model": "cheap" }
+  ],
+  "humanGates": ["after:task-analyst"],
+  "autoChain": true,
+  "skipped": [
+    { "agent": "mockup-reviewer", "reason": "No figma.com URL; analyst skill ux-design covers behavioral UX" }
+  ]
+}

package/presets/cursor/android-kotlin/team/fixtures/memlog.example.md

@@ -0,0 +1,9 @@
+# Memlog example
+
+Append-only. Agents write; `/task-continue` may read. The hook does not parse this file.
+
+## 2026-08-13
+
+- `decision`: specMode=generate; research-before-spec requested
+- `claim`: empty-cart copy lives in the empty-state handler (code-archaeology, inferred)
+- `assumption`: no guest checkout in v1

package/presets/cursor/android-kotlin/team/fixtures/mockup-review-fail-embedded-status.json

@@ -0,0 +1,8 @@
+{
+  "slug": "example-mockup-fail-gate",
+  "state": "awaiting_approval",
+  "currentAgent": "mockup-reviewer",
+  "awaitingHumanGate": true,
+  "retryAfterFix": null,
+  "note": "Embedded mockup FAIL: hook must NOT set retryAfterFix to feature-developer. Resume only via /task-continue."
+}

package/presets/cursor/android-kotlin/team/fixtures/mockup-review-standalone.json

@@ -0,0 +1,14 @@
+{
+  "slug": "example-mockup-review-standalone",
+  "intent": "mockup-review",
+  "profile": "light",
+  "summary": "Standalone Figma mockup review (report-only)",
+  "steps": [
+    { "agent": "mockup-reviewer", "label": "Figma mockup review", "model": "strong" }
+  ],
+  "humanGates": [],
+  "autoChain": true,
+  "skipped": [
+    { "agent": "feature-developer", "reason": "Standalone mockup-review is report-only" }
+  ]
+}

package/presets/cursor/android-kotlin/team/fixtures/ux-design-standalone.json

@@ -0,0 +1,15 @@
+{
+  "slug": "example-ux-design-standalone",
+  "intent": "ux-design",
+  "profile": "light",
+  "summary": "Standalone behavioral UX design (analyst + skill ux-design; report-only; no developer)",
+  "steps": [
+    { "agent": "task-analyst", "label": "UX design (skill ux-design)" }
+  ],
+  "humanGates": [],
+  "autoChain": true,
+  "skipped": [
+    { "agent": "feature-developer", "reason": "Standalone ux-design is report-only" },
+    { "agent": "mockup-reviewer", "reason": "No figma.com URL; not a mockup review" }
+  ]
+}

package/presets/cursor/go/MCP.md

@@ -11,6 +11,27 @@ Copied to `.cursor/mcp.json` on `ai-rules init cursor --preset go`.
 
 Browser e2e MCP (Playwright / Chrome DevTools) are **not** part of the go preset.
 
-Do not put secrets in the file. Optional: `CONTEXT7_API_KEY` in the environment. Figma — OAuth (do not commit the token).
+Do not put secrets in the file. Optional: `CONTEXT7_API_KEY` in the environment. Figma — OAuth (do not commit the token). Optional Figma MCP is design context only — **not** a mockup-review pipeline (this preset never schedules `mockup-reviewer`).
 
-After init: Settings → MCP → enable servers. `init` overwrites the same-named `mcp.json`.
+
+## Agent usage
+
+Load requestable rule `mcp-usage`. The **session MCP catalog** is source of truth (this file and `mcp.json` are hints). Discover tool schemas before calling; never invent them.
+
+**Context7 (shipped):** query docs when a third-party API is not confirmed by lockfile + sibling files. Use the installed major. Cap ≤3 doc queries per question. If Context7 is down, mark `// VERIFY` and continue — do not block.
+
+## Local overlay (not shipped)
+
+`init` **merges** `mcpServers`: preset keys are updated; extra local servers are kept. User-level MCP is never touched. Prefer user-level MCP if you do not want overlay servers in the project file.
+
+Use an overlay only when it is **ready** (`serverStatus` not `error` / `needsAuth` / `loading`) **and** the task fits. Absence is not a blocker unless the user required that MCP as source of truth.
+
+| Kind | Typical aliases | When |
+|------|-----------------|------|
+| Observability | `sentry`, `datadog`, `plugin-datadog-*` | production error, event/trace id, APM |
+| Tickets | `linear`, `jira`, `notion`, `plugin-notion-*` | ticket/page URL; read-only; task-folder artifacts remain SoT |
+| GitHub MCP | `github` | optional; native `gh` remains SoT for PRs and checks |
+
+Do **not** require Storybook, Playwright, or Chrome DevTools MCP as delivery gates on this preset.
+
+Optional Figma on this preset is ad-hoc design context only — not a mockup-review pipeline.

package/presets/cursor/go/agents/build-verifier.md

@@ -34,6 +34,12 @@ Document PASS/FAIL in `validation-report.md`.
 3. **No react-performance on ios/go/java:** skill directory / required handoff must be absent under ios-swift, go, java, mcp-ts, php-hexagonal, and php-laravel → **FAIL** (leakage). Prefer `check:preset-leakage`.
 4. **Rule eval (WARN):** `scripts/check-rule-eval.mjs` / `yarn check:rule-eval` should exist for maintainers; smoke optional. Hard fail only when the opt-in eval job runs — not part of default `check:preset-structure`.
 
+
+**Forbidden mockup-reviewer:** agent file `agents/mockup-reviewer.md` or required `AGENT_HANDOFF` / pipeline handoff for `mockup-reviewer` → **FAIL** (no UI mockup reviewer).
+
+**Forbidden ux-designer / ux-design:** agent file `agents/ux-designer.md` or required `skills/ux-design` / `rules/ux-design` / pipeline handoff stem `ux-design` → **FAIL** (no UI UX surface).
+
+
 ## Artifact contract
 
 - **Authoritative inputs:** read `.cursor/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for brief/decomposition, implementation evidence, pipeline scope, and changed files.

package/presets/cursor/go/agents/ci-investigator.md

@@ -16,6 +16,14 @@ Triage red CI for Go repos (and ai-rules preset-structure when relevant).
 
 - Never treat `lint:js` / Playwright / xcodebuild as the Go default gate.
 
+
+## MCP usage
+
+Load requestable rule `mcp-usage` when verifying third-party library APIs (Context7) or when a local overlay MCP is present and the task fits. Discover tools at runtime; do not invent schemas. Overlay absence is not a blocker unless the user required that MCP as source of truth.
+
+If a Sentry/Datadog (or similar) MCP is ready and the task is a production error, event, or trace, use it. Do not invent telemetry.
+
+
 ## Anti-sycophancy discipline
 
 - When writing or changing code, load / follow rule `anti-sycophancy-discipline`.

package/presets/cursor/go/agents/debugger.md

@@ -20,6 +20,14 @@ Investigate with **runtime evidence**: failing `go test` output, logs, stack tra
 
 Write `.cursor/team/tasks/<slug>/debug-report.md`.
 
+
+## MCP usage
+
+Load requestable rule `mcp-usage` when verifying third-party library APIs (Context7) or when a local overlay MCP is present and the task fits. Discover tools at runtime; do not invent schemas. Overlay absence is not a blocker unless the user required that MCP as source of truth.
+
+If a Sentry/Datadog (or similar) MCP is ready and the task is a production error, event, or trace, use it. Do not invent telemetry.
+
+
 ## Design guidance
 
 - Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.