@bonesofspring/ai-rules 0.2.18 → 0.2.19

package/presets/claude/svelte/skills/ci-investigation/SKILL.md

@@ -25,6 +25,14 @@ Write `ci-report.md` under the task slug folder:
 - Fix applied (or handoff to feature-developer)
 - 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/claude/svelte/skills/code-review/SKILL.md

@@ -31,7 +31,7 @@ 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 `.claude/team/tasks/<slug>/review.md` and set `status.json` to `completed` or `changes_requested`.
+For agent team tasks, write `.claude/team/tasks/<slug>/review.md` and upsert the owned terminal receipt (`completed` or `changes_requested`); do not mutate `status.json`.
 
 ## Design guidance
 

package/presets/claude/svelte/skills/debug-investigation/SKILL.md

@@ -25,7 +25,19 @@ For agent team tasks, write `.claude/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`.
+
+
+## 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 Chrome DevTools MCP is ready and the app is running, use it for console, network, and runtime evidence.
+
+Shipped browser split: Playwright MCP for e2e specs/selectors; Chrome DevTools MCP for live-app debug and performance (app must be running). Storybook MCP if present and the work is component docs/stories.
+
+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
 

package/presets/claude/svelte/skills/feature-delivery/SKILL.md

@@ -20,7 +20,15 @@ Implement only the current AC / decomposition task. Clarify ambiguity before cod
 
 ## 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.
+
+Shipped browser split: Playwright MCP for e2e specs/selectors; Chrome DevTools MCP for live-app debug and performance (app must be running). Storybook MCP if present and the work is component docs/stories.
+
 
 ## Design guidance
 

package/presets/claude/svelte/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 `.claude/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: `.claude/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/claude/svelte/team/README.md

@@ -27,6 +27,7 @@ Artifact directory for the Claude Code “agent team” pipeline.
       unit-test-plan.md
       documentation.md
       review.md
+      .memlog.md             # append-only agent notes (optional)
 ```
 
 ## pipeline.json schema
@@ -35,6 +36,7 @@ Artifact directory for the Claude Code “agent team” pipeline.
 {
   "slug": "order-history-date-filter",
   "intent": "feature",
+  "specMode": "consume",
   "summary": "Add date filter to Order History",
   "steps": [
     { "agent": "task-analyst", "label": "Clarify and decompose" },
@@ -59,6 +61,8 @@ Artifact directory for the Claude Code “agent team” pipeline.
 | `skipIf` | `debugger.fixed` \| `ci-investigator.resolved` |
 | `parallel` | Invoke all `agent` values in one parent turn |
 
+Optional top-level **`specMode`:** `consume` | `generate` | `none` (router echo; `brief.md` `## Spec mode` wins).
+
 ## status.json (pipeline mode)
 
 ```json
@@ -112,6 +116,13 @@ Bootstrap `<slug>/` by **writing** `pipeline.json` (Write tool). Runtime/hook ow
 
 Commit task artifacts if you want them to survive `ai-rules clean cursor`. Or copy finished tasks to `docs/agent-workflow/tasks/<slug>/`.
 
+
+## 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 `.claude/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/claude/svelte/team/fixtures/feature-full.json

@@ -1,10 +1,15 @@
 {
   "slug": "example-feature-full",
   "intent": "feature",
+  "specMode": "consume",
   "profile": "full",
   "routingDecision": {
     "complexity": "high",
-    "riskFlags": ["cross-layer", "public-contract", "broad-test-surface"],
+    "riskFlags": [
+      "cross-layer",
+      "public-contract",
+      "broad-test-surface"
+    ],
     "routingReasons": [
       "The feature spans UI, state, and API boundaries, so architecture and implementation checkpoints are required.",
       "The public contract and e2e acceptance surface require independent validation and review."
@@ -14,15 +19,44 @@
   },
   "summary": "Multi-layer feature with e2e 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": "Validation gate", "model": "cheap" },
-    { "agent": "security-reviewer", "label": "Security review", "model": "strong" },
-    { "agent": "code-reviewer", "label": "Code review", "model": "cheap" },
-    { "agent": "qa-tester", "label": "E2E", "scope": "e2e-only" }
+    {
+      "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": "Validation gate",
+      "model": "cheap"
+    },
+    {
+      "agent": "security-reviewer",
+      "label": "Security review",
+      "model": "strong"
+    },
+    {
+      "agent": "code-reviewer",
+      "label": "Code review",
+      "model": "cheap"
+    },
+    {
+      "agent": "qa-tester",
+      "label": "E2E",
+      "scope": "e2e-only"
+    }
+  ],
+  "humanGates": [
+    "after:task-analyst"
   ],
-  "humanGates": ["after:task-analyst"],
   "autoChain": true,
   "skipped": []
 }

package/presets/claude/svelte/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 CartEmpty.tsx (code-archaeology, inferred)
+- `assumption`: no guest checkout in v1

package/presets/cursor/android-kotlin/MCP.md

@@ -13,4 +13,23 @@ Playwright / Chrome DevTools are **not** part of the **android-kotlin preset** (
 
 Do not put secrets in the file. Optional: `CONTEXT7_API_KEY` in the environment. Figma — OAuth (do not commit the token).
 
-After init: Settings → MCP → enable servers. `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/cursor/android-kotlin/agents/accessibility-reviewer.md

@@ -48,6 +48,12 @@ PASS | PASS_WITH_NOTES | FAIL
 |-----------|--------|-------|
 ```
 
+
+## 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 `.cursor/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for brief/decomposition, implementation or UI diff scope, and prior review artifacts when present.

package/presets/cursor/android-kotlin/agents/ci-investigator.md

@@ -60,6 +60,14 @@ Commands run and results.
 
 Write the owned terminal receipt described under **Artifact contract**.
 
+
+## 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.
+
+
 ## 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.md`, `decomposition.md`, and other authoritative prior artifacts for this step.

package/presets/cursor/android-kotlin/agents/debugger.md

@@ -57,6 +57,14 @@ fixApplied: false
 
 Write the owned terminal receipt described under **Artifact contract**.
 
+
+## 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.
+
+
 ## 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.md`, `decomposition.md`, and other authoritative prior artifacts for this step.

package/presets/cursor/android-kotlin/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 `.cursor/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 `.cursor/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/cursor/android-kotlin/agents/migration-specialist.md

@@ -60,6 +60,12 @@ Temporary adapters, feature flags, dual code paths if needed.
 
 Write the owned terminal receipt described under **Artifact contract**.
 
+
+## 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 `.cursor/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for `brief.md`, `decomposition.md`, and other authoritative prior artifacts for this step.

package/presets/cursor/android-kotlin/agents/performance-auditor.md

@@ -51,6 +51,12 @@ Profiler / Macrobenchmark notes, launch timings, or measured scroll hitch hints.
 Ordered list for feature-developer if fixes are requested.
 ```
 
+
+## 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 `.cursor/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the manifest entries for brief when present and the scoped git diff / screens under audit.

package/presets/cursor/android-kotlin/agents/solution-architect.md

@@ -16,6 +16,12 @@ You are a solution architect for **Android Feature modules** (Presentation / Dom
 
 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/cursor/android-kotlin/agents/task-analyst.md

@@ -34,6 +34,15 @@ Do not invent architecture or persistence stacks — frame “as in the repo”.
 
 **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 `.cursor/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 `.cursor/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 `.cursor/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/cursor/android-kotlin/agents/task-router.md

@@ -84,6 +84,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:instrumentation-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/cursor/android-kotlin/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/android-kotlin/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/android-kotlin/rules/README.md

@@ -39,6 +39,7 @@ Flat Cursor SoT. Claude twins live under `presets/claude/android-kotlin/rules/<t
 | `post-change-build.mdc` | requestable | Required after edits |
 | `security-android.mdc` | security/network | Secrets/TLS |
 | `design-guidance.mdc` | requestable | Smells/GoF |
+| `mcp-usage.mdc` | requestable | Context7 + overlay MCP |
 | `anti-sycophancy-discipline.mdc` | requestable | VERIFY discipline |
 | `code-review-mr.mdc` | requestable | MR checklist |
 | `agent-team-intake.mdc` | requestable | thin `/task` hint |
@@ -55,6 +56,7 @@ Flat Cursor SoT. Claude twins live under `presets/claude/android-kotlin/rules/<t
 | `quality/code-quality-and-refactoring.md` | `code-quality-and-refactoring.mdc` | Stack notes: Kotlin / Gradle gate |
 | `quality/anti-sycophancy-discipline.md` | `anti-sycophancy-discipline.mdc` | requestable |
 | `quality/design-guidance.md` | `design-guidance.mdc` | requestable |
+| `quality/mcp-usage.md` | `mcp-usage.mdc` | requestable Context7 + overlay MCP |
 | `agent-team/agent-team-orchestrator.md` | `agent-team-orchestrator.mdc` | instrumentation roles in Stack notes |
 | `agent-team/agent-team-intake.md` | `agent-team-intake.mdc` | thin alias |
 | `architecture/feature-delivery-workflow.md` | `feature-delivery-workflow.mdc` | Android checklist |

package/presets/cursor/android-kotlin/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 | Android Studio / AGP/Gradle modules/Android upgrades |
 | `api-contract-reviewer` | no | OpenAPI / Kotlin codegen contracts |

package/presets/cursor/android-kotlin/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/android-kotlin/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/android-kotlin/rules/feature-delivery-workflow.mdc

@@ -20,7 +20,7 @@ Deliver features in layer order. Prefer neighboring `features/<name>/` analogs.
 5. **Presentation** — ViewModel MVI/UDF + Compose screens (`state-and-viewmodels`, `compose-ui`).
 6. **Navigation** — wire launcher ports / host (`navigation-feature-launcher`).
 7. **Tests** — JVM unit tests; instrumentation when UI AC requires (`tests-unit`, `tests-ui`).
-8. **Gate** — invoke **`post-change-build`** + **`gradle-tooling`**.
+8. **Gate** — invoke **`post-change-build`** + **`gradle-tooling`**. 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.
 
 ## Layer → rule matrix
 
@@ -39,4 +39,6 @@ Deliver features in layer order. Prefer neighboring `features/<name>/` analogs.
 
 ## Related
 
+- 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`.
+
 - Product behavior discovery: requestable **`product-specs`** (`docs/specs/INDEX.md`) — do not paste the discovery algorithm here.