contextos-agents 1.7.0 → 2.0.0-beta.2

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

@@ -1,192 +0,0 @@
-# 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

@@ -1,161 +0,0 @@
-# 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.