contextos-agents 1.7.0 → 2.0.0-beta.3

package/.agents/core/skills/system-design/system-design.md

@@ -1,112 +0,0 @@
-# System Design — Patterns & Principles
-
-## Architecture Patterns
-
-### Monolith (Start Here)
-
-- **When**: MVP, small team, < 100K users
-- **Structure**: Modular monolith with clear boundaries
-- **Rule**: You can always extract microservices later. You can't easily merge them back.
-
-### Microservices
-
-- **When**: Team > 10 engineers, independent deployment needed
-- **Communication**: REST (sync), Message Queue (async)
-- **Data**: Each service owns its database
-- **Pitfalls**: Network complexity, distributed transactions, debugging difficulty
-
-### Event-Driven
-
-- **When**: Loose coupling between services, async processing
-- **Patterns**: Event Sourcing, CQRS, Pub/Sub
-- **Tools**: Kafka, RabbitMQ, AWS SQS, Redis Streams
-
-## Scalability
-
-### Horizontal vs Vertical
-
-- **Vertical first** — upgrade your server before distributing
-- **Horizontal when** — you hit single-machine limits or need redundancy
-
-### Database Scaling
-
-1. **Indexes** — most common fix for slow queries
-2. **Read replicas** — for read-heavy workloads
-3. **Connection pooling** — PgBouncer, connection limits
-4. **Caching** — Redis for hot data
-5. **Sharding** — last resort, adds massive complexity
-
-### Caching Layers
-
-```
-Client Cache (browser) → CDN → API Cache (Redis) → Database
-```
-
-| Strategy | Description |
-| --- | --- |
-| Cache-Aside | App checks cache first, fetches from DB on miss |
-| Write-Through | App writes to cache AND DB simultaneously |
-| Write-Behind | App writes to cache, async write to DB |
-| TTL-based | Set expiry, accept stale data |
-
-## Load Balancing
-
-- **Round Robin** — simple, default
-- **Least Connections** — for varying request duration
-- **IP Hash** — for sticky sessions (avoid if possible)
-- **Health checks** — remove unhealthy instances
-
-## API Design
-
-### REST Conventions
-
-```
-GET    /users          → List users
-GET    /users/:id      → Get user
-POST   /users          → Create user
-PUT    /users/:id      → Full update
-PATCH  /users/:id      → Partial update
-DELETE /users/:id      → Delete user
-```
-
-### Pagination
-
-- Cursor-based for real-time data (recommended)
-- Offset-based for static data
-
-### Versioning
-
-- URL-based (`/v1/`, `/v2/`) — simplest
-- Header-based — more flexible
-
-## Reliability
-
-- **Circuit breaker** — stop calling failing services
-- **Retry with exponential backoff** — for transient failures
-- **Timeout** — every external call needs a timeout
-- **Health checks** — `/health` endpoint for load balancers
-- **Graceful degradation** — work with reduced functionality
-
-## Data Storage
-
-| Use Case | Technology |
-| --- | --- |
-| Relational data, ACID | PostgreSQL |
-| Key-value, caching | Redis |
-| Full-text search | Elasticsearch, Meilisearch |
-| Document store | MongoDB (if truly schemaless) |
-| Time series | TimescaleDB, InfluxDB |
-| Blob storage | S3, R2 |
-| Queue | Redis Streams, RabbitMQ, SQS |
-
-## Decision Framework
-
-Before choosing an architecture:
-
-1. What's the expected load? (users, requests/sec)
-2. What's the team size?
-3. What's the timeline?
-4. What are the consistency requirements?
-5. What's the budget?
-
-**Default answer**: Start with a monolith, PostgreSQL, Redis cache. Extract services only when you have data showing you need to.

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

@@ -1,71 +0,0 @@
-# Testing Examples — Anti-patterns vs ContextOS Standard
-
-## Example 1: React Component Testing
-
-### Anti-pattern: Anti-pattern (Brittle query & implementation coupling)
-
-```typescript
-// BAD: querying by CSS class or test-id and testing internal state
-test('submits form', async () => {
-  const wrapper = render(<LoginForm />);
-  const input = wrapper.container.querySelector('.email-input');
-  fireEvent.change(input, { target: { value: 'user@test.com' } });
-  fireEvent.click(wrapper.container.querySelector('#submit-btn'));
-  expect(wrapper.state().isSubmitted).toBe(true); // Brittle!
-});
-```
-
-### Best practice: ContextOS Standard (User-centric role queries & userEvent)
-
-```typescript
-// GOOD: user-facing roles, userEvent, async wait
-import { render, screen } from '@testing-library/react';
-import userEvent from '@testing-library/user-event';
-import { LoginForm } from './LoginForm';
-
-test('submits form with valid user credentials', async () => {
-  const user = userEvent.setup();
-  const onSubmit = vi.fn();
-  render(<LoginForm onSubmit={onSubmit} />);
-
-  await user.type(screen.getByLabelText(/email address/i), 'user@test.com');
-  await user.type(screen.getByLabelText(/password/i), 'SecureP@ss123!');
-  await user.click(screen.getByRole('button', { name: /sign in/i }));
-
-  expect(onSubmit).toHaveBeenCalledWith({
-    email: 'user@test.com',
-    password: 'SecureP@ss123!'
-  });
-  expect(screen.queryByRole('alert')).not.toBeInTheDocument();
-});
-```
-
----
-
-## Example 2: API Mocking with MSW (Mock Service Worker)
-
-### Anti-pattern: Anti-pattern (Hardcoded global fetch monkey-patching)
-
-```typescript
-// BAD: globally overwriting fetch breaks other tests and hides actual contract
-global.fetch = vi.fn().mockResolvedValue({
-  json: () => Promise.resolve({ data: 'ok' })
-});
-```
-
-### Best practice: ContextOS Standard (Network boundary mocking)
-
-```typescript
-// GOOD: declarative MSW network handler
-import { http, HttpResponse } from 'msw';
-import { setupServer } from 'msw/node';
-
-export const server = setupServer(
-  http.get('/api/users/:id', ({ params }) => {
-    if (params.id === '404') {
-      return new HttpResponse(null, { status: 404 });
-    }
-    return HttpResponse.json({ id: params.id, name: 'Alice Smith' });
-  })
-);
-```

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

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

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

@@ -1,11 +0,0 @@
-{
-  "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

@@ -1,32 +0,0 @@
-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
-type: instruction-only
-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"
-resources:
-  - EXAMPLES.md
-  - SKILL.md
-  - TROUBLESHOOTING.md
-  - VALIDATION.json

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

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

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

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

@@ -1,12 +0,0 @@
-{
-  "$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

@@ -1,17 +0,0 @@
-id: typescript
-name: TypeScript
-category: frontend
-type: instruction-only
-tags: [frontend, backend, types, static-analysis]
-requires: []
-optional: [zod, prisma]
-conflicts: []
-weight: 9
-documents:
-  - typescript.md
-resources:
-  - EXAMPLES.md
-  - SKILL.md
-  - TROUBLESHOOTING.md
-  - VALIDATION.json
-  - typescript.md

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

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

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