contextos-agents 1.5.0

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

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

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

@@ -0,0 +1,19 @@
+# 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/core/skills/node/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/node/node.md

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

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

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

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

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

@@ -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/performance/performance.md

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

@@ -0,0 +1,10 @@
+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/ponytail-mindset/EXAMPLES.md

@@ -0,0 +1,45 @@
+# ponytail-mindset Examples — Anti-patterns vs ContextOS Standard
+
+## Example 1: Data Formatting and Manipulation
+
+### Anti-pattern: Over-engineered Custom Utility Class
+
+```typescript
+// BAD: 40 lines of boilerplate for relative date formatting
+export class DateFormatterService {
+  private static instance: DateFormatterService;
+  public static getInstance() { /* singleton boilerplate */ }
+  public formatRelative(date: Date): string {
+    const diff = Date.now() - date.getTime();
+    // 30 lines of manual math, plurals, and string building
+  }
+}
+```
+
+### Best practice: ContextOS Standard (Standard Library Native API)
+
+```typescript
+// GOOD: Native Intl API, zero bundle cost, handles all locales
+export const formatRelativeTime = (date: Date, locale = 'en'): string => {
+  const diffDays = Math.round((date.getTime() - Date.now()) / (1000 * 60 * 60 * 24));
+  return new Intl.RelativeTimeFormat(locale, { numeric: 'auto' }).format(diffDays, 'day');
+};
+```
+
+---
+
+## Example 2: Component Library Reuse
+
+### Anti-pattern: Hand-rolled Modal from Scratch
+
+```text
+BAD: Writing custom overlay DOM, manual scroll locking, manual focus trapping,
+and custom keydown listeners. Burns 300+ lines of fragile code.
+```
+
+### Best practice: ContextOS Standard (Leverage Established Primitives)
+
+```bash
+# GOOD: Install battle-tested primitive that handles ARIA, portals, and keyboard navigation
+npx shadcn@latest add dialog
+```