@bonesofspring/ai-rules 0.2.26 → 0.2.28

package/presets/opencode/java/skills/technical-retro/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: technical-retro
-description: Facilitates technical retrospectives for tasks, sprints, incidents, releases, and agent-team pipelines. Use when the user asks for retro, postmortem, process review, or action items after delivery.
+description: "Facilitates technical retrospectives for tasks, sprints, incidents, releases, and agent-team pipelines. Use when the user asks for retro, postmortem, process review, or action items after delivery."
 ---
 
 # Technical Retro

package/presets/opencode/java/skills/unit-testing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: unit-testing
-description: Plans, generates, and heals parameterized JUnit unit tests for domain, use cases, and mappers using *Test.java and tests-unit rules. Use for unit-test planning, generation, or healing.
+description: "Plans, generates, and heals parameterized JUnit unit tests for domain, use cases, and mappers using *Test.java and tests-unit rules. Use for unit-test planning, generation, or healing."
 ---
 
 # Unit testing (Java)

package/presets/opencode/java/skills/write-adr/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: write-adr
-description: Author an Architecture Decision Record (ADR) with Context, Decision, Consequences, and Links. Use when capturing a durable technical choice for the team.
+description: "Author an Architecture Decision Record (ADR) with Context, Decision, Consequences, and Links. Use when capturing a durable technical choice for the team."
 ---
 
 # Write ADR

package/presets/opencode/mcp-ts/OPENCODE.md

@@ -24,6 +24,19 @@ Root `AGENTS.md` is native always-on. Read it first, then this file.
 
 See `.opencode/rules/README.md` for the full catalog and loading strategy.
 
+## Harness wiring
+
+- `opencode.json` carries a compact `instructions` list (always-on rule
+  paths + `.opencode/AGENTS.md`) and a harness-level `permission.bash`
+  block. On re-init, `mergeOpencodeConfig` unions preset instruction paths
+  into the consumer list and fills missing bash keys. Extra paths and
+  same-key overrides stay.
+- **Subagent rules** are re-declared inside every `.opencode/agents/*.md`
+  via the `## Rules to load (subagent context)` block (always-on + zone
+  rules filtered to stems that exist for this stack). `Task`-launched
+  subagents do not inherit the parent's `instructions`, so this block
+  is the authoritative mechanism.
+
 **Platform docs:** published with the `@bonesofspring/ai-rules` package
 (`docs/OPENCODE.md`, `docs/OPENCODE-COMPATIBILITY.md`) — **not** copied into
 the consumer repo. Source: https://github.com/bonesofspring/ai-rules
@@ -48,4 +61,5 @@ npx @bonesofspring/ai-rules init opencode --preset mcp-ts
 
 Copies rules, commands, agents, hooks, skills, `OPENCODE.md` →
 `.opencode/AGENTS.md`, `MCP.md`, `opencode.json` → project `opencode.json`
-(`mcp` merge), plus `REPO_AGENTS.md` → root `AGENTS.md`. Seeds `.ai.local/team/`.
+(`mcp` merge, instruction-path union, missing bash keys), plus
+`REPO_AGENTS.md` → root `AGENTS.md`. Seeds `.ai.local/team/`.

package/presets/opencode/mcp-ts/adapter-map.json

@@ -3,7 +3,7 @@
   "platform": "opencode",
   "stack": "mcp-ts",
   "semanticSource": "cursor/mcp-ts",
-  "sourceRevision": "2a33847d399e586578df7875ebcce6d5f0831d0803a148691882ab21b8f45b77",
+  "sourceRevision": "8d8d5d2737c689451c222cee97747f78dc10cf47ed25126cb0d51fdf73667550",
   "entries": [
     {
       "source": "AGENTS.md",
@@ -183,7 +183,7 @@
       "category": "mcp",
       "disposition": "transform",
       "loadMode": "manual",
-      "reason": "Cursor mcp.json → opencode.json mcp (local/remote types)"
+      "reason": "Cursor mcp.json → opencode.json mcp (local/remote types); emits permission.bash + compact instructions"
     },
     {
       "source": "rules/agent-team-intake.mdc",

package/presets/opencode/mcp-ts/agents/build-verifier.md

@@ -10,6 +10,23 @@ permission:
 
 Write only team artifacts under `.ai.local/team/**`. Do not edit production code.
 
+## Rules to load (subagent context)
+
+This subagent does **not** inherit `opencode.json` `instructions`. Read these rules explicitly before acting:
+
+- `.opencode/rules/mcp-ts-app-core.md`
+- `.opencode/rules/mcp-server-boundaries.md`
+- `.opencode/rules/code-quality-and-refactoring.md`
+- `.opencode/rules/ai-local-overlay.md`
+- `.opencode/rules/feature-delivery-workflow.md` — layer order, mockup gate, ux-design gate
+- `.opencode/rules/reference-features.md` — analog files first
+- `.opencode/rules/anti-sycophancy-discipline.md` — procedural anti-sycophancy rules
+- `.opencode/rules/mcp-usage.md` — when verifying third-party APIs (Context7)
+- `.opencode/rules/mcp-ts-tooling.md`
+- `.opencode/rules/post-change-test.md`
+
+Also read matching `.ai.local/rules/*.md` (local overlay) for the active zone, and the project strict rules if present.
+
 You are the build verifier for **TypeScript MCP servers** (and for **ai-rules preset packaging** when scope says so).
 
 ## Consumer MCP repos
@@ -37,7 +54,7 @@ From `packages/ai-rules/`:
 yarn check:preset-structure
 ```
 
-Hard gates: twin-map (stacks include **mcp-ts**), token-budget (alwaysApply/session-start = 3), leakage (`MCP_TS_FORBIDDEN_IN_CHAIN`, `MCP_TS_FORBIDDEN_AGENT_STEMS`, chain forks mcp-ts≠next≠ios-swift≠go≠java≠php-hexagonal≠php-laravel), shared-core drift (`AI_RULES_DRIFT_FAIL=1` via `check:preset-structure`).
+Hard gates: twin-map (stacks include **mcp-ts**), token-budget (alwaysApply / session-start 3–5), leakage (`MCP_TS_FORBIDDEN_IN_CHAIN`, `MCP_TS_FORBIDDEN_AGENT_STEMS`, chain forks mcp-ts≠next≠ios-swift≠go≠java≠php-hexagonal≠php-laravel), shared-core drift (`AI_RULES_DRIFT_FAIL=1` via `check:preset-structure`).
 
 Document PASS/FAIL in `validation-report.md`. Soft leakage output:
 

package/presets/opencode/mcp-ts/agents/feature-developer.md

@@ -6,6 +6,28 @@ permission:
   edit: allow
 ---
 
+## Rules to load (subagent context)
+
+This subagent does **not** inherit `opencode.json` `instructions`. Read these rules explicitly before acting:
+
+- `.opencode/rules/mcp-ts-app-core.md`
+- `.opencode/rules/mcp-server-boundaries.md`
+- `.opencode/rules/code-quality-and-refactoring.md`
+- `.opencode/rules/ai-local-overlay.md`
+- `.opencode/rules/feature-delivery-workflow.md` — layer order, mockup gate, ux-design gate
+- `.opencode/rules/reference-features.md` — analog files first
+- `.opencode/rules/anti-sycophancy-discipline.md` — procedural anti-sycophancy rules
+- `.opencode/rules/mcp-usage.md` — when verifying third-party APIs (Context7)
+- `.opencode/rules/mcp-tool-design.md`
+- `.opencode/rules/mcp-contract-testing.md`
+- `.opencode/rules/mcp-auth-secrets.md`
+- `.opencode/rules/mcp-transport-packaging.md`
+- `.opencode/rules/mcp-ts-conventions.md`
+- `.opencode/rules/mcp-ts-tooling.md`
+- `.opencode/rules/post-change-test.md`
+
+Also read matching `.ai.local/rules/*.md` (local overlay) for the active zone, and the project strict rules if present.
+
 Implement MCP server features following **mcp-ts** boundaries.
 
 ## Mandatory flow

package/presets/opencode/mcp-ts/agents/security-reviewer.md

@@ -10,6 +10,21 @@ permission:
 
 Write only team artifacts under `.ai.local/team/**`. Do not edit production code.
 
+## Rules to load (subagent context)
+
+This subagent does **not** inherit `opencode.json` `instructions`. Read these rules explicitly before acting:
+
+- `.opencode/rules/mcp-ts-app-core.md`
+- `.opencode/rules/mcp-server-boundaries.md`
+- `.opencode/rules/code-quality-and-refactoring.md`
+- `.opencode/rules/ai-local-overlay.md`
+- `.opencode/rules/feature-delivery-workflow.md` — layer order, mockup gate, ux-design gate
+- `.opencode/rules/reference-features.md` — analog files first
+- `.opencode/rules/anti-sycophancy-discipline.md` — procedural anti-sycophancy rules
+- `.opencode/rules/mcp-usage.md` — when verifying third-party APIs (Context7)
+
+Also read matching `.ai.local/rules/*.md` (local overlay) for the active zone, and the project strict rules if present.
+
 Review MCP diffs against `security-mcp.md` and `mcp-auth-secrets.md`.
 
 ## Focus

package/presets/opencode/mcp-ts/agents/solution-architect.md

@@ -10,6 +10,21 @@ permission:
 
 Write only team artifacts under `.ai.local/team/**`. Do not edit production code.
 
+## Rules to load (subagent context)
+
+This subagent does **not** inherit `opencode.json` `instructions`. Read these rules explicitly before acting:
+
+- `.opencode/rules/mcp-ts-app-core.md`
+- `.opencode/rules/mcp-server-boundaries.md`
+- `.opencode/rules/code-quality-and-refactoring.md`
+- `.opencode/rules/ai-local-overlay.md`
+- `.opencode/rules/feature-delivery-workflow.md` — layer order, mockup gate, ux-design gate
+- `.opencode/rules/reference-features.md` — analog files first
+- `.opencode/rules/anti-sycophancy-discipline.md` — procedural anti-sycophancy rules
+- `.opencode/rules/mcp-usage.md` — when verifying third-party APIs (Context7)
+
+Also read matching `.ai.local/rules/*.md` (local overlay) for the active zone, and the project strict rules if present.
+
 Design MCP server changes for **mcp-ts**.
 
 ## Deliverable

package/presets/opencode/mcp-ts/agents/task-analyst.md

@@ -10,6 +10,21 @@ permission:
 
 Write only team artifacts under `.ai.local/team/**`. Do not edit production code.
 
+## Rules to load (subagent context)
+
+This subagent does **not** inherit `opencode.json` `instructions`. Read these rules explicitly before acting:
+
+- `.opencode/rules/mcp-ts-app-core.md`
+- `.opencode/rules/mcp-server-boundaries.md`
+- `.opencode/rules/code-quality-and-refactoring.md`
+- `.opencode/rules/ai-local-overlay.md`
+- `.opencode/rules/feature-delivery-workflow.md` — layer order, mockup gate, ux-design gate
+- `.opencode/rules/reference-features.md` — analog files first
+- `.opencode/rules/anti-sycophancy-discipline.md` — procedural anti-sycophancy rules
+- `.opencode/rules/mcp-usage.md` — when verifying third-party APIs (Context7)
+
+Also read matching `.ai.local/rules/*.md` (local overlay) for the active zone, and the project strict rules if present.
+
 Analyze MCP server work requests for the **mcp-ts** preset.
 
 ## Classify first

package/presets/opencode/mcp-ts/agents/task-router.md

@@ -10,6 +10,21 @@ permission:
 
 Write only team artifacts under `.ai.local/team/**`. Do not edit production code.
 
+## Rules to load (subagent context)
+
+This subagent does **not** inherit `opencode.json` `instructions`. Read these rules explicitly before acting:
+
+- `.opencode/rules/mcp-ts-app-core.md`
+- `.opencode/rules/mcp-server-boundaries.md`
+- `.opencode/rules/code-quality-and-refactoring.md`
+- `.opencode/rules/ai-local-overlay.md`
+- `.opencode/rules/feature-delivery-workflow.md` — layer order, mockup gate, ux-design gate
+- `.opencode/rules/reference-features.md` — analog files first
+- `.opencode/rules/anti-sycophancy-discipline.md` — procedural anti-sycophancy rules
+- `.opencode/rules/mcp-usage.md` — when verifying third-party APIs (Context7)
+
+Also read matching `.ai.local/rules/*.md` (local overlay) for the active zone, and the project strict rules if present.
+
 You are a task router for a **TypeScript MCP server** agent team. You **do not** implement tasks — you classify intent and plan the agent pipeline.
 
 ## Inputs

package/presets/opencode/mcp-ts/commands/spec-start.md

@@ -1,5 +1,5 @@
 ---
-description: Bootstrap or generate docs/specs (INDEX + page/feature) via task-analyst author mode. Optional docs-only path with human gate.
+description: "Bootstrap or generate docs/specs (INDEX + page/feature) via task-analyst author mode. Optional docs-only path with human gate."
 ---
 
 ## Invocation arguments

package/presets/opencode/mcp-ts/commands/task-continue.md

@@ -1,5 +1,5 @@
 ---
-description: Continue an agent-team task after a human gate, pause, or review changes request using pipeline.json and status.json.
+description: "Continue an agent-team task after a human gate, pause, or review changes request using pipeline.json and status.json."
 ---
 
 ## Invocation arguments

package/presets/opencode/mcp-ts/commands/task.md

@@ -1,5 +1,5 @@
 ---
-description: Route a natural-language task through the agent-team pipeline: task-router, pipeline.json, and the first planned specialist.
+description: "Route a natural-language task through the agent-team pipeline: task-router, pipeline.json, and the first planned specialist."
 ---
 
 ## Invocation arguments

package/presets/opencode/mcp-ts/commands/technical-retro.md

@@ -1,5 +1,5 @@
 ---
-description: Facilitate a technical retrospective for a period, incident, release, or completed agent-team task slug.
+description: "Facilitate a technical retrospective for a period, incident, release, or completed agent-team task slug."
 ---
 
 ## Invocation arguments

package/presets/opencode/mcp-ts/hooks/chain-team-phases.sh

@@ -44,7 +44,10 @@ try {
 }
 
 const slug = active.slug;
-if (!slug) {
+// Reject non-kebab / traversal slugs: the runtime writes status.json and
+// metrics.json under tasks/<slug>, so an unchecked slug could escape the tree.
+const SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+if (typeof slug !== 'string' || slug.length > 48 || !SLUG_RE.test(slug)) {
   process.stdout.write('{}');
   process.exit(0);
 }
@@ -71,6 +74,9 @@ function waitForMetricsLock() {
   // and never blocked on the lock file, so two concurrent subagentStop events
   // could both acquire the lock and corrupt metrics.json. Retry EEXIST with a
   // 10 ms sleep up to 200 attempts (2 s ceiling). On any other error, throw.
+  // A lock left behind by a killed process is reclaimed once its mtime is older
+  // than STALE_LOCK_MS, so one crash cannot brick the task forever.
+  const STALE_LOCK_MS = 30000;
   for (let attempt = 0; attempt < 200; attempt += 1) {
     try {
       const fd = fs.openSync(METRICS_LOCK, 'wx');
@@ -78,6 +84,13 @@ function waitForMetricsLock() {
       return;
     } catch (error) {
       if (!error || error.code !== 'EEXIST') throw error;
+      try {
+        const lockStat = fs.statSync(METRICS_LOCK);
+        if (Date.now() - lockStat.mtimeMs > STALE_LOCK_MS) {
+          fs.unlinkSync(METRICS_LOCK);
+          continue;
+        }
+      } catch {}
       const until = Date.now() + 10;
       while (Date.now() < until) { /* 10 ms busy-wait */ }
     }
@@ -435,7 +448,10 @@ function legacyFlow() {
 
 
 if (hookInput.action === 'end_human_gate') {
-    status.awaitingHumanGate = false;
+  // Only advance when a gate was actually open. A duplicate or retried
+  // end_human_gate must be a no-op, not a silent pipeline skip.
+  const gateWasOpen = Boolean(status.activeHumanGateEventId) || status.awaitingHumanGate === true;
+  status.awaitingHumanGate = false;
   // A2 (retro §8): pin a single runId per pipeline so subsequent events don't
   // fragment the metrics ledger across multiple runId sequences. Prefer
   // metrics.json.task.runId when metrics already exist, then status.metricsRunId,
@@ -462,7 +478,7 @@ if (hookInput.action === 'end_human_gate') {
     });
     delete status.activeHumanGateEventId;
   }
-  if (hookInput.activateNext && fs.existsSync(pipelinePath)) {
+  if (gateWasOpen && hookInput.activateNext && fs.existsSync(pipelinePath)) {
     let resumePipeline = null;
     try { resumePipeline = JSON.parse(fs.readFileSync(pipelinePath, 'utf8')); } catch {}
     if (resumePipeline) {
@@ -484,6 +500,19 @@ if (hookInput.action === 'end_human_gate') {
         else out(handoffForAgent(resumeAgents[0], resumeNext.step.scope, resumeNext.step));
         process.exit(0);
       }
+      // Gate on the final step: no executable step remains. Complete the
+      // pipeline instead of leaving it in_progress forever.
+      status.state = 'completed';
+      completeTaskMetrics();
+      writeStatus({
+        pipelineIndex: resumeSteps.length,
+        phase: 'done',
+        state: 'completed',
+        currentAgent: null,
+        awaitingHumanGate: false,
+      });
+      out(`Pipeline complete for "${slug}". Run /technical-retro ${slug}.`);
+      process.exit(0);
     }
   }
   // A2 (retro §8): if gate closes the final human gate of the pipeline

package/presets/opencode/mcp-ts/opencode.json

@@ -1,5 +1,19 @@
 {
   "$schema": "https://opencode.ai/config.json",
+  "instructions": [
+    ".opencode/AGENTS.md",
+    ".opencode/rules/mcp-ts-app-core.md",
+    ".opencode/rules/mcp-server-boundaries.md",
+    ".opencode/rules/code-quality-and-refactoring.md",
+    ".opencode/rules/ai-local-overlay.md"
+  ],
+  "permission": {
+    "bash": {
+      "*": "allow",
+      "git commit *": "deny",
+      "git push *": "deny"
+    }
+  },
   "mcp": {
     "context7": {
       "type": "local",

package/presets/opencode/mcp-ts/rules/README.md

@@ -4,8 +4,13 @@ Plain Markdown. OpenCode does **not** auto-load these files. Root `AGENTS.md`
 and `.opencode/AGENTS.md` list four essential paths to Read immediately; the
 rest are lazy-loaded when the task matches.
 
-Do not put this catalog into `opencode.json` `instructions` as the only
-always-on path (V2 may ignore that field).
+Subagent tasks (`Task`/`@name`) start blank and never read these rule files;
+the **authoritative** mechanism is the `## Rules to load (subagent context)`
+block injected into every `.opencode/agents/*.md`. The preset also adds a
+compact `opencode.json` `instructions` list (alwaysOn paths +
+`.opencode/AGENTS.md`) as a hedge for the parent context, with
+`bin/opencode-install.js` filling-if-absent on re-init; do **not** treat
+`instructions` as the only always-on path (V2 may ignore the field).
 
 ## Essential (entry-critical)
 

package/presets/opencode/mcp-ts/rules/agent-team-intake.md

@@ -9,3 +9,8 @@ When the user message looks like a **work request** (implement, add, fix, refact
 3. Pure questions (“how does X work”, “explain”) — prefer agent **`codebase-analyzer`** (explain-as-is); trivial one-liners may be answered inline. Do not open `/task`.
 
 Exceptions: user explicitly says “no pipeline”, “just do it”, or continues an active slug.
+
+## Stack notes
+
+- Scope: TypeScript MCP server modules (`src/tools|resources|prompts`, `src/index.ts`) — not Next `app/src`, iOS `Features/`, Go `cmd/`/`internal/**`, or Playwright/XCUITest UI flows.
+- **Phase 1 override:** no `codebase-analyzer` agent. For explain-as-is ("how does X work"), answer inline or load requestable MCP rules (`mcp-server-boundaries`, `mcp-tool-design`) — do **not** invoke a missing subagent.

package/presets/opencode/mcp-ts/rules/anti-sycophancy-discipline.md

@@ -21,3 +21,7 @@ Procedural rules for code generation and review. Load when writing or changing c
 15. **Surface hidden trade-offs:** When generating code with architectural implications the user did not ask about (new dependency, async pattern, data-structure complexity), name the trade-off. Do not bury it.
 16. **Match verification to risk:** Trivial → syntax/type check. Logic → manual trace. Concurrency/state → written scenario. Skipping verification proportional to risk is the failure mode.
 17. **Honest status reporting:** When asked "is X done?", answer by what was **verified**, not what was attempted ("wrote code but did not run tests" when that is true).
+
+## Stack notes
+
+- **Phase 1:** load for `feature-developer` and parent review flows only. `debugger` / `ci-investigator` are Phase-2 reserved — ignore those agent names in the shared prose above until they ship.

package/presets/opencode/mcp-ts/rules/code-quality-and-refactoring.md

@@ -14,6 +14,12 @@
 - **CUPID:** Composable; Unix philosophy (one responsibility); Predictable; Idiomatic (repo); Domain-based.
 - **Composition over inheritance;** Law of Demeter — no `a.b.c.d` chains; via public API / facade.
 
+# Over-abstraction guardrails
+
+- **No unnecessary constants:** do not hoist a one-off literal, string, or boolean into a named constant. Inline it, or use an existing token/enum when the value is meaningful and reused. Named constants are for shared, semantic, or repeated values.
+- **No invented utilities:** do not add a `utils`/helper for a single call site or a thin pass-through wrapper. Inline it or extend the existing helper; a new shared utility is justified only after the Rule of Three.
+- **Decompose over conditionals:** a unit (function, component, hook) that accumulates several branches (`if` / ternary / `switch`) should be split into smaller units with one reason to change instead of piling up conditions.
+
 # Refactoring during changes
 
 - Light refactor is OK if it reduces duplication, improves readability, and does not break public contracts.
@@ -38,3 +44,12 @@ Essentials below. Full procedural set (~17 rules) → load **`anti-sycophancy-di
 Style enforcement (formatter / linter / post-change gate) lives in the **stack toolchain** — see each adapter’s **Stack notes**.
 
 > Stack-specific lint gates, examples, and toolchain — in the preset adapter **Stack notes** section.
+
+## Stack notes
+
+- **No UI layer in this preset** — ignore shared-core bullets about design system / UI packages / CSS tokens; apply public-API and boy-scout rules to MCP registration modules and handlers.
+- Public surface: tool/resource/prompt names + JSON Schema-compatible contracts — avoid deep imports across unrelated modules.
+- Prefer Zod for authoring validation; MCP-facing schemas are protocol JSON Schema (SDK-supported conversion) — never pass raw Zod objects as the wire contract without verification.
+- Unverifiable SDK usage → `// VERIFY: @modelcontextprotocol/sdk @ <version>`.
+- Post-change gate: **`post-change-test`** + **`mcp-ts-tooling`** (repository-discovered typecheck/test — not Next lint, not Go tools, not xcodebuild).
+- Style: project ESLint/Prettier/tsc when configured — authoritative style gate; do not duplicate formatter recipes in prose.

package/presets/opencode/mcp-ts/rules/code-review-mr.md

@@ -38,3 +38,9 @@ Procedure details live in skill `code-review`. Required shape:
 - Rank by severity: **`blocker` | `important` | `nit`** (list blocker → nit).
 - Vague («looks risky») is not a finding — cite evidence or ask for surrounding file context.
 - End with a verdict on its own line: **`Safe to merge | needs changes | reject`**.
+
+## Stack notes
+
+- Check MCP boundaries: registration vs handler vs capability; schema/contract stability; no secret leakage.
+- Ban Playwright/XCUITest/Next-app path requirements in review comments for this stack.
+- **Phase 1:** no `code-reviewer` agent — parent (or `/task` review-only) applies skill `code-review` and writes `review.md`. Pipeline step name `code-reviewer` is Phase 2.

package/presets/opencode/mcp-ts/rules/design-guidance.md

@@ -97,3 +97,8 @@ Do not introduce a second stem (`refactoring-smells` / `design-patterns-for-agen
 - Ubiquitous language: `feature-delivery-workflow` (lineage).
 - MR checklist (smells in scope; pattern name only if repo uses it): `code-review-mr`.
 - Token / twin policy for authors: `preset-token-budget`, `preset-twin-sync` (meta, not consumer always-on).
+
+## Stack notes
+
+- Apply smells to MCP registration modules, handlers, and schema duplication — not UI components.
+- Prefer extract-handler / extract-schema over introducing hexagonal layers the repo does not use.

package/presets/opencode/mcp-ts/rules/mcp-usage.md

@@ -84,3 +84,10 @@ Policy is stack-class-specific — see adapter **Stack notes**. If a Figma **plu
 - Treating overlay absence as blocked (except user-required SoT)
 - Tracker/admin write tools without an explicit ask
 - Calling overlay MCP “just in case” on unrelated tasks
+
+## Stack notes
+
+- Shipped MCP is Context7 only. Do **not** require Storybook, Playwright, Chrome DevTools, or Figma as delivery gates.
+- Observability and ticket overlays still apply when present.
+- `init` **merges** `mcpServers`: preset keys update; extra local servers are kept.
+- Do not add a server-under-development to shipped consumer `mcp.json`.

package/presets/opencode/mcp-ts/rules/preset-layering.md

@@ -9,7 +9,7 @@ Rules for **preset authors** (`packages/ai-rules/presets/**`). Not always-on in
 | Layer | Where | What to put |
 |-------|-------|-------------|
 | **Core** | `presets/_shared/core/**` | Stack-agnostic prose + checklists; no frontmatter; no paths `app/**`, `Features/**`, Playwright, xcodebuild |
-| **Stack** | `presets/{cursor\|claude\|mavis\|opencode}/<stack>/` | Domain/tooling, stack always-on trio, stack examples in **Stack notes** |
+| **Stack** | `presets/{cursor\|claude\|mavis\|opencode}/<stack>/` | Domain/tooling, stack always-on set (3–5), stack examples in **Stack notes** |
 | **Platform** | Cursor `.mdc` / Claude `.md` / Mavis `.md` / OpenCode `.md` | Frontmatter (`alwaysApply`/`globs` vs `paths:` vs OpenCode `mode`/`permission`), platform-only (`BUGBOT.md`, `CLAUDE.md`) |
 
 ## Where to put a new rule

package/presets/opencode/mcp-ts/rules/preset-pr-checklist.md

@@ -12,7 +12,7 @@ Checklist for PRs that touch `packages/ai-rules/presets/**` (and dogfood `.curso
 - [ ] **Mavis derive:** mapped `cursor/<stack>/` change → `mavis/<stack>/` + `adapter-map.json` **same PR** when the stack is in `releasedStacks` (run `generate-mavis.mjs --stack <stack>` + `check-mavis-adapter-map.mjs`; see `preset-twin-sync` § Mavis derivation)
 - [ ] **OpenCode derive:** mapped `cursor/<stack>/` change → `opencode/<stack>/` + `adapter-map.json` **same PR** when the stack is in `releasedStacks` (run `generate-opencode.mjs --stack <stack>` + `check-opencode-adapter-map.mjs`; see `preset-twin-sync` § OpenCode derivation)
 - [ ] **Mapping:** `claude/<stack>/rules/README.md` mapping table is current
-- [ ] **Token budget:** Cursor `alwaysApply` ≤ 4 (4th slot reserved for `ai-local-overlay`); Claude session-start exactly 3; meta rules not always-on
+- [ ] **Token budget:** Cursor `alwaysApply` and Claude session-start both **3–5** (extra slots reserved for `ai-local-overlay`); body sum ≤200 (stretch ≤170); meta rules not always-on
 - [ ] **Local overlay coverage:** every installable stack ships `ai-local-overlay.mdc` (Cursor) and `ai-local-overlay.md` (Claude) with `MANDATORY` + acknowledgement format + `docs/LOCAL-OVERLAY.md` pointer; Claude twin listed in `claude/<stack>/rules/README.md` mapping table. Run `packages/ai-rules/scripts/check-local-overlay.sh`.
 - [ ] **Leakage:** no foreign stack agent stems / handoff strings (`preset-no-cross-stack-leakage`)
 - [ ] **Hook-only lifecycle:** `status.json` / `metrics.json` writes happen only inside `hooks/`; agents read but never rewrite lifecycle fields. Run `packages/ai-rules/scripts/check-hook-only-lifecycle.sh`.

package/presets/opencode/mcp-ts/rules/preset-token-budget.md

@@ -8,19 +8,19 @@ Invariants for rule loading in an **installed** preset (consumer app).
 
 | Platform | Always-on | Cap |
 |----------|-----------|-----|
-| Cursor | `alwaysApply: true` | **≤ 4** |
-| Claude | rules **without** `paths:` | **exactly 3** |
-| Mavis | `adapter-map` rules with `loadMode: root-entry` | **≤ 4** |
-| OpenCode | `adapter-map` rules with `loadMode: root-entry` | **≤ 4** |
+| Cursor | `alwaysApply: true` | **3–5** |
+| Claude | rules **without** `paths:` | **3–5** |
+| Mavis | `adapter-map` rules with `loadMode: root-entry` | **3–5** |
+| OpenCode | `adapter-map` rules with `loadMode: root-entry` | **3–5** |
 
-**Cursor 4th slot is reserved for `ai-local-overlay`** (consumer-owned `.ai.local/` rules). If you do not need local overlay, demote that rule to `globs: ["**/.ai.local/**"]` and revert to ≤3.
+Caps are **aligned** across platforms: minimum **3** (base invariants), maximum **5**. Slots beyond the base invariants are reserved for `ai-local-overlay` (consumer-owned `.ai.local/` rules). If you do not need local overlay, demote that rule to `globs: ["**/.ai.local/**"]` / Claude `paths:`, or a non-root load mode on Mavis / OpenCode.
 
-**Claude Option A (README exclusion):** when counting Claude rules without `paths:` / session-start, **exclude `**/README.md`** (topic indexes are not session-start rules). The intended session-start trio remains **exactly 3**; body budget sums **only those 3** rules.
+**Claude Option A (README exclusion):** when counting Claude rules without `paths:` / session-start, **exclude `**/README.md`** (topic indexes are not session-start rules). Body budget sums only the intended session-start rules (≤5).
 
 Session-start body budget:
-- Claude trio: ≤140 lines total (stretch ≤120).
-- Cursor 4-set: ≤170 lines total (4 rules including `ai-local-overlay`).
-- Mavis / OpenCode: ≤4 root-entry rule files; combined root `AGENTS.md` + platform entry ≤170 nonempty lines. Do not dump the full rule catalog into `AGENTS.md`.
+- Claude session-start: ≤200 lines total (stretch ≤170).
+- Cursor always-on: ≤200 lines total (stretch ≤170).
+- Mavis / OpenCode: ≤5 root-entry rule files; combined root `AGENTS.md` + platform entry ≤200 nonempty lines. Do not dump the full rule catalog into `AGENTS.md`.
 
 ## Meta / author rules
 
@@ -36,4 +36,4 @@ Orchestrator, feature-delivery, code-review, post-change gates, domain globs —
 
 ## Verifier
 
-build-verifier **FAIL** if Cursor `alwaysApply` count exceeds 4, Claude session-start count exceeds 3 (Claude count **excludes `**/README.md`**), or if a `preset-*` meta rule is marked always-on.
+build-verifier **FAIL** if Cursor `alwaysApply` count or Claude session-start count is outside **3–5** (Claude count **excludes `**/README.md`**), or if a `preset-*` meta rule is marked always-on.

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

@@ -110,3 +110,9 @@ Block handoff via `open_questions` until fixed:
 - 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/opencode/mcp-ts/rules/product-specs.md

@@ -54,3 +54,9 @@ Same-changeset INDEX updates, frontmatter v1, required body headings, templates,
 - 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/opencode/mcp-ts/skills/code-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: code-review
-description: Reviews MCP TypeScript diffs for boundaries, schema contracts, capability scope, and secrets. Use for MR review or when code-review workflow is requested.
+description: "Reviews MCP TypeScript diffs for boundaries, schema contracts, capability scope, and secrets. Use for MR review or when code-review workflow is requested."
 ---
 
 # Code review (mcp-ts)

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

@@ -1,6 +1,6 @@
 ---
 name: debug-investigation
-description: Investigates MCP server bugs with runtime evidence — schema failures, handler errors, transport startup. Use for failing tests or incorrect tool behavior.
+description: "Investigates MCP server bugs with runtime evidence — schema failures, handler errors, transport startup. Use for failing tests or incorrect tool behavior."
 ---
 
 <!-- shared-core: quality/debug-investigation.md -->

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

@@ -1,6 +1,6 @@
 ---
 name: feature-delivery
-description: Delivers TypeScript MCP server features end-to-end across contracts, schemas, handlers, registration, tests, and package validation. Use when implementing or extending a feature, especially through /task or feature-developer.
+description: "Delivers TypeScript MCP server features end-to-end across contracts, schemas, handlers, registration, tests, and package validation. Use when implementing or extending a feature, especially through /task or feature-developer."
 ---
 
 # Feature Delivery (mcp-ts)

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

@@ -1,6 +1,6 @@
 ---
 name: spec-authoring
-description: Author or bootstrap consumer docs/specs (INDEX, page/feature templates, frontmatter v1). Use with task-analyst author mode, /spec-start, or when brief AC requests Generate/Bootstrap.
+description: "Author or bootstrap consumer docs/specs (INDEX, page/feature templates, frontmatter v1). Use with task-analyst author mode, /spec-start, or when brief AC requests Generate/Bootstrap."
 ---
 
 # Spec authoring

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

@@ -1,6 +1,6 @@
 ---
 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.
+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

package/presets/opencode/mcp-ts/skills/unit-testing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: unit-testing
-description: Plans and writes unit tests for MCP schemas and handlers using the repository test runner. Use for schema/handler coverage and fixing failing unit tests.
+description: "Plans and writes unit tests for MCP schemas and handlers using the repository test runner. Use for schema/handler coverage and fixing failing unit tests."
 ---
 
 # Unit testing (mcp-ts)

package/presets/opencode/next/OPENCODE.md

@@ -24,6 +24,19 @@ Root `AGENTS.md` is native always-on. Read it first, then this file.
 
 See `.opencode/rules/README.md` for the full catalog and loading strategy.
 
+## Harness wiring
+
+- `opencode.json` carries a compact `instructions` list (always-on rule
+  paths + `.opencode/AGENTS.md`) and a harness-level `permission.bash`
+  block. On re-init, `mergeOpencodeConfig` unions preset instruction paths
+  into the consumer list and fills missing bash keys. Extra paths and
+  same-key overrides stay.
+- **Subagent rules** are re-declared inside every `.opencode/agents/*.md`
+  via the `## Rules to load (subagent context)` block (always-on + zone
+  rules filtered to stems that exist for this stack). `Task`-launched
+  subagents do not inherit the parent's `instructions`, so this block
+  is the authoritative mechanism.
+
 **Platform docs:** published with the `@bonesofspring/ai-rules` package
 (`docs/OPENCODE.md`, `docs/OPENCODE-COMPATIBILITY.md`) — **not** copied into
 the consumer repo. Source: https://github.com/bonesofspring/ai-rules
@@ -62,4 +75,5 @@ npx @bonesofspring/ai-rules init opencode --preset next
 
 Copies rules, commands, agents, hooks, skills, `OPENCODE.md` →
 `.opencode/AGENTS.md`, `MCP.md`, `opencode.json` → project `opencode.json`
-(`mcp` merge), plus `REPO_AGENTS.md` → root `AGENTS.md`. Seeds `.ai.local/team/`.
+(`mcp` merge, instruction-path union, missing bash keys), plus
+`REPO_AGENTS.md` → root `AGENTS.md`. Seeds `.ai.local/team/`.