@wangs-ui/skills 1.3.0-alpha.11 → 1.3.0-alpha.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wangs-ui/skills",
-  "version": "1.3.0-alpha.11",
+  "version": "1.3.0-alpha.12",
   "description": "CLI to install, update, and manage modular AI agent skills for Wangs UI React applications",
   "keywords": [
     "agents",
@@ -29,7 +29,8 @@
   },
   "files": [
     "dist",
-    "skills"
+    "skills",
+    "rules"
   ],
   "type": "module",
   "sideEffects": false,

package/rules/react19-checklist-and-reference.md

@@ -0,0 +1,37 @@
+---
+trigger: model_decision
+description: "Apply when doing a final review pass on React 19 component or hook code for compiler-optimization compliance."
+owner: wangs-ui
+metadata:
+  owner: wangs-ui
+---
+# Rule: React 19 — Review Checklist & Quick Reference
+
+## Checking Compiler Optimization
+
+- **React DevTools** — an optimized component shows a "Memo ✨" badge next to its name in the component tree.
+- **ESLint / Oxlint** — compiler's recommended rules flag Rules-of-React violations at lint time.
+
+## Review Checklist
+
+- [ ] Compiler confirmed active ("Memo ✨" badge) before removing any _existing_ manual memoization
+- [ ] No new `useMemo`/`useCallback`/`React.memo` added without documented reason (confirmed bail-out, or external boundary)
+- [ ] No prop/state/context mutation anywhere in render
+- [ ] All hooks called unconditionally at top level, same order every render
+- [ ] Side effects live in `useEffect`/event handlers, never during render
+- [ ] Components are `PascalCase`; hooks are `camelCase` and prefixed `use`
+- [ ] `ref` accepted as normal prop instead of `forwardRef`
+- [ ] Action/optimistic-update state modeled as discriminated union, not optional fields
+- [ ] Mutually exclusive prop combinations modeled as discriminated union `Props` type
+- [ ] Any `"use no memo"` usage has a comment explaining why
+
+## Quick Reference
+
+| Situation                                                   | Do                                                            |
+| ----------------------------------------------------------- | ------------------------------------------------------------- |
+| Tempted to write `useMemo`/`useCallback`                    | Don't — write plain expression, let compiler decide           |
+| Need a ref on a function component                          | Accept `ref` as a prop, skip `forwardRef`                     |
+| Form/async state with distinct outcomes                     | Discriminated union via `useActionState`, not optional fields |
+| Callback needs latest props/state without re-running effect | `useEffectEvent`                                              |
+| A hook/library is known-incompatible with compiler          | `"use no memo"` at top of that function, with comment         |
+| Checking if optimization is happening                       | React DevTools "Memo ✨" badge + compiler lint rules          |

package/rules/react19-compiler-render-patterns.md

@@ -0,0 +1,13 @@
+---
+trigger: model_decision
+description: "Apply when writing or reviewing render logic in a React 19 component."
+owner: wangs-ui
+metadata:
+  owner: wangs-ui
+---
+# Rule: React 19 — Compiler-Friendly Render Patterns
+
+- Creating new object/array/function literals inline in render (`style={{ color }}`, `onClick={() => ...}`) is fine — stop manually hoisting or `useMemo`-wrapping these preemptively; the compiler memoizes them if it determines it's worthwhile.
+- Avoid module-level mutable variables read or written during render — that state is invisible to the compiler and breaks idempotence.
+- Don't use `useRef` to store a value that should trigger a re-render when it changes — refs are an imperative escape hatch, not state, and the compiler treats them as such.
+- Keep components small and composable. The compiler optimizes per component/hook boundary, so a single 300-line component gives it far less to work with than several focused ones.

package/rules/react19-naming-conventions.md

@@ -0,0 +1,16 @@
+---
+trigger: model_decision
+description: "Apply when naming a React 19 component, hook, or prop."
+owner: wangs-ui
+metadata:
+  owner: wangs-ui
+---
+# Rule: React 19 — Naming Conventions
+
+The compiler identifies what to optimize by naming heuristics, same as the Rules of Hooks linter:
+
+| Kind                                                                     | Convention                      | Notes                                                                         |
+| ------------------------------------------------------------------------ | ------------------------------- | ----------------------------------------------------------------------------- |
+| Components                                                               | `PascalCase`, returns JSX       | Compiler treats it as a component to optimize                                 |
+| Custom hooks                                                             | `camelCase`, prefixed `use`     | Required for both Rules-of-Hooks lint and compiler analysis                   |
+| Plain helper functions that return JSX-like values but aren't components | Avoid `PascalCase`/`use` naming | Prevents the compiler (and other devs) from mistaking it for a component/hook |

package/rules/react19-no-manual-memoization.md

@@ -0,0 +1,26 @@
+---
+trigger: model_decision
+description: "Apply when writing or reviewing a React 19 component or hook that uses or is tempted to use useMemo/useCallback/React.memo."
+owner: wangs-ui
+metadata:
+  owner: wangs-ui
+---
+# Rule: React 19 — Stop Hand-Rolling Memoization
+
+Don't reach for `useMemo`, `useCallback`, or `React.memo` by default — the compiler adds this automatically wherever it determines it helps.
+
+```tsx
+// ❌ Old habit — noisy, and a mismatched dependency array is a whole class of bugs
+const filteredUsers = useMemo(() => users.filter((u) => u.isActive), [users]);
+const handleClick = useCallback(() => onSelect(user.id), [onSelect, user.id]);
+
+// ✅ New default — just write the logic; the compiler memoizes what's worth memoizing
+const filteredUsers = users.filter((u) => u.isActive);
+const handleClick = () => onSelect(user.id);
+```
+
+## When manual memoization is still justified:
+
+- You've **confirmed a compiler bail-out** on a genuine hot path via profiling, and fixing the underlying Rules-of-React violation isn't possible right now.
+- A value must have **stable referential identity across a boundary the compiler can't see** — e.g. passed into a non-React library, a WebSocket subscription, or a third-party hook incompatible with the compiler (`react-hook-form`'s `useForm`, `@tanstack/react-table`'s `useReactTable` are known cases).
+- Keep any manual memoization it produces isolated and commented with _why_, so it doesn't silently rot into a bail-out later when the code around it changes.

package/rules/react19-primitives-typing.md

@@ -0,0 +1,85 @@
+---
+trigger: model_decision
+description: "Apply when typing React 19 primitives — ref props, useActionState, useOptimistic, use(), useEffectEvent."
+owner: wangs-ui
+metadata:
+  owner: wangs-ui
+---
+# Rule: React 19 — Typing React 19 Primitives
+
+## `ref` as a Normal Prop
+
+`forwardRef` is no longer required for most cases; function components accept `ref` directly.
+
+```tsx
+type InputProps = {
+  ref?: React.Ref<HTMLInputElement>;
+  placeholder?: string;
+};
+
+function TextInput({ ref, placeholder }: InputProps) {
+  return <input ref={ref} placeholder={placeholder} />;
+}
+```
+
+## Actions with `useActionState`
+
+Type the state and payload as generics; model the result as a discriminated union rather than optional fields.
+
+```tsx
+type FormState = { status: 'idle' } | { status: 'error'; message: string } | { status: 'success' };
+
+const [state, formAction, isPending] = useActionState<FormState, FormData>(
+  async (_previous, formData) => {
+    const email = formData.get('email');
+    if (typeof email !== 'string' || !email.includes('@')) {
+      return { status: 'error', message: 'Invalid email' };
+    }
+    await submit(email);
+    return { status: 'success' };
+  },
+  { status: 'idle' },
+);
+```
+
+## Optimistic Updates with `useOptimistic`
+
+Type both the state and the update shape.
+
+```tsx
+const [optimisticTodos, addOptimisticTodo] = useOptimistic<Todo[], Todo>(
+  todos,
+  (state, newTodo) => [...state, newTodo],
+);
+```
+
+## Reading Promises or Context with `use()`
+
+Type the resolved value, not the promise wrapper; `use()` is not a hook and may be called conditionally.
+
+```tsx
+function Comments({ commentsPromise }: { commentsPromise: Promise<Comment[]> }) {
+  const comments = use(commentsPromise); // suspends until resolved
+  return (
+    <ul>
+      {comments.map((c) => (
+        <li key={c.id}>{c.text}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+## Stable Event Callbacks with `useEffectEvent` (React 19.2+)
+
+Separates "event" logic from "reactive" effect logic so the callback always sees latest props/state without being listed as an effect dependency.
+
+```tsx
+const onVisit = useEffectEvent((url: string) => {
+  logVisit(url, theme); // always fresh `theme`, never re-triggers the effect
+});
+
+useEffect(() => {
+  onVisit(url);
+}, [url]); // `theme` intentionally omitted — onVisit is stable
+```

package/rules/react19-props-typing.md

@@ -0,0 +1,25 @@
+---
+trigger: model_decision
+description: "Apply when defining a component's Props type or interface."
+owner: wangs-ui
+metadata:
+  owner: wangs-ui
+---
+# Rule: React 19 — Typing Props
+
+- `interface` for a component's `Props` — it's an entity shape, often extended.
+- A discriminated union when a component has mutually exclusive prop combinations, instead of a pile of optional props that can contradict each other.
+
+```tsx
+// ❌ Bad — nothing stops passing both `href` and `onClick` incoherently
+interface ButtonProps {
+  label: string;
+  href?: string;
+  onClick?: () => void;
+}
+
+// ✅ Good — the two variants can't be mixed
+type ButtonProps =
+  | { variant: 'link'; label: string; href: string }
+  | { variant: 'action'; label: string; onClick: () => void };
+```

package/rules/react19-purity-and-immutability.md

@@ -0,0 +1,41 @@
+---
+trigger: model_decision
+description: "Apply when writing or reviewing a React 19 component or hook body for purity and immutability."
+owner: wangs-ui
+metadata:
+  owner: wangs-ui
+---
+# Rule: React 19 — Purity and Immutability (Load-Bearing)
+
+The compiler assumes your components and hooks are pure. Violating these rules causes the compiler to silently skip optimizing that component:
+
+- **Idempotent renders** — given the same props/state/context, a component must return the same output. No random values, no `Date.now()`, no side effects during render.
+- **Immutability** — never mutate props, state, or context directly. Always create new objects/arrays for changes.
+- **Side effects only in effects or event handlers** — never during render.
+- **Hooks called unconditionally, top-level, same order every render** — no hooks inside conditionals, loops, or nested functions.
+
+```tsx
+// ❌ Mutates a prop — breaks purity and the compiler can't safely memoize this
+function TodoList({ todos }: { todos: Todo[] }) {
+  todos.sort((a, b) => a.priority - b.priority); // mutates caller's array
+  return (
+    <ul>
+      {todos.map((t) => (
+        <li key={t.id}>{t.title}</li>
+      ))}
+    </ul>
+  );
+}
+
+// ✅ Creates a new array — pure, compiler-safe
+function TodoList({ todos }: { todos: Todo[] }) {
+  const sorted = [...todos].sort((a, b) => a.priority - b.priority);
+  return (
+    <ul>
+      {sorted.map((t) => (
+        <li key={t.id}>{t.title}</li>
+      ))}
+    </ul>
+  );
+}
+```

package/rules/react19-tooling-and-opt-out.md

@@ -0,0 +1,68 @@
+---
+trigger: model_decision
+description: 'Apply when configuring React Compiler tooling or opting a component out via "use no memo".'
+owner: wangs-ui
+metadata:
+  owner: wangs-ui
+---
+# Rule: React 19 — Tooling Setup & Compiler Opt-Out
+
+## Tooling Setup
+
+**The compiler is opt-in — no default setup enables it automatically.** Plain `@vitejs/plugin-react` (`react()`), plain Next.js, plain Babel/webpack config, etc. do **not** run the compiler on their own. Verify it's actually wired up before assuming manual memoization can be dropped.
+
+```bash
+# Compiler (build-time transform)
+npm install --save-dev --save-exact babel-plugin-react-compiler@latest
+```
+
+### Lint rules — oxlint
+
+Oxlint ships a **native, Rust-based** `react/react-compiler` rule:
+
+```json
+// .oxlintrc.json
+{
+  "plugins": ["react"],
+  "rules": {
+    "react/react-compiler": "error"
+  }
+}
+```
+
+This single rule reports:
+
+- **Rules-of-React violations** (conditional hooks, reading a ref during render, mutating props) — must-fix bugs.
+- **Compiler bail-outs** — places compiler declined to optimize without rule violation.
+
+### Wiring into Vite 8
+
+```js
+// vite.config.js
+import { defineConfig } from 'vite';
+import react, { reactCompilerPreset } from '@vitejs/plugin-react';
+import babel from '@rolldown/plugin-babel';
+
+export default defineConfig({
+  plugins: [
+    babel({ presets: [reactCompilerPreset()] }), // must run before react()
+    react(),
+  ],
+});
+```
+
+```bash
+npm install --save-dev @rolldown/plugin-babel @babel/core babel-plugin-react-compiler
+```
+
+## Incompatibility Escape Hatch (`"use no memo"`)
+
+If a specific function is genuinely incompatible with compiler (e.g. calls `useForm` from `react-hook-form`), opt out with `"use no memo"` directive as **first line of function body** — leave a comment explaining why:
+
+```tsx
+function LegacyForm() {
+  'use no memo';
+  const form = useForm(); // incompatible with the compiler today
+  // ...
+}
+```

package/rules/typescript-assertions-last-resort.md

@@ -0,0 +1,13 @@
+---
+trigger: model_decision
+description: "Apply when writing or reviewing a type assertion (`as X`) or non-null assertion (`x!`)."
+owner: wangs-ui
+metadata:
+  owner: wangs-ui
+---
+# Rule: TypeScript — Type Assertions & Non-Null Assertions are a Last Resort
+
+- `as X` and `x!` tell the compiler "trust me" — they produce zero runtime safety and actively hide bugs if wrong.
+- Acceptable only when the compiler genuinely cannot know something you do (e.g. a DOM query you've already null-checked, or narrowing a third-party type at a well-tested boundary) — and even then, prefer a type guard or a runtime check over a bare assertion.
+- Never use `as any` or `as unknown as X` to force an incompatible cast — that's `any` wearing a disguise.
+- `x!` should almost always be replaceable by an actual null check or optional chaining (`x?.y`) plus a real fallback.

package/rules/typescript-checklist-and-reference.md

@@ -0,0 +1,34 @@
+---
+trigger: model_decision
+description: "Apply when doing a final TypeScript review pass on a file."
+owner: wangs-ui
+metadata:
+  owner: wangs-ui
+---
+# Rule: TypeScript — Review Checklist & Quick Reference
+
+## Review Checklist
+
+Before considering TypeScript code "done," verify:
+
+- [ ] No `any` anywhere (including implicit `any` from missing annotations)
+- [ ] External/uncertain data enters as `unknown` and is narrowed before use
+- [ ] Variant state is a discriminated union, not optional fields + booleans
+- [ ] `interface` used for object/entity shapes; `type` used for unions/aliases/intersections
+- [ ] No stray `I` prefixes on interfaces
+- [ ] Naming follows casing conventions consistently
+- [ ] `as` / `!` are rare, justified, and can't be replaced by a guard or null check
+- [ ] Exported functions/methods have explicit return types
+- [ ] Switch statements over unions have an exhaustiveness (`never`) check
+- [ ] `tsconfig.json` includes the strictness baseline
+
+## Quick Reference
+
+| Situation                                      | Use                                                           |
+| ---------------------------------------------- | ------------------------------------------------------------- |
+| External/uncertain data                        | `unknown` + narrowing                                         |
+| "This value is definitely one of these shapes" | Discriminated union (`type`)                                  |
+| Object with identity, may be extended          | `interface`                                                   |
+| Union, intersection, tuple, mapped type        | `type`                                                        |
+| Need to prove a type through logic             | Type guard / narrowing                                        |
+| Tempted to write `any`                         | Stop — use `unknown`, a generic, or a local interface instead |

package/rules/typescript-discriminated-unions.md

@@ -0,0 +1,40 @@
+---
+trigger: model_decision
+description: "Apply when modeling a variant or multi-shape state in TypeScript."
+owner: wangs-ui
+metadata:
+  owner: wangs-ui
+---
+# Rule: TypeScript — Discriminated Unions for Variant State
+
+Whenever a value can be one of several distinct "shapes" (loading/success/error states, event types, API response variants), model it as a **discriminated union** with a literal tag field — never as a loose object with optional fields or boolean flags.
+
+```ts
+// ❌ Bad — booleans can contradict each other; unclear which fields are valid together
+interface FetchState {
+  isLoading: boolean;
+  isError: boolean;
+  data?: User;
+  error?: string;
+}
+
+// ✅ Good — only one shape is possible at a time, and the compiler enforces it
+type FetchState =
+  | { status: 'idle' }
+  | { status: 'loading' }
+  | { status: 'success'; data: User }
+  | { status: 'error'; error: string };
+
+function render(state: FetchState) {
+  switch (state.status) {
+    case 'success':
+      return state.data.name; // `data` is guaranteed to exist here
+    case 'error':
+      return state.error; // `error` is guaranteed to exist here
+    default:
+      return null;
+  }
+}
+```
+
+Use a consistent tag field name across a codebase (`kind`, `type`, or `status` — pick one and stick with it) so narrowing patterns stay predictable.

package/rules/typescript-explicit-return-types.md

@@ -0,0 +1,22 @@
+---
+trigger: model_decision
+description: "Apply when writing or reviewing an exported function, class method, or public API surface in TypeScript."
+owner: wangs-ui
+metadata:
+  owner: wangs-ui
+---
+# Rule: TypeScript — Explicit Return Types on Exported Functions
+
+Inference is fine for local, private helpers, but exported functions, class methods, and anything forming a public API should declare an explicit return type. This prevents an internal implementation change from silently widening/narrowing the public contract.
+
+```ts
+// ❌ Return type is inferred and can silently drift
+export function getActiveUsers(users: User[]) {
+  return users.filter((u) => u.active);
+}
+
+// ✅ Explicit, intentional contract
+export function getActiveUsers(users: User[]): User[] {
+  return users.filter((u) => u.active);
+}
+```

package/rules/typescript-interface-vs-type.md

@@ -0,0 +1,40 @@
+---
+trigger: model_decision
+description: "Apply when deciding between `interface` and `type` for a new TypeScript declaration."
+owner: wangs-ui
+metadata:
+  owner: wangs-ui
+---
+# Rule: TypeScript — `interface` vs `type`
+
+Both can describe object shapes, but they signal different intent. Default rule:
+
+| Use `interface` for...                                                     | Use `type` for...                                                          |
+| -------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| Object / entity shapes (a `User`, a `Product`, a component's `Props`)      | Unions (`"a" \| "b"`) and discriminated unions                             |
+| Public API contracts meant to be `implements`-ed by classes                | Intersections (`A & B`)                                                    |
+| Shapes that consumers may want to **extend/augment** (declaration merging) | Tuples (`[string, number]`)                                                |
+|                                                                            | Function types / callback signatures                                       |
+|                                                                            | Mapped, conditional, or utility-derived types (`Partial<T>`, `Pick<T, K>`) |
+|                                                                            | Aliasing a primitive or another type for readability                       |
+
+```ts
+// ✅ interface — an entity with identity, extendable
+interface User {
+  id: string;
+  email: string;
+  role: UserRole;
+}
+
+interface AdminUser extends User {
+  permissions: Permission[];
+}
+
+// ✅ type — union, alias, derived shape
+type UserRole = 'admin' | 'editor' | 'viewer';
+type UserId = User['id'];
+type PartialUser = Partial<User>;
+type Callback<T> = (value: T) => void;
+```
+
+Don't mix conventions arbitrarily within one file — if a shape is a plain data object that will never need a union/intersection, `interface` is the default; the moment it needs to express "one of several shapes," reach for `type`.

package/rules/typescript-literal-unions-vs-enums.md

@@ -0,0 +1,22 @@
+---
+trigger: model_decision
+description: "Apply when modeling a fixed set of string or numeric variants in TypeScript."
+owner: wangs-ui
+metadata:
+  owner: wangs-ui
+---
+# Rule: TypeScript — Prefer Literal Unions Over Numeric Enums
+
+String literal unions are simpler, tree-shake better, and produce clearer error messages than TypeScript `enum`. Reserve `enum` (or `as const` object maps) for cases that need reverse lookup or genuinely benefit from a namespaced runtime value.
+
+```ts
+// ✅ Preferred
+type OrderStatus = 'pending' | 'shipped' | 'delivered' | 'cancelled';
+
+// Acceptable when a namespaced runtime object is actually needed
+const OrderStatus = {
+  Pending: 'pending',
+  Shipped: 'shipped',
+} as const;
+type OrderStatus = (typeof OrderStatus)[keyof typeof OrderStatus];
+```

package/rules/typescript-naming-conventions.md

@@ -0,0 +1,24 @@
+---
+trigger: model_decision
+description: "Apply when naming a TypeScript type, variable, or constant."
+owner: wangs-ui
+metadata:
+  owner: wangs-ui
+---
+# Rule: TypeScript — Naming Conventions
+
+| Kind                                                       | Convention                                  | Example                             |
+| ---------------------------------------------------------- | ------------------------------------------- | ----------------------------------- |
+| Types, interfaces, classes, enums                          | `PascalCase`                                | `UserProfile`, `OrderStatus`        |
+| Interfaces                                                 | `PascalCase`, **no `I` prefix**             | `User`, not `IUser`                 |
+| Type aliases                                               | `PascalCase`                                | `type ApiResponse<T> = ...`         |
+| Variables, functions, methods, properties                  | `camelCase`                                 | `getUserById`, `isValid`            |
+| Booleans                                                   | `camelCase` with `is/has/should/can` prefix | `isLoading`, `hasPermission`        |
+| True constants (module-level, never reassigned, primitive) | `UPPER_SNAKE_CASE`                          | `MAX_RETRIES`, `DEFAULT_TIMEOUT_MS` |
+| Enum members                                               | `PascalCase`                                | `enum Status { Active, Archived }`  |
+| Generic type parameters (simple, single-purpose)           | Single uppercase letter                     | `T`, `K`, `V`, `E` for errors       |
+| Generic type parameters (multiple / non-obvious)           | Descriptive, prefixed with `T`              | `TInput`, `TOutput`, `TContext`     |
+| Discriminated union tag field                              | Consistent across the codebase              | `kind`, `type`, or `status`         |
+| Files with a single exported entity                        | Match the entity name                       | `UserProfile.ts`, `useAuth.ts`      |
+
+Naming should describe **intent**, not implementation — `fetchUser` not `getUserFromApiEndpoint`; `retryCount` not `numRetries2`.

package/rules/typescript-narrowing-over-casting.md

@@ -0,0 +1,44 @@
+---
+trigger: model_decision
+description: "Apply when narrowing an `unknown` or union-typed value in TypeScript."
+owner: wangs-ui
+metadata:
+  owner: wangs-ui
+---
+# Rule: TypeScript — `unknown` + Narrowing, Not Casting
+
+Prefer proving a type through control flow over asserting it with `as`.
+
+## Narrowing techniques, in order of preference:
+
+1. **`typeof`** — primitives (`string`, `number`, `boolean`, `undefined`, `function`)
+2. **`instanceof`** — class instances, `Error`, `Date`, custom classes
+3. **`in`** — checking a property exists before accessing it on a union/unknown
+4. **User-defined type guards** — `function isUser(x: unknown): x is User`
+5. **Discriminated union tag checks** — `switch (value.kind) { ... }`
+6. **Exhaustiveness checks** — a `never`-typed default branch so adding a new variant is a compile error until every switch/if-chain handles it
+
+```ts
+// ✅ Type guard
+function isUser(value: unknown): value is User {
+  return typeof value === 'object' && value !== null && 'id' in value && 'email' in value;
+}
+
+// ✅ Exhaustiveness check
+function assertNever(x: never): never {
+  throw new Error(`Unhandled case: ${JSON.stringify(x)}`);
+}
+
+function area(shape: Shape): number {
+  switch (shape.kind) {
+    case 'circle':
+      return Math.PI * shape.radius ** 2;
+    case 'square':
+      return shape.side ** 2;
+    default:
+      return assertNever(shape); // compile error if a variant is missed
+  }
+}
+```
+
+Type assertions (`as X`) and the non-null assertion (`!`) bypass this entirely — treat them as a last resort, not a shortcut.

package/rules/typescript-readonly-by-default.md

@@ -0,0 +1,24 @@
+---
+trigger: model_decision
+description: "Apply when declaring a TypeScript collection or object shape."
+owner: wangs-ui
+metadata:
+  owner: wangs-ui
+---
+# Rule: TypeScript — Readonly by Default
+
+Prefer immutable shapes unless mutation is intentional and localized.
+
+```ts
+interface Point {
+  readonly x: number;
+  readonly y: number;
+}
+
+function config(values: readonly string[]) {
+  /* ... */
+}
+
+const ROLES = ['admin', 'editor', 'viewer'] as const;
+type UserRole = (typeof ROLES)[number];
+```

package/rules/typescript-tsconfig-strictness.md

@@ -0,0 +1,31 @@
+---
+trigger: model_decision
+description: "Apply when configuring or reviewing tsconfig.json compiler strictness options."
+owner: wangs-ui
+metadata:
+  owner: wangs-ui
+---
+# Rule: TypeScript — Baseline `tsconfig.json` Strictness
+
+Treat these as the non-negotiable floor for any project this rule touches:
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "strictPropertyInitialization": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "forceConsistentCasingInFileNames": true
+  }
+}
+```
+
+`strict: true` alone enables the core group (`noImplicitAny`, `strictNullChecks`, etc.), but `noUncheckedIndexedAccess` and `exactOptionalPropertyTypes` are commonly missed and close real gaps (array/object index access returning `T` instead of `T | undefined`; optional properties silently accepting `undefined` as an explicit value).