contextos-agents 2.1.0 → 2.2.0

package/catalog/skills/ci-cd/EXAMPLES.md

@@ -0,0 +1,79 @@
+# CI/CD - Examples & GitHub Actions Configurations
+
+## Example 1: Production Quality Gate Workflow
+
+```yaml
+# .github/workflows/ci.yml
+name: CI Quality Gates
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    name: Lint, Types & Security
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - name: Install Dependencies
+        run: npm ci
+
+      - name: Secret Scan
+        run: npm run check:secrets
+
+      - name: Linter & Format Check
+        run: npm run lint
+
+      - name: Type Check
+        run: npx tsc --noEmit
+
+      - name: Unit Tests with Coverage
+        run: npm test -- --coverage
+
+      - name: Build Verification
+        run: npm run build
+
+      - name: Dependency Audit
+        run: npm audit --audit-level=high
+```
+
+---
+
+## Example 2: Polyglot Matrix Test Stage
+
+```yaml
+  test-matrix:
+    name: Node Test Matrix
+    needs: quality
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version: ['20', '22']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+      - run: npm ci
+      - run: npm test
+```

package/catalog/skills/ci-cd/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: ci-cd
+description: Automates CI/CD pipeline setup. Enforces unskippable quality gates, shift-left static analysis, secret scanning, and hardened GitHub Actions workflows.
+---
+
+# CI/CD and Automation
+
+Automate quality gates so no change reaches production without passing tests, lint, type checking, security scans, and build verification.
+
+## Core Philosophy
+
+- **Shift Left**: Catch problems as early in the delivery lifecycle as possible. A defect caught during static analysis or linting takes seconds to fix; the same defect discovered in production takes hours and damages reliability.
+- **Faster is Safer**: Small, frequent, automated releases drastically lower blast radius and risk compared to infrequent bulk deployments.
+- **Unskippable Gates Invariant**: Never disable a failing rule or skip a test suite just to make a pipeline green. Fix the root cause in the code.
+
+## The Quality Gate Pipeline
+
+Every Pull Request must successfully traverse these automated stages before merge approval:
+
+```
+Pull Request Opened
+       │
+       ▼
+ 1. Secret Scanning    (prevent credential leaks before running untrusted steps)
+       │
+       ▼
+ 2. Lint & Formatting  (eslint, prettier, markdownlint)
+       │
+       ▼
+ 3. Type Checking      (tsc --noEmit, pyright, mypy)
+       │
+       ▼
+ 4. Unit Tests         (vitest, jest, pytest with coverage thresholds)
+       │
+       ▼
+ 5. Production Build   (bundling, tree-shaking, static generation)
+       │
+       ▼
+ 6. Integration Tests  (API contracts, database migrations)
+       │
+       ▼
+ 7. Security Audit     (npm audit, trivy, dependency vulnerability checks)
+       │
+       ▼
+ 8. Bundle Budget      (bundle size checks against baseline thresholds)
+       │
+       ▼
+   Merge Allowed
+```
+
+## Hardened Pipeline Standards
+
+1. **Least-Privilege Token Permissions**:
+   Explicitly declare workflow and job permissions at the top of the workflow file. Default to read-only access:
+   ```yaml
+   permissions:
+     contents: read
+   ```
+2. **Deterministic Dependency Installation**:
+   Always use frozen lockfiles (`npm ci` instead of `npm install`, `uv sync --frozen` instead of `pip install`).
+3. **Concurrency Cancellation**:
+   Automatically cancel in-progress runs when a newer commit is pushed to the same Pull Request branch:
+   ```yaml
+   concurrency:
+     group: ${{ github.workflow }}-${{ github.ref }}
+     cancel-in-progress: true
+   ```
+4. **Action Pinning**:
+   Reference trusted actions using verified release tags (e.g. `actions/checkout@v4`) or full commit SHAs.

package/catalog/skills/ci-cd/TROUBLESHOOTING.md

@@ -0,0 +1,52 @@
+# CI/CD - Troubleshooting & Common Edge Cases
+
+## Common Diagnostic Scenarios
+
+### 1. Flaky Integration Tests in CI Environments
+
+- **Symptom**: Test suite randomly fails in GitHub Actions but always passes on developer machines.
+- **Root Cause**: Race conditions, port collisions, unawaited background tasks, or timezone dependencies (`new Date().getHours()`) differing between UTC runners and local environments.
+- **Fix Protocol**:
+  1. Fix runner timezones to UTC in CI setup steps (`TZ: 'UTC'`).
+  2. Eliminate hardcoded ports in integration tests; use ephemeral ports (`0`) or testcontainers.
+  3. Ensure all asynchronous operations and database transactions are explicitly awaited before asserting and tearing down.
+  4. Never use `retry` plugins to mask flaky tests; isolate the asynchronous race condition.
+
+---
+
+### 2. GitHub Actions Token Permission Denied (`Resource not accessible by integration`)
+
+- **Symptom**: CI workflow fails at the checkout, comment, or release stage with an authorization error.
+- **Root Cause**: The repository enforces secure defaults with read-only tokens, but the workflow needs to write statuses, PR comments, or packages.
+- **Fix Protocol**:
+  - Declare explicit, least-privilege permissions at the job level rather than granting global admin rights:
+    ```yaml
+    jobs:
+      comment-pr:
+        runs-on: ubuntu-latest
+        permissions:
+          contents: read
+          pull-requests: write
+    ```
+
+---
+
+### 3. Exceeded Runner Minutes & Slow CI Builds
+
+- **Symptom**: Workflow takes > 15 minutes to run, exhausting GitHub Actions free-tier minutes.
+- **Root Cause**: Running `npm install` without package manager caching, sequential execution of independent checks, and missing concurrency cancellation.
+- **Fix Protocol**:
+  1. Use `actions/setup-node@v4` with `cache: 'npm'` to reuse cached node_modules across runs.
+  2. Split monolithic jobs into parallel jobs: run lint, type-check, and unit tests concurrently.
+  3. Add `concurrency` cancellation to cancel stale builds when a developer pushes new commits to an open PR.
+
+---
+
+### 4. Bundle Size Budget Check Failures
+
+- **Symptom**: PR fails on `bundlesize` check with `Bundle size exceeded by 4.2 KB`.
+- **Root Cause**: An imported third-party library pulled in heavy un-treeshaken dependencies or large date/locale libraries.
+- **Fix Protocol**:
+  1. Inspect the bundle visualizer or source map explorer.
+  2. Replace broad root imports (`import { map } from 'lodash'`) with direct submodule imports (`import map from 'lodash/map'`).
+  3. Dynamically import heavy UI widgets (modals, charts, rich text editors) using `React.lazy()` or `next/dynamic`.

package/catalog/skills/ci-cd/VALIDATION.json

@@ -0,0 +1,11 @@
+{
+  "skill": "ci-cd",
+  "version": "1.0.0",
+  "checks": [
+    "Shift-left quality gates pipeline implemented in order",
+    "Least-privilege token permissions declared (contents: read)",
+    "Deterministic dependency installation enforced with frozen lockfile",
+    "Concurrency cancellation configured for PR branch updates",
+    "Unskippable gates invariant enforced without disabling rules"
+  ]
+}

package/catalog/skills/ci-cd/skill.yaml

@@ -0,0 +1,13 @@
+schemaVersion: 2
+name: ci-cd
+description: Shift-left CI/CD pipeline automation inspired by Addy Osmani. Enforces unskippable quality gates, least-privilege token permissions, and deterministic GitHub Actions workflows.
+version: 1.0.0
+category: devops
+type: instruction-only
+requires:
+  - engineering-workflow
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json

package/catalog/skills/database/EXAMPLES.md

@@ -0,0 +1,74 @@
+# Database Examples - Anti-patterns vs ContextOS Standard
+
+## Example 1: Solving the N+1 Query Problem
+
+### Anti-pattern: Anti-pattern (N+1 database queries in a loop)
+
+```typescript
+// BAD: 1 query for users + N queries for posts!
+const users = await prisma.user.findMany();
+const usersWithPosts = [];
+for (const user of users) {
+  const posts = await prisma.post.findMany({ where: { userId: user.id } }); // N queries!
+  usersWithPosts.push({ ...user, posts });
+}
+```
+
+### Best practice: ContextOS Standard (Batch query or relational include)
+
+```typescript
+// GOOD: 1 single optimized batch query
+const usersWithPosts = await prisma.user.findMany({
+  where: { isActive: true },
+  select: {
+    id: true,
+    name: true,
+    email: true,
+    posts: {
+      where: { published: true },
+      select: { id: true, title: true, createdAt: true },
+      take: 5
+    }
+  }
+});
+```
+
+---
+
+## Example 2: Safe Atomic Transactions with Locking
+
+### Anti-pattern: Anti-pattern (Unprotected read-modify-write race condition)
+
+```typescript
+// BAD: race condition between reading balance and updating
+const account = await prisma.account.findUnique({ where: { id } });
+if (account.balance >= amount) {
+  await prisma.account.update({
+    where: { id },
+    data: { balance: account.balance - amount }
+  });
+}
+```
+
+### Best practice: ContextOS Standard (Atomic conditional update in transaction)
+
+```typescript
+// GOOD: atomic database transaction with invariant check
+export async function deductBalance(accountId: string, amount: number) {
+  return await prisma.$transaction(async (tx) => {
+    const updated = await tx.account.updateMany({
+      where: {
+        id: accountId,
+        balance: { gte: amount }
+      },
+      data: {
+        balance: { decrement: amount }
+      }
+    });
+
+    if (updated.count === 0) {
+      throw new InsufficientFundsError(accountId);
+    }
+  });
+}
+```

package/catalog/skills/database/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: database
+description: Database architecture, schema design, Prisma, Drizzle ORM, indexing strategies, migrations, and N+1 query resolution.
+---
+
+# database
+
+## Overview
+
+Relational database design, query optimization, migration safety, connection pooling in serverless environments, and ORM usage across PostgreSQL, Prisma, and Drizzle.
+
+## When to Use
+
+Activate for tasks involving database schema design, migrations, indexing, relational models, ORM queries, transactions, or query performance tuning.
+
+## Rules & Patterns
+
+### Negative Constraints (What NOT to Do)
+
+1. **NEVER do `SELECT *` in production**: Always select explicit columns required by the caller to minimize memory bandwidth and lock footprint.
+2. **NEVER run destructive migrations without backward compatibility**: Always follow expand-and-contract (Phase 1: add new column as nullable; Phase 2: backfill; Phase 3: make non-nullable & remove old column).
+3. **NEVER execute queries in loops (The N+1 Anti-Pattern)**: Always use batch loading (`inArray`, `DataLoader`, or relational `include` / `JOIN`).
+4. **NEVER leave foreign keys without indexes**: In PostgreSQL/MySQL, child foreign key columns must always have an index to prevent table-level locking on cascade deletes.
+5. **NEVER perform multi-entity writes without a database transaction**: Any operation touching multiple records must use `prisma.$transaction` or `db.transaction`.
+6. **NEVER open unpooled database connections in Serverless / Edge functions**: Serverless scale-outs will instantly exhaust PostgreSQL's `max_connections`.
+
+---
+
+### Zero-Downtime Migrations (Expand-and-Contract)
+
+When modifying schemas with zero downtime:
+
+1. **Phase 1 (Expand)**: Add the new column as `NULLABLE` (or with a default value). Deploy the application code that reads from old column and writes to both old and new.
+2. **Phase 2 (Backfill)**: Run an asynchronous batch migration job in chunks (e.g. 1000 rows at a time) to populate data from old column to new column.
+3. **Phase 3 (Contract)**: Update application code to read and write exclusively from the new column.
+4. **Phase 4 (Cleanup)**: Once traffic is fully shifted, remove the old column and mark the new column as `NOT NULL` in a separate migration.
+
+---
+
+### Serverless & Edge Connection Pooling
+
+In serverless environments (AWS Lambda, Vercel Functions):
+
+- Always connect via a connection pooler:
+  - **Prisma**: Use Prisma Accelerate or configure transaction mode connection URLs.
+  - **Drizzle / Node-Postgres**: Use `@neondatabase/serverless` or connect to PgBouncer pooler port (`6543`) with `max: 1` per serverless container.
+- Set strict statement timeouts (e.g. `statement_timeout = '5000'`) to prevent hanging queries from exhausting pool capacity.
+
+---
+
+### Indexing & Performance Rules
+
+- **B-Tree Indexes**: For high-cardinality filters (`status`, `user_id`, `created_at`).
+- **Composite Indexes**: When querying multiple columns together (`WHERE organization_id = ? AND status = ?`), order columns in index by equality first, range second.
+- **Partial Indexes**: For sparse boolean flags (`WHERE is_processed = false`).
+- **Covering Indexes**: Include frequently selected columns (`INCLUDE (title, created_at)`) to enable index-only scans without table heap access.
+
+---
+
+## Code Examples
+
+### Zero-Downtime Column Rename (Drizzle ORM)
+
+```typescript
+// Step 1 (Expand): Keep old column, add new column
+export const users = pgTable('users', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  fullName: varchar('full_name', { length: 255 }), // new column
+  name: varchar('name', { length: 255 }),           // old column kept during transition
+});
+
+// App write logic during transition:
+await db.insert(users).values({
+  name: input.name,
+  fullName: input.name
+});
+```
+
+---
+
+## Validation Checklist
+
+- [ ] All database queries select explicit required columns (no `SELECT *`).
+- [ ] Foreign keys have matching indexes on child tables.
+- [ ] Multi-table writes wrapped in ACID transactions.
+- [ ] No N+1 queries in loops.
+- [ ] Schema migrations tested against expand-and-contract pattern.
+- [ ] Serverless database connection string uses pooling proxy.
+
+---
+
+## Common Mistakes
+
+- **Missing pagination limits**: Unbounded `findMany()` calls leading to Out-Of-Memory crashes under production volume.
+- **Locking entire tables**: Adding `NOT NULL` columns with heavy compute defaults in PostgreSQL without concurrent index creation.
+
+---
+
+## Integration Notes
+
+- Interacts with `system-design`, `ddd`, and `security` (multi-tenant tenantId scoping).

package/catalog/skills/database/TROUBLESHOOTING.md

@@ -0,0 +1,18 @@
+# Database Troubleshooting Guide
+
+## Common Issues & Fixes
+
+### 1. Connection Pool Exhaustion in Serverless / Edge
+
+- **Cause**: Creating a new PrismaClient / DB connection instance on every serverless function invocation.
+- **Fix**: Declare PrismaClient as a global singleton across warm lambdas, and enable PgBouncer or Prisma Accelerate.
+
+### 2. Slow Queries on Large Tables
+
+- **Cause**: Missing composite index on filtered and ordered columns.
+- **Fix**: Run `EXPLAIN ANALYZE <query>` and add targeted indexes matching the WHERE and ORDER BY columns.
+
+### 3. Database Deadlocks during Concurrent Transactions
+
+- **Cause**: Different transactions updating resources in different orders.
+- **Fix**: Always acquire locks and update entities in a deterministic alphabetical or ID-ordered sequence.

package/catalog/skills/database/VALIDATION.json

@@ -0,0 +1,11 @@
+{
+  "skill": "database",
+  "version": "1.0.0",
+  "checks": [
+    "No SELECT * in application queries",
+    "All foreign keys indexed",
+    "Multi-table writes enclosed in database transactions",
+    "No N+1 queries in loops",
+    "Safe expand-and-contract migration strategy"
+  ]
+}

package/catalog/skills/database/skill.yaml

@@ -0,0 +1,14 @@
+schemaVersion: 2
+name: database
+description: Database architecture, schema design, Prisma, Drizzle ORM, indexing strategies, migrations, and N+1 query resolution.
+version: 1.0.0
+category: backend
+type: instruction-only
+requires:
+  - system-design
+  - typescript
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json

package/catalog/skills/ddd/EXAMPLES.md

@@ -0,0 +1,42 @@
+# ddd Examples - Anti-patterns vs ContextOS Standard
+
+## Example 1: Domain Entities vs Anemic Models
+
+### Anti-pattern: Anemic Domain Model with Leaky Setters
+
+```typescript
+// BAD: Zero business invariants; any caller can corrupt state
+class BankAccount {
+  public balance: number = 0;
+  public isFrozen: boolean = false;
+}
+
+// Logic leaked into controller or service
+account.balance -= 500; // Overdraft not checked!
+```
+
+### Best practice: ContextOS Standard (Rich Domain Model with Guarded Invariants)
+
+```typescript
+// GOOD: Invariants strictly enforced inside Aggregate Root
+class BankAccount {
+  private _balance: number;
+  private _isFrozen: boolean;
+
+  constructor(id: string, initialDeposit: Money) {
+    this._balance = initialDeposit.amount;
+    this._isFrozen = false;
+  }
+
+  public withdraw(amount: Money): void {
+    if (this._isFrozen) {
+      throw new AccountFrozenException('Cannot withdraw from a frozen account');
+    }
+    if (this._balance < amount.amount) {
+      throw new InsufficientFundsException('Insufficient funds for withdrawal');
+    }
+    this._balance -= amount.amount;
+    this.addDomainEvent(new MoneyWithdrawnEvent(this.id, amount));
+  }
+}
+```