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

package/README.md

@@ -1,27 +1,33 @@
 # @wangs-ui/skills
 
-Modular AI agent skills installer and manager for **Wangs UI** React components and design patterns.
+Modular AI agent skills and guardrail rules installer and manager for **Wangs UI** React components and design patterns.
 
-Skills are standalone: they work in any Storybook or React project without requiring project scaffolding tools. They pair with [`@wangs-ui/mcp`](../mcp/README.md), which supplies the live component catalog, typed APIs, and story implementations the skills tell agents to verify against.
+Skills and rules are standalone: they work in any Storybook or React project without requiring project scaffolding tools. They pair with [`@wangs-ui/mcp`](../mcp/README.md), which supplies the live component catalog, typed APIs, and story implementations the skills tell agents to verify against.
 
 ---
 
 ## ⚡ Quick Start
 
 ```bash
-# List available skills
+# List available skills & rules
 npx @wangs-ui/skills list
 
-# Install skills (opens interactive multiselect menu with skill descriptions)
+# Interactive installer (select skills and rules via multiselect menu)
 npx @wangs-ui/skills add
 
+# Install all rules (Wangs UI invariants, React 19 compiler-first, TypeScript strict)
+npx @wangs-ui/skills add --rules
+
 # Install specific skills directly by name
 npx @wangs-ui/skills add wangs-ui-components data-table create-form
 
-# Update installed skills
+# Install specific rules directly by name
+npx @wangs-ui/skills add forms-destructuring-lock no-raw-html
+
+# Update installed skills and rules
 npx @wangs-ui/skills update
 
-# Remove a skill
+# Remove a skill or rule
 npx @wangs-ui/skills remove create-form
 ```
 
@@ -29,7 +35,8 @@ npx @wangs-ui/skills remove create-form
 
 ## 🛠️ Features
 
-- **Modular UI Skills**: Installs specialized guidelines, component patterns, and rules into your AI agent environment.
+- **Procedural Skills**: Installs specialized step-by-step guidelines and workflows into your agent environment (`.agents/skills/`, `.claude/skills/`, etc.).
+- **Declarative Guardrail Rules**: Installs high-signal invariants and pitfalls (`.agents/rules/`, `.claude/rules/`) covering Wangs UI core facts, React 19 compiler patterns, and strict TypeScript discipline.
 - **MCP-Verified Guidance**: Skills mandate querying the MCP server for live contracts instead of hardcoding props, so guidance never drifts from the installed package version.
 - **Cross-Platform & Multi-Agent**: Supports Antigravity IDE, Claude Code, OpenCode, Kilo, and universal agent directories on Mac and Windows.
 - **Independent Usage**: Works in any Storybook or React project without requiring project scaffolding tools.

package/dist/bin.js

@@ -1,21 +1,22 @@
 #!/usr/bin/env node
-import { i as listSkills, n as updateSkills, r as addSkills, t as removeSkills } from "./src-BzJg2A5l.js";
+import { i as listSkills, n as updateSkills, r as addSkills, t as removeSkills } from "./src-DwQOnl9b.js";
 import path from "node:path";
 import { parseArgs } from "node:util";
 //#region bin.ts
+var VERSION = "1.3.0-alpha.11";
 var HELP_TEXT = `
-\x1b[1m\x1b[36m🚀 Wangs UI Skills CLI\x1b[0m
-Install, update, and manage modular AI agent skills for Wangs UI React applications.
+\x1b[1m\x1b[36m🚀 Wangs UI Skills & Rules CLI\x1b[0m
+Install, update, and manage modular AI agent skills and rules for Wangs UI React applications.
 
 \x1b[1mUsage:\x1b[0m
   npx @wangs-ui/skills [command] [options]
   wangs-ui-skills [command] [options]
 
 \x1b[1mCommands:\x1b[0m
-  \x1b[36mlist\x1b[0m                      List all available and installed skills
-  \x1b[36madd\x1b[0m [skills...]           Install specified skills (interactive if none provided)
-  \x1b[36mupdate\x1b[0m [skills...]        Update installed skills to latest versions
-  \x1b[36mremove\x1b[0m <skills...>        Remove specified skills from agent environment
+  \x1b[36mlist\x1b[0m                      List all available and installed skills & rules
+  \x1b[36madd\x1b[0m [items...]            Install specified skills or rules (interactive if none provided)
+  \x1b[36mupdate\x1b[0m [items...]         Update installed skills and rules to latest versions
+  \x1b[36mremove\x1b[0m <items...>         Remove specified skills or rules from agent environment
 
 \x1b[1mOptions:\x1b[0m
   --target <dir>            Target directory (default: current working directory)
@@ -24,8 +25,9 @@ Install, update, and manage modular AI agent skills for Wangs UI React applicati
 
 \x1b[1mExamples:\x1b[0m
   npx @wangs-ui/skills list
-  npx @wangs-ui/skills add create-form
-  npx @wangs-ui/skills add wangs-ui-components data-table dialog-modal
+  npx @wangs-ui/skills add --rules
+  npx @wangs-ui/skills add forms-destructuring-lock
+  npx @wangs-ui/skills add create-form data-table
   npx @wangs-ui/skills update
   npx @wangs-ui/skills remove create-form
 `;
@@ -36,7 +38,7 @@ async function main() {
 		return;
 	}
 	if (args.includes("--version") || args.includes("-v")) {
-		console.log("1.0.0");
+		console.log(VERSION);
 		return;
 	}
 	const parsed = parseArgs({
@@ -45,10 +47,13 @@ async function main() {
 		allowPositionals: true,
 		strict: false
 	});
-	const baseDir = parsed.values.target ? path.resolve(parsed.values.target) : process.cwd();
+	const targetVal = parsed.values.target;
+	const baseDir = typeof targetVal === "string" ? path.resolve(targetVal) : process.cwd();
 	const { positionals } = parsed;
 	const command = positionals[0] || "list";
-	const skillArgs = positionals.slice(1);
+	const itemArgs = positionals.slice(1);
+	if (args.includes("--rules")) itemArgs.push("--rules");
+	if (args.includes("--skills")) itemArgs.push("--skills");
 	switch (command) {
 		case "list":
 		case "ls":
@@ -57,16 +62,16 @@ async function main() {
 		case "add":
 		case "install":
 		case "i":
-			await addSkills(skillArgs, baseDir);
+			await addSkills(itemArgs, baseDir);
 			break;
 		case "update":
 		case "up":
-			updateSkills(skillArgs, baseDir);
+			updateSkills(itemArgs, baseDir);
 			break;
 		case "remove":
 		case "rm":
 		case "delete":
-			removeSkills(skillArgs, baseDir);
+			removeSkills(itemArgs, baseDir);
 			break;
 		default:
 			console.log(`\x1b[31mUnknown command: "${command}"\x1b[0m`);

package/dist/index.js

@@ -1,2 +1,2 @@
-import { a as getAgentSkillDirs, c as isSkillInstalled, d as loadAllSkills, i as listSkills, l as removeSkill, n as updateSkills, o as getInstalledSkills, r as addSkills, s as installSkill, t as removeSkills, u as getSkill } from "./src-BzJg2A5l.js";
-export { addSkills, getAgentSkillDirs, getInstalledSkills, getSkill, installSkill, isSkillInstalled, listSkills, loadAllSkills, removeSkill, removeSkills, updateSkills };
+import { _ as loadAllRules, a as getAgentRuleDirs, c as getInstalledSkills, d as isRuleInstalled, f as isSkillInstalled, g as getSkill, h as getRule, i as listSkills, l as installRule, m as removeSkill, n as updateSkills, o as getAgentSkillDirs, p as removeRule, r as addSkills, s as getInstalledRules, t as removeSkills, u as installSkill, v as loadAllSkills } from "./src-DwQOnl9b.js";
+export { addSkills, getAgentRuleDirs, getAgentSkillDirs, getInstalledRules, getInstalledSkills, getRule, getSkill, installRule, installSkill, isRuleInstalled, isSkillInstalled, listSkills, loadAllRules, loadAllSkills, removeRule, removeSkill, removeSkills, updateSkills };

package/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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];
+```