@bonesofspring/ai-rules 0.2.25 → 0.2.27

package/presets/mavis/mcp-ts/rules/product-specs-authoring.md

@@ -0,0 +1,118 @@
+<!-- shared-core: architecture/product-specs-authoring.md -->
+
+# Product specs authoring
+
+Load when **Generate** or **Bootstrap** is requested (`/spec-start`, router `spec-gen`, brief AC, or analyst author mode). Discovery-only work stays on **`product-specs`**.
+
+**Optional prefix:** when the user or AC asks **research-before-spec**, load skill **`spec-discovery`** first (subset of methods; **claim-ledger** mandatory). Not the default `/task` consume path and not a new pipeline step.
+
+## Modes
+
+1. **Consume** — default; never invent INDEX/specs (see `product-specs`).
+2. **Generate** — create/update page/feature specs + INDEX rows from brief AC, user intent, Figma, or code archaeology. Inventing *product* behavior is forbidden without a stated source (AC / user / UI copy / code-observed behavior labeled `status: draft` or `inferred`).
+3. **Bootstrap** — create `INDEX.md` + `_templates/` copies + first domain spec under greenfield policy.
+
+## Greenfield policy
+
+Agents **may** create INDEX + first specs **only when** one of:
+
+1. User runs `/spec-start` or explicitly asks to bootstrap `docs/specs`.
+2. Brief/AC includes generation or bootstrap language.
+3. Router detects `spec-gen` intent.
+
+Otherwise: missing INDEX → optional tree; do **not** invent INDEX merely because discovery loaded.
+
+## Conflict precedence
+
+1. **Human gate** decision (approved brief/spec edits).
+2. **Current task `brief.md` AC** — if AC contradicts an existing spec, analyst must reconcile (update spec as `draft` or revise AC) before developer; no silent contradiction.
+3. **Approved `docs/specs/**`** — behavior SoT for feature-developer once gate passed.
+4. **Code / `.ai/context`** — discovery evidence only; never override approved spec without gate.
+
+Label inferred-from-code lines with `status: draft` until human promotes.
+
+## INDEX.md contract (v1)
+
+| Column | Required | Notes |
+|--------|----------|-------|
+| `id` | yes | Stable kebab/id matching frontmatter `id` |
+| `type` | yes | `page` \| `feature` |
+| `domain` | yes | Domain folder under `docs/specs/domains/<domain>/` |
+| `title` | yes | Human label |
+| `path` | yes | Repo-relative path to markdown file |
+| `routes` | no | Summary; may duplicate frontmatter |
+| `aliases` | no | Comma-separated PageName / deep-link aliases |
+| `status` | no | `draft` \| `active` \| `deprecated` |
+
+Layout: `docs/specs/domains/<domain>/<id>.md` (page) and optional `docs/specs/domains/<domain>/feature.md`. Adding/renaming/removing a linked file **must** update INDEX in the **same change set**.
+
+## Frontmatter v1
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `id` | string | yes | Unique; matches INDEX |
+| `type` | enum `page` \| `feature` | yes | Backend/MCP: prefer `feature` |
+| `domain` | string | yes | |
+| `routes` | string[] | yes (may be `[]`) | Web: URL paths; mobile: deep links/screens; backend: HTTP paths; mcp-ts: tool names |
+| `ui` | string[] | yes (may be `[]`) | Component/screen refs; empty on backend/mcp |
+| `store` | string[] | yes (may be `[]`) | Slice/module refs; empty when N/A |
+| `api` | string[] | yes (may be `[]`) | Services/ports/tools |
+| `aliases` | string[] | yes (may be `[]`) | |
+| `e2e` | string[] | yes (may be `[]`) | Stack-appropriate test paths |
+| `status` | enum | no | default `draft` on agent generate |
+| `owners` | string[] | no | |
+| `related` | string[] | no | Spec ids or paths |
+
+Arrays are **always present** (empty allowed). Do not omit keys for N/A stacks.
+
+## Body headings (minimum)
+
+**`page` required:** Overview; Entry / actors; Primary flows; States (loading / empty / error / success as applicable — mark N/A explicitly); Acceptance criteria (links or bullets to brief AC / product source).
+
+**`page` optional:** Analytics, Accessibility, Edge cases, Related specs.
+
+**`feature` required:** Overview; Shared behavior / constraints; Related pages (links).
+
+**`feature` optional:** Cross-cutting states, Analytics.
+
+Compliant = valid frontmatter + all required headings present (non-empty prose or explicit `N/A`) + INDEX row with resolvable `path`.
+
+## Templates & assets
+
+**Package SoT:** `packages/ai-rules/presets/_shared/assets/docs-specs/` (`INDEX.md` stub, `_templates/page.md`, `_templates/feature.md`; `schemas/frontmatter-v1.schema.json` is a documentation artifact — the checker does not evaluate it).
+
+**CLI `init`:** when consumer `docs/specs/` is **absent**, copy INDEX stub + `_templates/*` (idempotent; **never overwrite** existing INDEX). When the tree already exists, skip seed entirely.
+
+**Skill fallback:** if consumer `_templates/` missing during author mode, copy from package/skill assets before authoring.
+
+## Author roles
+
+| Role | Responsibility |
+|------|----------------|
+| **task-analyst** | Primary author (Generate + Bootstrap); INDEX bootstrap; brief **Related specs** + **Spec gaps / generation requested**; loads this stem + skill `spec-authoring`; optional skill `spec-discovery` when research-before-spec |
+| **tech-writer** | Post-delivery sync where present; never invent product behavior without AC/code source |
+| **feature-developer** | Consumes approved specs as SoT; mechanical INDEX/frontmatter fixes only on renames |
+| **mcp-ts** | No tech-writer — author + post-sync via **task-analyst** only |
+
+## Self-check before handoff (soft block)
+
+Block handoff via `open_questions` until fixed:
+
+- [ ] Required frontmatter keys present; arrays always present (may be `[]`)
+- [ ] Required body headings present (or explicit `N/A`)
+- [ ] INDEX row added/updated with resolvable `path` in the **same change set**
+- [ ] Sources cited; invented product behavior absent (or labeled `draft` / `inferred`)
+- [ ] Conflict with brief AC reconciled or flagged
+
+## Related
+
+- `product-specs` — discovery / consume
+- Skill `spec-authoring` — procedural checklist
+- Skill `spec-discovery` — opt-in research-before-spec (not default)
+- Optional consumer script `scripts/check-product-specs.sh` (ships in the npm package; WARN default; `--strict` FAIL). Bash checks INDEX links, required frontmatter keys, and body headings — it does **not** evaluate `frontmatter-v1.schema.json`
+
+## Stack notes
+
+- Author via skill `spec-authoring` + **task-analyst only** (no tech-writer on this stack).
+- `routes` = tool names; `ui`/`store` = `[]`; prefer `type: feature`.
+- Requestable — not always-on / session-start.

package/presets/mavis/mcp-ts/rules/product-specs.md

@@ -0,0 +1,62 @@
+<!-- shared-core: architecture/product-specs.md -->
+
+# Product specs (docs/specs)
+
+Product page/feature **behavior** specs live under the consumer repo `docs/specs/**`. This stem covers **discovery and presence** — not layer implementation order (see `feature-delivery-workflow`) and not code-structure mirroring (see `reference-features`).
+
+**Authoring** (Generate / Bootstrap modes, INDEX/frontmatter v1, body checklist, greenfield, conflict precedence) → load **`product-specs-authoring`** when generation is requested (`/spec-start`, brief AC, or router `spec-gen`).
+
+**Pipeline `specMode`:** `consume` (this stem) · `generate` (authoring stem) · `none` (spike/research — skip INDEX row requirement; do not invent a dummy INDEX). Primary field: `brief.md` `## Spec mode`; optional `pipeline.json` `specMode`.
+
+## Modes (summary)
+
+| Mode | When | Behavior |
+|------|------|----------|
+| **Consume** (default) | INDEX exists or globs hit `docs/specs/**` without generate intent | Discover via INDEX; soft-fail on miss; **never invent** INDEX/specs |
+| **Generate** | Explicit generate intent / AC / `/spec-start` with existing tree | Create/update page/feature specs + INDEX from stated sources |
+| **Bootstrap** | Explicit bootstrap / `/spec-start` when tree absent | Create INDEX + templates + first domain spec |
+| **None** (`specMode: none`) | Spike / research / preset-only | Skip INDEX requirement and author mode; no dummy INDEX row |
+
+Greenfield: agents may create INDEX/specs **only** on explicit intent, AC, or `/spec-start`. Missing INDEX alone does **not** authorize inventing the tree.
+
+## Presence policy
+
+- If `specMode` is **`none`** → do **not** require an INDEX row; continue from brief/AC. Do not invent INDEX.
+- If `docs/specs/INDEX.md` is **missing** → the tree is **optional** (greenfield OK for *consume*). Continue with code/brief discovery; do not invent an INDEX solely because this stem loaded.
+- If INDEX **exists** and `specMode` is not `none` → it is the **required discovery path** for work that touches a listed page, feature, route, or alias.
+
+## Discovery algorithm
+
+1. Always start at `docs/specs/INDEX.md` when present (skip when `specMode: none`).
+2. Resolve the entry by: route, stable `id`, PageName / alias, or domain folder.
+3. Read the **linked page** spec and, when INDEX or page Related links it, the optional domain `feature.md`. Do **not** dump the whole `docs/specs/**` tree into the prompt — locator = those linked files.
+
+## Miss policy (INDEX present, row or file missing)
+
+- Record the gap in `open_questions` / handoff gaps.
+- Fall back to code discovery and consumer `.ai/context/**` when present.
+- **Do not invent** product behavior, states, interactions, or contracts.
+- Hard-fail / block only when the task’s acceptance criteria explicitly require a named spec that is absent (human/gate decision).
+
+## Authoring pointer
+
+Same-changeset INDEX updates, frontmatter v1, required body headings, templates, and conflict precedence live in **`product-specs-authoring`**. Do not paste the full checklist here.
+
+## Non-goals
+
+- Not a replacement for `.ai/context/**` (external AI Code Review glossary) or `reference-features` (file-layout mirror).
+- Not Tessl / an external host as primary SoT.
+- No stack filesystem path recipes in this core body — path examples belong only in adapter **Stack notes**.
+
+## Related
+
+- `product-specs-authoring` — generation modes, contracts, self-check.
+- Skill `spec-discovery` — opt-in research-before-spec (author mode only; not default consume).
+- `reference-features` — code structure mirror (how to layout files), not product behavior.
+- Consumer `.ai/context/**` when present — review/domain glossary; cross-link, do not replace.
+
+## Stack notes
+
+- `routes`: MCP **tool names**. `ui` / `store`: `[]`. `api`: tools/handlers. `e2e`: contract/unit paths.
+- Prefer `type: feature`. **Forbidden:** requiring `app/src/ui`, Playwright paths, or Next lint recipes.
+- Requestable / `docs/specs/**` globs — not always-on / session-start.

package/presets/mavis/mcp-ts/rules/reference-features.md

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

package/presets/mavis/mcp-ts/rules/security-mcp.md

@@ -0,0 +1,43 @@
+# Security (MCP servers)
+
+- Treat tool **arguments** as **untrusted**. Validate with schemas; canonicalize paths/URLs.
+- Minimize capabilities: no default "read any file" / "fetch any URL" without AC and allowlists.
+- Secrets: env/secret manager only; redact in logs and tool results (`mcp-auth-secrets`).
+- Least privilege: each tool gets the smallest capability adapter it needs — no ambient `process.env` dumps.
+
+## Path traversal (FAIL patterns)
+
+- Resolve with `path.resolve` (or equivalent) then require the result stays under an approved root (`path.relative` must not start with `..`).
+- Deny `../`, encoded variants (`%2e%2e`), and null-byte tricks before FS access.
+- Follow symlinks only if the **final** realpath is still inside the root — otherwise reject.
+- Unit shapes: `tool.rejectsPathTraversal`, `tool.rejectsSymlinkEscape`, `tool.acceptsInRoot`.
+
+## SSRF / outbound URL (FAIL patterns)
+
+When tools fetch URLs:
+
+- Allowlist hosts (or deny by default); block metadata IP `169.254.169.254`, link-local (`169.254.0.0/16`), loopback when not explicitly local-dev, and private ranges unless AC says otherwise.
+- Do not follow redirects to a host outside the allowlist; re-validate after each hop.
+- Prefer literal IPs from a resolved allowlist over trusting DNS alone when policy requires it.
+- Unit shapes: `tool.deniesMetadataIp`, `tool.deniesBlockedHost`, `tool.allowsAllowlistedHost`.
+
+## Prompt injection and untrusted content
+
+- Tool **descriptions** and **results** must not instruct the model to ignore safety; handlers must not execute model-supplied shell without an explicit, reviewed design.
+- Treat **retrieved** tool/resource/prompt content (and any fetched remote payload) as **untrusted data**, not as authority:
+  - It must **not** expand tool capabilities, change auth/scopes, or trigger shell/network/FS side effects merely because the content contains instructions.
+  - Handlers decide actions from validated args + trusted request context only — never from natural-language directives inside resource bodies or prior tool output.
+  - Do not echo secrets found in untrusted content into logs or subsequent tool results.
+
+## Forbidden
+
+- Shipping live credentials in examples or fixtures.
+- Echoing `process.env` or Authorization headers into tool output.
+- Fail-open auth when remote transport is enabled.
+- Broad "run arbitrary command" tools without explicit AC and sandboxing.
+- Letting tool/resource text escalate privileges or bypass schema/auth checks.
+
+## Agents
+
+- `security-reviewer` on tool/auth/config/capability changes; then `post-change-test`.
+- Phase 1: feature-developer must not skip schema validation to "move faster".

package/presets/mavis/mcp-ts/rules/technical-retro.md

@@ -0,0 +1,11 @@
+<!-- shared-core: review/technical-retro.md -->
+
+# Technical retro — rule alias
+
+Full scenario (including the **“Agent work”** block for a slug from team tasks) lives in the slash command:
+
+**`commands/technical-retro.md`** → `/technical-retro`
+
+When a task has `metrics.json`, use the local aggregation script and state the cohort, sample size, incomplete artifacts, attribution confidence, active attempt duration, and human-gate wait separately. Do not score malformed artifacts or gate wait as agent work.
+
+Use this rule only if the command is unavailable. Do not duplicate the command contents in the response — follow the command file and skill `technical-retro`.

package/presets/mavis/mcp-ts/rules/tests-unit.md

@@ -0,0 +1,23 @@
+# Unit tests (MCP)
+
+- Table-driven tests for schema parse failures and handler outcomes.
+- Test **pure** handler logic with fakes for FS/network capabilities — no live MCP client required.
+- Cover invalid inputs that schemas should reject **before** side effects.
+- Prefer repository runner (Vitest/Jest/node:test) discovered via tooling rules.
+
+## Required shapes (when capability applies)
+
+- `schema.parse` / Zod: valid input; missing field; wrong type; empty string where non-empty required.
+- Path tools: reject `../` escape and symlink-outside-root (fake FS); accept in-root relative paths.
+- URL/fetch tools: deny blocked hosts (metadata IP, link-local) when allowlist is in play.
+- Auth-sensitive handlers: assert secrets never appear in returned content or thrown messages.
+
+## Forbidden smells
+
+- Hitting real external APIs in unit tests without an explicit integration harness and AC.
+- Asserting on unstable SDK private fields.
+- Browser e2e frameworks (Playwright) as the unit gate.
+
+## Naming
+
+- `toolName.validInput`, `toolName.rejectsPathTraversal`, `schema.parse.*` — follow repo style.

package/presets/mavis/mcp-ts/skills/README.md

@@ -0,0 +1,14 @@
+# Skills (mcp-ts Phase 1)
+
+| Skill | Use |
+|-------|-----|
+| `feature-delivery` | End-to-end MCP feature flow |
+| `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) |
+| `unit-testing` | Schema/handler unit tests |
+| `code-review` | Diff review checklist |
+| `debug-investigation` | Bug investigation |
+
+Phase 2 may add `ci-investigation`, `technical-retro`, `write-adr`, `mcp-contract-testing` skills.
+
+Until then: `/technical-retro` uses `commands/technical-retro.md` (no skill required); review-only uses skill `code-review` on the parent (no `code-reviewer` agent).

package/presets/mavis/mcp-ts/skills/code-review/SKILL.md

@@ -0,0 +1,12 @@
+# Code review (mcp-ts)
+
+1. Follow `code-review-mr.md`, `mcp-server-boundaries.md`, `mcp-tool-design.md`, `security-mcp.md`.
+2. Flag monolithic entry files, schema/protocol mismatches, unscopeed capabilities, secret leakage.
+3. Phase 1: security-reviewer covers threat model; no separate `code-reviewer` agent yet — parent may apply this skill directly.
+For agent team tasks, write the review artifact 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.

package/presets/mavis/mcp-ts/skills/debug-investigation/SKILL.md

@@ -0,0 +1,41 @@
+<!-- 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
+
+1. Reproduce with unit/contract fixtures before changing code.
+2. Check schema validation vs handler logic vs registration wiring.
+3. Prefer repository tests over ad-hoc Inspector-only claims.
+4. Load `anti-sycophancy-discipline` — report what was verified.
+
+### 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.

package/presets/mavis/mcp-ts/skills/feature-delivery/SKILL.md

@@ -0,0 +1,31 @@
+# Feature Delivery (mcp-ts)
+
+1. Read brief, AC, and decomposition.
+2. If `docs/specs/INDEX.md` exists **or** brief/handoff lists approved generated specs, resolve via **`product-specs`** and treat approved specs as behavior SoT before layer work (soft-fail on miss — do not invent behavior). If generation was requested but not yet approved, stop for human gate — do not implement against draft-only gaps.
+3. Follow `feature-delivery-workflow.md` + `reference-features.md`: contract → schema → handler → register → unit/contract tests → package validation.
+4. Keep transport/lifecycle in the entry module; tools stay in registration modules.
+5. After TS edits: **invoke** `post-change-test.md` (+ `mcp-ts-tooling.md`).
+
+## Do / Don't
+
+- **Do** Zod-first authoring with JSON Schema-compatible protocol contracts.
+- **Don't** invent SDK APIs; use VERIFY markers / Context7.
+- **Don't** use Playwright, XCUITest, Next lint, or Go tools as this stack's gate.
+
+## Scope discipline
+
+Implement only the current AC / decomposition task. See `feature-developer` → **Zero improvisation**.
+
+## Handoff
+
+Summarize by layer + validation. Agent team: upsert the owned terminal receipt in `artifact-manifest.json`; do not mutate `status.json`.
+
+
+## MCP usage
+
+Load requestable rule `mcp-usage` when verifying third-party library APIs (Context7) or when a local overlay MCP is present and the task fits. Discover tools at runtime; do not invent schemas. Overlay absence is not a blocker unless the user required that MCP as source of truth.
+
+
+## Design guidance
+
+- Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.

package/presets/mavis/mcp-ts/skills/spec-authoring/SKILL.md

@@ -0,0 +1,21 @@
+# Spec authoring
+
+Requestable — not always-on. Load **`product-specs`** + **`product-specs-authoring`** first.
+
+## Steps
+
+1. **Resolve mode** — Generate (tree exists) vs Bootstrap (create INDEX + templates + first spec). Refuse inventing INDEX without explicit intent/AC/`/spec-start`.
+2. **Ensure templates** — if consumer `docs/specs/_templates/` missing, copy from package SoT `presets/_shared/assets/docs-specs/_templates/` (or seeded init assets).
+3. **Fill frontmatter v1** — all array keys present (may be `[]`); prefer `type: feature` on backend/MCP; default `status: draft`.
+4. **Fill required body headings** — page: Overview, Entry/actors, Primary flows, States, Acceptance criteria; feature: Overview, Shared behavior/constraints, Related pages. Use `N/A` explicitly when needed.
+5. **Update INDEX** in the **same change set** (columns: id, type, domain, title, path, optional routes/aliases/status).
+6. **Self-check** against `product-specs-authoring` checklist; put blockers in `open_questions`.
+7. **Handoff** — list created/updated paths + INDEX diff for human gate (`after:task-analyst`). Approve before feature-developer.
+
+## Sources
+
+Cite AC / user / Figma / labeled code inference. Do not invent product behavior.
+
+## mcp-ts
+
+Analyst-only path (no tech-writer). `routes` = tool names; `ui`/`store` = `[]`.

package/presets/mavis/mcp-ts/skills/spec-discovery/SKILL.md

@@ -0,0 +1,53 @@
+# 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 `.ai.local/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: `.ai.local/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/mavis/mcp-ts/skills/unit-testing/SKILL.md

@@ -0,0 +1,11 @@
+# Unit testing (mcp-ts)
+
+1. Prefer table-driven tests for schema reject/accept and handler outcomes.
+2. Fake FS/network capabilities — no live MCP client required for unit scope.
+3. Follow `tests-unit.md` and `mcp-contract-testing.md`.
+4. Discover runner via `mcp-ts-tooling` (Vitest/Jest/node:test).
+
+## Out of scope (Phase 1)
+
+- Dedicated `contract-test-*` agents (Phase 2).
+- Browser e2e (Playwright) — forbidden.

package/presets/mavis/mcp-ts/team/README.md

@@ -0,0 +1,77 @@
+# Agent team artifacts
+
+Shared `/task` runtime for Cursor, Claude, Mavis, and OpenCode. Seeded at **`.ai.local/team/`**. Overlay must not load this tree as rules.
+
+`init` refreshes README + fixtures. It never overwrites `tasks/<slug>/`. `clean <tool>` never deletes `.ai.local/`.
+
+## Layout
+
+```
+.ai.local/team/
+  README.md
+  active-task.json           # current slug pointer (runtime)
+  fixtures/                  # pipeline profile examples
+  tasks/<slug>/
+    pipeline.json            # router-owned plan
+    status.json              # hook-owned lifecycle
+    metrics.json             # hook-owned append-only ledger
+    artifact-manifest.json   # producer receipts
+    brief.md, decomposition.md, implementation.md, review.md, …
+    .memlog.md               # optional agent notes (hook does not parse)
+```
+
+Bootstrap a slug by **writing** `pipeline.json` (editor Write tool). Do not `mkdir -p` from a sandboxed Shell. The hook owns `status.json` / `metrics.json`; agents must not patch lifecycle fields.
+
+## pipeline.json
+
+```json
+{
+  "slug": "order-history-date-filter",
+  "intent": "feature",
+  "specMode": "consume",
+  "summary": "Add date filter to Order History",
+  "steps": [
+    { "agent": "task-analyst", "label": "Clarify and decompose" },
+    { "agent": "feature-developer", "label": "Implement + unit tests", "scope": "unit-in-dev" },
+    { "agent": "build-verifier", "label": "Validation gate" },
+    { "agent": "code-reviewer", "label": "Code review" }
+  ],
+  "humanGates": ["after:task-analyst"],
+  "autoChain": true,
+  "skipped": []
+}
+```
+
+| Field | Notes |
+|-------|--------|
+| `agent` | kebab-case, or an array when `parallel: true` |
+| `scope` | e.g. `unit-in-dev`, `e2e-only` |
+| `skipIf` | `debugger.fixed` \| `ci-investigator.resolved` |
+| `model` | optional `cheap` \| `standard` \| `strong` |
+| `specMode` | `consume` \| `generate` \| `none` — `brief.md` `## Spec mode` wins |
+
+## status.json
+
+Prefer `phase: executing`. States: `in_progress`, `completed`, `awaiting_approval` (`/task-continue`), `changes_requested`, `validation_failed`.
+
+## Commands
+
+```bash
+/task <description>
+/task-continue <slug>
+/technical-retro <slug>
+```
+
+After a human gate, close wait via the **installed** hook (do not hand-edit `pipelineIndex`):
+
+```bash
+printf '%s\n' '{"status":"completed","action":"end_human_gate","activateNext":true}' | bash .mavis/hooks/chain-team-phases.sh
+```
+
+Same JSON on Claude, Mavis, or OpenCode: `bash .<tool>/hooks/chain-team-phases.sh`.
+
+## Contracts
+
+- Manifest schema: shared core `agent-team/agent-artifact-contracts.md`. Read it first; producers upsert only their IDs.
+- Metrics: append-only allowlisted events — `agent-team/agent-task-metrics.md`. Aggregate: `node packages/ai-rules/scripts/aggregate-agent-task-metrics.mjs --team-root .ai.local/team`.
+- Commit `.ai.local/team/` templates (and slugs if you want them in clones).

package/presets/mavis/mcp-ts/team/fixtures/bugfix-standard.json

@@ -0,0 +1,32 @@
+{
+  "slug": "example-schema-bugfix",
+  "intent": "bugfix",
+  "profile": "standard",
+  "summary": "Fix schema validation rejecting valid tool input",
+  "steps": [
+    {
+      "agent": "task-analyst",
+      "label": "Reproduce + AC"
+    },
+    {
+      "agent": "feature-developer",
+      "label": "Fix schema/handler + tests"
+    },
+    {
+      "agent": "build-verifier",
+      "label": "typecheck + tests"
+    }
+  ],
+  "humanGates": [],
+  "autoChain": true,
+  "skipped": [
+    {
+      "agent": "security-reviewer",
+      "reason": "Proven schema/style-only bugfix — no auth/**, secrets, or FS/net capability change (document skip; otherwise route security-reviewer)"
+    },
+    {
+      "agent": "solution-architect",
+      "reason": "Localized schema bugfix"
+    }
+  ]
+}

package/presets/mavis/mcp-ts/team/fixtures/feature-full.json

@@ -0,0 +1,36 @@
+{
+  "slug": "example-add-tool-full",
+  "intent": "feature",
+  "specMode": "consume",
+  "profile": "full",
+  "summary": "Add MCP tool with schema, handler, registration, and tests",
+  "steps": [
+    {
+      "agent": "task-analyst",
+      "label": "Brief + decomposition"
+    },
+    {
+      "agent": "feature-developer",
+      "label": "contract\u2192schema\u2192handler\u2192register\u2192test\u2192package"
+    },
+    {
+      "agent": "build-verifier",
+      "label": "typecheck + tests"
+    },
+    {
+      "agent": "security-reviewer",
+      "label": "Capability / secrets review",
+      "model": "strong"
+    }
+  ],
+  "humanGates": [
+    "after:task-analyst"
+  ],
+  "autoChain": true,
+  "skipped": [
+    {
+      "agent": "solution-architect",
+      "reason": "Straightforward tool add; architecture spike not required"
+    }
+  ]
+}