opencastle 0.32.5 → 0.32.7

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

@@ -5,29 +5,27 @@ description: "Enforce cross-agent consistency in multi-page/multi-component proj
 
 # Project Consistency
 
-When multiple agents build different pages or sections in parallel, each makes independent decisions about colors, fonts, component APIs, content tone, and page structure. Without coordination, the result looks like it was built by five different teams — because it was.
+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.**
 
-**The fix is architectural, not aspirational.** Consistency cannot be "hoped for" after parallel work is done. It must be engineered as shared inputs before parallel work begins.
-
-## The Foundation-First Principle
+## Foundation-First Principle
 
 ```
-❌ Wrong:  [agent A] ─┐                         → inconsistent output
-           [agent B] ─┤→ build pages in parallel → inconsistent output
-           [agent C] ─┘                         → inconsistent output
+❌ Wrong:  [A] ─┐                    → inconsistent output
+           [B] ─┤→ build in parallel → inconsistent output
+           [C] ─┘                    → inconsistent output
 
-✅ Right:  [foundation task] → shared artifacts → [agent A] ─┐
-                                                  [agent B] ─┤→ consistent output
-                                                  [agent C] ─┘
+✅ Right:  [foundation] → artifacts → [A] ─┐
+                                      [B] ─┤→ consistent output
+                                      [C] ─┘
 ```
 
-**Phase 1 (sequential):** One task creates all shared artifacts — design tokens, layout component, UI library, style guide.  
-**Phase 2 (parallel):** Every page task imports from Phase 1 output. No new values, no recreated components.
+**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 without a contract | Artifact that enforces it |
-|-----------|-------------------------------|--------------------------|
+| 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 |
@@ -37,314 +35,97 @@ When multiple agents build different pages or sections in parallel, each makes i
 
 ## Foundation Phase Artifacts
 
-A foundation task must produce four things. All subsequent tasks depend on its completion.
-
-### a. Design Tokens File
-
-A single CSS custom properties file — the system's single source of truth. No agent may introduce a color, size, or timing value outside this file.
-
-**Path:** `src/styles/tokens.css` (or equivalent for your framework)
-
-```css
-/* Palette — name for intent, not appearance */
-:root {
-  --color-ink:        #1a1614;          /* primary text */
-  --color-paper:      #f5f0e8;          /* page background */
-  --color-accent:     #c8e630;          /* the memorable one — use sparingly */
-  --color-muted:      #9b9083;          /* secondary text, labels */
-  --color-surface:    #eae3d8;          /* card backgrounds, elevated surfaces */
-  --color-border:     rgba(26,22,20,.08);
-
-  /* Typography scale — fluid with clamp(), modular ratio 1.25 */
-  --text-xs:   clamp(0.75rem,  0.72rem + 0.15vw, 0.875rem);
-  --text-sm:   clamp(0.875rem, 0.83rem  + 0.22vw, 1rem);
-  --text-base: clamp(1rem,     0.95rem  + 0.25vw, 1.125rem);
-  --text-lg:   clamp(1.25rem,  1.1rem   + 0.75vw, 1.563rem);
-  --text-xl:   clamp(1.563rem, 1.35rem  + 1.06vw, 2rem);
-  --text-2xl:  clamp(1.953rem, 1.6rem   + 1.77vw, 2.75rem);
-  --text-hero: clamp(2.441rem, 1.8rem   + 3.2vw,  4.5rem);
-
-  /* Font families */
-  --font-display: 'Playfair Display', 'Georgia', serif;
-  --font-body:    'Source Serif 4', 'Georgia', serif;
-  --font-mono:    'JetBrains Mono', 'Courier New', monospace;
-
-  /* Spacing — 4px base, geometric progression */
-  --space-1:  0.25rem;   --space-2:  0.5rem;
-  --space-3:  0.75rem;   --space-4:  1rem;
-  --space-6:  1.5rem;    --space-8:  2rem;
-  --space-12: 3rem;      --space-16: 4rem;
-  --space-24: 6rem;      --space-32: 8rem;
-
-  /* Borders & radius */
-  --radius-sm: 4px;  --radius-md: 8px;  --radius-lg: 16px;  --radius-full: 9999px;
-  --border-width: 1px;  --border-width-thick: 2px;
-
-  /* Elevation */
-  --shadow-sm: 0 1px 4px rgba(26,22,20,.06);
-  --shadow-md: 0 4px 16px rgba(26,22,20,.08);
-  --shadow-lg: 0 12px 48px rgba(26,22,20,.12);
-
-  /* Motion — intentional easing, not browser defaults */
-  --ease-out-expo:    cubic-bezier(0.16, 1, 0.3, 1);
-  --ease-in-out-back: cubic-bezier(0.68, -0.6, 0.32, 1.6);
-  --duration-fast:    150ms;
-  --duration-normal:  300ms;
-  --duration-slow:    600ms;
-
-  /* Layout */
-  --container-sm:  640px;
-  --container-md:  768px;
-  --container-lg:  1024px;
-  --container-xl:  1280px;
-  --container-pad: var(--space-6);
-}
-```
-
-> **Rule:** If a value isn't a token, it doesn't belong in a component stylesheet. Period.
-
-### b. Shared Layout Component
-
-Wraps every page. Provides the header, navigation, footer, and responsive container. Every page agent imports this — never creates its own.
-
-**Path:** `src/components/Layout.tsx` (React) or `src/layouts/Layout.astro` (Astro)
-
-```tsx
-// Layout.tsx — simplified contract; foundation task provides the full implementation
-interface LayoutProps {
-  title: string;
-  description?: string;
-  children: React.ReactNode;
-}
-
-export function Layout({ title, description, children }: LayoutProps) {
-  return (
-    <>
-      <Head title={title} description={description} />
-      <div className="site">
-        <SiteHeader />           {/* navigation — from tokens and style guide */}
-        <main className="site__main">{children}</main>
-        <SiteFooter />
-      </div>
-    </>
-  );
-}
-```
-
-The layout must handle:
-- Responsive container (`max-width: var(--container-xl)`, centered, padded)
-- Site header with navigation (labels defined in style guide brief)
-- Site footer
-- Consistent page padding using spacing tokens
-- Document head (meta tags, fonts, canonical URL)
-
-### c. UI Component Library
-
-Shared primitives that every page agent imports. Each component uses only design tokens — zero hardcoded values.
-
-**Path:** `src/components/ui/`
+A foundation task must produce four artifacts. All phase-2 tasks depend on its completion.
 
-Minimum required components:
-
-| Component | Purpose | Key variants |
-|-----------|---------|--------------|
-| `Button` | Primary CTA and actions | `primary`, `secondary`, `ghost` |
-| `Card` | Content containers | `default`, `bordered`, `elevated` |
-| `Heading` | h1–h6 with token-based sizing | via `level` prop |
-| `Text` | Body copy with consistent sizing | `sm`, `base`, `lg` |
-| `Link` | Anchor with consistent hover treatment | `default`, `subtle` |
-| `Section` | Vertical spacing wrapper | `sm`, `md`, `lg`, `xl` |
-| `Container` | Responsive width constraint | `sm`, `md`, `lg`, `xl` |
-| `Grid` | Consistent column layout | via `cols` prop |
-
-Component API rules (defined once, followed by all):
-- Props use camelCase
-- Variant selection via `variant` prop (string union)
-- Size selection via `size` prop (string union)
-- All components accept `className` for one-off overrides
-- No inline `style` props in library components
-
-### d. Style Guide Brief
-
-Defined inline in the foundation task prompt (not a separate file). Page task prompts must quote it verbatim.
-
-Required fields:
-- **Aesthetic direction:** 2–3 words (`warm editorial`, `cold brutalist`, `soft playful`)
-- **Typography pairing:** display font + body font + mono (if used)
-- **Content tone:** formal/casual, active/passive, sentence length preference
-- **Navigation labels:** exact labels for every nav link (prevents terminology drift)
-- **Page structure pattern:** the default sequence (e.g., `hero → intro → features → CTA → footer`)
-- **Terminology glossary:** any project-specific terms that could be said multiple ways (pick one)
+| 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 |
 
 ---
 
 ## Consistency Rules for Page Agents
 
-Every agent building a page in a multi-agent convoy MUST follow these rules. Non-negotiable.
-
-### Visual
-- Import tokens from the tokens file. **Never introduce a new color value, font size, or spacing value.**
-- If a value you need doesn't exist as a token, stop and flag it — don't invent an inline value and move on.
-- Use CSS custom properties exclusively. No raw hex, no raw `px` values in stylesheets.
-
-### Code
-- Import `Layout` from the shared layout path. Do not create a page-local layout wrapper.
-- Import `Button`, `Card`, `Heading`, etc. from the UI library path. Do not recreate them.
-- Follow the naming conventions: PascalCase components, camelCase props, kebab-case CSS classes.
-- Co-locate component files (component, styles, tests) — do not scatter across `pages/`, `styles/`, and `components/`.
+Every page agent in a multi-agent convoy MUST follow all rules below.
 
-### Content
-- Match the tone from the style guide brief exactly. If the brief says "conversational and direct," don't write formal passive-voice copy.
-- Use the terminology glossary. If the brief says "projects" (not "work" or "portfolio"), use "projects" everywhere.
-- Follow the heading hierarchy pattern. If H1 is the page title and H2 introduces sections, don't invent new patterns.
-
-### Structural
-- Every page uses the shared Layout component — no exceptions.
-- Follow the page structure pattern from the style guide brief (`hero → content → CTA`, etc.).
-- Navigation labels must match the style guide brief exactly — no paraphrasing.
-- Responsive breakpoints come from the tokens file (`--container-sm/md/lg/xl`). Define no new breakpoints.
+| 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. |
 
 ---
 
-## Convoy Integration Pattern
+## Convoy Integration
 
 ```
 Phase 1: foundation-setup  (1 task, blocks Phase 2)
 ├── Agent:  UI-UX Expert or Developer
-├── Creates: tokens.css, Layout component, UI component library
+├── Creates: tokens.css, Layout, UI component library
 ├── Defines: style guide brief (aesthetic, tone, nav labels, terminology)
-└── Output:  all paths documented for Phase 2 task prompts
+└── 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 task prompt contains the 5 mandatory references below]
+├── home-page · about-page · projects-page · contact-page · ...
+└── [every prompt contains the 5 mandatory references below]
 ```
 
 ### 5 Mandatory References in Every Page Task Prompt
 
 ```
-1. Design tokens:    `[path to tokens.css]` — use ONLY these tokens. No new values.
-2. Layout:           `[path to Layout]` — wrap all page content in this component.
-3. UI components:    `[path to 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/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]
 ```
 
-These are **inputs** to the task, not suggestions.
-
 ---
 
 ## Prompt Template: Foundation Task
 
-Copy and fill in. This prompt goes to a single agent before parallel work begins.
-
 ````markdown
-## Foundation Setup
-
-Create the design system foundation for [project description].
-
-### Aesthetic Direction
-[2-3 word aesthetic] — [one sentence: what this feels like and who it's for]
-
-### Design Tokens
-Create `[path]/tokens.css` with CSS custom properties for:
-- Colors: name for intent (ink, paper, accent, muted, surface, border)
-- Typography: [display font] + [body font], fluid clamp() scale (xs → hero)
-- Spacing: 4px base, geometric progression (space-1 through space-32)
-- Motion: custom easing curves + duration tokens (fast/normal/slow)
-- Shadows (sm/md/lg), border radius (sm/md/lg/full), breakpoints (sm/md/lg/xl)
-
-### Shared Layout
-Create `[path]/Layout.[tsx|astro|vue]` with:
-- Responsive container (max-width centered, padded with --container-pad)
-- Site header with navigation: [list nav labels exactly]
-- Site footer with [footer content]
-- Document head (title, description, fonts)
-
-### UI Component Library
-Create these components in `[path]/ui/`:
-Button (primary/secondary/ghost), Card (default/bordered/elevated),
-Heading (h1–h6 via level prop), Text (sm/base/lg), Link,
-Section (vertical spacer), Container (width constraint), Grid
-
-Rules: all components use only token variables — zero hardcoded values.
-Consistent prop API: variant, size, className on every component.
-
-### Style Guide Brief
-- Tone: [formal/casual, active/passive, sentence length]
-- Terminology: [key terms — e.g., "projects" not "work", "clients" not "customers"]
-- Page structure: [hero → intro → features → CTA]
-
-### Acceptance Criteria
-- [ ] All design values use CSS custom properties — zero hardcoded hex/px in components
-- [ ] Layout renders correctly at 320px (mobile), 768px (tablet), 1280px (desktop)
-- [ ] All UI components import tokens from the tokens file — no new values
-- [ ] Typography uses clamp() for fluid sizing throughout
-- [ ] Fonts are loaded efficiently (subset, display=swap)
-- [ ] At least one distinctive design detail beyond generic defaults
-````
+## Foundation Setup — [project description]
 
----
+**Aesthetic:** [2-3 word direction] — [one sentence]
 
-## Prompt Template: Page Task
+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.
 
-Copy and fill in for each parallel page task.
+**Style Guide:** Tone: [formal/casual]. Terminology: [key terms]. Page structure: [hero → ... → CTA].
 
-````markdown
-## Build [Page Name] Page
-
-[One paragraph: page purpose, target audience, primary user action]
-
-### Foundation References (MANDATORY — do not deviate)
-- **Design tokens:** `[path]/tokens.css` — use ONLY these variables. No new color/font/spacing values.
-- **Layout component:** `[path]/Layout.[tsx|astro|vue]` — wrap all page content in this.
-- **UI components:** `[path]/ui/` — use Button, Card, Heading, Section, Container. Do not recreate them.
-- **Aesthetic:** [2-3 word direction]
-- **Tone:** [tone from style guide brief]
-- **Terminology:** [key terms from style guide brief]
-
-### Page Content
-[Specific sections, copy direction, media requirements]
-
-### Page Structure
-Follow the established pattern: [hero → intro → features → CTA] (from foundation brief)
-
-### Acceptance Criteria
-- [ ] Page uses the shared Layout component
-- [ ] All styling uses design tokens — zero hardcoded values
-- [ ] Shared UI components imported and used (not recreated)
-- [ ] Content tone and terminology match the style guide brief
-- [ ] Responsive at 320px, 768px, 1280px
-- [ ] [page-specific criteria]
+**Acceptance Criteria:** Zero hardcoded hex/px · Layout responsive at 320/768/1280px · Fluid typography via clamp() · Fonts loaded efficiently
 ````
 
 ---
 
-## Anti-Patterns
+## Prompt Template: Page Task
+
+````markdown
+## Build [Page Name] Page — [purpose, audience, primary action]
 
-These will produce an inconsistent result regardless of individual page quality.
+**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]
 
-| Anti-pattern | Consequence | Fix |
-|-------------|-------------|-----|
-| Each agent picks fonts/colors | Every page feels like a different site | Foundation task creates tokens first |
-| Page-local `styles/global.css` files | Conflicting resets and overrides | One shared tokens file, imported once |
-| Copy-pasting `Button` between pages | API drift, visual divergence | Import from shared library |
-| Inline `style={{ color: '#3b4f' }}` | Bypasses the token contract entirely | CSS class with token variable |
-| Skipping foundation "for a simple site" | Still inconsistent — just smaller | Foundation takes 1 task, saves N fixes |
-| Different terminology per page | Confuses users ("projects" vs "portfolio") | Terminology glossary in style guide brief |
-| Foundation and page tasks run in parallel | Page tasks start before artifacts exist | Foundation phase must fully complete first |
+**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]
+````
 
 ---
 
-## When to Load This Skill
+## Anti-Patterns
 
-Load this skill when:
-- A convoy plan includes 2+ pages or UI sections built by different agents
-- The `generate-convoy` prompt describes a multi-page application
-- A decomposition produces parallel page-building tasks
-- A Developer or UI-UX Expert agent is working on a page within a multi-agent build
+| 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 |
 
-The **decomposition** skill should reference this skill in multi-page task plans. The **generate-convoy** prompt template should embed the foundation-first pattern.

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

@@ -3,117 +3,69 @@ 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."
 ---
 
-<!-- ⚠️ This file is managed by OpenCastle. Edits will be overwritten on update. Customize in the .opencastle/ directory instead. -->
-
 # React Development Standards
 
-Modern React patterns following the official React documentation at https://react.dev.
-
-## Architecture
-
-- Functional components with hooks as primary pattern.
-- Component composition over inheritance.
-- Organize by feature/domain, not by type.
-- Separate presentational and container components.
-- Custom hooks for reusable stateful logic.
+Modern React patterns — https://react.dev.
 
-## TypeScript Integration
+## Architecture & Components
 
-- Interfaces for props, state, and component definitions.
-- Proper types for API responses, event handlers, and refs.
-- Generic components where appropriate.
-- Strict mode in `tsconfig.json`.
-- Leverage built-in types (`React.FC`, `React.ComponentProps`, etc.).
-- Union types for component variants and states.
-- Shared types in `interfaces/` folder of appropriate project.
+- 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.
 
-## Component Design
+## TypeScript
 
-- Single responsibility principle.
-- Descriptive, consistent PascalCase naming.
-- Props validation via TypeScript.
-- Small, focused, testable, reusable.
-- Use `<>...</>` or `React.Fragment` to avoid extra DOM nodes.
-- Never mutate props or state directly.
-- Destructure props in function signature.
+- 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/`.
 
-## State Management
+## State & Hooks
 
-- `useState` for local state.
-- `useReducer` for complex state logic.
-- `useContext` for cross-tree state sharing.
-- React Query for server state.
+| Concern | Tool |
+|---------|------|
+| Local state | `useState` |
+| Complex state | `useReducer` |
+| Cross-tree state | `useContext` |
+| Server state | React Query |
+| DOM / mutable ref | `useRef` |
+| Perf optimization | `useMemo` / `useCallback` |
 
-## Hooks and Effects
-
-- `useEffect` with proper dependency arrays.
-- Cleanup functions in effects to prevent memory leaks.
-- `useMemo`/`useCallback` for performance optimization when needed.
-- Custom hooks for reusable logic.
-- Rules of hooks: only call at top level.
-- `useRef` for DOM access and mutable values.
+- `useEffect`: proper deps, cleanup to prevent leaks.
+- Hooks only at top level; extract reusable logic to custom hooks.
 
 ## Styling
 
-- **CSS Modules** with `.module.scss` files.
-- **Sass** for advanced features.
-- Scoped styles to avoid global conflicts.
-- Responsive design with mobile-first approach.
-- CSS custom properties for theming.
-- Consistent spacing, typography, color systems.
-- Sass variables and mixins from shared libraries.
-- Co-locate styles with components.
+- **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.
 
 ## Performance
 
-- Stable `key` props in lists.
-- `React.memo` when appropriate.
-- Code splitting with `React.lazy` and `Suspense`.
-- Tree shaking and dynamic imports.
-- Virtual scrolling for large lists.
-- Profile with React DevTools.
-- Avoid anonymous functions in render.
-- `ErrorBoundary` for graceful error handling.
+- 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.
 
 ## Data Fetching
 
-- Libraries: React Query, SWR, Apollo Client.
-- Loading, error, and success states.
-- Handle race conditions and request cancellation.
-- Optimistic updates.
-- Caching strategies.
-- Offline/network error handling.
-
-## Error Handling
-
-- Error Boundaries for component-level errors.
-- Proper error states in data fetching.
-- Fallback UI for error scenarios.
-- Meaningful error messages to users.
+- Libraries: React Query, SWR, or Apollo Client.
+- Always handle loading/error/success; cancel on unmount; optimistic updates.
 
 ## Forms
 
-- Controlled components.
-- React Hook Form + Zod for validation.
-- Form submission and error states.
-- Accessibility: labels, ARIA attributes.
-- Debounced validation.
+- Controlled components; React Hook Form + Zod for validation.
+- Accessibility: labels, ARIA attributes; debounced validation.
 
 ## Testing
 
-- React Testing Library: test behavior, not implementation.
-- Jest as test runner.
-- Mock external dependencies and API calls.
+- React Testing Library (behavior, not implementation); Jest runner.
+- Co-locate tests in `__tests__`; mock external deps and API calls.
 - Test accessibility and keyboard navigation.
-- Co-locate tests in `__tests__` subdirectory.
-- **CRITICAL**: Never mix static imports and `require()` for lazy-loaded libraries in tests.
-- Use `jest.requireMock()` instead of `require()` in test functions.
-- Use `jest.requireActual()` or equivalent in mock setup.
+- **CRITICAL**: Never mix static imports and `require()` for lazy-loaded libs in tests — use `jest.requireMock()` / `jest.requireActual()`.
 
 ## Security
 
-- Sanitize user inputs (XSS prevention).
-- Validate/escape data before rendering.
-- HTTPS for external APIs.
-- Avoid storing sensitive data in localStorage/sessionStorage.
-- CSP headers.
+- Sanitize inputs (XSS); validate/escape before rendering.
+- HTTPS for external APIs; no sensitive data in localStorage/sessionStorage; CSP headers.