@martinffx/atelier 0.1.0

package/skills/code-subagents/references/spec-reviewer-prompt.md

@@ -0,0 +1,62 @@
+# Spec Compliance Reviewer Prompt Template
+
+Dispatch after the implementer completes a task. Verifies the implementation matches what
+was specified — nothing more, nothing less.
+
+**Dispatch this BEFORE the code quality review.**
+
+## Template
+
+```
+You are reviewing whether an implementation matches its specification.
+
+## What Was Requested
+
+{FULL TEXT of task requirements from plan.json}
+
+## What Implementer Claims They Built
+
+{From implementer's report}
+
+## CRITICAL: Do Not Trust the Report
+
+The implementer's report may be incomplete, inaccurate, or optimistic. You MUST verify
+everything independently.
+
+**DO NOT:**
+- Take their word for what they implemented
+- Trust their claims about completeness
+- Accept their interpretation of requirements
+
+**DO:**
+- Read the actual code they wrote
+- Compare actual implementation to requirements line by line
+- Check for missing pieces they claimed to implement
+- Look for extra features they didn't mention
+
+## Your Job
+
+Read the implementation code and verify:
+
+**Missing requirements:**
+- Did they implement everything that was requested?
+- Are there requirements they skipped or missed?
+- Did they claim something works but didn't actually implement it?
+
+**Extra/unneeded work:**
+- Did they build things that weren't requested?
+- Did they over-engineer or add unnecessary features?
+- Did they add "nice to haves" that weren't in spec?
+
+**Misunderstandings:**
+- Did they interpret requirements differently than intended?
+- Did they solve the wrong problem?
+- Did they implement the right feature but the wrong way?
+
+**Verify by reading code, not by trusting the report.**
+
+## Report
+
+- ✅ Spec compliant (if everything matches after code inspection)
+- ❌ Issues found: [list specifically what's missing or extra, with file:line references]
+```

package/skills/oracle-architect/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: oracle-architect
+description: DDD and hexagonal architecture with functional core pattern. Use when designing features, modeling domains, breaking down tasks, or understanding component responsibilities.
+user-invocable: false
+---
+
+# Architect Skill
+
+Domain-Driven Design and hexagonal architecture with functional core pattern for feature design.
+
+## Architecture Model
+
+Unified view of functional core and effectful edge:
+
+```
+          Effectful Edge (IO)              Functional Core (Pure)
+┌─────────────────────────────────┐    ┌──────────────────────────┐
+│  Router    → request parsing    │    │  Service  → orchestration│
+│  Consumer  → event handling     │───▶│  Entity   → domain rules │
+│  Client    → external APIs      │    │            → validation  │
+│  Producer  → event publishing   │◀───│            → transforms  │
+│  Repository→ data persistence   │    │                          │
+└─────────────────────────────────┘    └──────────────────────────┘
+```
+
+**Key Principle:** Business logic lives in the functional core (Service + Entity). IO operations live in the effectful edge. Core defines interfaces; edge implements them (dependency inversion).
+
+## Functional Core
+
+Pure, deterministic components containing all business logic.
+
+### Service Layer
+
+**Responsibility:** Orchestrate business operations, coordinate between entities and repositories.
+
+**Characteristics:**
+- Pure functions that take data and return results
+- No IO operations (database, HTTP, file system)
+- Calls repositories through interfaces (dependency injection)
+- Composes entity operations into workflows
+- Returns success/error results
+
+**Example:**
+```typescript
+class OrderService {
+  async createOrder(request: CreateOrderRequest): Promise<Result<Order>> {
+    // Validate with entity
+    const order = Order.fromRequest(request);
+    const validation = order.validate();
+    if (!validation.ok) return validation;
+
+    // Check business rules
+    const inventory = await this.inventoryRepo.checkAvailability(order.items);
+    if (!inventory.available) return Err('Items not available');
+
+    // Coordinate persistence
+    await this.inventoryRepo.reserve(order.items);
+    const saved = await this.orderRepo.save(order.toRecord());
+
+    return Ok(Order.fromRecord(saved));
+  }
+}
+```
+
+### Entity Layer
+
+**Responsibility:** Domain models, validation, business rules, data transformations.
+
+**Characteristics:**
+- Pure data structures with behavior
+- All validation logic
+- Data transformations (fromRequest, toRecord, toResponse)
+- Business rules and invariants
+- No IO, no framework dependencies
+
+**Example:**
+```typescript
+class Order {
+  constructor(
+    public readonly id: string,
+    public readonly customerId: string,
+    public readonly items: OrderItem[],
+    public readonly status: OrderStatus,
+    public readonly total: number
+  ) {}
+
+  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)
+    );
+  }
+
+  toRecord(): OrderRecord {
+    return {
+      id: this.id,
+      customer_id: this.customerId,
+      items: JSON.stringify(this.items),
+      status: this.status,
+      total: this.total
+    };
+  }
+
+  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);
+  }
+
+  canCancel(): boolean {
+    return ['pending', 'confirmed'].includes(this.status);
+  }
+}
+```
+
+## Effectful Edge
+
+IO-performing components that interact with the outside world.
+
+### Router
+
+**Responsibility:** HTTP request handling, parsing, response formatting.
+
+**Characteristics:**
+- Parses HTTP requests into domain types
+- Calls service layer with parsed data
+- Formats service results into HTTP responses
+- Handles HTTP-specific concerns (status codes, headers)
+- No business logic
+
+**Example:**
+```typescript
+router.post('/orders', async (req, res) => {
+  const result = await orderService.createOrder(req.body);
+
+  if (result.ok) {
+    res.status(201).json(result.value.toResponse());
+  } else {
+    res.status(400).json({ error: result.error });
+  }
+});
+```
+
+### Repository
+
+**Responsibility:** Data persistence and retrieval.
+
+**Characteristics:**
+- Implements data access interface used by services
+- Converts between domain entities and database records
+- Handles database queries and transactions
+- No business logic or validation
+
+**Example:**
+```typescript
+class OrderRepository {
+  async save(record: OrderRecord): Promise<OrderRecord> {
+    return await db.orders.create(record);
+  }
+
+  async findById(id: string): Promise<OrderRecord | null> {
+    return await db.orders.findOne({ id });
+  }
+}
+```
+
+## Component Matrix
+
+Quick reference for where things belong:
+
+| Concern | Component | Layer | Testability |
+|---------|-----------|-------|-------------|
+| Domain model | Entity | Core | Unit test (pure) |
+| Validation | Entity | Core | Unit test (pure) |
+| Business rules | Entity | Core | Unit test (pure) |
+| Orchestration | Service | Core | Unit test (stub repos) |
+| Data transforms | Entity | Core | Unit test (pure) |
+| HTTP parsing | Router | Edge | Integration test |
+| Data access | Repository | Edge | Integration test |
+| External APIs | Client | Edge | Integration test |
+| Event handling | Consumer | Edge | Integration test |
+| Event publishing | Producer | Edge | Integration test |
+
+## Task Breakdown
+
+### Bottom-Up Dependency Ordering
+
+Implementation order follows dependency chain:
+
+```
+1. Entity   → Domain models, validation, transforms
+2. Repository → Data access interfaces and implementations
+3. Service  → Business logic orchestration
+4. Router   → HTTP endpoints
+```
+
+**Rationale:** Each layer depends on layers below. Can't implement service without entity, can't implement router without service.
+
+### Task Granularity
+
+**One task per layer:**
+- Implement Order entity with validation
+- Implement OrderRepository with data access
+- Implement OrderService with business logic
+- Implement order API endpoints
+
+**For complex features, break down further:**
+- Entity: Order, OrderItem, OrderStatus
+- Repository: OrderRepository, InventoryRepository
+- Service: OrderService, PaymentService
+- Router: Order routes, Payment routes
+
+## Architect → Testing Flow
+
+Architectural decisions inform testing strategy:
+
+```
+Architect Outputs           →    Testing Inputs
+────────────────────────────────────────────────
+Component responsibilities  →    What to test
+Layer boundaries           →    Where to test
+Pure vs effectful          →    Unit vs integration
+Entity transformations     →    Property-based tests
+Service orchestration      →    Stub-driven tests
+```
+
+The testing skill uses architectural structure to determine:
+- What gets unit tested (core) vs integration tested (edge)
+- Where to place test boundaries
+- What to stub and what to test for real
+- What test cases validate business rules
+
+## Reference Materials
+
+For detailed patterns and examples:
+
+- **See [references/ddd-patterns.md](references/ddd-patterns.md)** - Aggregates, Value Objects, Domain Events, Bounded Contexts, composition patterns
+- **See [references/data-modeling.md](references/data-modeling.md)** - Entity design principles, schema patterns, access pattern optimization, data transformation
+- **See [references/api-design.md](references/api-design.md)** - REST conventions, request/response contracts, error handling, versioning patterns

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

@@ -0,0 +1,345 @@
+# API Design Reference
+
+REST conventions, request/response contracts, and error handling patterns.
+
+## REST Conventions
+
+### Resource-Oriented Endpoints
+
+**Standard CRUD operations:**
+```
+GET    /orders          # List orders
+POST   /orders          # Create order
+GET    /orders/:id      # Get single order
+PATCH  /orders/:id      # Update order
+DELETE /orders/:id      # Delete order
+```
+
+**Nested resources:**
+```
+GET    /orders/:orderId/items          # List order items
+POST   /orders/:orderId/items          # Add item to order
+GET    /orders/:orderId/items/:itemId  # Get order item
+PATCH  /orders/:orderId/items/:itemId  # Update order item
+DELETE /orders/:orderId/items/:itemId  # Delete order item
+```
+
+### Actions (Non-CRUD Operations)
+
+**Use POST for state transitions:**
+```
+POST /orders/:id/cancel   # Cancel order
+POST /orders/:id/ship     # Ship order
+POST /orders/:id/confirm  # Confirm order
+```
+
+**Reasoning:** These modify state but aren't CRUD operations. They represent domain actions.
+
+**Avoid:**
+```
+PATCH /orders/:id { "action": "cancel" }  # Unclear what changed
+GET   /orders/:id/cancel                  # GET shouldn't have side effects
+```
+
+## Request/Response Contracts
+
+### Request Types
+
+**Create request (POST /resource):**
+```typescript
+interface CreateOrderRequest {
+  customerId: string;
+  items: Array<{
+    productId: string;
+    quantity: number;
+  }>;
+  shippingAddress?: {
+    street: string;
+    city: string;
+    zipCode: string;
+  };
+}
+```
+
+**Update request (PATCH /resource/:id):**
+```typescript
+interface UpdateOrderRequest {
+  status?: 'pending' | 'confirmed' | 'shipped';
+  shippingAddress?: Address;
+  // Only fields that can be updated
+}
+```
+
+**Query parameters:**
+```
+GET /orders?customerId=cust-123&status=pending&limit=20&offset=0
+
+interface ListOrdersQuery {
+  customerId?: string;
+  status?: OrderStatus;
+  limit?: number;  // Default 20, max 100
+  offset?: number; // Pagination offset
+}
+```
+
+### Response Types
+
+**Single resource (GET /resource/:id):**
+```typescript
+interface OrderResponse {
+  id: string;
+  customerId: string;
+  items: OrderItem[];
+  status: 'pending' | 'confirmed' | 'shipped' | 'delivered';
+  total: number;
+  createdAt: string;  // ISO 8601
+  updatedAt: string;
+}
+```
+
+**List response (GET /resource):**
+```typescript
+interface ListOrdersResponse {
+  data: OrderResponse[];
+  pagination: {
+    total: number;
+    limit: number;
+    offset: number;
+    hasMore: boolean;
+  };
+}
+```
+
+**Create response (POST /resource):**
+```typescript
+// Return created resource with 201 status
+interface CreateOrderResponse extends OrderResponse {
+  id: string; // Generated by server
+}
+```
+
+### Timestamp Conventions
+
+**Use ISO 8601 for all timestamps:**
+```json
+{
+  "createdAt": "2024-01-21T10:30:45Z",
+  "updatedAt": "2024-01-21T10:30:45Z",
+  "deletedAt": null
+}
+```
+
+**Never:** Unix timestamps, custom formats, or timezone abbreviations
+
+## Error Handling
+
+### HTTP Status Codes
+
+**Success:**
+- `200 OK` - GET, PATCH succeeded
+- `201 Created` - POST created resource
+- `204 No Content` - DELETE or update with no response body
+
+**Client Errors:**
+- `400 Bad Request` - Invalid input validation
+- `401 Unauthorized` - Missing authentication
+- `403 Forbidden` - Authenticated but insufficient permissions
+- `404 Not Found` - Resource not found
+- `409 Conflict` - State violation (can't transition state)
+- `422 Unprocessable Entity` - Validation failed
+
+**Server Errors:**
+- `500 Internal Server Error` - Unhandled exception
+- `503 Service Unavailable` - Temporary outage
+
+### Error Response Format
+
+**Validation error (400):**
+```typescript
+interface ValidationErrorResponse {
+  error: 'Validation failed';
+  code: 'VALIDATION_ERROR';
+  details: {
+    field: string;
+    message: string;
+  }[];
+}
+
+// Example
+{
+  "error": "Validation failed",
+  "code": "VALIDATION_ERROR",
+  "details": [
+    { "field": "items", "message": "Must have at least one item" },
+    { "field": "customerId", "message": "Invalid customer ID format" }
+  ]
+}
+```
+
+**Business rule violation (409):**
+```typescript
+interface ConflictErrorResponse {
+  error: string;
+  code: string;
+  details?: Record<string, unknown>;
+}
+
+// Example
+{
+  "error": "Cannot cancel shipped order",
+  "code": "ORDER_ALREADY_SHIPPED",
+  "details": {
+    "status": "shipped",
+    "orderId": "order-123"
+  }
+}
+```
+
+**Not found (404):**
+```json
+{
+  "error": "Order not found",
+  "code": "ORDER_NOT_FOUND",
+  "details": { "id": "order-123" }
+}
+```
+
+**Generic error (500):**
+```json
+{
+  "error": "Internal server error",
+  "code": "INTERNAL_ERROR"
+}
+```
+
+### Error Code Convention
+
+Use SCREAMING_SNAKE_CASE for error codes:
+- `VALIDATION_ERROR` - Input validation failed
+- `ORDER_NOT_FOUND` - Resource not found
+- `ORDER_ALREADY_SHIPPED` - State violation
+- `INSUFFICIENT_INVENTORY` - Business rule violation
+- `AUTHENTICATION_REQUIRED` - Auth failed
+- `PERMISSION_DENIED` - Authz failed
+
+## Versioning Patterns
+
+### URL Versioning
+
+**Include version in path:**
+```
+GET /v1/orders
+GET /v2/orders
+```
+
+**Pros:** Explicit, clear to consumers
+**Cons:** Requires multiple code paths
+
+### Accept Header Versioning
+
+**Use media type version:**
+```
+GET /orders
+Accept: application/vnd.myapi.v2+json
+```
+
+**Pros:** Cleaner URLs, single endpoint
+**Cons:** Less discoverable
+
+### Pragmatic Approach
+
+1. Start without versioning (all responses same format)
+2. Add versioning when you need breaking changes
+3. Support at least 2 versions during transition
+4. Provide clear deprecation timeline
+
+### Backwards Compatibility
+
+**Adding fields (safe):**
+```typescript
+// v1
+interface OrderResponse {
+  id: string;
+  total: number;
+}
+
+// v2 (backwards compatible)
+interface OrderResponse {
+  id: string;
+  total: number;
+  tax?: number;  // New optional field
+}
+```
+
+**Removing fields (breaking change):**
+```typescript
+// Requires new API version
+// v1 has 'total'
+// v2 has 'subtotal' and 'tax'
+```
+
+## Example: Complete Order API
+
+### Endpoints
+
+```
+POST /orders
+  Create order
+  Request: CreateOrderRequest
+  Response: 201 OrderResponse
+
+GET /orders
+  List orders
+  Query: ListOrdersQuery
+  Response: 200 ListOrdersResponse
+
+GET /orders/:id
+  Get order
+  Response: 200 OrderResponse
+
+PATCH /orders/:id
+  Update order
+  Request: UpdateOrderRequest
+  Response: 200 OrderResponse
+
+POST /orders/:id/cancel
+  Cancel order
+  Response: 200 OrderResponse
+
+DELETE /orders/:id
+  Delete order
+  Response: 204 (no body)
+```
+
+### Implementation Pattern
+
+```typescript
+// Router handles HTTP concerns
+router.post('/orders', async (req, res) => {
+  // 1. Parse request
+  const request: CreateOrderRequest = req.body;
+
+  // 2. Validate input (preliminary)
+  if (!request.customerId) {
+    return res.status(400).json({
+      error: 'Validation failed',
+      code: 'VALIDATION_ERROR',
+      details: [{ field: 'customerId', message: 'Required' }]
+    });
+  }
+
+  // 3. Call service
+  const result = await orderService.createOrder(request);
+
+  // 4. Handle result
+  if (result.ok) {
+    return res.status(201).json(result.value.toResponse());
+  }
+
+  // 5. Return error
+  res.status(409).json({
+    error: result.error,
+    code: result.code || 'UNKNOWN_ERROR'
+  });
+});
+```