@codihaus/claude-skills 1.0.0 → 1.3.0

package/knowledge/domains/_index.md

@@ -0,0 +1,105 @@
+# Domain Knowledge
+
+Business domain knowledge. Answers: **"WHAT do I build for this business?"**
+
+## Purpose
+
+When skills work on business-specific features, they load the relevant domain folder for:
+- Business terminology and concepts
+- Common entities and data models
+- Workflow and state machines
+- Validation rules and business logic
+- Compliance and regulatory requirements
+
+## Available Domains
+
+| Domain | Folder | Description | Status |
+|--------|--------|-------------|--------|
+| SaaS | `saas/` | Subscriptions, multi-tenancy, billing | Ready |
+| E-commerce | `ecommerce/` | Products, carts, orders, fulfillment | Ready |
+| Insurance | `insurance/` | Policies, claims, underwriting | Planned |
+| Healthcare | `healthcare/` | Patient data, HIPAA compliance | Planned |
+
+## Folder Structure
+
+Each domain follows this structure:
+
+```
+domains/{domain-name}/
+├── _index.md           # Main knowledge file
+│   ├── Overview        # What it is, key concepts
+│   ├── Terminology     # Business terms
+│   ├── Common Entities # Data models
+│   ├── Workflows       # State machines, lifecycles
+│   ├── For /dev-specs  # Spec writing guidance
+│   ├── For /dev-coding # Implementation patterns
+│   ├── For /dev-review # Review checklists
+│   └── Integration     # Common service integrations
+│
+├── references/         # Detailed documentation
+│   ├── workflows.md    # Detailed state machines
+│   ├── compliance.md   # Regulatory requirements
+│   └── glossary.md     # Extended terminology
+│
+└── assets/             # Code templates
+    ├── schema.prisma   # Example database schema
+    ├── types.ts        # TypeScript types
+    └── validation.ts   # Validation schemas
+```
+
+## How Skills Use Domain Knowledge
+
+### /dev-specs
+```
+1. Identify domain from BRD/use cases
+2. Read domains/{domain}/_index.md
+3. Use correct terminology
+4. Follow domain workflows
+5. Include domain-specific validation
+```
+
+### /dev-coding
+```
+1. Read specs → identify domain
+2. Read domains/{domain}/_index.md
+3. Use "For /dev-coding" section
+4. Implement domain state machines correctly
+5. Follow domain business rules
+```
+
+### /dev-review
+```
+1. Identify domain from code
+2. Read domains/{domain}/_index.md
+3. Use "For /dev-review" section
+4. Verify domain rules implemented correctly
+5. Check compliance requirements
+```
+
+## Detecting Domain
+
+Skills detect domain from:
+1. BRD mentions (subscription, cart, policy)
+2. Entity names (Tenant, Order, Claim)
+3. User explicitly states domain
+4. Project type indicators
+
+## Adding New Domains
+
+1. Create folder: `domains/{name}/`
+2. Create `_index.md` following the structure above
+3. Add `references/` with detailed docs
+4. Add `assets/` with code templates
+5. Update this index
+
+## Stack vs Domain
+
+| Type | Answers | Examples | Location |
+|------|---------|----------|----------|
+| **Stack** | HOW to build | Directus, Nuxt, Next.js | `knowledge/stacks/` |
+| **Domain** (this folder) | WHAT to build | SaaS, E-commerce, Insurance | `knowledge/domains/` |
+
+Stack knowledge is about the **technology**.
+Domain knowledge is about the **business**.
+
+Both inform better specs, coding, and reviews.

package/knowledge/domains/ecommerce/_index.md

@@ -0,0 +1,499 @@
+# E-commerce Domain Knowledge
+
+> Online retail business patterns and implementation guidance
+
+## Overview
+
+**What it is:**
+- Online product/service sales
+- Shopping cart and checkout flow
+- Payment processing
+- Order fulfillment and shipping
+
+**Key concepts:**
+- **SKU** = Stock Keeping Unit (unique product variant)
+- **Cart** = Temporary collection of items
+- **Order** = Confirmed purchase
+- **Fulfillment** = Picking, packing, shipping
+- **Inventory** = Stock levels and tracking
+
+## Terminology
+
+| Term | Definition |
+|------|------------|
+| SKU | Unique identifier for product variant |
+| AOV | Average Order Value |
+| GMV | Gross Merchandise Value |
+| Conversion Rate | % of visitors who purchase |
+| Cart Abandonment | % of carts not completed |
+| COGS | Cost of Goods Sold |
+| Backorder | Order for out-of-stock item |
+
+## Common Entities
+
+### Product Entities
+
+```
+Product
+├── id, name, slug, description
+├── status (draft, active, archived)
+├── category_id
+├── base_price
+├── images[]
+└── metadata (JSON)
+
+ProductVariant (SKU)
+├── product_id
+├── sku (unique)
+├── name (Size: M, Color: Red)
+├── price (override or null)
+├── attributes (JSON)
+└── inventory_quantity
+
+Category
+├── id, name, slug
+├── parent_id (hierarchical)
+└── sort_order
+
+Inventory
+├── variant_id
+├── location_id (warehouse)
+├── quantity
+├── reserved_quantity
+└── reorder_point
+```
+
+### Order Entities
+
+```
+Cart
+├── id, session_id or user_id
+├── items[]
+├── expires_at
+└── metadata
+
+CartItem
+├── cart_id
+├── variant_id
+├── quantity
+├── price_at_add
+└── metadata
+
+Order
+├── id, order_number
+├── user_id, email
+├── status (pending, paid, shipped, delivered, canceled)
+├── subtotal, tax, shipping, total
+├── shipping_address
+├── billing_address
+└── metadata
+
+OrderItem
+├── order_id
+├── variant_id
+├── quantity
+├── unit_price
+├── total_price
+└── fulfilled_quantity
+
+Payment
+├── order_id
+├── amount, currency
+├── status (pending, completed, failed, refunded)
+├── provider (stripe, paypal)
+├── provider_id
+└── metadata
+
+Shipment
+├── order_id
+├── tracking_number
+├── carrier
+├── status (pending, shipped, delivered)
+├── shipped_at
+└── items[]
+```
+
+## Order Lifecycle
+
+```
+      ┌────────────┐
+      │   Cart     │
+      └─────┬──────┘
+            │ (checkout)
+      ┌─────▼──────┐
+      │  Pending   │ (awaiting payment)
+      └─────┬──────┘
+            │
+      ┌─────▼──────┐    (payment fails)    ┌──────────┐
+      │   Paid     │─────────────────────► │  Failed  │
+      └─────┬──────┘                        └──────────┘
+            │
+      ┌─────▼──────┐
+      │ Processing │ (preparing fulfillment)
+      └─────┬──────┘
+            │
+      ┌─────▼──────┐    (partial ship)     ┌───────────────┐
+      │  Shipped   │─────────────────────► │ Partially     │
+      └─────┬──────┘                        │ Shipped       │
+            │                              └───────────────┘
+      ┌─────▼──────┐
+      │ Delivered  │
+      └─────┬──────┘
+            │ (return requested)
+      ┌─────▼──────┐
+      │  Returned  │
+      └────────────┘
+```
+
+## For /dev-specs
+
+### Cart & Checkout Spec Template
+
+```markdown
+## Feature: Shopping Cart
+
+### Entities
+- Cart: session-based or user-based
+- CartItem: product + quantity
+
+### API Endpoints
+| Method | Path | Purpose |
+|--------|------|---------|
+| GET | /api/cart | Get current cart |
+| POST | /api/cart/items | Add item |
+| PATCH | /api/cart/items/:id | Update quantity |
+| DELETE | /api/cart/items/:id | Remove item |
+| POST | /api/cart/checkout | Begin checkout |
+
+### Business Rules
+1. Cart expires after 7 days of inactivity
+2. Price locked when added (show if changed)
+3. Quantity limited by inventory
+4. Merge guest cart on login
+5. Reserve inventory during checkout (15 min)
+
+### Validation
+- Quantity > 0
+- Variant must be in stock
+- Cannot exceed max quantity per SKU
+```
+
+### Inventory Spec Template
+
+```markdown
+## Feature: Inventory Management
+
+### Stock States
+- Available = quantity - reserved
+- Reserved = items in active checkouts
+- Backordered = ordered but not in stock
+
+### Rules
+1. Decrement on order confirmation (not cart add)
+2. Reserve during checkout (timeout 15 min)
+3. Release reserved if checkout abandoned
+4. Allow backorder for specific products only
+5. Send alert when below reorder_point
+
+### Operations
+| Operation | Effect |
+|-----------|--------|
+| Add to cart | No change |
+| Begin checkout | Reserve quantity |
+| Abandon checkout | Release reserved |
+| Order confirmed | Move reserved to sold |
+| Cancel order | Return to available |
+| Receive shipment | Increase quantity |
+```
+
+## For /dev-coding
+
+### Cart Operations
+
+```typescript
+// Add to cart
+const addToCart = async (cartId: string, variantId: string, quantity: number) => {
+  // Check inventory
+  const variant = await getVariant(variantId);
+  const available = variant.inventory_quantity - variant.reserved_quantity;
+
+  if (quantity > available) {
+    throw new Error(`Only ${available} available`);
+  }
+
+  // Check existing item
+  const existingItem = await db.cartItems.findFirst({
+    where: { cart_id: cartId, variant_id: variantId },
+  });
+
+  if (existingItem) {
+    return db.cartItems.update({
+      where: { id: existingItem.id },
+      data: { quantity: existingItem.quantity + quantity },
+    });
+  }
+
+  return db.cartItems.create({
+    data: {
+      cart_id: cartId,
+      variant_id: variantId,
+      quantity,
+      price_at_add: variant.price,
+    },
+  });
+};
+
+// Get cart with totals
+const getCart = async (cartId: string) => {
+  const cart = await db.carts.findUnique({
+    where: { id: cartId },
+    include: {
+      items: {
+        include: { variant: { include: { product: true } } },
+      },
+    },
+  });
+
+  const subtotal = cart.items.reduce(
+    (sum, item) => sum + item.price_at_add * item.quantity,
+    0
+  );
+
+  return { ...cart, subtotal };
+};
+```
+
+### Checkout Flow
+
+```typescript
+// Begin checkout - reserve inventory
+const beginCheckout = async (cartId: string) => {
+  const cart = await getCart(cartId);
+
+  // Check all items still available
+  for (const item of cart.items) {
+    const available = await getAvailableQuantity(item.variant_id);
+    if (item.quantity > available) {
+      throw new Error(`${item.variant.name} has only ${available} in stock`);
+    }
+  }
+
+  // Reserve inventory
+  await db.$transaction(async (tx) => {
+    for (const item of cart.items) {
+      await tx.variants.update({
+        where: { id: item.variant_id },
+        data: { reserved_quantity: { increment: item.quantity } },
+      });
+    }
+
+    await tx.carts.update({
+      where: { id: cartId },
+      data: {
+        checkout_started_at: new Date(),
+        checkout_expires_at: addMinutes(new Date(), 15),
+      },
+    });
+  });
+
+  return cart;
+};
+
+// Complete checkout - create order
+const completeCheckout = async (cartId: string, paymentIntentId: string) => {
+  const cart = await getCart(cartId);
+
+  const order = await db.$transaction(async (tx) => {
+    // Create order
+    const order = await tx.orders.create({
+      data: {
+        user_id: cart.user_id,
+        status: 'paid',
+        subtotal: cart.subtotal,
+        total: cart.subtotal + cart.tax + cart.shipping,
+        items: {
+          create: cart.items.map(item => ({
+            variant_id: item.variant_id,
+            quantity: item.quantity,
+            unit_price: item.price_at_add,
+            total_price: item.price_at_add * item.quantity,
+          })),
+        },
+      },
+    });
+
+    // Decrement inventory (move from reserved to sold)
+    for (const item of cart.items) {
+      await tx.variants.update({
+        where: { id: item.variant_id },
+        data: {
+          inventory_quantity: { decrement: item.quantity },
+          reserved_quantity: { decrement: item.quantity },
+        },
+      });
+    }
+
+    // Delete cart
+    await tx.carts.delete({ where: { id: cartId } });
+
+    return order;
+  });
+
+  return order;
+};
+```
+
+### Price Calculation
+
+```typescript
+// Calculate order totals
+const calculateTotals = (items: CartItem[], address: Address) => {
+  const subtotal = items.reduce(
+    (sum, item) => sum + item.price * item.quantity,
+    0
+  );
+
+  const tax = calculateTax(subtotal, address);
+  const shipping = calculateShipping(items, address);
+  const discount = calculateDiscount(items, cart.coupon_code);
+
+  return {
+    subtotal,
+    tax,
+    shipping,
+    discount,
+    total: subtotal + tax + shipping - discount,
+  };
+};
+
+// Tax calculation (simplified)
+const calculateTax = (subtotal: number, address: Address) => {
+  const rate = getTaxRate(address.state, address.country);
+  return Math.round(subtotal * rate);
+};
+```
+
+### Inventory Reservation Release (Cron Job)
+
+```typescript
+// Run every 5 minutes
+const releaseExpiredReservations = async () => {
+  const expiredCarts = await db.carts.findMany({
+    where: {
+      checkout_expires_at: { lt: new Date() },
+      checkout_started_at: { not: null },
+    },
+    include: { items: true },
+  });
+
+  for (const cart of expiredCarts) {
+    await db.$transaction(async (tx) => {
+      for (const item of cart.items) {
+        await tx.variants.update({
+          where: { id: item.variant_id },
+          data: { reserved_quantity: { decrement: item.quantity } },
+        });
+      }
+
+      await tx.carts.update({
+        where: { id: cart.id },
+        data: {
+          checkout_started_at: null,
+          checkout_expires_at: null,
+        },
+      });
+    });
+  }
+};
+```
+
+## For /dev-review
+
+### Cart & Checkout Checklist
+
+```
+[ ] Cart persists across sessions (logged in users)
+[ ] Guest cart merges on login
+[ ] Price changes shown to user
+[ ] Inventory checked before checkout
+[ ] Inventory reserved during checkout
+[ ] Reserved inventory released on timeout
+[ ] Cannot checkout with 0 quantity items
+[ ] Order confirmation email sent
+```
+
+### Inventory Checklist
+
+```
+[ ] Inventory decremented on order, not cart
+[ ] Reserved quantity tracked separately
+[ ] Overselling prevented (race condition safe)
+[ ] Low stock alerts configured
+[ ] Backorder clearly indicated to user
+```
+
+### Payment Checklist
+
+```
+[ ] Payment amount matches order total
+[ ] Payment verified server-side
+[ ] Partial payments handled (if applicable)
+[ ] Refunds update inventory
+[ ] Payment failures don't create orders
+[ ] Webhook signatures validated
+```
+
+### Security Checklist
+
+```
+[ ] Price calculated server-side (never trust client)
+[ ] Coupon codes validated server-side
+[ ] PCI compliance for card data
+[ ] Address validation
+[ ] Fraud detection (velocity checks)
+```
+
+## Common Anti-Patterns
+
+| Anti-Pattern | Problem | Better Approach |
+|--------------|---------|-----------------|
+| Trust client price | Price manipulation | Calculate server-side |
+| Decrement on cart add | Inventory issues | Decrement on order confirm |
+| No reservation timeout | Stock locked forever | 15 min timeout + cron |
+| Single inventory field | Can't track reserved | Separate available/reserved |
+| Validate stock once | Race conditions | Validate in transaction |
+| Hardcoded tax rates | Compliance issues | Tax service API |
+
+## Integration
+
+### With Stripe
+
+```typescript
+// Create payment intent
+const createPaymentIntent = async (cart: Cart) => {
+  const totals = calculateTotals(cart.items, cart.shipping_address);
+
+  return stripe.paymentIntents.create({
+    amount: totals.total, // in cents
+    currency: 'usd',
+    metadata: { cart_id: cart.id },
+  });
+};
+
+// Webhook: payment succeeded
+app.post('/webhooks/stripe', async (req, res) => {
+  const event = stripe.webhooks.constructEvent(...);
+
+  if (event.type === 'payment_intent.succeeded') {
+    const { cart_id } = event.data.object.metadata;
+    await completeCheckout(cart_id, event.data.object.id);
+  }
+});
+```
+
+## Resources
+
+### References in this folder
+- `references/checkout-flows.md` - Detailed checkout state machines
+- `references/shipping.md` - Shipping calculation patterns
+- `assets/order-schema.prisma` - Example Prisma schema