@martinffx/atelier 0.1.0

package/skills/oracle-testing/references/stub-driven-tdd.md

@@ -0,0 +1,322 @@
+# Stub-Driven TDD Workflow
+
+Complete workflow examples showing the Stub → Test → Implement → Refactor pattern.
+
+## The Four-Step Pattern
+
+```
+1. Stub   → Create minimal interface/function signatures
+2. Test   → Write tests against stubs
+3. Implement → Make tests pass with real implementation
+4. Refactor  → Improve code while keeping tests green
+```
+
+## Why Stub-Driven?
+
+**Traditional TDD problem:** Can't write tests until implementation exists
+
+**Stub-Driven solution:** Write interface/type signatures first, test against those, then implement
+
+**Benefits:**
+- Tests define behavior before implementation
+- Interfaces emerge from use cases, not speculation
+- Refactoring is safe (tests validate behavior)
+- Fast feedback loop (stub → test → implement)
+
+## Complete Order Service Example
+
+### Step 1: Stub
+
+Define the interface and service class with stub methods:
+
+```typescript
+// Define repository interface from use case
+interface OrderRepository {
+  save(order: OrderRecord): Promise<OrderRecord>;
+  findById(id: string): Promise<OrderRecord | null>;
+  delete(id: string): Promise<void>;
+}
+
+// Service uses stub - methods throw NotImplemented
+class OrderService {
+  constructor(private repo: OrderRepository) {}
+
+  async createOrder(request: CreateOrderRequest): Promise<Result<Order>> {
+    throw new Error('Not implemented');
+  }
+
+  async cancelOrder(id: string): Promise<Result<void>> {
+    throw new Error('Not implemented');
+  }
+
+  async getOrder(id: string): Promise<Result<Order>> {
+    throw new Error('Not implemented');
+  }
+}
+
+// Export for testing
+export { OrderService, OrderRepository };
+```
+
+### Step 2: Test
+
+Write comprehensive tests against the stubs:
+
+```typescript
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { OrderService, OrderRepository } from './order-service';
+import { CreateOrderRequest, OrderRecord, Order } from './order';
+import { Ok, Err } from './result';
+
+describe('OrderService', () => {
+  let service: OrderService;
+  let mockRepo: OrderRepository;
+
+  beforeEach(() => {
+    // Create stub implementation
+    mockRepo = {
+      save: vi.fn(),
+      findById: vi.fn(),
+      delete: vi.fn()
+    };
+    service = new OrderService(mockRepo);
+  });
+
+  describe('createOrder', () => {
+    it('should save valid order', async () => {
+      mockRepo.save.mockResolvedValue({
+        id: '123',
+        customer_id: 'C1',
+        items: '[]',
+        status: 'pending',
+        total: 0
+      });
+
+      const result = await service.createOrder({
+        customerId: 'C1',
+        items: [{ productId: 'P1', quantity: 2, price: 10 }]
+      });
+
+      expect(result.ok).toBe(true);
+      expect(mockRepo.save).toHaveBeenCalledWith(
+        expect.objectContaining({
+          customer_id: 'C1',
+          status: 'pending'
+        })
+      );
+    });
+
+    it('should validate order before saving', async () => {
+      const result = await service.createOrder({
+        customerId: 'C1',
+        items: [] // Invalid: empty items
+      });
+
+      expect(result.ok).toBe(false);
+      expect(mockRepo.save).not.toHaveBeenCalled();
+    });
+
+    it('should calculate total correctly', async () => {
+      mockRepo.save.mockResolvedValue({
+        id: '123',
+        customer_id: 'C1',
+        items: '[]',
+        status: 'pending',
+        total: 0
+      });
+
+      await service.createOrder({
+        customerId: 'C1',
+        items: [
+          { productId: 'P1', quantity: 2, price: 10 },
+          { productId: 'P2', quantity: 1, price: 15 }
+        ]
+      });
+
+      expect(mockRepo.save).toHaveBeenCalledWith(
+        expect.objectContaining({ total: 35 })
+      );
+    });
+  });
+
+  describe('cancelOrder', () => {
+    it('should cancel pending order', async () => {
+      mockRepo.findById.mockResolvedValue({
+        id: '123',
+        customer_id: 'C1',
+        items: '[]',
+        status: 'pending',
+        total: 0
+      });
+      mockRepo.delete.mockResolvedValue(undefined);
+
+      const result = await service.cancelOrder('123');
+
+      expect(result.ok).toBe(true);
+      expect(mockRepo.delete).toHaveBeenCalledWith('123');
+    });
+
+    it('should reject canceling shipped order', async () => {
+      mockRepo.findById.mockResolvedValue({
+        id: '123',
+        customer_id: 'C1',
+        items: '[]',
+        status: 'shipped',
+        total: 0
+      });
+
+      const result = await service.cancelOrder('123');
+
+      expect(result.ok).toBe(false);
+      expect(mockRepo.delete).not.toHaveBeenCalled();
+    });
+
+    it('should reject canceling non-existent order', async () => {
+      mockRepo.findById.mockResolvedValue(null);
+
+      const result = await service.cancelOrder('999');
+
+      expect(result.ok).toBe(false);
+    });
+  });
+
+  describe('getOrder', () => {
+    it('should retrieve order by id', async () => {
+      mockRepo.findById.mockResolvedValue({
+        id: '123',
+        customer_id: 'C1',
+        items: '[]',
+        status: 'pending',
+        total: 0
+      });
+
+      const result = await service.getOrder('123');
+
+      expect(result.ok).toBe(true);
+      if (result.ok) {
+        expect(result.value.id).toBe('123');
+      }
+    });
+
+    it('should return error for non-existent order', async () => {
+      mockRepo.findById.mockResolvedValue(null);
+
+      const result = await service.getOrder('999');
+
+      expect(result.ok).toBe(false);
+    });
+  });
+});
+```
+
+### Step 3: Implement
+
+Make tests pass with real implementation:
+
+```typescript
+class OrderService {
+  constructor(private repo: OrderRepository) {}
+
+  async createOrder(request: CreateOrderRequest): Promise<Result<Order>> {
+    // Transform request to entity
+    const order = Order.fromRequest(request);
+
+    // Validate
+    const validation = order.validate();
+    if (!validation.ok) return validation;
+
+    // Save to repository
+    const record = order.toRecord();
+    const saved = await this.repo.save(record);
+
+    // Transform back to entity
+    return Ok(Order.fromRecord(saved));
+  }
+
+  async cancelOrder(id: string): Promise<Result<void>> {
+    // Find order
+    const record = await this.repo.findById(id);
+    if (!record) return Err('Order not found');
+
+    // Transform to entity
+    const order = Order.fromRecord(record);
+
+    // Check business rule
+    if (!order.canCancel()) {
+      return Err(`Cannot cancel ${order.status} order`);
+    }
+
+    // Delete
+    await this.repo.delete(id);
+    return Ok(undefined);
+  }
+
+  async getOrder(id: string): Promise<Result<Order>> {
+    // Find order
+    const record = await this.repo.findById(id);
+    if (!record) return Err('Order not found');
+
+    // Transform to entity
+    return Ok(Order.fromRecord(record));
+  }
+}
+```
+
+### Step 4: Refactor
+
+Improve code while keeping tests green:
+
+```typescript
+class OrderService {
+  constructor(private repo: OrderRepository) {}
+
+  async createOrder(request: CreateOrderRequest): Promise<Result<Order>> {
+    const order = Order.fromRequest(request);
+    return await this.validateAndSave(order);
+  }
+
+  async cancelOrder(id: string): Promise<Result<void>> {
+    const order = await this.findOrderOrError(id);
+    if (!order.ok) return order;
+
+    return await this.checkCancellableAndDelete(order.value);
+  }
+
+  async getOrder(id: string): Promise<Result<Order>> {
+    return await this.findOrderOrError(id);
+  }
+
+  private async validateAndSave(order: Order): Promise<Result<Order>> {
+    const validation = order.validate();
+    if (!validation.ok) return validation;
+
+    const record = order.toRecord();
+    const saved = await this.repo.save(record);
+    return Ok(Order.fromRecord(saved));
+  }
+
+  private async findOrderOrError(id: string): Promise<Result<Order>> {
+    const record = await this.repo.findById(id);
+    if (!record) return Err('Order not found');
+    return Ok(Order.fromRecord(record));
+  }
+
+  private async checkCancellableAndDelete(order: Order): Promise<Result<void>> {
+    if (!order.canCancel()) {
+      return Err(`Cannot cancel ${order.status} order`);
+    }
+    await this.repo.delete(order.id);
+    return Ok(undefined);
+  }
+}
+```
+
+All tests still pass after refactoring - behavior is unchanged, only implementation improved.
+
+## Key Takeaways
+
+1. **Start with stubs** - Define interfaces before implementation
+2. **Test against contracts** - Test the interface, not the implementation
+3. **Implement once tests are clear** - Make tests pass with real code
+4. **Refactor with confidence** - Tests validate behavior doesn't change
+5. **Keep feedback loop fast** - Each step is quick and focused

package/skills/oracle-thinkdeep/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: oracle-thinkdeep
+description: Extended reasoning analysis using sequential thinking. Use for deep exploration, comprehensive analysis, complex decisions, or when you need fresh perspectives on difficult problems.
+user-invocable: true
+---
+
+# ThinkDeep: Extended Reasoning Analysis
+
+## Step 1: Parse Request Parameters
+
+<strategist>
+@agent-oracle
+
+Analyze the thinkdeep request: $ARGUMENTS
+
+**Parameter Extraction:**
+- **Main prompt**: [extract core thinking request]
+- **Focus areas**: [extract "architecture, performance, security" etc]
+- **File references**: [extract "reference to file.py" patterns]
+- **Problem context**: [extract additional context provided]
+
+**Parsed Configuration:**
+- Prompt: [core request]
+- Focus areas: [identified areas]
+- File references: [any files mentioned]
+- Problem context: [additional context]
+</strategist>
+
+## Step 2: Deep Sequential Analysis
+
+<strategist>
+@agent-oracle
+
+Use sequential thinking (mcp__sequential-thinking__sequentialthinking) for extended reasoning:
+
+### Thought 1: Context Understanding
+Analyze the current session context to understand:
+- What has been discussed so far
+- Previous decisions and analyses made
+- User's specific constraints and goals
+- Existing solutions or approaches tried
+
+### Thought 2: Problem Decomposition
+Break down the core issue into:
+- Primary problem statement
+- Key sub-problems or components
+- Underlying assumptions and constraints
+- Success criteria and desired outcomes
+
+### Thought 3: Assumption Challenge
+Question the underlying assumptions:
+- What assumptions are we making?
+- Are these assumptions valid in this context?
+- What if the opposite were true?
+- Alternative perspectives to consider
+
+### Thought 4: Alternative Approaches Exploration
+Explore different solution paths:
+- Conventional approaches and their pros/cons
+- Unconventional or innovative solutions
+- Trade-offs between different options
+- Hybrid or combined approaches
+
+### Thought 5: Context Integration
+Incorporate relevant context:
+- File references and code patterns
+- Previous session insights
+- User's specific technical stack
+- Business or project constraints
+
+### Thought 6: Edge Case Analysis
+Identify potential issues:
+- What could go wrong with each approach?
+- Edge cases and failure modes
+- Scalability and performance concerns
+- Security and maintenance implications
+
+### Thought 7: Risk Assessment
+Evaluate risks for each option:
+- Implementation complexity
+- Technical debt potential
+- Team skill requirements
+- Timeline and resource impacts
+
+### Thought 8: Solution Synthesis
+Combine insights into recommendations:
+- Primary recommended approach
+- Backup or alternative options
+- Implementation considerations
+- Next steps and validation points
+
+Continue sequential thinking until satisfaction, using:
+- `isRevision: true` to refine previous thoughts
+- `branchFromThought` to explore alternative reasoning paths
+- `needsMoreThoughts: true` to extend analysis if needed
+</strategist>
+
+## Step 3: Critical Evaluation & Synthesis
+
+**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?
+
+**Contextual Validation:**
+- Fit with user's technical stack and preferences
+- Alignment with previous decisions in session
+- Practicality given team skills and resources
+- Integration with existing systems or patterns
+
+**Final Synthesis:**
+- **Primary Recommendation**: [best approach with rationale]
+- **Alternative Options**: [backup plans with trade-offs]
+- **Implementation Guidance**: [key considerations and next steps]
+- **Risk Mitigation**: [how to address identified concerns]
+
+---
+
+## Usage Examples
+
+**Basic deep analysis:**
+```
+/atelier-thinkdeep "Analyze my authentication architecture"
+```
+
+**With file references:**
+```
+/atelier-thinkdeep "Evaluate my database schema with reference to models/user.py"
+```
+
+**With focus areas:**
+```
+/atelier-thinkdeep "Assess my microservices design focusing on performance and security"
+```
+
+**Complex architectural decisions:**
+```
+/atelier-thinkdeep "Should I use GraphQL or REST for my API considering team skills and scalability needs"
+```
+
+## When to Use ThinkDeep
+
+- **Architecture decisions**: When choosing between major design approaches
+- **Complex problem solving**: Multi-faceted issues requiring deep analysis
+- **Assumption validation**: Challenging conventional wisdom or previous decisions
+- **Alternative exploration**: When stuck and need fresh perspectives
+- **Risk assessment**: Before major implementation decisions
+
+## ThinkDeep vs Challenge
+
+**Use /atelier-thinkdeep**: Deep exploration, comprehensive analysis, alternative discovery, complex decisions
+**Use /atelier-challenge**: Question assumptions, test validity, assess risks, prevent automatic agreement
+
+**Key distinction**: ThinkDeep = deep exploration, Challenge = critical evaluation
+
+## Expected Outcomes
+
+After using this command:
+- Comprehensive understanding of the problem space
+- Multiple approaches evaluated with trade-offs
+- Clear recommendation with solid reasoning
+- Risk assessment and mitigation strategies
+- Actionable next steps for implementation

package/skills/python-architecture/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: python-architecture
+description: Python application architecture with functional core, effectful shell, DDD, and data modeling. Use when designing application layers, separating pure business logic from IO, defining domain models, implementing validation, or structuring bounded contexts.
+user-invocable: false
+---
+
+# Python Application Architecture
+
+Modern Python application architecture following functional core / imperative shell pattern, Domain-Driven Design, and type-safe data modeling.
+
+## Core Principle: Functional Core / Imperative Shell
+
+Separate pure business logic from side effects:
+
+- **Functional Core**: Pure functions, business logic, no IO
+- **Imperative Shell**: Coordinates external dependencies, handles side effects
+
+See [references/functional-core.md](references/functional-core.md) for detailed patterns and examples.
+
+## Layered Architecture
+
+Follow bottom-up dependency flow:
+
+```
+Router/Handler → Service → Repository → Entity → Database
+```
+
+Each layer depends only on layers below.
+
+**Responsibilities:**
+- **Entity**: Domain models, validation, business rules, data transformations (fromRequest, toRecord, toResponse)
+- **Repository**: Abstract storage interface, returns domain entities
+- **Service**: Business workflows, orchestrates entities and repositories
+- **Router/Handler**: HTTP handling, delegates to services
+
+## Domain Models
+
+### Entity Example
+
+```python
+from dataclasses import dataclass
+from uuid import UUID
+from decimal import Decimal
+
+@dataclass
+class Order:
+    """Entity - has identity and encapsulated behavior"""
+    id: UUID
+    customer_id: UUID
+    total: Decimal
+    status: str
+
+    def apply_discount(self, rate: Decimal) -> None:
+        """Business rule - encapsulated in entity"""
+        if self.status == "pending":
+            self.total = self.total * (1 - rate)
+
+    @classmethod
+    def from_request(cls, req, customer_id: UUID) -> "Order":
+        """Transform API request → entity"""
+        return cls(id=uuid4(), customer_id=customer_id, total=Decimal("0"), status="pending")
+
+    def to_response(self):
+        """Transform entity → API response"""
+        return {"id": self.id, "total": self.total, "status": self.status}
+```
+
+### Value Object Example
+
+```python
+from dataclasses import dataclass
+
+@dataclass(frozen=True)
+class Money:
+    """Value object - immutable, no identity"""
+    amount: Decimal
+    currency: str
+
+    def add(self, other: "Money") -> "Money":
+        if self.currency != other.currency:
+            raise ValueError("Cannot add different currencies")
+        return Money(self.amount + other.amount, self.currency)
+```
+
+See [references/ddd.md](references/ddd.md) for aggregates, bounded contexts, and domain services.
+
+## Repository Pattern
+
+Abstract storage behind interface:
+
+```python
+from abc import ABC, abstractmethod
+from typing import Optional
+
+class OrderRepository(ABC):
+    """Abstract repository - interface only"""
+
+    @abstractmethod
+    def get(self, order_id: UUID) -> Optional[Order]:
+        pass
+
+    @abstractmethod
+    def save(self, order: Order) -> None:
+        pass
+
+class PostgresOrderRepository(OrderRepository):
+    """Concrete implementation"""
+
+    def get(self, order_id: UUID) -> Optional[Order]:
+        record = self.session.get(OrderRecord, order_id)
+        return Order.from_record(record) if record else None
+
+    def save(self, order: Order) -> None:
+        record = order.to_record()
+        self.session.merge(record)
+        self.session.commit()
+```
+
+## Data Modeling
+
+- **dataclasses**: Domain models and internal logic (lightweight, standard library)
+- **Pydantic**: API boundaries (validation, JSON schema, OpenAPI)
+- **Entity transformations**: `from_request()`, `to_response()`, `from_record()`, `to_record()`
+
+See [references/data-modeling.md](references/data-modeling.md) for validation patterns, Pydantic features, and transformation examples.
+
+## Best Practices
+
+1. **Pure functions first** - Write business logic without IO dependencies
+2. **Entity encapsulation** - Keep business rules inside entities
+3. **Repository abstraction** - Hide storage details, work with domain entities
+4. **Validate at boundaries** - Use Pydantic at API edges, simple validation in entities
+5. **Immutable value objects** - Always use `frozen=True`
+6. **Single Responsibility** - Each layer has one reason to change
+7. **Dependency direction** - Always depend on abstractions, not implementations
+
+## Anti-Patterns
+
+❌ **Anemic Domain Model** - Entities with only getters/setters, all logic in services
+❌ **Transaction Script** - All logic in service layer, entities just data
+❌ **Leaky Abstraction** - Repository exposing database details
+❌ **God Object** - Entity with too many responsibilities
+❌ **Mixed Concerns** - Business logic calling IO directly
+
+For detailed examples, patterns, and decision trees, see the reference materials:
+- [references/functional-core.md](references/functional-core.md) - Core vs shell separation
+- [references/ddd.md](references/ddd.md) - DDD patterns, aggregates, bounded contexts
+- [references/data-modeling.md](references/data-modeling.md) - dataclasses, Pydantic, transformations