opencastle 0.32.12 → 0.32.13

package/src/orchestrator/skills/panel-majority-vote/SKILL.md

@@ -1,20 +1,10 @@
 ---
 name: panel-majority-vote
-description: "Run 3 isolated reviewer sub-agents against the same question and decide PASS/BLOCK by majority vote (2/3 wins). Use when deterministic verification is insufficient."
+description: "Runs 3 isolated reviewer sub-agents and consolidates a PASS/BLOCK verdict by majority. Use when the user requests an independent review of code changes, pull requests, design documents, or release notes."
 ---
 
 # Skill: Panel majority vote
 
-## Contract
-
-| Rule | Detail |
-|------|--------|
-| Scope | One run root, one panel key |
-| Artifacts | Reviewers use only declared in-scope artifacts |
-| Runners | Exactly 3 isolated reviewer runs |
-| Verdict | Majority (2/3 wins) |
-| On BLOCK | Consolidated report must include retry summary |
-
 ## Inputs / Outputs
 
 **Inputs:** `<runRoot>`, `<panelKey>` (filesystem-safe), question text, artifact list. Panel dir default: `<runRoot>/panel/`.
@@ -25,84 +15,49 @@ description: "Run 3 isolated reviewer sub-agents against the same question and d
 | Raw reviewer outputs | `<panelDir>/<panelKey>-reviewer-outputs.md` |
 | Consolidated report | `<panelDir>/<panelKey>.md` |
 
-## Procedure
-
-1. **Validate scope** — every artifact path is under `<runRoot>`; list is sufficient to answer the question.
-2. **Spawn 3 reviewers in parallel** — identical prompt to 3 isolated subagents. Optionally write payload to `<panelDir>/<panelKey>-panel-prompt.md`. Required output sections (no others): `VERDICT: PASS | BLOCK`, `MUST-FIX:`, `SHOULD-FIX:`, `QUESTIONS:`, `TEST IDEAS:`, `CONFIDENCE: low | med | high`.
-3. **Persist outputs** — write `<panelDir>/<panelKey>-reviewer-outputs.md` with header (run root, panel key, question, artifacts) and each reviewer output verbatim, separated.
-4. **Consolidate** — count PASS/BLOCK; overall PASS if ≥ 2. Deduplicate MUST-FIX/SHOULD-FIX with reviewer counts. Record disagreements. Include determinize-next recs. If BLOCK, add retry summary.
-5. **Write report** — create `<panelDir>/<panelKey>.md` using `panel-report.template.md`.
-6. **Print summary** — overall verdict + vote tally + report path.
-7. **Log (⛔ hard gate)** — use **observability-logging** skill panel command. Fields: `panel_key`, `verdict`, `pass_count`, `block_count`, `must_fix`, `should_fix`, `reviewer_model`, `weighted`, `attempt`, `tracker_issue`, `artifacts_count`, `report_path`. Link report as verification evidence.
-
-## Notes
-
-- On BLOCK: change the underlying work and re-run; do not re-word the question.
-- After 3 consecutive BLOCKs on the same panel key: create a dispute record per **team-lead-reference** § Dispute Protocol.
 
-## Model Selection
+## Procedure
 
-| Domain | Model |
-|--------|-------|
-| Security, architecture, complex logic | Quality (Claude Sonnet 4.6) × 3 |
-| Feature implementation, UI, queries | Standard (Gemini 3.1 Pro) × 3 |
-| Mixed-domain | Quality × 1, Standard × 2 |
+1. **Validate scope** — every artifact path is under `<runRoot>` and the list is sufficient to answer the question.
 
-Use same model for all 3 reviewers.
+2. **Spawn 3 reviewers in parallel** — start three isolated subagents with identical prompts. Spawn 3 reviewers using `runSubagent` with identical prompts; each reviewer receives the same question, artifact list, and constraints but runs in isolation. Required reviewer output sections (no others): `VERDICT: PASS | BLOCK`, `MUST-FIX:`, `SHOULD-FIX:`, `QUESTIONS:`, `TEST IDEAS:`, `CONFIDENCE: low | med | high`.
 
-## Weighted Consensus Variant
+3. **Persist outputs** — write `<panelDir>/<panelKey>-reviewer-outputs.md` with a header (run root, panel key, question, artifacts) and each reviewer output verbatim, separated.
 
-For subjective decisions where domain expertise should weight more than head-count.
+4. **Consolidate** — parse each reviewer output for its `VERDICT:` line and count PASS votes. Overall verdict = PASS if pass_count ≥ 2; otherwise BLOCK. Deduplicate `MUST-FIX:` and `SHOULD-FIX:` items and annotate each item with `(N/3 reviewers)`.
 
-### When to Use
+```bash
+# count PASS/BLOCK from combined outputs
+pass_count=$(grep -o "VERDICT: PASS" panel/run123-reviewer-outputs.md | wc -l)
+block_count=$(grep -o "VERDICT: BLOCK" panel/run123-reviewer-outputs.md | wc -l)
+verdict=$([ "$pass_count" -ge 2 ] && echo PASS || echo BLOCK)
 
-| Decision Type | Mode |
-|--------------|------|
-| Security vulnerability, code correctness | Simple majority |
-| UI/UX, architecture tradeoffs, data model, naming | Weighted |
+# emit a minimal JSON summary using jq (install jq if needed)
+jq -n --arg panel_key "run123-panel" --arg verdict "$verdict" --argjson pass_count $pass_count --argjson block_count $block_count '{panel_key:$panel_key, verdict:$verdict, pass_count:$pass_count, block_count:$block_count}' > panel/run123-summary.json
+```
 
-### Weight Assignment
+5. **Write report** — create `<panelDir>/<panelKey>.md` with the minimal structure below and reference the generated summary.
 
-Base weight: 1. Add bonuses:
+- Title: Panel `<panelKey>` — Verdict: `PASS | BLOCK` (pass_count/block_count)
+- Highlights: top deduplicated `MUST-FIX` and `SHOULD-FIX` items
+- Evidence: paths to reviewer outputs and `panel/run123-summary.json`
 
-| Factor | Bonus |
-|--------|-------|
-| Domain expertise (relevant to review) | +2 |
-| Confidence high / med / low | +1 / 0 / -1 |
-| Prior success rate >80% (AGENT-PERFORMANCE.md) | +1 |
+6. **Print summary** — overall verdict + vote tally + report path.
 
-Example: Security Expert + high = **4**; Architect + med = **2**.
+7. **Log (⛔ hard gate)** — call the **observability-logging** skill with `panel_key`, `verdict`, `pass_count`, `block_count`, `must_fix`, `should_fix`, `reviewer_model`, `weighted`, `attempt`, `tracker_issue`, `artifacts_count`, `report_path` for verification.
 
-### Voting Protocol
+## Notes
 
-1. Assign weights before spawning.
-2. Spawn with same prompt; collect PASS/BLOCK + confidence.
-3. Score: sum weights by verdict; PASS if PASS score > BLOCK score.
-4. Tie: highest individual weight breaks tie; if equal, default BLOCK.
+- On BLOCK: change the underlying work and re-run; do not re-word the question.
+- After 3 consecutive BLOCKs on the same panel key: create a dispute record per **team-lead-reference** § Dispute Protocol.
+- Model selection: use the same model for all 3 reviewers. See **team-lead-reference** for model routing.
 
-### Conflict Resolution
+## Related Resources
 
-| Scenario | Outcome |
+| Resource | Purpose |
 |----------|---------|
-| Low-weight BLOCKs, high-weight PASSes | PASS; move BLOCK's MUST-FIX → SHOULD-FIX |
-| Domain expert BLOCKs, generalists PASS | BLOCK |
-| All equal weight | Simple majority (2/3 wins) |
-
-### Report Extension
-
-```markdown
-### Weighting
-| Reviewer | Role | Domain | Confidence | Prior Success | Final Weight |
-|----------|------|--------|------------|---------------|-------------|
-| 1 | [Agent] | +X | +X | +X | X |
-
-### Weighted Score
-- PASS: X (reviewers: 1, 3)
-- BLOCK: X (reviewer: 2)
-- **Overall: PASS/BLOCK** (weighted)
-```
-
-### Integration
-
-Same steps 1–7 as standard panel. Differences: assign weights in step 2; use weighted calculation in step 4; add weighting table to report. Team Lead decides simple vs. weighted; include rationale in delegation prompt.
+| `panel-report.template.md` | Report template for step 5 |
+| `REFERENCE.md` | Weighted consensus variant and weighting details |
+| **observability-logging** skill | Panel logging command (step 7) |
+| **team-lead-reference** skill | Model routing and dispute protocol |
 

package/src/orchestrator/skills/performance-optimization/SKILL.md

@@ -1,12 +1,14 @@
 ---
 name: performance-optimization
-description: "Frontend and backend performance optimization patterns including rendering, asset optimization, JavaScript performance, caching, profiling, and code review checklist. Use when optimizing components, reviewing code for performance, or analyzing bundle size and Core Web Vitals."
+description: "Profiles and reduces frontend/backend costs: split bundles, optimize assets, apply caching, and fix Core Web Vitals regressions. Use when profiling Lighthouse/CI regressions, reducing bundle size, or fixing high CLS/LCP/TTI metrics."
 ---
 
 # Performance Optimization
 
 **Rule:** Measure first (`Chrome DevTools`, `Lighthouse`, `Datadog`), optimize second. Set budgets (load time, memory, API latency). Automate in CI/CD.
 
+Domain-specific patterns (rendering, JS, Node optimizations) are referenced in REFERENCE.md to keep this skill concise.
+
 ## Patterns by Domain
 
 | Domain | Key patterns |
@@ -25,6 +27,44 @@ input.addEventListener('input', (e) => fetch(`/search?q=${e.target.value}`));
 let t; input.addEventListener('input', (e) => { clearTimeout(t); t = setTimeout(() => fetch(`/search?q=${e.target.value}`), 300); });
 ```
 
+## Executable Examples
+
+### Dynamic import splitting (example)
+
+```js
+// Lazy-load a heavy chart only on client
+import dynamic from 'next/dynamic';
+const Chart = dynamic(() => import('../components/Chart'), { ssr: false, loading: () => <div>Loading chart…</div> });
+export default function Page(){ return <Chart />; }
+```
+
+### React.memo + profiler pattern
+
+```jsx
+import React, { Profiler } from 'react';
+const Item = React.memo(function Item({data}){ return <div>{data.title}</div>; });
+function onRender(id, phase, actualDuration){ console.log(id, phase, actualDuration); }
+export default function List({items}){
+	return (
+		<Profiler id="List" onRender={onRender}>
+			{items.map(i=> <Item key={i.id} data={i} />)}
+		</Profiler>
+	);
+}
+```
+
+## Profiling Workflow (step-by-step)
+
+1. Run Lighthouse (or CI perf job) and record baseline.
+	 - Checkpoint: failing metric(s) identified (LCP/CLS/FID/TTI).
+	 - Recovery: if noisy, reproduce locally with `--emulated-form-factor=mobile`.
+2. Profile with DevTools Profiler / React profiler or Node `clinic` for backend.
+	 - Checkpoint: hotspot call stacks / long tasks located.
+3. Apply minimal fix (code-split, memoize, reduce payloads, defer non-critical work).
+	 - Checkpoint: targeted change reduces measured hotspot time in profiler.
+4. Re-run Lighthouse/CI perf job and compare; set threshold (e.g., 10% improvement or within budget).
+5. If regression persists, iterate and create a rollback plan; note fixes in changelog.
+
 ## Review Checklist
 
 - [ ] No O(n²)+ algorithms; appropriate data structures

package/src/orchestrator/skills/project-consistency/SKILL.md

@@ -1,119 +1,83 @@
 ---
 name: project-consistency
-description: "Enforce cross-agent consistency in multi-page/multi-component projects. Covers visual design, code patterns, content style, and structural conventions. Essential for convoy parallel execution where multiple agents build different parts of the same app."
+description: "Generates shared CSS variables, validates component naming conventions, and creates layout pattern templates. Use when coordinating a design system, theme, consistent styling, CSS variables, or a component library across parallel agents."
 ---
 
 # Project Consistency
 
-Multiple agents building in parallel make independent decisions about colors, fonts, APIs, and tone. **Consistency must be engineered as shared inputs before parallel work begins — not hoped for afterward.**
+Ensure consistency by producing shared artifacts and automated checks before parallel work begins.
 
 ## Foundation-First Principle
 
-```
-❌ Wrong:  [A] ─┐                    → inconsistent output
-           [B] ─┤→ build in parallel → inconsistent output
-           [C] ─┘                    → inconsistent output
-
-✅ Right:  [foundation] → artifacts → [A] ─┐
-                                      [B] ─┤→ consistent output
-                                      [C] ─┘
-```
-
-**Phase 1 (sequential):** One task creates all shared artifacts.  
-**Phase 2 (parallel):** Every page task imports from Phase 1. No new values, no recreated components.
-
-### The 4 Consistency Dimensions
-
-| Dimension | What drifts | Artifact |
-|-----------|-------------|----------|
-| **Visual** | Color palettes, font choices, spacing units | Design tokens file |
-| **Code** | Component APIs, naming conventions, import paths | UI component library |
-| **Content** | Tone, terminology, heading hierarchy | Style guide brief |
-| **Structural** | Page layout, navigation, responsive breakpoints | Shared layout component |
-
----
-
-## Foundation Phase Artifacts
-
-A foundation task must produce four artifacts. All phase-2 tasks depend on its completion.
-
-| Artifact | Path | Contents |
-|----------|------|----------|
-| **Design tokens** | `src/styles/tokens.css` | CSS custom properties: palette, typography, spacing, motion, shadows, radius, breakpoints. **Rule:** no value outside this file. |
-| **Shared layout** | `src/components/Layout.tsx` (React) · `src/layouts/Layout.astro` (Astro) | Wraps every page: responsive container, header, nav, footer, document head. Import — never recreate. |
-| **UI component library** | `src/components/ui/` | `Button`, `Card`, `Heading`, `Text`, `Link`, `Section`, `Container`, `Grid` — tokens only. API: camelCase props, `variant`/`size`/`className`, no inline `style`. |
-| **Style guide brief** | Inline in foundation prompt (quoted verbatim in page prompts) | Aesthetic direction · typography pairing · content tone · nav labels · page structure pattern · terminology glossary |
-
----
+Phase 1 (sequential): create shared artifacts (tokens, Layout, UI components). Phase 2 (parallel): every page imports from Phase 1; no new tokens or duplicated components.
 
-## Consistency Rules for Page Agents
+### Foundation Artifacts & Page Rules
 
-Every page agent in a multi-agent convoy MUST follow all rules below.
+| Artifact | Path | Page Agent Rules |
+|----------|------|------------------|
+| **Design tokens** | `src/styles/tokens.css` | Import only. Never introduce new color/font/spacing values. |
+| **Shared layout** | `src/components/Layout.tsx` / `Layout.astro` | Wrap every page. Never recreate. |
+| **UI components** | `src/components/ui/` | Import from library. PascalCase components, camelCase props. |
+| **Style guide brief** | Inline in prompts | Match tone + terminology exactly. Follow heading hierarchy. |
 
-| Area | Rules |
-|------|-------|
-| **Visual** | Import tokens only. Never introduce new color, font-size, or spacing values. Flag missing tokens — don't invent inline values. CSS custom properties exclusively; no raw hex or raw `px`. |
-| **Code** | Import `Layout` from shared path — no page-local wrappers. Import UI components from library — don't recreate. PascalCase components, camelCase props, kebab-case CSS classes. Co-locate component files. |
-| **Content** | Match tone from style guide exactly. Use terminology glossary verbatim. Follow heading hierarchy pattern. |
-| **Structural** | Every page uses shared Layout — no exceptions. Follow page structure from brief. Nav labels match brief exactly. Breakpoints from tokens only. |
+**Validation checkpoints:**
+1. Foundation complete: `tokens.css` has all palette/type/spacing vars, Layout renders, UI components compile.
+2. Per-page: `grep -r 'style={{' src/pages/` returns 0 hits (no inline styles). All imports resolve.
 
 ---
 
 ## Convoy Integration
 
-```
-Phase 1: foundation-setup  (1 task, blocks Phase 2)
-├── Agent:  UI-UX Expert or Developer
-├── Creates: tokens.css, Layout, UI component library
-├── Defines: style guide brief (aesthetic, tone, nav labels, terminology)
-└── Output:  all paths documented for Phase 2 prompts
-
-Phase 2: page-building  (N tasks, all parallel)
-├── home-page · about-page · projects-page · contact-page · ...
-└── [every prompt contains the 5 mandatory references below]
-```
-
-### 5 Mandatory References in Every Page Task Prompt
+Phase 1 (sequential): foundation-setup creates tokens, Layout, UI library, and style guide brief. Phase 2 (parallel): every page task imports from Phase 1. Include these 5 references in every page prompt:
 
 ```
-1. Design tokens:  `[path/tokens.css]` — use ONLY these tokens. No new values.
-2. Layout:         `[path/Layout]` — wrap all page content in this component.
-3. UI components:  `[path/src/components/ui/]` — import; do not recreate.
-4. Aesthetic:      [2-3 word direction from foundation]
-5. Content tone:   [tone description from foundation]
+1. Design tokens path   2. Layout path   3. UI components path
+4. Aesthetic direction   5. Content tone
 ```
 
----
-
-## Prompt Template: Foundation Task
+Prompt templates: see [TEMPLATES.md](./TEMPLATES.md).
 
-````markdown
-## Foundation Setup — [project description]
-
-**Aesthetic:** [2-3 word direction] — [one sentence]
-
-Create `[path]/tokens.css`: palette (intent-named), fluid typography (clamp()), spacing (4px base), motion, shadows, radius, breakpoints.  
-Create `[path]/Layout.[tsx|astro|vue]`: responsive container, site header (nav: [labels]), footer, document head.  
-Create `[path]/ui/`: Button, Card, Heading, Text, Link, Section, Container, Grid — tokens only, zero hardcoded values; `variant`/`size`/`className` API.
+---
 
-**Style Guide:** Tone: [formal/casual]. Terminology: [key terms]. Page structure: [hero → ... → CTA].
+## Executable Examples
 
-**Acceptance Criteria:** Zero hardcoded hex/px · Layout responsive at 320/768/1280px · Fluid typography via clamp() · Fonts loaded efficiently
-````
+### Example: `src/styles/tokens.css`
 
----
+```css
+:root {
+	/* Palette */
+	--color-bg: #ffffff;
+	--color-foreground: #0f172a;
+	--color-primary: #0ea5e9;
+	--color-primary-600: #0284c7;
 
-## Prompt Template: Page Task
+	/* Typography */
+	--font-base: 'Inter, system-ui, -apple-system, sans-serif';
+	--text-sm: 0.875rem;
+	--text-base: 1rem;
 
-````markdown
-## Build [Page Name] Page — [purpose, audience, primary action]
+	/* Spacing */
+	--space-1: 4px;
+	--space-2: 8px;
+	--space-3: 16px;
 
-**MANDATORY refs:** tokens: `[path]/tokens.css` (no new values) · Layout: `[path]/Layout.[ext]` (wrap all content) · UI: `[path]/ui/` (import, don't recreate) · Aesthetic: [2-3 words] · Tone: [tone] · Terms: [glossary]
+	/* Radius */
+	--radius-sm: 6px;
+	--radius-md: 12px;
+}
+```
 
-**Content:** [sections, copy direction, media]  **Structure:** [hero → ... → CTA]
+### Minimal Button component example (React)
 
-**Acceptance Criteria:** Shared Layout used · Zero hardcoded values · UI components imported · Tone/terminology match · Responsive 320/768/1280px · [page-specific]
-````
+```tsx
+import './tokens.css';
+type ButtonProps = { children: React.ReactNode; variant?: 'primary' | 'ghost'; className?: string };
+export function Button({ children, variant = 'primary', className = '' }: ButtonProps) {
+	const base = 'px-4 py-2 rounded';
+	const variantCls = variant === 'primary' ? 'bg-[var(--color-primary)] text-white' : 'bg-transparent';
+	return <button className={`${base} ${variantCls} ${className}`}>{children}</button>;
+}
+```
 
 ---
 
@@ -122,10 +86,7 @@ Create `[path]/ui/`: Button, Card, Heading, Text, Link, Section, Container, Grid
 | Anti-pattern | Fix |
 |-------------|-----|
 | Agents pick their own fonts/colors | Foundation creates tokens first |
-| Page-local `styles/global.css` | One shared tokens file, imported once |
 | Copy-pasting `Button` between pages | Import from shared library |
 | Inline `style={{ color: '#...' }}` | CSS class with token variable |
-| Skipping foundation "for a simple site" | Foundation takes 1 task, saves N fixes |
-| Different terminology per page | Terminology glossary in style guide brief |
 | Foundation and page tasks run in parallel | Foundation phase must fully complete first |
 

package/src/orchestrator/skills/project-consistency/TEMPLATES.md

@@ -0,0 +1,39 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+## Prompt Templates — Foundation & Page Tasks
+
+### Foundation Setup — Prompt (copy-paste)
+
+````markdown
+## Foundation Setup — [project description]
+
+**Aesthetic:** [2-3 word direction] — [one sentence]
+
+Create `[path]/tokens.css`: palette (intent-named), fluid typography (clamp()), spacing (4px base), motion, shadows, radius, breakpoints.
+Create `[path]/Layout.[tsx|astro|vue]`: responsive container, site header (nav: [labels]), footer, document head.
+Create `[path]/ui/`: Button, Card, Heading, Text, Link, Section, Container, Grid — tokens only, zero hardcoded values; `variant`/`size`/`className` API.
+
+**Style Guide:** Tone: [formal/casual]. Terminology: [key terms]. Page structure: [hero → ... → CTA].
+
+**Acceptance Criteria:** Zero hardcoded hex/px · Layout responsive at 320/768/1280px · Fluid typography via clamp() · Fonts loaded efficiently
+````
+
+### Page Task — Prompt (copy-paste)
+
+````markdown
+## Build [Page Name] Page — [purpose, audience, primary action]
+
+**MANDATORY refs:** tokens: `[path]/tokens.css` (no new values) · Layout: `[path]/Layout.[ext]` (wrap all content) · UI: `[path]/ui/` (import, don't recreate) · Aesthetic: [2-3 words] · Tone: [tone] · Terms: [glossary]
+
+**Content:** [sections, copy direction, media]  **Structure:** [hero → ... → CTA]
+
+**Acceptance Criteria:** Shared Layout used · Zero hardcoded values · UI components imported · Tone/terminology match · Responsive 320/768/1280px · [page-specific]
+````
+
+### How to use
+
+- Copy the appropriate template into the foundation or page task tracker issue.
+- Replace bracketed placeholders (`[path]`, `[Aesthetic]`) with exact values from the foundation task outputs.
+- Attach paths to tokens, Layout, and UI component library explicitly in the prompt.
+
+Last Updated: 2026-03-31

package/src/orchestrator/skills/react-development/REFERENCE.md

@@ -0,0 +1,7 @@
+> Parent: [SKILL.md](./SKILL.md)
+
+Reference materials for React development guidance.
+
+- See `src/orchestrator/skills/react-development/SKILL.md` for concise rules and quick examples.
+
+Examples, deep-dive topics, and extended patterns (performance, forms, advanced typing) live here when needed.

package/src/orchestrator/skills/react-development/SKILL.md

@@ -1,71 +1,79 @@
 ---
 name: react-development
-description: "React development standards for functional components, hooks, TypeScript integration, state management, styling, and testing patterns. Use when creating or modifying React components, custom hooks, or component tests."
+description: "Enforces naming conventions, prop typing patterns, file structure, and test coverage standards. Use when creating or modifying React components, custom hooks, or component tests. Trigger terms: React app, .tsx files, testing library, custom hooks, functional components"
 ---
 
 # React Development Standards
 
-Modern React patterns — https://react.dev.
+<!-- Concrete actions moved into description and workflows; trigger terms are in frontmatter -->
 
-## Architecture & Components
+## New Component Workflow
 
-- Functional components + hooks; composition over inheritance.
-- Feature/domain folders; separate presentational and container components.
-- PascalCase names; single responsibility; destructure props; never mutate props/state.
-- `<>...</>` to avoid extra DOM nodes; props validated via TypeScript.
+1. **Create file** — `ComponentName.tsx` in the feature folder; co-locate `ComponentName.module.scss` and `ComponentName.test.tsx`
+2. **Define interface** — export `ComponentNameProps` with TypeScript; destructure in function signature
+3. **Implement** — functional component with hooks; use CSS Modules for styling
+4. **Test** — RTL behavioral tests; cover render, interaction, edge cases, accessibility
+5. **Verify** — lint + type-check + test pass; visually confirm in browser if UI
 
-## TypeScript
+## Architecture & Components (concise)
 
-- Interfaces for props, state, event handlers, refs, and API responses.
-- Generic components where appropriate; union types for variants.
-- Built-ins: `React.FC`, `React.ComponentProps`, etc.
-- Strict mode in `tsconfig.json`; shared types in `interfaces/`.
+- Functional components with hooks. Follow domain/feature folder structure and co-locate tests/styles with components.
+- PascalCase names; destructure props; use TypeScript interfaces for props.
 
-## State & Hooks
+```tsx
+interface UserCardProps { name: string; role: string }
+export function UserCard({ name, role }: UserCardProps) {
+  return (
+    <div data-testid="user-card">
+      <h3>{name}</h3>
+      <span>{role}</span>
+    </div>
+  );
+}
+```
 
-| Concern | Tool |
-|---------|------|
-| Local state | `useState` |
-| Complex state | `useReducer` |
-| Cross-tree state | `useContext` |
-| Server state | React Query |
-| DOM / mutable ref | `useRef` |
-| Perf optimization | `useMemo` / `useCallback` |
+## TypeScript
 
-- `useEffect`: proper deps, cleanup to prevent leaks.
-- Hooks only at top level; extract reusable logic to custom hooks.
+- Use interfaces for props and shared types; keep strict mode enabled in `tsconfig.json`. See [REFERENCE.md](REFERENCE.md) for detailed TypeScript patterns.
 
 ## Styling
 
 - **CSS Modules** (`.module.scss`) co-located with components.
 - Sass for advanced features; variables/mixins from shared libraries.
-- Mobile-first responsive; CSS custom properties for theming.
+- CSS custom properties for theming.
 
-## Performance
+<!-- Performance guidance trimmed; follow project-specific conventions and benchmark when needed. -->
 
-- Stable `key` props; `React.memo` where warranted.
-- Code-split with `React.lazy` + `Suspense`; dynamic imports.
-- Avoid anonymous functions in render; virtual scrolling for large lists.
-- `ErrorBoundary` for graceful degradation.
+## Testing
 
-## Data Fetching
+- React Testing Library (behavior, not implementation); Jest runner.
+- Co-locate tests next to components; mock external deps and API calls.
+- Test accessibility and keyboard navigation; verify component public surface via unit tests.
 
-- Libraries: React Query, SWR, or Apollo Client.
-- Always handle loading/error/success; cancel on unmount; optimistic updates.
+```tsx
+import { render, screen } from '@testing-library/react';
+import { UserCard } from './UserCard';
 
-## Forms
+test('renders user info', () => {
+  render(<UserCard name="Alice" role="Admin" />);
+  expect(screen.getByText('Alice')).toBeInTheDocument();
+  expect(screen.getByTestId('user-card')).toBeInTheDocument();
+});
+```
 
-- Controlled components; React Hook Form + Zod for validation.
-- Accessibility: labels, ARIA attributes; debounced validation.
+## Verification commands + error recovery
 
-## Testing
+Run these as part of your PR validation pipeline or locally:
 
-- React Testing Library (behavior, not implementation); Jest runner.
-- Co-locate tests in `__tests__`; mock external deps and API calls.
-- Test accessibility and keyboard navigation.
-- **CRITICAL**: Never mix static imports and `require()` for lazy-loaded libs in tests — use `jest.requireMock()` / `jest.requireActual()`.
+```bash
+pnpm lint        # fixable issues: pnpm lint --fix
+pnpm typecheck   # run `pnpm tsc --noEmit` if alias not present
+pnpm test        # rerun failing tests with `pnpm test -- -t <name>`
+pnpm build       # ensure production build succeeds
+```
+
+If `lint` fails: run `pnpm lint --fix` and re-run. If `typecheck` fails: inspect reported files; add missing types. If tests fail: run with `--runInBand` to collect stack traces and reproduce locally.
 
 ## Security
 
-- Sanitize inputs (XSS); validate/escape before rendering.
-- HTTPS for external APIs; no sensitive data in localStorage/sessionStorage; CSP headers.
+- Follow project conventions for input sanitization, secret handling, and CSP. See **api-patterns** for validation patterns.