@jetrabbits/agentic 0.0.1

package/areas/software/frontend/rules/performance.md

@@ -0,0 +1,23 @@
+# Rule: Performance Budget
+
+**Priority**: P1 — Must be resolved before release; tracked per PR.
+
+## Core Web Vitals Targets (Production)
+
+| Metric | Target | Hard Limit |
+|:---|:---|:---|
+| LCP (Largest Contentful Paint) | < 2.0s | < 2.5s |
+| INP (Interaction to Next Paint) | < 100ms | < 200ms |
+| CLS (Cumulative Layout Shift) | < 0.05 | < 0.1 |
+
+## Bundle Constraints
+
+1. **Initial JS bundle**: ≤ 200 KB gzipped for the critical path.
+2. **Route-level chunks**: Every route must be lazy-loaded via `React.lazy()` + `Suspense`.
+3. **Third-party libraries**: Any dependency > 50 KB gzipped must be explicitly approved in `bundle-policy.md`.
+4. **No synchronous localStorage access** in the render path.
+5. Images must use modern formats (WebP/AVIF) and include `width`/`height` attributes.
+
+## Enforcement
+
+Bundle size is tracked via `bundlesize` in CI. PRs that increase the initial bundle by > 5 KB trigger a mandatory `/bundle-analyze` workflow run.

package/areas/software/frontend/rules/quality.md

@@ -0,0 +1,12 @@
+# Rule: Code Quality
+
+**Priority**: P1 — Violations block merge via automated lint gates.
+
+## Constraints
+
+1. **TypeScript strict mode** is non-negotiable (`strict: true` in `tsconfig.json`). No `any` without an explicit `// eslint-disable` comment explaining why.
+2. **No hardcoded user-facing strings**: All copy must use i18n keys (`t('key.path')`).
+3. **No direct DOM manipulation**: Never use `document.getElementById` or `querySelector` from within React components. Use `useRef`.
+4. **State immutability**: Never mutate state objects directly.
+5. **Test coverage**: New components must ship with ≥ 1 rendering test and ≥ 1 interaction test.
+6. **No `console.log` in committed code**: Use the project's structured logger (`lib/logger.ts`).

package/areas/software/frontend/skills/a11y-audit/SKILL.md

@@ -0,0 +1,61 @@
+# Skill: Accessibility Audit & Remediation
+
+## When to load
+
+When building interactive components, reviewing a PR for accessibility, or fixing a11y lint errors.
+
+## Most Common Violations & Fixes
+
+### 1. Icon-only button without label
+```tsx
+// ❌
+<button onClick={onClose}><CloseIcon /></button>
+
+// ✅
+<button onClick={onClose} aria-label="Close dialog">
+  <CloseIcon aria-hidden="true" />
+</button>
+```
+
+### 2. Input without label
+```tsx
+// ❌
+<input type="email" placeholder="Email address" />
+
+// ✅
+<label htmlFor="email">Email address</label>
+<input id="email" type="email" placeholder="jane@example.com" />
+```
+
+### 3. Modal focus management
+```tsx
+const Modal = ({ isOpen, onClose, children }: ModalProps) => {
+  const firstFocusableRef = useRef<HTMLButtonElement>(null);
+  useEffect(() => {
+    if (isOpen) firstFocusableRef.current?.focus();
+  }, [isOpen]);
+
+  return isOpen ? (
+    <div role="dialog" aria-modal="true" aria-labelledby="dialog-title">
+      {children}
+      <button ref={firstFocusableRef} onClick={onClose}>Close</button>
+    </div>
+  ) : null;
+};
+```
+
+### 4. Dynamic content announcements
+```tsx
+const StatusMessage = ({ message }: { message: string }) => (
+  <div aria-live="polite" aria-atomic="true" className="sr-only">
+    {message}
+  </div>
+);
+```
+
+## Keyboard Navigation Checklist
+
+- [ ] Tab order follows visual reading order (no `tabindex > 0`)
+- [ ] Custom dropdown: Arrow keys navigate, Escape closes, Enter selects
+- [ ] Modals: Focus trapped inside; Escape closes; focus returns to trigger
+- [ ] All hover interactions have keyboard equivalent

package/areas/software/frontend/skills/api-integration/SKILL.md

@@ -0,0 +1,58 @@
+# Skill: API Integration Patterns
+
+## When to load
+
+When connecting a component to a REST API, handling loading/error states, or implementing optimistic updates.
+
+## Standard Fetch Layer
+
+```ts
+const apiClient = {
+  get: async <T>(path: string, options?: RequestInit): Promise<T> => {
+    const res = await fetch(`${import.meta.env.VITE_API_URL}${path}`, {
+      ...options,
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${getToken()}`,
+        ...options?.headers,
+      },
+    });
+    if (!res.ok) throw new ApiError(res.status, await res.json());
+    return res.json();
+  },
+};
+```
+
+## Loading & Error States
+
+```tsx
+const UserList = () => {
+  const { data, isLoading, isError, error } = useQuery({
+    queryKey: ['users'],
+    queryFn: () => apiClient.get<User[]>('/users'),
+  });
+
+  if (isLoading) return <UserListSkeleton />;
+  if (isError) return <ErrorMessage message={error.message} />;
+
+  return <ul>{data.map(user => <UserItem key={user.id} user={user} />)}</ul>;
+};
+```
+
+## Optimistic Updates
+
+```tsx
+const mutation = useMutation({
+  mutationFn: (id: string) => apiClient.delete(`/todos/${id}`),
+  onMutate: async (id) => {
+    await queryClient.cancelQueries({ queryKey: ['todos'] });
+    const previous = queryClient.getQueryData<Todo[]>(['todos']);
+    queryClient.setQueryData<Todo[]>(['todos'], old => old?.filter(t => t.id !== id));
+    return { previous };
+  },
+  onError: (_err, _id, context) => {
+    queryClient.setQueryData(['todos'], context?.previous);
+  },
+  onSettled: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
+});
+```

package/areas/software/frontend/skills/component-design/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: component-design
+type: skill
+description: Design reusable React/Vue components with correct patterns, typed APIs, state handling, and accessibility.
+related-rules:
+  - architecture.md
+  - accessibility.md
+allowed-tools: Read, Write, Edit, Bash
+---
+
+# Component Design Patterns Skill
+
+> **Expertise:** Compound components, controlled/uncontrolled, render props, component API design, accessibility requirements.
+
+## Pattern Selection Guide
+
+```
+Multiple visual zones in one component?         → Slot / Children Props
+Coordinated subcomponents sharing state?        → Compound Components
+Works with react-hook-form / external control?  → Controlled/Uncontrolled Hybrid
+Self-contained widget with internal state?      → Uncontrolled with defaults
+Highly customizable rendering?                  → Render Props / Headless
+```
+
+## Pattern 1: Compound Components
+
+Use when: a component has multiple coordinated parts sharing implicit state.
+
+```tsx
+// Context shared between sub-components
+const MenuContext = createContext<{ open: boolean; toggle: () => void } | null>(null);
+
+const Menu = ({ children }: { children: React.ReactNode }) => {
+  const [open, setOpen] = useState(false);
+  return (
+    <MenuContext.Provider value={{ open, toggle: () => setOpen(o => !o) }}>
+      <div role="menu" aria-expanded={open}>{children}</div>
+    </MenuContext.Provider>
+  );
+};
+
+Menu.Trigger = function MenuTrigger({ children }: { children: React.ReactNode }) {
+  const ctx = useContext(MenuContext)!;
+  return (
+    <button onClick={ctx.toggle} aria-haspopup="true" aria-expanded={ctx.open}>
+      {children}
+    </button>
+  );
+};
+
+Menu.Items = function MenuItems({ children }: { children: React.ReactNode }) {
+  const { open } = useContext(MenuContext)!;
+  if (!open) return null;
+  return <ul role="listbox">{children}</ul>;
+};
+
+// Usage — caller controls structure
+<Menu>
+  <Menu.Trigger>Options</Menu.Trigger>
+  <Menu.Items>
+    <li role="option">Edit</li>
+    <li role="option">Delete</li>
+  </Menu.Items>
+</Menu>
+```
+
+## Pattern 2: Controlled / Uncontrolled Hybrid
+
+Use when: component works standalone OR integrates with external form libraries.
+
+```tsx
+interface InputProps {
+  value?: string;           // controlled mode if provided
+  defaultValue?: string;    // uncontrolled mode
+  onChange?: (value: string) => void;
+  label: string;
+  error?: string;
+}
+
+const Input = ({ value, onChange, defaultValue, label, error }: InputProps) => {
+  const [internal, setInternal] = useState(defaultValue ?? '');
+  const isControlled = value !== undefined;
+  const current = isControlled ? value : internal;
+
+  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    if (!isControlled) setInternal(e.target.value);
+    onChange?.(e.target.value);
+  };
+
+  const id = useId();   // stable ID for label association
+  return (
+    <div>
+      <label htmlFor={id}>{label}</label>
+      <input id={id} value={current} onChange={handleChange}
+             aria-invalid={!!error} aria-describedby={error ? `${id}-error` : undefined} />
+      {error && <span id={`${id}-error`} role="alert">{error}</span>}
+    </div>
+  );
+};
+```
+
+## Component States — Always Implement All
+
+Every component that fetches or receives async data must handle all states:
+
+```tsx
+interface DataComponentProps {
+  userId: string;
+}
+
+const UserCard = ({ userId }: DataComponentProps) => {
+  const { data, isLoading, isError, error } = useUser(userId);
+
+  // 1. Loading state — skeleton or spinner
+  if (isLoading) return <UserCardSkeleton />;
+
+  // 2. Error state — meaningful message, not blank
+  if (isError) return (
+    <div role="alert">
+      <p>Failed to load user data.</p>
+      <button onClick={() => refetch()}>Try again</button>
+    </div>
+  );
+
+  // 3. Empty state — explicit, not silent blank area
+  if (!data) return <p>No user found.</p>;
+
+  // 4. Success state — the happy path
+  return <div>{data.name}</div>;
+};
+```
+
+## Props API Design Rules
+
+```tsx
+// ✅ Good: explicit, typed, small surface area
+interface ButtonProps {
+  variant: 'primary' | 'secondary' | 'ghost';
+  size?: 'sm' | 'md' | 'lg';
+  isLoading?: boolean;
+  onClick?: () => void;
+  children: React.ReactNode;
+  'aria-label'?: string;  // Allow a11y override
+}
+
+// ❌ Bad: too many booleans (boolean explosion)
+interface ButtonProps {
+  isPrimary?: boolean;
+  isSecondary?: boolean;
+  isSmall?: boolean;
+  isLarge?: boolean;
+  // Can set isPrimary + isSecondary simultaneously — ambiguous
+}
+
+// ❌ Bad: style overrides passed as strings
+interface ButtonProps {
+  className?: string;   // Breaks component encapsulation
+  style?: CSSProperties; // Creates leaky styling contract
+}
+```
+
+## Accessibility Requirements Per Component
+
+| Component | Required ARIA | Keyboard | Notes |
+|---|---|---|---|
+| Dialog/Modal | `role="dialog"`, `aria-modal`, `aria-labelledby` | Trap focus; Escape closes | Focus returns to trigger on close |
+| Dropdown/Select | `role="listbox"`, `aria-expanded` | Arrow keys navigate; Enter selects | Announce selection |
+| Toggle/Switch | `role="switch"`, `aria-checked` | Space toggles | |
+| Alert/Toast | `role="alert"` or `aria-live="polite"` | — | Screen reader announces immediately |
+| Tab panel | `role="tablist"`, `role="tab"`, `role="tabpanel"` | Arrow keys between tabs | |
+| Form field | `<label>` with `htmlFor` | — | Never skip label |

package/areas/software/frontend/skills/css-architecture/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: css-architecture
+type: skill
+description: Structure CSS/Tailwind for maintainability — tokens, BEM naming, specificity control, responsive patterns.
+related-rules:
+  - architecture.md
+  - accessibility.md
+allowed-tools: Read, Write, Edit, Bash
+---
+
+# CSS Architecture Skill
+
+> **Expertise:** Design tokens, BEM, Tailwind utility classes, CSS custom properties, responsive design, dark mode.
+
+## Design Tokens — Never Hardcode Values
+
+```css
+/* tokens.css — single source of truth */
+:root {
+  /* Color — semantic names, not visual */
+  --color-primary: #3b82f6;
+  --color-primary-hover: #2563eb;
+  --color-surface: #ffffff;
+  --color-surface-raised: #f8fafc;
+  --color-text-primary: #0f172a;
+  --color-text-muted: #64748b;
+  --color-error: #ef4444;
+  --color-success: #22c55e;
+
+  /* Spacing — 4px base unit */
+  --space-1: 0.25rem;   /* 4px */
+  --space-2: 0.5rem;    /* 8px */
+  --space-4: 1rem;      /* 16px */
+  --space-6: 1.5rem;    /* 24px */
+  --space-8: 2rem;      /* 32px */
+
+  /* Typography */
+  --font-size-sm: 0.875rem;
+  --font-size-base: 1rem;
+  --font-size-lg: 1.125rem;
+  --font-size-xl: 1.25rem;
+  --line-height-tight: 1.25;
+  --line-height-normal: 1.5;
+
+  /* Borders */
+  --radius-sm: 0.25rem;
+  --radius-md: 0.5rem;
+  --radius-lg: 1rem;
+  --border-color: #e2e8f0;
+}
+
+/* Dark mode via media query or class */
+@media (prefers-color-scheme: dark) {
+  :root {
+    --color-surface: #0f172a;
+    --color-text-primary: #f1f5f9;
+    --border-color: #1e293b;
+  }
+}
+```
+
+## BEM Naming Convention
+
+```css
+/* Block */
+.card { }
+
+/* Element (part of block) */
+.card__header { }
+.card__body { }
+.card__footer { }
+
+/* Modifier (variation of block or element) */
+.card--featured { }
+.card__header--sticky { }
+
+/* Avoid deep nesting — max 2 levels */
+/* ❌ .card__header__title__icon { } */
+/* ✅ .card__icon { } */
+```
+
+## Tailwind: Extracting Repeated Patterns
+
+```tsx
+// ❌ Repeating long class strings — hard to maintain
+<button className="px-4 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700 focus:ring-2 focus:ring-blue-500 disabled:opacity-50">
+<button className="px-4 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700 focus:ring-2 focus:ring-blue-500 disabled:opacity-50">
+
+// ✅ Extract to component variant
+const buttonVariants = cva(
+  "px-4 py-2 rounded-md focus:ring-2 disabled:opacity-50 transition-colors",
+  {
+    variants: {
+      variant: {
+        primary: "bg-blue-600 text-white hover:bg-blue-700 focus:ring-blue-500",
+        secondary: "bg-gray-100 text-gray-900 hover:bg-gray-200 focus:ring-gray-400",
+        ghost: "text-gray-700 hover:bg-gray-100 focus:ring-gray-400",
+      },
+      size: {
+        sm: "px-3 py-1.5 text-sm",
+        md: "px-4 py-2",
+        lg: "px-6 py-3 text-lg",
+      },
+    },
+    defaultVariants: { variant: "primary", size: "md" },
+  }
+);
+```
+
+## Responsive Design Patterns
+
+```css
+/* Mobile-first — base styles for mobile, then override for larger */
+.card {
+  padding: var(--space-4);           /* mobile */
+}
+
+@media (min-width: 768px) {
+  .card { padding: var(--space-6); } /* tablet */
+}
+
+@media (min-width: 1024px) {
+  .card { padding: var(--space-8); } /* desktop */
+}
+
+/* Container queries (modern — prefer over media queries for components) */
+.card-container { container-type: inline-size; }
+
+@container (min-width: 400px) {
+  .card { display: grid; grid-template-columns: auto 1fr; }
+}
+```
+
+## Specificity Rules
+
+```css
+/* Target specificity range: 0-1-0 to 0-2-0 */
+/* ❌ Too high — hard to override */
+#app .container .card.featured > .header span.title { }  /* 1-3-1 */
+
+/* ✅ Right level — component-scoped */
+.card__title { }                 /* 0-1-0 */
+.card--featured .card__title { } /* 0-2-0 */
+
+/* Never use !important in component styles — signals architecture problem */
+```

package/areas/software/frontend/skills/error-handling/SKILL.md

@@ -0,0 +1,55 @@
+# Skill: Frontend Error Handling
+
+## When to load
+
+When adding error boundaries, handling async errors, or building error UI states.
+
+## Error Boundary
+
+```tsx
+class ErrorBoundary extends React.Component<
+  { fallback: React.ComponentType<{ error: Error; reset: () => void }> },
+  { error: Error | null }
+> {
+  state = { error: null };
+
+  static getDerivedStateFromError(error: Error) {
+    return { error };
+  }
+
+  componentDidCatch(error: Error, info: React.ErrorInfo) {
+    logger.error('UI Error', { error: error.message, componentStack: info.componentStack });
+  }
+
+  render() {
+    if (this.state.error) {
+      const Fallback = this.props.fallback;
+      return <Fallback error={this.state.error} reset={() => this.setState({ error: null })} />;
+    }
+    return this.props.children;
+  }
+}
+
+// Usage:
+<ErrorBoundary fallback={RouteErrorFallback}>
+  <UserDashboard />
+</ErrorBoundary>
+```
+
+## Error Classification
+
+```ts
+export class ApiError extends Error {
+  constructor(public status: number, public body: unknown) {
+    super(`API Error ${status}`);
+  }
+}
+
+// In components:
+if (error instanceof ApiError) {
+  if (error.status === 401) return <LoginRedirect />;
+  if (error.status === 403) return <ForbiddenMessage />;
+  if (error.status === 404) return <NotFound />;
+}
+return <GenericError message={error.message} />;
+```

package/areas/software/frontend/skills/performance-tuning/SKILL.md

@@ -0,0 +1,58 @@
+# Skill: Frontend Performance Tuning
+
+## When to load
+
+When optimizing Core Web Vitals, reducing bundle size, diagnosing render performance, or reviewing images/fonts.
+
+## Re-render Prevention
+
+```tsx
+// Memoize expensive computations
+const sorted = useMemo(
+  () => [...items].sort((a, b) => a.name.localeCompare(b.name)),
+  [items]
+);
+
+// Stable callback references
+const handleClick = useCallback(() => doSomething(id), [id]);
+
+// Memoize child components receiving object/function props
+const ExpensiveList = React.memo(({ items, onSelect }: ListProps) => (
+  // rendering
+));
+
+// ❌ Inline objects create new references every render
+<MyComponent config={{ timeout: 3000 }} />
+// ✅ Stable reference
+const CONFIG = { timeout: 3000 };
+<MyComponent config={CONFIG} />
+```
+
+## Code Splitting (Mandatory)
+
+```tsx
+const UserDashboard = lazy(() => import('./features/users/UserDashboard'));
+
+<Suspense fallback={<PageSkeleton />}>
+  <UserDashboard />
+</Suspense>
+```
+
+## Image Optimization Checklist
+
+- [ ] Explicit `width` and `height` to prevent CLS
+- [ ] WebP/AVIF via `<picture>` with JPG fallback
+- [ ] `loading="lazy"` for below-fold images
+- [ ] `loading="eager"` + `fetchpriority="high"` for LCP image
+
+## Bundle Analysis
+
+```bash
+npx vite-bundle-visualizer
+```
+
+| Library | Problem | Solution |
+|:---|:---|:---|
+| `moment.js` | 300KB+ | Replace with `date-fns` |
+| `lodash` | Full import | Use `lodash-es` named imports |
+| `@mui/material` | Full import | Path imports: `@mui/material/Button` |

package/areas/software/frontend/skills/state-management/SKILL.md

@@ -0,0 +1,54 @@
+# Skill: State Management
+
+## When to load
+
+When deciding where to put state, choosing between local/global state, integrating server state, or debugging stale data.
+
+## State Classification Matrix
+
+| State Type | Example | Solution |
+|:---|:---|:---|
+| **Local UI State** | Modal open/close, input focus | `useState` / `useReducer` |
+| **Shared UI State** | Theme, sidebar collapse | React Context + `useReducer` |
+| **Server/Remote State** | API data, pagination | React Query / SWR |
+| **URL State** | Filters, search params | `useSearchParams` |
+| **Global App State** | Auth session, shopping cart | Zustand / Redux Toolkit |
+| **Form State** | Input values, validation errors | React Hook Form |
+
+## Colocation Rule
+
+State should live as **close to where it's used** as possible. Only lift state up when two components genuinely need to share it.
+
+```
+❌ Storing modal visibility in a global store
+✅ Storing modal visibility in the component that renders the modal
+```
+
+## React Query: Key Patterns
+
+```tsx
+const { data } = useQuery({
+  queryKey: ['users', { page, filters }],
+  queryFn: () => fetchUsers({ page, filters }),
+  staleTime: 5 * 60 * 1000,
+});
+
+const mutation = useMutation({
+  mutationFn: createUser,
+  onSuccess: () => queryClient.invalidateQueries({ queryKey: ['users'] }),
+});
+```
+
+## Zustand: Slice Pattern
+
+```ts
+export const useAuthStore = create<AuthState>((set) => ({
+  user: null,
+  token: null,
+  login: async (credentials) => {
+    const { user, token } = await authApi.login(credentials);
+    set({ user, token });
+  },
+  logout: () => set({ user: null, token: null }),
+}));
+```