contextos-agents 2.1.0 → 2.1.1

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));
+  }
+}
+```

package/catalog/skills/ddd/SKILL.md

@@ -0,0 +1,247 @@
+---
+name: Domain-Driven Design
+description: >
+  ContextOS skill for Domain-Driven Design
+---
+
+# Domain-Driven Design
+
+## Overview
+
+Domain-Driven Design standard for robust business software. Enforces separation between domain logic (Entities, Value Objects, Aggregates, Domain Events) and infrastructure frameworks, preventing leaky abstractions.
+
+## When to Use
+
+Activate when designing core business domain models, transactional consistency boundaries, enterprise APIs, or complex aggregate hierarchies.
+
+## Rules & Patterns
+<!-- Source: ddd.md -->
+
+## Domain-Driven Design - Patterns & Practices
+
+## When to Use DDD
+
+**Use when:**
+
+- Complex business logic that goes beyond CRUD
+- Multiple domain experts with different vocabularies
+- The domain model is the competitive advantage
+- Enterprise-grade applications
+
+**Don't use when:**
+
+- Simple CRUD applications
+- Hackathon/MVP (overkill)
+- No domain expert available
+
+## Strategic Design
+
+### Bounded Contexts
+
+The single most important DDD concept. A Bounded Context is a boundary within which a particular model is defined and applicable.
+
+**Example - E-Commerce:**
+
+```
+[Order Context]          [Payment Context]       [Shipping Context]
+  - Order                  - Payment               - Shipment
+  - OrderItem              - Transaction            - TrackingNumber
+  - Customer (ref)         - Refund                 - Address
+  - Address (value)        - Invoice                - Carrier
+```
+
+`Customer` means different things in each context:
+
+- Order Context: name, email, shipping preference
+- Payment Context: billing info, payment methods
+- Support Context: ticket history, satisfaction score
+
+### Context Map
+
+```
+[Order] ←→ [Payment]     # Partnership
+[Order] → [Shipping]     # Customer-Supplier
+[Order] → [Legacy CRM]   # Anti-Corruption Layer
+```
+
+## Tactical Design
+
+### Entities
+
+Objects with identity. Two entities with the same attributes but different IDs are different.
+
+```typescript
+class User {
+  readonly id: UserId;
+  name: string;
+  email: Email;  // Value Object
+}
+```
+
+### Value Objects
+
+Objects defined by their attributes, not identity. Immutable.
+
+```typescript
+class Email {
+  constructor(readonly value: string) {
+    if (!isValidEmail(value)) throw new InvalidEmailError(value);
+  }
+  equals(other: Email): boolean {
+    return this.value === other.value;
+  }
+}
+```
+
+### Aggregates
+
+A cluster of entities and value objects with a single root entity (Aggregate Root). All access goes through the root.
+
+```typescript
+class Order {  // Aggregate Root
+  private items: OrderItem[] = [];
+  
+  addItem(product: ProductRef, quantity: number): void {
+    // Business logic HERE, not in a service
+    if (quantity <= 0) throw new InvalidQuantityError();
+    this.items.push(new OrderItem(product, quantity));
+  }
+  
+  get total(): Money {
+    return this.items.reduce((sum, item) => sum.add(item.subtotal), Money.zero());
+  }
+}
+```
+
+**Aggregate Rules:**
+
+1. Reference other aggregates by ID only
+2. One aggregate per transaction
+3. Eventual consistency between aggregates
+
+### Domain Events
+
+Something that happened in the domain that domain experts care about.
+
+```typescript
+class OrderPlaced implements DomainEvent {
+  constructor(
+    readonly orderId: OrderId,
+    readonly customerId: CustomerId,
+    readonly total: Money,
+    readonly occurredAt: Date
+  ) {}
+}
+```
+
+### Domain Services
+
+Business logic that doesn't naturally belong to an entity or value object.
+
+```typescript
+class PricingService {
+  calculatePrice(order: Order, customer: Customer, promotions: Promotion[]): Money {
+    // Complex pricing logic involving multiple aggregates
+  }
+}
+```
+
+### Repositories
+
+Abstraction over data access. One repository per aggregate root.
+
+```typescript
+interface OrderRepository {
+  findById(id: OrderId): Promise<Order | null>;
+  save(order: Order): Promise<void>;
+  delete(id: OrderId): Promise<void>;
+}
+```
+
+## Directory Structure (DDD)
+
+```
+src/
+├── modules/
+│   └── orders/                    # Bounded Context
+│       ├── domain/
+│       │   ├── entities/
+│       │   │   └── order.ts       # Aggregate Root
+│       │   ├── value-objects/
+│       │   │   └── money.ts
+│       │   ├── events/
+│       │   │   └── order-placed.ts
+│       │   ├── services/
+│       │   │   └── pricing.ts
+│       │   └── repositories/
+│       │       └── order.repository.ts  # Interface
+│       ├── application/
+│       │   ├── commands/
+│       │   │   └── place-order.ts
+│       │   ├── queries/
+│       │   │   └── get-order.ts
+│       │   └── handlers/
+│       │       └── place-order.handler.ts
+│       └── infrastructure/
+│           ├── persistence/
+│           │   └── order.repository.impl.ts  # Implementation
+│           └── api/
+│               └── orders.controller.ts
+```
+
+### The Clean Architecture Dependency Rule
+
+In DDD, dependencies **MUST strictly point inward**:
+
+```
+[ Frameworks & Drivers (Web, DB, UI) ]
+      └──▶ [ Interface Adapters (Controllers, Gateways) ]
+            └──▶ [ Application (Use Cases, CQRS Handlers) ]
+                  └──▶ [ Domain (Entities, Value Objects) ]
+```
+
+- The **Domain layer** has ZERO dependencies on ORMs (Prisma, TypeORM), HTTP frameworks (Express, NestJS), or external SDKs.
+- Repositories are defined as interfaces in the domain/application layer and implemented in the infrastructure layer.
+
+### Domain Events vs Integration Events
+
+1. **Domain Events**: Represent state changes inside a single Bounded Context.
+   - Raised directly inside the Aggregate Root (`order.addItem(...)` raises `OrderItemAdded`).
+   - Dispatched in-process before transaction commit.
+2. **Integration Events**: Published across Bounded Context boundaries to communicate with other services.
+   - Dispatched via Transactional Outbox pattern to message brokers.
+   - Must use backward-compatible schemas with versioning.
+
+### Anti-Corruption Layer (ACL)
+
+When consuming data from an external bounded context or 3rd-party vendor API (e.g. Stripe, Salesforce):
+
+- NEVER import external domain models directly into your domain.
+- Create an **ACL Translator / Adapter** in the infrastructure layer to convert external DTOs into your own Value Objects and Entities.
+
+---
+
+## Anti-Patterns
+
+- [FAIL] Anemic domain model - entities with only getters/setters, all logic in services
+- [FAIL] Big aggregate - aggregates should be small, focused on invariants
+- [FAIL] Cross-aggregate transactions - use eventual consistency
+- [FAIL] DDD everywhere - use DDD only where complexity justifies it
+- [FAIL] ORM entities leaking into Domain - domain entities must not depend on `@Entity()` or ORM decorators
+
+
+## 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/catalog/skills/ddd/TROUBLESHOOTING.md

@@ -0,0 +1,19 @@
+# ddd Troubleshooting & Common Mistakes
+
+## 1. God Aggregates
+
+- **Symptom**: Aggregate Root contains 20 child entities and loading it requires joining dozens of tables.
+- **Root Cause**: Treating ERD tables as aggregate boundaries rather than transactional consistency units.
+- **Fix**: Design small aggregates. Reference other aggregates by ID only, not by object reference.
+
+## 2. Leaking Infrastructure into Domain Layer
+
+- **Symptom**: Domain entities import Prisma, TypeORM decorators, or Express Request objects.
+- **Root Cause**: Inverting Clean Architecture boundaries.
+- **Fix**: The Domain layer must be pure TypeScript with zero external framework dependencies.
+
+## 3. Transaction Spanning Multiple Aggregates
+
+- **Symptom**: High database lock contention and deadlocks under concurrent transactions.
+- **Root Cause**: Modifying multiple aggregate roots within the same database transaction.
+- **Fix**: Rule of thumb: Exactly one Aggregate Root modified per transaction. Use Domain Events for eventual consistency across other aggregates.

package/catalog/skills/ddd/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/catalog/skills/ddd/skill.yaml

@@ -0,0 +1,14 @@
+schemaVersion: 2
+id: ddd
+name: Domain-Driven Design
+category: architecture
+type: instruction-only
+requires: []
+optional: [microservices, system-design]
+conflicts: []
+weight: 6
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json

package/catalog/skills/decisions/EXAMPLES.md

@@ -0,0 +1,35 @@
+# decisions Examples - Anti-patterns vs ContextOS Standard
+
+## Example 1: Documenting Tech Choices
+
+### Anti-pattern: Tribal Knowledge & Undocumented Decisions
+
+```text
+"We switched to Redis for session storage last month because Dan said so on Slack."
+Three months later, Dan leaves and nobody knows why the config is set up this way.
+```
+
+### Best practice: ContextOS Standard (MADR Architecture Decision Record)
+
+```markdown
+# ADR 0003: Use Redis for Distributed Session Storage
+
+## Context and Problem Statement
+Our application is transitioning from a single server to horizontally auto-scaled instances.
+Sticky sessions on load balancer cause uneven distribution and drop sessions on node recycling.
+
+## Considered Options
+1. PostgreSQL session table
+2. Redis cluster
+3. JWT stateless tokens in cookies
+
+## Decision Outcome
+Chosen option: "Redis cluster", because:
+- Sub-millisecond read/write latency compared to relational DB queries.
+- Built-in TTL automatically handles session expiration without cron cleanup.
+- Avoids security risks of client-stored JWT revocation.
+
+## Consequences
+- Positive: Stateless web tier, zero session drops on deployment.
+- Negative: Adds operational dependency on Redis cluster infrastructure.
+```