contextos-agents 1.6.1 → 2.0.0-beta.2

package/.agents/generated/gemini/skills/node/SKILL.md

@@ -1,323 +0,0 @@
----
-name: Node.js
-description: >
-  ContextOS skill for Node.js
----
-# Node.js
-
-## Overview
-
-Production-grade Node.js runtime and server standard. Enforces async event loop non-blocking hygiene, graceful shutdown, structured JSON logging with correlation IDs, and unhandled rejection guards.
-
-## When to Use
-
-Activate when developing Node.js HTTP servers, Express/Fastify APIs, background workers, CLI tools, or stream-based data pipelines.
-
-## Negative Constraints (What NOT to Do)
-
-1. **NEVER execute synchronous filesystem/crypto calls in request handlers (`fs.readFileSync`)**: Always use async promises (`fs.promises.*`) to avoid blocking the event loop.
-2. **NEVER leave uncaught promise rejections**: Every async route must use `express-async-errors` or wrap operations in try/catch calling `next(err)`.
-3. **NEVER buffer large files/payloads entirely in memory (`fs.readFile`)**: Always use Streams or Pipelines (`stream.pipeline`) for processing large files.
-4. **NEVER store in-memory session or user state on a single process instance**: Use Redis or an external state store to allow multi-instance scaling.
-5. **NEVER ignore `SIGTERM` / `SIGINT` shutdown signals**: Always implement graceful shutdown to close open DB pools and drain active HTTP connections.
-
-## Rules & Patterns
-
-## 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
-```
-
-
-## 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.
-
-
-<!-- Source: node.md -->
-
-# 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
-```
-
-<!-- Source: EXAMPLES.md -->
-
-# Node.js Examples — Anti-patterns vs ContextOS Standard
-
-## Example 1: Graceful Process Shutdown
-
-### Anti-pattern: Anti-pattern (Abruptly killing process and dropping in-flight requests)
-
-```javascript
-// BAD: drops active database transactions and in-flight HTTP connections
-process.on('SIGTERM', () => {
-  process.exit(0);
-});
-```
-
-### Best practice: ContextOS Standard (Graceful connection draining)
-
-```typescript
-// GOOD: drains active requests, closes database connections, and exits safely
-import http from 'http';
-import { prisma } from './db';
-import { logger } from './logger';
-
-export function setupGracefulShutdown(server: http.Server) {
-  const shutdown = async (signal: string) => {
-    logger.info(`Received ${signal}. Starting graceful shutdown...`);
-    
-    server.close(async () => {
-      logger.info('HTTP server closed.');
-      try {
-        await prisma.$disconnect();
-        logger.info('Database pool closed.');
-        process.exit(0);
-      } catch (err) {
-        logger.error('Error during database disconnect:', err);
-        process.exit(1);
-      }
-    });
-
-    // Force shutdown after timeout if connections hang
-    setTimeout(() => {
-      logger.error('Forceful shutdown timeout reached.');
-      process.exit(1);
-    }, 10_000).unref();
-  };
-
-  process.on('SIGTERM', () => shutdown('SIGTERM'));
-  process.on('SIGINT', () => shutdown('SIGINT'));
-}
-```
-
----
-
-## Example 2: Stream-based File Processing
-
-### Anti-pattern: Anti-pattern (Loading entire 500MB file into buffer)
-
-```typescript
-// BAD: easily causes Out Of Memory (OOM) crashes under concurrency
-app.get('/download/:file', async (req, res) => {
-  const data = await fs.promises.readFile(`/uploads/${req.params.file}`);
-  res.send(data);
-});
-```
-
-### Best practice: ContextOS Standard (Piping read stream with pipeline)
-
-```typescript
-// GOOD: constant memory usage (O(1) RAM) regardless of file size
-import fs from 'fs';
-import { pipeline } from 'stream/promises';
-
-app.get('/download/:file', async (req, res, next) => {
-  try {
-    const filePath = `/uploads/${req.params.file}`;
-    const readStream = fs.createReadStream(filePath);
-    await pipeline(readStream, res);
-  } catch (err) {
-    next(err);
-  }
-});
-```
-
-<!-- Source: TROUBLESHOOTING.md -->
-
-# node Troubleshooting & Common Mistakes
-
-## 1. Unhandled Promise Rejections Crashing the Process
-
-- **Symptom**: Node process crashes abruptly without clear stack trace in production.
-- **Root Cause**: Missing `process.on('unhandledRejection')` handler in Node.js >= 15.
-- **Fix**: Always register top-level unhandledRejection and uncaughtException logging before exiting cleanly.
-
-## 2. Event Loop Starvation
-
-- **Symptom**: API endpoints stop responding or latency spikes to 10+ seconds.
-- **Root Cause**: Heavy synchronous operations (`JSON.parse` on a 50MB file, sync bcrypt hashing, or regex catastrophic backtracking).
-- **Fix**: Offload CPU-heavy tasks to Worker Threads or use async worker queues.
-
-## 3. Memory Leaks in Event Emitters
-
-- **Symptom**: "MaxListenersExceededWarning: Possible EventEmitter memory leak detected".
-- **Root Cause**: Adding listeners inside request handlers without removing them on close.
-- **Fix**: Remove listeners in cleanup callbacks or use `AbortController` signals.

package/.agents/generated/gemini/skills/performance/SKILL.md

@@ -1,185 +0,0 @@
----
-name: Web Performance
-description: >
-  ContextOS skill for Web Performance
----
-# 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.
-
-
-<!-- Source: performance.md -->
-
-# 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
-
-<!-- Source: EXAMPLES.md -->
-
-# 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>;
-}
-```
-
-<!-- Source: TROUBLESHOOTING.md -->
-
-# 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.