contextos-agents 1.5.0

package/.agents/core/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/.agents/core/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/.agents/core/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/.agents/core/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/.agents/core/skills/ddd/ddd.md

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

@@ -0,0 +1,10 @@
+id: ddd
+name: Domain-Driven Design
+category: architecture
+tags: [architecture, ddd, domain, bounded-context, aggregate]
+requires: []
+optional: [microservices, system-design]
+conflicts: []
+weight: 6
+documents:
+  - ddd.md

package/.agents/core/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/.agents/core/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/.agents/core/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/.agents/core/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/.agents/core/skills/decisions/skill.yaml

@@ -0,0 +1,10 @@
+name: decisions
+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