oh-my-agent-commandcode 0.0.0-stage → 20.38.3

package/skills/oma-frontend/resources/angular-rules.md

@@ -0,0 +1,110 @@
+# Frontend Agent - Angular Rules
+
+Applies when the target project is Angular (`angular.json` present, or `@angular/core` in
+`package.json`). In Angular projects these rules **replace** the React/Next.js-specific
+sections of this skill (shadcn workflow, Server/Client component split, Next.js libraries).
+Cross-cutting rules still apply: accessibility, design tokens, i18n sources of truth,
+self-describing file names, and verification before handoff.
+
+## Core Conventions
+
+1. **Standalone components only** — no new `NgModule`s. Existing NgModule code may stay;
+   migrate opportunistically, never big-bang.
+2. **`ChangeDetectionStrategy.OnPush` on every component.** Prefer zoneless
+   (`provideZonelessChangeDetection`) when the project already opts in.
+3. **Signals first**: `signal`, `computed`, `effect`, signal inputs `input()`, `model()`,
+   and `output()` are the default state primitives. Reach for RxJS only for genuine
+   event streams (see RxJS policy below).
+4. **`inject()` over constructor injection** in new code.
+5. **New template control flow** — `@if` / `@for` / `@switch` / `@defer`. Do not write
+   `*ngIf` / `*ngFor` in new templates.
+6. **Lazy routes**: `loadComponent` / `loadChildren`; colocate feature route configs with
+   the feature.
+7. **Typed Reactive Forms** for anything beyond a single input; validation schemas live
+   next to the form.
+8. **Angular CLI for scaffolding** (`ng generate`); respect the project's generator
+   defaults and file-naming style. For naming, follow the project's existing convention;
+   new projects follow the current Angular style guide (kebab-case basenames).
+9. **UI library**: use the project's detected library (Spartan UI, Angular Material,
+   PrimeNG, …) before hand-rolling components. Tailwind CSS follows
+   `resources/tailwind-rules.md` where applicable.
+10. **Data access**: `HttpClient` (or `httpResource`) lives in injectable services, never
+    inline in components.
+
+## RxJS Policy — Marble Tests Are MANDATORY
+
+Signals cover most component state. RxJS is the right tool for **streams over time**:
+debounced input, cancellation (`switchMap`), merging event sources, websockets, polling.
+
+Interop happens at boundaries only: `toSignal` / `toObservable` from
+`@angular/core/rxjs-interop`. Do not hand-subscribe in components when `toSignal` or the
+`async` pipe can own the subscription.
+
+**Non-negotiable: every non-trivial Observable pipeline ships with a marble test.**
+A stream without a marble test fails review.
+
+"Non-trivial" means the pipeline contains any of:
+
+- time-based operators: `debounceTime`, `throttleTime`, `auditTime`, `delay`, `timer`-driven logic
+- combination operators: `combineLatest`, `withLatestFrom`, `merge`, `zip`, `race`
+- higher-order mapping: `switchMap`, `mergeMap`, `concatMap`, `exhaustMap`
+- error/retry flow: `retry`, `retryWhen`, `catchError` with re-subscription
+- any custom operator
+
+A single synchronous `map`/`filter` on an `HttpClient` call may use a standard async test
+instead — everything else gets marbles.
+
+### Marble test skeleton (`TestScheduler`, runner-agnostic)
+
+```ts
+import { TestScheduler } from 'rxjs/testing';
+import { debounceTime } from 'rxjs';
+
+describe('search query stream', () => {
+  let scheduler: TestScheduler;
+
+  beforeEach(() => {
+    scheduler = new TestScheduler((actual, expected) => {
+      expect(actual).toEqual(expected); // wire to the runner's deep-equal
+    });
+  });
+
+  it('emits only the last value inside the debounce window', () => {
+    scheduler.run(({ cold, expectObservable }) => {
+      const source$ = cold('a 50ms b 199ms c|', { a: 'n', b: 'ng', c: 'ngx' });
+      const result$ = source$.pipe(debounceTime(100));
+      expectObservable(result$).toBe('151ms b 100ms (c|)', { b: 'ng', c: 'ngx' });
+    });
+  });
+});
+```
+
+Rules for marble tests:
+
+1. **Always use `scheduler.run()`** — it virtualizes time, so `debounceTime(300)` needs no
+   real waiting and no scheduler injection into production code.
+2. **Test timing, not just values**: the marble diagram must assert *when* emissions
+   happen, including completion/error frames.
+3. **Cover cancellation** for higher-order mappings (`switchMap` dropping the stale inner
+   observable is exactly the behavior marbles exist to prove) — use `expectSubscriptions`
+   for inner-subscription lifetimes when relevant.
+4. `TestScheduler` is runner-agnostic — it works under Vitest, Jest, and Jasmine/Karma;
+   only the `assertDeepEqual` wiring differs.
+
+## Verification
+
+Before handoff, run the project's Angular checks (typical set):
+
+```bash
+{pm} run lint          # or: ng lint
+bunx tsc --noEmit -p tsconfig.app.json
+{test_cmd}             # e.g. bunx vitest run, ng test --watch=false
+```
+
+Checklist deltas vs the React checklist:
+
+- [ ] New components are standalone + OnPush
+- [ ] No new `*ngIf` / `*ngFor` / `NgModule`
+- [ ] Component state is signal-based unless a stream is genuinely needed
+- [ ] Every non-trivial RxJS pipeline has a passing marble test
+- [ ] Routes added lazily (`loadComponent` / `loadChildren`)

package/skills/oma-frontend/resources/checklist.md

@@ -0,0 +1,76 @@
+# Frontend Agent - Self-Verification Checklist
+
+Run through every item before submitting your work.
+
+## Next.js 16 Conventions
+- [ ] Request-proxy/auth-gate file is named `proxy.ts` (NOT `middleware.ts`) and exports `proxy` (NOT `middleware`)
+<!-- oma-docs:ignore-start -->
+- [ ] Do NOT flag `src/proxy.ts` as dead code or recommend renaming to `middleware.ts`; `proxy.ts` is the canonical Next.js 16+ convention
+<!-- oma-docs:ignore-end -->
+- [ ] Config flags use the `Proxy` form (e.g. `skipProxyUrlNormalize`), not the legacy `Middleware` form
+- [ ] Every `<Link>` passes `prefetch={false}`; any prefetching link is a deliberate high-intent target with an inline reason
+
+## TypeScript
+- [ ] Strict mode, no `any` types
+- [ ] Explicit interfaces for all component props
+- [ ] No TypeScript errors (run the project's configured `typecheck` command; preserve framework checks and the selected TypeScript 7/native-preview executable)
+
+## Styling
+- [ ] Tailwind CSS only (no inline styles, no CSS modules)
+- [ ] Responsive at 320px, 768px, 1024px, 1440px
+- [ ] Dark mode supported (if project uses it)
+- [ ] No hardcoded colors (use Tailwind theme tokens)
+
+## Accessibility (WCAG 2.2 AA)
+- [ ] Semantic HTML elements (`<nav>`, `<main>`, `<button>`)
+- [ ] All images have alt text
+- [ ] Color contrast >= 4.5:1 (normal text), >= 3:1 (large text)
+- [ ] Keyboard navigation works for all interactive elements
+- [ ] ARIA labels on non-obvious interactive elements
+- [ ] Focus indicators visible
+
+## UX States
+- [ ] Loading state (skeleton or spinner)
+- [ ] Error state (user-friendly message + retry action)
+- [ ] Empty state (helpful message + CTA)
+- [ ] Optimistic updates where appropriate
+
+## Recommended product-interface review (advisory)
+
+For new or substantially changed admin consoles, dashboards, SaaS product UI,
+and internal tools, recommend `oma-design` with Interface Design
+`design-review` using [product-interface-review.md](../../oma-design/resources/product-interface-review.md).
+Record `completed`, `recommended-not-run` with a reason, or `not-applicable`.
+An unavailable or omitted advisory review does not block completion; the task's
+required functional, responsive, and accessibility checks still apply.
+
+## Deferred / Stub Markers (transparency)
+- [ ] Every deferred external integration is wrapped in `// TODO(oma-deferred): <vendor or feature>`
+- [ ] Every mock data block has `// MVP: replace with <real-source>` on top
+- [ ] Every save/persist UI has a working storage adapter (localStorage, IndexedDB, or API). Empty `onClick={() => console.log("save")}` does NOT count; wire actual persistence, or mark explicitly: `// TODO(oma-deferred): persist <state> to <storage>`
+- [ ] Reload-after-save round-trips state for any save action surfaced in the UI
+
+## React 19 hook patterns (catch what eslint catches)
+React 19 + recent `eslint-plugin-react-hooks` flag these as hard errors. They aren't style nits; they break runtime behavior. Avoid them at write-time, not "fix later".
+
+- [ ] **Don't put `setState` synchronously inside `useEffect`** (`react-hooks/set-state-in-effect`). Cascading renders trash performance and, in graphics contexts, can exhaust GPU resources. Replace with: derive in render (`const count = items.length`), lazy `useState` initializer (`useState(() => computeOnce())`), move the update into the event handler that triggered it, or `useSyncExternalStore` for external subscriptions.
+- [ ] **Don't read `ref.current` during render** (`react-hooks/refs`). Refs are null on first render and don't trigger re-renders when they attach, so any JSX gated on `ref.current` is wrong. Read refs only inside event handlers or effects. When a child component needs an instance, pass the ref object itself (or use a callback ref); let the child read `.current` from inside its own effect/handler.
+- [ ] **`useEffect` deps complete and stable.** List every referenced reactive value. Wrap object/array literals in `useMemo` so the dep identity doesn't change every render.
+- [ ] **No prop-mirroring via effect.** `useEffect(() => setX(derive(props)))` is always a bug; compute `x` in the render body or memoize.
+
+## react-three-fiber specifics
+- [ ] Heavy components (`Canvas`, drei helpers, anything that touches `window`/WebGL) load via `next/dynamic` with `ssr: false`.
+- [ ] Effects, helpers, and post-process passes mount unconditionally on the relevant state; don't gate them on `ref.current` truthiness in JSX.
+- [ ] Background and lighting work without remote assets when the project doesn't ship a CDN HDR. Solid `<color attach="background">` or local textures beat a `<Environment preset>` that depends on network.
+- [ ] Shadow map sizes scale to the number of lights; default to 1024 unless the scene needs more. Multiple 2048-shadowed lights drain GPU memory on integrated graphics.
+
+## Performance
+- [ ] No unnecessary re-renders (check with React DevTools Profiler)
+- [ ] Memoization matches the project's React Compiler setting: compiler ON (`reactCompiler` in `next.config.*`) → no hand-written `useMemo`/`useCallback`/`React.memo` in new code; compiler OFF → memoize manually (see `tech-stack.md` §React Compiler)
+- [ ] Code splitting for route-level components
+- [ ] Images optimized and lazy-loaded
+
+## Testing
+- [ ] Unit tests for components with logic
+- [ ] User interactions tested (click, type, submit)
+- [ ] Async behavior tested (loading -> data -> display)

package/skills/oma-frontend/resources/error-playbook.md

@@ -0,0 +1,125 @@
+# Frontend Agent - Error Recovery Playbook
+
+When you encounter a failure, find the matching scenario and follow the recovery steps.
+Use the relevant recovery steps. If required information or authority is missing, pause the dependent action and continue independent work.
+
+---
+
+## False Positive: `proxy.ts` flagged as dead code or `middleware.ts` demanded
+
+<!-- oma-docs:ignore-start -->
+**Symptoms**: Reviewer claims `src/proxy.ts` won't be picked up, demands rename to `src/middleware.ts`, or flags the auth gate as not wired.
+<!-- oma-docs:ignore-end -->
+
+1. Check the installed Next.js version and the project's request interception convention.
+2. For a project using the Next.js 16+ proxy convention, inspect `proxy.ts` in the root or `src/` and its `proxy` export.
+3. Verify location, configuration, and relevant tests. A framework entry point need not have application imports.
+4. Correct a finding based only on an outdated filename assumption; retain any wiring or authorization defect supported by evidence.
+5. Reference: https://nextjs.org/docs/messages/middleware-to-proxy
+
+---
+
+## TypeScript Compilation Error
+
+**Symptoms**: `TS2322`, `TS2345`, `Type X is not assignable to type Y`
+
+1. Read the error: which file, which line, which types conflict
+2. Check: is the interface/type definition correct?
+3. Check: is the API response type matching the expected shape?
+4. If API mismatch: update the type to match actual response (don't cast with `as any`)
+5. If generic issue: use explicit type parameter `<Type>` instead of inference
+6. **NEVER do this**: `@ts-ignore`, `as any` (hides type issues without resolving them)
+
+---
+
+## Build Error
+
+**Symptoms**: `next build` fails, `Module not found`, `SyntaxError`
+
+1. Read the full error: which module, which file
+2. If missing dependency: note in result as "requires `npm install X`"; do NOT install yourself
+3. If import path wrong: use `search_for_pattern("export.*ComponentName")` to find actual path
+4. If dynamic import issue: ensure component is client-side (`'use client'`)
+5. Re-run the build only if the user explicitly requested a build; otherwise use relevant non-build checks and report the verification limit.
+
+---
+
+## Test Failure
+
+**Symptoms**: `vitest` FAILED, `expect(X).toBe(Y)` assertion errors
+
+1. Read the error: expected vs received, which test file
+2. `find_symbol("ComponentName")` to check current implementation
+3. Determine: test outdated or implementation wrong?
+   - Test expects old behavior → update test
+   - Component bug → fix component
+4. Re-run the specific test: `npx vitest run path/to/test.ts`
+5. **After 3 failures**: Try a different approach. Record in progress
+
+---
+
+## Hydration Mismatch (Next.js)
+
+**Symptoms**: `Hydration failed`, `Text content does not match server-rendered HTML`
+
+1. Find the component that renders differently on server vs client
+2. Common causes:
+   - `Date.now()` or `Math.random()` in render
+   - Browser-only APIs (`window`, `localStorage`) without `useEffect`
+   - Conditional rendering based on client-only state
+3. Fix: keep the server and first client render identical, then set browser-only state in `useEffect`; use a narrowly scoped `dynamic(..., { ssr: false })` boundary when rendering must be client-only
+4. If third-party component: wrap with `dynamic(() => import(...), { ssr: false })`
+
+---
+
+## API Integration Error
+
+**Symptoms**: `Network Error`, `CORS`, `401 Unauthorized`, wrong data shape
+
+1. **CORS**: Check backend CORS config; is frontend origin allowed?
+2. **401**: Check token; is it in the header? is it expired?
+3. **Wrong data**: Log `response.data` and compare with expected type
+4. **Network Error**: Is the backend running? Correct port?
+5. If backend isn't your responsibility: document the expected API contract in result
+
+---
+
+## Styling / Layout Broken
+
+**Symptoms**: Component renders but looks wrong, responsive breakpoint fails
+
+1. Check Tailwind classes: typo? wrong breakpoint prefix?
+2. Check parent container: is it blocking layout? (`overflow-hidden`, fixed width)
+3. Test at specific breakpoints: 320px, 768px, 1024px, 1440px
+4. Use browser DevTools to inspect computed styles
+5. If dark mode issue: check `dark:` variants applied
+
+---
+
+## Rate Limit / Quota Error (LLM runtime)
+
+**Symptoms**: `429`, `RESOURCE_EXHAUSTED`, `rate limit exceeded` (any vendor runtime: Claude, Codex, etc.)
+
+1. Identify the source. An expected rate-limit response from the application under review is a test result, not an agent-provider quota failure.
+2. For provider quota exhaustion, stop affected provider calls and record the unavailable checks; continue independent authorized work when possible.
+3. Preserve injected session/task/run IDs and the claim path. Save progress/results under the configured memory base using the task/run-scoped names in `../../_shared/runtime/memory-protocol.md`.
+4. Use a valid claim status (`partial`, `blocked`, or `failed`) with the actual cause and unresolved work per `../../_shared/runtime/result-contract.md`; do not invent a `quota_exceeded` status.
+
+---
+
+## Workflow State Unavailable
+
+Follow `../../_shared/runtime/memory-protocol.md`; state storage is independent of the code-intelligence provider.
+
+1. Use the injected progress/result paths and session/task identity.
+2. If a file operation fails, retry once when the failure may be transient.
+3. Preserve work and report the failed path and error to the coordinator. Do not silently redirect artifacts to `/tmp` or mark a missing result as completed.
+4. For read-only tasks, return the result through the runtime's response channel as required by the dispatch contract.
+
+---
+
+## General Principles
+
+- **After 3 failures**: If same approach fails 3 times, must try a different method
+- **Blocked**: If no progress after 5 turns, save current state and record `Status: blocked`
+- **Out of scope**: If you find backend issues, only record in result; do not modify directly

package/skills/oma-frontend/resources/execution-protocol.md

@@ -0,0 +1,46 @@
+# Frontend Agent - Execution Protocol
+
+## Preparation
+Use the task's scope, existing project conventions, and acceptance criteria. Follow `../../_shared/core/execution-policy.md` when it has not already been supplied. Read only references needed by the selected operation; consult lessons or recovery guides for an observed issue. Expand planning depth only when the change requires it.
+
+## Step 1: Analyze
+- Read the task requirements carefully
+- Read `DESIGN.md` if present at the project root; treat Section 9 (Agent Prompt Guide) as authoritative component spec
+- Identify which components, pages, and hooks are needed
+- Inspect existing structure and relevant symbols via `../../_shared/core/code-intelligence.md`; if the configured provider is unavailable, use native search only for paths outside this project or ignored paths
+- Review existing patterns: reference search for `Button` through the configured provider to understand usage conventions. Native search is only for paths outside this project or ignored paths.
+- List assumptions; ask if unclear
+
+## Step 2: Plan
+- Decide on component structure (which are new, which extend existing)
+- Define props interfaces with TypeScript
+- Plan state management approach (Jotai or Zustand for client, nuqs for URL, TanStack Query for server)
+- Identify API integration points (orval-generated TanStack Query hooks when an OpenAPI spec exists; regenerate via the project's `gen:api` task after contract changes)
+- Plan responsive breakpoints and accessibility requirements
+- For requested GPU/canvas effects, cinematic video-scroll, or selected GSAP APIs,
+  choose the matching route in [specialized-visual-implementation.md](specialized-visual-implementation.md).
+- For affected motion, touch, feedback, or interaction performance, apply
+  [shared interaction quality](../../_shared/ui-interaction-quality.md).
+
+## Step 3: Implement
+- **Honor the task's `test_approach`** (see `../../_shared/core/test-approach.md`): for `tdd` tasks, write and run the focused test first (record the RED failure), make the minimal change (GREEN), then continue
+- Typical affected files (choose an order from actual dependencies):
+  1. TypeScript types/interfaces
+  2. API client hooks (orval-generated from OpenAPI when available; hand-written TanStack Query otherwise)
+  3. Reusable UI components (shadcn/ui based)
+  4. Feature components (compose UI + logic)
+  5. Page components (route-level)
+  6. Tests (unit + integration)
+- Follow `resources/tailwind-rules.md` for styling
+
+## Step 4: Verify
+- Check applicable items in `resources/checklist.md`
+- Use `../../_shared/core/common-checklist.md` only for cross-domain verification
+- Check TypeScript strict mode: no errors
+- For `tdd` tasks, append the `TDD_EVIDENCE` block (test command, RED, GREEN) to the result file per `../../_shared/core/test-approach.md`
+- Verify responsive design at 320px, 768px, 1024px, 1440px
+- Test keyboard navigation and screen reader compatibility
+- For a new or substantially changed admin console, dashboard, SaaS product UI, or internal tool, follow the [recommended product-interface review](../../oma-design/resources/product-interface-review.md). Record its advisory outcome; reviewer approval is not a completion prerequisite unless the task explicitly requires it.
+
+## On Error
+See `resources/error-playbook.md` for recovery steps.