contextos-agents 1.7.0 → 2.0.0-beta.2

package/.agents/core/skills/ddd/SKILL.md

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

package/.agents/core/skills/ddd/TROUBLESHOOTING.md

@@ -1,19 +0,0 @@
-# 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/core/skills/ddd/VALIDATION.json

@@ -1,12 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "type": "object",
-  "properties": {
-    "rules_followed": {
-      "type": "boolean"
-    }
-  },
-  "required": [
-    "rules_followed"
-  ]
-}

package/.agents/core/skills/ddd/ddd.md

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

package/.agents/core/skills/ddd/skill.yaml

@@ -1,17 +0,0 @@
-id: ddd
-name: Domain-Driven Design
-category: architecture
-type: instruction-only
-tags: [architecture, ddd, domain, bounded-context, aggregate]
-requires: []
-optional: [microservices, system-design]
-conflicts: []
-weight: 6
-documents:
-  - ddd.md
-resources:
-  - EXAMPLES.md
-  - SKILL.md
-  - TROUBLESHOOTING.md
-  - VALIDATION.json
-  - ddd.md

package/.agents/core/skills/decisions/EXAMPLES.md

@@ -1,35 +0,0 @@
-# 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/.agents/core/skills/decisions/SKILL.md

@@ -1,90 +0,0 @@
----
-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/.agents/core/skills/decisions/TROUBLESHOOTING.md

@@ -1,13 +0,0 @@
-# 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/core/skills/decisions/VALIDATION.json

@@ -1,12 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "type": "object",
-  "properties": {
-    "rules_followed": {
-      "type": "boolean"
-    }
-  },
-  "required": [
-    "rules_followed"
-  ]
-}

package/.agents/core/skills/decisions/skill.yaml

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

package/.agents/core/skills/docker/EXAMPLES.md

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