@martinffx/atelier 1.2.2 → 1.4.0

package/skills/oracle-architect/references/ddd-patterns.md

@@ -1,348 +0,0 @@
-# DDD Patterns Reference
-
-Domain-Driven Design patterns for modeling business domains and enforcing consistency.
-
-## Aggregates
-
-**Definition:** Cluster of domain objects treated as a single unit for data changes
-
-**Rules:**
-- One entity is the aggregate root (e.g., Order)
-- External references only to the root
-- Changes go through the root
-- Root enforces invariants
-
-**Example:**
-```typescript
-class Order {  // Aggregate root
-  private items: OrderItem[];  // Part of aggregate
-
-  addItem(item: OrderItem): Result<Order> {
-    // Root enforces invariants
-    if (this.items.length >= 100) {
-      return Err('Order cannot have more than 100 items');
-    }
-    this.items.push(item);
-    return Ok(this);
-  }
-}
-```
-
-**Business Rules Enforcement:**
-```typescript
-class Order {
-  private status: OrderStatus;
-  private appliedDiscounts: Discount[] = [];
-
-  applyDiscount(discount: Discount): Result<void> {
-    // Business rule: can't apply discount to shipped orders
-    if (this.status === 'shipped') {
-      return Err('Cannot discount shipped orders');
-    }
-
-    // Business rule: no duplicate discounts
-    if (this.appliedDiscounts.some(d => d.id === discount.id)) {
-      return Err('Discount already applied');
-    }
-
-    this.appliedDiscounts.push(discount);
-    return Ok(undefined);
-  }
-}
-```
-
-## Value Objects
-
-**Definition:** Immutable objects defined by their attributes, not identity
-
-**Characteristics:**
-- No identity (equality by value)
-- Immutable
-- Self-validating
-- Encapsulate validation logic
-
-**Example:**
-```typescript
-class Money {
-  constructor(
-    public readonly amount: number,
-    public readonly currency: string
-  ) {
-    if (amount < 0) throw new Error('Amount cannot be negative');
-    if (!['USD', 'EUR', 'GBP'].includes(currency)) {
-      throw new Error('Unsupported currency');
-    }
-  }
-
-  add(other: Money): Money {
-    if (this.currency !== other.currency) {
-      throw new Error('Cannot add different currencies');
-    }
-    return new Money(this.amount + other.amount, this.currency);
-  }
-
-  equals(other: Money): boolean {
-    return this.amount === other.amount && this.currency === other.currency;
-  }
-
-  static fromCents(cents: number, currency: string): Money {
-    return new Money(cents / 100, currency);
-  }
-}
-```
-
-**More Examples:**
-```typescript
-// Email VO with validation
-class Email {
-  readonly value: string;
-
-  constructor(value: string) {
-    if (!this.isValid(value)) throw new Error('Invalid email');
-    this.value = value.toLowerCase();
-  }
-
-  private isValid(email: string): boolean {
-    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
-  }
-
-  equals(other: Email): boolean {
-    return this.value === other.value;
-  }
-}
-
-// Address VO with composition
-class Address {
-  constructor(
-    public readonly street: string,
-    public readonly city: string,
-    public readonly zipCode: string,
-    public readonly country: string
-  ) {}
-
-  equals(other: Address): boolean {
-    return this.street === other.street &&
-           this.city === other.city &&
-           this.zipCode === other.zipCode &&
-           this.country === other.country;
-  }
-}
-```
-
-## Domain Events
-
-**Definition:** Something that happened in the domain that domain experts care about
-
-**Characteristics:**
-- Immutable facts about what happened
-- Named in past tense
-- Include context about what changed
-- Timestamped
-
-**Example:**
-```typescript
-class OrderPlaced {
-  constructor(
-    public readonly orderId: string,
-    public readonly customerId: string,
-    public readonly total: number,
-    public readonly occurredAt: Date
-  ) {}
-}
-
-// Service publishes events
-const order = await orderService.createOrder(request);
-await eventBus.publish(
-  new OrderPlaced(order.id, order.customerId, order.total, new Date())
-);
-
-// Events cross bounded contexts
-class OrderShipped {
-  constructor(
-    public readonly orderId: string,
-    public readonly shippingAddress: Address,
-    public readonly trackingNumber: string,
-    public readonly occurredAt: Date
-  ) {}
-}
-```
-
-**Event-Driven Workflows:**
-```typescript
-// Order context publishes OrderPlaced
-// Inventory context listens and consumes
-class InventoryService {
-  async handleOrderPlaced(event: OrderPlaced): Promise<Result<void>> {
-    // Reserve inventory in response to order
-    const result = await this.inventoryRepo.reserve(event.orderId);
-    if (!result.ok) {
-      // Handle reservation failure
-      await this.eventBus.publish(new InventoryReservationFailed(event.orderId));
-    }
-    return result;
-  }
-}
-```
-
-## Bounded Contexts
-
-**Definition:** Explicit boundaries where a domain model applies
-
-**Guidelines:**
-- Each context has its own ubiquitous language
-- Contexts communicate via well-defined contracts
-- Same concept may have different models in different contexts
-- Example: "Customer" in Sales context vs "User" in Auth context
-
-**Context Composition:**
-```
-Bounded Context: "Orders"
-┌────────────────────────────────────────────────────────────────┐
-│                                                                │
-│   Effectful Edge                    Functional Core            │
-│   ┌──────────────────┐             ┌──────────────────┐       │
-│   │ Router           │────────────▶│ Service          │       │
-│   │ POST /orders     │             │ OrderService     │       │
-│   └──────────────────┘             └────────┬─────────┘       │
-│                                              │                 │
-│   ┌──────────────────┐             ┌────────▼─────────┐       │
-│   │ Repository       │◀────────────│ Aggregate        │       │
-│   │ OrderRepository  │             │ Order (root)     │       │
-│   └──────────────────┘             │ └─ OrderItem[]   │       │
-│                                    │ └─ Money (VO)    │       │
-│   ┌──────────────────┐             └──────────────────┘       │
-│   │ Producer         │◀── Domain Event: OrderPlaced           │
-│   └────────┬─────────┘                                        │
-└────────────│───────────────────────────────────────────────────┘
-             │
-             ▼ Events cross context boundaries
-┌────────────────────────────────────────────────────────────────┐
-│ Bounded Context: "Inventory"                                   │
-│   Consumer ──▶ InventoryService ──▶ StockLevel (Aggregate)     │
-└────────────────────────────────────────────────────────────────┘
-```
-
-**Context Anti-Patterns:**
-- Shared database (breaks boundary enforcement)
-- Generic "core" or "common" domain (pollutes context boundaries)
-- Cross-context validation (move validation to appropriate context)
-- Tight coupling via shared types (use context-specific DTOs)
-
-## Composition Rules
-
-| DDD Pattern | Maps To | Location |
-|-------------|---------|----------|
-| Bounded Context | Module/Package boundary | Contains all layers |
-| Aggregate | Entity cluster | Functional Core |
-| Aggregate Root | Primary Entity | Entity layer |
-| Value Object | Immutable type | Entity layer |
-| Domain Event | Event class | Published from Service, consumed by edge |
-| Repository | Data access | Effectful Edge (interface in Core) |
-
-**Key Interactions:**
-1. **Router → Service**: HTTP request parsed, passed to service
-2. **Service → Aggregate**: Service orchestrates aggregate operations
-3. **Aggregate → Repository**: Service uses repository to persist aggregate
-4. **Service → Producer**: Service publishes domain events after state change
-5. **Consumer → Service**: Events from other contexts trigger service operations
-
-## Seam Placement
-
-Where you put the seam matters as much as what goes behind it.
-
-### Core/Edge Seam
-
-The primary seam runs between the functional core and the effectful edge:
-
-```
-┌─────────────────────────────────┐
-│  Functional Core (pure)         │
-│  ┌──────────────────────────┐   │
-│  │ OrderService             │   │
-│  │   createOrder() ────────┼───┼──▶ (seam)
-│  │   processPayment()       │   │
-│  └──────────────────────────┘   │
-└─────────────────────────────────┘
-              │
-              ▼ seam
-┌─────────────────────────────────┐
-│  Effectful Edge (IO)            │
-│  ┌──────────────────────────┐   │
-│  │ PostgresOrderRepository  │◀──┼── adapter
-│  │ HttpPaymentClient        │   │   adapter
-│  │ InMemoryOrderRepository  │   │   adapter (test)
-│  └──────────────────────────┘   │
-└─────────────────────────────────┘
-```
-
-**Rules:**
-- Core defines the interface; edge implements it (dependency inversion)
-- The seam must have **at least two adapters** to be real (production + test)
-- Core never imports edge code; edge imports core interfaces
-
-### Internal Seams
-
-A deep module can have **internal seams** — private to its implementation, used by its own tests:
-
-```typescript
-class Order {
-  // External seam (public interface)
-  validate(): Result<Order> { ... }
-
-  // Internal seam (private, tested directly)
-  private calculateTax(subtotal: number): Money { ... }
-}
-```
-
-Internal seams let you test complex logic without exposing it in the public interface.
-
-### When to Create a Seam
-
-Use the **adapter rule**: one adapter = hypothetical; two = real.
-
-| Scenario | Action |
-|----------|--------|
-| One database implementation, no test fake | No seam needed. Direct dependency is simpler. |
-| One database implementation, test fake exists | Extract interface. The fake is the second adapter. |
-| Multiple database implementations (Postgres + DynamoDB) | Extract interface. The implementations are the adapters. |
-| External API with one client | Direct dependency. Introduce seam only when you need a mock/stub for testing. |
-
-### Anti-Patterns
-
-**Seam at every dependency:**
-```typescript
-// ❌ Too many seams — every dependency gets an interface
-interface IValidator { ... }
-interface IFormatter { ... }
-interface IConverter { ... }
-// Each has one adapter. Indirection without value.
-```
-
-**No seam at the core/edge boundary:**
-```typescript
-// ❌ Core imports edge directly
-import { db } from '../edge/postgres';
-class OrderService {
-  async createOrder(req) {
-    await db.orders.create(...); // Core knows about Postgres
-  }
-}
-```
-
-**Leaky seam:**
-```typescript
-// ❌ Interface exposes implementation details
-interface OrderRepository {
-  queryRaw(sql: string): Promise<Row[]>; // Caller knows SQL
-  beginTransaction(): Promise<Transaction>; // Caller manages transactions
-}
-// The seam leaks. Callers become coupled to the database.
-```
-
-### Seam Placement Checklist
-
-Before introducing a new seam, verify:
-- [ ] At least two adapters will exist (production + test, or multiple production)
-- [ ] The interface hides implementation details (no SQL, no HTTP, no framework types)
-- [ ] The core doesn't import edge code
-- [ ] Deleting the module would re-appear complexity across N callers

package/skills/oracle-architect/references/interface-design.md

@@ -1,203 +0,0 @@
-# Interface Design Reference
-
-Patterns for designing module interfaces that maximize depth, leverage, and locality.
-
-Based on "Design It Twice" (Ousterhout) — your first idea is unlikely to be the best.
-
-## Design It Twice
-
-Before committing to a module's interface, sketch at least two alternatives with different trade-offs.
-
-### Process
-
-1. **Frame the problem space**
-   - List constraints any interface must satisfy
-   - Identify dependencies and which category they fall into
-   - Write a rough illustrative code sketch to ground the constraints
-
-2. **Sketch alternatives**
-   - Alternative A: Minimize the interface (1–3 entry points max)
-   - Alternative B: Maximize flexibility (support many use cases)
-   - Alternative C: Optimize for the most common caller (default case trivial)
-
-3. **Compare by depth**
-   - Which alternative has the smallest interface for the most behaviour?
-   - Which concentrates the most knowledge in one place?
-   - Which has the best test surface?
-
-### Example: Order Creation Interface
-
-**Problem:** Design the interface for creating an order.
-
-**Alternative A — Minimal interface:**
-```typescript
-interface OrderService {
-  createOrder(request: CreateOrderRequest): Promise<Result<Order>>;
-}
-```
-- **Pros:** Tiny surface. One seam. Easy to mock.
-- **Cons:** All complexity hidden inside. Hard to test partial flows (e.g. validation without persistence).
-- **Depth:** Very deep. High leverage, high locality.
-
-**Alternative B — Flexible interface:**
-```typescript
-interface OrderService {
-  validate(request: CreateOrderRequest): Promise<Result<Order>>;
-  reserveInventory(order: Order): Promise<Result<Order>>;
-  save(order: Order): Promise<Result<Order>>;
-  publishEvents(order: Order): Promise<void>;
-}
-```
-- **Pros:** Callers compose their own flows. Easy to test each step.
-- **Cons:** Interface is as complex as implementation. Callers must know ordering constraints (reserve before save).
-- **Depth:** Shallow. Low leverage — callers replicate orchestration.
-
-**Alternative C — Optimized for common case:**
-```typescript
-interface OrderService {
-  createOrder(request: CreateOrderRequest): Promise<Result<Order>>;
-  createOrderDraft(request: CreateOrderRequest): Promise<Result<Order>>; // no inventory check
-  confirmOrder(orderId: string): Promise<Result<Order>>; // draft → confirmed
-}
-```
-- **Pros:** Common case (createOrder) is trivial. Draft pattern supports async workflows.
-- **Cons:** More surface area than Alternative A. Callers must understand draft vs confirmed.
-- **Depth:** Moderate. Good leverage for the common case.
-
-**Recommendation:** Alternative C. It balances depth with real workflow needs. The draft/confirm split is a real seam (two callers: interactive vs batch).
-
-## Interface Size Heuristics
-
-### The Rule of Three
-
-A module's public interface should have no more than 3 primary entry points for each responsibility:
-
-```typescript
-// ❌ Too wide
-interface OrderService {
-  createOrder(...): Promise<Order>;
-  updateOrder(...): Promise<Order>;
-  deleteOrder(...): Promise<void>;
-  getOrder(...): Promise<Order>;
-  listOrders(...): Promise<Order[]>;
-  searchOrders(...): Promise<Order[]>;
-  cancelOrder(...): Promise<Order>;
-  shipOrder(...): Promise<Order>;
-  refundOrder(...): Promise<Order>;
-}
-
-// ✅ Split by responsibility (2 modules, each with ~3 methods)
-interface OrderLifecycleService {
-  create(...): Promise<Order>;
-  cancel(...): Promise<Order>;
-  ship(...): Promise<Order>;
-}
-
-interface OrderQueryService {
-  get(id: string): Promise<Order>;
-  list(filters: OrderFilters): Promise<Order[]>;
-  search(query: string): Promise<Order[]>;
-}
-```
-
-### Invariants in the Interface
-
-The interface includes not just types, but everything a caller must know:
-
-```typescript
-interface PaymentService {
-  // ❌ Interface hides invariants
-  processPayment(orderId: string, amount: number): Promise<Receipt>;
-  // Caller must discover: amount must match order total, order must be confirmed,
-  // can't process twice, throws if payment gateway is down.
-
-  // ✅ Interface encodes invariants in types
-  processPayment(
-    order: ConfirmedOrder, // type encodes "must be confirmed"
-    payment: PaymentMethod  // type encodes valid methods
-  ): Promise<Result<Receipt, PaymentError>>;
-  // Error mode explicit in return type. Ordering implicit in input types.
-```
-
-## Dependency Categories
-
-The shape of an interface depends on what it depends on.
-
-| Category | Description | Interface Impact |
-|----------|-------------|------------------|
-| **In-process** | Same memory space, no serialization | Can pass rich types, callbacks, streams |
-| **Local-substitutable** | Same interface, different implementations (real vs test) | Seam is real. Interface must hide implementation |
-| **Ports & adapters** | Crosses a real boundary (DB, HTTP, message queue) | Interface must be narrow. Errors are part of the contract |
-| **Mock** | Test-only dependency, no production equivalent | Don't create a seam. Test the real module |
-
-## Common Interface Anti-Patterns
-
-### Leaky Abstraction
-
-```typescript
-// ❌ Interface exposes implementation
-interface UserRepository {
-  query(sql: string, params: any[]): Promise<Row[]>;
-}
-
-// ✅ Interface hides implementation
-interface UserRepository {
-  findByEmail(email: Email): Promise<User | null>;
-  save(user: User): Promise<User>;
-}
-```
-
-### Pass-Through Interface
-
-```typescript
-// ❌ Every method delegates 1:1 to another module
-class OrderService {
-  async findById(id: string) { return this.repo.findById(id); }
-  async save(order: Order) { return this.repo.save(order); }
-  async delete(id: string) { return this.repo.delete(id); }
-}
-// Deletion test: delete OrderService → complexity doesn't reappear.
-// It's a pass-through. Remove it and call repo directly.
-```
-
-### God Interface
-
-```typescript
-// ❌ One module does everything
-interface PlatformService {
-  createUser(...): Promise<User>;
-  sendEmail(...): Promise<void>;
-  processPayment(...): Promise<Receipt>;
-  generateReport(...): Promise<PDF>;
-}
-// No cohesion. Deleting it would reappear complexity, but in unrelated places.
-// Split by domain responsibility instead.
-```
-
-### Chatty Interface
-
-```typescript
-// ❌ Many small methods that must be called in sequence
-interface OrderBuilder {
-  setCustomer(customerId: string): this;
-  addItem(item: OrderItem): this;
-  setShipping(address: Address): this;
-  setPayment(method: PaymentMethod): this;
-  validate(): Result<void>;
-  build(): Order;
-}
-// Callers must know ordering. State machine hidden in method calls.
-// Better: single method that takes a complete request.
-```
-
-## Decision Checklist
-
-Before finalizing an interface:
-
-- [ ] Run the deletion test — does complexity reappear across N callers?
-- [ ] Check depth — is the interface at least 3x smaller than the implementation?
-- [ ] Verify seam — are there at least two adapters?
-- [ ] Encode invariants — are error modes, ordering, and constraints visible in types?
-- [ ] Test surface — can you test all behaviour through the public interface?
-- [ ] Hide details — does the interface leak SQL, HTTP, frameworks, or implementation?
-- [ ] Common case — is the most frequent caller's experience trivial?

package/skills/oracle-challenge/SKILL.md

@@ -1,126 +0,0 @@
----
-name: oracle-challenge
-description: Challenge an approach with critical thinking. Use when questioning assumptions, validating decisions, testing approach validity, or preventing automatic agreement.
-user-invocable: true
----
-
-# Challenge: Critical Thinking Prompt
-
-## Step 1: Parse Challenge Request
-
-<strategist>
-@agent-oracle
-
-Analyze the challenge request: $ARGUMENTS
-
-**Challenge Extraction:**
-- **Core concern**: Extract the main doubt or question
-- **Target approach**: Identify what is being challenged
-- **Context**: Relevant background from current session
-- **Specific aspects**: Particular elements to question
-
-**Challenge Summary:**
-You're challenging: [identified approach]
-Because: [extracted concern]
-In context of: [session context]
-</strategist>
-
-## Step 2: Set Up Critical Thinking Framework
-
-<framework>
-**What to Question:**
-- **Underlying assumptions**: What beliefs support this approach?
-- **Evidence base**: What data or experience validates it?
-- **Context fit**: How well does it work in your specific situation?
-- **Alternatives considered**: What other options were explored?
-- **Risk factors**: What could go wrong with this approach?
-
-**Critical Thinking Prompts:**
-- Is this approach solving the right problem?
-- Are the underlying assumptions still valid?
-- What evidence contradicts this direction?
-- How does this fit with your constraints and goals?
-- What are the opportunity costs?
-</framework>
-
-## Step 3: Sequential Thinking Analysis
-
-<strategist>
-@agent-oracle
-
-Use sequential thinking (mcp__sequential-thinking__sequentialthinking) to analyze this challenge:
-
-**Thought 1**: Question the fundamental assumptions
-**Thought 2**: Examine contradictory evidence
-**Thought 3**: Explore alternative approaches
-**Thought 4**: Assess context-specific fit
-**Thought 5**: Evaluate risks and trade-offs
-**Thought 6**: Synthesize findings into recommendation
-
-Build systematically through evidence, alternatives, and risks.
-Continue until you reach a clear conclusion.
-</strategist>
-
-## Step 4: Critical Evaluation Output
-
-**Self-Critique Questions:**
-- Does the analysis address the user's specific context?
-- Are the recommendations practical and implementable?
-- Have we considered the most important constraints?
-- Are there any blind spots or missing perspectives?
-
-**Final Synthesis:**
-- **Assumption validity**: Are the underlying assumptions sound?
-- **Evidence assessment**: Does evidence support or contradict?
-- **Alternative recommendation**: If current approach is problematic, what instead?
-- **Risk mitigation**: How to address identified concerns?
-
----
-
-## Usage Examples
-
-**Challenge Technical Decisions:**
-```
-/atelier-challenge "Do we really need a microservices architecture for this simple app?"
-```
-
-**Challenge Implementation Approach:**
-```
-/atelier-challenge "I think this caching strategy will actually slow things down"
-```
-
-**Challenge Requirements:**
-```
-/atelier-challenge "Are we solving the right problem with this feature?"
-```
-
-**Challenge Architectural Patterns:**
-```
-/atelier-challenge "Should we really use event sourcing for this use case?"
-```
-
-## When to Use Challenge
-
-**Before Major Decisions:**
-- Architecture choices
-- Technology stack decisions
-- Design pattern selection
-- Implementation approach
-
-**When Something Feels Off:**
-- "This seems overly complex"
-- "I'm not sure this solves the real problem"
-- "This approach feels wrong"
-- "Are we over-engineering this?"
-
-**To Prevent Automatic Agreement:**
-- When you want genuine critical evaluation
-- When you need to challenge conventional wisdom
-- When you want to test your own assumptions
-
-## Challenge vs ThinkDeep
-
-**Use /atelier-challenge**: Question assumptions, test validity, assess risks, prevent automatic agreement
-**Use /atelier-thinkdeep**: Deep exploration, comprehensive analysis, alternative discovery, complex decisions
-
-**Key distinction**: Challenge = critical evaluation, ThinkDeep = deep exploration