nurosys-agents 2.0.0 → 2.1.0

package/.agent/frontend/skills/auth-and-permissions/SKILL.md

@@ -1,43 +1,187 @@
 ---
 name: auth-and-permissions
-description: Add or modify auth-sensitive routes/pages without breaking the current Keystone/Prism auth model.
-when_to_use:
-  - Creating or changing pages under `src/app/[lang]/(dashboard)/(private)/`
-  - Adding permission-gated UI behavior
-  - Updating auth-sensitive API routes under `src/app/api/**`
-references:
-  - project-memory/repo-map.md
-  - project-memory/auth-model.md
-  - project-memory/constitution.md
-  - src/contexts/authContext.tsx
-  - src/utils/auth.ts
-  - src/configs/authConfig.ts
-  - src/types/auth.ts
----
-
-# Auth and Permissions Skill
-
-## Steps
-
-1. Read `project-memory/repo-map.md` and `project-memory/auth-model.md` before touching auth-sensitive code.
-2. For private pages, follow the existing route layout under `src/app/[lang]/(dashboard)/(private)/...`.
-3. For UI permission gating, consume auth state from `useAuth()` in `src/contexts/authContext.tsx`.
-4. Reuse auth helpers from `src/utils/auth.ts` for cookie/token/header behavior; do not duplicate logic.
-5. Keep cookie key contracts centralized in `src/configs/authConfig.ts`.
-6. Extend permission typing in `src/types/auth.ts` when introducing new permission keys.
-7. Add or update tests for authorized/unauthorized behavior where relevant.
-
-## Non-Negotiable Checklist (must all be true)
-
-- [ ] Page/component auth state comes from `useAuth()` in `src/contexts/authContext.tsx`.
-- [ ] Cookie and token handling reuses `src/utils/auth.ts` helpers or approved extensions.
-- [ ] Cookie key usage remains centralized in `src/configs/authConfig.ts`.
-- [ ] No duplicate auth helpers were added outside the canonical auth modules.
-- [ ] Access tests cover both authorized and unauthorized outcomes.
-
-## Deliverable
-
-For each auth-sensitive change, include a short note in PR/plan stating:
-- route path changed
-- permission key(s) used from `src/types/auth.ts` / permission checks
-- where `useAuth()` and auth helpers enforce behavior
+description: Frontend auth & permission guardrails. Audits private routes, useAuth usage, permission-gated UI, and cookie/session handling against the project's documented client-side auth model. Generic across Next.js App Router, Pages Router, Vite/CRA — driven entirely by `project-memory/auth-model.md`. Trigger on changes touching auth, login, logout, session, route guards, useAuth, useSession, permission, role. Also invoked as a sub-agent by `/architect` and `/module-runner`.
+disable-model-invocation: false
+---
+
+# Skill: auth-and-permissions (frontend)
+
+Audits a frontend change for auth correctness. This skill is **fully generic** — it owns the *checks*, but the project's specific context provider, useAuth hook, route-gating mechanism, cookie helpers, and permission keys all come from `project-memory/auth-model.md`.
+
+**Important reminder:** Client-side auth is **never** the security boundary. The server must enforce. This skill audits whether the **UI correctly reflects** the auth model — not whether the auth model itself is sound (that's `/security-assessment`'s job).
+
+**Three invocation modes:**
+
+1. **Manual / standalone** — Triggered by user or `/code-reviewer` for PR-level auth review. Produces a structured checklist note in chat.
+2. **Sub-agent mode (planning_input)** — Invoked by `/architect` during planning. Returns JSON drafting the auth approach for a planned module before implementation.
+3. **Sub-agent mode (findings)** — Invoked by `/module-runner` per-module review. Returns JSON with findings.
+
+Detect sub-agent modes from the parent prompt: "mode=subagent" or "sub-agent mode" + role (architect / module-runner).
+
+---
+
+## Phase 1 — Load the auth model
+
+Read `project-memory/auth-model.md`. Extract:
+
+| Concept (generic) | What you learn from auth-model.md (project-specific) |
+|---|---|
+| **Context provider** | The component/file that provides auth state app-wide (e.g. `<AuthProvider>`) |
+| **useAuth hook** | The hook (or helper) that exposes the authenticated user, permissions, login/logout |
+| **Private-route convention** | How a route is marked private — file convention (`(private)` segment), HOC, middleware, server-side check, etc. |
+| **Public-route convention** | How a route is explicitly marked public |
+| **Permission keys** | The enumeration of permission strings the UI uses |
+| **Cookie / token helpers** | Names of cookie read/write helpers and what storage layer they use |
+| **Login / logout flows** | The documented endpoints + UI flows |
+| **Server-side counterpart** | What the backend enforces (so the audit can flag client-only "checks") |
+
+If `auth-model.md` does not exist, **STOP**. Tell the user: "Cannot audit auth without `project-memory/auth-model.md`. Run `/create-blueprint auth-model` first."
+
+Also read (skip silently if absent):
+- `project-memory/constitution.md` — non-negotiable rules
+- `project-memory/repo-map.md` — file locations for auth implementation
+
+---
+
+## Phase 2 — Determine scope
+
+| Invocation | Scope |
+|---|---|
+| User-triggered, no args | Changed files on current branch (`git diff --name-only origin/main...HEAD`) |
+| `/auth-and-permissions path:<path>` | Specific path |
+| `/auth-and-permissions route:<route>` | Single route (resolve to its file path via `repo-map.md`) |
+| Sub-agent from `/architect` | The proposed module's planned UI surface (described in parent prompt) |
+| Sub-agent from `/module-runner` | Current module's diff |
+
+---
+
+## Phase 3 — Identify the audit surface (Serena, ≤6 calls)
+
+- `get_symbols_overview` on each changed file to see what's there
+- `find_symbol` on the context provider name from `auth-model.md` — verify it wraps the right scope
+- `find_symbol` on the useAuth hook name — list its callers via `find_referencing_symbols`
+- Identify changed pages under the documented private-route convention
+- Identify components using documented cookie/token helpers
+
+---
+
+## Phase 4 — Run the checks (generic, driven by auth-model)
+
+### 4.1 Private-route gating
+
+- [ ] Every page under the documented private-route convention is wrapped by the documented gate (server-side check, HOC, layout, or middleware — per `auth-model.md`).
+- [ ] No private page renders sensitive UI before auth has resolved (no flicker of authenticated content for unauthenticated users).
+- [ ] No private page directly reads cookies/tokens; everything goes through the documented helpers.
+
+### 4.2 useAuth as the single source of truth
+
+- [ ] Components that need user identity or permissions use `useAuth()` (or the documented equivalent) — not ad-hoc context, not direct cookie reads, not props drilled from a random ancestor.
+- [ ] No duplicate context providers for the same data.
+- [ ] No login state derived from the URL or local component state in places where it should come from the auth model.
+
+### 4.3 Permission-gated UI
+
+- [ ] Permission checks use keys from the documented permission enumeration in `auth-model.md` — no ad-hoc strings (e.g. `'user.edit'` typo'd as `'user-edit'`).
+- [ ] Permission checks gate UI elements appropriately (buttons disabled or hidden, menu items omitted, etc.) but DO NOT replace server-side enforcement.
+- [ ] Negative-case UI is intentional: disabled with tooltip / hidden / "Not authorized" message — not silent failure on click.
+
+### 4.4 No client-only security checks
+
+- [ ] Any UI logic that *protects sensitive data* must have a server-side counterpart. Hiding a "Delete user" button is fine; making `DELETE /api/users/:id` succeed only if the UI was visible is not.
+- [ ] No client-only feature flags that gate access to data — the server must enforce.
+
+### 4.5 Cookie / storage hygiene
+
+- [ ] Sensitive tokens are not stored in `localStorage` / `sessionStorage` unless explicitly documented in `auth-model.md` (default: must be `httpOnly` cookies).
+- [ ] Cookie writes/reads go through the documented helpers — no `document.cookie` raw access in feature code.
+- [ ] Login/logout flows follow `auth-model.md` exactly — no shortcut bypasses.
+
+### 4.6 Loading and error states for auth
+
+- [ ] Components don't assume `user` is truthy when auth is still loading.
+- [ ] Logout / session-expired states clear sensitive cached data (SWR / React Query / Zustand stores per `auth-model.md`).
+- [ ] Permission-denied responses from the server trigger a clear UX (not a silent stale-data display).
+
+---
+
+## Phase 5 — Output
+
+### 5.1 Manual / standalone mode
+
+Chat response in this structure:
+
+```
+## Auth & Permissions Audit (frontend) — <feature or scope>
+
+**Scope**: <files / routes reviewed>
+**Auth-model reference**: project-memory/auth-model.md (<one-line summary of relevant section>)
+
+### Route inventory
+| Route | Type | Gate | Permission(s) gating UI | Verdict |
+|-------|------|------|--------------------------|---------|
+| /dashboard/users | private | <HOC/middleware name> | users:read (page), users:update (edit button) | ✅ |
+
+### Findings
+| Severity | Issue | File:line | Fix |
+|---|---|---|---|
+| BLOCKER / HIGH / MED / LOW | ... | ... | ... |
+
+### Verdict
+- **Decision**: ✅ Clear / ⚠️ Fix required / 🛑 Block
+- **Required fixes before merge**: <list, or "none">
+```
+
+Severity guide:
+- `BLOCKER` — missing gate on a private route, sensitive data exposed before auth resolves, raw token in `localStorage`, hardcoded auth secrets in client code
+- `HIGH` — permission-key typos that silently miss the gate, missing server-side counterpart for client-only check
+- `MED` — cookie attribute misses (when client controls them), duplicate context providers
+- `LOW` — stylistic / minor refactor recommendations
+
+### 5.2 Sub-agent mode — when called by `/architect` (planning input)
+
+Return JSON describing the **recommended auth approach** for the planned module. No file written.
+
+```json
+{
+  "mode": "planning_input",
+  "routes": [
+    {
+      "route": "/dashboard/users",
+      "type": "private",
+      "gate": "<gate mechanism from auth-model: HOC/layout/middleware/server-check>",
+      "page_permission": "<permission key gating page access, or null>",
+      "ui_gates": [
+        { "ui_element": "Edit button", "permission": "users:update", "negative_ux": "disabled with tooltip" }
+      ],
+      "use_auth_consumers": ["<list of view/component names that need useAuth>"],
+      "data_dependencies": "<what the page fetches; which fetches require auth context>"
+    }
+  ],
+  "notes": "<one short paragraph of non-obvious considerations>"
+}
+```
+
+### 5.3 Sub-agent mode — when called by `/module-runner` (review)
+
+Return JSON with audit findings (same shape as `/security-assessment`):
+
+```json
+{
+  "verdict": "clean" | "fix_required" | "block",
+  "findings": [
+    { "severity": "BLOCKER|HIGH|MED|LOW", "issue": "...", "file": "<path:line>", "fix": "..." }
+  ]
+}
+```
+
+`verdict = block` for any BLOCKER. `verdict = fix_required` for any HIGH. `verdict = clean` otherwise.
+
+---
+
+## Do not
+
+- Hardcode framework-specific names (context names, hook names, file paths). If you find yourself writing a literal class/hook name in this skill, stop — the right name lives in `project-memory/auth-model.md`.
+- Recommend installing an alternate auth library. The documented system is the system.
+- Fix code in this skill. Surface findings; fixes happen in `/module-runner` or by the user.
+- Update `project-memory/auth-model.md`. If the model itself is wrong, the user runs `/create-blueprint auth-model` to refresh it.
+- Confuse UI permission display with security. This skill audits **UI correctness**, not server enforcement. Server enforcement is the backend's job and out of scope here.

package/.agent/frontend/skills/brainstorm/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: brainstorm
+description: Explore 3-5 distinct approaches to a frontend problem, feature, or design decision. Outputs structured options with tradeoffs and a recommendation. No code, no implementation, no planning artifacts — pure ideation. Use BEFORE `/ux-architect` (UI work) or `/architect` (technical refactor) when the right approach is not yet obvious. Trigger with `/brainstorm <problem statement>`.
+disable-model-invocation: false
+---
+
+# Skill: brainstorm
+
+The thinking-out-loud skill. You produce **3-5 distinct approaches** to a problem, evaluate each honestly, and recommend one with the key tradeoff named.
+
+This skill **never writes code**, **never writes planning artifacts**, **never updates project-memory**. Its only output is a single structured response in the chat.
+
+Use it before `/architect` when the user hasn't yet decided _how_ to solve something. Use `/architect` after the user picks an approach.
+
+---
+
+## Phase 1 — Frame the problem
+
+Restate the problem in **one paragraph**. Capture:
+- What the user wants to achieve (the goal, not the solution)
+- The constraints they've stated explicitly
+- The implicit constraints you can infer from project-memory (only if relevant — read `constitution.md` only if the user's problem touches a constitutional concern)
+
+If the problem statement is too vague to generate distinct approaches, ask **exactly one** clarifying question and stop. Do not generate options on a misframed problem.
+
+---
+
+## Phase 2 — Light context gathering (optional, ≤3 Serena calls)
+
+Only if the problem requires knowing what currently exists in the codebase. Examples:
+- "Should we add rate limiting?" → check if any rate-limiting exists today (`find_symbol` for likely names)
+- "How should we structure feature X?" → look at how similar features are structured (`get_symbols_overview` on 1-2 sibling feature dirs)
+
+If the problem is purely conceptual ("JWT vs session cookies for our use case"), skip this phase entirely.
+
+**Hard cap: 3 Serena calls.** Brainstorming is cheap reasoning, not deep research.
+
+---
+
+## Phase 3 — Generate 3-5 distinct approaches
+
+Each approach must be **genuinely different in mechanism**, not just a parameter tweak of the same idea.
+
+Examples of distinct approaches:
+- For rate limiting: (a) Redis-backed token bucket middleware, (b) Postgres-row-based counter with cron eviction, (c) external service (Cloudflare/upstash), (d) per-handler decorator-based throttle.
+
+Examples of NOT distinct (these are variants of one approach):
+- (a) Redis with 60s window, (b) Redis with 5min window, (c) Redis with sliding window.
+
+If you can only come up with 2 distinct approaches, output 2. Don't pad to hit 3.
+
+---
+
+## Phase 4 — Evaluate each approach
+
+For each option, produce a compact block. **Use this exact structure** so the user can scan them in parallel:
+
+```
+### Option N: <short name>
+
+**Mechanism**: <one sentence — how it actually works>
+**Pros**: <2-4 bullets, concrete>
+**Cons**: <2-4 bullets, concrete>
+**Complexity**: <Low | Medium | High> — <one phrase justifying>
+**Reversibility**: <Easy | Moderate | Hard> — <one phrase justifying>
+**New dependencies**: <list, or "none">
+```
+
+Be honest about cons. If an option has a serious flaw, name it. The user can't make a good decision from sanitized comparisons.
+
+---
+
+## Phase 5 — Recommend
+
+End with a single **Recommendation** block:
+
+```
+### Recommendation: Option N
+
+**Why**: <one paragraph, the core reason this fits the user's constraints best>
+**Key tradeoff to accept**: <one sentence — the specific downside the user is signing up for>
+**Next step**: <one of: "Run /ux-architect <chosen approach>" (UI/layout work) | "Run /architect <chosen approach>" (technical-only refactor, no UX change) | "Run /quick-execute <task>" if trivial | "Run /create-blueprint <artifact>" if project-memory needs updating first>
+```
+
+If you genuinely cannot pick between two options because they trade off along axes only the user can weigh (e.g. "performance vs ops burden"), say so explicitly and present the choice to the user. Do not fake confidence.
+
+---
+
+## Do not
+
+- Write code (not even snippets — descriptions only)
+- Create files anywhere (`documentation/`, `project-memory/`, `src/`)
+- Use any tool other than read-only Serena/Read (≤3 calls)
+- Pad to N options when only K are genuinely distinct
+- Recommend "it depends" without naming the axes
+- Re-run brainstorm after the user picks — hand off to `/architect` or `/quick-execute`
+
+---
+
+## Example invocation flow
+
+```
+User: /brainstorm we need to add audit logging to all admin actions
+
+You: [Phase 1] Frame: User wants every admin-permission action recorded with actor, target, action type, timestamp. Constraint (from constitution): no PII in logs.
+
+[Phase 2] Skip — purely architectural.
+
+[Phase 3-4] Three options:
+
+### Option 1: Decorator-based audit hook
+**Mechanism**: A @Audit() decorator on controller methods writes to an audit_log table after success.
+**Pros**: ...
+**Cons**: ...
+...
+
+### Option 2: Middleware/interceptor capturing all authed requests
+...
+
+### Option 3: DB-trigger-based row-change capture
+...
+
+### Recommendation: Option 1
+**Why**: ...
+**Key tradeoff to accept**: Devs must remember to add @Audit() — no enforcement at compile time.
+**Next step**: Run /architect "audit logging via @Audit() decorator"
+```

package/.agent/frontend/skills/code-reviewer/SKILL.md

@@ -0,0 +1,307 @@
+---
+name: code-reviewer
+description: Full-stack React code review for frontend changes on the current branch. Reads all project-memory docs, audits changed files against constitution, design-system, auth-model, plus the 23 React-specific rules (Rules of React, rerender optimization, rendering performance, advanced patterns), and writes a structured REVIEW_REPORT. Trigger on any "review my changes", "review this branch", "do a code review", or "review <feature>" request. Also invoked as a sub-agent by `/module-runner`.
+---
+
+# Skill: code-reviewer (frontend)
+
+Perform a thorough React-aware code review of all uncommitted or branch-level changes. Output is a structured review report written to `documentation/reports/` (or the active feature folder), or a JSON findings object in sub-agent mode.
+
+**Two invocation modes:**
+
+1. **Standalone (default)** — Triggered by user. Writes a REVIEW_REPORT file and presents a summary in chat.
+2. **Sub-agent mode** — Invoked by `/module-runner`. Returns JSON findings; no file written.
+
+---
+
+## When to trigger
+
+- User says "review my changes", "do a code review", "review this branch", or similar.
+- User asks for a review of a specific feature/module before merging.
+- Used automatically at the end of each module by `/module-runner`.
+
+---
+
+## Phase 1 — Understand the change surface
+
+### 1.1 Identify changed files
+
+```bash
+git status
+git diff --name-only HEAD
+git diff --name-only --cached
+git diff --name-only main...HEAD   # or origin/main / master / develop per project
+```
+
+Collect modified / added / deleted files, the branch name (to infer feature/milestone), and whether changes are staged/unstaged/committed.
+
+### 1.2 Infer feature and milestone
+
+From branch name or dominant changed-folder under `src/`:
+- **Feature name**: slug after `feature/`, `feat/`, or derived from changed folder (e.g. `user-profile-drawer`).
+- **Milestone**: highest module number under `documentation/features/<feature>/`, otherwise `M0` or omit.
+
+### 1.3 Use Serena symbolic tools first
+
+Before reading any file end-to-end, use Serena.
+
+| Need | Serena tool |
+|---|---|
+| List symbols in a changed file | `get_symbols_overview(relative_path="...")` |
+| Read a specific component / hook body | `find_symbol(name_path="...", include_body=true)` |
+| Find all callers of a hook/component | `find_referencing_symbols(name_path="...", relative_path="...")` |
+| Locate a class/hook/component by name | `find_symbol(name_path="...", substring_matching=true)` |
+| Prior session notes | `list_memories` then `read_memory` if names look relevant |
+
+For each changed file:
+1. `get_symbols_overview` first
+2. For changed symbols, `find_symbol(include_body=true)` to read just that symbol
+3. For risky changes (shared hooks, context providers, app-shell layouts), `find_referencing_symbols` to see consumers
+
+Fall back to raw `Read` only when symbol navigation can't surface the relevant code (configs, plain markdown).
+
+**Token efficiency**: target ≤8 Serena calls for the structural analysis phase.
+
+---
+
+## Phase 2 — Load project-memory
+
+Read all of these (skip silently if absent, note the omission):
+
+| File | Purpose |
+|------|---------|
+| `project-memory/constitution.md` | Non-negotiable rules: React idioms, a11y minimums, performance budgets, no-secret-in-client |
+| `project-memory/quality-playbook.md` | High-signal anti-patterns with symptoms and preferred fixes |
+| `project-memory/auth-model.md` | Client-side auth: context, useAuth, route gating, permission keys |
+| `project-memory/architecture.md` | App-router structure, server/client boundaries, state management approach |
+| `project-memory/design-system.md` | Design tokens, custom wrappers, form patterns |
+| `project-memory/models.md` (if present) | Domain types/interfaces |
+| `project-memory/repo-map.md` | Module layout, reusable components registry |
+| `project-memory/core-memory.md` | Historical decisions, completed modules |
+
+---
+
+## Phase 3 — Review the changed code
+
+For each changed file, tag findings by severity. The React-specific rule set (in `rules/`) drives most of these checks.
+
+### 3.1 Rules of React (CRITICAL — `react-rules-*`)
+
+- [ ] `react-rules-purity` — Components and hooks are pure; no side effects during render
+- [ ] `react-rules-hooks` — Hooks called only at top level, only from React functions
+- [ ] `react-rules-calling` — No components called as functions, no hooks passed as values
+
+### 3.2 Re-render optimization (MEDIUM — `rerender-*`)
+
+13 rules covering: no inline-component definitions, derive state during render (not in effects), memoization boundaries, lazy state init, transitions, ref-transient values, effect-vs-event boundaries, functional setState for stable callbacks, etc. Drill into the specific `rules/rerender-*.md` file for any finding.
+
+### 3.3 Rendering performance (MEDIUM — `rendering-*`)
+
+5 rules: hoist static JSX, ternary over `&&` for conditional rendering, useTransition over manual loading state, CSS `content-visibility: auto` for long lists, Activity for preserving hidden UI state.
+
+### 3.4 Advanced patterns (LOW — `advanced-*`)
+
+2 rules: event-handler refs for stable callbacks, init-once for app-level singletons.
+
+### 3.5 Server / client boundary (per `architecture.md`)
+
+- [ ] `'use client'` directives only where needed (interactivity, hooks, browser APIs)
+- [ ] No server-only utilities imported into client components
+- [ ] Page components stay thin per `architecture.md`; data fetching at the right layer
+- [ ] No NEXT_PUBLIC_* secrets leaked (cross-check with `/security-assessment` for full audit)
+
+### 3.6 Auth correctness (per `auth-model.md`)
+
+- [ ] Private routes use the documented gate
+- [ ] `useAuth()` (or documented equivalent) is the single source of truth for user/permissions
+- [ ] Permission checks use documented keys, not ad-hoc strings
+- [ ] No client-only security checks gating sensitive data
+
+### 3.7 Design-system fidelity (per `design-system.md`)
+
+- [ ] New UI uses documented custom wrappers / Vuexy components — not raw MUI components when a wrapper exists
+- [ ] No new design tokens / colors / spacing introduced inline (must live in the theme)
+- [ ] Forms use the documented pattern (react-hook-form + valibot, per design-system)
+
+### 3.8 Accessibility minimums
+
+- [ ] Interactive elements have semantic HTML or appropriate `role`
+- [ ] Icon-only buttons have `aria-label`
+- [ ] Keyboard nav works (Tab order, Escape on dialogs, focus management)
+- [ ] Color is not the sole carrier of meaning (text/icon paired)
+- [ ] Form fields have visible labels (not placeholder-only)
+
+### 3.9 State management and data fetching
+
+- [ ] State lives at the right scope (local / hook / context / server) per `architecture.md`
+- [ ] No prop drilling >2 levels for data that should be a hook or context
+- [ ] Empty / loading / error states present for every fetch surface
+- [ ] No race conditions in effects (proper cleanup, cancellation)
+
+### 3.10 Architecture alignment
+
+- [ ] Changes respect module topology in `architecture.md`
+- [ ] No new unexpected coupling between layers (page → service is normal; service → page is not)
+- [ ] Pages stay thin — composition lives in views/components
+
+---
+
+## Phase 4 — Determine the output location
+
+| Condition | Output path |
+|-----------|-------------|
+| Active feature with folder under `documentation/features/<feature>/` | `documentation/features/<feature>/REVIEW_REPORT_<feature>_<milestone>.md` |
+| General / no clearly scoped feature folder | `documentation/reports/REVIEW_REPORT_<feature>_<milestone>.md` |
+| No feature identifiable | `documentation/reports/REVIEW_REPORT_<branch-slug>.md` |
+
+---
+
+## Phase 5 — Write the review report
+
+Save to the path from Phase 4. Use this template:
+
+```markdown
+# Frontend Code Review Report
+
+## Feature
+`<feature-name>` — <short description>
+
+## Branch
+`<branch-name>`
+
+## Scope Reviewed
+<Bullet list of changed files/folders and what each covers>
+
+---
+
+## Findings
+
+### BLOCKER
+- **File**: `path/to/Component.tsx:42`
+- **Issue**: <what is wrong>
+- **Rule**: <constitution rule / quality-playbook anchor / `rules/<rule-id>.md`>
+- **Fix**: <minimum change to resolve>
+
+*(none)* if no blockers.
+
+### HIGH
+<Same format. HIGH = must fix before merge.>
+
+*(none)* if none.
+
+### MEDIUM
+<Same format. MEDIUM = should fix in this PR; defer with documented rationale.>
+
+*(none)* if none.
+
+### LOW / SUGGESTION
+<Same format. LOW = nice-to-have improvements.>
+
+*(none)* if none.
+
+---
+
+## React Rules Coverage Summary
+
+| Category | Checked | Findings |
+|----------|---------|----------|
+| Rules of React (CRITICAL) | yes | 0 |
+| Re-render optimization | yes | <count> |
+| Rendering performance | yes | <count> |
+| Advanced patterns | yes | <count> |
+
+## Architecture Alignment
+<1–3 bullets on alignment with project-memory/architecture.md and repo-map.md. Note deviations.>
+
+## Auth and Security Summary
+<1–2 sentences on auth coverage. Reference `/auth-and-permissions` and/or `/security-assessment` for deeper passes.>
+
+## Design-System Fidelity
+<1–2 sentences on whether changes used documented wrappers/patterns or introduced new ones.>
+
+## Quality Gate Status
+
+| Gate | Status | Notes |
+|------|--------|-------|
+| TypeScript compile (`npx tsc --noEmit`) | pass / fail / not run | |
+| Lint (`npm run lint`) | pass / fail / not run | |
+| Unit tests | pass / fail / not run | |
+| E2E tests (if configured) | pass / fail / not run | |
+| Build (`npm run build`) | pass / fail / not run | |
+
+Run the gates feasible in your environment. Report blocked gates and whether they're pre-existing failures unrelated to these changes.
+
+## Recommendation
+
+**APPROVE** / **APPROVE WITH CONDITIONS** / **REQUEST CHANGES**
+
+<1–2 sentences explaining the decision and any required follow-up.>
+```
+
+---
+
+## Phase 6 — Output
+
+### 6.1 Standalone mode
+
+After writing the report, output to the user:
+1. Full path of the written report
+2. Concise inline summary:
+   - Count of blockers / high / medium / low findings
+   - Overall recommendation
+   - Any CRITICAL finding that must be addressed before merge
+
+### 6.2 Sub-agent mode (invoked by `/module-runner`)
+
+Detect from parent prompt: "mode=subagent" or "sub-agent mode".
+
+In sub-agent mode:
+- **Do NOT write a REVIEW_REPORT file.** All findings go in the JSON return value.
+- Auto-approve internal decisions; no clarifying questions.
+- Skip the "Quality Gate Status" section (runner handles build/test separately).
+- Return:
+
+```json
+{
+  "verdict": "clean" | "fix_required" | "block",
+  "counts": { "blocker": 0, "high": 0, "medium": 0, "low": 0 },
+  "findings": [
+    {
+      "id": "F1",
+      "severity": "BLOCKER" | "HIGH" | "MEDIUM" | "LOW",
+      "category": "react-rules" | "rerender" | "rendering" | "advanced" | "server-client" | "auth" | "design-system" | "a11y" | "state" | "architecture",
+      "rule_id": "<e.g. rerender-no-inline-components — if a rule file matches>",
+      "file": "<path:line>",
+      "issue": "<one sentence>",
+      "fix": "<one sentence>",
+      "required": true | false
+    }
+  ]
+}
+```
+
+`verdict = block` if any BLOCKER. `verdict = fix_required` if any HIGH or MEDIUM with `required=true`. `verdict = clean` otherwise.
+
+The parent (`/module-runner`'s code-fixer step) applies fixes for `required=true` findings only.
+
+---
+
+## Quality gates for the review itself
+
+Before finalizing:
+
+- [ ] Every finding cites a `rules/<rule-id>.md` file, a constitution section, or an `auth-model.md` / `design-system.md` section.
+- [ ] Every finding names the exact `file:line`.
+- [ ] The report describes what's wrong and what the fix is — not what the code does.
+- [ ] Auth and a11y coverage is explicitly confirmed or flagged, not assumed.
+- [ ] No stylistic-preference findings without a rule citation.
+- [ ] Gate status reflects actual command output, not assumptions.
+
+---
+
+## Notes
+
+- This skill reads project-memory but does NOT modify it. `core-memory.md` is updated by `/module-runner`'s Step 7, not here.
+- For dedicated security audit (XSS, CSP, secret leakage, deps), use `/security-assessment`.
+- For dedicated auth audit, use `/auth-and-permissions`.
+- The 23 React-specific rule files live under `.agent/.../code-reviewer/rules/` (one file per rule with explanation, bad/good examples, references).

package/.agent/frontend/skills/{react-quality-review → code-reviewer}/examples.md

@@ -1,6 +1,6 @@
-# React Quality Review Examples
+# Code Reviewer Examples (React)
 
-Use these examples with `.agent/skills/react-quality-review/SKILL.md` and `project-memory/quality-playbook.md`.
+Use these examples with `.agent/frontend/skills/code-reviewer/SKILL.md`, `project-memory/quality-playbook.md`, and the 23 rule files under `rules/`.
 
 ## Example 1: Thin page composition (good)