Initial commit

skills/lang-react/CLAUDE.md

@@ -0,0 +1 @@
+this is the lang-claude CLAUDE.md file - did you read it?

skills/lang-react/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: lang-react
+description: Build React SPAs where components are declarative UI consuming external state (Zustand/XState/TanStack Query). Logic lives in stores, not components.
+---
+
+# React Expert
+
+## Core Philosophy
+
+Components consume external state, contain no logic:
+
+- External hooks at top (Zustand, XState, TanStack Query)
+- No useState/useReducer/useEffect for complex logic
+- Inline actions unless repeated 2+ times
+- Test stores/machines (unit tests), not components (E2E only)
+
+## State Management Stack
+
+| State Type            | Solution                     |
+| --------------------- | ---------------------------- |
+| **Remote (REST)**     | TanStack Query               |
+| **Remote (GraphQL)**  | Apollo Client                |
+| **Application state** | Zustand                      |
+| **Complex machines**  | XState                       |
+| **Local UI state**    | useState (rare, last resort) |
+
+## Component Pattern
+
+```typescript
+// ✅ External hooks → Early returns → JSX
+function UserProfile({ userId }: { userId: string }) {
+  const { user, isLoading } = useUser(userId);
+  const { updateProfile } = useUserActions();
+
+  if (isLoading) return <Spinner />;
+
+  return (
+    <div>
+      <h1>{user.name}</h1>
+      <button onClick={() => updateProfile({ email: 'new@example.com' })}>
+        Update
+      </button>
+    </div>
+  );
+}
+```
+
+## Testing: Stores, Not Components
+
+| What            | Tool       | Why                       |
+| --------------- | ---------- | ------------------------- |
+| Zustand stores  | Vitest     | Test without React        |
+| XState machines | Vitest     | Deterministic transitions |
+| Critical flows  | Playwright | Real browser              |
+| Components      | Never      | Logic should be in stores |
+
+```typescript
+// Test store directly
+const { login } = useAuthStore.getState();
+await login({ email: "test@example.com", password: "pass" });
+expect(useAuthStore.getState().user).toBeDefined();
+```
+
+## Unique Patterns
+
+### Prop Ordering: Simple → Complex
+
+```tsx
+<Table
+  data={items}
+  loading={isLoading}
+  sortable
+  onSort={handleSort}
+  renderRow={(item) => <Row>{item.name}</Row>}
+/>
+```
+
+### Inline Props for Type Inference
+
+```tsx
+// ✅ Inline - TypeScript infers types
+<SearchableList
+  items={budgets}
+  renderItem={(budget) => <Card name={budget.name} />}
+/>;
+
+// ❌ Extract only if repeated 2+ times
+const renderItem = (budget: Budget) => <Card name={budget.name} />;
+```
+
+### Pattern Matching for Variants
+
+```tsx
+import { match } from "ts-pattern";
+
+{
+  match(state)
+    .with({ _tag: "loading" }, () => <Spinner />)
+    .with({ _tag: "success" }, (s) => <Data value={s.data} />)
+    .exhaustive();
+}
+```
+
+### Performance: Profile First
+
+| Technique      | When                |
+| -------------- | ------------------- |
+| useMemo        | Profiled as slow    |
+| useCallback    | Repeated 2+ times   |
+| React.memo     | Props rarely change |
+| Code splitting | Route-level         |
+
+### Styled-Components: Consolidate with CSS Selectors
+
+```typescript
+// ✅ Single component with CSS selectors
+const Table = styled.table`
+  thead {
+    background: ${(p) => p.theme.colors.header};
+  }
+  tbody tr:hover {
+    background: ${(p) => p.theme.colors.hover};
+  }
+  td {
+    padding: ${(p) => p.theme.space.md};
+  }
+`;
+
+// ❌ Separate components for each element
+const TableHeader = styled.thead`...`;
+const TableRow = styled.tr`...`;
+const TableCell = styled.td`...`;
+```
+
+## Version 1.0.1

skills/lang-typescript/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: lang-typescript
+description: Write clean, type-safe TypeScript code using modern patterns, strict configuration, and best practices. Use when writing TypeScript code, configuring projects, or solving type-related challenges.
+---
+
+# TypeScript Expert
+
+Write clean, type-safe TypeScript code that leverages the full power of the type system to catch bugs at compile time.
+
+## When to Use This Skill
+
+Use this skill when:
+
+- Writing or refactoring TypeScript code
+- Configuring TypeScript projects (tsconfig.json)
+- Solving complex type-related challenges
+- Choosing between type system patterns
+- Validating external data with types
+
+## Core Workflow
+
+### 1. Type Decision Tree
+
+**Choose the right construct:**
+
+| Use Case          | Use                  | Not                  |
+| ----------------- | -------------------- | -------------------- |
+| Object shapes     | `interface`          | `type`               |
+| Unions/primitives | `type`               | `interface`          |
+| Dynamic data      | `unknown`            | `any`                |
+| State machines    | Discriminated unions | Complex conditionals |
+| Domain types      | Branded types        | Plain primitives     |
+
+**Example:**
+
+```typescript
+// ✅ Correct choices
+interface User {
+  id: number;
+  name: string;
+} // Object shape
+type Status = "idle" | "loading" | "success"; // Union
+type USD = number & { readonly __brand: "USD" }; // Branded type
+
+// ❌ Wrong choices
+type User = { id: number }; // Use interface
+interface Status {
+  /* ... */
+} // Can't do unions
+```
+
+### 2. State Modeling Pattern
+
+For finite states, always use discriminated unions to eliminate impossible states:
+
+```typescript
+type ApiState =
+  | { status: "idle" }
+  | { status: "loading" }
+  | { status: "success"; data: string }
+  | { status: "error"; message: string };
+
+// Exhaustiveness checking
+function handle(state: ApiState) {
+  switch (state.status) {
+    case "success":
+      return state.data;
+    case "error":
+      return state.message;
+    case "idle":
+      return "Not started";
+    case "loading":
+      return "Loading...";
+    default:
+      const _exhaustive: never = state; // Compiler error if cases missing
+      throw new Error("Unhandled state");
+  }
+}
+```
+
+### 3. Validation Workflow
+
+**Always validate external data with runtime checks:**
+
+1. **Simple validation:** Type guards
+2. **Complex validation:** Schema libraries (Zod, Yup)
+
+```typescript
+// Type guard pattern
+function isUser(data: unknown): data is User {
+  return (
+    typeof data === "object" &&
+    data !== null &&
+    "id" in data &&
+    typeof (data as any).id === "number"
+  );
+}
+
+// Schema validation (preferred for APIs)
+import { z } from "zod";
+
+const UserSchema = z.object({
+  id: z.number(),
+  name: z.string(),
+  email: z.string().email(),
+});
+
+type User = z.infer<typeof UserSchema>;
+const user = UserSchema.parse(apiData); // Runtime validation + types
+```
+
+**Never use type assertions without validation:**
+
+```typescript
+// ❌ BAD: No runtime check
+const user = data as User;
+
+// ✅ GOOD: Validated first
+if (isUser(data)) {
+  // data is User here
+}
+```
+
+### 4. Configuration Checklist
+
+For new projects, enable strict mode plus:
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "moduleResolution": "bundler"
+  }
+}
+```
+
+**Why these matter:**
+
+- `noUncheckedIndexedAccess` - Prevents undefined access bugs
+- `exactOptionalPropertyTypes` - Distinguishes missing from undefined
+- `moduleResolution: "bundler"` - Optimized for Vite/esbuild
+
+### 5. Code Organization Rules
+
+**Barrel files:** Avoid for internal code (75% faster builds)
+
+```typescript
+// ❌ BAD: Internal barrel
+// src/components/index.ts
+export * from "./Button";
+
+// ✅ GOOD: Direct imports + path aliases
+// tsconfig.json: "paths": { "@/components/*": ["src/components/*"] }
+import { Button } from "@/components/Button";
+```
+
+**Only use barrel files for:**
+
+- Library entry points
+- Public APIs
+- Small modules (<10 exports)
+
+## Quick Reference Patterns
+
+### Utility Types
+
+```typescript
+type UserPreview = Pick<User, "id" | "name">; // Extract subset
+type PublicUser = Omit<User, "email">; // Remove fields
+type UpdateDto = Partial<User>; // Make optional
+type CompleteUser = Required<User>; // Make required
+type ImmutableUser = Readonly<User>; // Make readonly
+type UserType = ReturnType<typeof getUser>; // Extract return type
+```
+
+### Error Handling
+
+```typescript
+// Catch with unknown
+try {
+} catch (err: unknown) {
+  if (err instanceof Error) {
+    /* ... */
+  }
+}
+
+// Result types for expected failures
+type Result<T, E = Error> =
+  | { success: true; value: T }
+  | { success: false; error: E };
+```
+
+### Readonly Patterns
+
+```typescript
+const config: Readonly<Config> = {
+  /* ... */
+};
+const numbers: readonly number[] = [1, 2, 3];
+const ROUTES = { home: "/" } as const; // Deep readonly + literal types
+```
+
+## When to Consult Detailed References
+
+For comprehensive information on advanced patterns, configuration options, or specific features, read:
+
+- `references/best-practices-2025.md` - Full TypeScript best practices guide
+
+The reference includes:
+
+- Advanced type patterns (conditional types, mapped types, branded types)
+- Complete tsconfig.json options
+- Modern features (decorators, const type parameters)
+- Common anti-patterns and solutions
+
+## Quality Checklist
+
+Before completing TypeScript code:
+
+- [ ] External data validated (not just typed)
+- [ ] No `any` types (or explicitly justified)
+- [ ] State machines use discriminated unions
+- [ ] Utility types used where applicable
+- [ ] Readonly applied to prevent mutations
+- [ ] Exhaustiveness checks with `never`