contextos-agents 1.5.0

package/.agents/generated/claude/skills/typescript/SKILL.md

@@ -0,0 +1,192 @@
+# TypeScript
+
+## Overview
+
+Strict TypeScript engineering standard. Enforces noImplicitAny, discriminated unions, branded types, immutability, exhaustive switch checks, and zero unsafe any or as unknown as T casts.
+
+## When to Use
+
+Activate on all TypeScript and JavaScript codebases to ensure compile-time type safety, robust domain modeling, and foolproof function contracts.
+
+## Negative Constraints (What NOT to Do)
+
+1. **NEVER use `any`**: Use `unknown` with type guards, discriminated unions, or Zod schemas.
+2. **NEVER use type assertions (`as Type` or `as unknown as Type`) to bypass safety**: Fix the underlying type signature or use runtime narrowing (`instanceof`, `typeof`, `in`).
+3. **NEVER use non-null assertions (`foo!.bar`)**: Handle `null` and `undefined` with optional chaining (`?.`) or explicit error guards.
+4. **NEVER export mutable global arrays or object constants**: Always mark constant objects and arrays with `as const` and `readonly`.
+5. **NEVER omit explicit return types on exported functions**: Exported public APIs must declare explicit return types to protect consumers.
+
+## Rules & Patterns
+
+## Strict Mode
+
+Always use strict TypeScript configuration:
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true
+  }
+}
+```
+
+## Types
+
+- **Prefer `interface`** for object shapes, `type` for unions/intersections
+- **No `any`** — use `unknown` if type is truly unknown, then narrow
+- **Explicit return types** for exported functions
+- **Const assertions** — `as const` for literal types
+
+```typescript
+// Good
+interface User {
+  id: string;
+  name: string;
+  role: 'admin' | 'user';
+}
+
+// Unions
+type Result<T> = { ok: true; data: T } | { ok: false; error: string };
+```
+
+## Utility Types
+
+- `Partial<T>` — all properties optional
+- `Required<T>` — all properties required
+- `Pick<T, K>` — select specific properties
+- `Omit<T, K>` — remove specific properties
+- `Record<K, V>` — key-value map
+
+## Type Guards
+
+```typescript
+function isUser(value: unknown): value is User {
+  return typeof value === 'object' && value !== null && 'id' in value;
+}
+```
+
+## Generic Patterns
+
+```typescript
+// Repository pattern
+interface Repository<T extends { id: string }> {
+  findById(id: string): Promise<T | null>;
+  create(data: Omit<T, 'id'>): Promise<T>;
+  update(id: string, data: Partial<T>): Promise<T>;
+  delete(id: string): Promise<void>;
+}
+```
+
+## Anti-Patterns
+
+- [FAIL] `any` — use `unknown` + type guards
+- [FAIL] Type assertions (`as`) — prefer type guards
+- [FAIL] Non-null assertions (`!`) — handle null explicitly
+- [FAIL] Enums — prefer union types or `as const` objects
+- [FAIL] Complex generics without JSDoc — document intent
+
+
+## Code Examples
+
+See `EXAMPLES.md` for detailed code examples.
+
+## Validation Checklist
+
+What to verify during the review phase before completing the task.
+
+## Common Mistakes
+
+Anti-patterns and things to explicitly avoid. See `TROUBLESHOOTING.md`.
+
+## Integration Notes
+
+How this skill interacts with other skills.
+
+
+# TypeScript Examples — Anti-patterns vs ContextOS Standard
+
+## Example 1: Type-Safe Parsing with Zod (No `any`)
+
+### Anti-pattern: Anti-pattern (Blind type assertion with `as`)
+
+```typescript
+// BAD: using 'as User' bypasses runtime validation completely
+async function fetchUser(id: string): Promise<User> {
+  const res = await fetch(`/api/users/${id}`);
+  const data = await res.json();
+  return data as User; // Runtime crash if payload changes!
+}
+```
+
+### Best practice: ContextOS Standard (Runtime schema validation with Zod)
+
+```typescript
+// GOOD: guaranteed runtime and compile-time type safety
+import { z } from 'zod';
+
+export const UserSchema = z.object({
+  id: z.string().uuid(),
+  name: z.string().min(1),
+  email: z.string().email(),
+  role: z.enum(['admin', 'member', 'guest']),
+  createdAt: z.string().datetime(),
+});
+
+export type User = z.infer<typeof UserSchema>;
+
+export async function fetchUser(id: string): Promise<User> {
+  const res = await fetch(`/api/users/${id}`);
+  if (!res.ok) throw new Error(`Fetch failed with status ${res.status}`);
+  const raw: unknown = await res.json();
+  return UserSchema.parse(raw);
+}
+```
+
+---
+
+## Example 2: Discriminated Unions for State Handling
+
+### Anti-pattern: Anti-pattern (Optional soup with boolean flags)
+
+```typescript
+// BAD: impossible states can be represented (e.g. isLoading: true AND error: 'Failed')
+interface AsyncState<T> {
+  data?: T;
+  isLoading: boolean;
+  error?: string;
+}
+```
+
+### Best practice: ContextOS Standard (Discriminated Union)
+
+```typescript
+// GOOD: impossible states are impossible at compile-time
+export type AsyncState<T> =
+  | { readonly status: 'idle' }
+  | { readonly status: 'loading' }
+  | { readonly status: 'success'; readonly data: T }
+  | { readonly status: 'error'; readonly error: Error };
+```
+
+# typescript Troubleshooting & Common Mistakes
+
+## 1. Excessive Use of `any` or `as unknown as T`
+
+- **Symptom**: Runtime `TypeError: Cannot read properties of undefined` in supposedly typed TypeScript code.
+- **Root Cause**: Bypassing type checking with `any` or forceful type assertions.
+- **Fix**: Use `unknown` with type guards, Zod schemas, or discriminated unions.
+
+## 2. Non-Exhaustive Switch on Unions
+
+- **Symptom**: New union member added but some switch statements fail to handle it, producing bugs.
+- **Root Cause**: Missing exhaustive type checking in `default:` case.
+- **Fix**: Add `default: const _exhaustive: never = action; throw new Error(_exhaustive);` to let the compiler catch missing branches.
+
+## 3. Inaccurate Generics Constraints
+
+- **Symptom**: Generic functions that lose type inference and resolve to `unknown`.
+- **Root Cause**: Over-specifying generics or missing `extends` constraints.
+- **Fix**: Constrain generics narrowly: `function get<T, K extends keyof T>(obj: T, key: K): T[K]`.

package/.agents/generated/claude/skills/ui-design/SKILL.md

@@ -0,0 +1,161 @@
+# UI Design
+
+## Overview
+
+Modern component library and design system engineering. Enforces design token hierarchies (spacing, radii, elevation), accessible component primitives (shadcn/ui, Radix), and responsive layout constraints.
+
+## When to Use
+
+Activate when designing design systems, reusable UI component libraries, navigation bars, modals, data tables, and interactive dashboards.
+
+## Rules & Patterns
+<!-- Source: ui.md -->
+
+## UI Design — Best Practices
+
+## Design System Foundations
+
+### Color
+
+- **Never use generic colors** — curate a harmonious palette
+- **Always tint** — no pure black (#000), no pure gray. Add a subtle warm or cool tint
+- **Color roles**: primary (action), secondary (accent), neutral (text, borders), semantic (error, success, warning, info)
+- **Dark mode**: design intentionally, not just invert. Surface hierarchy: background < surface < elevated
+- **Contrast**: 4.5:1 minimum for body text, 3:1 for large text
+
+### Typography
+
+- **Never use browser defaults** — choose a curated font (Inter, Outfit, Geist, Sora)
+- **Type scale**: use a modular scale (1.25 ratio) — 12, 14, 16, 20, 24, 32, 40, 48
+- **Font weights**: Regular (400), Medium (500), Semibold (600), Bold (700). Don't use all of them — pick 2-3
+- **Line height**: 1.5 for body, 1.2 for headings, 1.6 for long-form text
+- **Max line width**: 65-75 characters for readability
+
+### Spacing
+
+- **Use a 4px grid** — all spacing should be multiples of 4
+- **Spacing scale**: 4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 80, 96
+- **Consistency** — same spacing between similar elements
+- **Whitespace is design** — don't fill every pixel
+
+### Layout
+
+- **Grid system**: 12-column grid for desktop, 4-column for mobile
+- **Visual hierarchy**: size, weight, color, spacing, position
+- **F-pattern/Z-pattern** — for content-heavy pages
+- **Group related items** — use proximity and boundaries
+
+## Component Patterns
+
+### Buttons
+
+- Clear hierarchy: Primary > Secondary > Ghost/Text
+- Consistent sizing: sm (32px), md (40px), lg (48px)
+- States: default, hover, active, disabled, loading
+- Always accessible: sufficient contrast, focus indicator
+
+### Forms
+
+- Labels above inputs (not floating labels for critical forms)
+- Clear error states with inline messages
+- Logical tab order
+- Progressive disclosure — don't show all fields at once
+
+### Cards
+
+- Don't nest cards inside cards
+- Clear visual hierarchy within the card
+- Consistent padding and spacing
+- Interactive cards need hover state
+
+### Navigation
+
+- Maximum 7±2 items in primary nav
+- Clear active state
+- Mobile: bottom nav or hamburger (not both)
+- Breadcrumbs for deep hierarchies
+
+## Animation Principles
+
+- **Purpose**: guide attention, show relationships, provide feedback
+- **Duration**: 150-300ms for micro-interactions, 300-500ms for transitions
+- **Easing**: `ease-out` for entrances, `ease-in` for exits. Never `bounce` or `elastic`
+- **Reduce motion**: respect `prefers-reduced-motion`
+
+## Anti-Patterns (from Impeccable)
+
+- [FAIL] Gray text on colored backgrounds — destroys readability
+- [FAIL] Pure black text on white (#000 on #fff) — too harsh, tint the black
+- [FAIL] Cards nested inside cards — visual noise
+- [FAIL] Bounce/elastic easing — feels dated
+- [FAIL] Icon tile above every heading — SaaS template tell
+- [FAIL] Purple-to-blue gradient on everything — overused
+- [FAIL] Using Inter for everything — pick a font that matches your brand
+- [FAIL] Rounded-square icons everywhere — lack of visual variety
+
+## Dark Mode
+
+- Surface elevation through subtle lightening (not colored backgrounds)
+- Reduce white contrast — use #E0E0E0, not #FFFFFF
+- Shadows become less visible — use subtle borders or elevation changes
+- Test all states in both modes
+
+
+## Code Examples
+
+See `EXAMPLES.md` for detailed code examples.
+
+## Validation Checklist
+
+What to verify during the review phase before completing the task.
+
+## Common Mistakes
+
+Anti-patterns and things to explicitly avoid. See `TROUBLESHOOTING.md`.
+
+## Integration Notes
+
+How this skill interacts with other skills.
+
+
+# ui-design Examples — Anti-patterns vs ContextOS Standard
+
+## Example 1: Component Token Consistency
+
+### Anti-pattern: Hardcoded Arbitrary Tailwind Utilities
+
+```tsx
+// BAD: Inconsistent spacing, arbitrary colors, unmaintainable styling
+<div className="p-[13px] bg-[#1a1b2e] rounded-[7px] text-[#99aab5] border border-[#2b2d42]">
+  <button className="px-[15px] py-[7px] bg-[#5865f2] hover:bg-[#4752c4]">Action</button>
+</div>
+```
+
+### Best practice: ContextOS Standard (Semantic Theme Tokens)
+
+```tsx
+// GOOD: Consistent scale utilities driven by Tailwind v4 @theme design tokens
+<div className="p-4 bg-card rounded-lg text-muted-foreground border border-border">
+  <Button variant="primary" size="md">Action</Button>
+</div>
+```
+
+# ui-design Troubleshooting & Common Mistakes
+
+## 1. Z-Index Chaos
+
+- **Symptom**: Tooltips rendered underneath dialog overlays, or dropdowns hidden behind sticky headers.
+- **Root Cause**: Ad-hoc hardcoded values (z-50, z-[999], z-[9999]).
+- **Fix**: Use Radix / shadcn Portals for floating elements so they render at root DOM level, or declare strict z-index tokens.
+
+## 2. Inconsistent Component States
+
+- **Symptom**: Buttons have hover states but lack focus-visible rings or disabled states.
+- **Root Cause**: Styling only the default and hover states.
+- **Fix**: Standardize state matrices for every interactive element: default, hover, focus-visible, active, disabled, loading.
+
+## 3. Ignoring Empty and Error Component States
+
+- **Symptom**: Tables or list views show a blank white box when there are 0 records.
+- **Root Cause**: Developers only design for the "ideal data" case.
+- **Fix**: Every data component must explicitly render designed EmptyState and ErrorState fallbacks.