nurosys-agents 2.0.0 → 2.1.0

package/.agent/frontend/skills/explore-codebase/SKILL.md

@@ -1,29 +1,48 @@
 ---
 name: explore-codebase
-description: Navigate and understand codebase structure using the knowledge graph
-disable-model-invocation: true
+description: Navigate and understand a React/Next.js codebase efficiently using Serena's symbolic tools. Trigger when the user asks "where is X", "what does Y do", "how is Z wired", "where's the layout for ...", or asks for a tour of a module. Symbol-level navigation, not full-file reads.
 ---
 
-## Explore Codebase
+# Skill: explore-codebase (frontend)
 
-Use the code-review-graph MCP tools to explore and understand the codebase.
+Use Serena to understand the codebase's structure and find specific code, without reading whole files.
 
-### Steps
+## Steps
 
-1. Run `list_graph_stats` to see overall codebase metrics.
-2. Run `get_architecture_overview` for high-level community structure.
-3. Use `list_communities` to find major modules, then `get_community` for details.
-4. Use `semantic_search_nodes` to find specific functions or classes.
-5. Use `query_graph` with patterns like `callers_of`, `callees_of`, `imports_of` to trace relationships.
-6. Use `list_flows` and `get_flow` to understand execution paths.
+1. **Orient with project-memory first**
+   - If `project-memory/repo-map.md` exists, read it — it's the curated map of where things live.
+   - If `project-memory/architecture.md` exists, skim its module-topology and server/client boundary sections.
+   - For app-router projects, `src/app/` is the route tree; `src/app/(public)`, `(dashboard)`, etc. are route groups per `repo-map.md`.
 
-### Tips
+2. **List symbols in candidate files**
+   - `get_symbols_overview(relative_path="<file or dir>")` — shows top-level symbols (components, hooks, exports) without reading their bodies.
+   - For app-router projects, `get_symbols_overview` on `src/app/<route>/page.tsx` and `layout.tsx` is the right starting point.
 
-- Start broad (stats, architecture) then narrow down to specific areas.
-- Use `children_of` on a file to see all its functions and classes.
-- Use `find_large_functions` to identify complex code.
+3. **Locate by name**
+   - `find_symbol(name_path="<name>", include_body=false)` — find a component / hook / type by name. Add `substring_matching=true` for fuzzy.
+   - Use `name_path="<Component>/<method>"` for class methods (rare in React) or named exports.
 
-## Token Efficiency Rules
-- ALWAYS start with `get_minimal_context(task="<your task>")` before any other graph tool.
-- Use `detail_level="minimal"` on all calls. Only escalate to "standard" when minimal is insufficient.
-- Target: complete any review/debug/refactor task in ≤5 tool calls and ≤800 total output tokens.
+4. **Read targeted symbol bodies**
+   - `find_symbol(name_path="...", include_body=true)` — read only the symbol you need.
+
+5. **Trace relationships**
+   - `find_referencing_symbols(name_path="...", relative_path="...")` — find every consumer of a hook / component / type.
+   - This answers "what re-renders when this changes?" and "is this component still used?"
+
+6. **Check Serena memories**
+   - `list_memories` — prior session notes (project_overview, tech_stack, design-system, etc.)
+   - `read_memory(memory_name="...")` if relevant.
+
+## Tips
+
+- **Project-memory before any tool call.** If `repo-map.md` answers the question, don't query Serena.
+- **Symbols before files.** Default to `get_symbols_overview` over `Read`; default to `find_symbol(include_body=true)` over `Read` on a known file.
+- **App router routing**: page files live in `src/app/<route>/page.tsx`. The route's UI is composed by `layout.tsx` (server) + page.tsx + any client components.
+- **Hooks**: project hooks usually live in `src/hooks/` per `repo-map.md` — `find_symbol(name_path="useX")` is the fastest path.
+- **Components**: shared components in `src/components/` or `src/@core/components/`; feature-specific views in `src/views/<feature>/`.
+
+## Token Efficiency
+
+- Target ≤5 Serena calls for any exploration task.
+- If you can't pinpoint what you need in 5 calls, the question is too broad — ask the user to narrow it.
+- Never read a file's whole content just to find one symbol. Use Serena.

package/.agent/frontend/skills/quick-execute/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: quick-execute
+description: Fast execution for small frontend tasks (component bug fixes, prop tightening, a11y label additions, copy tweaks, single-component refactors). No planning gate, no approval cycle. Use when the user asks for a short, well-scoped UI change and there is no need for UX or architectural design. Trigger with `/quick-execute <task>` or natural-language descriptions of a small change.
+disable-model-invocation: false
+---
+
+# Skill: quick-execute
+
+A no-friction execution skill. Skip planning, skip approval gates, ship the change.
+
+**Use it for:** typo / copy fixes, a11y label additions, prop type tightening, conditional rendering fixes, single-component bug fixes (incorrect state, missing dep), simple style tweaks confined to one component, key prop fixes in lists.
+
+**Do NOT use it for:** anything touching UX layout, auth context/route gating, design-system primitives, new pages/routes, or more than ~3 files. Those go through `/ux-architect` or `/architect`.
+
+---
+
+## Phase 1 — Understand the task
+
+Read the user's request. If anything is genuinely ambiguous (not a stylistic preference — a load-bearing decision), ask **exactly one** clarifying question. Otherwise proceed.
+
+If the task description references a file or component the user already has open, treat that as the starting point — don't re-search for it.
+
+---
+
+## Phase 2 — Locate (Serena-first, ≤3 calls)
+
+Use Serena to pinpoint the code that needs to change.
+
+| Need | Tool |
+|---|---|
+| Find a component / hook by name | `find_symbol(name_path="...", include_body=false)` |
+| Inspect a file's structure | `get_symbols_overview(relative_path="...")` |
+| Find callers before changing a hook/component | `find_referencing_symbols(...)` |
+| Read a specific symbol's body | `find_symbol(name_path="...", include_body=true)` |
+
+**Hard cap: 3 Serena calls.** If you can't pinpoint the change in 3 calls, the task is too vague for `/quick-execute` — STOP and recommend `/explore-codebase`, `/ux-architect`, or `/architect`.
+
+Project-memory: do **not** read project-memory docs in this skill. If the change is small enough for `/quick-execute`, it's small enough that constitution-level rules apply only if obviously violated.
+
+---
+
+## Phase 3 — Execute
+
+Make the change. Use Serena's symbolic edit tools where the change is symbol-shaped:
+
+- Replacing a whole component / hook → `replace_symbol_body`
+- Inserting a new component near an existing one → `insert_after_symbol` / `insert_before_symbol`
+- Small in-line edits inside a larger symbol → `replace_content` (regex/string)
+
+For trivial JSX tweaks (single-line conditional, ARIA attribute, key prop), prefer `replace_content` over reading the whole component.
+
+No approval gate. No "here's what I'm about to do" preamble. Just do it.
+
+---
+
+## Phase 4 — Verify
+
+Run the smallest verification that covers the change:
+
+1. **If a test file exists for the affected component** (e.g. `Component.test.tsx`, `Component.spec.tsx`) — run `npm test -- <scoped pattern>`. If it passes, done.
+2. **If no test exists, run the lint check** — `npm run lint` (or equivalent from `package.json` scripts). For TypeScript projects, also `npx tsc --noEmit` is acceptable as a quick gate.
+3. **If neither applies, run build** — `npm run build` (catches type/import errors).
+4. **If none of the above is feasible** — state explicitly: "No automated verification available. Manual check: [one concrete thing — render the page, click X, verify Y]."
+
+Do not write a new test just to verify a `/quick-execute` change. If the change needs new tests, it's outside this skill's scope.
+
+---
+
+## Phase 5 — Summarize
+
+One paragraph. State:
+
+- What changed (1 sentence, file + component/hook)
+- Why (1 sentence, the user's intent restated)
+- How it was verified (1 sentence)
+
+No bulleted lists, no headings, no "what's next" section. Just the paragraph.
+
+---
+
+## Hard Guardrails (STOP and recommend `/ux-architect` or `/architect`)
+
+If during execution you discover any of the following, **stop immediately** and tell the user the task needs `/ux-architect` (for UX/visual decisions) or `/architect` (for technical decomposition):
+
+- The change requires editing more than 3 files
+- The change touches `project-memory/auth-model.md` concerns (auth context, route gating, useAuth, permission keys)
+- The change introduces a new page or route under `src/app/` (or the project's pages directory)
+- The change touches the design-system layer — custom wrappers (`CustomTextField`, `CustomDialog`, etc.), theme tokens, breakpoints
+- The change modifies any context provider, app-shell layout, or top-level provider tree
+- The change requires installing or upgrading a third-party dependency
+- The change crosses the server/client boundary (adding `'use client'`, converting a server component to client, etc.)
+- You realize there are callers/consumers (other components, hooks, pages) that need coordinated updates
+
+Tell the user: "This is bigger than `/quick-execute` is designed for. Recommend `/ux-architect <task>` (if UX/visual changes) or `/architect <task>` (if technical only) to plan it properly." Do not partially execute and leave the system in an inconsistent state.
+
+---
+
+## Do not
+
+- Plan. There is no plan phase in this skill.
+- Ask for approval. The user invoked `/quick-execute` precisely to skip that.
+- Make unrelated improvements ("while I'm here, I also cleaned up the styles..."). Stay in scope.
+- Update `project-memory/core-memory.md`. Small changes don't earn a history entry.
+- Commit or push. Leave that to the user.
+- Introduce new dependencies, change rendering strategy (SSR↔CSR), or restructure hooks/components beyond the original scope.

package/.agent/frontend/skills/refactor-safely/SKILL.md

@@ -1,29 +1,57 @@
 ---
 name: refactor-safely
-description: Plan and execute safe refactoring using dependency analysis
-disable-model-invocation: true
+description: Plan and execute React/Next.js refactors with confidence. Uses Serena's symbolic tools for impact analysis (consumers, references) and symbolic edits (rename, replace_symbol_body, safe_delete_symbol) plus React-specific guardrails for hooks, components, and the server/client boundary. Trigger on "rename", "refactor", "extract", "split", "consolidate", "move" requests.
 ---
 
-## Refactor Safely
+# Skill: refactor-safely (frontend)
 
-Use the knowledge graph to plan and execute refactoring with confidence.
+Symbol-level refactors with bounded blast radius. The rule: **map impact first, then edit**.
 
-### Steps
+## Steps
 
-1. Use `refactor_tool` with mode="suggest" for community-driven refactoring suggestions.
-2. Use `refactor_tool` with mode="dead_code" to find unreferenced code.
-3. For renames, use `refactor_tool` with mode="rename" to preview all affected locations.
-4. Use `apply_refactor_tool` with the refactor_id to apply renames.
-5. After changes, run `detect_changes` to verify the refactoring impact.
+1. **Locate the target symbol**
+   - `find_symbol(name_path="<name>", include_body=true)` — read the current definition.
 
-### Safety Checks
+2. **Map blast radius**
+   - `find_referencing_symbols(name_path="<name>", relative_path="<file>")` — every consumer.
+   - Count and review the result. If >20 consumers and the user asked for a quick rename, surface impact first: "This affects N consumer sites — confirm before I proceed."
 
-- Always preview before applying (rename mode gives you an edit list).
-- Check `get_impact_radius` before major refactors.
-- Use `get_affected_flows` to ensure no critical paths are broken.
-- Run `find_large_functions` to identify decomposition targets.
+3. **Preview the plan**
+   - List files and line ranges that will change.
+   - For renames: old → new name and how many sites update.
+   - For signature changes: list each consumer and how it needs to adapt.
+   - For prop changes: list every component using the prop.
+   - Get user confirmation if the refactor touches more than a single file.
 
-## Token Efficiency Rules
-- ALWAYS start with `get_minimal_context(task="<your task>")` before any other graph tool.
-- Use `detail_level="minimal"` on all calls. Only escalate to "standard" when minimal is insufficient.
-- Target: complete any review/debug/refactor task in ≤5 tool calls and ≤800 total output tokens.
+4. **Apply the edit symbolically**
+   - **Rename**: `rename_symbol(name_path="...", relative_path="...", new_name="...")` — updates definition + all references in one call.
+   - **Replace a component/hook body**: `replace_symbol_body(name_path="...", relative_path="...", body="<new body>")`.
+   - **Insert near a symbol**: `insert_after_symbol` / `insert_before_symbol`.
+   - **Delete safely**: `safe_delete_symbol(name_path="...", relative_path="...")` — verifies no remaining references first.
+   - **Small in-line edits**: `replace_content(relative_path="...", pattern="...", replacement="...")`.
+
+5. **Verify**
+   - `find_referencing_symbols` again after rename — confirm everything was updated.
+   - Run `npm run build && npm run lint` (and tests if scoped) to catch type and lint failures.
+
+## React-specific safety rules
+
+- **Renaming a hook**: confirm every caller is inside another hook or component function. If any caller is at module top level, the rename is unsafe (top-level hooks violate Rules of React) — abort and recommend `/architect` for a deeper refactor.
+- **Changing a hook's parameter or return shape**: flag every consumer that destructures the return value — confirm each one updates correctly. Don't apply a partial change.
+- **Changing a hook's dependency array shape (effects/memos/callbacks)**: flag as needing review — the meaning may change. Do not auto-apply.
+- **Splitting a component**: preserve `displayName` if used in dev tools, tests, or analytics.
+- **Renaming a component used by an app-shell layout** (root layout, providers, error boundaries): surface as a high-impact change before proceeding.
+- **Crossing the server/client boundary**: moving code between `'use client'` and server components is **not** a `/refactor-safely` operation — recommend `/architect`.
+- **Moving a class component → functional component**: out of scope; recommend `/architect`.
+- **Changing a component's props in a way that breaks API**: if `project-memory/design-system.md` documents the component as public, surface the breaking-change risk before proceeding.
+
+## Safety rules (general)
+
+- **Never delete a symbol without `find_referencing_symbols` first.** Use `safe_delete_symbol` which does this check for you.
+- **For cross-module renames** (the symbol is exported and used by other modules), confirm with the user before running `rename_symbol`.
+- **If `project-memory/architecture.md` documents the refactored area as stable/public**, surface that to the user before proceeding.
+
+## Token Efficiency
+
+- Target ≤6 Serena calls per refactor: locate (1) + impact (1) + edit (1) + verify (1-3).
+- Don't re-read files after symbolic edits — Serena's edit tools are reliable; if they returned without error, the change is applied.

package/.agent/frontend/skills/security-assessment/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: security-assessment
+description: Run a standalone security audit on the frontend codebase, a diff, or a specific path. Covers XSS, client-side auth bypass, secret leakage (NEXT_PUBLIC_), CSP & headers, third-party scripts, dependency audit, data exposure, cookies & storage. Outputs a structured SECURITY_ASSESSMENT report with CRITICAL/HIGH/MEDIUM/LOW findings. Trigger with `/security-assessment [scope]` where scope is `diff`, `path:<path>`, or `full`. Also invoked as a sub-agent by `/module-runner` and `/architect`.
+disable-model-invocation: false
+---
+
+# Skill: security-assessment (frontend)
+
+A focused security audit for React / Next.js codebases. Distinct from `/code-reviewer` — that skill checks React quality + correctness; this one goes deep on security only and produces a security-specific report.
+
+**Two invocation modes:**
+
+1. **Standalone (default)** — Triggered by user. Writes `documentation/reports/SECURITY_ASSESSMENT_<YYYY-MM-DD>.md` and presents a summary in chat.
+2. **Sub-agent mode** — Invoked by `/module-runner` (per-module audit) or `/architect` (pre-design review). Returns JSON. Detect via parent prompt saying "sub-agent mode" or "mode=subagent".
+
+---
+
+## Phase 1 — Determine scope
+
+| Invocation | Scope |
+|---|---|
+| `/security-assessment` (no args) | `diff` — audit changed files only (current branch vs main/master) |
+| `/security-assessment diff` | Same as above, explicit |
+| `/security-assessment path:src/app/(public)` | Audit a specific path |
+| `/security-assessment full` | Audit the entire codebase (slow — confirm before proceeding) |
+
+For `full`, ask: "Full-codebase audit may take significant time and tokens. Proceed?" Wait for confirmation. Skip this prompt in sub-agent mode.
+
+For `diff`: `git diff --name-only origin/main...HEAD` (fall back to `main` → `master` → `develop`).
+
+---
+
+## Phase 2 — Load auth model + design-system
+
+Required:
+- `project-memory/auth-model.md` — client-side auth: route gating mechanism, useAuth, permission keys, public-vs-private route convention, what client must enforce vs what backend enforces
+
+If missing, **STOP**. Tell the user: "Cannot run security-assessment without `project-memory/auth-model.md`. Run `/create-blueprint auth-model` first."
+
+Optional (skip silently if absent):
+- `project-memory/constitution.md` — for rules on logging, secret handling, no-PII rules
+- `project-memory/design-system.md` — to identify which custom wrappers handle escaping vs raw rendering
+
+---
+
+## Phase 3 — Map the audit surface with Serena (≤8 calls)
+
+| Need | Tool |
+|---|---|
+| All page / layout files in scope | `find_symbol(name_path="...", substring_matching=true)` on `Page` / `Layout` |
+| Components rendering arbitrary HTML | grep / search for `dangerouslySetInnerHTML` (raw `Bash grep` if Serena doesn't surface it) |
+| `next.config.js` headers / CSP | direct `Read` |
+| Public env-var usage | grep for `NEXT_PUBLIC_` and `process.env.NEXT_PUBLIC_` |
+| Third-party `<script>` tags / `next/script` | grep |
+| `localStorage` / `sessionStorage` writes | grep |
+| Cookie handlers | `find_symbol` on documented cookie helpers from `auth-model.md` |
+
+Build the audit-target list first; read symbol bodies in Phase 4 only as needed.
+
+---
+
+## Phase 4 — Run the audit checks
+
+### 4.1 XSS
+
+For every component or page in scope:
+- `dangerouslySetInnerHTML` usage — is the source trusted? Is it sanitized (DOMPurify, isomorphic-dompurify, sanitize-html)? Flag any uses sourcing from API responses or URL params without sanitization.
+- Raw HTML from markdown libraries — confirm the markdown lib is configured safely (no raw HTML pass-through unless explicitly trusted).
+- URL params reflected directly into the DOM (e.g. `<div>{searchParams.q}</div>` is fine; `dangerouslySetInnerHTML={{ __html: searchParams.q }}` is a finding).
+- Anchor `href` with user-controlled URL — must use `rel="noreferrer noopener"` for `target="_blank"`, and `javascript:` URLs must be filtered.
+- Inline event handlers built from strings.
+
+### 4.2 Client-side auth bypass
+
+- Per `auth-model.md`, every private route must use the documented gate (HOC, middleware, server-side check).
+- Any `if (user.role === ...)` check that controls *access* (not just UI rendering) must have a server-side counterpart — UI checks alone are not security.
+- Flag any direct API calls (in client components) that fetch sensitive data without an auth check on the server side.
+- Verify that login / logout flows match `auth-model.md` (no ad-hoc token reads from URL, no localStorage tokens unless documented).
+
+### 4.3 Secret leakage
+
+- Every `NEXT_PUBLIC_*` env var: examine its value/role. If it looks like a secret (`*_SECRET`, `*_KEY`, `*_TOKEN`, server-only API tokens), it leaks into the client bundle — **CRITICAL**.
+- Hardcoded API keys, JWT secrets, Stripe live keys, etc. in any client-side file — `git grep -nE "(sk_live|pk_live|api[_-]?key|jwt[_-]?secret)"` patterns.
+- Server-only code accidentally imported into a client component (signaled by `'use client'` at top + import of server-only utility).
+- Source maps shipped in production builds (`next.config.js` — `productionBrowserSourceMaps`).
+
+### 4.4 CSP & security headers
+
+Inspect `next.config.js` (or `next.config.mjs`):
+- `Content-Security-Policy` defined? Avoids `'unsafe-inline'` and `'unsafe-eval'`?
+- `frame-ancestors` set (clickjacking protection)?
+- `Strict-Transport-Security`, `X-Content-Type-Options: nosniff`, `Referrer-Policy`, `Permissions-Policy` configured?
+- For other frameworks: `vite.config.ts` plugin equivalents, `_headers` (Netlify), `vercel.json` headers.
+
+### 4.5 Third-party scripts
+
+- All `<script src="https://...">` (and `next/script`) entries: verify the source is intentional and reputable.
+- `crossOrigin` and `integrity` (SRI) attributes for any external script you control loading-order of.
+- Loading-strategy review for `next/script`: `beforeInteractive` for auth-sensitive scripts is suspicious; default `afterInteractive` is safer.
+- Any `eval`-equivalent constructs introduced by third-party libs (e.g. analytics with inline scripts).
+
+### 4.6 Dependency audit
+
+- Run `npm audit --omit=dev` (best-effort; capture summary). Flag CRITICAL/HIGH advisories.
+- Pay special attention to: parsers (markdown, XML, YAML), sanitizers, JWT libs, crypto libs, anything handling user input.
+- Recent diff added a new dep? Justified, reputable, maintained?
+
+### 4.7 Data exposure
+
+- Any component rendering raw token / password / secret fields directly (`<div>{user.apiToken}</div>`).
+- `console.log` / `console.error` calls in client code that include auth tokens, full user objects with PII, API keys.
+- Production-build leaks: ensure `console.*` statements are stripped in production (or that production logger guards them).
+- API responses over-fetching: client components receiving full user objects from server when only a subset is needed (reduce attack surface).
+- Error boundaries / fallback UIs that print stack traces in production.
+
+### 4.8 Cookies & storage
+
+- `localStorage` / `sessionStorage` writes carrying anything sensitive: auth tokens, session IDs, PII. These should be in `httpOnly` cookies instead.
+- Cookie helpers (per `auth-model.md`) — confirm `Secure`, `SameSite=Lax` or `Strict`, `httpOnly` (server-set) where applicable.
+- IndexedDB usage with sensitive data — same rule: not for tokens.
+
+---
+
+## Phase 5 — Synthesize findings
+
+Severity (see `templates/SECURITY_REPORT.md`):
+
+- **CRITICAL** — `NEXT_PUBLIC_*` secret leak, client-only auth gate on sensitive data, hardcoded production credentials, XSS with attacker-controlled HTML reaching the DOM
+- **HIGH** — Missing CSP / `'unsafe-inline'` in CSP, sensitive data in localStorage, missing SRI on third-party scripts loading auth-adjacent code, missing server-side enforcement counterpart
+- **MEDIUM** — Missing security headers, third-party script without integrity hash, PII in client logs, sourcemaps in prod
+- **LOW** — Hygiene: minor unused `NEXT_PUBLIC_` vars, inline event handlers from constants, etc.
+
+Discard speculative findings. Every finding must cite a `file:line`.
+
+---
+
+## Phase 6 — Output
+
+### 6.1 Standalone mode
+
+Write report to `documentation/reports/SECURITY_ASSESSMENT_<YYYY-MM-DD>.md` using `.agent/templates/SECURITY_REPORT.md`. Fill every section. If a section has no findings, write "No findings." — do not delete the section.
+
+Then in chat:
+- Counts: "0 CRITICAL, 2 HIGH, 3 MEDIUM, 1 LOW"
+- The HIGH/CRITICAL findings, one line each
+- The report path
+
+Do not paste the full report into chat.
+
+### 6.2 Sub-agent mode
+
+Do **not** write a file. Return:
+
+```json
+{
+  "verdict": "clean" | "fix_required" | "block",
+  "counts": { "critical": 0, "high": 0, "medium": 0, "low": 0 },
+  "findings": [
+    {
+      "severity": "CRITICAL" | "HIGH" | "MEDIUM" | "LOW",
+      "category": "xss" | "auth_bypass" | "secret_leak" | "csp" | "third_party" | "deps" | "data_exposure" | "storage" | "other",
+      "title": "<short>",
+      "files": ["<path:line>"],
+      "fix": "<one sentence>"
+    }
+  ]
+}
+```
+
+`verdict = block` if any CRITICAL. `verdict = fix_required` if any HIGH. `verdict = clean` otherwise.
+
+The parent (`/module-runner`'s security-fixer phase) consumes this JSON and applies fixes for CRITICAL/HIGH automatically.
+
+---
+
+## Do not
+
+- Write code fixes in this skill. Fixes happen in `/module-runner`'s security-fixer phase or surface to the user.
+- Update `project-memory/`. Findings don't change the source of truth.
+- Speculate. Every finding must be backed by `file:line`.
+- Run `full` without explicit confirmation (in standalone mode).
+- Confuse UI-level permission display with security. Hiding a button doesn't enforce auth — the server must.

package/.agent/frontend/skills/ux-architect/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: ux-architect
+description: Plan the UX, layout, and component composition for a frontend feature BEFORE technical decomposition. Reads project-memory (design-system, repo-map, architecture, auth-model), invokes `/vuexy-component-guide` as a read-only sub-agent to maximize reuse, surveys existing pages/views/components via Serena, and produces `<feature>_UX_PLAN.md`. NEVER writes code. Hands off to `/architect` for technical module decomposition. Trigger with `/ux-architect <feature description>`.
+disable-model-invocation: false
+---
+
+# Skill: ux-architect
+
+The UX/layout planner for frontend features. You design **what the user will see and how it composes from existing components** before the technical decomposition happens.
+
+## Hard guarantee — ux-architect NEVER writes code
+
+This skill produces a single document: `documentation/features/<feature_name>/<feature>_UX_PLAN.md`.
+
+**What ux-architect MUST NOT touch:**
+- Anything under `src/` (pages, components, hooks, services, styles)
+- `next.config.js`, theme files, design-token modules
+- Tests
+- Git
+- Dependencies (`package.json`)
+- `project-memory/` (except optional notes to `core-memory.md` deferred to `/module-runner`)
+
+If you feel the urge to "just sketch the JSX" or "show the component code", stop. The UX plan describes composition; `/module-runner` writes the code later, guided by `/architect`'s technical module plan, which itself consumes this UX plan.
+
+---
+
+## When to trigger
+
+- User asks to "design", "plan UX for", "wireframe", "lay out", or "spec the screen for" a feature
+- A `/brainstorm` session picked an approach that includes new UI
+- The user is about to call `/architect` but the visual/composition decisions haven't been made yet
+
+---
+
+## Output
+
+`documentation/features/<feature_name>/<feature>_UX_PLAN.md` — written using the template at `.agent/templates/UX_PLAN.md`.
+
+Naming:
+- `<feature_name>` is `snake_case` (e.g. `user_profile_drawer`, `bulk_actions_toolbar`)
+
+---
+
+## Phase 0 — Prerequisites (HARD STOP)
+
+Required project-memory files:
+
+- `project-memory/design-system.md`
+- `project-memory/repo-map.md`
+- `project-memory/architecture.md`
+- `project-memory/auth-model.md`
+
+If any are missing, **STOP** and respond:
+
+> ⚠️ `/ux-architect` requires the following project-memory files to ground UX decisions in this project's actual conventions. Missing:
+> - [list each missing file]
+>
+> Run `/create-blueprint all` (or `/create-blueprint <artifact>` for individual ones), then re-invoke `/ux-architect <feature>`.
+
+Do not proceed to Phase 1 until every required file exists.
+
+---
+
+## Phase 1 — Understand intent
+
+Capture, in your own words (one short paragraph):
+
+- **Who is the user?** Role, permission level, context of use.
+- **What do they see?** The screens/dialogs/drawers in play.
+- **What does success look like?** A single sentence describing the user's end state.
+- **Accessibility** — any specific a11y requirements stated or implied (keyboard-only flow, screen-reader-critical, etc.)
+- **Responsive scope** — which breakpoints matter (mobile-first? desktop-only admin?)
+
+If anything load-bearing is ambiguous (not stylistic — actually changes the plan), ask **exactly one** clarifying question and stop. Otherwise proceed.
+
+---
+
+## Phase 2 — Read foundational docs
+
+Read in order:
+
+| File | What you extract |
+|------|------------------|
+| `project-memory/design-system.md` | Design tokens, breakpoints, color/spacing scale, custom-wrapper inventory, theming approach |
+| `project-memory/architecture.md` | App-router structure, server/client boundary rules, state-management approach, data-fetching patterns |
+| `project-memory/repo-map.md` | Where pages/views/hooks/components live, naming conventions, existing reusable components registry |
+| `project-memory/auth-model.md` | Private-vs-public route convention, useAuth pattern, permission keys, route gating mechanism |
+| `project-memory/core-memory.md` (if present) | Prior decisions about similar features — avoid re-litigating |
+
+---
+
+## Phase 3 — Sub-agent consult: `/vuexy-component-guide` (REQUIRED)
+
+This is the **reuse-first** step. Always run it. Run it **before** sketching any layouts — what's available shapes what you propose.
+
+Spawn `/vuexy-component-guide` as a sub-agent (Claude Code Task tool / Cursor subagent / foreground for Codex). The parent prompt includes:
+
+> Sub-agent mode. Proposed UI surface for feature `<feature_name>`:
+> - Pages / routes: [list]
+> - Dialogs / drawers / modals: [list with what each contains]
+> - Forms: [list with field counts and validation needs]
+> - Lists / tables / cards: [list with item shape]
+> - States: empty / loading / error for each fetch surface
+>
+> Return reuse_candidates and gaps per your SKILL.md sub-agent contract.
+
+Capture the returned JSON. Every UI element you proposed should map to either a `reuse_candidate` or a `gap`. If something is unaccounted for in the response, ask the sub-agent to re-run (or surface it as a finding to the user).
+
+---
+
+## Phase 4 — Sub-agent consult: existing-pages reuse (Serena, ≤6 calls)
+
+Identify any existing pages, views, or components this feature should **extend** rather than duplicate.
+
+| Need | Tool |
+|---|---|
+| Find similar pages | `find_symbol(name_path="...Page", substring_matching=true)` |
+| Find similar dialogs/drawers | `find_symbol(name_path="...Dialog", substring_matching=true)` and `...Drawer` |
+| Inspect a candidate page's structure | `get_symbols_overview(relative_path="src/.../page.tsx")` |
+| Read a candidate component body | `find_symbol(name_path="...", include_body=true)` |
+
+Output of this phase: a short list — "Existing components/pages this feature should extend or compose with, with file paths". Surface these in the UX plan's "Reuse from existing app" section.
+
+---
+
+## Phase 5 — Compose the UX plan
+
+Use `.agent/templates/UX_PLAN.md` as the template. Fill every section:
+
+1. **Feature summary** — one paragraph: who, what they see, what success looks like
+2. **Scope decisions** — in scope, out of scope, assumptions (explicit and confirmable)
+3. **Reuse from existing app** — from Phase 4 (pages/components/hooks to extend or compose with)
+4. **Component reuse from design system** — from Phase 3 (`reuse_candidates` from `/vuexy-component-guide`)
+5. **Gaps & new patterns** — from Phase 3 (`gaps` from `/vuexy-component-guide`) — each gap needs a stated plan (build new, propose addition to design system, or close as out-of-scope)
+6. **Pages & routes** — every new or modified route; note `'use client'` decisions
+7. **Page-by-page layout** — for each page, an ASCII wireframe + which components compose each region
+8. **Dialogs / drawers / modals** — trigger, content composition, dismissal behavior
+9. **Forms** — fields, validation rules, submit behavior, error rendering; reference the form pattern from the design system
+10. **State surface** — for every stateful piece: where it lives (local / hook / context / server) and the data shape
+11. **Empty / loading / error states** — required for every list, fetch, and form surface — no exceptions
+12. **A11y** — keyboard nav order, ARIA roles, focus management on dialog open/close, color/contrast considerations
+13. **Responsive** — breakpoint behavior for each layout; mobile-vs-desktop differences spelled out
+14. **Auth gating** — which routes are private, which UI is permission-gated, what `useAuth()` (or documented equivalent) drives each gate
+15. **Design-system fit** — confirm: any new tokens? any new wrappers? Default expectation is no. If yes, surface as a finding requiring design-system extension before implementation.
+16. **Open questions** — any UX decisions deferred because the user needs to weigh in
+
+Each section is text + ASCII + references. No JSX, no CSS, no code.
+
+---
+
+## Phase 6 — Approval gate (HARD STOP)
+
+After writing `_UX_PLAN.md`, **STOP**. Present to the user:
+
+- Path to the UX plan file
+- One-paragraph summary of the visual outcome
+- Any `gaps` from the design-system consult that need a decision
+- Any `Open questions` from Phase 5
+
+Wait for explicit approval. If the user requests changes, update the plan and re-present.
+
+---
+
+## Phase 7 — Hand off to `/architect`
+
+After approval, present the next-step instruction:
+
+> ✅ UX plan approved. The technical module decomposition is the next step.
+>
+> Run: `/architect documentation/features/<feature_name>/`
+>
+> `/architect` will read your UX plan and produce a `MODULE_WISE_PLAN.md` that translates this UX into ordered technical modules (page-layer, view-layer, hooks, services). It will then write per-module prompts that `/module-runner` consumes to build each module autonomously.
+
+`/ux-architect` is done after this hand-off. Do not do `/architect`'s job from here.
+
+---
+
+## Quality gates
+
+Before finalizing the UX plan, verify:
+
+- [ ] Every UI element in scope maps to either a design-system `reuse_candidate` or an explicit `gap` (no UI silently invented)
+- [ ] Every fetch surface has empty / loading / error states defined
+- [ ] Every form has validation rules and a submit-error UX
+- [ ] Every private route has its auth gate named per `auth-model.md`
+- [ ] No new design tokens or wrappers without an explicit "Design-system fit" finding
+- [ ] Open questions are real questions for the user, not deferred decisions you should have made
+
+---
+
+## Do not
+
+- Write code (no JSX, no CSS, no TypeScript types beyond field shape descriptions)
+- Speculate about API shapes — those belong in `/architect`'s technical module plan
+- Skip the `/vuexy-component-guide` consult — reuse-first is the whole point of this skill
+- Propose new custom wrappers without surfacing them as a design-system gap
+- Update `project-memory/`. If the design system itself needs an addition, suggest `/create-blueprint design-system` after this UX plan is approved
+- Create the `documentation/features/<feature_name>/` directory until Phase 5 (avoid empty directories on early-exit)