@plazmodium/odin 0.3.2-beta → 0.3.4-beta

package/builtin/skills/architecture/domain-driven-design/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: domain-driven-design
+description: Domain-Driven Design patterns — bounded contexts, aggregates, and strategic design
+category: architecture
+version: "1.0"
+compatible_with:
+  - clean-architecture
+  - event-driven
+  - microservices
+---
+
+# Domain-Driven Design (DDD)
+
+## Overview
+
+DDD is a software design approach that models complex business domains through a shared ubiquitous language, bounded contexts, and tactical patterns like aggregates and domain events.
+
+## Strategic Design
+
+### Bounded Contexts
+
+```
+┌─────────────────┐    ┌──────────────────┐    ┌───────────────┐
+│   Identity &    │    │    Ordering       │    │   Shipping    │
+│   Access        │    │                   │    │               │
+│                 │    │  Order            │    │  Shipment     │
+│  User           │◄──►│  LineItem         │◄──►│  Tracking     │
+│  Role           │    │  Cart             │    │  Address      │
+│  Permission     │    │  Payment          │    │  Carrier      │
+└─────────────────┘    └──────────────────┘    └───────────────┘
+     Context Map: Published Language / Anti-Corruption Layer
+```
+
+Each bounded context has its own:
+- **Ubiquitous language** — "User" in Identity vs "Customer" in Ordering
+- **Models** — same real-world concept, different representations
+- **Data store** — ideally its own database/schema
+
+### Context Mapping
+
+| Pattern | When to Use |
+|---------|------------|
+| **Shared Kernel** | Two teams co-own a small shared model |
+| **Customer-Supplier** | Upstream provides what downstream needs |
+| **Anti-Corruption Layer** | Translate between contexts to prevent leaking |
+| **Published Language** | Well-defined API/events for integration |
+
+## Tactical Patterns
+
+### Aggregate
+
+```typescript
+// Aggregate Root — consistency boundary
+class Order {
+  private items: OrderItem[] = [];
+  private status: OrderStatus = 'draft';
+
+  addItem(product: ProductRef, quantity: number, price: Money): void {
+    if (this.status !== 'draft') throw new DomainError('Cannot modify submitted order');
+    const existing = this.items.find(i => i.productId === product.id);
+    if (existing) {
+      existing.increaseQuantity(quantity);
+    } else {
+      this.items.push(new OrderItem(product.id, quantity, price));
+    }
+  }
+
+  submit(): DomainEvent[] {
+    if (this.items.length === 0) throw new DomainError('Cannot submit empty order');
+    this.status = 'submitted';
+    return [new OrderSubmitted(this.id, this.total(), this.items.length)];
+  }
+
+  get total(): Money {
+    return this.items.reduce((sum, item) => sum.add(item.subtotal()), Money.zero());
+  }
+}
+```
+
+### Domain Events
+
+```typescript
+// Events represent something that happened in the domain
+class OrderSubmitted implements DomainEvent {
+  readonly occurredAt = new Date();
+  constructor(
+    public readonly orderId: string,
+    public readonly total: Money,
+    public readonly itemCount: number,
+  ) {}
+}
+
+// Handle in application layer
+class OnOrderSubmitted {
+  constructor(private emailService: EmailService, private inventoryService: InventoryService) {}
+
+  async handle(event: OrderSubmitted): Promise<void> {
+    await this.emailService.sendOrderConfirmation(event.orderId);
+    await this.inventoryService.reserveItems(event.orderId);
+  }
+}
+```
+
+### Repository
+
+```typescript
+// Repository per aggregate root — NOT per table
+interface OrderRepository {
+  findById(id: OrderId): Promise<Order | null>;
+  save(order: Order): Promise<void>;  // Saves entire aggregate
+  nextId(): OrderId;
+}
+```
+
+## Best Practices
+
+1. **One aggregate = one transaction** — don't modify multiple aggregates in one transaction
+2. **Reference aggregates by ID** — not by direct object reference
+3. **Small aggregates** — only include what's needed for invariant enforcement
+4. **Domain events for cross-aggregate communication** — eventual consistency between aggregates
+5. **Ubiquitous language** — code names must match domain expert vocabulary
+6. **Anti-Corruption Layer** — always translate at context boundaries
+
+## Gotchas
+
+- **Anemic domain model** — entities with only getters/setters and all logic in services
+- **Big aggregate** — putting everything in one aggregate kills performance
+- **Premature context splitting** — start with one context, split when language diverges
+- **Ignoring the domain expert** — DDD requires ongoing collaboration, not just patterns

package/builtin/skills/architecture/event-driven/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: event-driven
+description: Event-driven architecture patterns — event sourcing, CQRS, message brokers, and async workflows
+category: architecture
+version: "1.0"
+compatible_with:
+  - domain-driven-design
+  - microservices
+  - redis
+---
+
+# Event-Driven Architecture
+
+## Overview
+
+Event-driven architecture (EDA) uses events as the primary mechanism for communication between components. Events represent facts — things that have happened — and enable loose coupling, scalability, and auditability.
+
+## Patterns
+
+### Event Notification
+
+```
+Producer → Event Bus → Consumer(s)
+
+OrderService                    NotificationService
+    │                                  │
+    ├── publishes ──►  OrderPlaced ──► │ sends email
+    │                                  │
+InventoryService                PaymentService
+    │                                  │
+    ├── subscribes ─► OrderPlaced ──►  │ charges card
+```
+
+### Event Sourcing
+
+```typescript
+// Store events, not state — rebuild state by replaying events
+class OrderEventStore {
+  async save(orderId: string, events: DomainEvent[]): Promise<void> {
+    for (const event of events) {
+      await this.db.insert('events', {
+        stream_id: orderId,
+        type: event.type,
+        data: JSON.stringify(event),
+        version: event.version,
+        occurred_at: event.occurredAt,
+      });
+    }
+  }
+
+  async load(orderId: string): Promise<DomainEvent[]> {
+    return this.db.query(
+      'SELECT * FROM events WHERE stream_id = $1 ORDER BY version ASC',
+      [orderId]
+    );
+  }
+}
+
+// Rebuild aggregate from events
+function rehydrate(events: DomainEvent[]): Order {
+  const order = new Order();
+  for (const event of events) {
+    order.apply(event); // Mutates internal state
+  }
+  return order;
+}
+```
+
+### CQRS (Command Query Responsibility Segregation)
+
+```
+Commands (Write)                    Queries (Read)
+    │                                   │
+    ▼                                   ▼
+┌──────────┐   events    ┌──────────────────┐
+│ Write DB │ ──────────► │ Read Projections  │
+│ (events) │             │ (denormalized)    │
+└──────────┘             └──────────────────┘
+```
+
+```typescript
+// Command side — validates and stores events
+async function placeOrder(cmd: PlaceOrderCommand): Promise<void> {
+  const order = await eventStore.load(cmd.orderId);
+  const events = order.place(cmd.items); // Returns new events
+  await eventStore.save(cmd.orderId, events);
+  await eventBus.publish(events);
+}
+
+// Query side — read from optimized projections
+async function getOrderSummary(orderId: string): Promise<OrderSummary> {
+  return readDb.query('SELECT * FROM order_summaries WHERE id = $1', [orderId]);
+}
+
+// Projector — updates read model when events arrive
+class OrderProjector {
+  async handle(event: OrderPlaced): Promise<void> {
+    await readDb.insert('order_summaries', {
+      id: event.orderId,
+      status: 'placed',
+      total: event.total,
+      item_count: event.items.length,
+    });
+  }
+}
+```
+
+### Message Broker Patterns
+
+```typescript
+// Dead letter queue for failed messages
+const config = {
+  queue: 'order-processing',
+  deadLetterQueue: 'order-processing-dlq',
+  maxRetries: 3,
+  retryDelay: [1000, 5000, 30000], // Exponential backoff
+};
+
+// Idempotent consumers — handle duplicate delivery
+async function handleOrderPlaced(event: OrderPlaced): Promise<void> {
+  const processed = await cache.get(`processed:${event.id}`);
+  if (processed) return; // Already handled
+
+  await processOrder(event);
+  await cache.set(`processed:${event.id}`, '1', 'EX', 86400);
+}
+```
+
+## Best Practices
+
+1. **Events are facts** — immutable, past-tense (`OrderPlaced`, not `PlaceOrder`)
+2. **Idempotent consumers** — always handle duplicate delivery gracefully
+3. **Schema evolution** — version events; add fields, don't rename/remove
+4. **Dead letter queues** — capture failed messages for manual inspection
+5. **Correlation IDs** — trace events across services with a shared ID
+6. **Eventually consistent** — accept that read models may lag; design UX accordingly
+7. **Start without event sourcing** — event notification is simpler; add sourcing when you need audit trails
+
+## Gotchas
+
+- **Ordering guarantees** — most message brokers guarantee order per partition/key, not globally
+- **Eventual consistency** — read model may be stale; handle "not found yet" in consumers
+- **Event versioning** — changing event schemas without migration breaks consumers
+- **Debugging** — tracing an operation across async events is harder than a synchronous call stack
+- **Two-phase commit trap** — don't try to atomically write to DB + publish event; use outbox pattern

package/builtin/skills/architecture/microservices/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: microservices
+description: Microservices design patterns — service boundaries, communication, resilience, and observability
+category: architecture
+version: "1.0"
+depends_on:
+  - domain-driven-design
+  - event-driven
+compatible_with:
+  - docker
+  - kubernetes
+  - rest-api
+  - grpc
+---
+
+# Microservices Architecture
+
+## Overview
+
+Microservices decompose an application into small, independently deployable services organized around business capabilities. Each service owns its data and communicates via APIs or events.
+
+## Service Design
+
+### Service Boundaries
+
+```
+✅ Good boundaries (aligned with business capabilities):
+┌──────────┐  ┌───────────┐  ┌──────────┐  ┌───────────┐
+│  Users   │  │  Orders   │  │ Payments │  │ Shipping  │
+│          │  │           │  │          │  │           │
+│ - Auth   │  │ - Cart    │  │ - Charge │  │ - Track   │
+│ - Profile│  │ - Checkout│  │ - Refund │  │ - Fulfill │
+│ - Prefs  │  │ - History │  │ - Ledger │  │ - Label   │
+└──────────┘  └───────────┘  └──────────┘  └───────────┘
+
+❌ Bad boundaries (tech layers):
+┌──────────┐  ┌───────────┐  ┌──────────┐
+│ Frontend │  │  Backend  │  │ Database │  ← Not microservices
+└──────────┘  └───────────┘  └──────────┘
+```
+
+### Communication
+
+```
+Synchronous (request/response):
+  REST API   — Simple CRUD, public APIs
+  gRPC       — Internal service-to-service, streaming
+
+Asynchronous (event-driven):
+  Message Queue (RabbitMQ, SQS) — Task processing, commands
+  Event Stream (Kafka)          — Event sourcing, data sync
+```
+
+## Core Patterns
+
+### API Gateway
+
+```yaml
+# Route external requests to internal services
+routes:
+  /api/users/*:    upstream: http://user-service:3000
+  /api/orders/*:   upstream: http://order-service:3000
+  /api/payments/*: upstream: http://payment-service:3000
+
+# Cross-cutting concerns at the gateway:
+# - Authentication / JWT validation
+# - Rate limiting
+# - Request logging
+# - Response caching
+```
+
+### Service Communication
+
+```typescript
+// Sync: REST with circuit breaker
+import CircuitBreaker from 'opossum';
+
+const paymentBreaker = new CircuitBreaker(
+  async (orderId: string) => {
+    return fetch(`http://payment-service/charges/${orderId}`);
+  },
+  { timeout: 3000, errorThresholdPercentage: 50, resetTimeout: 30000 }
+);
+
+// Fallback when circuit is open
+paymentBreaker.fallback(() => ({ status: 'pending', message: 'Payment service unavailable' }));
+```
+
+### Saga Pattern (distributed transactions)
+
+```
+Choreography (events):
+  OrderCreated → PaymentCharged → InventoryReserved → ShipmentScheduled
+       ↓ (if fails)
+  OrderCreated → PaymentCharged → InventoryFailed → PaymentRefunded → OrderCancelled
+
+Orchestration (central coordinator):
+  OrderSaga:
+    1. Create order (pending)
+    2. Charge payment → if fails → cancel order
+    3. Reserve inventory → if fails → refund payment → cancel order
+    4. Schedule shipment → if fails → release inventory → refund → cancel
+    5. Mark order complete
+```
+
+### Service Mesh / Observability
+
+```yaml
+# Distributed tracing headers (propagate across services)
+X-Request-ID: unique-per-request
+X-Correlation-ID: unique-per-user-action
+
+# Health check endpoint (every service)
+GET /health
+{
+  "status": "healthy",
+  "version": "1.2.3",
+  "uptime": 86400,
+  "dependencies": {
+    "database": "connected",
+    "cache": "connected",
+    "payment-service": "healthy"
+  }
+}
+```
+
+## Best Practices
+
+1. **Database per service** — no shared databases; communicate via APIs/events
+2. **Smart endpoints, dumb pipes** — business logic in services, not in the messaging layer
+3. **Design for failure** — circuit breakers, retries with backoff, fallbacks
+4. **Health checks** — every service exposes `/health` with dependency status
+5. **Distributed tracing** — propagate correlation IDs through all service calls
+6. **Independent deployability** — each service has its own CI/CD pipeline
+7. **Start with a monolith** — extract services when team/domain boundaries become clear
+
+## Gotchas
+
+- **Distributed monolith** — services that must deploy together aren't microservices
+- **Data consistency** — no ACID across services; use sagas and eventual consistency
+- **Network unreliability** — every service call can fail, timeout, or return stale data
+- **Operational complexity** — monitoring, logging, tracing across N services is hard
+- **Service discovery** — services need to find each other; use DNS, Consul, or Kubernetes services

package/builtin/skills/architecture/tla-precheck/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: tla-precheck
+description: "Formal design verification using TLA+ model checking via tla-precheck. Use when a feature involves state machines, lifecycle transitions, concurrent state mutations, or invariants that must hold across all interleavings."
+category: architecture
+compatible_with:
+  - clean-architecture
+  - domain-driven-design
+  - event-driven
+depends_on: []
+---
+
+# TLA+ PreCheck — Formal Design Verification
+
+## Overview
+
+[tla-precheck](https://github.com/kingbootoshi/tla-precheck) translates a TypeScript state machine DSL (`.machine.ts`) into TLA+ specifications, then runs the TLC model checker to exhaustively verify invariants and graph equivalence. Odin integrates it as an opt-in design verification step in the Architect → Guardian flow.
+
+## When to Use
+
+Write a `.machine.ts` file when the feature involves:
+
+- **Entity lifecycle management** — status transitions, state machines with guard conditions
+- **Concurrent operations on shared state** — multiple actors mutating the same resource
+- **Financial/billing state changes** — charges, refunds, subscriptions where invariant violations cause real damage
+- **Distributed workflow coordination** — where guard conditions are scattered across files/services
+- **Any invariant that must hold across all possible interleavings** — not just the happy path
+
+Complexity level (L1/L2/L3) is a secondary signal. Even a small L1 feature can contain a high-risk lifecycle invariant.
+
+## The `.machine.ts` DSL
+
+A machine definition describes states, events, transitions, and invariants:
+
+```typescript
+import { defineMachine } from 'tla-precheck';
+
+export default defineMachine({
+  moduleName: 'AgentRuns',
+
+  constants: {
+    Users: { type: 'set', values: ['u1', 'u2'] },
+    MaxConcurrent: { type: 'number', value: 1 },
+  },
+
+  state: {
+    runs: { type: 'map', keys: 'Users', values: ['idle', 'queued', 'running', 'completed'] },
+  },
+
+  init: {
+    runs: { u1: 'idle', u2: 'idle' },
+  },
+
+  actions: {
+    QueueRun: {
+      guard: (s) => Object.values(s.runs).some((v) => v === 'idle'),
+      update: (s) => {
+        const user = Object.keys(s.runs).find((u) => s.runs[u] === 'idle')!;
+        s.runs[user] = 'queued';
+      },
+    },
+    StartRun: {
+      guard: (s) => {
+        const running = Object.values(s.runs).filter((v) => v === 'running').length;
+        return running < MaxConcurrent && Object.values(s.runs).some((v) => v === 'queued');
+      },
+      update: (s) => {
+        const user = Object.keys(s.runs).find((u) => s.runs[u] === 'queued')!;
+        s.runs[user] = 'running';
+      },
+    },
+    CompleteRun: {
+      guard: (s) => Object.values(s.runs).some((v) => v === 'running'),
+      update: (s) => {
+        const user = Object.keys(s.runs).find((u) => s.runs[u] === 'running')!;
+        s.runs[user] = 'completed';
+      },
+    },
+  },
+
+  invariants: {
+    AtMostOneRunning: (s) =>
+      Object.values(s.runs).filter((v) => v === 'running').length <= MaxConcurrent,
+  },
+});
+```
+
+## Odin Integration
+
+### Architect Phase (Phase 3)
+
+1. Identify state flows in the spec that need formal verification
+2. Write a `.machine.ts` file for each critical flow
+3. Document in spec section "4.6 State Machine Verification"
+4. Ask the orchestrator to call `odin.verify_design` for each machine
+5. If proof fails → fix the **design** (the DSL), not patch around it
+6. Loop until all machines return `status: VERIFIED`
+7. Record aggregated results as one `design_verification` phase artifact
+
+### Guardian Phase (Phase 4)
+
+Guardian reviews proof results in the Technical Soundness perspective:
+
+- All machines `VERIFIED` → supports **Good**
+- Any machine `VIOLATION` → **Blocking** (design must be fixed)
+- State flows in spec but no proof run → **Needs Work**
+- Tool not configured/available → **N/A**
+
+### Configuration
+
+```yaml
+# .odin/config.yaml
+formal_verification:
+  provider: tla-precheck    # or "none" (default)
+  timeout_seconds: 120
+```
+
+### Requirements
+
+- Java 17+ (for the TLC model checker)
+- `tla-precheck` installed as a devDependency in the target project
+
+```bash
+npm install -D tla-precheck
+```
+
+## Verification Status Codes
+
+| Status | Meaning |
+|--------|---------|
+| `VERIFIED` | Proof passed, invariants hold, graph equivalence confirmed |
+| `VIOLATION` | Invariant violation found — design bug |
+| `INVALID_MODEL` | DSL parse error or malformed machine — fix the `.machine.ts`, not the design |
+| `TIMEOUT` | TLC exceeded time budget — simplify the state space or increase timeout |
+| `UNAVAILABLE` | Java or tla-precheck not installed |
+| `NOT_CONFIGURED` | `formal_verification.provider` is `none` |
+| `INTERNAL_ERROR` | Unexpected failure in tla-precheck |
+
+## Design Loop
+
+```
+Write .machine.ts
+       │
+       ▼
+ odin.verify_design
+       │
+   ┌───┴───┐
+   │       │
+VERIFIED  VIOLATION
+   │       │
+   ▼       ▼
+ Done    Read counter-example
+         Fix the DESIGN (DSL)
+         Re-run verification
+         └──────────────┘
+```
+
+The key insight: when proof fails, **fix the design**, not the code. The `.machine.ts` IS the design. If you can't make the invariant hold in the model, you can't make it hold in the implementation.
+
+## Best Practices
+
+- **Keep state spaces small** — use 2-3 constants per set, not production-scale values. TLC checks all interleavings exhaustively.
+- **Name invariants descriptively** — `AtMostOneRunning` not `Inv1`. Guardian reviews these names.
+- **One machine per concern** — don't model your entire system in one file. Model the billing flow, the auth flow, the workflow transitions separately.
+- **Pin the version** — `tla-precheck` is early-stage (1 contributor, no releases). Pin exact version in `package.json`.
+- **Check `equivalent`** — proof passing but `equivalent: false` means your TypeScript interpreter diverges from the TLA+ spec. This is a bug in the DSL, not the model checker.
+
+## References
+
+- [tla-precheck GitHub](https://github.com/kingbootoshi/tla-precheck)
+- [TLA+ Learning Resources](https://lamport.azurewebsites.net/tla/learning.html)
+- [Odin Architect Agent — Section 4.6](../../../agents/definitions/architect.md)