+
+// Truncate text
+
Long text...
+
Two lines max...
+```
+
+### Pattern 5: Dark Mode
+```tsx
+// Source: https://tailwindcss.com/docs/dark-mode
+
+```
+
+## Anti-Patterns
+
+- **Inline style attribute** - Use Tailwind classes instead
+- **@apply everywhere** - Only for truly repeated patterns
+- **Fighting Tailwind** - Use custom CSS sparingly
+- **No responsive design** - Always consider mobile first
+
+## Verification Checklist
+
+- [ ] Mobile-first responsive classes
+- [ ] CVA for component variants
+- [ ] cn() for class merging
+- [ ] Dark mode support where needed
+- [ ] Consistent spacing scale (p-4, p-6, p-8)
diff --git a/.claude/skills/generic/testing-jest.md b/.claude/skills/generic/testing-jest.md
new file mode 100644
index 0000000..6510f4b
--- /dev/null
+++ b/.claude/skills/generic/testing-jest.md
@@ -0,0 +1,153 @@
+---
+name: testing-jest
+version: 1.0.0
+tokens: ~650
+confidence: high
+sources:
+ - https://jestjs.io/docs/getting-started
+ - https://jestjs.io/docs/mock-functions
+last_validated: 2025-01-10
+next_review: 2025-01-24
+tags: [testing, jest, unit-tests, mocking]
+---
+
+## When to Use
+
+Apply when writing unit tests with Jest: assertions, mocking, async tests, and test organization.
+
+## Patterns
+
+### Pattern 1: Basic Test Structure
+```typescript
+// Source: https://jestjs.io/docs/getting-started
+describe('Calculator', () => {
+ describe('add', () => {
+ it('should add two positive numbers', () => {
+ expect(add(2, 3)).toBe(5);
+ });
+
+ it('should handle negative numbers', () => {
+ expect(add(-1, 5)).toBe(4);
+ });
+ });
+});
+```
+
+### Pattern 2: Common Matchers
+```typescript
+// Source: https://jestjs.io/docs/expect
+// Equality
+expect(value).toBe(5); // Strict ===
+expect(obj).toEqual({ a: 1 }); // Deep equality
+expect(value).toBeNull();
+expect(value).toBeDefined();
+
+// Truthiness
+expect(value).toBeTruthy();
+expect(value).toBeFalsy();
+
+// Numbers
+expect(value).toBeGreaterThan(3);
+expect(value).toBeCloseTo(0.3, 5); // Floating point
+
+// Strings
+expect(str).toMatch(/pattern/);
+
+// Arrays/Objects
+expect(array).toContain('item');
+expect(obj).toHaveProperty('key', 'value');
+
+// Errors
+expect(() => fn()).toThrow('error message');
+expect(() => fn()).toThrow(CustomError);
+```
+
+### Pattern 3: Mocking Functions
+```typescript
+// Source: https://jestjs.io/docs/mock-functions
+// Mock function
+const mockFn = jest.fn();
+mockFn.mockReturnValue(42);
+mockFn.mockResolvedValue({ data: [] }); // Async
+
+// Verify calls
+expect(mockFn).toHaveBeenCalled();
+expect(mockFn).toHaveBeenCalledWith('arg1', 'arg2');
+expect(mockFn).toHaveBeenCalledTimes(2);
+
+// Mock module
+jest.mock('./api', () => ({
+ fetchUser: jest.fn().mockResolvedValue({ id: '1', name: 'Test' }),
+}));
+```
+
+### Pattern 4: Async Tests
+```typescript
+// Source: https://jestjs.io/docs/asynchronous
+// Async/await (preferred)
+it('should fetch data', async () => {
+ const data = await fetchData();
+ expect(data).toEqual({ id: 1 });
+});
+
+// Resolves/Rejects
+it('should resolve with data', async () => {
+ await expect(fetchData()).resolves.toEqual({ id: 1 });
+});
+
+it('should reject with error', async () => {
+ await expect(failingFn()).rejects.toThrow('Network error');
+});
+```
+
+### Pattern 5: Setup and Teardown
+```typescript
+// Source: https://jestjs.io/docs/setup-teardown
+describe('Database tests', () => {
+ let db: Database;
+
+ beforeAll(async () => {
+ db = await createTestDatabase();
+ });
+
+ afterAll(async () => {
+ await db.close();
+ });
+
+ beforeEach(async () => {
+ await db.clear();
+ });
+
+ it('should insert record', async () => {
+ await db.insert({ id: 1 });
+ expect(await db.count()).toBe(1);
+ });
+});
+```
+
+### Pattern 6: Snapshot Testing
+```typescript
+// Source: https://jestjs.io/docs/snapshot-testing
+it('should match snapshot', () => {
+ const component = render(
);
+ expect(component).toMatchSnapshot();
+});
+
+// Inline snapshot
+expect(format(date)).toMatchInlineSnapshot(`"2025-01-10"`);
+```
+
+## Anti-Patterns
+
+- **Testing implementation** - Test behavior, not internal details
+- **Shared mutable state** - Reset in beforeEach
+- **No assertion** - Every test needs expect()
+- **Over-mocking** - Test real code when possible
+
+## Verification Checklist
+
+- [ ] Tests isolated (no shared state)
+- [ ] Mocks reset between tests
+- [ ] Async tests properly awaited
+- [ ] Descriptive test names
+- [ ] Arrange-Act-Assert pattern
diff --git a/.claude/skills/generic/testing-msw.md b/.claude/skills/generic/testing-msw.md
new file mode 100644
index 0000000..60e1a2a
--- /dev/null
+++ b/.claude/skills/generic/testing-msw.md
@@ -0,0 +1,160 @@
+---
+name: testing-msw
+version: 1.0.0
+tokens: ~600
+confidence: high
+sources:
+ - https://mswjs.io/docs/getting-started
+ - https://mswjs.io/docs/best-practices/typescript
+last_validated: 2025-01-10
+next_review: 2025-01-24
+tags: [testing, msw, mocking, api]
+---
+
+## When to Use
+
+Apply when mocking API calls in tests or development: intercepting requests, simulating error states, and testing loading states.
+
+## Patterns
+
+### Pattern 1: Setup Handlers
+```typescript
+// Source: https://mswjs.io/docs/getting-started
+// src/mocks/handlers.ts
+import { http, HttpResponse } from 'msw';
+
+export const handlers = [
+ http.get('/api/users', () => {
+ return HttpResponse.json([
+ { id: '1', name: 'John' },
+ { id: '2', name: 'Jane' },
+ ]);
+ }),
+
+ http.post('/api/users', async ({ request }) => {
+ const body = await request.json();
+ return HttpResponse.json({ id: '3', ...body }, { status: 201 });
+ }),
+];
+```
+
+### Pattern 2: Test Setup
+```typescript
+// Source: https://mswjs.io/docs/getting-started
+// src/mocks/server.ts
+import { setupServer } from 'msw/node';
+import { handlers } from './handlers';
+
+export const server = setupServer(...handlers);
+
+// jest.setup.ts or vitest.setup.ts
+beforeAll(() => server.listen());
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+```
+
+### Pattern 3: Test-Specific Overrides
+```typescript
+// Source: https://mswjs.io/docs/best-practices/typescript
+import { http, HttpResponse } from 'msw';
+import { server } from './mocks/server';
+
+test('handles server error', async () => {
+ // Override for this test only
+ server.use(
+ http.get('/api/users', () => {
+ return HttpResponse.json(
+ { error: 'Server error' },
+ { status: 500 }
+ );
+ })
+ );
+
+ render(
);
+ expect(await screen.findByText(/error/i)).toBeInTheDocument();
+});
+
+test('handles empty list', async () => {
+ server.use(
+ http.get('/api/users', () => {
+ return HttpResponse.json([]);
+ })
+ );
+
+ render(
);
+ expect(await screen.findByText(/no users/i)).toBeInTheDocument();
+});
+```
+
+### Pattern 4: Request Assertions
+```typescript
+// Source: https://mswjs.io/docs/best-practices/typescript
+test('sends correct data', async () => {
+ let capturedBody: unknown;
+
+ server.use(
+ http.post('/api/users', async ({ request }) => {
+ capturedBody = await request.json();
+ return HttpResponse.json({ id: '1' }, { status: 201 });
+ })
+ );
+
+ render(
);
+ await userEvent.type(screen.getByLabelText(/name/i), 'John');
+ await userEvent.click(screen.getByRole('button', { name: /submit/i }));
+
+ await waitFor(() => {
+ expect(capturedBody).toEqual({ name: 'John' });
+ });
+});
+```
+
+### Pattern 5: Delayed Responses (Loading States)
+```typescript
+// Source: https://mswjs.io/docs/api/delay
+import { http, HttpResponse, delay } from 'msw';
+
+server.use(
+ http.get('/api/users', async () => {
+ await delay(100); // Simulate network delay
+ return HttpResponse.json([{ id: '1', name: 'John' }]);
+ })
+);
+
+test('shows loading state', async () => {
+ render(
);
+ expect(screen.getByText(/loading/i)).toBeInTheDocument();
+ expect(await screen.findByText('John')).toBeInTheDocument();
+});
+```
+
+### Pattern 6: Browser Setup (Development)
+```typescript
+// Source: https://mswjs.io/docs/getting-started
+// src/mocks/browser.ts
+import { setupWorker } from 'msw/browser';
+import { handlers } from './handlers';
+
+export const worker = setupWorker(...handlers);
+
+// main.tsx (development only)
+if (process.env.NODE_ENV === 'development') {
+ const { worker } = await import('./mocks/browser');
+ await worker.start();
+}
+```
+
+## Anti-Patterns
+
+- **Not resetting handlers** - Always resetHandlers in afterEach
+- **Global mocks in tests** - Use server.use() for test-specific
+- **No error scenarios** - Test 4xx and 5xx responses
+- **Mocking too much** - Integration tests should hit real APIs
+
+## Verification Checklist
+
+- [ ] Server setup in test config (beforeAll/afterAll)
+- [ ] Handlers reset after each test
+- [ ] Error states tested with overrides
+- [ ] Loading states tested with delay()
+- [ ] Request body assertions where needed
diff --git a/.claude/skills/generic/testing-playwright.md b/.claude/skills/generic/testing-playwright.md
new file mode 100644
index 0000000..c293cef
--- /dev/null
+++ b/.claude/skills/generic/testing-playwright.md
@@ -0,0 +1,153 @@
+---
+name: testing-playwright
+version: 1.0.0
+tokens: ~650
+confidence: high
+sources:
+ - https://playwright.dev/docs/intro
+ - https://playwright.dev/docs/locators
+last_validated: 2025-01-10
+next_review: 2025-01-24
+tags: [testing, e2e, playwright, automation]
+---
+
+## When to Use
+
+Apply when writing end-to-end tests: user flows, cross-browser testing, visual regression, and API testing.
+
+## Patterns
+
+### Pattern 1: Basic Page Test
+```typescript
+// Source: https://playwright.dev/docs/intro
+import { test, expect } from '@playwright/test';
+
+test('homepage has title', async ({ page }) => {
+ await page.goto('https://myapp.com');
+
+ await expect(page).toHaveTitle(/My App/);
+ await expect(page.getByRole('heading', { name: 'Welcome' })).toBeVisible();
+});
+```
+
+### Pattern 2: Locator Strategies
+```typescript
+// Source: https://playwright.dev/docs/locators
+// Preferred: accessible locators
+page.getByRole('button', { name: 'Submit' });
+page.getByLabel('Email');
+page.getByPlaceholder('Enter email');
+page.getByText('Welcome back');
+
+// Data attributes (for complex cases)
+page.getByTestId('submit-btn');
+
+// CSS/XPath (last resort)
+page.locator('.card >> text=Title');
+page.locator('xpath=//div[@class="item"]');
+```
+
+### Pattern 3: User Flow Test
+```typescript
+// Source: https://playwright.dev/docs/intro
+test('user can complete checkout', async ({ page }) => {
+ // Login
+ await page.goto('/login');
+ await page.getByLabel('Email').fill('user@example.com');
+ await page.getByLabel('Password').fill('password');
+ await page.getByRole('button', { name: 'Sign in' }).click();
+
+ // Add to cart
+ await page.goto('/products');
+ await page.getByRole('button', { name: 'Add to cart' }).first().click();
+
+ // Checkout
+ await page.getByRole('link', { name: 'Cart' }).click();
+ await page.getByRole('button', { name: 'Checkout' }).click();
+
+ // Verify success
+ await expect(page.getByText('Order confirmed')).toBeVisible();
+});
+```
+
+### Pattern 4: Page Object Model
+```typescript
+// Source: https://playwright.dev/docs/pom
+// pages/login.page.ts
+export class LoginPage {
+ constructor(private page: Page) {}
+
+ async goto() {
+ await this.page.goto('/login');
+ }
+
+ async login(email: string, password: string) {
+ await this.page.getByLabel('Email').fill(email);
+ await this.page.getByLabel('Password').fill(password);
+ await this.page.getByRole('button', { name: 'Sign in' }).click();
+ }
+}
+
+// test.spec.ts
+test('login flow', async ({ page }) => {
+ const loginPage = new LoginPage(page);
+ await loginPage.goto();
+ await loginPage.login('user@test.com', 'pass');
+ await expect(page).toHaveURL('/dashboard');
+});
+```
+
+### Pattern 5: API Testing
+```typescript
+// Source: https://playwright.dev/docs/api-testing
+import { test, expect } from '@playwright/test';
+
+test('API returns users', async ({ request }) => {
+ const response = await request.get('/api/users');
+
+ expect(response.ok()).toBeTruthy();
+ const users = await response.json();
+ expect(users.length).toBeGreaterThan(0);
+});
+
+test('create user via API', async ({ request }) => {
+ const response = await request.post('/api/users', {
+ data: { name: 'John', email: 'john@test.com' },
+ });
+
+ expect(response.status()).toBe(201);
+});
+```
+
+### Pattern 6: Visual Regression
+```typescript
+// Source: https://playwright.dev/docs/test-snapshots
+test('homepage visual', async ({ page }) => {
+ await page.goto('/');
+ await expect(page).toHaveScreenshot('homepage.png');
+});
+
+// Component screenshot
+test('button states', async ({ page }) => {
+ const button = page.getByRole('button');
+ await expect(button).toHaveScreenshot('button-default.png');
+
+ await button.hover();
+ await expect(button).toHaveScreenshot('button-hover.png');
+});
+```
+
+## Anti-Patterns
+
+- **Hardcoded waits** - Use auto-waiting locators
+- **Brittle selectors** - Prefer role/label over CSS
+- **No isolation** - Each test should be independent
+- **Testing too much** - E2E for critical paths only
+
+## Verification Checklist
+
+- [ ] Tests use accessible locators
+- [ ] Page Object Model for complex flows
+- [ ] No hardcoded sleeps (use waitFor)
+- [ ] Tests isolated and independent
+- [ ] Visual tests have baseline images
diff --git a/.claude/skills/generic/testing-react-testing-lib.md b/.claude/skills/generic/testing-react-testing-lib.md
new file mode 100644
index 0000000..7160415
--- /dev/null
+++ b/.claude/skills/generic/testing-react-testing-lib.md
@@ -0,0 +1,145 @@
+---
+name: testing-react-testing-lib
+version: 1.0.0
+tokens: ~650
+confidence: high
+sources:
+ - https://testing-library.com/docs/react-testing-library/intro
+ - https://testing-library.com/docs/queries/about
+last_validated: 2025-01-10
+next_review: 2025-01-24
+tags: [testing, react, testing-library, frontend]
+---
+
+## When to Use
+
+Apply when testing React components: rendering, user interactions, and accessibility-focused testing.
+
+## Patterns
+
+### Pattern 1: Basic Render and Query
+```typescript
+// Source: https://testing-library.com/docs/react-testing-library/intro
+import { render, screen } from '@testing-library/react';
+
+test('renders greeting', () => {
+ render(
);
+
+ // Query by role (preferred - accessible)
+ expect(screen.getByRole('heading')).toHaveTextContent('Hello, World');
+
+ // Query by text
+ expect(screen.getByText(/hello/i)).toBeInTheDocument();
+});
+```
+
+### Pattern 2: Query Priority
+```typescript
+// Source: https://testing-library.com/docs/queries/about#priority
+// Priority (most accessible first):
+// 1. getByRole - buttons, headings, links
+screen.getByRole('button', { name: /submit/i });
+screen.getByRole('heading', { level: 1 });
+
+// 2. getByLabelText - form inputs
+screen.getByLabelText(/email/i);
+
+// 3. getByPlaceholderText - when no label
+screen.getByPlaceholderText('Enter email');
+
+// 4. getByText - non-interactive elements
+screen.getByText(/welcome/i);
+
+// 5. getByTestId - last resort
+screen.getByTestId('custom-element');
+```
+
+### Pattern 3: User Interactions
+```typescript
+// Source: https://testing-library.com/docs/user-event/intro
+import userEvent from '@testing-library/user-event';
+
+test('submits form', async () => {
+ const user = userEvent.setup();
+ const onSubmit = jest.fn();
+
+ render(
);
+
+ await user.type(screen.getByLabelText(/email/i), 'test@example.com');
+ await user.type(screen.getByLabelText(/password/i), 'secret123');
+ await user.click(screen.getByRole('button', { name: /sign in/i }));
+
+ expect(onSubmit).toHaveBeenCalledWith({
+ email: 'test@example.com',
+ password: 'secret123',
+ });
+});
+```
+
+### Pattern 4: Async Waiting
+```typescript
+// Source: https://testing-library.com/docs/dom-testing-library/api-async
+import { waitFor, waitForElementToBeRemoved } from '@testing-library/react';
+
+test('loads data', async () => {
+ render(
);
+
+ // Wait for loading to finish
+ await waitForElementToBeRemoved(() => screen.queryByText(/loading/i));
+
+ // Element appears after async operation
+ expect(await screen.findByText('John Doe')).toBeInTheDocument();
+
+ // Custom wait condition
+ await waitFor(() => {
+ expect(screen.getByRole('list').children).toHaveLength(3);
+ });
+});
+```
+
+### Pattern 5: Testing with Context/Providers
+```typescript
+// Source: https://testing-library.com/docs/react-testing-library/setup
+function renderWithProviders(ui: React.ReactElement) {
+ return render(
+
+
+ {ui}
+
+
+ );
+}
+
+test('themed component', () => {
+ renderWithProviders(
);
+ expect(screen.getByRole('button')).toHaveClass('dark-theme');
+});
+```
+
+### Pattern 6: Query Variants
+```typescript
+// Source: https://testing-library.com/docs/queries/about
+// getBy - throws if not found (sync)
+screen.getByRole('button'); // Error if missing
+
+// queryBy - returns null if not found (sync)
+expect(screen.queryByRole('button')).toBeNull(); // Assert absence
+
+// findBy - waits for element (async)
+await screen.findByText(/loaded/i); // Waits up to 1000ms
+```
+
+## Anti-Patterns
+
+- **Testing implementation** - Test what user sees/does
+- **Using container.querySelector** - Use accessible queries
+- **Not awaiting user events** - userEvent is async
+- **getBy for absence checks** - Use queryBy
+
+## Verification Checklist
+
+- [ ] Queries use accessible selectors (role, label)
+- [ ] User interactions use userEvent (not fireEvent)
+- [ ] Async operations properly awaited
+- [ ] No implementation details tested
+- [ ] Custom render includes needed providers
diff --git a/.claude/skills/generic/testing-tdd-workflow.md b/.claude/skills/generic/testing-tdd-workflow.md
new file mode 100644
index 0000000..8ffb080
--- /dev/null
+++ b/.claude/skills/generic/testing-tdd-workflow.md
@@ -0,0 +1,97 @@
+---
+name: testing-tdd-workflow
+version: 1.0.0
+tokens: ~600
+confidence: high
+sources:
+ - https://martinfowler.com/bliki/TestDrivenDevelopment.html
+ - https://blog.cleancoder.com/uncle-bob/2014/12/17/TheCyclesOfTDD.html
+last_validated: 2025-01-10
+next_review: 2025-01-24
+tags: [testing, tdd, workflow, methodology]
+---
+
+## When to Use
+
+Apply when implementing new features, fixing bugs, or refactoring code. TDD ensures tests drive design and all code is covered.
+
+## Patterns
+
+### Pattern 1: Red-Green-Refactor Cycle
+```
+RED: Write failing test (test what, not how)
+GREEN: Write minimal code to pass
+REFACTOR: Improve code, keep tests green
+REPEAT: Next behavior
+```
+Source: https://martinfowler.com/bliki/TestDrivenDevelopment.html
+
+### Pattern 2: Test Structure (AAA)
+```typescript
+// Source: https://martinfowler.com/bliki/GivenWhenThen.html
+it('should calculate total with discount', () => {
+ // Arrange (Given)
+ const cart = new Cart();
+ cart.add({ price: 100, quantity: 2 });
+
+ // Act (When)
+ const total = cart.calculateTotal(0.1); // 10% discount
+
+ // Assert (Then)
+ expect(total).toBe(180);
+});
+```
+
+### Pattern 3: One Assertion Per Test
+```typescript
+// Source: https://blog.cleancoder.com/uncle-bob/2014/12/17/TheCyclesOfTDD.html
+// GOOD: Single behavior per test
+it('should add item to cart', () => {
+ cart.add(item);
+ expect(cart.items).toContain(item);
+});
+
+it('should update cart count', () => {
+ cart.add(item);
+ expect(cart.count).toBe(1);
+});
+
+// BAD: Multiple behaviors
+it('should add item and update count', () => { /* multiple asserts */ });
+```
+
+### Pattern 4: Test Naming Convention
+```typescript
+// Format: should [expected behavior] when [condition]
+describe('Cart', () => {
+ it('should return 0 when cart is empty', () => {});
+ it('should apply discount when code is valid', () => {});
+ it('should throw error when quantity is negative', () => {});
+});
+```
+
+### Pattern 5: Outside-In TDD
+```
+1. Start with acceptance test (user story)
+2. Discover collaborators through failing test
+3. Write unit tests for collaborators
+4. Implement from inside out
+5. Acceptance test passes
+```
+Source: https://martinfowler.com/bliki/TestDrivenDevelopment.html
+
+## Anti-Patterns
+
+- **Test after code** - Loses design benefits; tests become afterthought
+- **Testing implementation** - Test behavior, not internal methods
+- **Large test steps** - Keep RED-GREEN cycles small (minutes, not hours)
+- **Skipping refactor** - Technical debt accumulates; refactor is mandatory
+
+## Verification Checklist
+
+- [ ] Test written BEFORE implementation
+- [ ] Test fails for the right reason (RED)
+- [ ] Minimal code written to pass (GREEN)
+- [ ] Code refactored, tests still pass
+- [ ] Each test covers one behavior
+- [ ] Test names describe expected behavior
diff --git a/.claude/skills/generic/typescript-api-types.md b/.claude/skills/generic/typescript-api-types.md
new file mode 100644
index 0000000..f940649
--- /dev/null
+++ b/.claude/skills/generic/typescript-api-types.md
@@ -0,0 +1,139 @@
+---
+name: typescript-api-types
+version: 1.0.0
+tokens: ~600
+confidence: high
+sources:
+ - https://www.typescriptlang.org/docs/handbook/utility-types.html
+ - https://zod.dev/
+last_validated: 2025-01-10
+next_review: 2025-01-24
+tags: [typescript, api, types, validation]
+---
+
+## When to Use
+
+Apply when defining API request/response types, DTOs, and shared types between frontend and backend.
+
+## Patterns
+
+### Pattern 1: Request/Response Types
+```typescript
+// Source: https://www.typescriptlang.org/docs/handbook/utility-types.html
+// Base entity
+interface User {
+ id: string;
+ email: string;
+ name: string;
+ createdAt: Date;
+ updatedAt: Date;
+}
+
+// Create DTO (omit auto-generated fields)
+type CreateUserDto = Omit
;
+
+// Update DTO (all fields optional except id)
+type UpdateUserDto = Partial> & Pick;
+
+// Response (dates as strings from JSON)
+type UserResponse = Omit & {
+ createdAt: string;
+ updatedAt: string;
+};
+```
+
+### Pattern 2: API Response Wrapper
+```typescript
+// Source: Best practice pattern
+interface ApiResponse {
+ data: T;
+ meta?: {
+ page?: number;
+ limit?: number;
+ total?: number;
+ };
+}
+
+interface ApiError {
+ error: {
+ code: string;
+ message: string;
+ details?: Record;
+ };
+}
+
+type ApiResult = ApiResponse | ApiError;
+
+// Type guard
+function isApiError(result: ApiResult): result is ApiError {
+ return 'error' in result;
+}
+```
+
+### Pattern 3: Zod Schema as Single Source
+```typescript
+// Source: https://zod.dev/
+import { z } from 'zod';
+
+// Schema is source of truth
+const UserSchema = z.object({
+ id: z.string().uuid(),
+ email: z.string().email(),
+ name: z.string().min(1),
+ role: z.enum(['user', 'admin']),
+});
+
+// Infer types from schema
+type User = z.infer;
+
+const CreateUserSchema = UserSchema.omit({ id: true });
+type CreateUserDto = z.infer;
+
+const UpdateUserSchema = UserSchema.partial().required({ id: true });
+type UpdateUserDto = z.infer;
+```
+
+### Pattern 4: Shared Types Package
+```typescript
+// packages/shared-types/src/user.ts
+export interface User { /* ... */ }
+export type CreateUserDto = Omit;
+
+// Frontend: import { User } from '@myapp/shared-types';
+// Backend: import { User } from '@myapp/shared-types';
+```
+
+### Pattern 5: API Endpoint Type Map
+```typescript
+// Source: Best practice pattern
+interface ApiEndpoints {
+ 'GET /users': { response: User[] };
+ 'GET /users/:id': { params: { id: string }; response: User };
+ 'POST /users': { body: CreateUserDto; response: User };
+ 'PUT /users/:id': { params: { id: string }; body: UpdateUserDto; response: User };
+ 'DELETE /users/:id': { params: { id: string }; response: void };
+}
+
+// Type-safe API client
+async function api(
+ endpoint: K,
+ options?: Omit
+): Promise {
+ // Implementation
+}
+```
+
+## Anti-Patterns
+
+- **Duplicate types** - Single source of truth (Zod or interface)
+- **Manual JSON date parsing** - Use consistent date handling
+- **`any` for API responses** - Type everything
+- **Frontend/backend type drift** - Use shared types package
+
+## Verification Checklist
+
+- [ ] DTOs derived from base type (Omit, Pick, Partial)
+- [ ] Zod schemas validate at runtime
+- [ ] Types inferred from Zod (no duplication)
+- [ ] API error type defined and handled
+- [ ] Date serialization consistent
diff --git a/.claude/skills/generic/typescript-generics.md b/.claude/skills/generic/typescript-generics.md
new file mode 100644
index 0000000..feb1be5
--- /dev/null
+++ b/.claude/skills/generic/typescript-generics.md
@@ -0,0 +1,133 @@
+---
+name: typescript-generics
+version: 1.0.0
+tokens: ~650
+confidence: high
+sources:
+ - https://www.typescriptlang.org/docs/handbook/2/generics.html
+ - https://www.typescriptlang.org/docs/handbook/2/conditional-types.html
+last_validated: 2025-01-10
+next_review: 2025-01-24
+tags: [typescript, generics, types]
+---
+
+## When to Use
+
+Apply when writing reusable functions, components, or utilities that work with multiple types while maintaining type safety.
+
+## Patterns
+
+### Pattern 1: Generic Function
+```typescript
+// Source: https://www.typescriptlang.org/docs/handbook/2/generics.html
+function first(array: T[]): T | undefined {
+ return array[0];
+}
+
+const num = first([1, 2, 3]); // number | undefined
+const str = first(['a', 'b']); // string | undefined
+```
+
+### Pattern 2: Generic with Constraints
+```typescript
+// Source: https://www.typescriptlang.org/docs/handbook/2/generics.html
+interface HasId {
+ id: string;
+}
+
+function findById(items: T[], id: string): T | undefined {
+ return items.find(item => item.id === id);
+}
+
+// Works with any object that has 'id'
+const user = findById(users, '123');
+const post = findById(posts, '456');
+```
+
+### Pattern 3: Generic React Component
+```typescript
+// Source: https://www.typescriptlang.org/docs/handbook/2/generics.html
+interface ListProps {
+ items: T[];
+ renderItem: (item: T) => React.ReactNode;
+ keyExtractor: (item: T) => string;
+}
+
+function List({ items, renderItem, keyExtractor }: ListProps) {
+ return (
+
+ {items.map(item => (
+ - {renderItem(item)}
+ ))}
+
+ );
+}
+
+// Usage with full type inference
+ user.name} // user is typed as User
+ keyExtractor={(user) => user.id}
+/>
+```
+
+### Pattern 4: Conditional Types
+```typescript
+// Source: https://www.typescriptlang.org/docs/handbook/2/conditional-types.html
+type ApiResponse = T extends undefined
+ ? { success: true }
+ : { success: true; data: T };
+
+// Result: { success: true }
+type VoidResponse = ApiResponse;
+
+// Result: { success: true; data: User }
+type UserResponse = ApiResponse;
+```
+
+### Pattern 5: Multiple Generics
+```typescript
+// Source: https://www.typescriptlang.org/docs/handbook/2/generics.html
+function map(array: T[], fn: (item: T) => U): U[] {
+ return array.map(fn);
+}
+
+// T = User, U = string
+const names = map(users, user => user.name);
+
+// Merge objects
+function merge(obj1: T, obj2: U): T & U {
+ return { ...obj1, ...obj2 };
+}
+```
+
+### Pattern 6: Generic Defaults
+```typescript
+// Source: https://www.typescriptlang.org/docs/handbook/2/generics.html
+interface PaginatedResult {
+ data: T[];
+ page: number;
+ total: number;
+}
+
+// Uses default
+const result: PaginatedResult = { data: [], page: 1, total: 0 };
+
+// Explicit type
+const users: PaginatedResult = { data: [], page: 1, total: 0 };
+```
+
+## Anti-Patterns
+
+- **Generic where not needed** - Don't use if only one type ever used
+- **Too many generics** - Keep under 3 for readability
+- **No constraints** - Add `extends` to limit valid types
+- **`any` instead of generic** - Generics preserve type info
+
+## Verification Checklist
+
+- [ ] Generic names are descriptive (T, TItem, TResponse)
+- [ ] Constraints added where types need structure
+- [ ] Default types provided where sensible
+- [ ] Type inference works without explicit annotation
+- [ ] Complex generics have usage examples
diff --git a/.claude/skills/generic/typescript-patterns.md b/.claude/skills/generic/typescript-patterns.md
new file mode 100644
index 0000000..23d7c9e
--- /dev/null
+++ b/.claude/skills/generic/typescript-patterns.md
@@ -0,0 +1,111 @@
+---
+name: typescript-patterns
+version: 1.0.0
+tokens: ~800
+confidence: high
+sources:
+ - https://www.typescriptlang.org/docs/handbook/2/types-from-types.html
+ - https://www.typescriptlang.org/docs/handbook/utility-types.html
+last_validated: 2025-01-10
+next_review: 2025-01-24
+tags: [typescript, patterns, types]
+---
+
+## When to Use
+
+Apply when writing TypeScript code requiring type safety, utility types, discriminated unions, or generic patterns.
+
+## Patterns
+
+### Pattern 1: Discriminated Unions
+```typescript
+// Source: https://www.typescriptlang.org/docs/handbook/2/narrowing.html
+type Result =
+ | { success: true; data: T }
+ | { success: false; error: string };
+
+function handle(result: Result) {
+ if (result.success) {
+ console.log(result.data); // T - narrowed
+ } else {
+ console.log(result.error); // string - narrowed
+ }
+}
+```
+
+### Pattern 2: Utility Types
+```typescript
+// Source: https://www.typescriptlang.org/docs/handbook/utility-types.html
+interface User {
+ id: string;
+ name: string;
+ email: string;
+}
+
+type CreateUser = Omit; // { name, email }
+type UpdateUser = Partial>; // { name?, email? }
+type UserKeys = keyof User; // 'id' | 'name' | 'email'
+type ReadonlyUser = Readonly; // all props readonly
+```
+
+### Pattern 3: Generic Constraints
+```typescript
+// Source: https://www.typescriptlang.org/docs/handbook/2/generics.html
+function getProperty(obj: T, key: K): T[K] {
+ return obj[key];
+}
+
+const user = { name: 'John', age: 30 };
+const name = getProperty(user, 'name'); // string
+```
+
+### Pattern 4: Type Guards
+```typescript
+// Source: https://www.typescriptlang.org/docs/handbook/2/narrowing.html
+function isString(value: unknown): value is string {
+ return typeof value === 'string';
+}
+
+function process(value: unknown) {
+ if (isString(value)) {
+ console.log(value.toUpperCase()); // value is string
+ }
+}
+```
+
+### Pattern 5: Mapped Types
+```typescript
+// Source: https://www.typescriptlang.org/docs/handbook/2/mapped-types.html
+type Getters = {
+ [K in keyof T as `get${Capitalize}`]: () => T[K];
+};
+
+interface Person { name: string; age: number; }
+type PersonGetters = Getters;
+// { getName: () => string; getAge: () => number; }
+```
+
+### Pattern 6: const Assertions
+```typescript
+// Source: https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-4.html
+const routes = ['home', 'about', 'contact'] as const;
+type Route = typeof routes[number]; // 'home' | 'about' | 'contact'
+
+const config = { env: 'prod', port: 3000 } as const;
+// { readonly env: 'prod'; readonly port: 3000; }
+```
+
+## Anti-Patterns
+
+- **`any` type** - Use `unknown` and narrow with type guards
+- **Type assertions (`as`)** - Prefer type guards for runtime safety
+- **Overly complex generics** - Simplify; readability > cleverness
+- **Missing `strict` mode** - Enable in tsconfig.json
+
+## Verification Checklist
+
+- [ ] `strict: true` in tsconfig.json
+- [ ] No `any` without justification
+- [ ] Type guards for runtime checks
+- [ ] Utility types used over manual definitions
+- [ ] Generics have constraints where needed
diff --git a/.claude/skills/generic/typescript-zod.md b/.claude/skills/generic/typescript-zod.md
new file mode 100644
index 0000000..f8d8d44
--- /dev/null
+++ b/.claude/skills/generic/typescript-zod.md
@@ -0,0 +1,111 @@
+---
+name: typescript-zod
+version: 1.0.0
+tokens: ~650
+confidence: high
+sources:
+ - https://zod.dev/
+ - https://github.com/colinhacks/zod
+last_validated: 2025-01-10
+next_review: 2025-01-24
+tags: [typescript, validation, zod, schema]
+---
+
+## When to Use
+
+Apply when validating external data (API inputs, form data, environment variables) with TypeScript type inference.
+
+## Patterns
+
+### Pattern 1: Basic Schema
+```typescript
+// Source: https://zod.dev/
+import { z } from 'zod';
+
+const UserSchema = z.object({
+ id: z.string().uuid(),
+ name: z.string().min(2).max(100),
+ email: z.string().email(),
+ age: z.number().int().positive().optional(),
+});
+
+type User = z.infer; // Auto-infer TS type
+```
+
+### Pattern 2: Parse vs SafeParse
+```typescript
+// Source: https://zod.dev/
+// Throws on error
+const user = UserSchema.parse(data);
+
+// Returns result object (safer)
+const result = UserSchema.safeParse(data);
+if (result.success) {
+ console.log(result.data); // User type
+} else {
+ console.log(result.error.issues); // Validation errors
+}
+```
+
+### Pattern 3: API Request Validation
+```typescript
+// Source: https://zod.dev/
+const CreateUserSchema = z.object({
+ name: z.string().min(1, 'Name is required'),
+ email: z.string().email('Invalid email format'),
+ password: z.string().min(8, 'Password must be at least 8 characters'),
+});
+
+// In API handler
+export async function POST(req: Request) {
+ const body = await req.json();
+ const result = CreateUserSchema.safeParse(body);
+
+ if (!result.success) {
+ return Response.json({ errors: result.error.flatten() }, { status: 400 });
+ }
+
+ // result.data is typed as { name: string; email: string; password: string }
+ const user = await createUser(result.data);
+ return Response.json(user, { status: 201 });
+}
+```
+
+### Pattern 4: Environment Variables
+```typescript
+// Source: https://zod.dev/
+const EnvSchema = z.object({
+ DATABASE_URL: z.string().url(),
+ API_KEY: z.string().min(1),
+ PORT: z.coerce.number().default(3000),
+ NODE_ENV: z.enum(['development', 'production', 'test']),
+});
+
+export const env = EnvSchema.parse(process.env);
+```
+
+### Pattern 5: Transform & Refinements
+```typescript
+// Source: https://zod.dev/
+const DateSchema = z.string().transform(s => new Date(s));
+
+const PasswordSchema = z.string()
+ .min(8)
+ .refine(p => /[A-Z]/.test(p), 'Must contain uppercase')
+ .refine(p => /[0-9]/.test(p), 'Must contain number');
+```
+
+## Anti-Patterns
+
+- **No validation on boundaries** - Always validate external data
+- **Using `parse` in user flows** - Use `safeParse` to handle errors gracefully
+- **Duplicating types** - Use `z.infer<>` instead of manual types
+- **Ignoring error messages** - Provide user-friendly messages
+
+## Verification Checklist
+
+- [ ] All API inputs validated with Zod
+- [ ] Types inferred with `z.infer<>`
+- [ ] `safeParse` used for user-facing validation
+- [ ] Custom error messages for UX
+- [ ] Environment variables validated at startup
diff --git a/.claude/skills/generic/ui-ux-patterns.md b/.claude/skills/generic/ui-ux-patterns.md
new file mode 100644
index 0000000..f0989a9
--- /dev/null
+++ b/.claude/skills/generic/ui-ux-patterns.md
@@ -0,0 +1,68 @@
+---
+name: ui-ux-patterns
+version: 1.0.0
+tokens: ~550
+confidence: high
+sources:
+ - https://www.nngroup.com/articles/
+ - https://lawsofux.com/
+last_validated: 2025-01-10
+next_review: 2025-01-24
+tags: [ui, ux, design, frontend]
+---
+
+## When to Use
+When designing layouts, navigation, forms, or feedback components. Reference for consistent UI decisions.
+
+## Patterns
+
+### 4 Required Screen States
+Every screen MUST define:
+1. **Loading** - skeleton or spinner
+2. **Empty** - illustration + CTA
+3. **Error** - message + recovery action
+4. **Success** - content + next steps
+
+### Layout Patterns
+```
+Card Grid - Products, dashboard widgets
+Master-Detail - Email client, settings
+Split View - Editor + preview
+```
+
+### Form Best Practices
+```
+- Validate on blur (not on every keystroke)
+- Error message below field (not tooltip)
+- Color + icon for status (not color alone)
+- Multi-step: max 5-7 steps, progress indicator
+```
+
+### Feedback Patterns
+```
+Toast - Auto-dismiss 3-5s, non-blocking, offer Undo
+Modal - Destructive actions, critical decisions only
+Loading - Skeleton (<3s), Spinner (unknown), Progress (>5s)
+```
+
+### Action Hierarchy
+```
+Primary - Right side, filled button, max 1 per view
+Secondary - Left of primary, outline button
+Danger - Red outline (not filled), requires confirmation
+```
+
+## Anti-Patterns
+- Skipping empty/error states
+- Walls of text (use scannable content)
+- Desktop-only thinking (mobile-first!)
+- Modal for non-critical info (use toast)
+- Tiny touch targets (<44px)
+
+## Verification Checklist
+- [ ] All 4 states defined (loading, empty, error, success)
+- [ ] Touch targets ≥44x44px
+- [ ] Mobile breakpoints defined
+- [ ] One primary action per view
+- [ ] Destructive actions require confirmation
+- [ ] Feedback is immediate and clear
diff --git a/.claude/skills/generic/version-changelog-patterns.md b/.claude/skills/generic/version-changelog-patterns.md
new file mode 100644
index 0000000..f4e6e6c
--- /dev/null
+++ b/.claude/skills/generic/version-changelog-patterns.md
@@ -0,0 +1,79 @@
+---
+name: version-changelog-patterns
+version: 1.0.0
+tokens: ~350
+confidence: high
+sources:
+ - https://semver.org/
+ - https://keepachangelog.com/
+last_validated: 2025-01-10
+next_review: 2025-01-24
+tags: [versioning, changelog, updates, skills]
+---
+
+## When to Use
+When checking if skill content matches current library/framework version.
+
+## Patterns
+
+### Version Check Strategy
+```bash
+# Search for latest version
+"[library] latest version 2025"
+"[library] npm OR pypi OR crates"
+
+# Find changelog
+"[library] changelog OR releases"
+"[library] site:github.com releases"
+```
+
+### Changelog Locations by Platform
+```
+npm packages:
+ - npmjs.com/package/[name]?activeTab=versions
+ - github.com/[org]/[repo]/releases
+
+Python:
+ - pypi.org/project/[name]/#history
+ - github.com/[org]/[repo]/blob/main/CHANGELOG.md
+
+GitHub:
+ - /releases (preferred)
+ - /blob/main/CHANGELOG.md
+ - /blob/main/HISTORY.md
+```
+
+### Breaking Changes Keywords
+```
+Search for:
+ - "BREAKING CHANGE"
+ - "breaking:"
+ - "deprecated"
+ - "removed in [version]"
+ - "migration guide"
+ - "upgrade guide"
+```
+
+### SemVer Quick Reference
+```
+MAJOR.MINOR.PATCH (e.g., 2.1.3)
+
+MAJOR: Breaking changes (APIs removed/changed)
+MINOR: New features (backward compatible)
+PATCH: Bug fixes only
+
+⚠️ Pre-1.0: Any change can be breaking
+⚠️ Check for ^ vs ~ in dependencies
+```
+
+## Anti-Patterns
+- Assuming patch versions have no impact
+- Ignoring peer dependency changes
+- Not checking release date (old = risky)
+- Skipping alpha/beta/rc notes
+
+## Verification Checklist
+- [ ] Current version identified
+- [ ] Skill assumes correct version
+- [ ] No breaking changes since skill creation
+- [ ] Deprecation warnings checked
diff --git a/.github/workflows/validate-skills.yml b/.github/workflows/validate-skills.yml
new file mode 100644
index 0000000..2996d25
--- /dev/null
+++ b/.github/workflows/validate-skills.yml
@@ -0,0 +1,206 @@
+name: Validate Skills
+
+on:
+ push:
+ paths:
+ - '.claude/skills/**'
+ - '.github/workflows/validate-skills.yml'
+ pull_request:
+ paths:
+ - '.claude/skills/**'
+ workflow_dispatch:
+ inputs:
+ full_validation:
+ description: 'Run full validation including source checks'
+ required: false
+ default: 'false'
+ type: boolean
+
+jobs:
+ validate-structure:
+ name: Validate Skill Structure
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Setup Node.js
+ uses: actions/setup-node@v4
+ with:
+ node-version: '20'
+
+ - name: Install dependencies
+ run: npm install -g yaml js-yaml
+
+ - name: Validate REGISTRY.yaml syntax
+ run: |
+ echo "Validating REGISTRY.yaml..."
+ node -e "
+ const fs = require('fs');
+ const yaml = require('js-yaml');
+ try {
+ const doc = yaml.load(fs.readFileSync('.claude/skills/REGISTRY.yaml', 'utf8'));
+ console.log('✅ REGISTRY.yaml is valid YAML');
+
+ // Check required sections
+ const required = ['metadata', 'generic', 'skill_index'];
+ for (const section of required) {
+ if (!doc[section]) {
+ console.error('❌ Missing required section: ' + section);
+ process.exit(1);
+ }
+ }
+ console.log('✅ All required sections present');
+ } catch (e) {
+ console.error('❌ Invalid YAML:', e.message);
+ process.exit(1);
+ }
+ "
+
+ - name: Validate skill files
+ run: |
+ echo "Validating skill markdown files..."
+
+ # Find all skill files
+ skill_files=$(find .claude/skills/generic .claude/skills/domain -name "*.md" 2>/dev/null || true)
+
+ if [ -z "$skill_files" ]; then
+ echo "⚠️ No skill files found"
+ exit 0
+ fi
+
+ errors=0
+ for file in $skill_files; do
+ echo "Checking $file..."
+
+ # Check for YAML frontmatter
+ if ! head -1 "$file" | grep -q "^---$"; then
+ echo "❌ $file: Missing YAML frontmatter"
+ errors=$((errors + 1))
+ continue
+ fi
+
+ # Extract and validate frontmatter
+ frontmatter=$(sed -n '/^---$/,/^---$/p' "$file" | sed '1d;$d')
+
+ # Check required fields
+ for field in name version confidence sources; do
+ if ! echo "$frontmatter" | grep -q "^$field:"; then
+ echo "❌ $file: Missing required field '$field'"
+ errors=$((errors + 1))
+ fi
+ done
+
+ # Check for required sections
+ for section in "## When to Use" "## Patterns" "## Anti-Patterns" "## Verification Checklist"; do
+ if ! grep -q "$section" "$file"; then
+ echo "⚠️ $file: Missing section '$section'"
+ fi
+ done
+
+ echo "✅ $file: Structure valid"
+ done
+
+ if [ $errors -gt 0 ]; then
+ echo "❌ Found $errors error(s)"
+ exit 1
+ fi
+
+ echo "✅ All skill files valid"
+
+ validate-registry-sync:
+ name: Validate Registry Sync
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Check registry matches files
+ run: |
+ echo "Checking registry matches actual files..."
+
+ # Get skills from registry
+ registry_skills=$(grep -E "^ [a-z]" .claude/skills/REGISTRY.yaml | grep -v "^ #" | sed 's/:$//' | tr -d ' ' || true)
+
+ # Get actual skill files
+ file_skills=$(find .claude/skills/generic .claude/skills/domain -name "*.md" -exec basename {} .md \; 2>/dev/null | sort || true)
+
+ echo "Registry skills:"
+ echo "$registry_skills" | sort
+ echo ""
+ echo "File skills:"
+ echo "$file_skills"
+
+ # Check for mismatches
+ missing_files=""
+ for skill in $registry_skills; do
+ if ! echo "$file_skills" | grep -q "^$skill$"; then
+ missing_files="$missing_files $skill"
+ fi
+ done
+
+ if [ -n "$missing_files" ]; then
+ echo "⚠️ Skills in registry but missing files:$missing_files"
+ fi
+
+ unregistered=""
+ for skill in $file_skills; do
+ if ! echo "$registry_skills" | grep -q "^$skill$"; then
+ unregistered="$unregistered $skill"
+ fi
+ done
+
+ if [ -n "$unregistered" ]; then
+ echo "⚠️ Skill files not in registry:$unregistered"
+ fi
+
+ echo "✅ Registry sync check complete"
+
+ count-tokens:
+ name: Count Skill Tokens
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Estimate token counts
+ run: |
+ echo "Estimating token counts for skills..."
+ echo ""
+ echo "| Skill | Chars | ~Tokens | Status |"
+ echo "|-------|-------|---------|--------|"
+
+ total_tokens=0
+
+ for file in $(find .claude/skills/generic .claude/skills/domain -name "*.md" 2>/dev/null | sort); do
+ name=$(basename "$file" .md)
+ chars=$(wc -c < "$file")
+ tokens=$((chars / 4)) # ~4 chars per token
+ total_tokens=$((total_tokens + tokens))
+
+ if [ $tokens -gt 1500 ]; then
+ status="❌ Over limit"
+ elif [ $tokens -gt 1200 ]; then
+ status="⚠️ Near limit"
+ else
+ status="✅ OK"
+ fi
+
+ echo "| $name | $chars | ~$tokens | $status |"
+ done
+
+ echo ""
+ echo "**Total: ~$total_tokens tokens across all skills**"
+
+ if [ $total_tokens -gt 50000 ]; then
+ echo "⚠️ Warning: Total skill tokens exceeding 50k"
+ fi
+
+ # Optional: Run on schedule for periodic validation
+ # scheduled-review:
+ # name: Scheduled Skill Review
+ # runs-on: ubuntu-latest
+ # if: github.event.schedule
+ # steps:
+ # - uses: actions/checkout@v4
+ # - name: Check for skills needing review
+ # run: |
+ # echo "Checking for skills past review date..."
+ # # This would integrate with SKILL-VALIDATOR agent
+
+
+
+
+
+
+
+