@martinffx/atelier 0.1.0

package/skills/oracle-architect/references/data-modeling.md

@@ -0,0 +1,318 @@
+# Data Modeling Reference
+
+Entity design principles, schema patterns, and access pattern optimization.
+
+## Entity Design
+
+### Design Process
+1. Start with domain concepts from product requirements
+2. Identify aggregates and their boundaries
+3. Define attributes and relationships
+4. Add validation rules and invariants
+5. Include transformation methods (fromRequest, toRecord, toResponse)
+
+### Entity Structure
+
+**Core transformation methods:**
+```typescript
+class Order {
+  // Create from external request
+  static fromRequest(req: CreateOrderRequest): Order
+
+  // Create from database record
+  static fromRecord(record: OrderRecord): Order
+
+  // Convert to database record
+  toRecord(): OrderRecord
+
+  // Convert to API response
+  toResponse(): OrderResponse
+
+  // Validate invariants
+  validate(): Result<Order>
+}
+```
+
+### Example Entity Design
+
+```typescript
+class Order {
+  constructor(
+    public readonly id: string,
+    public readonly customerId: string,
+    public readonly items: OrderItem[],
+    public readonly status: OrderStatus,
+    public readonly total: number,
+    public readonly createdAt: Date,
+    public readonly metadata: OrderMetadata
+  ) {}
+
+  static fromRequest(req: CreateOrderRequest): Order {
+    return new Order(
+      generateId(),
+      req.customerId,
+      req.items.map(i => new OrderItem(i)),
+      'pending',
+      req.items.reduce((sum, i) => sum + i.price * i.quantity, 0),
+      new Date(),
+      { source: req.source || 'web' }
+    );
+  }
+
+  toRecord(): OrderRecord {
+    return {
+      id: this.id,
+      customer_id: this.customerId,
+      items: JSON.stringify(this.items),
+      status: this.status,
+      total: this.total,
+      created_at: this.createdAt.toISOString(),
+      metadata: this.metadata
+    };
+  }
+
+  toResponse(): OrderResponse {
+    return {
+      id: this.id,
+      customerId: this.customerId,
+      items: this.items,
+      status: this.status,
+      total: this.total,
+      createdAt: this.createdAt.toISOString()
+    };
+  }
+
+  validate(): Result<Order> {
+    if (this.items.length === 0) {
+      return Err('Order must have at least one item');
+    }
+    if (this.total < 0) {
+      return Err('Order total cannot be negative');
+    }
+    return Ok(this);
+  }
+}
+```
+
+## Schema Patterns
+
+### Relational Design
+
+**Orders table:**
+```sql
+CREATE TABLE orders (
+  id UUID PRIMARY KEY,
+  customer_id UUID NOT NULL REFERENCES customers(id),
+  status VARCHAR(20) NOT NULL CHECK (status IN ('pending', 'confirmed', 'shipped', 'delivered')),
+  total DECIMAL(10,2) NOT NULL,
+  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX idx_orders_customer ON orders(customer_id);
+CREATE INDEX idx_orders_status ON orders(status);
+CREATE INDEX idx_orders_created ON orders(created_at DESC);
+```
+
+**Order items (normalized):**
+```sql
+CREATE TABLE order_items (
+  id UUID PRIMARY KEY,
+  order_id UUID NOT NULL REFERENCES orders(id) ON DELETE CASCADE,
+  product_id UUID NOT NULL,
+  quantity INT NOT NULL CHECK (quantity > 0),
+  price DECIMAL(10,2) NOT NULL,
+  UNIQUE(order_id, product_id)
+);
+
+CREATE INDEX idx_order_items_order ON order_items(order_id);
+```
+
+### DynamoDB Single Table Design
+
+**Items structure:**
+```typescript
+{
+  PK: 'ORDER#123',
+  SK: 'ORDER#123',
+  type: 'Order',
+  customerId: 'CUST#456',
+  status: 'pending',
+  total: 99.99,
+  items: [...],
+  createdAt: '2024-01-21T10:00:00Z',
+
+  // GSI for customer lookup
+  GSI1PK: 'CUST#456',
+  GSI1SK: 'ORDER#2024-01-21T10:00:00Z',
+
+  // GSI for status lookup
+  GSI2PK: 'pending',
+  GSI2SK: 'ORDER#2024-01-21T10:00:00Z'
+}
+
+{
+  PK: 'ORDER#123',
+  SK: 'ITEM#item-001',
+  type: 'OrderItem',
+  productId: 'PROD#999',
+  quantity: 2,
+  price: 49.99
+}
+```
+
+**Key design:**
+- PK = partition key (primary lookup)
+- SK = sort key (range queries)
+- GSI = global secondary index (alternative queries)
+
+## Access Patterns
+
+### Define Patterns First
+
+List all data access patterns **before** designing schema:
+
+1. **Find order by ID**
+   - Query: `PK = ORDER#123, SK = ORDER#123`
+   - Index: Primary key
+
+2. **List orders by customer**
+   - Query: `GSI1PK = CUST#456`
+   - Index: Global secondary index
+
+3. **List pending orders by date**
+   - Query: `GSI2PK = pending, GSI2SK > date`
+   - Index: Global secondary index sorted by date
+
+4. **Count orders by status**
+   - Query: Scan with filter (or GSI)
+   - Performance: Consider status table
+
+5. **Get recent orders for customer**
+   - Query: `GSI1PK = CUST#456` sorted by date DESC
+   - Index: Global secondary index
+
+### Query Optimization
+
+**N+1 Problem:**
+```typescript
+// BAD: N+1 queries
+const orders = await orderRepo.findByCustomer(customerId);
+const itemsPerOrder = await Promise.all(
+  orders.map(o => itemRepo.findByOrder(o.id))  // N queries
+);
+
+// GOOD: Single query with denormalization
+const orderData = await db.orders
+  .where({ customerId })
+  .select(['*', 'items']) // Includes denormalized items
+  .sort({ createdAt: 'DESC' });
+```
+
+**Index Coverage:**
+```sql
+-- Bad: Full table scan
+SELECT * FROM orders WHERE customer_id = $1;
+
+-- Good: Index-covered query
+CREATE INDEX idx_orders_customer_status
+ON orders(customer_id, status);
+
+SELECT * FROM orders
+WHERE customer_id = $1 AND status = 'pending';
+```
+
+## Data Transformation Patterns
+
+### Request → Entity → Record → Response Flow
+
+```typescript
+// 1. HTTP Request arrives
+POST /orders
+{
+  "customerId": "cust-123",
+  "items": [{ "productId": "prod-1", "quantity": 2 }]
+}
+
+// 2. Router parses to request type
+const request: CreateOrderRequest = req.body;
+
+// 3. Entity transforms from request (with ID generation)
+const order = Order.fromRequest(request);
+
+// 4. Entity validates business rules
+const validation = order.validate();
+if (!validation.ok) return error;
+
+// 5. Service performs logic, uses repository
+await repo.save(order.toRecord());
+
+// 6. Repository converts to database record
+{
+  id: "order-abc",
+  customer_id: "cust-123",
+  items: "[...]",
+  status: "pending",
+  created_at: "2024-01-21T10:00:00Z"
+}
+
+// 7. Response converts from record
+const response = order.toResponse();
+
+// 8. HTTP Response sends
+{
+  "id": "order-abc",
+  "customerId": "cust-123",
+  "items": [...],
+  "status": "pending"
+}
+```
+
+### Transformation Considerations
+
+**Immutability:**
+```typescript
+// Bad: Mutation during transform
+toRecord(): OrderRecord {
+  this.items.forEach(i => i.status = 'recorded');
+  return { items: this.items };
+}
+
+// Good: No side effects
+toRecord(): OrderRecord {
+  return {
+    items: this.items.map(i => ({
+      ...i,
+      // Transform properties as needed
+    }))
+  };
+}
+```
+
+**Versioning:**
+```typescript
+// Handle multiple API versions
+toResponse(version: 'v1' | 'v2'): OrderResponse {
+  const base = {
+    id: this.id,
+    customerId: this.customerId,
+    status: this.status
+  };
+
+  if (version === 'v2') {
+    return { ...base, total: this.total };
+  }
+  return base;
+}
+```
+
+**Partial Loading:**
+```typescript
+// Only load fields needed for the operation
+async findOrderSummary(id: string): Promise<OrderSummary> {
+  const record = await db.orders
+    .select(['id', 'status', 'total'])
+    .findOne({ id });
+  return { id: record.id, status: record.status, total: record.total };
+}
+```

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

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

package/skills/oracle-challenge/SKILL.md

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