@codihaus/claude-skills 1.0.0 → 1.3.0

package/knowledge/domains/saas/_index.md

@@ -0,0 +1,371 @@
+# SaaS Domain Knowledge
+
+> Software as a Service business patterns and implementation guidance
+
+## Overview
+
+**What it is:**
+- Subscription-based software delivery
+- Multi-tenant architecture
+- Usage-based or tiered pricing
+- Self-service user management
+
+**Key concepts:**
+- **Tenant** = Organization/company using the product
+- **Subscription** = Billing relationship with a tenant
+- **Plan/Tier** = Feature set + pricing level
+- **Seat** = Per-user licensing within a tenant
+- **Trial** = Time-limited free access
+- **Churn** = Customer cancellation
+
+## Terminology
+
+| Term | Definition |
+|------|------------|
+| MRR | Monthly Recurring Revenue |
+| ARR | Annual Recurring Revenue |
+| ARPU | Average Revenue Per User |
+| LTV | Lifetime Value of a customer |
+| CAC | Customer Acquisition Cost |
+| Churn Rate | % of customers who cancel |
+| NRR | Net Revenue Retention |
+
+## Common Entities
+
+### Core Entities
+
+```
+Tenant (Organization)
+├── id, name, slug
+├── plan_id (subscription tier)
+├── trial_ends_at
+├── subscription_status
+└── settings (JSON)
+
+User
+├── id, email, name
+├── tenant_id (belongs to)
+├── role (admin, member, viewer)
+└── last_login_at
+
+Subscription
+├── tenant_id
+├── plan_id
+├── status (trialing, active, past_due, canceled)
+├── current_period_start/end
+├── cancel_at_period_end
+└── payment_method_id
+
+Plan
+├── id, name, slug
+├── price_monthly, price_yearly
+├── features (JSON)
+├── limits (users, storage, etc.)
+└── is_public
+```
+
+### Billing Entities
+
+```
+Invoice
+├── tenant_id
+├── amount, currency
+├── status (draft, open, paid, void)
+├── period_start/end
+└── line_items[]
+
+PaymentMethod
+├── tenant_id
+├── type (card, bank)
+├── last4, brand
+└── is_default
+
+Usage (for usage-based billing)
+├── tenant_id
+├── metric (api_calls, storage_gb)
+├── quantity
+└── period
+```
+
+## Subscription Lifecycle
+
+```
+                    ┌─────────────┐
+                    │   Signup    │
+                    └──────┬──────┘
+                           │
+                    ┌──────▼──────┐
+             ┌──────│   Trial     │──────┐
+             │      └──────┬──────┘      │
+             │             │             │
+      (no convert)   (converts)    (trial ends)
+             │             │             │
+             ▼             ▼             ▼
+        ┌────────┐  ┌──────────┐  ┌──────────┐
+        │Expired │  │  Active  │  │Past Due  │
+        └────────┘  └────┬─────┘  └────┬─────┘
+                         │             │
+                   (cancels)     (pays)│
+                         │             │
+                         ▼             │
+                    ┌────────┐         │
+                    │Canceled│◄────────┘
+                    └────────┘
+```
+
+## For /dev-specs
+
+### Subscription Feature Spec Template
+
+```markdown
+## Feature: Subscription Management
+
+### Entities Affected
+- Tenant: Add subscription_status, trial_ends_at
+- Subscription: New entity
+
+### API Endpoints
+| Method | Path | Purpose |
+|--------|------|---------|
+| POST | /api/subscriptions | Create subscription |
+| GET | /api/subscriptions/current | Get current subscription |
+| PATCH | /api/subscriptions/current | Update subscription |
+| POST | /api/subscriptions/cancel | Cancel at period end |
+| POST | /api/subscriptions/resume | Resume canceled |
+
+### Business Rules
+1. Trial period: 14 days default
+2. Downgrade: Takes effect at period end
+3. Upgrade: Immediate, prorated
+4. Cancel: Access until period end
+5. Past due: 3 retry attempts, then suspend
+
+### Validation Rules
+- Cannot downgrade below current usage
+- Cannot cancel with pending invoices
+- Must have payment method for paid plans
+```
+
+### Multi-Tenancy Spec Template
+
+```markdown
+## Feature: Multi-Tenant Data Isolation
+
+### Approach
+- Database: Single DB, tenant_id column on all tables
+- Auth: JWT includes tenant_id claim
+- API: All queries filtered by tenant_id
+
+### Security Rules
+1. All queries MUST include tenant_id filter
+2. Users can only access their tenant's data
+3. Admin routes require tenant admin role
+4. Super-admin can access any tenant (support)
+
+### Data Model
+- All tenant-scoped tables have tenant_id column
+- Foreign keys reference within same tenant
+- Unique constraints include tenant_id
+```
+
+## For /dev-coding
+
+### Tenant-Scoped Queries
+
+```typescript
+// ALWAYS filter by tenant_id
+const getProjects = async (tenantId: string) => {
+  return db.projects.findMany({
+    where: { tenant_id: tenantId },
+  });
+};
+
+// From auth context
+const getProjects = async (ctx: AuthContext) => {
+  return db.projects.findMany({
+    where: { tenant_id: ctx.tenantId },
+  });
+};
+
+// NEVER do this - data leak
+const getProjects = async (projectId: string) => {
+  return db.projects.findUnique({ where: { id: projectId } }); // Missing tenant check!
+};
+```
+
+### Subscription Status Check
+
+```typescript
+// Check subscription before feature access
+const checkFeatureAccess = (tenant: Tenant, feature: string): boolean => {
+  // Check subscription status
+  if (tenant.subscription_status !== 'active' &&
+      tenant.subscription_status !== 'trialing') {
+    return false;
+  }
+
+  // Check feature in plan
+  const plan = getPlan(tenant.plan_id);
+  return plan.features.includes(feature);
+};
+
+// Middleware
+const requireFeature = (feature: string) => {
+  return async (req, res, next) => {
+    const tenant = await getTenant(req.tenantId);
+    if (!checkFeatureAccess(tenant, feature)) {
+      return res.status(403).json({
+        error: 'Feature not available in your plan',
+        upgrade_url: '/settings/billing'
+      });
+    }
+    next();
+  };
+};
+```
+
+### Usage Tracking
+
+```typescript
+// Track usage for billing
+const trackUsage = async (tenantId: string, metric: string, quantity: number) => {
+  await db.usage.upsert({
+    where: {
+      tenant_id_metric_period: {
+        tenant_id: tenantId,
+        metric,
+        period: getCurrentBillingPeriod(),
+      }
+    },
+    create: { tenant_id: tenantId, metric, quantity, period: getCurrentBillingPeriod() },
+    update: { quantity: { increment: quantity } },
+  });
+};
+
+// Check limit
+const checkUsageLimit = async (tenantId: string, metric: string): Promise<boolean> => {
+  const tenant = await getTenant(tenantId);
+  const plan = getPlan(tenant.plan_id);
+  const usage = await getCurrentUsage(tenantId, metric);
+
+  return usage < plan.limits[metric];
+};
+```
+
+### Trial Handling
+
+```typescript
+// Check trial status
+const isTrialActive = (tenant: Tenant): boolean => {
+  return tenant.subscription_status === 'trialing' &&
+         new Date(tenant.trial_ends_at) > new Date();
+};
+
+// Trial expiration job (run daily)
+const expireTrials = async () => {
+  const expiredTrials = await db.tenants.findMany({
+    where: {
+      subscription_status: 'trialing',
+      trial_ends_at: { lt: new Date() },
+    },
+  });
+
+  for (const tenant of expiredTrials) {
+    await db.tenants.update({
+      where: { id: tenant.id },
+      data: { subscription_status: 'expired' },
+    });
+    await sendEmail(tenant.owner_email, 'trial_expired');
+  }
+};
+```
+
+## For /dev-review
+
+### Multi-Tenancy Checklist
+
+```
+[ ] All queries include tenant_id filter
+[ ] No cross-tenant data access possible
+[ ] Unique constraints include tenant_id
+[ ] API endpoints validate tenant ownership
+[ ] File uploads scoped to tenant
+[ ] Caching keys include tenant_id
+[ ] Logs don't leak tenant data
+```
+
+### Subscription Checklist
+
+```
+[ ] Subscription status checked before paid features
+[ ] Plan limits enforced
+[ ] Upgrade/downgrade handles proration
+[ ] Cancel preserves access until period end
+[ ] Trial expiration handled
+[ ] Payment failures trigger appropriate flow
+[ ] Webhooks from payment provider validated
+```
+
+### Security Checklist
+
+```
+[ ] Tenant isolation at every layer
+[ ] Admin actions audit logged
+[ ] Billing data encrypted
+[ ] PCI compliance if storing cards
+[ ] User can only see their tenant's data
+[ ] Super-admin access logged
+```
+
+## Common Anti-Patterns
+
+| Anti-Pattern | Problem | Better Approach |
+|--------------|---------|-----------------|
+| Query without tenant_id | Data leak between tenants | Always include tenant filter |
+| Checking plan in frontend only | Can be bypassed | Check in backend/middleware |
+| Immediate downgrade | Lose paid features early | Apply at period end |
+| No trial expiration job | Trials never expire | Run daily job |
+| Hardcoded plan features | Hard to update | Store in database |
+| Usage tracked client-side | Can be spoofed | Track server-side |
+
+## Integration
+
+### With Stripe
+
+```typescript
+// Create subscription
+const subscription = await stripe.subscriptions.create({
+  customer: tenant.stripe_customer_id,
+  items: [{ price: plan.stripe_price_id }],
+  trial_period_days: 14,
+  metadata: { tenant_id: tenant.id },
+});
+
+// Webhook handling
+app.post('/webhooks/stripe', async (req, res) => {
+  const event = stripe.webhooks.constructEvent(
+    req.body,
+    req.headers['stripe-signature'],
+    process.env.STRIPE_WEBHOOK_SECRET
+  );
+
+  switch (event.type) {
+    case 'invoice.paid':
+      await activateSubscription(event.data.object);
+      break;
+    case 'invoice.payment_failed':
+      await handlePaymentFailure(event.data.object);
+      break;
+    case 'customer.subscription.deleted':
+      await cancelSubscription(event.data.object);
+      break;
+  }
+});
+```
+
+## Resources
+
+### References in this folder
+- `references/billing-flows.md` - Detailed billing state machines
+- `references/pricing-models.md` - Pricing strategy patterns
+- `assets/subscription-schema.prisma` - Example Prisma schema

package/knowledge/stacks/_index.md

@@ -0,0 +1,101 @@
+# Stack Knowledge
+
+Technical knowledge about platforms and tools. Answers: **"HOW do I build with this?"**
+
+## Purpose
+
+When skills detect a tech stack (via `stack.md`), they load the relevant stack folder for:
+- Best practices and patterns
+- Anti-patterns to avoid
+- Code templates and examples
+- Skill-specific guidance (specs, coding, review)
+
+## Available Stacks
+
+| Stack | Folder | Type | Status |
+|-------|--------|------|--------|
+| Directus | `directus/` | Backend BaaS | Ready |
+| Nuxt.js | `nuxt/` | Vue + SSR Framework | Ready |
+| Next.js | `nextjs/` | React + SSR Framework | Ready |
+| Prisma | `prisma/` | ORM | Planned |
+| Supabase | `supabase/` | Backend BaaS | Planned |
+
+## Folder Structure
+
+Each stack follows this structure:
+
+```
+stacks/{stack-name}/
+├── _index.md           # Main knowledge file
+│   ├── Overview        # What it is, when to use
+│   ├── Best Practices  # Patterns to follow
+│   ├── Anti-Patterns   # What to avoid
+│   ├── For /dev-specs  # Spec writing guidance
+│   ├── For /dev-coding # Implementation patterns
+│   ├── For /dev-review # Review checklists
+│   └── Integration     # How it works with other stacks
+│
+├── references/         # Detailed documentation
+│   ├── api.md          # API reference
+│   ├── patterns.md     # Common patterns
+│   └── performance.md  # Performance optimization
+│
+└── assets/             # Code templates
+    ├── composable.ts   # Example composable
+    ├── component.vue   # Example component
+    └── config.ts       # Example config
+```
+
+## How Skills Use Stack Knowledge
+
+### /dev-scout
+```
+1. Detect stack from package.json, .env, configs
+2. Write to stack.md: "Stack: Directus + Nuxt"
+3. Include: "Load knowledge/stacks/directus/ and knowledge/stacks/nuxt/"
+```
+
+### /dev-specs
+```
+1. Read stack.md → identify stacks
+2. Read stacks/{stack}/_index.md
+3. Use "For /dev-specs" section
+4. Write specs following stack patterns
+```
+
+### /dev-coding
+```
+1. Read specs + stack.md
+2. Read stacks/{stack}/_index.md
+3. Read stacks/{stack}/references/ for deep patterns
+4. Copy from stacks/{stack}/assets/ if needed
+5. Implement following stack patterns
+```
+
+### /dev-review
+```
+1. Identify stack from project
+2. Read stacks/{stack}/_index.md
+3. Use "For /dev-review" section
+4. Check code against stack best practices
+```
+
+## Adding New Stacks
+
+1. Create folder: `stacks/{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** (this folder) | HOW to build | Directus, Nuxt, Next.js | `knowledge/stacks/` |
+| **Domain** | WHAT to build | SaaS, Insurance, E-commerce | `knowledge/domains/` |
+
+Stack knowledge is about the **technology**.
+Domain knowledge is about the **business**.
+
+Both inform better specs, coding, and reviews.