contextos-agents 1.5.0

package/.agents/core/skills/testing/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: testing
+description: Vitest, React Testing Library, and Playwright testing standards. Enforces TDD/BDD, test pyramid, zero brittle mocks, and complete assertion coverage.
+---
+
+# Testing
+
+## Overview
+
+Testing strategy across unit, component, integration, and end-to-end testing suites using Vitest, React Testing Library, and Playwright.
+
+## When to Use
+
+Activate for any task involving unit tests, integration tests, E2E testing, TDD/BDD workflows, or fixing regression bugs.
+
+## Rules & Patterns
+
+### ️ The ContextOS Testing Pyramid
+
+```
+      /\
+     /E2E\       10% — Playwright (Critical user journeys, auth, checkout)
+    /-----\
+   / Integ \     20% — API & Component Integration (RTL + MSW / Supertest)
+  /---------\
+ /   Unit    \   70% — Pure functions, Domain Entities, Utils (Vitest)
+/-------------\
+```
+
+### Negative Constraints (What NOT to Do)
+
+1. **NEVER mock internal implementation details**: Mock ONLY external I/O boundaries (HTTP network requests via MSW, Database via test containers or in-memory DB).
+2. **NEVER test implementation details**: In React Testing Library, query by user-facing roles (`getByRole`, `getByLabelText`), NEVER by CSS selectors or internal component state.
+3. **NEVER write assertions without an expected failure mode**: Each test must test a single logical behavior and fail if that behavior breaks.
+4. **NEVER leave flaky tests or arbitrary sleep (`await delay(1000)`)**: Always use `waitFor()` or explicit event triggers with timeouts.
+5. **NEVER share mutable state between tests**: Every test must have isolated state via `beforeEach()` setup and clean reset.
+
+### AAA Standard Pattern
+
+```typescript
+describe('Feature / Unit', () => {
+  it('should achieve expected outcome when given specific condition', async () => {
+    // 1. ARRANGE
+    const user = createTestUser({ role: 'admin' });
+    // 2. ACT
+    const result = await processOrder(user, sampleCart);
+    // 3. ASSERT
+    expect(result.status).toBe('confirmed');
+  });
+});
+```
+
+## Code Examples
+
+See `EXAMPLES.md` for detailed anti-patterns and production testing code.
+
+## Validation Checklist
+
+- [ ] Tests follow Arrange-Act-Assert (AAA) structure
+- [ ] No brittle CSS selectors or private state inspections
+- [ ] Mocks isolated strictly to network/IO boundaries (MSW)
+- [ ] Fast execution (< 5s for unit suite) with zero flaky sleeps
+
+## Common Mistakes
+
+- Over-mocking modules instead of running real pure logic. See `TROUBLESHOOTING.md`.
+
+## Integration Notes
+
+Interacts directly with `engineering-workflow` (Verify phase), `react`, and `typescript`.

package/.agents/core/skills/testing/TROUBLESHOOTING.md

@@ -0,0 +1,18 @@
+# Testing Troubleshooting Guide
+
+## Common Issues & Fixes
+
+### 1. `act(...)` warning in React Testing Library
+
+- **Cause**: An asynchronous state update triggered after the test completed.
+- **Fix**: Ensure all async operations are awaited using `await waitFor(() => ...)` or `await screen.findByRole(...)`.
+
+### 2. Tests pass in isolation but fail in concurrent test runs
+
+- **Cause**: Shared in-memory state or un-reset singleton.
+- **Fix**: Reset all mocks and in-memory databases in `beforeEach(() => vi.clearAllMocks())` and `afterEach(() => cleanup())`.
+
+### 3. Playwright timeout waiting for selector
+
+- **Cause**: Element is animating or blocked behind a modal/overlay.
+- **Fix**: Use web-first assertions like `await expect(page.getByRole('button')).toBeVisible()` which automatically retry until timeout.

package/.agents/core/skills/testing/VALIDATION.json

@@ -0,0 +1,11 @@
+{
+  "skill": "testing",
+  "version": "1.0.0",
+  "checks": [
+    "Test pyramid ratio enforced (70% unit/integration)",
+    "AAA (Arrange-Act-Assert) pattern implemented",
+    "No internal state inspection or brittle selectors",
+    "MSW used for network boundaries",
+    "Zero shared state between test executions"
+  ]
+}

package/.agents/core/skills/testing/skill.yaml

@@ -0,0 +1,26 @@
+name: testing
+description: Vitest, React Testing Library, and Playwright testing standards. Enforces TDD/BDD, test pyramid, zero brittle mocks, and complete assertion coverage.
+version: 1.0.0
+category: engineering
+requires:
+  - engineering-workflow
+  - typescript
+triggers:
+  files:
+    - "*.test.ts"
+    - "*.test.tsx"
+    - "*.test.js"
+    - "*.spec.ts"
+    - "*.spec.tsx"
+    - "vitest.config.*"
+    - "playwright.config.*"
+    - "jest.config.*"
+  keywords:
+    - "test"
+    - "vitest"
+    - "playwright"
+    - "unit test"
+    - "e2e"
+    - "mock"
+    - "assert"
+    - "coverage"

package/.agents/core/skills/typescript/EXAMPLES.md

@@ -0,0 +1,64 @@
+# 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 };
+```

package/.agents/core/skills/typescript/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: TypeScript
+description: >
+  ContextOS skill for TypeScript
+---
+
+# 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.

package/.agents/core/skills/typescript/TROUBLESHOOTING.md

@@ -0,0 +1,19 @@
+# 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/core/skills/typescript/VALIDATION.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "rules_followed": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "rules_followed"
+  ]
+}

package/.agents/core/skills/typescript/skill.yaml

@@ -0,0 +1,10 @@
+id: typescript
+name: TypeScript
+category: frontend
+tags: [frontend, backend, types, static-analysis]
+requires: []
+optional: [zod, prisma]
+conflicts: []
+weight: 9
+documents:
+  - typescript.md

package/.agents/core/skills/typescript/typescript.md

@@ -0,0 +1,71 @@
+# TypeScript — Best Practices
+
+## 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

package/.agents/core/skills/ui-design/EXAMPLES.md

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

package/.agents/core/skills/ui-design/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: UI Design
+description: >
+  ContextOS skill for UI Design
+---
+
+# 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.

package/.agents/core/skills/ui-design/TROUBLESHOOTING.md

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

package/.agents/core/skills/ui-design/VALIDATION.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "rules_followed": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "rules_followed"
+  ]
+}

package/.agents/core/skills/ui-design/skill.yaml

@@ -0,0 +1,10 @@
+id: ui-design
+name: UI Design
+category: design
+tags: [design, ui, components, design-system, visual]
+requires: []
+optional: [react, tailwind, web-accessibility]
+conflicts: []
+weight: 7
+documents:
+  - ui.md