@bonesofspring/ai-rules 0.2.18 → 0.2.19

package/presets/claude/go/team/fixtures/feature-full.json

@@ -1,20 +1,56 @@
 {
   "slug": "example-feature-full",
   "intent": "feature",
+  "specMode": "consume",
   "profile": "full",
   "summary": "Multi-layer Go use case with integration-test coverage",
   "steps": [
-    { "agent": "task-analyst", "label": "Clarify and decompose" },
-    { "agent": "solution-architect", "label": "Design boundaries", "model": "strong" },
-    { "agent": "feature-developer", "label": "Implement + unit tests", "scope": "unit-in-dev" },
-    { "agent": "build-verifier", "label": "go test / go vet / golangci-lint", "model": "cheap" },
-    { "agent": "security-reviewer", "label": "Security review", "model": "strong" },
-    { "agent": "code-reviewer", "label": "Code review", "model": "cheap" },
-    { "agent": "qa-tester", "label": "Integration tests", "scope": "e2e-only" },
-    { "agent": "integration-test-planner", "label": "Plan integration coverage" },
-    { "agent": "integration-test-generator", "label": "Generate integration tests" }
+    {
+      "agent": "task-analyst",
+      "label": "Clarify and decompose"
+    },
+    {
+      "agent": "solution-architect",
+      "label": "Design boundaries",
+      "model": "strong"
+    },
+    {
+      "agent": "feature-developer",
+      "label": "Implement + unit tests",
+      "scope": "unit-in-dev"
+    },
+    {
+      "agent": "build-verifier",
+      "label": "go test / go vet / golangci-lint",
+      "model": "cheap"
+    },
+    {
+      "agent": "security-reviewer",
+      "label": "Security review",
+      "model": "strong"
+    },
+    {
+      "agent": "code-reviewer",
+      "label": "Code review",
+      "model": "cheap"
+    },
+    {
+      "agent": "qa-tester",
+      "label": "Integration tests",
+      "scope": "e2e-only"
+    },
+    {
+      "agent": "integration-test-planner",
+      "label": "Plan integration coverage"
+    },
+    {
+      "agent": "integration-test-generator",
+      "label": "Generate integration tests"
+    }
+  ],
+  "humanGates": [
+    "after:task-analyst"
   ],
-  "humanGates": ["after:task-analyst"],
   "autoChain": true,
   "skipped": [
     {

package/presets/claude/go/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/claude/ios-swift/MCP.md

@@ -13,4 +13,23 @@ Playwright / Chrome DevTools are **not** part of the ios preset (browser e2e is
 
 Do not put secrets in the file. Optional: `CONTEXT7_API_KEY` in the environment. Figma — OAuth (do not commit the token).
 
-After init: enable MCP servers in the client. `init` overwrites a 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.

package/presets/claude/ios-swift/agents/accessibility-reviewer.md

@@ -24,6 +24,12 @@ You are an accessibility reviewer for an **iOS SwiftUI / UIKit** frontend.
 - Focus / rotor order for custom controls; hit targets roughly ≥44pt when obvious from layout.
 - Sheet/modal dismissal discoverability for VoiceOver users.
 
+
+## 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.
+
+
 ## Output
 
 Write `.claude/team/tasks/<slug>/a11y-review.md`:
@@ -50,17 +56,8 @@ PASS | PASS_WITH_NOTES | FAIL
 
 ## On completion
 
-Update `status.json`:
+Write the owned terminal receipt in `artifact-manifest.json`; do not mutate `status.json`.
 
-```json
-{
-  "slug": "<slug>",
-  "currentAgent": "accessibility-reviewer",
-  "phase": "executing",
-  "state": "completed",
-  "updatedAt": "<ISO8601>"
-}
-```
 
 If **FAIL**, set `"state": "changes_requested"` and list specific fixes for `feature-developer`.
 

package/presets/claude/ios-swift/agents/api-contract-reviewer.md

@@ -55,17 +55,8 @@ For feature-developer before or during implementation.
 
 ## On completion
 
-Update `status.json`:
-
-```json
-{
-  "slug": "<slug>",
-  "currentAgent": "api-contract-reviewer",
-  "phase": "executing",
-  "state": "completed",
-  "updatedAt": "<ISO8601>"
-}
-```
+Write the owned terminal receipt in `artifact-manifest.json`; do not mutate `status.json`.
+
 
 If **MISALIGNED**, set `"state": "changes_requested"` when blocking implementation.
 

package/presets/claude/ios-swift/agents/ci-investigator.md

@@ -58,20 +58,19 @@ Commands run and results.
 
 ## On completion
 
-Update `status.json`:
-
-```json
-{
-  "slug": "<slug>",
-  "currentAgent": "ci-investigator",
-  "phase": "executing",
-  "state": "completed",
-  "updatedAt": "<ISO8601>"
-}
-```
+Write the owned terminal receipt in `artifact-manifest.json`; do not mutate `status.json`.
+
 
 Provide summary: failed check, root cause, files changed, validation commands run, `resolved`.
 
+
+## 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/claude/ios-swift/agents/debugger.md

@@ -55,22 +55,21 @@ fixApplied: false
 
 ## On completion
 
-Update `status.json`:
-
-```json
-{
-  "slug": "<slug>",
-  "currentAgent": "debugger",
-  "phase": "executing",
-  "state": "completed",
-  "updatedAt": "<ISO8601>"
-}
-```
+Write the owned terminal receipt in `artifact-manifest.json`; do not mutate `status.json`.
+
 
 Handoff summary: root cause, recommended fix, files touched (if any), `fixApplied`.
 
 Do not perform formal code review or write XCUITest plans — those are separate agents.
 
+
+## 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/claude/ios-swift/agents/feature-developer.md

@@ -68,6 +68,29 @@ When work touches a page/feature/route/alias: if `docs/specs/INDEX.md` exists (o
 Mechanical INDEX/frontmatter fixes only when implementation renames routes/ids. Substantive behavior edits → hand back to task-analyst (or tech-writer where present). If INDEX is absent and generation was not approved, treat specs as optional (greenfield).
 
 
+**specMode `none`:** do not require INDEX; implement from brief/AC only.
+
+**applyReadiness:** YAML frontmatter on `implementation.md`:
+
+```yaml
+applyReadiness:
+  state: ready   # blocked | ready | all_done
+  contextFiles: []
+```
+
+`blocked` if human gate pending, required spec missing, required UX `INCOMPLETE`, or incomplete WP deps. `ready` when the current WP may be implemented. `all_done` on the final receipt when mechanical spec sync is done.
+
+**Code Map + Suggested Review Order:** when this WP spans **>1 layer or module**, add to `implementation.md` a Code Map (3–8 annotated paths) and Suggested Review Order lines `concern | path:line | ≤15 words`. Omit for single-file / single-layer WPs.
+
+**Memlog:** append implementation decisions to `.claude/team/tasks/<slug>/.memlog.md` (append-only).
+
+
+
+## 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.
+
+
 ## Artifact contract
 
 - **Authoritative inputs:** read `.claude/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for `brief.md`, `decomposition.md`, current scope, and applicable prior findings.

package/presets/claude/ios-swift/agents/migration-specialist.md

@@ -58,20 +58,17 @@ Temporary adapters, feature flags, dual code paths if needed.
 
 ## On completion
 
-Update `status.json`:
-
-```json
-{
-  "slug": "<slug>",
-  "currentAgent": "migration-specialist",
-  "phase": "executing",
-  "state": "completed",
-  "updatedAt": "<ISO8601>"
-}
-```
+Write the owned terminal receipt in `artifact-manifest.json`; do not mutate `status.json`.
+
 
 Hand off: orchestrator runs human gate (if configured), then `feature-developer` executes phases from the plan.
 
+
+## 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/claude/ios-swift/agents/performance-auditor.md

@@ -55,22 +55,19 @@ Ordered list for feature-developer if fixes are requested.
 
 ## On completion
 
-Update `status.json`:
-
-```json
-{
-  "slug": "<slug>",
-  "currentAgent": "performance-auditor",
-  "phase": "executing",
-  "state": "completed",
-  "updatedAt": "<ISO8601>"
-}
-```
+Write the owned terminal receipt in `artifact-manifest.json`; do not mutate `status.json`.
+
 
 For standalone `perf-audit` intent, suggest `/technical-retro` or a follow-up `/task` to implement fixes.
 
 Do not modify production code.
 
+
+## 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/claude/ios-swift/agents/qa-tester.md

@@ -45,17 +45,8 @@ When the task is mostly UI e2e, prefer `xcuitest-test-planner`, `xcuitest-test-g
 
 ## On completion
 
-Update `status.json`:
-
-```json
-{
-  "slug": "<slug>",
-  "currentAgent": "qa-tester",
-  "phase": "executing",
-  "state": "completed",
-  "updatedAt": "<ISO8601>"
-}
-```
+Write the owned terminal receipt in `artifact-manifest.json`; do not mutate `status.json`.
+
 
 Provide summary:
 

package/presets/claude/ios-swift/agents/security-reviewer.md

@@ -52,17 +52,8 @@ PASS | PASS_WITH_NOTES | FAIL
 
 ## On completion
 
-Update `status.json`:
-
-```json
-{
-  "slug": "<slug>",
-  "currentAgent": "security-reviewer",
-  "phase": "executing",
-  "state": "completed",
-  "updatedAt": "<ISO8601>"
-}
-```
+Write the owned terminal receipt in `artifact-manifest.json`; do not mutate `status.json`.
+
 
 If **FAIL**, set `"state": "changes_requested"`.
 

package/presets/claude/ios-swift/agents/solution-architect.md

@@ -16,6 +16,12 @@ You are a solution architect for **iOS Feature modules** (Presentation / Domain
 
 Handoff: architecture approved or awaiting gate → status update.
 
+
+## 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/claude/ios-swift/agents/task-analyst.md

@@ -34,6 +34,15 @@ Do not invent architecture stacks (TCA, SwiftData, …) — frame “as in the r
 
 **Author mode (Generate / Bootstrap):** When the user runs `/spec-start`, router intent is `spec-gen` / bootstrap, or brief/AC requests generation: load **`product-specs`** + **`product-specs-authoring`** and skill **`spec-authoring`**. You are the **primary author** (INDEX bootstrap included). Follow frontmatter v1 + required headings; update INDEX in the **same change set**; default `status: draft`. Block handoff via `open_questions` until the authoring self-check passes.
 
+
+**Spec mode:** Write `## Spec mode` in `brief.md` with exactly one of `consume` | `generate` | `none`. Infer if unset: spike/research/preset-only → `none`; `/spec-start` or router `spec-gen` → `generate`; otherwise `consume`. Router may echo `specMode` on `pipeline.json`.
+
+**`none`:** skip INDEX row requirement and author mode; do not invent a dummy INDEX.
+
+**Research-before-spec (opt-in):** load skill **`spec-discovery`** only when the user/AC asks research before authoring (not default consume `/task`). Run a **subset** of methods; **`claim-ledger` is mandatory** whenever the skill loads. Append chronological notes to `.claude/team/tasks/<slug>/.memlog.md` (append-only; do not mutate `status.json`).
+
+**applyReadiness (author blocked):** if specs are drafted but the human gate has not passed, or a required named spec is missing, emit `applyReadiness: { "state": "blocked", "contextFiles": ["…"] }` on the analysis receipt. Do not invoke feature-developer.
+
 ### Brief sections (when author mode or INDEX exists)
 
 Add to `brief.md`:
@@ -64,6 +73,14 @@ Write `.claude/team/tasks/<slug>/ux-design.md` with the headings in rule `ux-des
 
 When produced, append `ux-design.md` to this step's **`analysis`** `authoritativePaths` / `evidencePaths`. No new manifest producer row.
 
+
+## 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 the prompt/brief has a tracker URL (Linear/Jira/Notion/…) and that MCP is ready, pull AC **read-only**. Task-folder artifacts remain SoT.
+
+
 ## Artifact contract
 
 - **Authoritative inputs:** read `.claude/team/tasks/<slug>/artifact-manifest.json` first; consume `pipeline.json`, the manifest routing entry, user-approved decisions, and any authoritative architecture/approval entries.

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

@@ -84,6 +84,7 @@ Fixtures: `.claude/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 +112,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/claude/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` (`tooling-and-review/xcode-tooling.md`) 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/claude/ios-swift/agents/unit-test-healer.md

@@ -40,17 +40,8 @@ Short root-cause note in the handoff (and optionally `.claude/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/claude/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/claude/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` (`tooling-and-review/xcode-tooling.md`) 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/claude/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/claude/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 `.claude/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/claude/ios-swift/commands/spec-start.md

@@ -14,7 +14,7 @@ Routes intent **`spec-gen`** (or bootstrap) → **task-analyst** in **author mod
 3. Ensure `.claude/team/tasks/<slug>/` exists (Write artifacts; not Shell mkdir).
 4. Write `.claude/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/claude/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": {
       "type": "http",

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

@@ -9,7 +9,7 @@ In Claude Code all `.md` files under `rules/` are **discovered recursively**. Bo
 | **SoT** | `presets/cursor/ios-swift/rules/*.mdc` — edit here first |
 | **Derive** | Claude topic `.md` = body + `paths:` (from Cursor `globs:` / requestable triggers) |
 | **Drop** | Cursor-only keys (`alwaysApply`); keep short `description` |
-| **Checklist** | change Cursor → update Claude twin **same PR** (**FAIL** if missing — next, ios-swift, and go; see `preset-twin-sync` / build-verifier) |
+| **Checklist** | change Cursor → update Claude twin **same PR** (**FAIL** if missing — all 10 installable stacks; see `preset-twin-sync` / build-verifier) |
 
 ## Loading budget
 
@@ -39,6 +39,7 @@ In Claude Code all `.md` files under `rules/` are **discovered recursively**. Bo
 | `code-quality-and-refactoring.mdc` | `tooling-and-review/code-quality.md` |
 | `anti-sycophancy-discipline.mdc` | `tooling-and-review/anti-sycophancy-discipline.md` |
 | `design-guidance.mdc` | `tooling-and-review/design-guidance.md` |
+| `mcp-usage.mdc` | `tooling-and-review/mcp-usage.md` |
 | `code-review-mr.mdc` | `tooling-and-review/code-review.md` |
 | `post-change-build.mdc` | `tooling-and-review/post-change-build.md` |
 | `xcode-tooling.mdc` | `tooling-and-review/xcode-tooling.md` |
@@ -61,6 +62,7 @@ In Claude Code all `.md` files under `rules/` are **discovered recursively**. Bo
 | `quality/code-quality-and-refactoring.md` | `code-quality-and-refactoring.mdc` / `code-quality.md` | + Stack notes (Swift/DesignSystem) |
 | `quality/anti-sycophancy-discipline.md` | `anti-sycophancy-discipline.mdc` / `anti-sycophancy-discipline.md` | requestable full VERIFY/discipline set |
 | `quality/design-guidance.md` | `design-guidance.mdc` / `design-guidance.md` | requestable smells/GoF |
+| `quality/mcp-usage.md` | `mcp-usage.mdc` / `mcp-usage.md` | requestable Context7 + overlay MCP |
 | `agent-team/agent-team-orchestrator.md` | `agent-team-orchestrator.mdc` | Roles (XCUITest) in Stack notes |
 | `agent-team/agent-team-intake.md` | `agent-team-intake.mdc` | thin alias |
 | `architecture/feature-delivery-workflow.md` | `feature-delivery-workflow.mdc` | iOS Feature checklist |

package/presets/claude/ios-swift/rules/architecture/feature-delivery.md

@@ -27,7 +27,7 @@ Typical feature with data and UI. Layer details — `architecture/boundaries.md`
 3. **ViewModel** — state, use case / protocol calls; DI from App; no DTOs or URLs (`ui-and-accessibility/viewmodels.md`).
 4. **View / navigation** — thin SwiftUI Views, Design System; navigation as in the repo (`ui-and-accessibility/swiftui.md`).
 5. **Tests** — unit for mappers / use cases / VM (`testing/unit.md`); UI flows — XCUITest (`testing/ui.md`).
-6. **Completion** — **invoke** `tooling-and-review/post-change-build.md` (+ `tooling-and-review/xcode-tooling.md` for schemes/commands): build touched targets + lint/format per repo config.
+6. **Completion** — **invoke** `tooling-and-review/post-change-build.md` (+ `tooling-and-review/xcode-tooling.md` 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)
 
@@ -59,6 +59,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/claude/ios-swift/rules/architecture/product-specs-authoring.md

@@ -9,6 +9,8 @@ paths:
 
 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`).
@@ -82,7 +84,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.
 
@@ -92,7 +94,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 |
@@ -111,8 +113,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