@dombaras/agent-harness 0.1.0

package/README.md

@@ -0,0 +1,77 @@
+# @dombaras/agent-harness
+
+A reusable multi-agent harness for AI-assisted development. Ships a persona
+fleet (planner, engine engineer, mobile, QA architect/runner, security,
+architecture, product, data, devops, handoff), operating rules, model routing,
+and QA gates — then deploys them into any project.
+
+> Extracted from a production project so the "agents / subagents / guardrails /
+> personas" layer is **not** an inherent part of the app codebase. It lives in its
+> own repo and is installed via `npx @dombaras/agent-harness init`.
+
+## Why
+
+- The agent harness is tooling, not application code. It should not be committed
+  into every app repo.
+- One canonical, versioned source of truth for personas/rules/QA tiers, deployed
+  on demand and updatable via `npx @dombaras/agent-harness update`.
+
+## Install & initialize
+
+```bash
+# from anywhere (uses a target dir or defaults to cwd)
+npx @dombaras/agent-harness init --target /path/to/project --name "MyApp" --domain "a widget catalog"
+
+# non-interactive
+npx @dombaras/agent-harness init --target . --yes
+```
+
+`init` writes:
+
+| Path | Content | Ownership |
+|---|---|---|
+| `AGENTS.md` | root dispatcher | harness (overwrite) |
+| `.opencode/agents/*.md` | 13 persona subagent defs (with `model:` pins) | harness (overwrite) |
+| `.agents/AGENTS.md` | full operating rulebook | harness (overwrite) |
+| `.agents/rules/00-operating.md` | always-loaded rules summary | harness (overwrite) |
+| `.agents/skills/*/SKILL.md` | persona instruction skills | harness (overwrite) |
+| `opencode.json` | main/small model routing | harness (overwrite) |
+| `scripts/qa/*` | `test:dispatch` / `test:governance` gates | harness (overwrite) |
+| `.agents/memory/*` | project data (domain-map, stack-versions, handoff, locations, model-routing) | **project** (create-if-missing) |
+| `.harness.json` | deployed version + project profile | harness |
+
+## Placeholders
+
+Templates use `{{PROJECT_NAME}}` and `{{PROJECT_DOMAIN}}`; `init` substitutes
+them from `--name` / `--domain` (or prompts, or `.harness.json`). Domain facts
+that are genuinely project-specific (entity model, catalog sources, visibility
+tiers, trust tiers) live in `.agents/memory/domain-map.md`, which `init`
+scaffolds for you to fill in — the skills reference it instead of hardcoding
+domain assumptions.
+
+## Model routing
+
+- Concrete models are set in `.opencode/agents/<name>.md` (`model:` field) and
+  `opencode.json` (`model` + `small_model`).
+- `.agents/skills/*/SKILL.md` carries a `model:` label only (informational).
+- `npx @dombaras/agent-harness list` prints the persona → model mapping.
+- `npm run test:dispatch` mechanically verifies model pins against
+  `scripts/qa/models.allowlist.txt`.
+
+## Update
+
+```bash
+npx @dombaras/agent-harness update --target /path/to/project
+```
+
+Overwrites harness-owned files, preserves `.agents/memory/*`.
+
+## Develop
+
+```bash
+node bin/agent-harness.js list
+node bin/agent-harness.js init --target /tmp/demo --name Demo --yes
+```
+
+Clear the data-test except keep `templates/` generic; do not commit a target
+project's `.agents/memory/` into this repo.

package/bin/agent-harness.js

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+"use strict";
+/*
+ * agent-harness — deploy the LibraryOS agent harness (personas, skills, rules,
+ * model routing, QA gates) into a target project.
+ *
+ * Commands:
+ *   init   [--target <dir>] [--name <project>] [--domain <desc>] [--yes]
+ *   update [--target <dir>]
+ *   list                                   (list personas + models)
+ *
+ * `init` materializes templates/ into the target and substitutes {{
+ * PROJECT_NAME }} / {{ PROJECT_DOMAIN }}. `.agents/memory/*` files are only
+ * created when absent (project data). Harness-owned files are overwritten.
+ */
+
+const fs = require("fs");
+const path = require("path");
+const readline = require("readline");
+
+const PKG = require("../package.json");
+const TEMPLATES_DIR = path.resolve(__dirname, "..", "templates");
+const CONFIG_FILE = ".harness.json";
+
+// Files the harness owns and overwrites on every run.
+// `.agents/memory/*` is project data -> create-if-missing only.
+function listFiles(dir, base = dir) {
+  const out = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const abs = path.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...listFiles(abs, base));
+    else out.push({ abs, rel: path.relative(base, abs) });
+  }
+  return out;
+}
+
+function substitute(text, vars) {
+  let out = text;
+  for (const [key, value] of Object.entries(vars)) {
+    out = out.split("{{" + key + "}}").join(value);
+  }
+  return out;
+}
+
+function isMemoryFile(rel) {
+  return rel.split(path.sep).includes(".agents") &&
+    rel.split(path.sep).includes("memory");
+}
+
+function writeFileIfAbsent(targetAbs, content) {
+  if (fs.existsSync(targetAbs)) return "skip";
+  fs.mkdirSync(path.dirname(targetAbs), { recursive: true });
+  fs.writeFileSync(targetAbs, content, "utf8");
+  return "create";
+}
+
+function readConfig(target) {
+  const p = path.join(target, CONFIG_FILE);
+  if (fs.existsSync(p)) {
+    try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch (_) { return {}; }
+  }
+  return {};
+}
+
+function ask(question, fallback) {
+  if (process.argv.includes("--yes")) return Promise.resolve(fallback || "");
+  if (!process.stdin.isTTY) return Promise.resolve(fallback || "");
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => { rl.close(); resolve(answer.trim()); });
+  });
+}
+
+function resolveVars(target, args) {
+  const existing = readConfig(target);
+  const nameFlag = args["--name"];
+  const domainFlag = args["--domain"];
+  const projectName = nameFlag || existing.projectName || path.basename(target);
+  return { projectName, domainFlag, existing, VARIABLES: { PROJECT_NAME: projectName, PROJECT_DOMAIN: domainFlag || existing.projectDomain || "" } };
+}
+
+function printPersonas(templatesDir) {
+  const agents = path.join(templatesDir, ".opencode", "agents");
+  console.log("Personas (model routing):\n");
+  for (const f of fs.readdirSync(agents).sort()) {
+    const src = fs.readFileSync(path.join(agents, f), "utf8");
+    const model = (src.match(/^model:\s*(.+)$/m) || [])[1] || "?";
+    console.log(`  ${f.replace(/\.md$/, "").padEnd(22)} -> ${model}`);
+  }
+}
+
+async function init(target, args) {
+  if (!fs.existsSync(TEMPLATES_DIR)) {
+    console.error("templates/ directory not found next to this CLI.");
+    process.exit(1);
+  }
+  const { projectName, domainFlag, VARIABLES } = resolveVars(target, args);
+
+  let projectDomain = VARIABLES.PROJECT_DOMAIN;
+  if (!domainFlag && !readConfig(target).projectDomain) {
+    projectDomain = await ask(`Project domain (one line) for "${projectName}": `, "");
+  }
+  VARIABLES.PROJECT_DOMAIN = projectDomain;
+
+  const stats = { overwritten: 0, created: 0, skipped: 0 };
+  for (const { abs, rel } of listFiles(TEMPLATES_DIR)) {
+    const content = substitute(fs.readFileSync(abs, "utf8"), VARIABLES);
+    const targetAbs = path.join(target, rel);
+    if (isMemoryFile(rel)) {
+      const r = writeFileIfAbsent(targetAbs, content);
+      if (r === "create") stats.created++; else stats.skipped++;
+    } else {
+      fs.mkdirSync(path.dirname(targetAbs), { recursive: true });
+      fs.writeFileSync(targetAbs, content, "utf8");
+      stats.overwritten++;
+    }
+  }
+
+  const config = {
+    version: PKG.version,
+    projectName,
+    projectDomain,
+    initializedAt: new Date().toISOString(),
+  };
+  fs.writeFileSync(path.join(target, CONFIG_FILE), JSON.stringify(config, null, 2) + "\n", "utf8");
+
+  console.log(`\nagent-harness v${PKG.version} initialized "${projectName}" in ${target}`);
+  console.log(`  ${stats.overwritten} harness files written, ${stats.created} memory files created, ${stats.skipped} existing memory files preserved.\n`);
+  console.log("  Next steps:");
+  console.log("   1. Fill in `.agents/memory/domain-map.md` and `.agents/memory/stack-versions.md`.");
+  console.log("   2. Add QA gate scripts to package.json:");
+  console.log('      "test:dispatch": "node scripts/qa/check-dispatch-config.js",');
+  console.log('      "test:governance": "node scripts/qa/governance.js"');
+  console.log("   3. Restart your agent CLI (config is read once at startup).\n");
+}
+
+function update(target) {
+  const { projectName, VARIABLES } = resolveVars(target, {});
+  console.log(`Updating harness in ${target} (project "${projectName}")...`);
+  return init(target, { "--name": projectName, "--domain": VARIABLES.PROJECT_DOMAIN });
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const cmd = args[0] || "help";
+  const flags = {};
+  for (let i = 1; i < args.length; i++) {
+    if (args[i] === "--target" || args[i] === "--name" || args[i] === "--domain") {
+      flags[args[i]] = args[i + 1]; i++;
+    }
+  }
+  const target = path.resolve(flags["--target"] || process.cwd());
+
+  switch (cmd) {
+    case "init":
+      init(target, flags).catch((e) => { console.error(e); process.exit(1); });
+      break;
+    case "update":
+      update(target).catch((e) => { console.error(e); process.exit(1); });
+      break;
+    case "list":
+      printPersonas(TEMPLATES_DIR);
+      break;
+    default:
+      console.log(`agent-harness v${PKG.version}\n\nUsage:\n  agent-harness init   [--target <dir>] [--name <project>] [--domain <desc>] [--yes]\n  agent-harness update [--target <dir>]\n  agent-harness list`);
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@dombaras/agent-harness",
+  "version": "0.1.0",
+  "description": "Reusable multi-agent harness for AI-assisted development: personas, skills, operating rules, model routing, and QA gates. Deploy into any project with `npx @dombaras/agent-harness init`.",
+  "bin": {
+    "agent-harness": "bin/agent-harness.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "bin/",
+    "templates/",
+    "README.md"
+  ],
+  "keywords": [
+    "opencode",
+    "agents",
+    "subagents",
+    "personas",
+    "ai-harness",
+    "claude-code",
+    "copilot"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/templates/.agents/AGENTS.md

@@ -0,0 +1,103 @@
+# Project Rules & Operating Guidelines
+
+## 1. Fact-Based, Zero-Guessing SDLC (Strict Operating Law Across All Roles & Personas)
+- **Zero-Speculation Rule**: NEVER guess, hypothesize without evidence, or assume the root cause of an error, performance lag, or system behavior. Speculation is strictly forbidden across all personas and workflow stages.
+- **Evidence-First Engineering**: Every diagnostic conclusion, bug fix, architectural decision, and feature enhancement MUST be grounded in observable facts: live server logs, telemetry traces (`/api/debug/logs`, `scratch/mobile-debug.log`), database records (`ExternalServiceLog`, Prisma queries), or verified runtime execution.
+- **Mandatory Telemetry Before Fixes**: If logs or telemetry are absent or insufficient to isolate the root cause, you MUST FIRST add structured logging/instrumentation, execute or have the user reproduce, inspect the resulting log file, and ONLY THEN implement the solution based on the captured data.
+- **Authentic Runtime Execution**: NEVER substitute real application runtime calls with ad-hoc external test scripts that might bypass actual configurations, environment variables, middleware, or request pipelines. Always test and verify behavior using the actual APIs and functions the application uses.
+- **Scientific Progression Gate**: A fix is NEVER complete until live logs or automated runtime tests explicitly demonstrate the bug is eliminated and that the failure mode no longer occurs in real runtime conditions.
+
+## 2. Dynamic Data & Business Logic Integrity
+- **No Hardcoded Mock Lists**: NEVER create hardcoded lists (e.g. fake records, mock reviews, static fallback arrays) without explicit user approval. Always prefer dynamic database queries and database-backed system settings (`SystemSetting`).
+
+## 3. UI, Mobile Ergonomics & RTL Support
+- **Zero Native Popups**: NEVER use `Alert.alert()`, `alert()`, `confirm()`, or `prompt()`. Replace all dialogs with inline toast notifications, bottom sheets, inline state transitions, or haptic feedback.
+- **Progressive Hydration & Cold-Start**: Never render empty dashboard/hub states while waiting for asynchronous auth/community sync. Always use local cache hydration (`AsyncStorage` / SQLite) so UI renders immediately without blank loading lags.
+- **The 5 Essential UI States**: Every screen and list component must explicitly handle: Ideal State, Empty State (with onboarding CTA), Loading Skeleton, Error State (with retry action), and Partial/Single-item State.
+- **Error Handling Contract (Mobile)**: Every `catch` block in a React Native screen MUST:
+  1. Trigger `Haptics.notificationAsync(NotificationFeedbackType.Error)` for tactile feedback.
+  2. Set a user-visible error state variable (e.g., `setActionError('Failed to approve loan')`) that renders an inline error banner or toast — NOT just `console.warn`.
+  3. Include a retry mechanism (re-call the failed function) or a clear dismissal path.
+  - `console.warn` alone is NEVER acceptable as error handling in production code. It is invisible to the user.
+  - **Reference pattern** (use this exact structure in every async action handler):
+    ```typescript
+    try {
+      await api.someAction(userId, ...args);
+      await Haptics.notificationAsync(Haptics.NotificationFeedbackType.Success);
+      await refreshSync();
+    } catch (err: any) {
+      await Haptics.notificationAsync(Haptics.NotificationFeedbackType.Error);
+      setActionError(err?.message || t('errors.genericRetry'));
+      // Error banner auto-renders via actionError state
+    }
+    ```
+- **Cross-Screen Consistency Rule**: Whenever you implement a UX pattern in one screen (error handling shape, haptic feedback, loading skeleton, animation style, empty state CTA), you MUST:
+  1. Grep for all other screens that have analogous patterns (e.g., all `catch` blocks, all `isLoading` states, all empty-list branches).
+  2. Apply the same pattern globally if it's missing or inconsistent.
+  3. If the scope is too large for the current session, explicitly log it as a deferred item in the handoff with the exact files and patterns that need alignment.
+  - **The "Fix One, Fix All" mandate**: A local fix applied to one screen but not others is a regression-in-waiting. If you fix an error handler in `transactions.tsx`, check `shelf.tsx`, `index.tsx`, `discover.tsx`, `community.tsx`, and `scan.tsx` for the same issue.
+- **Bidirectional & RTL Support**:
+  - Always use logical Tailwind / CSS properties (`ps-*`, `pe-*`, `ms-*`, `me-*`, `text-start`, `text-end`) instead of physical ones (`pl-*`, `pr-*`, `ml-*`, `mr-*`, `left-*`, `right-*`).
+  - In React Native RTL mode, use inverted horizontal lists (`inverted={isRTL}`) or direction-aware flex layouts so items begin on the right in Hebrew and left in English.
+  - Pass dynamic `dir={isRTL ? "rtl" : "ltr"}` to all Radix UI and shadcn primitives.
+- **Physical Paradigm Alignment & Legacy Pruning Rule**:
+  - Whenever introducing or refactoring a flow, model, or paradigm (e.g. async drop-off vs in-person handoff, neighbor trust vs stranger marketplace), you MUST explicitly audit existing steps and PRUNE legacy mechanisms that create contradictory friction with the new flow. Never bolt new features on top of obsolete verification steps without removing what they replace.
+  - Every transaction or physical interaction flow MUST be traced step-by-step through a literal physical walkthrough from both actors' perspectives to ensure zero unnecessary friction gates (such as PINs, redundant codes, or mandatory face-to-face requirements).
+
+## 4. Framework & Backend Architecture
+- **Verify Stack Versions First**: Before writing framework-specific code, confirm versions in `package.json` / `mobile/package.json` against `.agents/memory/stack-versions.md`. Never assume a newer/older framework convention; read the relevant guide in `node_modules/next/dist/docs/` (or the equivalent).
+- **Async Route Params**: Dynamic route params in the App Router (`page.tsx`, `route.ts`) are Promises: always use `const { id } = await params;`.
+- **Framer Motion Types**: Always import `Variants` from `framer-motion` to avoid TypeScript build failures.
+- **Privacy & Visibility Tiers**: Enforce the project's visibility/privacy tier model (see `.agents/memory/domain-map.md` §Visibility tiers) across all data-access endpoints.
+
+## 5. Token Efficiency & Workflow Discipline
+- **When NOT to Plan**: Do not generate heavy `implementation_plan.md` planning ceremonies for simple bug fixes, CSS/layout tweaks, single-file adjustments, or minor follow-ups. Execute directly to conserve tokens.
+- **Precise File Inspections**: Avoid reading whole 800+ line files. Use `grep_search` with line numbers to locate the relevant region, then `read_file` with targeted line ranges.
+- **Search Before Reading**: For questions about code, search first (`grep_search` / `file_search`) rather than opening files blind. Batch multiple independent searches/reads in parallel in a single turn.
+- **Don't Re-read Unchanged Files**: If a file's content is already in context, edit it directly; only re-read the specific lines you need if context is stale.
+- **Delegate Big Searches**: For broad, multi-file exploration ("where is X used?", "find all callers of Y"), use the `Explore` subagent instead of many manual search+read round-trips in the main conversation.
+- **Prefer Memory over Re-derivation**: Persist non-obvious facts to `.agents/memory/` (stack versions, gotchas, handoff state) so future sessions never re-discover them. Read relevant memory files before starting.
+- **Locations Map (read first)**: Before starting, read `.agents/memory/locations.md` — the canonical index of where sessions, logs, docs, and data live. Never re-hunt for a planning doc or a log path; it is (or should be) recorded there.
+- **Subagent & Model Routing (Step Zero — non-negotiable)**: Before reading/editing any file for a task, satisfy the dispatch gate in `.agents/rules/00-operating.md` (§"Step Zero"). Personas: `planner`, `frontend-engineer`, `mobile-engineer`, `ui-designer`, `qa-architect`, `qa-runner`, `security-engineer`, `product-manager`, `system-architect`, `diagnostics-expert`, `data-engineer`, `devops-engineer`, `handoff`. Dispatch via the `task` tool — each runs on its own `model:` from `.opencode/agents/<name>.md`. Do NOT gather deep context inline first, and do NOT inline persona-owned work on the main conversation model; use the `skill` tool only for instruction-only context. Read `.agents/memory/model-routing.md` at session start for persona→model tiers. Dispatch **independent** subagents in **parallel**; serialize only on dependencies.
+- **Synchronous Terminal Commands**: Prefer sync one-shot terminal commands (build, test, lint) that return output inline, rather than background servers/watchers, unless the process must keep running.
+- **No Output Bloat**: Never paste large files or diffs into chat unless asked. Never print a code block of a change — apply the edit with the edit tool instead.
+- **Right-Size the QA Tier**: Never run the full regression suite for a CSS/copy tweak — pick the minimal QA tier (see §6).
+
+## 6. Smart Tiered Testing & Progression Protocol (QA Architect + QA Runner)
+- NEVER run full heavy regression suites blindly for small changes.
+- Adopt the split QA personas: `qa-architect` (`.agents/skills/qa-architect/SKILL.md`) inspects the diff, audits testing gaps, selects the right-sized test plan, and authors progression tests; `qa-runner` (`.agents/skills/qa-runner/SKILL.md`) executes the chosen tier and reports pass/fail — the thinker never runs, the doer never designs:
+  - **The "Static ≠ Runtime" Rule**: Never declare UI, Mobile, or API changes verified based solely on static typing (`tsc`). Always execute live headless rendering or HTTP routes.
+  - **Tier 1 (UI, CSS, Mobile, Copy)**: Run `npm run test:quick` (Types + Translation Parity + Mobile Headless Component Smoke in ~3s).
+  - **Tier 2 (Route / Web Page layout)**: Run `npm run test:routes` or `node scripts/verify-all.js --route=<path>` (Web route render in ~4s).
+  - **Tier 3 (API, Prisma, Transactions)**: Run `npm run test:api` (API edge cases & governance in ~6s).
+  - **Tier 4 (Data Ingestion)**: Run `npx ts-node scripts/test-catalog.ts` (100-record E2E simulation).
+  - **Tier 5 (Major Release / Breaking Refactor)**: Run `npm run test:verify` (Full regression).
+  - **Tier 6 (Security / Dependencies)**: Run `npm run test:security` (`npm audit --audit-level=high`).
+- **Progression Testing Workflow**: When introducing new routes, API endpoints, or database states:
+  1. Author dedicated assertion pathways for the new feature in `scripts/verify-all.js`.
+  2. Execute the targeted progression test to verify happy path and error boundaries.
+  3. Graduate the new test into the permanent regression suite.
+
+## 7. Definition of Done & Continuous GitHub Backup
+Every completed task MUST pass this gate, in order:
+0. **Feature Completeness Gate** — before running QA, verify the change against this checklist:
+   - [ ] **5 UI States**: Does every affected screen/component handle Ideal, Empty (with CTA), Loading (skeleton), Error (user-visible + retry), and Partial states? List each state explicitly.
+   - [ ] **Error handling**: Are there any `catch` blocks that only `console.warn`/`console.error` without user-facing feedback? (Zero tolerance — every catch must have haptic + visible error state.)
+   - [ ] **Haptic consistency**: Does every user-initiated action (button press, swipe, submit) produce haptic feedback (success or error)?
+   - [ ] **RTL verification**: If the change touches layout, has it been mentally traced through the project's RTL mode? Are all spacing/alignment properties logical (`ps-*`, `ms-*`, `text-start`)?
+   - [ ] **Cross-screen audit**: If you introduced a new UX pattern (e.g., a new error banner style, a new loading skeleton, a new action handler shape), grep for all similar patterns across other screens and apply consistently.
+   - [ ] **File size check**: If the modified file exceeds 500 lines, extract new or modified sections into separate component files before committing.
+1. **QA tier** — have `qa-architect` pick the right-sized tier (and author any progression tests), then `qa-runner` execute it and make it pass (§6).
+2. **Security check** — if the change touches data access, input, auth, external services, or secrets, apply the `security-engineer` skill and run `npm run test:security` when dependencies changed.
+3. **Commit** — stage changes, commit with a concise descriptive message (`feat:`, `fix:`, `refactor:`).
+4. **Push** — `git push origin main`.
+- **Mechanical floor**: a git `pre-push` hook (husky) automatically runs `npm run test:quick` on every push — keep it green.
+- **Lean permissions**: grant only the narrowest `git`/`gh` action needed; ask for escalated permission only after a command has actually failed — never preemptively.
+- Git may not be on PATH in the default shell; use the full path to `git.exe` (see `.agents/memory/locations.md`).
+
+## 8. Session & Traceability Discipline
+- **One session = one coherent task**. Do not bundle unrelated work into a single session; keep a short task checklist as the single source of truth.
+- **Planned vs. Shipped**: At the end of each session, record a one-line "planned → shipped → deferred" delta so future agents can tell aspirational design docs from implemented reality. Never treat old planning docs as ground truth — always verify against the live code and the DB schema.
+- **Dispatch Log (mandatory)**: Every session wrap-up MUST open with a dispatch log — `subagent → model → shipped/deferred`. An empty log is a non-compliant session (Step Zero gate was skipped).
+- **Persist Continuity**: At session end, use the `handoff` skill to update `.agents/memory/handoff.md`. Project history lives in `.agents/memory/antigravity-history.md`; stack facts in `.agents/memory/stack-versions.md`.
+- **Pointers Map Hygiene**: Whenever you create, discover, or change an important location during a session — a new external AI session archive, a scratch script, a log file, a doc, a DB target, an env file — you MUST record it in `.agents/memory/locations.md` so it never becomes unfindable. Each agent front-end records its own session/log paths. The `handoff` skill's pointer step enforces this at session end.

package/templates/.agents/memory/domain-map.md

@@ -0,0 +1,29 @@
+# Domain map — {{PROJECT_NAME}}
+
+Project-specific domain facts the persona skills reference. Fill this in during
+`npx @dombaras/agent-harness init`; keep it current as the domain evolves. The skills read
+this instead of hardcoding domain assumptions.
+
+## Entity model
+<!-- canonical → edition → item chain, plus supporting entities (author, etc.) -->
+_TODO: describe the core and supporting entities and how they relate._
+
+## External sources
+<!-- data sources / integrations, auth, and rate-limit notes -->
+_TODO: list external catalog/data APIs this project ingests from._
+
+## Visibility / privacy tiers
+<!-- e.g. community / private / public — and what each permits -->
+_TODO: enumerate the access tiers and their rules._
+
+## Core state machine(s)
+<!-- the central domain process/FSM that `system-architect` governs -->
+_TODO: name and outline the domain's central lifecycle/state machine._
+
+## Trust & gamification
+<!-- user progression tiers and activity badges -->
+_TODO: define user tiers and rewards._
+
+## Domain identifiers & acronyms
+<!-- ID formats (ISBN/barcode/etc.), domain-specific terms -->
+_TODO: list identifier patterns and glossary terms._

package/templates/.agents/memory/handoff.md

@@ -0,0 +1,12 @@
+# Where we stopped (handoff)
+
+Date: <YYYY-MM-DD>
+
+## Dispatch log
+- <subagent → model → shipped/deferred> (empty log = non-compliant session)
+
+## Done this session (planned → shipped → deferred)
+- 
+
+## Still open / next
+- 

package/templates/.agents/memory/locations.md

@@ -0,0 +1,10 @@
+# Locations map
+
+Canonical index of where sessions, logs, docs, and data live. Update whenever a
+session creates, discovers, or changes an important location.
+
+- **Repos**: 
+- **Logs / telemetry**: 
+- **DB / env**: 
+- **Docs**: 
+- **AI session archives**: (each agent front-end records its own paths)

package/templates/.agents/memory/model-routing.md

@@ -0,0 +1,47 @@
+# Model routing
+
+This project's subagent personas run on their own models via the `model:`
+frontmatter in `.opencode/agents/<name>.md`. This file documents the tiering
+policy — the concrete model IDs are the source of truth in the agent files
+(and `opencode.json` for the main conversation).
+
+## Tiers (recommended — override per-project)
+
+| Tier | Purpose |
+|---|---|
+| reasoning | Planning, architecture, security review, debugging, product design, QA architecture |
+| general | Everyday coding, UI design, mobile native, infra/devops, data, QA execution |
+| mechanical | File reads, commits, handoffs |
+
+The harness ships a recommended concrete mapping (`reasoning` → a strong
+reasoning model, `general` → a strong coder model, `mechanical` → a cheap fast
+model). Change it only by editing `.opencode/agents/<name>.md` `model:` — the
+`model:` label in `.agents/skills/*/SKILL.md` is informational only and does NOT
+route models.
+
+## Subagent output contract
+
+Every subagent must return a single final message with, in order:
+
+1. **Result** — what was shipped / decided.
+2. **Evidence** — commands run or files changed with observed output.
+3. **Deferred & risks** — what remains and follow-ups the orchestrator must handle.
+
+## Dispatch failure ladder (never silent)
+
+1. Retry once (resume the same `task_id`).
+2. Degrade inline on the main model and log `degraded: <persona> model: <reason>`.
+3. Never silently skip or re-scope — only waive via the explicit waiver path.
+
+## Dispatch preflight (`npm run test:dispatch`)
+
+`scripts/qa/check-dispatch-config.js` verifies model pins, persona↔skill parity,
+and the output-contract marker. Run it after editing any agent/skill path:
+
+```
+npm run test:dispatch
+```
+
+## Gotchas
+
+- Restart the agent CLI after editing `opencode.json` or agent files (read once at startup).

package/templates/.agents/memory/stack-versions.md

@@ -0,0 +1,12 @@
+# Stack versions — {{PROJECT_NAME}}
+
+Confirmed framework / runtime versions. Verify against `package.json` and
+`mobile/package.json` before trusting this file.
+
+_TODO: record web framework, styling, ORM, mobile SDK/native, and key libraries with versions._
+
+- **Web**: 
+- **Styling**: 
+- **ORM / DB**: 
+- **Mobile**: 
+- **Key native libs**: 

package/templates/.agents/rules/00-operating.md

@@ -0,0 +1,85 @@
+# {{PROJECT_NAME}} Operating Rules
+
+These rules apply to the entire repository. They are enforced across all agent
+front-ends (VS Code Copilot, Claude Code, Zoo Code, Antigravity).
+
+## Step Zero — Subagent dispatch gate (NON-NEGOTIABLE)
+
+Before reading or editing any file for a task, STOP and dispatch:
+
+1. Decompose the task and identify which personas it touches using the mapping below (lookup, not judgment). For non-trivial tasks, dispatch `planner` first to emit the dispatch plan.
+2. Dispatch each persona via the `task` tool — the subagent runs on its own `model:` from `.opencode/agents/<name>.md`.
+3. Dispatch **independent** subagents in **parallel** (one message, multiple `task` calls); serialize only when one depends on another's output.
+4. Keep only coordination/mechanical work (git, commits, reads, final integration) on the main model.
+
+Do NOT gather deep context inline first — that is exactly what causes the "might as well finish inline" collapse. Skipping dispatch is a rules violation, not a style preference.
+
+> **Waivers (the ONLY way to skip a persona — explicit and recordable):** A persona may be skipped ONLY when the change is (a) fully covered by an automated gate that runs on push or in the QA tiers (`lint:hooks`, `test:schema`, `test:dispatch`, `test:governance`, `test:security`, or a peer `test:*`), AND (b) the skip was pre-audited in `.agents/memory/` with a cited pointer. Any other skip is a HIGH-severity rules violation. Every waiver MUST be written into the wrap-up dispatch log as `waived: <persona>` with `reason: <gate or pointer>`.
+>
+> **Dispatch failure ladder (never silent):** if a `task` dispatch fails, (1) retry the same task once (resume the same `task_id`); (2) if it still fails, degrade by doing the persona work inline on the main model AND log `degraded: <persona> model: <failure>` in the wrap-up dispatch log; (3) never silently re-scope or skip. Mirror in `.agents/memory/model-routing.md` §"Dispatch failure ladder".
+
+Every subagent must return the **output contract** (`result` → `evidence` → `deferred & risks`); see `.agents/memory/model-routing.md`.
+
+| Work area | Persona subagent |
+|---|---|
+| Task decomposition → dispatch plan | `planner` |
+| Web app code (React / Next.js / Tailwind / shadcn) | `frontend-engineer` |
+| Mobile native (Expo / React Native) | `mobile-engineer` |
+| Design system / tokens / shared components | `ui-designer` |
+| QA strategy (risk + tier + progression tests) | `qa-architect` |
+| QA execution (run tiers, catalog E2E, data cleanup) | `qa-runner` |
+| DB schema / data model / tenancy / sync protocol | `system-architect` |
+| Auth, secrets, input validation, external services, deps | `security-engineer` |
+| Error / performance / API debugging | `diagnostics-expert` |
+| Features, gamification, product journeys | `product-manager` |
+| Data/catalog ingestion / entity resolution | `data-engineer` |
+| Deployment / cron / secrets / build & release | `devops-engineer` |
+| Session wrap-up / handoff | `handoff` |
+
+Every session wrap-up MUST open with a **dispatch log** — `subagent → model → shipped/deferred`. An empty log is a non-compliant session.
+
+## 1. Fact-Based, Zero-Guessing SDLC — Evidence Over Speculation
+- NEVER speculate, guess, or assume the root cause of an error or system behavior across any persona.
+- Inspect live logs, telemetry (debug-log endpoints, mobile debug logs), structured telemetry records (e.g. `ExternalServiceLog`), or database state before proposing fixes.
+- If logs/telemetry are insufficient, FIRST add structured instrumentation, run it, reproduce, capture actual data, and base the fix exclusively on observed facts.
+- Verify against the real application runtime — never ad-hoc scripts that bypass real config/middleware.
+
+## 2. Data & business-logic integrity
+- NEVER create hardcoded mock lists or fake data (records, reviews, fallback arrays) without explicit approval.
+- Prefer dynamic database queries and database-backed `SystemSetting` values.
+
+## 3. UI, mobile ergonomics, RTL & flow alignment
+- NEVER use `Alert.alert()`, `alert()`, `confirm()`, or `prompt()`. Use toasts, bottom sheets, or inline states.
+- Hydrate from local cache (AsyncStorage / SQLite) so the UI never renders blank loading states.
+- Handle the 5 UI states: ideal, empty (with CTA), loading, error (with retry), partial/single-item.
+- Use logical CSS/props (`ps-*`, `ms-*`, `text-start`), never physical (`pl-*`, `left-*`).
+- In React Native RTL, use inverted horizontal lists and direction-aware flex.
+- **Legacy Pruning & Physical Roleplay Rule**: When refactoring or introducing a new flow/paradigm (e.g. async drop-off vs in-person handoff), ALWAYS audit and prune contradictory legacy friction steps (e.g. PINs, redundant codes) and roleplay the physical real-world user journey step-by-step.
+
+## 4. Stack — verify versions first
+- Never assume framework versions from memory. Read `.agents/memory/stack-versions.md` (the project-specific version manifest) before writing framework code.
+- Read the relevant framework guide shipped in `node_modules/<framework>/dist/docs/` (if present) before writing against it; heed deprecation notices.
+- Framework-specific gotchas (e.g. async route params, strict typing) live in the `frontend-engineer` / `mobile-engineer` skills.
+
+## 5. Token & workflow discipline
+- No heavy planning docs for simple fixes.
+- Search before reading; use targeted line reads; batch independent searches/reads.
+- Delegate broad searches; persist non-obvious facts to `.agents/memory/`.
+- **Subagent & model routing**: Satisfy the **Step Zero dispatch gate** (top of this file) before touching any code. Read `.agents/memory/model-routing.md` at session start for the persona→concrete-model tiers. Do NOT inline persona-owned work in the main conversation; load a persona via the `skill` tool only for instruction-only context.
+
+## 6. Testing — right-sized QA tier & Static ≠ Runtime rule
+- Never declare code verified based solely on static typing (`tsc`); always execute runtime component or API pathways.
+- Tier 1: `npm run test:quick` (Types + Translations + Mobile Headless Render Smoke in ~3s) · Tier 2: `npm run test:routes` · Tier 3: `npm run test:api` · Tier 5: `npm run test:verify` · Tier 6: `npm run test:security`.
+- Audit testing gaps per subsystem and graduate progression tests into the permanent regression suite.
+
+## 7. Definition of Done
+1. Run the right-sized QA tier and make it pass.
+2. Apply the security lens when the change touches data, auth, input, or secrets.
+3. Commit with a concise `feat:` / `fix:` / `refactor:` message.
+4. Push to `main` (the pre-push hook runs `npm run test:quick`).
+
+## 8. Session discipline
+- One session = one coherent task.
+- At the end, record a planned → shipped → deferred delta (see `.agents/skills/handoff/SKILL.md`).
+- Every wrap-up MUST open with the **dispatch log** (`subagent → model → shipped/deferred`). Empty log = non-compliant session.
+- Read `.agents/memory/locations.md` at session start (canonical map of sessions, logs, docs, data). Update it at session end with any new/changed locations (external session archives, scratch scripts, log files, DB targets), so each front-end's data stays discoverable.

package/templates/.agents/skills/data-engineer/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: data-engineer
+description: Use for catalog/data ingestion and entity resolution — external-source ingestion, canonical-record dedup, external service telemetry.
+model: general
+---
+
+# Data / Catalog Engineer
+
+You own catalog/data ingestion, entity resolution, and external service integration — not the core domain state machine (that's `system-architect`) and not UI.
+
+> **Project specifics live in memory, not here.** Read `.agents/memory/domain-map.md` (external sources, entity model chain, canonical/dedup rules) before touching ingestion code.
+
+## Output contract (always return)
+
+1. **What changed** — files + one-line summaries.
+2. **Entity-resolution impact** — how dedup/canonicalization behavior changed and any migration seed needed.
+3. **External-service notes** — new endpoints/keys, rate-limit handling, telemetry-log coverage.
+
+## Scope
+
+- Ingest from your project's external sources (see `.agents/memory/domain-map.md` §External sources) and map them into the canonical entity chain (see §Entity model).
+- Entity resolution / dedup heuristics (canonical-vs-edition matching, cross-source reconciliation).
+- External-service telemetry via a structured log (`ExternalServiceLog`): status, latency, rate-limit, auth errors.
+
+## Rules
+
+- NEVER hardcode mock/sample data or static fallback lists — always dynamic DB queries and database-backed `SystemSetting` values.
+- New ingestion code requires a progression test at Tier 4 (data E2E simulation), handed to `qa-runner`.
+- Preserve the project's visibility tiers and the attribution of external ratings/sources (e.g. `externalRatingSource`).

package/templates/.agents/skills/devops-engineer/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: devops-engineer
+description: Use for deployment, CI/CD, cron/scheduling, env & secrets management, hosting config, and mobile build/release setup.
+model: general
+---
+
+# DevOps / Infrastructure Engineer
+
+You own deployment, scheduling, secrets, and build/release pipelines — not application logic.
+
+## Output contract (always return)
+
+1. **What changed** — config/env files + one-line summaries.
+2. **Post-deploy steps** — anything the user must do manually (add env vars, approve a build, rotate a secret).
+3. **Rollback/risk** — how to revert and what the failure mode is.
+
+## Scope
+
+- **Cron / scheduling**: the project's hosting cron config (e.g. `vercel.json` `crons`, where the provider sends a cron secret as an `Authorization: Bearer` header and never follows redirects; verify the plan's run-frequency cap).
+- **Env & secrets**: `.env` (gitignored) / `.env.example` (tracked). Never commit a real secret; document the variable in `.env.example`.
+- **Deployment**: the project's hosting config (build settings, `maxDuration`, etc.) — see `.agents/memory/locations.md` for the canonical deploy targets.
+- **Mobile releases**: `eas build`, TestFlight, Play internal track.
+
+## Rules
+
+- Verify cron cadence is idempotent before deploying (reconciliation-based, safe on duplicate/missed runs).
+- Update `.agents/memory/locations.md` if you add a new deploy/env/scheduler target.
+- Refer `npm audit` to `qa-runner` under Tier 6 (`npm run test:security`) rather than running it yourself when it's QA context.