contextos-agents 2.1.0 → 2.2.0

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.
+```

package/catalog/skills/decisions/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: decision-engine
+description: >
+  Architecture Decision Records (ADR) management. Creates, tracks, and queries
+  decisions so the AI agent understands WHY choices were made, not just WHAT was chosen.
+---
+
+# 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.

package/catalog/skills/decisions/TROUBLESHOOTING.md

@@ -0,0 +1,13 @@
+# 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/catalog/skills/decisions/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/decisions/skill.yaml

@@ -0,0 +1,13 @@
+schemaVersion: 2
+name: decisions
+category: architecture
+type: instruction-only
+description: >
+  Architecture Decision Records (ADR) management. Creates, tracks, and queries
+  architectural decisions so AI assistants understand why choices were made.
+version: 1.0.0
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json

package/catalog/skills/docker/EXAMPLES.md

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

package/catalog/skills/docker/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: docker
+description: Docker containerization, multi-stage builds, non-root security, layer caching optimization, and docker-compose standards.
+---
+
+# Docker
+
+## Overview
+
+Containerization, Dockerfile architecture, multi-stage compilation, security hardening, and container orchestration for production workloads.
+
+## When to Use
+
+Activate when creating or optimizing Dockerfiles, docker-compose configurations, container security audits, CI/CD container build stages, or production container deployments.
+
+## 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:22-alpine3.20` or `python:3.12-slim-bookworm`).
+3. **NEVER copy source code before dependency manifests**: Always copy package manifests (`package.json`, `pnpm-lock.yaml`, `pyproject.toml`) and install dependencies first to maximize Docker layer cache hits.
+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 injected by the orchestrator.
+5. **NEVER include build tools or devDependencies in the final runner image**: Always use multi-stage builds to discard compilers, package managers, and temporary build caches from production images.
+6. **NEVER run without a `.dockerignore` file**: Always exclude `.git`, `node_modules`, `.env*`, and build outputs from the Docker build context.
+
+---
+
+### Pattern 1: Node.js / Next.js Standalone Multi-Stage Dockerfile
+
+Optimized multi-stage build producing minimal production images (<120MB) with non-root security:
+
+```dockerfile
+# ── Stage 1: Dependencies ─────────────────────────────────────────────
+FROM node:22-alpine3.20 AS deps
+RUN apk add --no-cache libc6-compat
+WORKDIR /app
+
+COPY package.json pnpm-lock.yaml* package-lock.json* yarn.lock* ./
+RUN \
+  if [ -f pnpm-lock.yaml ]; then corepack enable pnpm && pnpm i --frozen-lockfile; \
+  elif [ -f package-lock.json ]; then npm ci; \
+  else yarn --frozen-lockfile; \
+  fi
+
+# ── Stage 2: Builder ──────────────────────────────────────────────────
+FROM node:22-alpine3.20 AS builder
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+
+ENV NEXT_TELEMETRY_DISABLED=1
+ENV NODE_ENV=production
+RUN npm run build
+
+# ── Stage 3: Production Runner ────────────────────────────────────────
+FROM node:22-alpine3.20 AS runner
+WORKDIR /app
+
+ENV NODE_ENV=production
+ENV PORT=3000
+ENV HOSTNAME="0.0.0.0"
+
+RUN addgroup --system --gid 1001 nodejs && \
+    adduser --system --uid 1001 nextjs
+
+# Copy standalone output and static assets
+COPY --from=builder /app/public ./public
+COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
+COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
+
+USER nextjs
+EXPOSE 3000
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
+  CMD wget --no-verbose --tries=1 --spider http://127.0.0.1:3000/api/health || exit 1
+
+CMD ["node", "server.js"]
+```
+
+---
+
+### Pattern 2: Python / FastAPI Multi-Stage Dockerfile (uv)
+
+High-performance Python build utilizing `uv` for sub-second installs and slim final layers:
+
+```dockerfile
+# ── Stage 1: Build virtual environment ────────────────────────────────
+FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim AS builder
+WORKDIR /app
+
+ENV UV_COMPILE_BYTECODE=1
+ENV UV_LINK_MODE=copy
+
+# Install dependencies before code to leverage layer cache
+RUN --mount=type=cache,target=/root/.cache/uv \
+    --mount=type=bind,source=uv.lock,target=uv.lock \
+    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
+    uv sync --frozen --no-install-project --no-dev
+
+COPY . /app
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --frozen --no-dev
+
+# ── Stage 2: Runtime Runner ───────────────────────────────────────────
+FROM python:3.12-slim-bookworm AS runner
+WORKDIR /app
+
+# Create unprivileged application user
+RUN groupadd -r appgroup && useradd -r -g appgroup appuser
+
+COPY --from=builder --chown=appuser:appgroup /app /app
+
+ENV PATH="/app/.venv/bin:$PATH"
+ENV PYTHONUNBUFFERED=1
+
+USER appuser
+EXPOSE 8000
+
+HEALTHCHECK --interval=30s --timeout=3s --retries=3 \
+  CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/health').read()" || exit 1
+
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "2"]
+```
+
+---
+
+### Pattern 3: Essential `.dockerignore` Template
+
+Every repository must include a `.dockerignore` to prevent uploading secrets and heavy cache folders:
+
+```text
+.git
+.github
+node_modules
+npm-debug.log
+.env
+.env.*
+!.env.example
+dist
+build
+.next
+.cache
+coverage
+*.md
+Dockerfile*
+docker-compose*.yml
+```
+
+---
+
+## Validation Checklist
+
+- [ ] Multi-stage build separates build compilers from production runtime.
+- [ ] Non-root `USER` directive is active in the final image stage.
+- [ ] Base images are pinned to explicit, immutable release tags.
+- [ ] `HEALTHCHECK` directive is defined with reasonable interval and timeout.
+- [ ] `.dockerignore` prevents leaking local `.env` files and `node_modules`.
+- [ ] Dependencies are copied and installed before copying source code.
+
+## Common Mistakes
+
+- **Running as root**: Leaves the host system vulnerable if a container breakout vulnerability occurs.
+- **Copying entire source before install**: Invalidates the Docker layer cache on every code edit, slowing CI builds.
+- **Omitting HEALTHCHECK**: Orchestrators cannot detect frozen or zombie worker processes.
+
+## Integration Notes
+
+Interacts with `security` (container hardening) and `node` / `nextjs` / `fastapi`.