contextos-agents 1.7.0 → 2.0.0-beta.3

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

@@ -1,200 +0,0 @@
----
-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).
-
-
-<!-- Source: EXAMPLES.md -->
-
-# 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);
-    }
-  });
-}
-```
-
-<!-- Source: TROUBLESHOOTING.md -->
-
-# 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/.agents/generated/gemini/skills/ddd/SKILL.md

@@ -1,314 +0,0 @@
----
-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.
-
-
-<!-- Source: EXAMPLES.md -->
-
-# 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));
-  }
-}
-```
-
-<!-- Source: TROUBLESHOOTING.md -->
-
-# 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/.agents/generated/gemini/skills/decisions/SKILL.md

@@ -1,143 +0,0 @@
----
-name: decisions
-description: >
-  Architecture Decision Records (ADR) management. Creates, tracks, and queries architectural decisions so AI assistants understand why choices were made.
----
-# decision-engine
-
-## Overview
-
-Architecture Decision Record (ADR) system following Michael Nygard format. Captures context, options considered, tradeoffs, and consequences to prevent architectural regression and knowledge loss across AI sessions.
-
-## When to Use
-
-Activate when choosing or switching database engines, authentication strategies, state libraries, or significant architectural patterns.
-
-## Rules & Patterns
-
-You manage **Architecture Decision Records** (ADRs).
-
-## Why Decisions Matter
-
-Without ADRs, the AI agent sees:
-
-- "Database: PostgreSQL" — but doesn't know WHY
-- "Auth: JWT" — but doesn't know what alternatives were considered
-- "Framework: Next.js" — but doesn't know the tradeoffs
-
-With ADRs, the agent understands the reasoning and won't accidentally contradict prior decisions.
-
-## Commands
-
-### Create a Decision
-
-When an architectural choice is made during any pipeline stage:
-
-1. Auto-increment the decision number
-2. Use the template from `generators/templates/DECISION.md`
-3. Save to `docs/decisions/NNNN-decision-name.md`
-4. Update the Project Graph if the decision affects modules
-
-**Naming convention:** `docs/decisions/0001-use-postgresql.md`
-
-### Query Decisions
-
-Before making changes that touch architecture:
-
-1. Check `docs/decisions/` for related decisions
-2. If a decision exists, follow it
-3. If a decision needs to change, create a new ADR that **supersedes** the old one
-
-### Decision Lifecycle
-
-```
-proposed → accepted → [deprecated | superseded]
-```
-
-- **proposed**: Under discussion, not yet committed
-- **accepted**: The team agreed, this is the standard
-- **deprecated**: No longer relevant (project evolved)
-- **superseded**: Replaced by a newer decision (link to it)
-
-## Auto-Detection
-
-The Decision Engine should suggest creating an ADR when it detects:
-
-- A new database/ORM is introduced
-- A new framework is added
-- Authentication strategy changes
-- API versioning approach is chosen
-- Deployment strategy is decided
-- A significant library is added (state management, testing framework, etc.)
-
-
-## 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: EXAMPLES.md -->
-
-# 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.
-```
-
-<!-- Source: TROUBLESHOOTING.md -->
-
-# decisions Troubleshooting & Common Mistakes
-
-## 1. Post-Hoc Justifications
-
-- **Symptom**: ADR written weeks after code is merged, omitting all rejected options.
-- **Root Cause**: Treating ADRs as paperwork rather than decision-making tools.
-- **Fix**: Write the ADR during the PLAN phase _before_ implementing the decision.
-
-## 2. Omitting Trade-offs
-
-- **Symptom**: ADR lists only benefits, claiming the chosen tech has zero downsides.
-- **Root Cause**: Confirmation bias.
-- **Fix**: Every architecture decision has costs. Explicitly document negative trade-offs and operational overhead.