@bonesofspring/ai-rules 0.2.26 → 0.2.28

package/presets/opencode/ios-swift/agents/openspec-author.md

@@ -11,6 +11,21 @@ permission:
 
 Write team artifacts under `.ai.local/team/**` and scoped files (`openspec/**`). 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/ios-app-core.md`
+- `.opencode/rules/architecture-boundaries.md` — layer boundaries and allowed imports
+- `.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 an **OpenSpec** (Fission AI spec-driven SDD) author for a frontend/backend agent team.
 
 Your only writes target `openspec/**` (and team artifact manifests). Production code lives behind `feature-developer`; you are **docs / spec only**.

package/presets/opencode/ios-swift/agents/performance-auditor.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/ios-app-core.md`
+- `.opencode/rules/architecture-boundaries.md` — layer boundaries and allowed imports
+- `.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 an iOS performance auditor for a Swift/SwiftUI application.
 
 ## Inputs

package/presets/opencode/ios-swift/agents/qa-tester.md

@@ -6,6 +6,23 @@ permission:
   edit: allow
 ---
 
+## Rules to load (subagent context)
+
+This subagent does **not** inherit `opencode.json` `instructions`. Read these rules explicitly before acting:
+
+- `.opencode/rules/ios-app-core.md`
+- `.opencode/rules/architecture-boundaries.md` — layer boundaries and allowed imports
+- `.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/tests-unit.md`
+- `.opencode/rules/tests-ui.md`
+
+Also read matching `.ai.local/rules/*.md` (local overlay) for the active zone, and the project strict rules if present.
+
 You are a QA engineer for an **iOS Swift/SwiftUI** app with XCTest (or Swift Testing) unit tests and XCUITest UI tests.
 
 ## Inputs

package/presets/opencode/ios-swift/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/ios-app-core.md`
+- `.opencode/rules/architecture-boundaries.md` — layer boundaries and allowed imports
+- `.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 an iOS security reviewer for a Swift/SwiftUI application.
 
 ## Inputs

package/presets/opencode/ios-swift/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/ios-app-core.md`
+- `.opencode/rules/architecture-boundaries.md` — layer boundaries and allowed imports
+- `.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 solution architect for **iOS Feature modules** (Presentation / Domain / Data). Write `architecture.md` under `.ai.local/team/tasks/<slug>/`. No production code.
 
 ## Design rules

package/presets/opencode/ios-swift/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/ios-app-core.md`
+- `.opencode/rules/architecture-boundaries.md` — layer boundaries and allowed imports
+- `.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 senior analyst for an **iOS Swift** team. Reach **Definition of Ready** before implementation. Write only `.ai.local/team/**`. Do **not** write production code.
 
 ## Classify first

package/presets/opencode/ios-swift/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/ios-app-core.md`
+- `.opencode/rules/architecture-boundaries.md` — layer boundaries and allowed imports
+- `.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 an **iOS Swift/SwiftUI** agent team. You **do not** implement tasks — you classify intent and plan the agent pipeline.
 
 ## Inputs

package/presets/opencode/ios-swift/agents/tech-writer.md

@@ -11,6 +11,21 @@ permission:
 
 Write team artifacts under `.ai.local/team/**` and scoped files (`docs/**`). 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/ios-app-core.md`
+- `.opencode/rules/architecture-boundaries.md` — layer boundaries and allowed imports
+- `.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 technical writer for an **iOS Swift/SwiftUI** team.
 
 ## Inputs

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

@@ -6,6 +6,22 @@ permission:
   edit: allow
 ---
 
+## Rules to load (subagent context)
+
+This subagent does **not** inherit `opencode.json` `instructions`. Read these rules explicitly before acting:
+
+- `.opencode/rules/ios-app-core.md`
+- `.opencode/rules/architecture-boundaries.md` — layer boundaries and allowed imports
+- `.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/tests-unit.md`
+
+Also read matching `.ai.local/rules/*.md` (local overlay) for the active zone, and the project strict rules if present.
+
 You generate unit tests from project test plans for **iOS Swift**.
 
 ## Inputs

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

@@ -6,6 +6,22 @@ permission:
   edit: allow
 ---
 
+## Rules to load (subagent context)
+
+This subagent does **not** inherit `opencode.json` `instructions`. Read these rules explicitly before acting:
+
+- `.opencode/rules/ios-app-core.md`
+- `.opencode/rules/architecture-boundaries.md` — layer boundaries and allowed imports
+- `.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/tests-unit.md`
+
+Also read matching `.ai.local/rules/*.md` (local overlay) for the active zone, and the project strict rules if present.
+
 You debug and fix failing **iOS unit tests**.
 
 ## Inputs

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

@@ -10,6 +10,22 @@ 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/ios-app-core.md`
+- `.opencode/rules/architecture-boundaries.md` — layer boundaries and allowed imports
+- `.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/tests-unit.md`
+
+Also read matching `.ai.local/rules/*.md` (local overlay) for the active zone, and the project strict rules if present.
+
 You are a unit test planner for an **iOS** codebase using XCTest or Swift Testing.
 
 Use the **`unit-testing` skill** and `tests-unit.md`.

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

@@ -6,6 +6,22 @@ permission:
   edit: allow
 ---
 
+## Rules to load (subagent context)
+
+This subagent does **not** inherit `opencode.json` `instructions`. Read these rules explicitly before acting:
+
+- `.opencode/rules/ios-app-core.md`
+- `.opencode/rules/architecture-boundaries.md` — layer boundaries and allowed imports
+- `.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/tests-ui.md`
+
+Also read matching `.ai.local/rules/*.md` (local overlay) for the active zone, and the project strict rules if present.
+
 You generate XCUITest cases from project UI test plans.
 
 ## Inputs

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

@@ -6,6 +6,22 @@ permission:
   edit: allow
 ---
 
+## Rules to load (subagent context)
+
+This subagent does **not** inherit `opencode.json` `instructions`. Read these rules explicitly before acting:
+
+- `.opencode/rules/ios-app-core.md`
+- `.opencode/rules/architecture-boundaries.md` — layer boundaries and allowed imports
+- `.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/tests-ui.md`
+
+Also read matching `.ai.local/rules/*.md` (local overlay) for the active zone, and the project strict rules if present.
+
 You debug and fix failing **XCUITest** UI tests.
 
 ## Inputs

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

@@ -10,6 +10,22 @@ 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/ios-app-core.md`
+- `.opencode/rules/architecture-boundaries.md` — layer boundaries and allowed imports
+- `.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/tests-ui.md`
+
+Also read matching `.ai.local/rules/*.md` (local overlay) for the active zone, and the project strict rules if present.
+
 You are an expert UI test planner for an **iOS** app using XCUITest.
 
 ## Project structure

package/presets/opencode/ios-swift/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/ios-swift/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/ios-swift/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/ios-swift/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/ios-swift/hooks/chain-team-phases.sh

@@ -42,7 +42,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);
 }
@@ -69,6 +72,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');
@@ -76,6 +82,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 */ }
     }
@@ -495,7 +508,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,
@@ -522,7 +538,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) {
@@ -544,6 +560,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/ios-swift/opencode.json

@@ -1,5 +1,19 @@
 {
   "$schema": "https://opencode.ai/config.json",
+  "instructions": [
+    ".opencode/AGENTS.md",
+    ".opencode/rules/ios-app-core.md",
+    ".opencode/rules/architecture-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/ios-swift/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/ios-swift/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,11 @@ 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
+
+- Before adding a new UI control, check DesignSystem and existing components.
+- Public API: protocols and facades between features.
+- Acceptable examples: shared mapper/validation; replace force unwrap; split an overloaded ViewModel into use cases; design tokens instead of magic numbers/colors; remove a direct View→Data dependency in favor of a protocol.
+- Post-change gate: **`post-change-build.mdc`** + `xcode-tooling.mdc` (not yarn lint).
+- Style: **SwiftLint** (+ SwiftFormat when configured) — authoritative style gate; do not duplicate linter rules in prose.

package/presets/opencode/ios-swift/rules/code-review-mr.md

@@ -38,3 +38,42 @@ 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
+
+On-demand rule for review flows (not always-on).
+
+- **When to apply**
+  - Requests: “review this”, “evaluate the MR/branch/diff”, “look at the changes”.
+  - Rely on the local repository: branch, `git diff`, open files.
+
+- **What the agent must check**
+  - **Architecture and layers** (`architecture-boundaries.mdc`, `ios-app-core.mdc`):
+    - View does not call APIs and does not know DTOs.
+    - ViewModel does not depend on Data implementations directly.
+    - Domain does not import SwiftUI/UIKit.
+    - Data does not pull Presentation.
+  - **Dependencies and modules**:
+    - DI via protocols; composition root in App.
+    - No deep-import between features.
+    - Files in the correct layers (`Presentation`, `Domain`, `Data`, `DesignSystem`).
+  - **Swift and concurrency** (`swift-conventions.mdc`):
+    - `@MainActor` on UI; no unjustified force unwraps.
+    - Typed errors; correct Task cancellation where needed.
+  - **UI** (`swiftui-ui.mdc`):
+    - Thin Views; Design System tokens; accessibility identifiers for testable elements.
+  - **Networking and data** (`networking-services.mdc`):
+    - DTOs separated from domain; mappers cover edge cases.
+  - **Tests**:
+    - Non-trivial logic — unit (`tests-unit.mdc`); user flows — UI (`tests-ui.mdc`).
+    - State which tests to add or update.
+
+- **Depth and format**
+  - Focus on the **MR diff**, not the whole project.
+  - Overview first (MR goal, risks), then concrete comments with file and a fix suggestion matching repo patterns.
+  - No “big refactors” without a request (`code-quality-and-refactoring.mdc`).
+
+- **Constraints**
+  - Do not invent CI/MR hosting metadata without local data.
+  - Boy scout rule within the MR.
+  - BUGBOT automated review — see root `BUGBOT.md` (Cursor).

package/presets/opencode/ios-swift/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
+
+- Prefer protocol + composition over class inheritance hierarchies.
+- Suggest Adapter/Facade at Feature public API / DI boundaries — not inside Views.

package/presets/opencode/ios-swift/rules/feature-delivery-workflow.md

@@ -47,3 +47,69 @@ flowchart LR
 ## Zone → rules matrix
 
 Filled in the stack adapter: concrete globs/paths and `.mdc` / topic `.md` names.
+
+## Stack notes
+
+When the prompt or `brief.md` contains a `figma.com` URL, **mockup review** (`mockup-reviewer` / skill `mockup-review`) must complete — or the user must continue past FAIL/`BLOCKED_MCP` via `/task-continue` — **before UI implementation**. Non-UI tasks no-op this gate. When required-signal and **no** `figma.com`, **`ux-design.md`** (on the analysis manifest entry) must exist and not be `INCOMPLETE` before UI work — else **blocked**, hand back to `task-analyst`. Parallel to the mockup gate.
+
+Typical feature with data and UI. Layer details — `architecture-boundaries.mdc`, `ios-app-core.mdc`.
+
+## Checklist (work order)
+
+1. **Domain** — entities, value types, repository / use case protocols (`Features/**/Domain/**`).
+2. **Data** — DTOs (`Codable`), Domain ↔ DTO mappers, repository implementations, API client (`networking-services.mdc`).
+3. **ViewModel** — state, use case / protocol calls; DI from App; no DTOs or URLs (`state-and-viewmodels.mdc`).
+4. **View / navigation** — thin SwiftUI Views, Design System; navigation as in the repo (`swiftui-ui.mdc`).
+5. **Tests** — unit for mappers / use cases / VM (`tests-unit.mdc`); UI flows — XCUITest (`tests-ui.mdc`).
+6. **Completion** — **invoke** `post-change-build.mdc` (+ `xcode-tooling.mdc` for schemes/commands): build touched targets + lint/format per repo config. When the current WP spans **more than one** layer or module, `implementation.md` includes a **Code Map** (3–8 annotated paths) and **Suggested Review Order** (`concern | path:line | ≤15 word note`). Omit both for a single-file or single-layer WP.
+
+## Data flow (orientation)
+
+```mermaid
+flowchart LR
+  DTO[DTO] --> Mappers[Mappers]
+  Mappers --> Domain[Domain]
+  Domain --> Repo[Repository protocol]
+  Repo --> VM[ViewModel]
+  VM --> View[SwiftUI View]
+  DataImpl[Data impl] -.-> Repo
+```
+
+## Partial scenarios
+
+| Task | Minimum |
+|------|---------|
+| API / model only | Domain + DTO + mapper + repo impl; unit for mapper. |
+| VM / logic only | Domain protocols; mocks in tests; no HTTP in View. |
+| UI only | View + existing VM/state; no DTOs. |
+| Tests only | Specs per repo convention; do not change production without need. |
+
+## Anti-patterns
+
+- DTO / `Codable` transport types in View or ViewModel.
+- `URLSession` / concrete API client in ViewModel or View.
+- Domain imports SwiftUI / UIKit.
+- Deep-import of another feature’s internal files.
+- Assembling DI inside a View.
+- **Ubiquitous language:** Domain/type names reflect the feature domain — do not mix transport/framework terms into domain without need.
+- Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.
+- Do not mutate pipeline `status.json` / `metrics.json`; the orchestration hook is the single writer. Skills upsert the owned terminal receipt in `artifact-manifest.json`.
+
+## Matrix: zone → rules
+
+| Zone | Rules |
+|------|---------|
+| `Features/**/Domain/**`, `Core/Domain/**` | `architecture-boundaries.mdc`, `ios-app-core.mdc` |
+| `Features/**/Data/**`, `**/Network*/**` | `networking-services.mdc`, `architecture-boundaries.mdc` |
+| `*ViewModel*.swift`, Presentation state | `state-and-viewmodels.mdc` |
+| `Presentation/**`, `DesignSystem/**` | `swiftui-ui.mdc`, `architecture-boundaries.mdc` |
+| `**/*.swift` (style) | `swift-conventions.mdc` |
+| `*Tests/**` | `tests-unit.mdc` |
+| `*UITests/**` | `tests-ui.mdc` |
+| After Swift edits | `post-change-build.mdc` |
+
+When adding or extending a feature, **walk the checklist** and the table rules for touched zones.
+
+## Related
+
+- Product behavior discovery: requestable **`product-specs`** (`docs/specs/INDEX.md`) — do not paste the discovery algorithm here.

package/presets/opencode/ios-swift/rules/mcp-usage.md

@@ -84,3 +84,11 @@ 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
+
+- Pipeline **`mockup-reviewer`** is the only agent that reads Figma for mockup review. See `mockup-review`.
+- Shipped besides Context7: Figma (mockup-review pipeline). See `mockup-review`.
+- Do **not** require Storybook, Playwright, or Chrome DevTools MCP as handoffs or delivery gates.
+- Observability and ticket overlays still apply when present.
+- `init` **merges** `mcpServers`: preset keys update; extra local servers are kept.

package/presets/opencode/ios-swift/rules/mockup-review.md

@@ -105,3 +105,7 @@ PASS | PASS_WITH_NOTES | FAIL | BLOCKED_MCP
 ## AC coverage
 | Criterion | Status | Notes |
 ```
+
+## Stack notes
+
+Illustrative iOS size classes (not enforced pixels): compact / regular (e.g. small iPhone, large iPhone, iPad) mapped to small / medium / large.