@dombaras/agent-harness 0.1.0 → 0.1.1

package/templates/.agents/AGENTS.md

@@ -1,103 +1,105 @@
 # 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.
+The canonical rulebook. The always-loaded summary is `.agents/rules/00-operating.md`.
 
-## 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`).
+## 1. Fact-Based, Zero-Guessing SDLC
+
+- **Zero-Speculation Rule**: NEVER guess, hypothesize without evidence, or assume the root cause of an error, performance lag, or system behavior. Speculation is forbidden across all personas and workflow stages.
+- **Evidence-First Engineering**: Every diagnostic conclusion, fix, architectural decision, and enhancement MUST be grounded in observable facts: live server logs, telemetry traces, database records, or verified runtime execution. Know the project's debug/log endpoints — they are (or should be) recorded in `.agents/memory/locations.md`.
+- **Mandatory Telemetry Before Fixes**: If logs or telemetry are absent or insufficient, FIRST add structured instrumentation, execute or have the user reproduce, inspect the captured output, and ONLY THEN implement based on that data.
+- **Authentic Runtime Execution**: Never substitute real runtime calls with ad-hoc scripts that bypass actual config, env vars, middleware, or request pipelines. Verify through the real APIs/functions the app uses.
+- **Scientific Progression Gate**: A fix is not complete until live logs or automated runtime tests demonstrate the failure mode no longer occurs in real runtime conditions.
+
+## 2. Dynamic Data & Business-Logic Integrity
+
+- **No Hardcoded Mock Lists**: Never create hardcoded lists (fake records, mock reviews, static fallback arrays) without explicit user approval. Prefer dynamic queries and database-backed settings.
 
 ## 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).
+
+- **Zero Native Popups**: Never use `Alert.alert()`, `alert()`, `confirm()`, or `prompt()`. Use inline toasts, bottom sheets, inline state transitions, or haptics.
+- **Progressive Hydration & Cold-Start**: Never render empty states while waiting on async auth/sync. Hydrate from local cache so the UI renders immediately.
+- **The 5 Essential UI States**: Every screen/list component must handle Ideal, Empty (with CTA), Loading (skeleton), Error (retry), and Partial/single-item states.
+- **Error-Handling Contract (Mobile)**: Every `catch` block in a native screen must (1) fire an error haptic, (2) set a user-visible error state that renders inline — never `console.warn` alone, and (3) provide a retry or dismissal path. Follow the reference pattern in `.agents/skills/mobile-engineer/SKILL.md`.
+- **Cross-Screen Consistency ("Fix One, Fix All")**: When you implement a UX pattern in one screen, grep for analogous screens and apply it globally; if scope is too large, log a deferred item in the handoff with exact files/patterns. A local-only fix is a regression-in-waiting.
+- **Bidirectional & RTL**: Use logical properties (`ps-*`, `pe-*`, `ms-*`, `me-*`, `text-start`, `text-end`) never physical ones (`pl-*`, `left-*`); use inverted horizontal lists / direction-aware layout in native RTL; pass dynamic `dir` to UI primitives.
+- **Legacy Pruning & Physical Walkthrough**: When introducing a new flow/paradigm, explicitly audit and PRUNE obsolete mechanisms that contradict it — never bolt new steps on top of removed ones. Trace every physical/interaction flow step-by-step from each actor's perspective to eliminate unnecessary friction.
 
 ## 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.
+
+- **Verify Stack Versions First**: Confirm versions against `.agents/memory/stack-versions.md` before writing framework-specific code. Never assume a newer/older convention.
+- **Stack-Specific Gotchas**: Framework/library gotchas (async route params, strict-typing quirks, ORM generator/config layout, native runtime caveats) live in `.agents/memory/stack-versions.md` — read the relevant section before coding against that layer.
+- **Privacy & Visibility Tiers**: Enforce the project's tier model (`.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:`).
+
+- **When NOT to Plan**: No heavy planning docs for simple fixes, CSS/layout tweaks, or single-file changes — execute directly.
+- **Precise File Inspections**: Search first (`grep`), then read targeted line ranges — never whole 800+ line files blind. Batch independent searches/reads in parallel.
+- **Don't Re-read Unchanged Files**: Edit files already in context directly.
+- **Delegate Big Searches**: Use the `explore` subagent for broad multi-file exploration.
+- **Prefer Memory over Re-derivation**: Persist non-obvious facts to `.agents/memory/`; read the relevant memory files before starting.
+- **Locations Map**: Read `.agents/memory/locations.md` first — it is the canonical index of sessions, logs, docs, and data. Never re-hunt for a path.
+- **Step Zero — Subagent & Model Routing (non-negotiable)**: Before touching code, satisfy the dispatch gate (`.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 its own `model:`. Do NOT inline persona-owned work on the main model. Read `.agents/memory/model-routing.md` at session start. Dispatch independent subagents in parallel.
+  - **Persona map**:
+    | Work area | Persona |
+    |---|---|
+    | Task decomposition → dispatch plan | `planner` |
+    | Web app (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, data cleanup) | `qa-runner` |
+    | DB schema / data model / tenancy / sync | `system-architect` |
+    | Auth, secrets, input validation, deps | `security-engineer` |
+    | Error / performance / API debugging | `diagnostics-expert` |
+    | Features, gamification, product journeys | `product-manager` |
+    | Data ingestion / entity resolution | `data-engineer` |
+    | Deployment / cron / secrets / build+release | `devops-engineer` |
+    | Session wrap-up / handoff | `handoff` |
+  - **Waivers** (the only way to skip a persona): a persona may be skipped only when (a) the change is fully covered by an automated gate on push or in the QA tiers, AND (b) the skip is pre-audited in `.agents/memory/` with a cited pointer. Log every waiver as `waived: <persona>` with `reason: <gate|pointer>`.
+  - **Dispatch failure ladder** (never silent): retry once (resume the same `task_id`); if it still fails, do the work inline and log `degraded: <persona> model: <reason>`; never silently skip.
+- **Synchronous Terminal Commands**: Prefer sync one-shot commands (build/test/lint) that return inline, over background servers/watchers.
+- **No Output Bloat**: Never paste large files/diffs into chat; apply edits with the edit tool, never print a code block of a change.
+- **Right-Size the QA Tier**: Never run the full regression suite for a CSS/copy tweak.
+
+## 6. Smart Tiered Testing & Progression Protocol
+
+- Never run heavy regression suites blindly for small changes.
+- Split QA personas: `qa-architect` (thinks — inspects the diff, audits gaps, selects the minimal tier, authors progression tests) vs `qa-runner` (does — executes the chosen tier, reports pass/fail verbatim). The thinker never runs; the doer never designs.
+- **Static ≠ Runtime rule**: never declare UI/mobile/API changes verified from static typing alone — execute a real runtime path.
+- **Tiers** (commands are **project-provided** — the target project must define them; the harness ships only `test:dispatch` and `test:governance`):
+  | Tier | Scope | Command |
+  |---|---|---|
+  | 1 | UI/CSS/mobile/copy | `npm run test:quick` |
+  | 2 | Routes / page layout | `npm run test:routes` |
+  | 3 | API / ORM / transactions | `npm run test:api` |
+  | 4 | Data ingestion | the project's data E2E script |
+  | 5 | Major release / breaking refactor | `npm run test:verify` |
+  | 6 | Security / deps | `npm run test:security` |
+- **Progression Workflow**: for new routes/endpoints/states, (1) author a dedicated assertion path, (2) run the targeted progression test, (3) graduate it into the permanent regression suite.
+
+## 7. Definition of Done & Continuous Backup
+
+Every completed task passes this gate, in order:
+
+0. **Feature Completeness Gate**:
+   - [ ] 5 UI states handled on every affected screen (list them).
+   - [ ] No `catch` blocks that only `console.warn` without user-facing feedback.
+   - [ ] Haptic/feedback consistency for every user-initiated action.
+   - [ ] RTL traced if layout touched; logical properties used.
+   - [ ] Cross-screen audit if a new UX pattern was introduced.
+   - [ ] No modified file over ~500 lines without extracting components.
+1. **QA tier** — `qa-architect` picks the tier (and authors progression tests); `qa-runner` executes and makes it pass (§6).
+2. **Security check** — apply `security-engineer` when the change touches data/auth/input/secrets/deps.
+3. **Commit** — concise `feat:` / `fix:` / `refactor:` message.
 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`).
+- **Mechanical floor**: a pre-push hook should run `npm run test:quick` (project-provided; the harness does not install git hooks).
+- **Lean permissions**: grant only the narrowest `git`/`gh` action needed; escalate only after a command has actually failed.
+- Git may not be on PATH in the default shell — use the full path (`.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.
+
+- **One session = one coherent task**; keep a short checklist as the single source of truth.
+- **Planned vs. Shipped**: at session end, record a "planned → shipped → deferred" delta so aspirational docs are never mistaken for reality. Always verify against live code and schema.
+- **Dispatch Log (mandatory)**: every wrap-up opens with `subagent → model → shipped/deferred`. An empty log is non-compliant.
+- **Persist Continuity**: use the `handoff` skill to update `.agents/memory/handoff.md`. Project history lives in `.agents/memory/history.md`; stack facts in `.agents/memory/stack-versions.md`.
+- **Pointers Map Hygiene**: record every created/discovered/changed important location (session archives, scratch scripts, logs, docs, DB targets, env files) in `.agents/memory/locations.md`.

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

@@ -24,6 +24,6 @@ _TODO: name and outline the domain's central lifecycle/state machine._
 <!-- user progression tiers and activity badges -->
 _TODO: define user tiers and rewards._
 
-## Domain identifiers & acronyms
-<!-- ID formats (ISBN/barcode/etc.), domain-specific terms -->
+## Identifiers & acronyms
+<!-- ID formats, domain-specific terms -->
 _TODO: list identifier patterns and glossary terms._

package/templates/.agents/memory/history.md

@@ -0,0 +1,7 @@
+# Project history
+
+Durable, non-obvious project facts that don't belong in the session handoff.
+Append one line per milestone/finding with a date; keep it a pointer index, not
+a spec (code and the DB schema are the source of truth).
+
+- <YYYY-MM-DD> <fact / decision / gotcha, with file or commit ref>

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

@@ -19,6 +19,20 @@ 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.
 
+## Per-persona enforcement
+
+In addition to `model:`, agent files carry mechanical guardrails in their
+frontmatter:
+
+- **Thinkers** (`planner`, `product-manager`) have `permission: { edit: deny, bash: deny }`.
+- **`qa-architect`** has `permission: { bash: deny }` (authors tests, never runs).
+- **`handoff`** has `permission: { bash: deny }`.
+- **Deterministic personas** (`planner`, `qa-architect`, `qa-runner`, `handoff`,
+  `diagnostics-expert`) pin `temperature: 0.1`.
+- **`steps:`** caps iterations per persona (cost ceiling).
+- **`planner` / `handoff`** are `hidden: true` (orchestration-only, not in the
+  `@` menu).
+
 ## Subagent output contract
 
 Every subagent must return a single final message with, in order:
@@ -33,14 +47,16 @@ Every subagent must return a single final message with, in order:
 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`)
+## Gates
 
-`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` — `scripts/qa/check-dispatch-config.js` verifies model
+  pins, persona↔skill parity, and the output-contract marker.
+- `npm run test:governance` — `scripts/qa/governance.js` enforces the wrap-up
+  dispatch log.
+- `scripts/qa/check-qa-scripts.js` — verifies the DoD-referenced QA tier scripts
+  (project-provided) are wired into `package.json`.
 
-```
-npm run test:dispatch
-```
+Run `test:dispatch` after editing any agent/skill path.
 
 ## Gotchas
 

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

@@ -3,10 +3,33 @@
 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**: 
+
+## Web gotchas
+
+Record framework/library gotchas that bite during builds. Seed with any that
+apply to your stack; prune the rest.
+
+- **Async route params (App Router)**: dynamic route params in `page.tsx` /
+  `route.ts` are Promises — always `const { id } = await params;`.
+- **Framer Motion typing**: import the `Variants` type explicitly to avoid
+  strict-TS build failures.
+
+## ORM / DB gotchas
+
+- **Generator & config layout**: a recent ORM major renamed the client generator
+  and moved config out of `schema.prisma` (e.g. a `prisma.config.ts`). Confirm the
+  exact generator name and datasource location before editing the schema.
+- Record migrate + generate commands here once confirmed.
+
+## Mobile gotchas
+
+- **css-interop freeze race**: on `shadow-*` / `opacity-*` / `#NN` color
+  shorthand in Expo Go — prefer inline styles for animated/opacity properties.
+- **Expo Go vs dev build**: remote push notifications require an `eas` dev build
+  (Expo Go cannot receive them).
+- Record any other native/runtime caveats discovered during sessions here.

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

@@ -1,85 +1,29 @@
-# {{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.
+# {{PROJECT_NAME}} Operating Rules (summary)
+
+Always in effect. Full detail lives in `.agents/AGENTS.md`; read it before non-trivial work.
+
+## Step Zero — subagent dispatch gate (non-negotiable)
+
+Before reading or editing any file for a task, dispatch the relevant personas via the `task` tool — each runs on its own `model:` (`.opencode/agents/<name>.md`). Dispatch independent subagents in parallel; serialize only on dependencies. Keep only coordination/mechanical work (reads, git, commits) on the main model.
+
+- Persona map, waivers, and the dispatch-failure ladder: `.agents/AGENTS.md` §5 and `.agents/memory/model-routing.md`.
+- Every subagent returns the output contract (`Result` → `Evidence` → `Deferred & risks`).
+- Wrap up with a **dispatch log** (`subagent → model → shipped/deferred`) in `.agents/memory/handoff.md`.
+
+## Non-negotiable laws
+
+1. **Zero speculation** — base every fix/decision on observed logs, telemetry, or DB state; instrument first if evidence is missing.
+2. **No hardcoded mocks/fallback data** — prefer dynamic queries and database-backed settings.
+3. **5 UI states** (ideal/empty/loading/error/partial), user-visible errors (never `console.warn`-only), and RTL-safe logical props.
+4. **Verify stack versions** before writing framework code (`.agents/memory/stack-versions.md`).
+5. **Token discipline** — search before read, targeted reads, batch reads, don't re-read unchanged files, right-size QA.
+6. **Static ≠ runtime** — never declare verified from `tsc` alone; execute a real runtime/API path.
+7. **Commit** with `feat:`/`fix:`/`refactor:` then push to main.
+
+## Definition of Done
+
+Right-sized QA tier → security lens (if the change touches data/auth/input/secrets) → commit → push.
+
+## Session checklist
+
+Start: read `.agents/memory/locations.md` + `.agents/memory/model-routing.md`. End: record the dispatch log and update the handoff memory.

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

@@ -19,8 +19,8 @@ You own catalog/data ingestion, entity resolution, and external service integrat
 ## 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.
+- Entity resolution / dedup heuristics (canonical-vs-derived matching, cross-source reconciliation).
+- External-service telemetry via the project's structured log (`.agents/memory/domain-map.md` §External sources): status, latency, rate-limit, auth errors.
 
 ## Rules
 

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

@@ -16,7 +16,7 @@ You own deployment, scheduling, secrets, and build/release pipelines — not app
 
 ## 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).
+- **Cron / scheduling**: the project's hosting cron config (e.g. a provider `crons` block; the provider typically 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.

package/templates/.agents/skills/diagnostics-expert/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: diagnostics-expert
-description: Use when debugging errors, performance regressions, or API anomalies — log-first investigation, ExternalServiceLog, cold-start profiling, authentic reproduction.
+description: Use when debugging errors, performance regressions, or API anomalies — log-first investigation, telemetry, cold-start profiling, authentic reproduction.
 model: reasoning
 ---
 
@@ -12,9 +12,9 @@ You are a Site Reliability & Diagnostics Engineer. You solve bugs, race conditio
 
 ### 1. Zero Guessing & Log-First Rule
 - **Never guess root causes**.
-- Always inspect the live server output, client telemetry (`scratch/mobile-debug.log`), or query `ExternalServiceLog` in PostgreSQL before forming a hypothesis:
+- Always inspect the live server output, client telemetry, and the project's structured external-service log (see `.agents/memory/domain-map.md` §External sources and `.agents/memory/locations.md` for log paths) before forming a hypothesis:
   ```ts
-  // Inspect external services or server activity
+  // Inspect the project's structured external-service / telemetry log
   const logs = await prisma.externalServiceLog.findMany({
     orderBy: { createdAt: 'desc' },
     take: 10
@@ -24,20 +24,19 @@ You are a Site Reliability & Diagnostics Engineer. You solve bugs, race conditio
 
 ### 2. Missing Logs? Instrument First
 - If existing logs do not pinpoint why an API returned an unexpected response or why a client UI stalled:
-  1. Add structured telemetry statements via `logDebug(tag, payload)` or `console.log('[DEBUG_TAG]', { ... })`.
-  2. For mobile issues, utilize the `/api/debug/logs` collector to record device traces into `scratch/mobile-debug.log`.
+  1. Add structured telemetry via the project's logger (e.g. `logDebug(tag, payload)` or `console.log('[DEBUG_TAG]', { ... })`).
+  2. For mobile issues, use the project's device-log collector (`.agents/memory/locations.md`) to capture traces.
   3. Execute the operation (or ask the user to reproduce) and inspect the captured log file.
   4. Formulate the fix solely from the concrete failure point observed in the telemetry.
 
 ### 3. Authentic API & Client Reproduction
 - Never write ad-hoc external test scripts that execute standalone HTTP fetch requests bypassing auth context, cookies, or headers.
-- Always execute operations through the actual application functions (e.g. `api.sync(userId)`, `api.searchCatalog(query)`).
+- Always execute operations through the actual application functions (e.g. `api.sync(userId)`, `api.search(query)`).
 
 ### 4. Performance & Cold-Start Profiling
 - Measure the time taken across each layer:
-  1. Local storage read (`AsyncStorage`).
+  1. Local storage read (cache/AsyncStorage/SQLite).
   2. Network round-trip (`fetch` duration).
-  3. Database query resolution (`Prisma`).
+  3. Database query resolution (ORM).
   4. React rendering & layout calculation.
 - Eliminate duplicate API calls on component mount by using memoized hydration listeners or local caches.
-

package/templates/.agents/skills/handoff/SKILL.md

@@ -15,8 +15,8 @@ You are the session continuity keeper. When the user asks to save progress or wr
    - **Planned**: what was intended.
    - **Shipped**: what was actually implemented/verified (cite files + commit hash).
    - **Deferred**: what was consciously left out, with a one-line reason.
-3. **Record it** in `.agents/memory/handoff.md` (tracked file). Keep the file short (last session only). Move any durable notes into `.agents/memory/` topic files (e.g. `stack-versions.md`, `antigravity-history.md`) rather than growing the handoff.
-4. **Update the locations map** — `.agents/memory/locations.md` is the canonical index of where sessions, logs, docs, and data live. Add/refresh an entry for every external location this session created, discovered, or changed (AI session archives, scratch scripts, log files, DB targets, env files, docs). Each front-end (Antigravity, Continue, Copilot, Claude, Roo, Windsurf) records its own session paths. If nothing changed, leave it as-is.
+3. **Record it** in `.agents/memory/handoff.md` (tracked file). Keep the file short (last session only). Move any durable notes into `.agents/memory/` topic files (e.g. `stack-versions.md`, `history.md`) rather than growing the handoff.
+4. **Update the locations map** — `.agents/memory/locations.md` is the canonical index of where sessions, logs, docs, and data live. Add/refresh an entry for every external location this session created, discovered, or changed (AI session archives, scratch scripts, log files, DB targets, env files, docs). Each agent front-end records its own session paths. If nothing changed, leave it as-is.
 5. **Never invent** — mark anything uncertain as "unverified".
 
 ## Template

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

@@ -18,8 +18,8 @@ You own the native React Native layer and its gotchas — not shared web UI (tha
 
 - Exact runtime versions live in `.agents/memory/stack-versions.md` (Expo SDK, React Native, React, expo-router, nativewind, reanimated, worklets). Verify before writing.
 - `newArchEnabled` defaults may be `false` for the Expo Go runtime — do not assume Fabric.
-- css-interop can have a JS-thread freeze race on `shadow-*`/`opacity-*`/`#NN` color shorthand in Expo Go — read `.agents/memory/css-interop-freeze.md`; prefer inline styles for animated/opacity properties.
-- Read `.agents/memory/mobile-expo-notes.md` before starting.
+- css-interop can have a JS-thread freeze race on `shadow-*`/`opacity-*`/`#NN` color shorthand in Expo Go — see `.agents/memory/stack-versions.md` (§Mobile gotchas); prefer inline styles for animated/opacity properties.
+- Read `.agents/memory/stack-versions.md` before starting.
 
 ## Rules