@dombaras/agent-harness 0.1.0 → 0.1.1

package/templates/.agents/skills/product-manager/SKILL.md

@@ -11,12 +11,12 @@ You are a Lead Product Manager and UX Architect. You design intuitive, rewarding
 ## Core PM & UX Frameworks
 
 ### 1. Community Trust & Gamification System
-{{PROJECT_NAME}} operates on community trust and positive reinforcement. Define the exact tiers/badges in `.agents/memory/domain-map.md` §Trust & gamification (see the library's built-in sample: entry → participant → active → pillar, with activity badges across the core loops).
+{{PROJECT_NAME}} operates on community trust and positive reinforcement. Define the exact tiers/badges in `.agents/memory/domain-map.md` §Trust & gamification (sample progression: entry → participant → active → pillar, with activity badges across the core loops).
 
 ### 2. The 5 Essential UI States
 Every feature screen MUST explicitly define:
-1. **Ideal State**: Fully populated with books, reviews, or active loans.
-2. **Empty State**: Friendly illustration/icon + clear call-to-action (e.g. "Add your first book to start sharing").
+1. **Ideal State**: Fully populated with items, reviews, or active requests.
+2. **Empty State**: Friendly illustration/icon + clear call-to-action (e.g. "Add your first item to start sharing").
 3. **Loading State**: Contextual skeleton loaders (never empty blanks).
 4. **Error State**: Non-intrusive banner or card with a single-tap "Retry" button.
 5. **Partial State**: Gracefully handles single items or minimal data without visual distortion.
@@ -31,18 +31,18 @@ When asked to architect, review, or plan a feature, follow these phases strictly
 
 ### Phase 1: High-Level Vision & Information Architecture
 1. **Actor Mapping**: Who interacts with this feature (e.g. provider, consumer, admin)? What are their distinct goals and emotional states?
-2. **Mental Models**: Does the UI match real-world expectations (e.g. borrowing a physical book involves a physical handoff)?
+2. **Mental Models**: Does the UI match real-world expectations (e.g. borrowing a physical item involves a physical handoff)?
 3. **Cross-Platform Strategy**:
    - **Web**: density, keyboard navigation, wider information discovery.
    - **Mobile**: thumb-reachability, focused single-column tasks, native paradigms (bottom sheets over modals, swipe actions).
 
 ### Phase 2: Schema to Experience Mapping (The "No Missed States" Rule)
-1. **Enum & State Analysis**: Identify every status enum (e.g. `TxStatus`, `ItemStatus`). For every possible DB state, define what the user sees and what actions they can take.
+1. **Enum & State Analysis**: Identify every status enum (see `.agents/memory/domain-map.md` §Core state machine). For every possible DB state, define what the user sees and what actions they can take.
 2. Apply **The 5 Essential UI States** (above) to every view.
 
 ### Empty State Precondition Enumeration
 For each screen, enumerate ALL data preconditions that could result in an empty or broken state:
-- **Entry-level preconditions**: What if the user has no communities? No books? No transactions? No notifications? These are not edge cases — they are the DEFAULT state for every new user.
+- **Entry-level preconditions**: What if the user has no communities? No items? No transactions? No notifications? These are not edge cases — they are the DEFAULT state for every new user.
 - **In-screen preconditions**: What if a search returns zero results? What if a filter yields no matches?
 - **Dependency preconditions**: What if an upstream API (sync, discovery, community hub) fails or returns empty?
 
@@ -66,7 +66,7 @@ Each precondition MUST map to a specific UI state with a CTA. If you can't answe
 1. **Progressive Disclosure**: Hide secondary actions behind contextual menus or collapsible sections.
 2. **Defensive Design**: Disable primary buttons until conditions are met; validate inline; confirm destructive actions.
 3. **Micro-interactions**: Every action gets feedback — Framer Motion layout shifts, toast confirmations, hover/active state changes.
-4. **Cognitive Load Reduction**: Standardized icons, semantic colors, action-oriented microcopy ("Approve Loan", not "Submit").
+4. **Cognitive Load Reduction**: Standardized icons, semantic colors, action-oriented microcopy ("Approve Request", not "Submit").
 
 ## Phase 6: Post-Implementation Verification (run AFTER the feature is coded)
 
@@ -81,7 +81,7 @@ When a feature planned under this skill's methodology has been implemented, re-a
 ### 2. Data Precondition Completeness
 - Enumerate every data precondition that could produce an empty or degraded experience:
   - New user with zero communities → what do they see on the Community tab?
-  - User with communities but zero books → what do they see on Discovery?
+  - User with communities but zero items → what do they see on Discovery?
   - API returns 500 → does the user see an error or an infinite spinner?
 - If any precondition maps to "undefined behavior" (infinite loader, blank screen, silent failure), flag it as a blocker.
 

package/templates/.agents/skills/qa-architect/SKILL.md

@@ -28,6 +28,11 @@ You own QA **strategy** — risk assessment, tier selection, and progression tes
 
 Diff-aware planning helper: `npm run qa:plan [-- --json] [-- --base main]`.
 
+> The tier commands above are **project-provided** — the harness ships only
+> `test:dispatch` and `test:governance`. If a referenced script is missing,
+> route that finding to the orchestrator (`scripts/qa/check-qa-scripts.js`
+> verifies wiring mechanically).
+
 ## Progression vs regression
 
 - **Regression** asserts existing capabilities did not break.

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

@@ -27,13 +27,13 @@ You are the Application Security Engineer for {{PROJECT_NAME}}. Every code chang
 
 ## 3. Input Validation & Injection Defense
 - Validate and type-check every request body/query parameter at the route boundary. Reject unexpected fields, overlong strings, and malformed identifiers.
-- Use Prisma's parameterized queries/ORM methods exclusively — never interpolate user input into raw SQL strings. If raw SQL is unavoidable, use parameterized placeholders.
-- Validate identifiers: domain ID/ISBN/barcode strings must match expected digit patterns before being used in lookups.
+- Use the ORM's parameterized queries exclusively — never interpolate user input into raw SQL strings. If raw SQL is unavoidable, use parameterized placeholders.
+- Validate identifiers: domain IDs must match their expected patterns (`.agents/memory/domain-map.md` §Identifiers) before lookups.
 
 ## 4. External Service Calls & Safe Logging
-- External service logs (`ExternalServiceLog`) must never store PII, tokens, or full credentials. Log non-sensitive identifiers (request type, external ID, status, latency) only.
-- Treat all external responses (catalog, search, vision APIs — see `.agents/memory/domain-map.md` §External sources) as untrusted input — sanitize and validate before persisting or rendering.
-- Respect third-party rate limits (the catalog test already inserts a 2s delay to avoid IP bans).
+- External-service telemetry logs must never store PII, tokens, or full credentials. Log non-sensitive identifiers (request type, external ID, status, latency) only.
+- Treat all external responses (see `.agents/memory/domain-map.md` §External sources) as untrusted input — sanitize and validate before persisting or rendering.
+- Respect third-party rate limits (the data-ingestion test already inserts a delay to avoid IP bans).
 
 ## 5. Rate Limiting & Abuse Prevention
 - Public/unauthenticated endpoints (search, discovery) should be protected against abuse (rate limiting, input caps, result caps).

package/templates/.agents/skills/system-architect/SKILL.md

@@ -23,11 +23,11 @@ You are the Principal System Architect for {{PROJECT_NAME}}. You govern the data
 - Always include `lastSyncTimestamp` in payloads to keep client clocks synchronized.
 
 ### 3. Database Schema Evolution
-- **ORM/DS specifics (this project)**: read `.agents/memory/stack-versions.md` for the exact ORM version and generator/config layout (e.g. Prisma 7 uses the `prisma-client` generator + `prisma.config.ts`, NOT `prisma-client-js` / datasource `url` in `schema.prisma`). Follow the local convention for `.env`/`DATABASE_URL` (never commit secrets).
+- **ORM/DS specifics (this project)**: read `.agents/memory/stack-versions.md` for the exact ORM version and generator/config layout (a recent major renamed the generator and moved config out of `schema.prisma` — see the gotchas). Follow the local convention for `.env`/`DATABASE_URL` (never commit secrets).
 - When altering the schema:
-  1. Inspect relations and indices for query performance (e.g. `@@index([communityId])`, `@@index([userId])`).
-  2. Run the migrate command (`npx prisma migrate dev --name <migration_name>`).
-  3. Regenerate client types (`npx prisma generate`).
+  1. Inspect relations and indices for query performance (e.g. `@@index([ownerId])`, `@@index([userId])`).
+  2. Run the migrate command for the project's ORM (`.agents/memory/stack-versions.md`).
+  3. Regenerate client types (`.agents/memory/stack-versions.md`).
   4. Ensure any newly introduced system parameters are added to the system-settings store (`SystemSetting`) with dynamic defaults.
   5. Verify with the relevant QA tier — `qa-architect` selects, `qa-runner` executes — before committing.
 

package/templates/.opencode/agents/data-engineer.md

@@ -2,6 +2,7 @@
 description: Use for catalog/data ingestion and entity resolution — external-source ingestion, canonical-record dedup, external service telemetry.
 mode: subagent
 model: opencode/gpt-5.6-luna
+steps: 40
 ---
 
 You are the {{PROJECT_NAME}} Data Engineer. Read and follow the complete persona instructions in `.agents/skills/data-engineer/SKILL.md`, then carry out the task.

package/templates/.opencode/agents/devops-engineer.md

@@ -2,6 +2,7 @@
 description: Use for deployment, CI/CD, cron/scheduling, env & secrets management, hosting config, and mobile build/release setup.
 mode: subagent
 model: opencode/gpt-5.6-luna
+steps: 40
 ---
 
 You are the {{PROJECT_NAME}} DevOps Engineer. Read and follow the complete persona instructions in `.agents/skills/devops-engineer/SKILL.md`, then carry out the task.

package/templates/.opencode/agents/diagnostics-expert.md

@@ -2,6 +2,8 @@
 description: Use when debugging errors, performance regressions, or API anomalies — log-first investigation, ExternalServiceLog, cold-start profiling, authentic reproduction.
 mode: subagent
 model: opencode/deepseek-v4-pro
+temperature: 0.1
+steps: 30
 ---
 
 You are the {{PROJECT_NAME}} Diagnostics Expert. Read and follow the complete persona instructions in `.agents/skills/diagnostics-expert/SKILL.md`, then carry out the task.

package/templates/.opencode/agents/frontend-engineer.md

@@ -2,6 +2,7 @@
 description: Use when writing or fixing web React / Next.js / Tailwind / shadcn code (app/, components/, pages/), or resolving web build errors — not Expo/React Native (that's mobile-engineer).
 mode: subagent
 model: opencode/gpt-5.6-luna
+steps: 40
 ---
 
 You are the {{PROJECT_NAME}} Frontend Engineer. Read and follow the complete persona instructions in `.agents/skills/frontend-engineer/SKILL.md`, then carry out the task.

package/templates/.opencode/agents/handoff.md

@@ -2,6 +2,11 @@
 description: Use when the user asks to save progress, hand off, wrap up, or "remind me where we stopped" — writes a planned→shipped→deferred delta and updates the session handoff memory.
 mode: subagent
 model: opencode/gpt-5-nano
+temperature: 0.1
+steps: 10
+hidden: true
+permission:
+  bash: deny
 ---
 
 You are the {{PROJECT_NAME}} Handoff Assistant. Read and follow the complete persona instructions in `.agents/skills/handoff/SKILL.md`, then carry out the task.

package/templates/.opencode/agents/mobile-engineer.md

@@ -2,6 +2,7 @@
 description: Use when writing or fixing Expo / React Native native code — native runtime, Fabric, reanimated, worklets, css-interop, Android/iOS build issues.
 mode: subagent
 model: opencode/gpt-5.6-luna
+steps: 40
 ---
 
 You are the {{PROJECT_NAME}} Mobile Engineer. Read and follow the complete persona instructions in `.agents/skills/mobile-engineer/SKILL.md`, then carry out the task.

package/templates/.opencode/agents/planner.md

@@ -2,6 +2,12 @@
 description: Use to plan/decompose a task and emit the Step Zero subagent dispatch plan (personas, models, order, parallel batches) before any file is touched.
 mode: subagent
 model: opencode/deepseek-v4-pro
+temperature: 0.1
+steps: 15
+hidden: true
+permission:
+  edit: deny
+  bash: deny
 ---
 
 You are the {{PROJECT_NAME}} Planner / Tech Lead. Read and follow the complete persona instructions in `.agents/skills/planner/SKILL.md`, then carry out the task.

package/templates/.opencode/agents/product-manager.md

@@ -2,6 +2,10 @@
 description: Use when designing features, gamification, or user journeys — maps DB logic to UX with the 5 UI states.
 mode: subagent
 model: opencode/deepseek-v4-pro
+steps: 20
+permission:
+  edit: deny
+  bash: deny
 ---
 
 You are the {{PROJECT_NAME}} Product Manager. Read and follow the complete persona instructions in `.agents/skills/product-manager/SKILL.md`, then carry out the task.

package/templates/.opencode/agents/qa-architect.md

@@ -2,6 +2,10 @@
 description: Use to design the QA plan for a change — inspects the diff, assesses risk, selects the minimal tier, and authors progression tests (thinker only; does not run suites).
 mode: subagent
 model: opencode/deepseek-v4-pro
+temperature: 0.1
+steps: 20
+permission:
+  bash: deny
 ---
 
 You are the {{PROJECT_NAME}} QA Architect. Read and follow the complete persona instructions in `.agents/skills/qa-architect/SKILL.md`, then carry out the task.

package/templates/.opencode/agents/qa-runner.md

@@ -2,6 +2,8 @@
 description: Use to execute a QA plan or test tier (including the catalog E2E journey and catalog test-data cleanup) and report pass/fail — does not design tests or judge risk.
 mode: subagent
 model: opencode/gpt-5.6-luna
+temperature: 0.1
+steps: 50
 ---
 
 You are the {{PROJECT_NAME}} QA Runner. Read and follow the complete persona instructions in `.agents/skills/qa-runner/SKILL.md`, then carry out the task.

package/templates/.opencode/agents/security-engineer.md

@@ -2,6 +2,7 @@
 description: Use when a change touches auth, secrets, input validation, external services, or dependencies — security review + audit.
 mode: subagent
 model: opencode/deepseek-v4-pro
+steps: 30
 ---
 
 You are the {{PROJECT_NAME}} Security Engineer. Read and follow the complete persona instructions in `.agents/skills/security-engineer/SKILL.md`, then carry out the task.

package/templates/.opencode/agents/system-architect.md

@@ -2,6 +2,7 @@
 description: Use when changing the Prisma schema, data model, multi-tenant boundaries, privacy tiers, or sync protocol.
 mode: subagent
 model: opencode/deepseek-v4-pro
+steps: 40
 ---
 
 You are the {{PROJECT_NAME}} System Architect. Read and follow the complete persona instructions in `.agents/skills/system-architect/SKILL.md`, then carry out the task.

package/templates/.opencode/agents/ui-designer.md

@@ -2,6 +2,7 @@
 description: Use when designing the visual system — design tokens, theming, and shared/reusable UI components (shadcn/ui, Tailwind, Framer Motion) — not app screens or native code.
 mode: subagent
 model: opencode/gpt-5.6-luna
+steps: 40
 ---
 
 You are the {{PROJECT_NAME}} UI Designer. Read and follow the complete persona instructions in `.agents/skills/ui-designer/SKILL.md`, then carry out the task.

package/templates/AGENTS.md

@@ -1,17 +1,10 @@
-# Operating Rules
+# {{PROJECT_NAME}} — Agent Operating Rules
 
-The canonical operating rulebook for this project lives in [`.agents/AGENTS.md`](.agents/AGENTS.md), with an always-loaded rules summary in [`.agents/rules/00-operating.md`](.agents/rules/00-operating.md).
+The always-loaded rules summary lives in [`.agents/rules/00-operating.md`](.agents/rules/00-operating.md) (wired into `opencode.json` `instructions`). The full, canonical rulebook is [`.agents/AGENTS.md`](.agents/AGENTS.md) — read it before any non-trivial work.
 
-Read and follow it **before starting any task**. It governs:
+It governs: Step Zero subagent dispatch, zero-speculation debugging, data integrity, UI/RTL ergonomics, stack-version discipline, token efficiency, right-sized QA tiers, and the commit-and-push gate.
 
-- Debugging discipline (log-first, zero speculation)
-- Data & business-logic integrity (no hardcoded mocks)
-- UI/UX, mobile ergonomics, and RTL support
-- Framework / backend architecture
-- Token-efficiency discipline
-- The QA tier system (regression + progression)
-- The commit-and-push gate
+- **Dispatch personas** via the `task` tool (see `.agents/rules/00-operating.md` §Step Zero); consult the relevant `.agents/skills/<persona>/SKILL.md`.
+- **At session start**, read `.agents/memory/locations.md` and `.agents/memory/model-routing.md`.
 
-Domain-specific personas live in [`.agents/skills/`](.agents/skills/) — consult the relevant one for security, architecture, frontend, QA, UI, or product work.
-
-> This agent harness is deployed and maintained by `@dombaras/agent-harness` (`npx @dombaras/agent-harness init` / `npx @dombaras/agent-harness update`). Do not hand-edit the persona/skill/rules files in place — regenerate them from the harness and commit the deltas.
+> Deployed and maintained by `@dombaras/agent-harness` (`npx @dombaras/agent-harness init` / `update`). Do not hand-edit harness-owned files — regenerate them and commit the deltas.

package/templates/opencode.json

@@ -1,5 +1,6 @@
 {
   "$schema": "https://opencode.ai/config.json",
   "model": "opencode/deepseek-v4-pro",
-  "small_model": "opencode/gpt-5-nano"
+  "small_model": "opencode/gpt-5-nano",
+  "instructions": [".agents/rules/00-operating.md"]
 }

package/templates/scripts/qa/check-qa-scripts.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+"use strict";
+/*
+ * check-qa-scripts — verify the QA-tier npm scripts the rulebook's Definition of
+ * Done references actually exist in the target project's package.json.
+ *
+ * The harness ships only `test:dispatch` and `test:governance`; the runtime QA
+ * tiers (test:quick / test:routes / test:api / test:verify / test:security) are
+ * PROJECT-PROVIDED. This gate emits warnings for missing ones so a fresh deploy
+ * doesn't silently claim a QA tier that isn't wired up.
+ *
+ *   node scripts/qa/check-qa-scripts.js            # warnings only, exit 0
+ *   node scripts/qa/check-qa-scripts.js --strict   # fail (exit 1) on missing
+ */
+const fs = require("fs");
+const path = require("path");
+
+const root = path.resolve(__dirname, "..", "..");
+const strict = process.argv.includes("--strict");
+
+// npm scripts referenced by the DoD / QA tier matrix.
+const EXPECTED = {
+  "test:dispatch": "harness — persona model-pin preflight (shipped)",
+  "test:governance": "harness — session-governance gate (shipped)",
+  "test:quick": "Tier 1 — types + translations + mobile smoke",
+  "test:routes": "Tier 2 — route/page render",
+  "test:api": "Tier 3 — API/ORM edge cases",
+  "test:verify": "Tier 5 — full regression",
+  "test:security": "Tier 6 — npm audit + security checks",
+};
+
+const pkgPath = path.join(root, "package.json");
+if (!fs.existsSync(pkgPath)) {
+  console.error("FATAL: no package.json in project root");
+  process.exit(2);
+}
+
+let pkg;
+try {
+  pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+} catch (e) {
+  console.error(`FATAL: unparseable package.json: ${e.message}`);
+  process.exit(2);
+}
+
+const scripts = pkg.scripts || {};
+const missing = [];
+const present = [];
+
+console.log("QA script wiring check — DoD-referenced npm scripts");
+for (const [name, desc] of Object.entries(EXPECTED)) {
+  if (scripts[name]) {
+    present.push(name);
+    console.log(`  \u2713 ${name} (${desc})`);
+  } else {
+    missing.push(name);
+    console.log(`  \u26a0 ${name} MISSING (${desc})`);
+  }
+}
+
+if (missing.length) {
+  const verb = strict ? "FAILURE" : "WARNING";
+  console.log(
+    `\nRESULT: ${present.length}/${Object.keys(EXPECTED).length} wired. ` +
+      `${missing.length} missing: ${missing.join(", ")}.`
+  );
+  console.log(
+    `These are project-provided scripts — add them to package.json or narrow the QA tiers you use. ` +
+      `(Run with --strict to treat this as a failure.)`
+  );
+  process.exit(strict ? 1 : 0);
+}
+
+console.log("\nRESULT: all DoD-referenced QA scripts wired.");
+process.exit(0);