@bonesofspring/ai-rules 0.2.18 → 0.2.20

package/presets/cursor/ios-swift/agents/task-router.md

@@ -35,6 +35,20 @@ You are a task router for an **iOS Swift/SwiftUI** agent team. You **do not** im
 | `retro` | “retro”, “postmortem” | (orchestrator → `/technical-retro`) |
 
 **Never schedule Playwright agents** (`playwright-test-*`). If a next template mentions them, put in `skipped` with reason "iOS uses XCUITest" and use xcuitest trio.
+## Task class (spike / bounded / architectural)
+
+<!-- shared-core: agent-team/task-classification.md -->
+
+Name the class in `routingReasons`. Maps to profiles already in this file — do not add a parallel step table.
+
+| Class | Use existing |
+|-------|----------------|
+| Spike | intent `spike` |
+| Bounded | `profile: light` (or skip analyst when AC is complete) |
+| Architectural | `profile: full` + `solution-architect` when boundaries unclear |
+
+SoT: `agent-team/task-classification` (shared-core marker above; do not invent a second pipeline).
+
 **Light by intent:** `mockup-review` → only `mockup-reviewer` (`model: "strong"`, never `cheap`). `ux-design` → only `task-analyst` (skill `ux-design`; analyst default model, not `strong`). Classify `mockup-review` **before** `ux-design` **before** `review-only`. A `figma.com` URL with review-not-implement language remains `mockup-review` even if the user said «ревью UX». <!-- i18n-keep: E4 -->
 **Embed UX:** on `feature` / `refactor` / `spike` / `spec-gen` with required-signal or advisory UI AC, instruct **task-analyst** to load skill `ux-design` (no new pipeline step).
 
@@ -84,6 +98,7 @@ Fixtures: `.cursor/team/fixtures/` (feature-full, feature-light, bugfix-standard
 | Intent | Default humanGates |
 |--------|-------------------|
 | feature, refactor, test-only, a11y | `["after:task-analyst"]` |
+| spec-gen | `["after:task-analyst"]` |
 | migration | `["after:migration-specialist"]` |
 | unit-only | `["after:unit-test-planner"]` when new plan |
 | e2e-only | `["after:xcuitest-test-planner"]` when new plan |
@@ -111,6 +126,11 @@ Detect and set routing reasons when the user asks to **generate / bootstrap prod
 
 Do **not** add a dedicated `spec-author` agent. Do not require solution-architect for routine spec authoring.
 
+
+**specMode (optional `pipeline.json` field):** `none` for spike/research; `generate` for `spec-gen` / `/spec-start`; `consume` default when INDEX exists. Echo top-level `specMode`. Brief `## Spec mode` wins on conflict.
+
+Do **not** add a pipeline step for `spec-discovery`. Instruct analyst to load that skill only when the user/AC asks research-before-spec.
+
 ## Runtime initialization
 
 Return the routing receipt to the orchestrator. The orchestration runtime/hook exclusively initializes and updates `status.json`, `metrics.json`, attempt identities, and gate lifecycle; the router does not write those shared runtime files.

package/presets/cursor/ios-swift/agents/unit-test-generator.md

@@ -41,17 +41,8 @@ You generate unit tests from project test plans for **iOS Swift**.
 
 Run affected unit tests via `xcodebuild test` (`xcode-tooling.mdc`) when feasible. Report commands, pass/fail, and gaps.
 
-Update `status.json`:
-
-```json
-{
-  "slug": "<slug>",
-  "currentAgent": "unit-test-generator",
-  "phase": "executing",
-  "state": "completed",
-  "updatedAt": "<ISO8601>"
-}
-```
+Write the owned terminal receipt in `artifact-manifest.json`; do not mutate `status.json`.
+
 
 ## Design guidance
 

package/presets/cursor/ios-swift/agents/unit-test-healer.md

@@ -40,17 +40,8 @@ Short root-cause note in the handoff (and optionally `.cursor/team/tasks/<slug>/
 
 Report root cause, files changed, validation result, and remaining risk.
 
-Update `status.json`:
-
-```json
-{
-  "slug": "<slug>",
-  "currentAgent": "unit-test-healer",
-  "phase": "executing",
-  "state": "completed",
-  "updatedAt": "<ISO8601>"
-}
-```
+Write the owned terminal receipt in `artifact-manifest.json`; do not mutate `status.json`.
+
 
 ## Design guidance
 

package/presets/cursor/ios-swift/agents/unit-test-planner.md

@@ -49,17 +49,8 @@ Test titles in the plan must be **Russian**, each sentence starting with a capit
 
 ## On completion
 
-Update `status.json`:
-
-```json
-{
-  "slug": "<slug>",
-  "currentAgent": "unit-test-planner",
-  "phase": "executing",
-  "state": "completed",
-  "updatedAt": "<ISO8601>"
-}
-```
+Write the owned terminal receipt in `artifact-manifest.json`; do not mutate `status.json`.
+
 
 Do not write test source files — that is `unit-test-generator`'s job.
 

package/presets/cursor/ios-swift/agents/xcuitest-test-generator.md

@@ -34,14 +34,4 @@ You generate XCUITest cases from project UI test plans.
 
 Run affected UI tests via `xcodebuild test` (`xcode-tooling.mdc`) when a simulator/destination is available. Report files changed, tests run, failures, and gaps.
 
-Update `status.json`:
-
-```json
-{
-  "slug": "<slug>",
-  "currentAgent": "xcuitest-test-generator",
-  "phase": "executing",
-  "state": "completed",
-  "updatedAt": "<ISO8601>"
-}
-```
+For agent team tasks, upsert the owned terminal receipt in `artifact-manifest.json`; do not mutate `status.json`.

package/presets/cursor/ios-swift/agents/xcuitest-test-healer.md

@@ -34,14 +34,4 @@ You debug and fix failing **XCUITest** UI tests.
 
 Report root cause, files changed, validation result, and remaining flakiness risk.
 
-Update `status.json`:
-
-```json
-{
-  "slug": "<slug>",
-  "currentAgent": "xcuitest-test-healer",
-  "phase": "executing",
-  "state": "completed",
-  "updatedAt": "<ISO8601>"
-}
-```
+For agent team tasks, upsert the owned terminal receipt in `artifact-manifest.json`; do not mutate `status.json`.

package/presets/cursor/ios-swift/agents/xcuitest-test-planner.md

@@ -48,20 +48,8 @@ Write or update the relevant `*.cases.md` (or equivalent plan). Suggested shape:
 ...
 ```
 
-For agent team tasks, summarize planned scenarios and update `.cursor/team/tasks/<slug>/status.json`.
+For agent team tasks, summarize planned scenarios and upsert the owned terminal receipt in `artifact-manifest.json`; do not mutate `status.json`.
 
 ## On completion
 
-Update `status.json`:
-
-```json
-{
-  "slug": "<slug>",
-  "currentAgent": "xcuitest-test-planner",
-  "phase": "executing",
-  "state": "completed",
-  "updatedAt": "<ISO8601>"
-}
-```
-
 Do not write XCUITest Swift sources — that is `xcuitest-test-generator`'s job.

package/presets/cursor/ios-swift/commands/spec-start.md

@@ -14,7 +14,7 @@ Routes intent **`spec-gen`** (or bootstrap) → **task-analyst** in **author mod
 3. Ensure `.cursor/team/tasks/<slug>/` exists (Write artifacts; not Shell mkdir).
 4. Write `.cursor/team/active-task.json` → `{ "slug": "<slug>" }`.
 5. Write minimal `pipeline.json`: task-analyst → (optional stop) → feature-developer only if user asked implement-after. **No separate spec-author agent.**
-6. Invoke **task-analyst** with: author mode; load **`product-specs`** + **`product-specs-authoring`** + skill **`spec-authoring`**; Bootstrap if `docs/specs/` absent, else Generate.
+6. Invoke **task-analyst** with: author mode; load **`product-specs`** + **`product-specs-authoring`** + skill **`spec-authoring`**; Bootstrap if `docs/specs/` absent, else Generate. Optional: if arguments/AC ask research-before-spec, also load skill **`spec-discovery`** (not default).
 7. Wait for analyst. **Do not** invoke feature-developer until human gate passes.
 
 ## Human gate

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

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

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

@@ -22,6 +22,7 @@ Cursor Rule format:
 | `code-quality-and-refactoring.mdc` | **always** | Quality and light refactor |
 | `anti-sycophancy-discipline.mdc` | requestable | Full VERIFY/anti-sycophancy discipline (~17 rules) |
 | `design-guidance.mdc` | requestable | Smells/GoF (Fowler≤12, GoF≤8) |
+| `mcp-usage.mdc` | requestable | Context7 + overlay MCP |
 | `xcode-tooling.mdc` | requestable | Schemes, xcodebuild, SwiftLint/Format |
 | `post-change-build.mdc` | requestable | Build/lint after Swift edits (**required** after code edits) |
 | `agent-team-intake.mdc` | requestable | `/task` hint |
@@ -58,6 +59,7 @@ SoT prose: `packages/ai-rules/presets/_shared/core/**`. Adapters: `<!-- shared-c
 | `quality/code-quality-and-refactoring.md` | `code-quality-and-refactoring.mdc` | Stack notes: force unwrap, DesignSystem |
 | `quality/anti-sycophancy-discipline.md` | `anti-sycophancy-discipline.mdc` | requestable full VERIFY/discipline set |
 | `quality/design-guidance.md` | `design-guidance.mdc` | requestable smells/GoF |
+| `quality/mcp-usage.md` | `mcp-usage.mdc` | requestable Context7 + overlay MCP |
 | `agent-team/agent-team-orchestrator.md` | `agent-team-orchestrator.mdc` | Roles (XCUITest); preset PR pointer |
 | `agent-team/agent-team-intake.md` | `agent-team-intake.mdc` | thin + iOS scope note |
 | `architecture/feature-delivery-workflow.md` | `feature-delivery-workflow.mdc` | Feature modules checklist |

package/presets/cursor/ios-swift/rules/agent-team-orchestrator.mdc

@@ -19,6 +19,7 @@ Work request without `/task` — see **`agent-team-intake.mdc`**.
 | `/task-continue <slug>` | After human gate or pause |
 | `/feature-start <desc>` | Legacy: analyst-only start (no router) |
 | `/feature-continue <slug>` | Alias of task-continue |
+| `/spec-start [desc]` | Generate/bootstrap `docs/specs` — router intent `spec-gen` → analyst author mode → human gate |
 | `/technical-retro [slug]` | Retro with agent team block |
 
 ## Stack notes
@@ -28,7 +29,7 @@ Work request without `/task` — see **`agent-team-intake.mdc`**.
 | Agent | Prod writes | Typical intent |
 |-------|-------------|----------------|
 | `task-router` | no (team) | Every `/task` |
-| `task-analyst` | no | feature, refactor, test-only, a11y, docs, migration, ux-design |
+| `task-analyst` | no | feature, refactor, test-only, a11y, docs, migration, ux-design, spec-gen |
 | `solution-architect` | no | spike, cross-layer Feature |
 | `migration-specialist` | no | Xcode/SPM/iOS upgrades |
 | `api-contract-reviewer` | no | OpenAPI / Swift codegen contracts |

package/presets/cursor/ios-swift/rules/anti-sycophancy-discipline.mdc

@@ -11,7 +11,7 @@ alwaysApply: false
 
 Procedural rules for code generation and review. Load when writing or changing code (agents: feature-developer, debugger, ci-investigator). Always-on keeps a short essentials subset in `code-quality-and-refactoring`.
 
-1. **Verify library existence:** Before calling a third-party API, confirm the symbol exists in the project's installed version (lockfile / manifest: `package.json`, `go.mod`, `Podfile.lock`, `pom.xml`, `Cargo.toml`, or equivalent). If you cannot verify, mark `// VERIFY: lib.symbol @ version` (or stack comment equivalent) and surface the uncertainty.
+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.

package/presets/cursor/ios-swift/rules/code-quality-and-refactoring.mdc

@@ -33,7 +33,7 @@ alwaysApply: true
 
 Essentials below. Full procedural set (~17 rules) → load **`anti-sycophancy-discipline`**.
 
-- Unverifiable third-party API → mark `// VERIFY: lib.symbol @ version` (or stack equivalent); never invent signatures.
+- 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".

package/presets/cursor/ios-swift/rules/feature-delivery-workflow.mdc

@@ -20,7 +20,7 @@ Typical feature with data and UI. Layer details — `architecture-boundaries.mdc
 3. **ViewModel** — state, use case / protocol calls; DI from App; no DTOs or URLs (`state-and-viewmodels.mdc`).
 4. **View / navigation** — thin SwiftUI Views, Design System; navigation as in the repo (`swiftui-ui.mdc`).
 5. **Tests** — unit for mappers / use cases / VM (`tests-unit.mdc`); UI flows — XCUITest (`tests-ui.mdc`).
-6. **Completion** — **invoke** `post-change-build.mdc` (+ `xcode-tooling.mdc` for schemes/commands): build touched targets + lint/format per repo config.
+6. **Completion** — **invoke** `post-change-build.mdc` (+ `xcode-tooling.mdc` for schemes/commands): build touched targets + lint/format per repo config. When the current WP spans **more than one** layer or module, `implementation.md` includes a **Code Map** (3–8 annotated paths) and **Suggested Review Order** (`concern | path:line | ≤15 word note`). Omit both for a single-file or single-layer WP.
 
 ## Data flow (orientation)
 
@@ -52,6 +52,7 @@ flowchart LR
 - Assembling DI inside a View.
 - **Ubiquitous language:** Domain/type names reflect the feature domain — do not mix transport/framework terms into domain without need.
 - Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.
+- Do not mutate pipeline `status.json` / `metrics.json`; the orchestration hook is the single writer. Skills upsert the owned terminal receipt in `artifact-manifest.json`.
 
 ## Matrix: zone → rules
 

package/presets/cursor/ios-swift/rules/mcp-usage.mdc

@@ -0,0 +1,99 @@
+---
+description: When to call shipped Context7 and local overlay MCP — detect presence, use if the task fits, degrade.
+alwaysApply: false
+---
+
+<!-- shared-core: quality/mcp-usage.md -->
+
+# MCP usage
+
+Requestable protocol for **shipped** and **local-overlay** MCP servers. Agents load this stem via one-liner wiring — do not copy tool schemas into prompts; discover them at runtime.
+
+Does not replace Figma mockup-review (that checklist stays on `mockup-review`). Does not add pipeline agents or required handoff stems.
+
+## Presence (runtime catalog is SoT)
+
+1. Inspect the **session MCP catalog** (server names + `serverStatus`). Project `mcp.json` / `.mcp.json` is a hint, not proof the server is up (user-level and plugin servers never appear there).
+2. Treat `error`, `needsAuth`, and `loading` as **unavailable**. Authenticate only when this task needs that server.
+3. **Discover tool schemas before calling.** Never invent tool names or arguments from memory.
+4. Match overlay servers by **documented aliases** or exact catalog ids. Prefer a ready `plugin-*` id over an unknown similarly named server; if several match, ask rather than guessing.
+5. If two servers expose the same product (plugin + project entry), use the **ready** one; do not call both.
+
+## Classes
+
+| Class | Who adds it | Policy |
+|-------|-------------|--------|
+| **Shipped** | Preset `mcp.json` | Assume it should be there; call when the task fits; degrade if down (do not block unless noted below) |
+| **Local overlay** | Consumer project or user MCP | Use only when present **and** the task fits. Never a required pipeline step |
+
+Shipped in every preset: **Context7** (library docs). Other shipped servers are stack-specific — see adapter **Stack notes**.
+
+## Context7 (shipped)
+
+**When to call** (after lockfile / manifest + sibling files still do not confirm the symbol):
+
+- Third-party API that would otherwise get `// VERIFY: lib.symbol @ version`
+- Version-sensitive framework or SDK APIs
+- Migrations / major upgrades
+- Library is in the lockfile but the signature is unclear
+
+**When not to call:** repo public API; a sibling file already imports the symbol; a trivial call already in this module.
+
+**Flow:**
+
+1. Discover server `context7`.
+2. Resolve a library id, then query docs (read the live schema; typical names `resolve-library-id` then `query-docs`).
+3. Put the **installed major** from the project manifest into the query.
+4. Cap: **≤3 doc queries per question**.
+5. Source priority: lockfile / sibling code **>** Context7 **>** training data. If docs disagree with the installed major, keep the installed API.
+6. If Context7 is down: `// VERIFY` (or stack equivalent) and say MCP was unavailable. **Do not block** the task.
+
+## Local overlay protocol
+
+If a matching server is ready and a **task signal** fires → discover and use. Otherwise continue from files / native tools (`gh`, repo docs, source).
+
+Absence of an overlay is **not** `BLOCKED` unless the user required that MCP as source of truth.
+
+### Observability (Sentry, Datadog, similar)
+
+**Signal:** production error, event/trace id, APM / latency, pasted dashboard or issue URL.
+
+Use the **first ready** observability MCP. Do not invent metrics or stack traces. Do not require two observability servers.
+
+### Tickets (Linear, Jira, Notion, similar)
+
+**Signal:** ticket/page URL in the prompt or brief, or an explicit “pull from \<tracker\>”.
+
+Read-only by default. Task-folder artifacts (`brief.md`, `decomposition.md`) remain SoT — do not replace them with a tracker page. Write back to the tracker **only** if the user asked.
+
+### Component-library overlay
+
+**Signal:** UI component public API, stories, controls, or explicit component-docs MCP.
+
+If such a server is ready, use it for documented props/variants instead of inventing them. If it is down, read story/source files. **Block** only when the user required that MCP as SoT.
+
+Usual aliases and runtime needs live in frontend **Stack notes**. Do not ship this server in preset `mcp.json`.
+
+### GitHub MCP
+
+Native `gh` / git remain SoT for PRs and checks. A GitHub MCP may be used when present; do not require it.
+
+## Figma
+
+Policy is stack-class-specific — see adapter **Stack notes**. If a Figma **plugin** and a project `figma` server are both present, use the ready one and do not duplicate calls.
+
+## Forbidden
+
+- Secrets in `mcp.json` / `.mcp.json`
+- New pipeline agents or required handoffs for overlay MCP
+- Treating overlay absence as blocked (except user-required SoT)
+- Tracker/admin write tools without an explicit ask
+- Calling overlay MCP “just in case” on unrelated tasks
+
+## Stack notes
+
+- Pipeline **`mockup-reviewer`** is the only agent that reads Figma for mockup review. See `mockup-review`.
+- Shipped besides Context7: Figma (mockup-review pipeline). See `mockup-review`.
+- Do **not** require Storybook, Playwright, or Chrome DevTools MCP as handoffs or delivery gates.
+- Observability and ticket overlays still apply when present.
+- `init` **merges** `mcpServers`: preset keys update; extra local servers are kept.

package/presets/cursor/ios-swift/rules/preset-no-cross-stack-leakage.mdc

@@ -23,6 +23,7 @@ Ban leakage of stack-specific names, paths, and handoff stems across presets.
 - `go` / `java` / `php-hexagonal` / `php-laravel` / `mcp-ts` must not ship Playwright, XCUITest, Android instrumentation agents, Next lint recipes, or `xcodebuild`/`SwiftLint` as required handoffs.
 - `mcp-ts` must not ship Go tool commands (`go test`, `go vet`, `golangci-lint`) or `integration-test-*` agents as required delivery gates.
 - Shared core must not embed stack paths (`app/src/**`, `Features/**`, `playwright`, `xcodebuild`).
+- Storybook / Chrome DevTools MCP must **not** be required handoffs or agent stems (`storybook-reviewer`) on backend or mobile stacks. Frontend overlay mentions in `MCP.md` / `mcp-usage` Stack notes are OK.
 
 ## Forbidden in ios-swift hooks/agents (FAIL)
 

package/presets/cursor/ios-swift/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/ios-swift/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 / View / ViewModel modules (`Features/**` or equivalent) — **not** web `app/src/ui`. `e2e`: XCUITest paths.

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

@@ -3,6 +3,8 @@
 | 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 |

package/presets/cursor/ios-swift/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/ios-swift/skills/code-review/SKILL.md

@@ -32,7 +32,13 @@ Lead with findings ordered by severity. Required shape (also in `code-review-mr`
 - End with a verdict line: **`Safe to merge | needs changes | reject`**.
 - If there are no findings, say so and call out remaining test or validation risk.
 
-For agent team tasks, write `.cursor/team/tasks/<slug>/review.md` and set `status.json` to `completed` or `changes_requested`.
+For agent team tasks, write `.cursor/team/tasks/<slug>/review.md` and upsert the owned terminal receipt (`completed` or `changes_requested`); do not mutate `status.json`.
+
+## Receiving review feedback
+
+<!-- shared-core: review/receiving-code-review.md -->
+
+When **implementing** review comments (not when issuing them): verify each item against the codebase before changing code; do not perform agreement (`You're absolutely right!`). Unclear items → ask, do not guess.
 
 ## Design guidance
 

package/presets/cursor/ios-swift/skills/debug-investigation/SKILL.md

@@ -3,9 +3,37 @@ name: debug-investigation
 description: Investigates bugs, failing tests, crashes, and incorrect behavior with runtime evidence before applying minimal fixes. Use for bugfix tasks, debugger agent runs, regressions, and flaky test diagnosis.
 ---
 
-# Debug Investigation (iOS)
+<!-- shared-core: quality/debug-investigation.md -->
+
+# Debug investigation
+
+Stack-agnostic root-cause loop. Consumed by skill `debug-investigation` and agent `debugger`. Platform paths, MCP, and stack commands belong in adapter **Stack notes**.
+
+## When
+
+Any bug, test failure, build failure, or unexpected behavior — **before** proposing a fix.
+
+## Phases (in order)
+
+1. **Evidence** — reproduce, or collect the closest evidence (error output, failing test, logs, user steps).
+2. **Isolate** — expected vs actual in one sentence; smallest relevant slice of the codebase.
+3. **Root cause** — name the cause before editing. One hypothesis at a time; do not stack speculative fixes.
+4. **Minimal fix + verify** — smallest change that preserves architecture and public contracts. Add a regression test when the behavior is user-facing or likely to recur. Re-run the **failing** check first, then the relevant lint/type/test slice.
+
+## 3-fix architecture gate
+
+If **three** fix attempts fail, or the same symptom returns after two supposed fixes: **STOP**. Do not attempt fix #4. Escalate — the design is likely wrong (human partner or `solution-architect`). Chasing symptoms is the failure mode.
+
+## Do not
+
+- Broad refactor during a bugfix.
+- Fix only where the error surfaces if invalid data originates elsewhere.
+- Claim `fixApplied: true` without re-running the failing check (see `quality/verification-before-completion.md`).
+
+## Stack notes
+
+### Stack process
 
-## Process
 
 1. Reproduce the issue or collect the closest available evidence: Xcode console, lldb backtrace, crash log, failing XCTest/XCUITest output, Instruments note, or user steps.
 2. Define expected vs actual behavior in one sentence.
@@ -15,7 +43,7 @@ description: Investigates bugs, failing tests, crashes, and incorrect behavior w
 6. Add or update a regression XCTest when the behavior is domain/VM logic or likely to recur.
 7. Run the narrow failing check first (`xcodebuild test` for the affected target), then broader build validation if needed (`xcode-tooling.mdc`).
 
-## Artifacts
+### Artifacts
 
 For agent team tasks, write `.cursor/team/tasks/<slug>/debug-report.md` with:
 
@@ -25,10 +53,18 @@ For agent team tasks, write `.cursor/team/tasks/<slug>/debug-report.md` with:
 - Regression coverage.
 - Remaining risk.
 
-Update `status.json` when complete.
+Agent team: upsert the owned terminal receipt in `artifact-manifest.json`; do not mutate `status.json`.
 
 Do not use browser/Playwright tooling — this is an Xcode stack.
 
-## Design guidance
+
+### 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/ios-swift/skills/feature-delivery/SKILL.md

@@ -32,7 +32,13 @@ When editing **ai-rules ios-swift preset** sources (agents, hooks, rules) rather
 
 ## Handoff
 
-Summarize by layer, validation results, and known gaps. Agent team: update `.cursor/team/tasks/<slug>/status.json`.
+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
 

package/presets/cursor/ios-swift/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`.