contextos-agents 1.6.1 → 2.0.0-beta.2

package/.agents/core/skills/node/node.md

@@ -1,87 +0,0 @@
-# Node.js — Best Practices
-
-## Architecture
-
-- **Layered architecture**: Routes → Controllers → Services → Repositories
-- **Dependency injection** — don't import dependencies directly in services
-- **Config from environment** — never hardcode secrets, use env variables
-- **Graceful shutdown** — handle SIGTERM, close connections, drain requests
-
-## Error Handling
-
-- **Never swallow errors** — always handle or re-throw
-- **Custom error classes** — extend Error with HTTP status codes
-- **Global error handler** — catch unhandled rejections and uncaught exceptions
-- **Structured logging** — JSON logs with request ID, timestamp, level
-
-```typescript
-class AppError extends Error {
-  constructor(
-    public message: string,
-    public statusCode: number = 500,
-    public code: string = 'INTERNAL_ERROR'
-  ) {
-    super(message);
-    this.name = 'AppError';
-  }
-}
-```
-
-## API Design
-
-- **RESTful conventions** — GET (read), POST (create), PUT (full update), PATCH (partial), DELETE
-- **Consistent response format** — `{ data, error, pagination }`
-- **Validation at the edge** — validate request body/params with Zod or Joi
-- **Rate limiting** — protect against abuse
-- **CORS** — configure explicitly, never use `*` in production
-
-## Security
-
-- **Helmet.js** — security headers
-- **Input validation** — never trust client input
-- **SQL injection** — always use parameterized queries
-- **XSS** — sanitize output, use Content-Security-Policy
-- **Authentication** — JWT with short expiry + refresh tokens
-- **Secrets** — environment variables, never in code
-
-## Database
-
-- **Connection pooling** — don't create connections per request
-- **Migrations** — version-controlled schema changes
-- **Transactions** — for multi-step operations
-- **Indexes** — add indexes for frequently queried columns
-
-## Performance
-
-- **Async/await** — never block the event loop
-- **Streaming** — for large files and data sets
-- **Caching** — Redis for frequently accessed data
-- **Clustering** — use PM2 or cluster module for multi-core
-
-## Testing
-
-- **Unit tests** — services and utilities
-- **Integration tests** — API endpoints with test database
-- **Test isolation** — each test should be independent
-- **Fixtures** — use factories, not shared state
-
-## File Structure
-
-```
-src/
-├── config/          # Configuration
-├── modules/         # Feature modules
-│   └── users/
-│       ├── users.controller.ts
-│       ├── users.service.ts
-│       ├── users.repository.ts
-│       ├── users.routes.ts
-│       ├── users.types.ts
-│       └── users.test.ts
-├── shared/          # Shared utilities
-│   ├── middleware/
-│   ├── errors/
-│   └── utils/
-├── types/           # Global types
-└── app.ts           # App entry point
-```

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

@@ -1,10 +0,0 @@
-id: node
-name: Node.js
-category: backend
-tags: [backend, javascript, runtime, server, express, fastify]
-requires: [typescript]
-optional: [postgres, redis, docker]
-conflicts: []
-weight: 7
-documents:
-  - node.md

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

@@ -1,30 +0,0 @@
-# performance Examples — Anti-patterns vs ContextOS Standard
-
-## Example 1: Dynamic Imports for Heavy Libraries
-
-### Anti-pattern: Static Import of Heavy Visualizers in Initial Bundle
-
-```typescript
-// BAD: Adds 800KB (Monaco editor or Three.js) to the critical first-paint bundle!
-import { CodeEditor } from '@/components/CodeEditor';
-
-export default function Page() {
-  return <div><CodeEditor /></div>;
-}
-```
-
-### Best practice: ContextOS Standard (Lazy Load on Demand)
-
-```typescript
-// GOOD: Dynamic import splits chunk, only downloads when component renders
-import dynamic from 'next/dynamic';
-
-const CodeEditor = dynamic(
-  () => import('@/components/CodeEditor'),
-  { loading: () => <EditorSkeleton />, ssr: false }
-);
-
-export default function Page() {
-  return <div><CodeEditor /></div>;
-}
-```

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

@@ -1,75 +0,0 @@
----
-name: Web Performance
-description: >
-  ContextOS skill for Web Performance, Core Web Vitals, waterfall elimination, bundle size optimization, and caching strategies.
----
-
-# Web Performance & Core Web Vitals
-
-## Overview
-
-Enforces high-efficiency frontend and full-stack performance standards to achieve exceptional Core Web Vitals: Largest Contentful Paint (LCP < 2.5s), Interaction to Next Paint (INP < 200ms), and Cumulative Layout Shift (CLS < 0.1).
-
-## When to Use
-
-Activate whenever analyzing, profiling, writing, or optimizing page loading speeds, network waterfalls, script bundling, animation frame rates, or data caching.
-
-## Negative Constraints (What NOT to Do)
-
-1. **NEVER introduce async waterfalls**: Do not chain sequential `await` calls when requests can be executed concurrently via `Promise.all()`.
-2. **NEVER import large full libraries when only a utility is needed**: Never `import _ from 'lodash'`; use `import debounce from 'lodash/debounce'` or native alternatives.
-3. **NEVER render images or videos without explicit aspect ratios**: Always provide `width` and `height` or `aspect-ratio` to avoid Cumulative Layout Shift (CLS).
-4. **NEVER trigger synchronous layout thrashing**: Do not alternate between reading layout properties (`offsetHeight`, `getBoundingClientRect`) and writing styles in loops.
-5. **NEVER animate non-composited properties**: Animate only GPU-composited CSS properties (`transform`, `opacity`). Never animate `width`, `height`, `top`, `left`, or `margin`.
-
-## Rules & Patterns
-
-### 1. Vercel Optimization Hierarchy by Impact
-
-| Priority | Category | Key Optimization Target | Expected Impact |
-|:---|:---|:---|:---|
-| **1. CRITICAL** | **Eliminating Waterfalls** | Parallel data fetching (`Promise.all`), Suspense streaming | **30–60% faster LCP** |
-| **2. CRITICAL** | **Bundle Size Optimization** | Direct submodule imports, `next/dynamic`, deferring 3rd party scripts | **40–70% smaller initial JS** |
-| **3. HIGH** | **Server-Side & RSC Caching** | `React.cache()` request deduplication, edge SSR caching | **Lower TTFB & DB load** |
-| **4. MEDIUM-HIGH** | **Client Query Optimization** | SWR / TanStack Query stale-while-revalidate, deduplication | **Zero redundant network calls** |
-| **5. MEDIUM** | **Render & DOM Optimization** | Virtualization for large lists, state colocation, `:focus-visible` | **Smooth 60 FPS / INP < 100ms** |
-
-### 2. Eliminating Network Waterfalls
-
-```ts
-// [GOOD] Parallel execution
-const [user, notifications] = await Promise.all([
-  fetchUser(),
-  fetchNotifications(),
-]);
-const posts = await fetchPosts(user.id);
-```
-
-### 3. Layout Shift & Visual Stability (CLS < 0.1)
-
-- **Images & Video**: Always supply `width`, `height`, and `sizes` or CSS `aspect-ratio: 16 / 9`.
-- **Dynamic Content**: Reserve layout space for dynamically loaded widgets with min-height placeholders or skeletons.
-- **Tabular Numbers**: Use `font-feature-settings: "tnum"` / `font-variant-numeric: tabular-nums` for counters, clocks, and tables to prevent number width jitter.
-
-## Code Examples
-
-See `EXAMPLES.md` for detailed performance patterns and benchmark snippets.
-
-## Validation Checklist
-
-- [ ] LCP target is < 2.5s with preloaded critical fonts and LCP image `priority`.
-- [ ] No sequential `await` waterfalls in API routes or Server Components.
-- [ ] All animated elements use only `transform` and `opacity`.
-- [ ] `prefers-reduced-motion` media queries are respected.
-- [ ] Large tables / lists (> 100 items) utilize virtualization.
-
-## Common Mistakes
-
-- Chaining independent async requests instead of using `Promise.all`.
-- Animating layout-triggering properties (`height`, `width`, `top`) causing jank.
-- Missing image dimensions causing layout shift when images finish loading.
-
-## Integration Notes
-
-- Pairs with `nextjs` and `react` for App Router caching and component lifecycle tuning.
-- Pairs with `ui-ux-pro` for smooth animations and responsive design tokens.

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

@@ -1,19 +0,0 @@
-# performance Troubleshooting & Common Mistakes
-
-## 1. Cumulative Layout Shift (CLS) from Images & Fonts
-
-- **Symptom**: Page content jumps around as images and custom fonts load.
-- **Root Cause**: Missing width and height attributes on image tags and FOUT (Flash of Unstyled Text).
-- **Fix**: Always specify aspect-ratio or width/height on images, and use next/font to preload web fonts with fallback sizing.
-
-## 2. High Interaction to Next Paint (INP)
-
-- **Symptom**: User clicks a button and the UI freezes for 200ms+ before responding.
-- **Root Cause**: Long task blocking the main thread during event dispatch.
-- **Fix**: Defer non-critical state updates using startTransition() or split heavy computation with Web Workers.
-
-## 3. Unoptimized SVG / Icon Overload
-
-- **Symptom**: Huge DOM node count and slow initial render times.
-- **Root Cause**: Rendering 500 inline SVG icons with complex paths.
-- **Fix**: Use SVG sprite sheets, dynamic icon loaders, or lightweight canvas rendering for dense data visualizations.

package/.agents/core/skills/performance/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/performance/performance.md

@@ -1,52 +0,0 @@
-# Web Performance — Best Practices
-
-## Core Web Vitals
-
-| Metric | Target | What it measures |
-| --- | --- | --- |
-| LCP (Largest Contentful Paint) | < 2.5s | Loading performance |
-| INP (Interaction to Next Paint) | < 200ms | Responsiveness |
-| CLS (Cumulative Layout Shift) | < 0.1 | Visual stability |
-
-## Loading Performance
-
-- **Code splitting** — split by route, lazy load non-critical components
-- **Tree shaking** — use ES modules, avoid side-effect imports
-- **Image optimization** — WebP/AVIF, responsive srcset, lazy loading
-- **Font loading** — `font-display: swap`, preload critical fonts
-- **Critical CSS** — inline above-the-fold styles
-- **Preconnect** — `<link rel="preconnect">` for third-party origins
-
-## Runtime Performance
-
-- **Avoid layout thrashing** — batch DOM reads and writes
-- **Debounce/throttle** — expensive event handlers (scroll, resize, input)
-- **Web Workers** — offload heavy computation
-- **Virtualize long lists** — render only visible items
-- **Avoid synchronous operations** — use async/await, requestIdleCallback
-
-## Bundle Optimization
-
-- **Analyze bundle** — use webpack-bundle-analyzer or similar
-- **Dynamic imports** — `import()` for heavy libraries
-- **Avoid barrel exports** — they prevent tree shaking
-- **Vendor splitting** — separate vendor chunks for caching
-- **Compression** — Brotli > gzip
-
-## Caching Strategy
-
-| Asset | Cache | Strategy |
-| --- | --- | --- |
-| HTML | Short (5min) | Revalidate |
-| JS/CSS (hashed) | Long (1 year) | Immutable |
-| Images | Long (1 year) | Immutable |
-| API responses | Depends | stale-while-revalidate |
-| Fonts | Long (1 year) | Immutable |
-
-## Anti-Patterns
-
-- [FAIL] Importing entire libraries (`import _ from 'lodash'`)
-- [FAIL] Unoptimized images (PNG > 500KB)
-- [FAIL] Blocking scripts in `<head>` without `defer`
-- [FAIL] Layout shifts from dynamic content (no dimensions on images)
-- [FAIL] Premature optimization — measure first, optimize second

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

@@ -1,10 +0,0 @@
-id: performance
-name: Web Performance
-category: frontend
-tags: [frontend, performance, core-web-vitals, optimization]
-requires: []
-optional: [react, nextjs]
-conflicts: []
-weight: 6
-documents:
-  - performance.md

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

@@ -1,79 +0,0 @@
-# React Examples — Anti-patterns vs ContextOS Standard
-
-## Example 1: Derived State vs. useEffect
-
-### Anti-pattern: Anti-pattern (Redundant state + extra render with useEffect)
-
-```tsx
-// BAD: causes an unnecessary extra render cycle and potential state desync
-function OrderSummary({ items }: { items: CartItem[] }) {
-  const [total, setTotal] = useState(0);
-
-  useEffect(() => {
-    const calculated = items.reduce((sum, item) => sum + item.price * item.quantity, 0);
-    setTotal(calculated);
-  }, [items]);
-
-  return <div>Total: ${total}</div>;
-}
-```
-
-### Best practice: ContextOS Standard (Inline derived calculation / useMemo)
-
-```tsx
-// GOOD: calculated instantly during render with zero extra render pass
-function OrderSummary({ items }: { items: CartItem[] }) {
-  const total = useMemo(
-    () => items.reduce((sum, item) => sum + item.price * item.quantity, 0),
-    [items]
-  );
-
-  return <div>Total: ${total.toFixed(2)}</div>;
-}
-```
-
----
-
-## Example 2: Custom Hook Encapsulation
-
-### Anti-pattern: Anti-pattern (Scattered listener logic inside component)
-
-```tsx
-// BAD: window listener logic cluttering UI component
-function NavHeader() {
-  const [isScrolled, setIsScrolled] = useState(false);
-  useEffect(() => {
-    const handleScroll = () => setIsScrolled(window.scrollY > 50);
-    window.addEventListener('scroll', handleScroll);
-    return () => window.removeEventListener('scroll', handleScroll);
-  }, []);
-  return <header className={isScrolled ? 'scrolled' : ''}>Header</header>;
-}
-```
-
-### Best practice: ContextOS Standard (Reusable Custom Hook)
-
-```tsx
-// GOOD: extracted into a reusable, testable custom hook
-export function useScrollThreshold(threshold = 50): boolean {
-  const [isPassed, setIsPassed] = useState(() => typeof window !== 'undefined' && window.scrollY > threshold);
-
-  useEffect(() => {
-    let ticking = false;
-    const handleScroll = () => {
-      if (!ticking) {
-        window.requestAnimationFrame(() => {
-          setIsPassed(window.scrollY > threshold);
-          ticking = false;
-        });
-        ticking = true;
-      }
-    };
-
-    window.addEventListener('scroll', handleScroll, { passive: true });
-    return () => window.removeEventListener('scroll', handleScroll);
-  }, [threshold]);
-
-  return isPassed;
-}
-```

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

@@ -1,132 +0,0 @@
----
-name: React
-description: >
-  ContextOS skill for modern React (v18/v19), component architecture, state colocation, render optimization, and Vercel performance rules.
----
-
-# React Engineering & Performance Best Practices
-
-## Overview
-
-Enforces declarative, component-driven UI architecture with optimal re-render cycles, state colocation, responsive optimistic updates, and robust accessibility standards.
-
-## When to Use
-
-Activate whenever creating, refactoring, or optimizing React functional components, custom hooks, context providers, or UI interaction states.
-
-## Negative Constraints (What NOT to Do)
-
-1. **NEVER use `useEffect` to synchronize or compute derived state**: Calculate derived state inline during render. Use `useMemo` only for computationally intensive derivations.
-2. **NEVER use array indices as `key` props on dynamic or reorderable lists**: Always use stable, unique entity identifiers (`item.id`).
-3. **NEVER mutate React state directly**: Always return new immutable references (`[...prev, newItem]` or `{ ...prev, key: value }`).
-4. **NEVER declare subcomponents inside the render body of parent components**: Declare components at module scope or in dedicated files to prevent DOM node remounting and lost focus state.
-5. **NEVER create memory leaks in `useEffect`**: Always provide clean-up functions for event listeners, `AbortController`, timers, and websocket subscriptions.
-6. **NEVER lift state higher than necessary**: Colocate state to the nearest common ancestor or leaf component to prevent wasteful re-renders of unrelated subtrees.
-
-## Rules & Patterns
-
-### 1. State Colocation & Re-render Optimization
-
-- **State Colocation**: Keep state as close as possible to the components that consume it.
-- **Composition to Prevent Re-renders**: Pass expensive static subtrees as `children` to wrapper components holding state so the children do not re-render when the wrapper updates.
-
-```tsx
-export function ExpandableCard({ title, children }: { title: string; children: React.ReactNode }) {
-  const [isOpen, setIsOpen] = useState(false);
-
-  return (
-    <div className="rounded-xl border p-4">
-      <button 
-        type="button"
-        onClick={() => setIsOpen(v => !v)}
-        className="flex w-full justify-between font-semibold"
-        aria-expanded={isOpen}
-      >
-        <span>{title}</span>
-        <span>{isOpen ? '−' : '+'}</span>
-      </button>
-      {isOpen && <div className="mt-3 pt-3 border-t">{children}</div>}
-    </div>
-  );
-}
-```
-
-### 2. Optimistic UI Updates & Concurrent Actions (`useOptimistic`, `useTransition`)
-
-- Provide instantaneous visual feedback for user actions without waiting for server network roundtrips.
-
-```tsx
-import { useOptimistic, useTransition } from 'react';
-
-export function TodoList({ todos, onAdd }: { todos: Todo[]; onAdd: (text: string) => Promise<void> }) {
-  const [isPending, startTransition] = useTransition();
-  const [optimisticTodos, addOptimisticTodo] = useOptimistic(
-    todos,
-    (state, newText: string) => [...state, { id: 'temp-' + Date.now(), text: newText, isPending: true }]
-  );
-
-  const handleAction = async (formData: FormData) => {
-    const text = formData.get('todo') as string;
-    if (!text?.trim()) return;
-
-    startTransition(async () => {
-      addOptimisticTodo(text);
-      await onAdd(text);
-    });
-  };
-
-  return (
-    <form action={handleAction} className="space-y-4">
-      <input name="todo" placeholder="Add a new task..." className="border p-2 rounded" />
-      <button type="submit" disabled={isPending} className="bg-primary text-white px-4 py-2 rounded">
-        {isPending ? 'Saving...' : 'Add'}
-      </button>
-      <ul className="divide-y">
-        {optimisticTodos.map(todo => (
-          <li key={todo.id} className={todo.isPending ? 'opacity-50 italic' : ''}>
-            {todo.text}
-          </li>
-        ))}
-      </ul>
-    </form>
-  );
-}
-```
-
-### 3. Derived State vs. Effects Anti-Pattern
-
-```tsx
-// [GOOD] Computed directly during render (or memoized if expensive)
-function SearchResults({ query, items }: { query: string; items: Item[] }) {
-  const filtered = useMemo(() => {
-    const q = query.trim().toLowerCase();
-    if (!q) return items;
-    return items.filter(i => i.title.toLowerCase().includes(q));
-  }, [query, items]);
-
-  return <List items={filtered} />;
-}
-```
-
-## Code Examples
-
-See `EXAMPLES.md` for detailed code examples and hook implementations.
-
-## Validation Checklist
-
-- [ ] Zero `useEffect` hooks used for derived calculations.
-- [ ] Every list mapping has a unique, non-index entity ID key.
-- [ ] Subcomponents declared in parent render functions are extracted to top-level scope.
-- [ ] Effects with event listeners, timers, or abortable requests include clean-up returns.
-- [ ] Reusable components are composed cleanly via `children` or render props.
-
-## Common Mistakes
-
-- Setting state inside `useEffect` based on prop changes rather than deriving values inline.
-- Declaring nested components within component bodies.
-- Using index keys causing input focus loss or animations breaking on list mutations.
-
-## Integration Notes
-
-- Pairs with `typescript` for type safety on props, generics, and ref forwarding.
-- Pairs with `ui-ux-pro` and `web-accessibility` for UI tokens and ARIA standards.

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

@@ -1,19 +0,0 @@
-# react Troubleshooting & Common Mistakes
-
-## 1. Infinite Render Loops in useEffect
-
-- **Symptom**: Browser freezes, "Maximum update depth exceeded" error.
-- **Root Cause**: Creating new object or array literals inside component body and passing them to useEffect dependency array.
-- **Fix**: Colocate state, compute derived state during render without useEffect, or use primitive dependency values.
-
-## 2. Stale Closures in Callbacks
-
-- **Symptom**: Event handler or setTimeout accesses outdated state values.
-- **Root Cause**: Callback closing over initial state without updated dependency.
-- **Fix**: Use functional state updates (`setCount(c => c + 1)`) or `useRef` for mutable references.
-
-## 3. Prop Drilling vs Context Performance
-
-- **Symptom**: Changing a small state variable causes the entire component tree to re-render.
-- **Root Cause**: Storing rapidly changing state in a single monolithic React Context.
-- **Fix**: Split contexts by domain or migrate client UI state to Zustand with granular selectors.

package/.agents/core/skills/react/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/react/react.md

@@ -1,93 +0,0 @@
-# React — Best Practices
-
-## Component Architecture
-
-- **Prefer function components** with hooks over class components
-- **One component per file** — name file same as component
-- **Composition over inheritance** — use children and render props
-- **Keep components small** — if > 150 lines, split it
-
-## Hooks
-
-- **useState** for local state, **useReducer** for complex state
-- **useEffect** — always specify dependencies, clean up subscriptions
-- **Custom hooks** — extract reusable logic into `use*` functions
-- **useMemo/useCallback** — only when you have measured a performance problem
-
-## State Management
-
-- **Local state first** — don't reach for global state until you need it
-- **Lift state up** — find the closest common ancestor
-- **Context** — for cross-cutting concerns (theme, auth, locale)
-- **External store** (Zustand, Jotai) — for truly global, frequently updated state
-
-## Patterns
-
-### Container/Presenter
-
-```tsx
-// Container — handles logic
-function UserListContainer() {
-  const users = useUsers();
-  return <UserList users={users} />;
-}
-
-// Presenter — handles display
-function UserList({ users }: { users: User[] }) {
-  return <ul>{users.map(u => <UserItem key={u.id} user={u} />)}</ul>;
-}
-```
-
-### Error Boundaries
-
-- Wrap major sections in Error Boundaries
-- Provide meaningful fallback UI
-- Log errors to monitoring service
-
-### Loading States
-
-- Always handle: `loading`, `error`, `empty`, `data` states
-- Use Suspense where supported
-- Show skeleton screens, not spinners
-
-## Performance
-
-- **React.memo** — only for expensive renders with stable props
-- **Code splitting** — lazy load routes and heavy components
-- **Virtualization** — for lists > 100 items
-- **Image optimization** — use next/image or lazy loading
-- **Avoid** — inline object/array creation in JSX props
-
-## Anti-Patterns (Avoid)
-
-- [FAIL] Props drilling more than 2 levels — use Context or state management
-- [FAIL] useEffect for derived state — use useMemo instead
-- [FAIL] Index as key — use stable unique IDs
-- [FAIL] Mutating state directly — always create new references
-- [FAIL] God components — split into smaller, focused components
-- [FAIL] Business logic in components — extract to hooks or services
-
-## Testing
-
-- **React Testing Library** — test behavior, not implementation
-- Test user interactions, not component internals
-- Mock API calls, not React hooks
-- Use `screen.getByRole` over `getByTestId`
-
-## File Structure
-
-```
-components/
-  Button/
-    Button.tsx
-    Button.test.tsx
-    Button.module.css
-    index.ts
-hooks/
-  useAuth.ts
-  useDebounce.ts
-services/
-  api.ts
-types/
-  user.ts
-```

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

@@ -1,10 +0,0 @@
-id: react
-name: React
-category: frontend
-tags: [frontend, spa, jsx, components, hooks]
-requires: [typescript]
-optional: [tailwind, react-query, zustand, next-auth]
-conflicts: [vue, angular, svelte]
-weight: 8
-documents:
-  - react.md