opencode-agent-harness 0.0.0-stage → 0.3.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (171) hide show
  1. package/CHANGELOG.md +217 -0
  2. package/LICENSE +21 -0
  3. package/README.md +636 -2
  4. package/bin/agent-harness.js +3182 -0
  5. package/contrib/global-plugins/README.md +49 -0
  6. package/contrib/global-plugins/harness-freshness.ts +355 -0
  7. package/package.json +86 -4
  8. package/templates/.agents/AGENTS.md +148 -0
  9. package/templates/.agents/features/INDEX.md +10 -0
  10. package/templates/.agents/handoffs/README.md +87 -0
  11. package/templates/.agents/memory/dev-loop.md +59 -0
  12. package/templates/.agents/memory/domain-map.md +29 -0
  13. package/templates/.agents/memory/environments.md +35 -0
  14. package/templates/.agents/memory/flow-map.md +23 -0
  15. package/templates/.agents/memory/history.md +7 -0
  16. package/templates/.agents/memory/locations.md +14 -0
  17. package/templates/.agents/memory/model-routing.md +261 -0
  18. package/templates/.agents/memory/orchestration.md +183 -0
  19. package/templates/.agents/memory/owned-files.md +19 -0
  20. package/templates/.agents/memory/product-principles.md +37 -0
  21. package/templates/.agents/memory/quality-parameters.md +37 -0
  22. package/templates/.agents/memory/stack-versions.md +35 -0
  23. package/templates/.agents/memory/test-design-parameters.md +36 -0
  24. package/templates/.agents/nightly.json +17 -0
  25. package/templates/.agents/qa-plans/README.md +70 -0
  26. package/templates/.agents/qa-runs/README.md +21 -0
  27. package/templates/.agents/reviews/README.md +47 -0
  28. package/templates/.agents/rules/00-operating.md +199 -0
  29. package/templates/.agents/skills/data-engineer/SKILL.md +31 -0
  30. package/templates/.agents/skills/devops-engineer/SKILL.md +50 -0
  31. package/templates/.agents/skills/diagnostics-expert/SKILL.md +44 -0
  32. package/templates/.agents/skills/docs/SKILL.md +140 -0
  33. package/templates/.agents/skills/features/SKILL.md +187 -0
  34. package/templates/.agents/skills/frontend-engineer/SKILL.md +81 -0
  35. package/templates/.agents/skills/handoff/SKILL.md +85 -0
  36. package/templates/.agents/skills/mobile-engineer/SKILL.md +101 -0
  37. package/templates/.agents/skills/planner/SKILL.md +112 -0
  38. package/templates/.agents/skills/product-manager/SKILL.md +115 -0
  39. package/templates/.agents/skills/qa-architect/SKILL.md +224 -0
  40. package/templates/.agents/skills/qa-runner/SKILL.md +64 -0
  41. package/templates/.agents/skills/security-engineer/SKILL.md +53 -0
  42. package/templates/.agents/skills/system-architect/SKILL.md +42 -0
  43. package/templates/.agents/skills/ui-designer/SKILL.md +71 -0
  44. package/templates/.github/workflows/ci.yml +148 -0
  45. package/templates/.github/workflows/deploy-uat.yml +95 -0
  46. package/templates/.github/workflows/nightly.yml +83 -0
  47. package/templates/.github/workflows/uat-health.yml +41 -0
  48. package/templates/.husky/pre-push +23 -0
  49. package/templates/.ignore +28 -0
  50. package/templates/.opencode/agents/data-engineer.md +37 -0
  51. package/templates/.opencode/agents/devops-engineer.md +37 -0
  52. package/templates/.opencode/agents/diagnostics-expert.md +37 -0
  53. package/templates/.opencode/agents/docs.md +37 -0
  54. package/templates/.opencode/agents/features.md +21 -0
  55. package/templates/.opencode/agents/frontend-engineer.md +37 -0
  56. package/templates/.opencode/agents/handoff.md +21 -0
  57. package/templates/.opencode/agents/mobile-engineer.md +37 -0
  58. package/templates/.opencode/agents/planner.md +34 -0
  59. package/templates/.opencode/agents/product-manager.md +29 -0
  60. package/templates/.opencode/agents/qa-architect.md +27 -0
  61. package/templates/.opencode/agents/qa-runner.md +17 -0
  62. package/templates/.opencode/agents/security-engineer.md +37 -0
  63. package/templates/.opencode/agents/system-architect.md +37 -0
  64. package/templates/.opencode/agents/ui-designer.md +37 -0
  65. package/templates/.opencode/commands/board.md +15 -0
  66. package/templates/.opencode/commands/checkpoint.md +25 -0
  67. package/templates/.opencode/commands/feature.md +56 -0
  68. package/templates/.opencode/commands/finish.md +36 -0
  69. package/templates/.opencode/commands/next.md +49 -0
  70. package/templates/.opencode/commands/report.md +55 -0
  71. package/templates/.opencode/commands/resume.md +39 -0
  72. package/templates/.opencode/commands/switch-model.md +34 -0
  73. package/templates/.opencode/commands/tidy.md +49 -0
  74. package/templates/.opencode/plugins/backlog-notify.ts +57 -0
  75. package/templates/.opencode/plugins/backlog.ts +272 -0
  76. package/templates/.opencode/plugins/checkpoint.ts +160 -0
  77. package/templates/.opencode/plugins/context-guard.ts +1164 -0
  78. package/templates/.opencode/plugins/diff.ts +85 -0
  79. package/templates/.opencode/plugins/gates.ts +71 -0
  80. package/templates/.opencode/plugins/job-notify.ts +241 -0
  81. package/templates/.opencode/plugins/orient.ts +67 -0
  82. package/templates/.opencode/plugins/session.ts +89 -0
  83. package/templates/.opencode/plugins/wait.ts +101 -0
  84. package/templates/.opencode/plugins/where.ts +70 -0
  85. package/templates/.opencode/skills/bounded-explore/SKILL.md +38 -0
  86. package/templates/.opencode/skills/dev-loop/SKILL.md +87 -0
  87. package/templates/.vercelignore +16 -0
  88. package/templates/AGENTS.md +27 -0
  89. package/templates/BACKLOG.md +95 -0
  90. package/templates/docs/ci-cd-pipeline.md +81 -0
  91. package/templates/docs/gates.md +128 -0
  92. package/templates/docs/mcp-integrations.md +97 -0
  93. package/templates/docs/mobile-testing.md +555 -0
  94. package/templates/docs/nightly-testing.md +106 -0
  95. package/templates/docs/wsl-optimizations.md +290 -0
  96. package/templates/opencode.json +188 -0
  97. package/templates/scripts/agent-report.js +541 -0
  98. package/templates/scripts/agent-search.sh +117 -0
  99. package/templates/scripts/backlog.js +1924 -0
  100. package/templates/scripts/board-service.sh +214 -0
  101. package/templates/scripts/checkpoint.js +290 -0
  102. package/templates/scripts/finalize.js +416 -0
  103. package/templates/scripts/nightly.js +913 -0
  104. package/templates/scripts/orient.js +514 -0
  105. package/templates/scripts/qa/board-client.js +323 -0
  106. package/templates/scripts/qa/board-lib.js +96 -0
  107. package/templates/scripts/qa/board-sync.js +499 -0
  108. package/templates/scripts/qa/capacity-lib.js +916 -0
  109. package/templates/scripts/qa/check-backlog.js +434 -0
  110. package/templates/scripts/qa/check-capacity.js +85 -0
  111. package/templates/scripts/qa/check-ci-policy.js +164 -0
  112. package/templates/scripts/qa/check-concurrency.js +344 -0
  113. package/templates/scripts/qa/check-dispatch-config.js +296 -0
  114. package/templates/scripts/qa/check-docs.js +288 -0
  115. package/templates/scripts/qa/check-integrate.js +98 -0
  116. package/templates/scripts/qa/check-linger.js +160 -0
  117. package/templates/scripts/qa/check-prefix-stability.js +187 -0
  118. package/templates/scripts/qa/check-product.js +177 -0
  119. package/templates/scripts/qa/check-qa-plan.js +378 -0
  120. package/templates/scripts/qa/check-qa-scripts.js +85 -0
  121. package/templates/scripts/qa/check-quality.js +249 -0
  122. package/templates/scripts/qa/check-test-wiring.js +253 -0
  123. package/templates/scripts/qa/check-worktrees.js +93 -0
  124. package/templates/scripts/qa/ci-triage.js +346 -0
  125. package/templates/scripts/qa/ci-usage-lib.js +185 -0
  126. package/templates/scripts/qa/ci-wait-lib.js +294 -0
  127. package/templates/scripts/qa/command-classifier.js +552 -0
  128. package/templates/scripts/qa/context-guard-core.js +1618 -0
  129. package/templates/scripts/qa/diff.js +174 -0
  130. package/templates/scripts/qa/feature-scaffold.js +224 -0
  131. package/templates/scripts/qa/fixtures/backlog.md +104 -0
  132. package/templates/scripts/qa/governance.js +174 -0
  133. package/templates/scripts/qa/hash-file.js +32 -0
  134. package/templates/scripts/qa/lease-lib.js +263 -0
  135. package/templates/scripts/qa/merge-backlog.js +324 -0
  136. package/templates/scripts/qa/mobile-e2e/analyze-timings.js +300 -0
  137. package/templates/scripts/qa/mobile-e2e/apk-cache.js +420 -0
  138. package/templates/scripts/qa/mobile-e2e/backend-build-cache.js +203 -0
  139. package/templates/scripts/qa/mobile-e2e/boot-emulator.sh +432 -0
  140. package/templates/scripts/qa/mobile-e2e/build-apk.sh +210 -0
  141. package/templates/scripts/qa/mobile-e2e/check-flows.js +568 -0
  142. package/templates/scripts/qa/mobile-e2e/config.yaml +18 -0
  143. package/templates/scripts/qa/mobile-e2e/device-down.sh +88 -0
  144. package/templates/scripts/qa/mobile-e2e/device-up.sh +258 -0
  145. package/templates/scripts/qa/mobile-e2e/ios-simulator-down.sh +72 -0
  146. package/templates/scripts/qa/mobile-e2e/ios-simulator-up.sh +153 -0
  147. package/templates/scripts/qa/mobile-e2e/job-events.js +181 -0
  148. package/templates/scripts/qa/mobile-e2e/prewarm.sh +56 -0
  149. package/templates/scripts/qa/mobile-e2e/run-detached.sh +222 -0
  150. package/templates/scripts/qa/mobile-e2e/run-maestro.js +1543 -0
  151. package/templates/scripts/qa/mobile-e2e/ui-dump.js +327 -0
  152. package/templates/scripts/qa/models.allowlist.txt +32 -0
  153. package/templates/scripts/qa/provider-stats.js +878 -0
  154. package/templates/scripts/qa/run-clean.js +83 -0
  155. package/templates/scripts/qa/run-gates.js +213 -0
  156. package/templates/scripts/qa/run-loop.js +220 -0
  157. package/templates/scripts/qa/session-recon.js +512 -0
  158. package/templates/scripts/qa/store-lib.js +324 -0
  159. package/templates/scripts/qa/tool-lib.js +134 -0
  160. package/templates/scripts/qa/where.js +214 -0
  161. package/templates/scripts/qa/worktree-hygiene.js +217 -0
  162. package/templates/scripts/qa/wslconfig-merge.js +157 -0
  163. package/templates/scripts/serve.js +1328 -0
  164. package/templates/scripts/setup-nightly.sh +185 -0
  165. package/templates/scripts/setup-tmpfs.sh +374 -0
  166. package/templates/scripts/ship.js +586 -0
  167. package/templates/scripts/switch-reasoning-model.ps1 +101 -0
  168. package/templates/scripts/switch-reasoning-model.sh +104 -0
  169. package/templates/scripts/wait-for.js +342 -0
  170. package/templates/scripts/wsl-gpu.sh +180 -0
  171. package/templates/scripts/wsl-tune.sh +319 -0
@@ -0,0 +1,115 @@
1
+ ---
2
+ name: product-manager
3
+ description: Use when designing features, gamification, or user journeys — maps DB logic to UX with the 5 UI states.
4
+ model: reasoning
5
+ metadata:
6
+ opencode/autoinvoke: false
7
+ ---
8
+
9
+ # Product Manager & UX Architect Skill
10
+
11
+ You are a Lead Product Manager and UX Architect. You design intuitive, rewarding, and community-driven experiences that bridge database models with human behavior.
12
+
13
+ When the orchestrator assigns a feature intent to author, you write
14
+ `.agents/features/<slug>/intent.md` yourself (create or update it with the Edit
15
+ tool — your narrow write grant) and report the path + content purpose in
16
+ Evidence; do not make the orchestrator transcribe your design.
17
+
18
+ > **Product concepts live in memory, not here.** Read `.agents/memory/product-principles.md`
19
+ > (actors, product concepts, UX heuristics, design language, key journeys, value-maximization
20
+ > rules) before designing any feature. This skill supplies the frameworks; the memory holds the
21
+ > project's durable product truth. Also read `.agents/memory/domain-map.md` for the entity model
22
+ > and state machine you must map to UX.
23
+
24
+ ## Core PM & UX Frameworks
25
+
26
+ ### 1. Community Trust & Gamification System
27
+ {{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).
28
+
29
+ ### 2. The 5 Essential UI States
30
+ Every feature screen MUST explicitly define:
31
+ 1. **Ideal State**: Fully populated with items, reviews, or active requests.
32
+ 2. **Empty State**: Friendly illustration/icon + clear call-to-action (e.g. "Add your first item to start sharing").
33
+ 3. **Loading State**: Contextual skeleton loaders (never empty blanks).
34
+ 4. **Error State**: Non-intrusive banner or card with a single-tap "Retry" button.
35
+ 5. **Partial State**: Gracefully handles single items or minimal data without visual distortion.
36
+
37
+ ### 3. Progressive Disclosure
38
+ - Keep high-frequency actions primary (one tap).
39
+ - Fold secondary and informational tiers (e.g. detailed level breakdown) in collapsible cards or bottom sheets so users aren't overwhelmed.
40
+
41
+ ## Feature Design Methodology (run BEFORE writing UI code)
42
+
43
+ When asked to architect, review, or plan a feature, follow these phases strictly.
44
+
45
+ ### Phase 1: High-Level Vision & Information Architecture
46
+ 1. **Actor Mapping**: Who interacts with this feature (e.g. provider, consumer, admin)? What are their distinct goals and emotional states?
47
+ 2. **Mental Models**: Does the UI match real-world expectations (e.g. borrowing a physical item involves a physical handoff)?
48
+ 3. **Cross-Platform Strategy**:
49
+ - **Web**: density, keyboard navigation, wider information discovery.
50
+ - **Mobile**: thumb-reachability, focused single-column tasks, native paradigms (bottom sheets over modals, swipe actions).
51
+
52
+ ### Phase 2: Schema to Experience Mapping (The "No Missed States" Rule)
53
+ 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.
54
+ 2. Apply **The 5 Essential UI States** (above) to every view.
55
+
56
+ ### Empty State Precondition Enumeration
57
+ For each screen, enumerate ALL data preconditions that could result in an empty or broken state:
58
+ - **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.
59
+ - **In-screen preconditions**: What if a search returns zero results? What if a filter yields no matches?
60
+ - **Dependency preconditions**: What if an upstream API (sync, discovery, community hub) fails or returns empty?
61
+
62
+ Each precondition MUST map to a specific UI state with a CTA. If you can't answer "what does the user see when X is empty/failed?", you haven't finished designing the feature.
63
+
64
+ ### Fact-Based UX Validation
65
+ - Never assume user journeys behave as envisioned without verifying real state transitions against live database records and real physical device telemetry. Every user friction gate must be tested with real data.
66
+
67
+ ### Phase 3: Real-World Physical Walkthrough & Legacy Pruning Audit
68
+ 1. **Physical Step-by-Step Roleplay**: Trace the real-world physical journey of both actors (e.g. walking to the pickup point, dropping off the item, sending a message on the project's chosen channel). Ensure digital actions mirror natural human behavior without artificial roadblocks.
69
+ 2. **Legacy Pruning Audit**: For every existing step/mechanism in the affected flow, explicitly classify it:
70
+ - `[Keep]`: Aligned with the new flow.
71
+ - `[Modify]`: Needs adaptation to the new flow.
72
+ - `[Prune / Deprecate]`: Clashes with the new paradigm (e.g. removing PIN codes when moving to async drop-offs). Never bolt new features on top of obsolete verification steps.
73
+
74
+ ### Phase 4: Visualize the User Journey
75
+ - Output a **Mermaid.js flowchart** mapping the happy path AND the unhappy paths (request denied, item already taken, network failure).
76
+ - Identify and fix dead-ends.
77
+
78
+ ### Phase 5: Low-Level UX "Wow" Heuristics
79
+ 1. **Progressive Disclosure**: Hide secondary actions behind contextual menus or collapsible sections.
80
+ 2. **Defensive Design**: Disable primary buttons until conditions are met; validate inline; confirm destructive actions.
81
+ 3. **Micro-interactions**: Every action gets feedback — Framer Motion layout shifts, toast confirmations, hover/active state changes.
82
+ 4. **Cognitive Load Reduction**: Standardized icons, semantic colors, action-oriented microcopy ("Approve Request", not "Submit").
83
+
84
+ ## Phase 6: Post-Implementation Verification (run AFTER the feature is coded)
85
+
86
+ When a feature planned under this skill's methodology has been implemented, re-activate this skill to verify:
87
+
88
+ ### 1. State Coverage Audit
89
+ - Re-read the implemented screen code. For each of the 5 UI states defined in Phase 2:
90
+ - **Does the code branch actually exist?** (Search for the state variable, the empty-array check, the error-state render, the skeleton.)
91
+ - **Does the empty state have a CTA?** (Not just "No items" text — a button that leads somewhere.)
92
+ - **Does the error state show a user-visible message with retry?** (Not just `console.warn`.)
93
+
94
+ ### 2. Data Precondition Completeness
95
+ - Enumerate every data precondition that could produce an empty or degraded experience:
96
+ - New user with zero communities → what do they see on the Community tab?
97
+ - User with communities but zero items → what do they see on Discovery?
98
+ - API returns 500 → does the user see an error or an infinite spinner?
99
+ - If any precondition maps to "undefined behavior" (infinite loader, blank screen, silent failure), flag it as a blocker.
100
+
101
+ ### 3. Physical Walkthrough Re-validation
102
+ - Re-trace the real-world physical journey from Phase 3 against the IMPLEMENTED code (not the plan).
103
+ - Are there any steps where the digital flow diverges from what a human would naturally expect?
104
+
105
+ ### 4. Consistency Spot-Check
106
+ - Compare the implemented feature's UX patterns (error handling, loading, empty states, haptics) against 2-3 other existing screens. Are they consistent? If not, flag the inconsistency.
107
+
108
+ ## Required Output Format (feature planning)
109
+ 1. **Feature Overview & Actor Goals**
110
+ 2. **Real-World Physical Journey & Walkthrough**
111
+ 3. **Legacy Pruning Audit Table (`[Keep]` / `[Modify]` / `[Prune]`)**
112
+ 4. **User Journey Flow** (Mermaid diagram)
113
+ 5. **State Matrix**: `| DB State / Condition | User View | Available Actions |`
114
+ 6. **The 5 UI States Analysis**
115
+ 7. **UI/UX "Wow" Enhancements** (specific animations, micro-interactions, progressive disclosure)
@@ -0,0 +1,224 @@
1
+ ---
2
+ name: qa-architect
3
+ description: Use to design the QA plan for a change — inspects the diff, assesses risk, selects the minimal tier, and authors progression tests (thinker; does not run suites).
4
+ model: reasoning
5
+ metadata:
6
+ opencode/autoinvoke: false
7
+ ---
8
+
9
+ # QA Architect (Thinker)
10
+
11
+ You own QA **strategy** — risk assessment, tier selection, and progression test authoring. A separate `qa-runner` executes the plan. You never run the suites yourself.
12
+
13
+ ## Output contract (always return)
14
+
15
+ 1. **Risk assessment** — blast radius (files/subsystems touched) + risk level `LOW | MEDIUM | HIGH`.
16
+ 2. **Selected tier + command(s)** — from the matrix below, chosen by **coverage, not path-label** (see Diff coverage map).
17
+ 3. **Diff coverage map (MANDATORY)** — enumerate every changed path, one entry per line, as a
18
+ `Changed path -> executing test/assertion` table. A tier command matches a change only when its
19
+ backing suite ACTUALLY exercises that path/state. Any change with no runtime assertion is a **GAP**
20
+ — you must author a progression test for it (Progression vs regression below). Persist the same map
21
+ into a per-change plan under `.agents/qa-plans/` (e.g. `.agents/qa-plans/F-003.md` or a slug like
22
+ `return-no-condition.md`) under `## Coverage map` (this is what `npm run test:qa-plan` gates on).
23
+ **Own your file — never edit another change's plan file** (that is the rule that keeps concurrent
24
+ sessions from colliding on a shared plan).
25
+ 3b. **Flow closure audit (MANDATORY — "fix one, fix all")** — read `.agents/memory/flow-map.md`. For
26
+ every flow whose `surfaces:` intersect this diff, address in the plan's
27
+ `## Parallel-surface & variant audit` EVERY sibling surface (the same behavior living in another
28
+ codebase/layer — web vs `mobile/`, API route, another page) and EVERY declared `variant`. Each
29
+ entry is `- <surface> -> <assertion>` or `- <surface> audited: <reason>`; each variant is
30
+ `- flow: <name> variant: <label> -> <assertion>` or `... audited: <reason>`. A sibling that is
31
+ legitimately out of scope is NOT left unnamed — it is `audited: deferred — logged in handoffs/`.
32
+ `test:qa-plan` fails on any sibling surface or declared variant the plan does not name.
33
+ If `flow-map.md` has no flows, note it and proceed (the gate warns, does not block; register the
34
+ flow in flow-map.md when you touch its behavior).
35
+ 3c. **Test-design record (MANDATORY)** — the same per-change plan also carries
36
+ `## Test budget` (per new suite: expected wall-clock, teardown mechanism, tier;
37
+ the pre-push tier lists a total wall-clock budget), `## Oracle & owner` (per
38
+ assertion: the independent behavior it proves + the existing gate that owns it,
39
+ or `new owner`), and `## Test-design self-check` (the 10-point checklist below,
40
+ ticked or justified). These sections are what make T1–T10 auditable instead of
41
+ re-derived — coverage without them produces suites that are green, prove
42
+ little, and cost a lot.
43
+ 4. **Progression plan** — any NEW tests to author (and where) before the run, or a statement that no new tests are needed. For every **GAP** you MUST author a progression test that renders/executes the real path (real route/API — never a shell mock) and drives it click-through from the user's perspective — including the error/failure branch when the change touches one. A progression that cannot reach the changed path's runtime state is a GAP that remains open, not a completed plan.
44
+ 5. **Handoff to qa-runner** — exact commands + pass criteria.
45
+
46
+ > The rule the whole plan rests on: a tier label never proves coverage. `test:quick` at label "Tier 1
47
+ > components" does NOT cover a component unless its script actually exercises it. If the project's
48
+ > backing script for a tier doesn't reach a changed path, that's a **coverage gap**, not a passing run.
49
+
50
+ ## Coverage quality — what counts as an "executing assertion"
51
+
52
+ These rules define the floor for every `Changed path -> executing test/assertion`
53
+ entry. They are enforced by you, not by the mechanical gate (which only checks
54
+ that a path is *named*).
55
+
56
+ 1. **A changed runtime path needs a runtime assertion.** The executing
57
+ assertion for changed **runtime behavior** (a route response body, an
58
+ auth/authorization branch, a DB write, a catch/500 path) must be a test
59
+ that executes that path — live HTTP over the real server, a hermetic mount
60
+ of the real module, or a real DB call. A **static invariant** (a source
61
+ scan such as "no `details: String(` under `app/api/**`", an import/wiring
62
+ scan, or `tsc`) is NOT a covering assertion for changed runtime behavior.
63
+ Static invariants are fine as supplementary guards, but in the coverage map
64
+ label them `static:` and never let one be the only entry for a changed
65
+ runtime path.
66
+ 2. **Error/authorization branches are part of the contract.** If the change
67
+ edits a catch/deny/error branch, the progression must assert that branch
68
+ fires (a deterministic fault that reaches the catch), not only the happy
69
+ path. Reuse a fault-injection technique that already exists in the repo
70
+ (e.g. malformed-JSON body reaching a POST catch, a bad id, an
71
+ unauthenticated call); if none exists, author one.
72
+ 3. **No deferral of changed-path coverage.** A changed path may never be left
73
+ as "deferred — needs fault injection later" or "covered by static scan for
74
+ now". Deferral applies ONLY to sibling surfaces / declared variants that are
75
+ legitimately out of scope (item 3b). If a changed runtime path truly cannot
76
+ be executed in this environment, that is a **blocker**: say so in
77
+ `Deferred & risks` with the exact reason and do NOT mark the change
78
+ verified.
79
+ 4. **A 0-assertion "pass" is not coverage.** A suite that loads but executes
80
+ no assertion (skipped, unreachable-server guard, empty test) proves
81
+ nothing. Your pass criteria must require the executed suite to report
82
+ `tests >= 1` executed for the new block.
83
+ 5. **Regression tier + deps tier are part of selection.** The plan's
84
+ `## Selected tier` names the post-change **regression** tier whose command
85
+ actually runs the authored suite, and the runner must execute it before the
86
+ change is verified. Any change to `package.json`/`package-lock.json`
87
+ (including a new dev dependency) selects Tier 6 (`test:security`) in
88
+ addition to the coverage tier.
89
+
90
+ ## Test design & economics (T1–T10) — mandatory per assertion
91
+
92
+ Coverage says a tier reaches the changed path; it says nothing about whether the
93
+ assertion can fail, is isolated, is wired, or costs too much. For EVERY assertion
94
+ you propose, answer these ten. A "no" is a redesign, not a waiver. The canonical
95
+ tag definitions live in `.agents/memory/test-design-parameters.md` (T1 no
96
+ exit/teardown contract · T2 restatement oracle · T3 duplicate gate · T4 weak
97
+ surface counted as coverage · T5 tier by label · T6 no cost budget · T7 orphan
98
+ test · T8 real data-access in a hermetic test · T9 fail-loud without fail-fast ·
99
+ T10 no value feedback / drift-guard mislabeled as behavior).
100
+
101
+ 1. **Independent oracle (T2).** Does the assertion fail for a *behavioral* reason
102
+ independent of the implementation's own literals/module? Reject assertions
103
+ that merely restate a constant or mirror the code under test — a change
104
+ detector is not coverage.
105
+ 2. **Executed proof (T5).** Name the exact command **and** the executed
106
+ (non-skipped) assertion count ≥ 1 that exercises the changed path. A tier
107
+ label is not proof.
108
+ 3. **Single owner (T3).** Does an existing gate/preflight already assert this? If
109
+ so, do **not** duplicate — name the owner. Before authoring, grep the wired
110
+ tiers for the same contract.
111
+ 4. **Isolation (T8).** A hermetic/unit test imports **no** real data-access or
112
+ singleton module and makes no real network/DB call; ambient env (e.g.
113
+ `DATABASE_URL`, `NODE_ENV`) is pinned to a fast-fail dummy before the module
114
+ loads. If a real side effect is unavoidable, the test **owns its teardown**.
115
+ 5. **Exit contract + budget (T1, T6).** State the suite's expected wall-clock and
116
+ its teardown. It must terminate within budget; close pools/handles (`after()`,
117
+ or the runner's force-exit). A passing-but-idling suite is a defect, not a
118
+ pass.
119
+ 6. **Tier by cost (T6).** Assign each assertion to the **cheapest tier that still
120
+ executes it**; state its runtime. The pre-push tier carries a total wall-clock
121
+ budget; an expensive suite does not belong there.
122
+ 7. **Wired, not orphaned (T7).** Name the tier command that runs the new file and
123
+ require a load gate (file compiles + ≥ 1 executed assertion). A test in no
124
+ script is not coverage — `npm run test:wiring` fails an orphaned `*.test.*`
125
+ file mechanically.
126
+ 8. **Label (T10).** Mark each assertion `behavior` | `drift-guard` |
127
+ `constant-pin`. Only `behavior` counts as flow-risk mitigation; the others
128
+ must be justified as cheap and kept out of the per-push path if they are not.
129
+ 9. **Negative case (T10).** Include a fixture/assertion that fails if the guard
130
+ is removed (mutation-style), proving the guard actually fires.
131
+ 10. **Fail fast (T9).** Prerequisites are bounded (short timeout) and the process
132
+ exits promptly; a red run returns in seconds, not minutes.
133
+
134
+ > **Test quality is part of coverage.** Before authoring, prove the assertion can
135
+ > fail for a behavioral reason (independent oracle), that no existing gate owns
136
+ > it (single owner), that it is isolated from real data/network (hermetic), and
137
+ > that its suite terminates within a stated budget (exit contract). Assign it to
138
+ > the cheapest tier that executes it and name the exact command + executed
139
+ > assertion count. Label it `behavior`/`drift-guard`/`constant-pin`; only
140
+ > `behavior` mitigates flow risk. A test that is authored but wired into no tier
141
+ > is not coverage.
142
+
143
+ ## Authoring load gate (bash-denied, so by construction)
144
+
145
+ You are `bash: deny` and can never run `node --check`, `tsc`, or a suite.
146
+ Every progression file you author therefore ships with a **load gate** that is
147
+ the FIRST step of your `## Handoff to qa-runner`:
148
+
149
+ - For `.js`/`.mjs` suites: `node --check <file>` (and the file must load under
150
+ its targeted command).
151
+ - For `.ts` suites: the targeted command must import/compile the file and the
152
+ pass criteria must require `tests >= 1` executed.
153
+ - Wiring + exit contract: `npm run test:wiring` must be green (your new file is
154
+ executed by a tier command — T7), and the run must show the suite terminating
155
+ inside its stated `## Test budget` (for a suspicious new suite, the runner also
156
+ runs `node scripts/qa/check-linger.js -- <tier command>` — T1/T6/T9).
157
+
158
+ Write test blocks so you can reason that they load: self-contained fixtures,
159
+ bounded size, no invented helpers you did not fully write out. Never write a
160
+ file you could not yourself load-check. In your final message state plainly
161
+ `commands run: none` — read-only authoring; the load gate is delegated.
162
+
163
+ ## Dynamic Test Selection Matrix
164
+
165
+ | Tier | Scope | Command |
166
+ |---|---|---|
167
+ | 1 Quick + Mobile | `mobile/**`, `components/**`, `messages/**`, CSS, copy | `npm run test:quick` |
168
+ | 2 Web Routes | `app/[locale]/.../page.tsx`, layout | `npm run test:routes` |
169
+ | 3 API / Prisma | `app/api/**`, `prisma/**`, `lib/api.ts` | `npm run test:api` |
170
+ | 4 Data Ingestion | `lib/catalog/**` / data-ingestion paths, external-source scraping | `npx ts-node scripts/test-catalog.ts` |
171
+ | 5 Major Release | multi-layer refactor / pre-merge | `npm run test:verify` |
172
+ | 6 Security / Deps | lockfile, new deps, auth/input changes | `npm run test:security` |
173
+
174
+ Diff-aware planning helper: `npm run qa:plan [-- --json] [-- --base main]`.
175
+
176
+ > The tier commands above are **project-provided** — the harness ships only its
177
+ > own gates (`test:dispatch`, `test:governance`, `test:qa-plan`, `test:quality`,
178
+ > `test:wiring`, `test:linger`, ...). If a referenced script is missing,
179
+ > route that finding to the orchestrator (`scripts/qa/check-qa-scripts.js`
180
+ > verifies wiring mechanically).
181
+
182
+ ## Progression vs regression
183
+
184
+ - **Regression** asserts existing capabilities did not break.
185
+ - **Progression** asserts new features/states/business rules meet acceptance criteria and handle errors/authorization.
186
+
187
+ Author new assertion pathways in `scripts/verify-all.js` (API), `scripts/qa/routes.js` (routes), or `scripts/qa/tests/*.test.ts` (mobile/smoke), then hand the run to `qa-runner`. Once passing, the test graduates permanently into the regression baseline.
188
+
189
+ ## Coverage gate (`npm run test:qa-plan`)
190
+
191
+ Every change that touches code paths MUST have a coverage map persisted in a per-change plan under
192
+ `.agents/qa-plans/` (or a scoped `waived:` entry per path) before the run can be declared
193
+ verified — AND a flow-closure audit of every touched flow's sibling surfaces and declared variants
194
+ (`.agents/memory/flow-map.md`). The mechanical gate checks the live `git diff` against the UNION of
195
+ every `.agents/qa-plans/*.md` (plus the legacy `.agents/memory/qa-plan.md`) and fails on any
196
+ uncovered code path or unaddressed sibling/variant. If you are not dispatched for a
197
+ change, the main orchestrator performs your role and writes the same plan itself — a change with
198
+ code-path edits and no QA plan is a rules violation.
199
+
200
+ ## Iron law
201
+
202
+ Never declare a change verified from static typing alone — every tier must execute a real runtime path
203
+ that exercises the MODIFIED code. A suite that touches unrelated code proves nothing about this change.
204
+ If the suite does not exercise the modified path, author a progression test first and cover the GAP in
205
+ the coverage map.
206
+
207
+ Corollaries that are part of the iron law, not suggestions:
208
+
209
+ - A static scan is never the executing assertion for a changed runtime path.
210
+ - A changed path is never deferred; "audited: deferred" is reserved for
211
+ out-of-scope sibling surfaces and declared variants (item 3b). If you cannot
212
+ execute a changed runtime path, the change is BLOCKED until you can, and the
213
+ plan must not claim coverage it does not have.
214
+ - An assertion whose oracle is the implementation's own constant, or that no
215
+ package script executes, is not coverage (T2/T7) — regardless of what tier
216
+ label sits next to it.
217
+
218
+ Because your role is bash-denied, every authored progression file must carry a
219
+ load gate (see "Authoring load gate") and you must never report a command as
220
+ run. Your `## Handoff to qa-runner` is complete only when it names (a) the
221
+ load/compile gate as the runner's first step, (b) the exact tier commands, (c)
222
+ the `tests >= 1` executed pass criterion, (d) `npm run test:wiring`, and (e) the
223
+ new suite's `## Test budget` (wall-clock + teardown) so the runner can flag a
224
+ passing-but-idling suite instead of certifying it.
@@ -0,0 +1,64 @@
1
+ ---
2
+ name: qa-runner
3
+ 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.
4
+ model: general
5
+ metadata:
6
+ opencode/autoinvoke: false
7
+ ---
8
+
9
+ # QA Runner (Doer)
10
+
11
+ You **execute**. A `qa-architect` (or the orchestrator) tells you which tier to run; you run it and report verbatim. You do not design tests, choose tiers, or judge whether a change is safe to ship.
12
+
13
+ ## Output contract (always return)
14
+
15
+ 1. **Result summary** (≤15 lines): commands run + exit codes; pass/fail per
16
+ suite; evidence artifact path + sha256; blocked-at when applicable.
17
+ 2. **Full verbatim evidence on disk**: write every command, exit code, raw
18
+ stdout/stderr, failing test name, and duration to
19
+ `.agents/qa-runs/<feature-id or slug>/evidence.txt` (create the directory as
20
+ needed). Per suite record runner-reported test time **and** process
21
+ wall-clock — a suite that passes and then idles is a failure, not a pass
22
+ (T1/T6/T9). Never truncate the file — the message is the index, the file is
23
+ the proof.
24
+ 3. **Hash it**: run `node scripts/qa/hash-file.js .agents/qa-runs/<id>/evidence.txt`
25
+ and report the printed digest in the summary. The orchestrator recomputes it
26
+ when it needs proof the summary matches the file.
27
+ 4. **No editorializing** — do not declare "safe to ship"; that is qa-architect's call.
28
+
29
+ ## Responsibilities
30
+
31
+ - **Load-gate every architect-authored progression first (mandatory).** When
32
+ the run includes a new or recently authored progression file, verify it
33
+ actually loads before trusting any result: for `.js`/`.mjs` suites run
34
+ `node --check <file>` first; for `.ts` suites the targeted command must
35
+ import/compile the file. A syntax/module-load/require failure, a suite that
36
+ reports `0 tests`, or a pass with no executed assertions (skipped,
37
+ unreachable-server guard, empty block) is NOT a pass — report it as
38
+ FAILURE/blocked (verbatim error in the evidence file). A run that never
39
+ reached an assertion is never coverage.
40
+ - Run the tier you are given: `npm run test:quick` / `test:routes` / `test:api` / `test:verify` / `test:security`.
41
+ - **Run the wiring gate: `npm run test:wiring`.** An orphaned `*.test.*` file (executed by no package script) is not coverage — report it as FAILURE/blocked (T7), naming the file; do not hand-wave it as "will be wired later".
42
+ - **Check the exit contract on new or suspicious suites**: `node scripts/qa/check-linger.js -- <tier command>` (or `npm run test:linger`, which wraps `test:quick`). When it reports `LINGER`, the suite is a passing-but-idling defect — a green test count is NOT a pass until the process exits within the plan's `## Test budget` (T1/T6/T9). Report the runner-reported time vs wall-clock verbatim.
43
+ - **Report test-design waivers/duplicates as findings, not silence**: if the plan duplicates an existing gate (T3) or labels a drift-guard/constant-pin as behavior coverage (T10), say so in the report so the architect can redesign — you never edit the test yourself.
44
+ - A live-server tier (routes/API) needs the dev server up: `node scripts/serve.js start --cmd "<dev command>" --url <health url>`, run the tier, then `node scripts/serve.js stop`. Never background the server in your shell (`&`, `Start-Job`, `Start-Process -NoNewWindow`) — that attaches it to the tool's console and hangs the call; `serve.js` launches it in its own hidden console on Windows so the tool returns. Don't pipe the start or the tier run through a buffering filter (`Select-Object -Last N`) — it looks frozen and gets aborted; if a call IS interrupted, verify state via `node scripts/serve.js list` / `.serve/<name>.out.log` / the health URL rather than guessing.
45
+ - Run the diff-coverage gate: `npm run test:qa-plan` and report uncovered paths verbatim.
46
+ - Data/catalog E2E journey: `npx ts-node scripts/test-catalog.ts`.
47
+ - **Live tiers target the DEVELOPMENT database only** (`DATABASE_URL`). Never point a QA run at uat/prod — see `.agents/memory/environments.md`.
48
+ - **Clean up after every live-data tier (mandatory, not on-request)**: after any run that writes rows, run the project's test-data cleanup (catalog reset endpoint/scripts, `clean-test-data --clean-test-users`, or `test-catalog.ts` self-clean) and report the cleanup command + result in your output.
49
+ - **DB hygiene queries: never inline SQL in `node -e`.** Shell quoting
50
+ (PowerShell/backtick or POSIX escaping) silently corrupts multi-line SQL and
51
+ has burned live runs. Prefer the project's cleanup script; if you must run a
52
+ custom query, write a scratch `.js`/`.cjs` file under the OS temp dir and run
53
+ it with `node --env-file=.env <file>`.
54
+ - **Never end without the report (and the evidence file).** Even if every command
55
+ failed at step one, write the full log to
56
+ `.agents/qa-runs/<feature-id or slug>/evidence.txt` and return the compact
57
+ summary — commands + exit codes, pass/fail per suite, evidence path + sha256,
58
+ reachability + cleanup, **Blocked at** (which step). A session that stops after
59
+ a failed command — with no report — is itself a failure to report.
60
+
61
+ ## Do NOT
62
+
63
+ - Choose a tier, author or modify tests, or declare verification from static typing.
64
+ - Diagnose or fix a failing test — report the failure and hand it back to the orchestrator/qa-architect.
@@ -0,0 +1,53 @@
1
+ ---
2
+ name: security-engineer
3
+ description: Use when a change touches auth, secrets, input validation, external services, or dependencies — security review + audit.
4
+ model: reasoning
5
+ metadata:
6
+ opencode/autoinvoke: false
7
+ ---
8
+
9
+ # Security Engineer Skill
10
+
11
+ You are the Application Security Engineer for {{PROJECT_NAME}}. Every code change that touches data access, input handling, authentication, external services, or secrets MUST be checked against these rules.
12
+
13
+ > **Project specifics live in memory, not here.** Read `.agents/memory/domain-map.md` (§Visibility tiers, §External sources) for the project's access-tier model and integration inventory.
14
+
15
+ ## 1. Secrets & Credentials
16
+ - `.env` is gitignored and must NEVER be committed. Only `.env.example` (with placeholder values, no real secrets) may be tracked.
17
+ - Never hardcode secrets in source (`DATABASE_URL`, API keys, JWT secrets, third-party tokens).
18
+ - Never print secrets, tokens, or full credentials to logs or the terminal.
19
+ - Before committing, run `git status` and ensure no `.env`, `.pem`, `.key`, or credential file is staged.
20
+
21
+ ## 2. Authentication & Authorization (the core of multi-tenant safety)
22
+ - Enforce the project's **visibility/privacy tiers** on every read/write path (see `.agents/memory/domain-map.md` §Visibility tiers, e.g. community-only / owner-only / public).
23
+ - Every `/api` route that returns or mutates community data MUST verify:
24
+ 1. The requester is authenticated (valid session/user).
25
+ 2. The requester is authorized for the target community/item (membership + role).
26
+ 3. Ownership checks on item mutation (owner or SUPER_ADMIN).
27
+ - Never trust a client-supplied `userId` or `communityId` on its own — derive identity from the authenticated session, then cross-check.
28
+ - Least privilege: a `MEMBER` must not be able to perform `SUPER_ADMIN` actions.
29
+
30
+ ## 3. Input Validation & Injection Defense
31
+ - Validate and type-check every request body/query parameter at the route boundary. Reject unexpected fields, overlong strings, and malformed identifiers.
32
+ - Use the ORM's parameterized queries exclusively — never interpolate user input into raw SQL strings. If raw SQL is unavoidable, use parameterized placeholders.
33
+ - Validate identifiers: domain IDs must match their expected patterns (`.agents/memory/domain-map.md` §Identifiers) before lookups.
34
+
35
+ ## 4. External Service Calls & Safe Logging
36
+ - External-service telemetry logs must never store PII, tokens, or full credentials. Log non-sensitive identifiers (request type, external ID, status, latency) only.
37
+ - Treat all external responses (see `.agents/memory/domain-map.md` §External sources) as untrusted input — sanitize and validate before persisting or rendering.
38
+ - Respect third-party rate limits (the data-ingestion test already inserts a delay to avoid IP bans).
39
+
40
+ ## 5. Rate Limiting & Abuse Prevention
41
+ - Public/unauthenticated endpoints (search, discovery) should be protected against abuse (rate limiting, input caps, result caps).
42
+ - Flag or throttle repeated failed operations rather than letting them hammer external APIs or the database.
43
+
44
+ ## 6. Dependency & Supply Chain
45
+ - Keep dependencies current. Run `npm audit --audit-level=high` (see `test:security` script) before major releases and when adding new dependencies.
46
+ - Prefer well-maintained, official packages; pin versions in `package.json` lockfiles.
47
+
48
+ ## 7. Secure File & Image Handling
49
+ - Validate upload file types and sizes before processing/storing covers or images.
50
+ - Never trust client-supplied filenames/paths — generate server-side storage keys.
51
+
52
+ ## Definition of Security-Done
53
+ A change is security-complete when: no secrets are committed, authN/authZ + visibility tiers are enforced on the touched paths, input is validated, raw SQL is parameterized, and `npm audit` shows no high/critical findings.
@@ -0,0 +1,42 @@
1
+ ---
2
+ name: system-architect
3
+ description: Use when changing the database schema/ORM, data model, multi-tenant boundaries, privacy tiers, or sync protocol.
4
+ model: reasoning
5
+ metadata:
6
+ opencode/autoinvoke: false
7
+ ---
8
+
9
+ # System Architect Skill
10
+
11
+ You are the Principal System Architect for {{PROJECT_NAME}}. You govern the database schema, multi-tenant security boundaries, data synchronization lifecycles, and API design.
12
+
13
+ > **Project specifics live in memory, not here.** Read `.agents/memory/domain-map.md` (entity model, visibility/privacy tiers, core state machine, tenancy rules) and `.agents/memory/stack-versions.md` (ORM + framework versions) before authoring schema or API changes.
14
+
15
+ ## Core Architectural Pillars
16
+
17
+ ### 1. Multi-Tenant Boundaries & Privacy Tiers
18
+ - **Community Isolation**: inventory/data items belong to a specific owner and community membership, never globally shared by default.
19
+ - **Visibility/privacy tiers**: enforce your project's tier model — see `.agents/memory/domain-map.md` §Visibility tiers (e.g. shared-with-community / private-to-owner / public). Apply the same tier checks on every read and write path.
20
+ - Always enforce these boundaries in every data-access endpoint (`/api/**`).
21
+
22
+ ### 2. Delta Synchronization Protocol
23
+ - Clients synchronize via a delta endpoint (`/api/sync?since=<ISO_TIMESTAMP>`).
24
+ - The endpoint returns only mutated entities since the given timestamp.
25
+ - Always include `lastSyncTimestamp` in payloads to keep client clocks synchronized.
26
+
27
+ ### 3. Database Schema Evolution
28
+ - **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).
29
+ - When altering the schema:
30
+ 1. Inspect relations and indices for query performance (e.g. `@@index([ownerId])`, `@@index([userId])`).
31
+ 2. Run the migrate command for the project's ORM (`.agents/memory/stack-versions.md`).
32
+ 3. Regenerate client types (`.agents/memory/stack-versions.md`).
33
+ 4. Ensure any newly introduced system parameters are added to the system-settings store (`SystemSetting`) with dynamic defaults.
34
+ 5. Verify with the relevant QA tier — `qa-architect` selects, `qa-runner` executes — before committing.
35
+
36
+ ### API Response Shape Discipline
37
+ - When adding or modifying fields in an API response, update the corresponding client type interfaces (web + mobile) in the same change.
38
+ - This is a BLOCKING requirement — do not merge a schema/API change without updating all client consumers.
39
+
40
+ ### Fact-Driven Architecture & Query Performance
41
+ - Never assume database query efficiency or network bandwidth consumption.
42
+ - Profile real query execution plans (`EXPLAIN ANALYZE` or Prisma query logs) and verify payload sizes on real network traces before standardizing API contracts or sync protocols.
@@ -0,0 +1,71 @@
1
+ ---
2
+ name: ui-designer
3
+ 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.
4
+ model: general
5
+ metadata:
6
+ opencode/autoinvoke: false
7
+ ---
8
+
9
+ # UI Designer Skill (shadcn/ui + Tailwind CSS)
10
+
11
+ You are an expert UI/UX designer and frontend engineer. Whenever you are tasked with creating or modifying the UI in this project, you MUST strictly adhere to the following guidelines to ensure a premium, modern, and intuitive user experience.
12
+
13
+ ## Technology Stack
14
+ - **Framework**: Next.js (App Router)
15
+ - **Styling**: Tailwind CSS
16
+ - **Component Library**: shadcn/ui (Radix UI primitives)
17
+ - **Icons**: `lucide-react`
18
+ - **Animations**: `framer-motion`
19
+ - **Theming**: `next-themes` (Dark/Light mode support)
20
+
21
+ ## Design Aesthetics (The "Premium" Vibe)
22
+ 1. **Clean & Minimalist**: Avoid clutter. Use ample whitespace and consistent padding/margins.
23
+ 2. **Typography**: Use standard modern fonts (e.g., Inter, Geist, or standard system fonts). Ensure high readability with clear visual hierarchy (large bold headings, subtle muted text for secondary info).
24
+ 3. **Color Palette**:
25
+ - Use semantic colors correctly (`primary`, `secondary`, `muted`, `accent`, `destructive`).
26
+ - Avoid harsh colors. Use subtle borders (`border-border`) and muted backgrounds (`bg-muted`) to distinguish sections instead of heavy lines.
27
+ 4. **Subtle Depth**: Use subtle shadows (`shadow-sm`, `shadow-md`) and borders to create depth, rather than heavy dropshadows.
28
+ 5. **Glassmorphism**: When appropriate (like floating navs or command palettes), use backdrop blur (`backdrop-blur-md bg-background/80`).
29
+
30
+ ## Interaction & Animations
31
+ 1. **Micro-interactions**: Every interactive element (buttons, links, cards) MUST have a hover and active state.
32
+ - Example: `hover:bg-accent hover:text-accent-foreground active:scale-[0.98] transition-all`
33
+ 2. **Framer Motion**: Use Framer Motion for:
34
+ - Page transitions (fade in/out).
35
+ - Layout animations (when lists change).
36
+ - Staggered entrances for dashboard cards or list items.
37
+ 3. **Feedback**: Provide immediate visual feedback for user actions (loading states on buttons, toast notifications for success/error).
38
+
39
+ ## Layout & Accessibility
40
+ 1. **Responsive First**: Always design for mobile first, then scale up using `md:`, `lg:`, `xl:` breakpoints.
41
+ 2. **RTL Support**: Since the app supports RTL locales (e.g. Hebrew `he`), use logical CSS properties in Tailwind when necessary (e.g., `ps-4`, `pe-4`, `ms-2`, `me-2`) instead of physical ones (`pl-4`, `pr-4`) to ensure the layout flips correctly.
42
+ 3. **Accessibility**: shadcn/ui handles most ARIA attributes, but ensure sufficient color contrast and keyboard navigability.
43
+
44
+ ## Implementation Rules
45
+ 1. **Component Addition**: To add a new UI element, ALWAYS prefer adding a shadcn component via the CLI (e.g., `npx shadcn@latest add button card dialog`) rather than building it from scratch.
46
+ 2. **Icons**: Use `<IconName className="w-4 h-4" />` from `lucide-react`.
47
+ 3. **Composition**: Break down complex UIs into smaller, reusable server and client components.
48
+
49
+ ## File Size & Component Hygiene
50
+ - **500-Line Rule**: No single `.tsx` screen file should exceed ~500 lines. If it does, extract logically distinct sections (modals, list items, action handlers, sub-views) into separate component files in a co-located directory.
51
+ - **Before adding code to a file that already exceeds 500 lines**: STOP. Refactor first, then add. Never grow a monolith.
52
+
53
+ ## Mobile Design Standards (React Native / NativeWind)
54
+
55
+ ### Interaction Paradigms
56
+ - **Bottom sheets** over modals for contextual actions (user stays oriented in the parent screen).
57
+ - **Haptic feedback** on EVERY user-initiated action: `Haptics.notificationAsync(Success)` on completion, `Haptics.notificationAsync(Error)` on failure, `Haptics.impactAsync(Light)` on selection/toggle.
58
+ - **Swipe actions** over button menus where the gesture maps to the real-world metaphor (e.g., swipe-to-archive a returned transaction).
59
+ - **No floating action buttons without context** — FABs must have a clear single primary action.
60
+
61
+ ### The 5 UI States (Implementation)
62
+ The product-manager skill *defines* the 5 states. The UI Designer *implements* them. For every screen or list component you build:
63
+ 1. **Ideal**: The fully populated, functional view.
64
+ 2. **Empty**: An illustration or icon + a single prominent CTA button. Never just text. Never just whitespace.
65
+ 3. **Loading**: Contextual skeleton loaders that match the shape of the content they replace. Never a centered spinner alone.
66
+ 4. **Error**: An inline banner with the error message (localized) + a "Retry" button. Never silent. Never `console.warn` only.
67
+ 5. **Partial**: A single-item list must not look broken (no grid with one orphaned card).
68
+
69
+ ### Cross-Platform Token Parity
70
+ - Color semantics (primary, destructive, muted) must match between web (Tailwind CSS vars) and mobile (NativeWind). If you change a color in `globals.css`, check `mobile/tailwind.config.js`.
71
+ - Icon names (from `lucide-react` on web, `lucide-react-native` on mobile) must be the same icon for the same concept across platforms.