contextos-agents 1.5.0

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

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

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

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

@@ -0,0 +1,144 @@
+---
+name: docker
+description: >
+  Docker containerization, multi-stage builds, non-root security, layer caching optimization, and docker-compose standards.
+---
+# Docker
+
+## Overview
+
+Containerization, Dockerfile architecture, security best practices, and container orchestration for production workloads.
+
+## When to Use
+
+Activate when creating or optimizing Dockerfiles, docker-compose configurations, container security audits, or CI/CD container builds.
+
+## Rules & Patterns
+
+### Negative Constraints (What NOT to Do)
+
+1. **NEVER run containers as `root` in production**: Always create and switch to an unprivileged non-root user (e.g. `USER node` or `USER nonroot`).
+2. **NEVER use the `latest` tag**: Always pin base images to specific immutable version digests or explicit minor tags (e.g. `node:20.12.2-alpine3.19`).
+3. **NEVER copy source code before `package.json`**: Always copy lockfiles and install dependencies first to leverage Docker's layer caching.
+4. **NEVER bake secrets, API keys, or `.env` files into image layers**: Pass secrets via build-time secret mounts (`--mount=type=secret`) or runtime environment variables.
+5. **NEVER include build tools or devDependencies in the final runner image**: Always use multi-stage builds to discard compilers and package managers from production images.
+
+### Multi-Stage Standard Pattern
+
+```dockerfile
+FROM node:20.12.2-alpine3.19 AS builder
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci
+COPY . .
+RUN npm run build && npm prune --production
+
+FROM node:20.12.2-alpine3.19 AS runner
+WORKDIR /app
+ENV NODE_ENV=production
+RUN addgroup -S -g 1001 appgroup && adduser -S -u 1001 appuser -G appgroup
+COPY --from=builder --chown=appuser:appgroup /app/dist ./dist
+COPY --from=builder --chown=appuser:appgroup /app/node_modules ./node_modules
+USER appuser
+CMD ["node", "dist/index.js"]
+```
+
+## Code Examples
+
+See `EXAMPLES.md` for production Dockerfiles and dockerignore patterns.
+
+## Validation Checklist
+
+- [ ] Multi-stage build separates build tools from runtime
+- [ ] Non-root `USER` directive active in final stage
+- [ ] Base images pinned to exact versions
+- [ ] `.dockerignore` file prevents leaking node_modules or secrets
+
+## Common Mistakes
+
+- Copying entire workspace before `npm ci`, breaking Docker cache. See `TROUBLESHOOTING.md`.
+
+## Integration Notes
+
+Interacts with `security` (container hardening) and `node` / `nextjs` / `fastapi`.
+
+
+<!-- Source: EXAMPLES.md -->
+
+# Docker Examples — Anti-patterns vs ContextOS Standard
+
+## Example 1: Multi-Stage Build & Layer Caching
+
+### Anti-pattern: Anti-pattern (Fat single-stage image running as root)
+
+```dockerfile
+# BAD: 1.2GB image, runs as root, breaks caching on every file edit
+FROM node:latest
+WORKDIR /app
+COPY . .
+RUN npm install
+RUN npm run build
+EXPOSE 3000
+CMD ["npm", "start"]
+```
+
+### Best practice: ContextOS Standard (Slim multi-stage build with non-root user)
+
+```dockerfile
+# GOOD: 95MB image, non-root user, optimized layer caching
+FROM node:20.12.2-alpine3.19 AS builder
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci
+COPY . .
+RUN npm run build && npm prune --production
+
+FROM node:20.12.2-alpine3.19 AS runner
+WORKDIR /app
+ENV NODE_ENV=production
+RUN addgroup -S -g 1001 appgroup && adduser -S -u 1001 appuser -G appgroup
+COPY --from=builder --chown=appuser:appgroup /app/dist ./dist
+COPY --from=builder --chown=appuser:appgroup /app/node_modules ./node_modules
+USER appuser
+CMD ["node", "dist/main.js"]
+```
+
+---
+
+## Example 2: Docker Ignore File (`.dockerignore`)
+
+### Best practice: ContextOS Standard `.dockerignore`
+
+```gitignore
+node_modules
+npm-debug.log
+.git
+.gitignore
+.env
+.env.*
+dist
+coverage
+.DS_Store
+*.md
+```
+
+<!-- Source: TROUBLESHOOTING.md -->
+
+# Docker Troubleshooting Guide
+
+## Common Issues & Fixes
+
+### 1. Slow Docker builds rebuilding node_modules every time
+
+- **Cause**: Copying the entire directory (`COPY . .`) before running `npm ci`.
+- **Fix**: Copy `package.json` and `package-lock.json` separately first, run `npm ci`, and only then copy application source code.
+
+### 2. Permission Denied Errors with Non-Root Users
+
+- **Cause**: Files copied from builder without changing ownership.
+- **Fix**: Always use `--chown=appuser:appgroup` when copying files in Dockerfile.
+
+### 3. Missing native build dependencies on Alpine Linux
+
+- **Cause**: Packages requiring C bindings (e.g. `sharp`, `bcrypt`) fail on musl libc.
+- **Fix**: Add `RUN apk add --no-cache libc6-compat python3 make g++` in the builder stage.