nurosys-agents 2.0.0

package/.agent/frontend/skills/feature-workflow/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: feature-workflow
+description: Enforce requirement clarification, study, detailed planning, implementation, quality review, and testing for every feature/refactor.
+when_to_use:
+  - Any new feature in `src/app`, `src/components`, `src/services`, or `src/views`
+  - Any refactor that changes behavior
+references:
+  - project-memory/constitution.md
+  - project-memory/repo-map.md
+  - project-memory/quality-playbook.md
+  - project-memory/core-memory.md
+  - .agent/skills/react-quality-review/SKILL.md
+  - .agent/templates/FEATURE_PLAN.md
+  - .agent/templates/REVIEW_REPORT.md
+  - .agent/templates/TEST_PLAN.md
+---
+
+# Feature Workflow Skill
+
+## Required sequence (no skipping)
+
+0. **Foundation read (mandatory)**
+   - Read `project-memory/constitution.md`, `project-memory/repo-map.md`, `project-memory/auth-model.md`, and `project-memory/core-memory.md`.
+1. **Requirement clarification**
+   - Ask clarifying questions where needed.
+   - Capture hard constraints (auth, permissions, performance, data contracts, deadlines).
+2. **Codebase study**
+   - List relevant existing files/modules found before planning implementation.
+3. **Detailed plan**
+   - Define new/changed functions and hooks.
+   - Define shared derivations/selectors and where computed values should live.
+   - List all files to be touched.
+4. **Implementation**
+   - Execute the plan in dependency order.
+5. **Quality review + refactor**
+   - Run `.agent/skills/react-quality-review/SKILL.md`.
+   - Produce `Documentation/reports/REVIEW_REPORT.md`.
+   - Apply required refactors from findings.
+6. **Testing**
+   - Add/run unit tests for pure transforms/selectors.
+   - Add/run integration tests for pages/components where applicable.
+7. **Update memory**
+   - Append the completed module/feature summary to `project-memory/core-memory.md`.
+   - Record key decisions, files changed, tests run, and any carry-forward notes.
+
+## Mandatory artifacts
+
+- Feature plan: `Documentation/features/<feature_name>/FEATURE_PLAN.md` or `Documentation/plans/FEATURE_PLAN.md` (from `.agent/templates/FEATURE_PLAN.md`)
+- Review report: `Documentation/reports/REVIEW_REPORT.md` (from `.agent/templates/REVIEW_REPORT.md`, filled after implementation)
+- Test plan: `Documentation/features/<feature_name>/TEST_PLAN.md` or `Documentation/plans/TEST_PLAN.md` (from `.agent/templates/TEST_PLAN.md`, filled and executed)
+- `project-memory/core-memory.md` (updated after implementation)
+
+## PR gate checklist
+
+- [ ] Clarification questions + constraints documented.
+- [ ] Codebase study lists relevant files reviewed.
+- [ ] Detailed plan lists functions/hooks, shared derivations, computed-value ownership, file touch list.
+- [ ] React quality review executed, `Documentation/reports/REVIEW_REPORT.md` produced, and refactors applied.
+- [ ] Unit tests added for pure transforms/selectors.
+- [ ] Integration tests added/updated for pages/components where applicable.
+- [ ] `project-memory/core-memory.md` updated with implementation outcomes and next-step notes.

package/.agent/frontend/skills/react-quality-review/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: react-quality-review
+description: >
+  Post-implementation quality gate for React/Next.js. Covers Rules of React,
+  re-render optimization, rendering performance, and advanced patterns (23 rules in 4
+  categories). Use after features/refactors and when reviewing React PRs.
+when_to_use:
+  - After any feature implementation
+  - After any refactor (UI, hooks, services, routes)
+  - When writing or reviewing React components, hooks, or state management
+  - When optimizing re-render or rendering performance
+references:
+  - project-memory/quality-playbook.md
+  - project-memory/repo-map.md
+  - project-memory/auth-model.md
+  - src/contexts/authContext.tsx
+  - src/utils/auth.ts
+  - src/services/
+  - .agent/skills/react-quality-review/rules/
+---
+
+# React Quality Review Skill
+
+Run this skill immediately after coding, before merge. It combines the project's playbook checks with detailed React review rules (same taxonomy as the legacy `review-react` skill).
+
+## References
+
+- `project-memory/quality-playbook.md` — definitions and repo anchors
+- `.agent/templates/REVIEW_REPORT.md` — report structure
+- `.agent/skills/react-quality-review/rules/` — one file per rule (explanation, bad/good examples, links)
+- `.agent/skills/react-quality-review/examples.md` — concrete examples
+
+## Rule categories by priority
+
+Performance and correctness are grouped into four categories (23 rules), ordered by typical impact:
+
+| Priority | Category | Impact | Prefix | Rules |
+|----------|----------|--------|--------|-------|
+| 1 | Rules of React | CRITICAL | `react-rules-` | 3 |
+| 2 | Re-render optimization | MEDIUM | `rerender-` | 13 |
+| 3 | Rendering performance | MEDIUM | `rendering-` | 5 |
+| 4 | Advanced patterns | LOW | `advanced-` | 2 |
+
+### 1. Rules of React (CRITICAL)
+
+- `react-rules-purity` — Components and hooks must be pure; no side effects during render
+- `react-rules-hooks` — Only call hooks at the top level and from React functions
+- `react-rules-calling` — Never call components as functions or pass hooks as values
+
+### 2. Re-render optimization (MEDIUM)
+
+- `rerender-no-inline-components` — Never define components inside other components
+- `rerender-derived-state-no-effect` — Derive state during render, not in effects
+- `rerender-memo` — Extract memoized child components to avoid re-renders
+- `rerender-memo-with-default-value` — Hoist default non-primitive props outside memo
+- `rerender-simple-expression-in-memo` — Don’t useMemo for simple primitive expressions
+- `rerender-defer-reads` — Don’t subscribe to state only used in callbacks
+- `rerender-dependencies` — Use primitive values in effect dependencies
+- `rerender-derived-state` — Subscribe to derived booleans, not raw objects
+- `rerender-functional-setstate` — Use functional setState for stable callbacks
+- `rerender-lazy-state-init` — Pass an initializer to useState for expensive values
+- `rerender-move-effect-to-event` — Move interaction logic from effects to event handlers
+- `rerender-transitions` — Use startTransition for non-urgent state updates
+- `rerender-use-ref-transient-values` — Use refs for frequently changing transient values
+
+### 3. Rendering performance (MEDIUM)
+
+- `rendering-hoist-jsx` — Hoist static JSX outside component functions
+- `rendering-conditional-render` — Prefer ternary over `&&` for conditional rendering
+- `rendering-usetransition-loading` — Prefer useTransition over manual loading state
+- `rendering-content-visibility` — Use CSS `content-visibility: auto` for long lists
+- `rendering-activity` — Use Activity for preserving hidden UI state
+
+### 4. Advanced patterns (LOW)
+
+- `advanced-event-handler-refs` — Store latest event handlers in refs for stable callbacks
+- `advanced-init-once` — Initialize app-level singletons once, not per mount
+
+## How to use the rule files
+
+For any finding, open the matching file under `.agent/skills/react-quality-review/rules/`. Each file includes why it matters, incorrect vs correct examples, and reference links.
+
+Examples:
+
+- `.agent/skills/react-quality-review/rules/react-rules-purity.md`
+- `.agent/skills/react-quality-review/rules/rerender-no-inline-components.md`
+
+See `rules/_template.md` and `rules/_sections.md` for structure across rules.
+
+## Required checks (cross-check with playbook)
+
+Use `project-memory/quality-playbook.md` for definitions and repo anchors. Verify at least:
+
+- Derived state and effects (`rerender-derived-state-no-effect`, `rerender-derived-state`, playbook)
+- Effect misuse / event vs effect boundaries (`rerender-move-effect-to-event`, playbook)
+- Memoization boundaries (`rerender-memo`, `rerender-simple-expression-in-memo`, playbook)
+- Duplicate computations and repeated transforms (playbook + relevant `rerender-*` rules)
+- Next.js App Router server/client boundaries (playbook)
+- Dead code or duplicate logic residue (playbook)
+
+## Steps
+
+1. Read `project-memory/quality-playbook.md` and scan changed files against it and the rule list above; drill into specific `rules/*.md` files when something is unclear.
+2. Write `Documentation/reports/REVIEW_REPORT.md` using `.agent/templates/REVIEW_REPORT.md`; include findings and exact file/line pointers. Map severe issues to `react-rules-*` where applicable.
+3. For each finding, propose the smallest refactor that moves code toward playbook anchors and the relevant rule file.
+4. Confirm auth boundaries stay centralized (`src/contexts/authContext.tsx`, `src/utils/auth.ts`, `src/configs/authConfig.ts`).
+5. Attach the completed review report to PR notes.
+
+## Review report template (fill this)
+
+```md
+## Findings
+- [severity] <issue> — <file/path> — <playbook check and/or rule id, e.g. rerender-memo>
+
+## Proposed refactors
+- <refactor action> -> <target file(s)> -> <playbook anchor and/or rule file>
+
+## Files to change
+- <path>
+- <path>
+
+## Tests to add
+- <test name> — <what regression it prevents> — <unit/integration/manual>
+```
+
+For concrete examples, see `.agent/skills/react-quality-review/examples.md`.

package/.agent/frontend/skills/react-quality-review/examples.md

@@ -0,0 +1,24 @@
+# React Quality Review Examples
+
+Use these examples with `.agent/skills/react-quality-review/SKILL.md` and `project-memory/quality-playbook.md`.
+
+## Example 1: Thin page composition (good)
+
+- **File:** `src/app/[lang]/(dashboard)/(private)/apps/search-trend-research/page.tsx`
+- **Pattern used well:** Page delegates most behavior to feature view modules instead of embedding heavy business logic.
+- **Why this matters:** Route files stay easy to reason about and change risk is localized.
+- **Preferred refactor if it degrades:** Move derived data and side effects to hooks/services and keep page as composition shell.
+
+## Example 2: Dialog event flow (good target pattern)
+
+- **File:** `src/components/dialogs/create-campaign/CampaignFormAccordion.tsx`
+- **Pattern to preserve:** Keep submit behavior event-driven; avoid introducing effect-driven submit flags.
+- **Why this matters:** Explicit event flow prevents accidental duplicate side effects.
+- **Preferred refactor if it degrades:** Collapse boolean-triggered effects into explicit handler functions.
+
+## Example 3: Shared transform extraction (poor -> refactor target)
+
+- **File group:** `src/views/apps/prism-analytics/**` and `src/components/reports/utils/**`
+- **Pattern used poorly:** Similar formatting/filtering logic can drift when duplicated across report variants.
+- **Why this matters:** Inconsistent output and bug fixes repeated in multiple places.
+- **Preferred refactor:** Extract canonical helpers into `src/utils/**` or focused service modules and reuse across views.

package/.agent/frontend/skills/react-quality-review/rules/_sections.md

@@ -0,0 +1,26 @@
+# Sections
+
+This file defines all sections, their ordering, impact levels, and descriptions.
+The section ID (in parentheses) is the filename prefix used to group rules.
+
+---
+
+## 1. Rules of React (react-rules)
+
+**Impact:** CRITICAL
+**Description:** Fundamental rules from react.dev that ensure correctness. Components must be pure, Hooks must follow call rules, and components must not be called as functions.
+
+## 2. Re-render Optimization (rerender)
+
+**Impact:** MEDIUM
+**Description:** Patterns to minimize unnecessary re-renders: proper memoization, derived state, functional setState, and effect dependency management.
+
+## 3. Rendering Performance (rendering)
+
+**Impact:** MEDIUM
+**Description:** Techniques to optimize what and how React renders: hoisting static JSX, conditional rendering patterns, content-visibility, and transitions.
+
+## 4. Advanced Patterns (advanced)
+
+**Impact:** LOW
+**Description:** Specialized techniques for edge cases: storing handlers in refs for stable callbacks and one-time initialization patterns.

package/.agent/frontend/skills/react-quality-review/rules/_template.md

@@ -0,0 +1,28 @@
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: Optional description of impact (e.g., "20-50% improvement")
+tags: tag1, tag2
+---
+
+## Rule Title Here
+
+**Impact: MEDIUM (optional impact description)**
+
+Brief explanation of the rule and why it matters. This should be clear and concise, explaining the performance implications.
+
+**Incorrect (description of what's wrong):**
+
+```typescript
+// Bad code example here
+const bad = example()
+```
+
+**Correct (description of what's right):**
+
+```typescript
+// Good code example here
+const good = example()
+```
+
+Reference: [Link to documentation or resource](https://example.com)

package/.agent/frontend/skills/react-quality-review/rules/advanced-event-handler-refs.md

@@ -0,0 +1,55 @@
+---
+title: Store Event Handlers in Refs
+impact: LOW
+impactDescription: stable subscriptions
+tags: advanced, hooks, refs, event-handlers, optimization
+---
+
+## Store Event Handlers in Refs
+
+Store callbacks in refs when used in effects that shouldn't re-subscribe on callback changes.
+
+**Incorrect (re-subscribes on every render):**
+
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+  useEffect(() => {
+    window.addEventListener(event, handler)
+    return () => window.removeEventListener(event, handler)
+  }, [event, handler])
+}
+```
+
+**Correct (stable subscription):**
+
+```tsx
+function useWindowEvent(event: string, handler: (e) => void) {
+  const handlerRef = useRef(handler)
+  useEffect(() => {
+    handlerRef.current = handler
+  }, [handler])
+
+  useEffect(() => {
+    const listener = (e) => handlerRef.current(e)
+    window.addEventListener(event, listener)
+    return () => window.removeEventListener(event, listener)
+  }, [event])
+}
+```
+
+**Alternative: use `useEffectEvent` if you're on latest React:**
+
+```tsx
+import { useEffectEvent } from 'react'
+
+function useWindowEvent(event: string, handler: (e) => void) {
+  const onEvent = useEffectEvent(handler)
+
+  useEffect(() => {
+    window.addEventListener(event, onEvent)
+    return () => window.removeEventListener(event, onEvent)
+  }, [event])
+}
+```
+
+`useEffectEvent` provides a cleaner API for the same pattern: it creates a stable function reference that always calls the latest version of the handler.

package/.agent/frontend/skills/react-quality-review/rules/advanced-init-once.md

@@ -0,0 +1,42 @@
+---
+title: Initialize App Once, Not Per Mount
+impact: LOW-MEDIUM
+impactDescription: avoids duplicate init in development
+tags: initialization, useEffect, app-startup, side-effects
+---
+
+## Initialize App Once, Not Per Mount
+
+Do not put app-wide initialization that must run once per app load inside `useEffect([])` of a component. Components can remount and effects will re-run. Use a module-level guard or top-level init in the entry module instead.
+
+**Incorrect (runs twice in dev, re-runs on remount):**
+
+```tsx
+function Comp() {
+  useEffect(() => {
+    loadFromStorage()
+    checkAuthToken()
+  }, [])
+
+  // ...
+}
+```
+
+**Correct (once per app load):**
+
+```tsx
+let didInit = false
+
+function Comp() {
+  useEffect(() => {
+    if (didInit) return
+    didInit = true
+    loadFromStorage()
+    checkAuthToken()
+  }, [])
+
+  // ...
+}
+```
+
+Reference: [Initializing the application](https://react.dev/learn/you-might-not-need-an-effect#initializing-the-application)

package/.agent/frontend/skills/react-quality-review/rules/react-rules-calling.md

@@ -0,0 +1,66 @@
+---
+title: React Calls Components and Hooks
+impact: CRITICAL
+impactDescription: breaks React's rendering model and optimization
+tags: react-rules, components, hooks, calling-convention
+---
+
+## React Calls Components and Hooks
+
+**Impact: CRITICAL (breaks React's rendering model and optimization)**
+
+React must control when components render and hooks execute. Calling them directly bypasses reconciliation, state management, and optimization.
+
+### Rule 1: Never call component functions directly
+
+**Incorrect (calling component as function):**
+
+```tsx
+function Parent() {
+  // This bypasses React's rendering, no proper lifecycle or state isolation
+  return <div>{Profile({ name: 'Alice' })}</div>
+}
+```
+
+**Correct (use JSX):**
+
+```tsx
+function Parent() {
+  return <div><Profile name="Alice" /></div>
+}
+```
+
+Calling a component as a function makes React treat it as part of the parent's render. This means:
+- No separate fiber node for reconciliation
+- State and effects are tied to the parent
+- Keys and refs don't work as expected
+
+### Rule 2: Never pass Hooks as regular values
+
+**Incorrect (passing hook as prop):**
+
+```tsx
+function ChatRoom({ useStatus }) {
+  const status = useStatus() // Hook passed as value
+  return <p>{status}</p>
+}
+
+<ChatRoom useStatus={useOnlineStatus} />
+```
+
+**Correct (call hook directly, pass result as prop):**
+
+```tsx
+function ChatRoom({ status }) {
+  return <p>{status}</p>
+}
+
+function ChatRoomWrapper() {
+  const status = useOnlineStatus()
+  return <ChatRoom status={status} />
+}
+```
+
+Passing hooks as values makes them opaque to React's static analysis, breaks the Rules of Hooks, and prevents the compiler from optimizing correctly.
+
+Reference: [React calls Components and Hooks](https://react.dev/reference/rules/react-calls-components-and-hooks)

package/.agent/frontend/skills/react-quality-review/rules/react-rules-hooks.md

@@ -0,0 +1,91 @@
+---
+title: Rules of Hooks
+impact: CRITICAL
+impactDescription: violating causes runtime errors and broken state
+tags: react-rules, hooks, top-level
+---
+
+## Rules of Hooks
+
+**Impact: CRITICAL (violating causes runtime errors and broken state)**
+
+Hooks rely on a stable call order. Calling them conditionally or in loops breaks React's ability to track state correctly.
+
+### Rule 1: Only call Hooks at the top level
+
+**Incorrect (hook inside condition):**
+
+```tsx
+function Form({ showName }) {
+  if (showName) {
+    const [name, setName] = useState('') // Conditional hook call
+  }
+  const [email, setEmail] = useState('')
+  return <input value={email} onChange={e => setEmail(e.target.value)} />
+}
+```
+
+**Correct (always call hooks, conditionally use values):**
+
+```tsx
+function Form({ showName }) {
+  const [name, setName] = useState('')
+  const [email, setEmail] = useState('')
+  return (
+    <>
+      {showName && <input value={name} onChange={e => setName(e.target.value)} />}
+      <input value={email} onChange={e => setEmail(e.target.value)} />
+    </>
+  )
+}
+```
+
+**Incorrect (hook inside loop):**
+
+```tsx
+function Filters({ filters }) {
+  const values = []
+  for (const f of filters) {
+    values.push(useState(f.default)) // Hook in loop
+  }
+  return <>{/* ... */}</>
+}
+```
+
+**Correct (extract to child component or use single state):**
+
+```tsx
+function Filters({ filters }) {
+  const [values, setValues] = useState(() =>
+    Object.fromEntries(filters.map(f => [f.id, f.default]))
+  )
+  return <>{/* ... */}</>
+}
+```
+
+### Rule 2: Only call Hooks from React functions
+
+**Incorrect (hook in regular function):**
+
+```tsx
+function getUser() {
+  const [user, setUser] = useState(null) // Not a React component
+  return user
+}
+```
+
+**Correct (hook in component or custom hook):**
+
+```tsx
+function useUser() {
+  const [user, setUser] = useState(null)
+  return user
+}
+
+function Profile() {
+  const user = useUser()
+  return <p>{user?.name}</p>
+}
+```
+
+Reference: [Rules of Hooks](https://react.dev/reference/rules/rules-of-hooks)

package/.agent/frontend/skills/react-quality-review/rules/react-rules-purity.md

@@ -0,0 +1,121 @@
+---
+title: Components and Hooks Must Be Pure
+impact: CRITICAL
+impactDescription: prevents bugs from non-deterministic rendering
+tags: react-rules, purity, side-effects, immutability
+---
+
+## Components and Hooks Must Be Pure
+
+**Impact: CRITICAL (prevents bugs from non-deterministic rendering)**
+
+React assumes components are pure functions: same inputs, same output. Side effects during render cause bugs that are hard to reproduce, especially with concurrent features and Strict Mode.
+
+### Rule 1: Components must be idempotent
+
+**Incorrect (mutating external variable during render):**
+
+```tsx
+let count = 0
+
+function Counter() {
+  count++ // Side effect during render
+  return <p>{count}</p>
+}
+```
+
+**Correct (use state for mutable values):**
+
+```tsx
+function Counter() {
+  const [count, setCount] = useState(0)
+  return <p>{count}</p>
+}
+```
+
+### Rule 2: Side effects must run outside of render
+
+**Incorrect (side effect in render):**
+
+```tsx
+function ProductList({ items }) {
+  analytics.track('viewed', items.length) // Runs on every render
+  return <ul>{items.map(i => <li key={i.id}>{i.name}</li>)}</ul>
+}
+```
+
+**Correct (side effect in effect or event handler):**
+
+```tsx
+function ProductList({ items }) {
+  useEffect(() => {
+    analytics.track('viewed', items.length)
+  }, [items.length])
+  return <ul>{items.map(i => <li key={i.id}>{i.name}</li>)}</ul>
+}
+```
+
+### Rule 3: Props and state are immutable
+
+**Incorrect (mutating props):**
+
+```tsx
+function List({ items }) {
+  items.push({ id: 'last' }) // Mutating prop
+  return <ul>{items.map(i => <li key={i.id}>{i.name}</li>)}</ul>
+}
+```
+
+**Correct (create new values):**
+
+```tsx
+function List({ items }) {
+  const allItems = [...items, { id: 'last', name: 'Last' }]
+  return <ul>{allItems.map(i => <li key={i.id}>{i.name}</li>)}</ul>
+}
+```
+
+### Rule 4: Return values and arguments to Hooks are immutable
+
+**Incorrect (mutating hook return value):**
+
+```tsx
+function useItems() {
+  const items = useContext(ItemsContext)
+  items.sort() // Mutating context value
+  return items
+}
+```
+
+**Correct (copy before mutating):**
+
+```tsx
+function useItems() {
+  const items = useContext(ItemsContext)
+  return [...items].sort()
+}
+```
+
+### Rule 5: Values are immutable after being passed to JSX
+
+**Incorrect (mutating after JSX use):**
+
+```tsx
+function Page({ title }) {
+  const config = { title }
+  const element = <Header config={config} />
+  config.title = 'changed' // Mutating after JSX use
+  return element
+}
+```
+
+**Correct (don't mutate after passing to JSX):**
+
+```tsx
+function Page({ title }) {
+  const config = { title }
+  return <Header config={config} />
+}
+```
+
+Reference: [Components and Hooks must be pure](https://react.dev/reference/rules/components-and-hooks-must-be-pure)

package/.agent/frontend/skills/react-quality-review/rules/rendering-activity.md

@@ -0,0 +1,26 @@
+---
+title: Use Activity Component for Show/Hide
+impact: MEDIUM
+impactDescription: preserves state/DOM
+tags: rendering, activity, visibility, state-preservation
+---
+
+## Use Activity Component for Show/Hide
+
+Use React's `<Activity>` to preserve state/DOM for expensive components that frequently toggle visibility.
+
+**Usage:**
+
+```tsx
+import { Activity } from 'react'
+
+function Dropdown({ isOpen }: Props) {
+  return (
+    <Activity mode={isOpen ? 'visible' : 'hidden'}>
+      <ExpensiveMenu />
+    </Activity>
+  )
+}
+```
+
+Avoids expensive re-renders and state loss.