contextos-agents 1.6.1 → 2.0.0-beta.2

package/.agents/core/skills/nestjs/nestjs.md

@@ -1,103 +0,0 @@
-# NestJS — Best Practices
-
-## Module Architecture
-
-- **One module per domain** — `UsersModule`, `AuthModule`, `OrdersModule`
-- **Feature modules** — encapsulate related controllers, services, repositories
-- **Shared module** — for cross-cutting concerns (logging, config, utils)
-- **Core module** — singleton services (database, auth guards)
-
-```
-src/
-├── modules/
-│   ├── users/
-│   │   ├── users.module.ts
-│   │   ├── users.controller.ts
-│   │   ├── users.service.ts
-│   │   ├── users.repository.ts
-│   │   ├── dto/
-│   │   │   ├── create-user.dto.ts
-│   │   │   └── update-user.dto.ts
-│   │   ├── entities/
-│   │   │   └── user.entity.ts
-│   │   └── users.spec.ts
-│   └── auth/
-├── shared/
-│   ├── guards/
-│   ├── interceptors/
-│   ├── pipes/
-│   └── filters/
-├── config/
-└── app.module.ts
-```
-
-## Dependency Injection
-
-```typescript
-@Injectable()
-export class UsersService {
-  constructor(
-    @InjectRepository(User) private readonly usersRepo: Repository<User>,
-    private readonly configService: ConfigService,
-  ) {}
-}
-```
-
-- Prefer constructor injection
-- Use custom providers for complex setup
-- Scope: default is Singleton, use REQUEST scope only when needed
-
-## DTOs and Validation
-
-```typescript
-import { IsEmail, IsString, MinLength } from 'class-validator';
-
-export class CreateUserDto {
-  @IsEmail()
-  email: string;
-
-  @IsString()
-  @MinLength(2)
-  name: string;
-}
-```
-
-- Always use DTOs for request validation
-- Use `ValidationPipe` globally
-- Separate Create/Update/Response DTOs
-
-## Guards, Interceptors, Pipes
-
-| Type | Purpose |
-| --- | --- |
-| **Guards** | Authentication, authorization |
-| **Interceptors** | Logging, transformation, caching |
-| **Pipes** | Validation, transformation |
-| **Filters** | Exception handling |
-
-Execution order: Guards → Interceptors → Pipes → Handler → Interceptors → Filters
-
-## Error Handling
-
-```typescript
-@Catch()
-export class AllExceptionsFilter implements ExceptionFilter {
-  catch(exception: unknown, host: ArgumentsHost) {
-    // Transform to standard error format
-  }
-}
-```
-
-## Testing
-
-- **Unit tests** — mock dependencies with `Test.createTestingModule()`
-- **E2E tests** — use `supertest` with a test module
-- **Mock everything** — services should be testable in isolation
-
-## Anti-Patterns
-
-- [FAIL] Business logic in controllers — use services
-- [FAIL] Direct database access in controllers — use repositories
-- [FAIL] Circular dependencies — refactor module structure
-- [FAIL] God modules — split large modules by domain
-- [FAIL] Not using DTOs — always validate input

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

@@ -1,10 +0,0 @@
-id: nestjs
-name: NestJS
-category: backend
-tags: [backend, nodejs, typescript, enterprise, di, decorators]
-requires: [typescript, node]
-optional: [postgres, redis, docker, graphql]
-conflicts: [fastapi, express]
-weight: 8
-documents:
-  - nestjs.md

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

@@ -1,40 +0,0 @@
-# nextjs Examples — Anti-patterns vs ContextOS Standard
-
-## Example 1: Server Components vs Client Components
-
-### Anti-pattern: Marking the Entire Page as Client Component
-
-```tsx
-// BAD: app/dashboard/page.tsx with 'use client' at top
-// Bloats client bundle, loses SEO benefits, eliminates direct DB access
-'use client';
-
-export default function DashboardPage() {
-  const [data, setData] = useState(null);
-  useEffect(() => { fetch('/api/dashboard').then(...) }, []);
-  return <div>...</div>;
-}
-```
-
-### Best practice: ContextOS Standard (RSC by Default, Client Leaf Nodes)
-
-```tsx
-// GOOD: Server Component fetches data directly with zero bundle cost
-// app/dashboard/page.tsx (Server Component)
-import { Suspense } from 'react';
-import { db } from '@/lib/db';
-import { InteractiveChart } from './InteractiveChart'; // 'use client' leaf component
-
-export default async function DashboardPage() {
-  const stats = await db.analytics.getStats();
-  return (
-    <main>
-      <h1>Dashboard</h1>
-      <p>Total Revenue: {stats.revenue}</p>
-      <Suspense fallback={<ChartSkeleton />}>
-        <InteractiveChart initialData={stats.chartData} />
-      </Suspense>
-    </main>
-  );
-}
-```

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

@@ -1,163 +0,0 @@
----
-name: Next.js
-description: >
-  ContextOS skill for Next.js App Router, Server Components, Server Actions, performance optimization, and Vercel best practices.
----
-
-# Next.js App Router Best Practices
-
-## Overview
-
-Enforces high-performance architectural patterns for Next.js App Router based on Vercel Engineering guidelines: React Server Components (RSC), zero-waterfall async pipelines, request deduplication via `React.cache()`, bundle optimization, and secure Server Actions.
-
-## When to Use
-
-Activate whenever building, refactoring, or reviewing Next.js pages, layouts, Route Handlers (`app/api`), Server Actions, or components in the `app/` directory.
-
-## Negative Constraints (What NOT to Do)
-
-1. **NEVER use barrel imports for UI libraries**: Avoid `import { Button, Dialog } from '@/components'`. Import directly from the exact file (`import { Button } from '@/components/ui/button'`) to prevent bundler tree-shaking failures and trace bloat.
-2. **NEVER trust client-provided data or session state in Server Actions**: Always authenticate session and authorize tenant ownership inside the Server Action handler itself before mutating data.
-3. **NEVER introduce sequential `await` waterfalls for independent data**: Always use `Promise.all()` or parallel streaming `<Suspense>` boundaries.
-4. **NEVER pass large unneeded serialized data from Server to Client Components**: Only pass the specific primitive fields required by the client component (`server-dedup-props`).
-5. **NEVER use `useEffect` for data fetching**: Fetch directly in Server Components or use TanStack Query / SWR for client-side queries.
-6. **NEVER import server-only modules in client components**: Use the `server-only` package in data access layers to catch accidental client imports at build time.
-
-## Rules & Patterns
-
-### 1. Eliminating Async Waterfalls (Critical)
-
-- **Parallel Fetching**: Fetch independent data concurrently at the top of the route or component.
-- **Granular Streaming**: Wrap slow, non-critical subtrees in `<Suspense fallback={<Skeleton />}>` so critical above-the-fold content streams immediately.
-- **Defer Awaits**: Check cheap synchronous conditions before awaiting remote resources.
-
-### 2. Request Deduplication & Caching (`server-cache-react`)
-
-- Use `React.cache()` to deduplicate identical database or service calls across multiple components rendered in the same server request lifecycle.
-
-```tsx
-import { cache } from 'react';
-import { db } from '@/lib/db';
-
-export const getCurrentUser = cache(async (userId: string) => {
-  return await db.user.findUnique({
-    where: { id: userId },
-    select: { id: true, name: true, role: true, email: true }
-  });
-});
-```
-
-### 3. Secure Server Actions (`server-auth-actions`)
-
-- Treat every Server Action as a public HTTP endpoint. Always validate session, authorization, and input schema with Zod.
-
-```tsx
-'use server';
-
-import { z } from 'zod';
-import { auth } from '@/lib/auth';
-import { db } from '@/lib/db';
-import { revalidatePath } from 'next/cache';
-
-const UpdateProfileSchema = z.object({
-  name: z.string().min(2).max(50),
-});
-
-export async function updateProfile(formData: FormData) {
-  const session = await auth();
-  if (!session?.userId) throw new Error('Unauthorized');
-
-  const result = UpdateProfileSchema.safeParse({ name: formData.get('name') });
-  if (!result.success) return { error: 'Invalid input', issues: result.error.flatten() };
-
-  await db.user.update({
-    where: { id: session.userId },
-    data: { name: result.data.name },
-  });
-
-  revalidatePath('/settings');
-  return { success: true };
-}
-```
-
-### 4. Bundle Optimization & Dynamic Imports (`bundle-dynamic-imports`)
-
-- Heavy interactive client components (charts, rich-text editors, video players) must be dynamically loaded with `next/dynamic`.
-
-```tsx
-import dynamic from 'next/dynamic';
-
-const AnalyticsChart = dynamic(
-  () => import('@/components/analytics/chart').then(mod => mod.AnalyticsChart),
-  {
-    loading: () => <div className="h-64 animate-pulse bg-muted rounded-lg" />,
-    ssr: false,
-  }
-);
-```
-
-### 5. Next.js 15+ Async Request APIs (`async-params`)
-
-In Next.js 15+, `params`, `searchParams`, `cookies()`, and `headers()` are asynchronous and must be awaited:
-
-```tsx
-// [GOOD] Next.js 15+ Page Component
-interface PageProps {
-  params: Promise<{ id: string }>;
-  searchParams: Promise<{ [key: string]: string | string[] | undefined }>;
-}
-
-export default async function UserPage({ params, searchParams }: PageProps) {
-  const { id } = await params;
-  const { tab } = await searchParams;
-  const user = await getUser(id);
-
-  return <UserProfile user={user} activeTab={tab as string} />;
-}
-```
-
-### 6. Non-Blocking Background Tasks with `after()`
-
-To execute logging, analytics, or cache priming without delaying the user's HTTP response:
-
-```typescript
-import { after } from 'next/server';
-
-export async function POST(request: Request) {
-  const data = await request.json();
-  const result = await processOrder(data);
-
-  // Executes asynchronously AFTER the response stream has completed
-  after(async () => {
-    await sendSlackNotification(result);
-    await indexOrderInSearch(result.id);
-  });
-
-  return Response.json({ success: true, orderId: result.id });
-}
-```
-
----
-
-## Code Examples
-
-See `EXAMPLES.md` for detailed code examples and component templates.
-
-## Validation Checklist
-
-- [ ] All database queries in RSC layers use `React.cache()` if called across multiple components.
-- [ ] No barrel imports (`from '@/components'`); all imports point to exact component modules.
-- [ ] Server Actions have explicit auth checks and Zod input validation.
-- [ ] Heavy client widgets (charts, editors) use `next/dynamic`.
-- [ ] Images use `next/image` with explicit `sizes` and `priority` on LCP elements.
-
-## Common Mistakes
-
-- Using `'use client'` at page level instead of leaf components.
-- Relying on client-side authentication checks for Server Actions without server-side validation.
-- Chaining sequential awaits for independent data models.
-
-## Integration Notes
-
-- Pairs with `react` and `ui-ux-pro` for component design and state management.
-- Pairs with `security` for session authorization and input sanitization.

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

@@ -1,19 +0,0 @@
-# nextjs Troubleshooting & Common Mistakes
-
-## 1. Hydration Mismatch Errors
-
-- **Symptom**: "Text content does not match server-rendered HTML".
-- **Root Cause**: Rendering dates, window dimensions, or local storage data that differs between server render and client hydration.
-- **Fix**: Use suppressHydrationWarning on localized timestamps or load client-only state inside a useEffect after mount.
-
-## 2. Accidental Server Code Bundled to Client
-
-- **Symptom**: "Module not found: Can't resolve 'fs' or 'pg' in client bundle".
-- **Root Cause**: Client component importing a utility that transitively imports server-only database code.
-- **Fix**: Separate server utilities into *.server.ts and install import 'server-only'; at the top of server files.
-
-## 3. Waterfall Fetches in Server Components
-
-- **Symptom**: Page takes 3 seconds to load due to sequential await statements.
-- **Root Cause**: Awaiting independent data sources one after another.
-- **Fix**: Use Promise.all([fetchUsers(), fetchProducts()]) or separate into nested <Suspense> boundaries.

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

@@ -1,67 +0,0 @@
-# Next.js — Best Practices (App Router)
-
-## Routing
-
-- Use **App Router** (`app/` directory) — not Pages Router
-- **Layouts** — shared UI in `layout.tsx`, nested layouts for sections
-- **Loading states** — `loading.tsx` for Suspense boundaries
-- **Error handling** — `error.tsx` for error boundaries per route
-- **Not found** — `not-found.tsx` for 404 pages
-
-## Server vs Client Components
-
-- **Default to Server Components** — they're server by default
-- **Use `'use client'`** only when you need: event handlers, useState, useEffect, browser APIs
-- **Push client boundaries down** — keep as much as possible on the server
-- **Don't pass functions** from Server to Client components
-
-## Data Fetching
-
-- **Server Components** — fetch directly, no useEffect
-- **Server Actions** — for mutations (`'use server'`)
-- **Route Handlers** — `app/api/` for REST endpoints
-- **Parallel fetching** — use Promise.all for independent requests
-- **Caching** — leverage Next.js cache, revalidate strategically
-
-```tsx
-// Server Component — direct fetch
-async function UserProfile({ id }: { id: string }) {
-  const user = await getUser(id); // No useEffect needed
-  return <div>{user.name}</div>;
-}
-```
-
-## File Structure
-
-```
-app/
-├── layout.tsx              # Root layout
-├── page.tsx                # Home page
-├── globals.css
-├── (auth)/                 # Route group (no URL impact)
-│   ├── login/page.tsx
-│   └── register/page.tsx
-├── dashboard/
-│   ├── layout.tsx          # Dashboard layout
-│   ├── page.tsx            # Dashboard home
-│   └── settings/page.tsx
-├── api/
-│   └── users/route.ts      # API route
-└── components/             # Shared components
-```
-
-## Performance
-
-- **Image optimization** — always use `next/image`
-- **Font optimization** — use `next/font`
-- **Metadata** — export metadata object from pages
-- **Static generation** — prefer SSG over SSR when possible
-- **Edge runtime** — for latency-sensitive routes
-
-## Anti-Patterns
-
-- [FAIL] Using `useEffect` for data fetching in Server Components
-- [FAIL] Making everything a Client Component
-- [FAIL] Not using `loading.tsx` and `error.tsx`
-- [FAIL] Importing server-only code in Client Components
-- [FAIL] Not leveraging caching and revalidation

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

@@ -1,10 +0,0 @@
-id: nextjs
-name: Next.js
-category: frontend
-tags: [frontend, ssr, ssg, fullstack, react, app-router]
-requires: [react, typescript]
-optional: [tailwind, prisma, next-auth, react-query]
-conflicts: [vue, angular, remix]
-weight: 9
-documents:
-  - nextjs.md

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

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

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

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

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

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

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