create-baton 1.0.0 → 1.1.0

package/templates/skills/domains/saas/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: saas
+description: >-
+  SaaS product patterns — multi-tenancy, workspaces, billing, onboarding,
+  feature gating, and usage tracking. Load at Session 0 when building a
+  SaaS product. Stays loaded for the entire project lifecycle.
+---
+
+# SaaS Domain Skill
+
+> SaaS is not just an app with login. It's an app with organizations, billing, and self-service.
+
+---
+
+## Load This Skill When
+
+- User says they're building a SaaS, platform, or subscription product
+- Project has multiple users, teams, or organizations
+- Revenue model is recurring (monthly/annual subscriptions)
+
+---
+
+## Architecture Decisions (Session 0-1)
+
+### Multi-Tenancy Model
+
+Choose ONE. Don't change mid-project.
+
+| Model | How It Works | Best For |
+|-------|-------------|----------|
+| **Shared database, tenant column** | All tenants in same tables, filtered by `org_id` | Most SaaS (start here) |
+| **Schema per tenant** | Separate database schema per tenant | Regulated industries |
+| **Database per tenant** | Completely isolated databases | Enterprise, compliance-heavy |
+
+**Default:** Shared database with tenant column. It's simplest and scales to 10,000+ tenants.
+
+```sql
+-- Every table gets an org_id
+CREATE TABLE projects (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  org_id UUID NOT NULL REFERENCES organizations(id),
+  name TEXT NOT NULL,
+  created_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+-- RLS enforces tenant isolation
+CREATE POLICY "Tenant isolation"
+ON projects FOR ALL
+USING (org_id = (SELECT current_org_id()));
+```
+
+### Core Data Model
+
+Every SaaS needs these tables minimum:
+
+```
+users              — Individual people
+organizations      — Workspaces/teams (the billing entity)
+memberships        — users ↔ organizations (with role)
+subscriptions      — org ↔ plan (billing state)
+```
+
+Don't build more until you need it.
+
+---
+
+## Onboarding Flow (Session 2-3)
+
+### First-Time User Experience
+
+The first 60 seconds determine if a user stays. Design for this:
+
+```
+1. Sign up (email + password, or OAuth)
+2. Create or join organization
+3. ONE guided action (create first [thing])
+4. Success state — "You're set up!"
+```
+
+**Rules:**
+- Maximum 3 steps before user sees value
+- Pre-fill defaults where possible
+- Skip optional steps — let users configure later
+- Show progress indicator if more than 2 steps
+
+### Empty States
+
+Every list/dashboard screen needs an empty state with:
+- What this screen is for (one sentence)
+- A call to action (button to create first item)
+- Optional: example data or template
+
+Never show an empty table with column headers and no rows.
+
+---
+
+## Billing Integration (Session 3-5)
+
+### Stripe (Default Choice)
+
+Unless user specifies otherwise, use Stripe. It handles 90% of SaaS billing needs.
+
+**Core flow:**
+```
+User clicks "Upgrade" →
+  Redirect to Stripe Checkout →
+    Stripe handles payment →
+      Webhook confirms payment →
+        App updates subscription status
+```
+
+### What to Build
+
+| Component | When | Priority |
+|-----------|------|----------|
+| Pricing page | Session 3-4 | Must have |
+| Stripe Checkout redirect | Session 3-4 | Must have |
+| Webhook handler | Session 3-4 | Must have |
+| Customer portal link | Session 4-5 | Should have |
+| Usage tracking | Session 5+ | Nice to have |
+
+### What NOT to Build
+
+- Custom payment forms (use Stripe Checkout)
+- Invoice generation (Stripe does this)
+- Tax calculation (Stripe Tax or let Stripe handle it)
+- Subscription management UI (link to Stripe Customer Portal)
+
+### Webhook Security
+
+```typescript
+// ALWAYS verify webhook signatures
+const event = stripe.webhooks.constructEvent(
+  body,
+  signature,
+  process.env.STRIPE_WEBHOOK_SECRET
+);
+
+// Handle these events minimum:
+// checkout.session.completed — new subscription
+// customer.subscription.updated — plan change
+// customer.subscription.deleted — cancellation
+// invoice.payment_failed — payment issue
+```
+
+---
+
+## Feature Gating (Session 4-5)
+
+### Simple Tier Check
+
+```typescript
+// lib/billing.ts
+export function canAccess(org: Organization, feature: string): boolean {
+  const featureMap: Record<string, string[]> = {
+    free: ['basic_feature'],
+    pro: ['basic_feature', 'advanced_feature', 'api_access'],
+    enterprise: ['basic_feature', 'advanced_feature', 'api_access', 'sso', 'audit_log'],
+  };
+
+  return featureMap[org.plan]?.includes(feature) ?? false;
+}
+```
+
+**Rules:**
+- Check features, not plan names (plans change, features don't)
+- Gate at the server, not the client (client gates are cosmetic, not security)
+- Show locked features with upgrade prompt, don't hide them
+
+---
+
+## Usage Tracking (Session 5+)
+
+If billing is usage-based or has limits:
+
+```typescript
+// Track usage per org per period
+interface UsageRecord {
+  org_id: string;
+  metric: string;      // 'api_calls' | 'storage_mb' | 'team_members'
+  value: number;
+  period: string;      // '2026-02' (monthly)
+}
+```
+
+Show usage in dashboard:
+- Current usage vs limit
+- Percentage bar
+- Warning at 80%, block at 100%
+
+---
+
+## Common SaaS Patterns
+
+### Invitation System
+
+```
+Owner invites by email →
+  Email sent with invite link →
+    Invitee signs up or logs in →
+      Auto-joined to organization
+```
+
+Store pending invites. Don't require account creation before accepting.
+
+### Role-Based Access
+
+Keep it simple. Three roles cover 95% of SaaS:
+
+| Role | Can Do |
+|------|--------|
+| **Owner** | Everything + billing + delete org |
+| **Admin** | Everything except billing and delete |
+| **Member** | CRUD own resources, view shared resources |
+
+Don't add roles until users ask for them.
+
+### Settings Structure
+
+```
+Settings/
+├── Profile (user-level)
+├── Organization (org-level)
+├── Billing (owner-only)
+├── Team Members (admin+)
+└── Integrations (admin+)
+```
+
+---
+
+## Session Checkpoints
+
+### Session 3: Foundation Check
+- [ ] Users can sign up and create organization
+- [ ] Basic CRUD works with tenant isolation
+- [ ] Empty states on all screens
+
+### Session 5: Billing Check
+- [ ] Pricing page exists
+- [ ] Stripe integration works (test mode)
+- [ ] Webhook handles subscription events
+- [ ] Feature gating works for at least 2 tiers
+
+### Session 8: Pre-Launch Check
+- [ ] Onboarding flow is smooth (test with fresh account)
+- [ ] Billing works in live mode
+- [ ] Invitation system works
+- [ ] Settings pages exist
+
+---
+
+*Last updated: Baton Protocol v3.1*

package/templates/skills/patterns/authentication/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: authentication
+description: >-
+  Authentication patterns — login, signup, OAuth, protected routes, middleware,
+  password reset, and session management. Load at Session 1-3 when the project
+  needs user accounts. Use when discussing auth strategy or implementing login.
+---
+
+# Authentication Skill
+
+> Auth is the one thing you can't get wrong. A security hole here exposes everything.
+
+---
+
+## Choose Your Auth Strategy (Session 1)
+
+### Decision Tree
+
+```
+Using Supabase? → Use Supabase Auth (built-in, free)
+Using another database? → Use Better Auth or NextAuth
+Building an API? → Use API keys (see api domain skill)
+Just need social login? → Use OAuth provider directly
+```
+
+Don't mix strategies. Pick one and commit.
+
+### Strategy Comparison
+
+| Strategy | Best For | Complexity |
+|----------|----------|-----------|
+| **Supabase Auth** | Next.js + Supabase stack | Low |
+| **Better Auth** | Any stack, full control | Medium |
+| **NextAuth/Auth.js** | Next.js, many providers | Medium |
+| **Custom JWT** | APIs, microservices | High (avoid unless needed) |
+
+---
+
+## Core Auth Flows
+
+### Sign Up
+
+```
+Email + Password → Validate → Create account → Send verification email → Redirect to app
+```
+
+**Rules:**
+- Minimum password length: 8 characters
+- Don't enforce special characters (users hate it, doesn't help security)
+- Email verification is optional for MVP, required for production
+- After signup: redirect to app, not login page
+
+### Log In
+
+```
+Email + Password → Validate → Create session → Redirect to app
+```
+
+**Rules:**
+- Generic error messages: "Invalid email or password" (never reveal which is wrong)
+- Rate limit login attempts (5 per minute per IP)
+- Redirect to intended page after login, not always homepage
+
+### Log Out
+
+```
+Click logout → Destroy session → Redirect to landing page
+```
+
+**Rules:**
+- Clear all session data (cookies, localStorage)
+- Invalidate server-side session
+- Don't ask "are you sure?" — just log out
+
+### Password Reset
+
+```
+Enter email → Send reset link → Click link → Set new password → Auto log in
+```
+
+**Rules:**
+- Reset tokens expire in 1 hour
+- One-time use (invalidate after use)
+- Don't confirm if email exists ("If an account exists, we sent a reset link")
+- After reset: log user in automatically
+
+---
+
+## Protected Routes
+
+### Server-Side (Recommended)
+
+```typescript
+// middleware.ts (Next.js)
+export function middleware(request: NextRequest) {
+  const session = request.cookies.get('session');
+
+  if (!session && request.nextUrl.pathname.startsWith('/dashboard')) {
+    return NextResponse.redirect(new URL('/login', request.url));
+  }
+}
+
+export const config = {
+  matcher: ['/dashboard/:path*', '/settings/:path*'],
+};
+```
+
+### In Server Components
+
+```typescript
+// app/dashboard/page.tsx
+export default async function Dashboard() {
+  const user = await getAuthenticatedUser();
+  if (!user) redirect('/login');
+
+  return <DashboardContent user={user} />;
+}
+```
+
+### In Server Actions
+
+```typescript
+'use server'
+export async function updateProfile(formData: FormData) {
+  const user = await getAuthenticatedUser();
+  if (!user) throw new Error('Not authenticated');
+
+  // ... update logic
+}
+```
+
+**Rule:** Check auth in EVERY server action and API route. Never trust the client.
+
+---
+
+## Session Management
+
+### Cookie-Based Sessions (Default)
+
+```typescript
+// Set session cookie
+cookies().set('session', token, {
+  httpOnly: true,      // JavaScript can't read it
+  secure: true,        // HTTPS only
+  sameSite: 'lax',     // CSRF protection
+  maxAge: 60 * 60 * 24 * 7,  // 7 days
+  path: '/',
+});
+```
+
+**Rules:**
+- Always `httpOnly` — prevents XSS from stealing sessions
+- Always `secure` in production
+- Session expiry: 7 days for "remember me", 24 hours otherwise
+- Rotate session token on privilege changes (login, password change)
+
+### Never Use localStorage for Auth Tokens
+
+```
+BAD:  localStorage.setItem('token', jwt)    // XSS can steal it
+GOOD: httpOnly cookie set by server         // JavaScript can't access it
+```
+
+---
+
+## OAuth (Social Login)
+
+### When to Add
+
+- When users expect it (consumer apps)
+- When you want to reduce signup friction
+- NOT for B2B SaaS (email + password is fine)
+
+### Common Providers
+
+| Provider | Use When |
+|----------|----------|
+| Google | Default choice, everyone has an account |
+| GitHub | Developer-facing products |
+| Apple | iOS apps (required by App Store if you have social login) |
+
+### Implementation Pattern
+
+```
+Click "Login with Google" →
+  Redirect to Google OAuth →
+    Google redirects back with code →
+      Exchange code for tokens (server-side) →
+        Create or find user →
+          Create session →
+            Redirect to app
+```
+
+**Rules:**
+- Always offer email + password alongside OAuth
+- Handle "same email, different provider" gracefully
+- Store provider info but don't depend on it
+
+---
+
+## Auth UI Patterns
+
+### Login Page
+
+- Email field (autofocus)
+- Password field (with show/hide toggle)
+- "Log in" button (primary)
+- "Forgot password?" link
+- "Don't have an account? Sign up" link
+- OAuth buttons below (if applicable)
+
+### Signup Page
+
+- Email field
+- Password field
+- "Create account" button
+- "Already have an account? Log in" link
+- Terms of service checkbox (if legally required)
+
+### Common Mistakes
+
+- Don't put login and signup on the same page with tabs
+- Don't require username during signup (let them set it later)
+- Don't ask for unnecessary info at signup (name, phone, company)
+- Don't disable the submit button without explaining why
+
+---
+
+## Session Checkpoints
+
+### Session 2: Auth Foundation
+- [ ] Signup creates account
+- [ ] Login creates session
+- [ ] Logout destroys session
+- [ ] Protected routes redirect to login
+
+### Session 4: Auth Complete
+- [ ] Password reset works
+- [ ] Session cookies are httpOnly and secure
+- [ ] Auth checked in all server actions
+- [ ] Rate limiting on login endpoint
+
+---
+
+*Last updated: Baton Protocol v3.1*

package/templates/skills/patterns/database-design/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: database-design
+description: >-
+  Database design patterns — schema design, normalization, indexes, migrations,
+  and query optimization. Load at Session 1-2 when setting up the database.
+  Use when designing tables, writing migrations, or optimizing slow queries.
+---
+
+# Database Design Skill
+
+> Get the schema right early. Fixing it later means migrating live data.
+
+---
+
+## Schema Design (Session 1)
+
+### Every Table Needs
+
+```sql
+CREATE TABLE items (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  -- your columns here
+  created_at TIMESTAMPTZ DEFAULT NOW(),
+  updated_at TIMESTAMPTZ DEFAULT NOW()
+);
+```
+
+- UUID primary keys (not auto-increment — safer for distributed systems)
+- `created_at` and `updated_at` on every table
+- Auto-update `updated_at` with a trigger
+
+### Naming Conventions
+
+| Thing | Convention | Example |
+|-------|-----------|---------|
+| Tables | Plural, snake_case | `order_items` |
+| Columns | Singular, snake_case | `first_name` |
+| Foreign keys | `{table_singular}_id` | `user_id` |
+| Booleans | `is_` or `has_` prefix | `is_active` |
+| Timestamps | `_at` suffix | `deleted_at` |
+| Money | `_cents` or `_fils` suffix | `price_cents` |
+
+### Data Types
+
+| Use | Type | Why |
+|-----|------|-----|
+| IDs | UUID | No guessing, safe to expose |
+| Short text | TEXT | PostgreSQL treats VARCHAR and TEXT the same |
+| Long text | TEXT | Same as above |
+| Money | INTEGER (cents) | No floating point errors |
+| Booleans | BOOLEAN | Not integers |
+| Timestamps | TIMESTAMPTZ | Always with timezone |
+| JSON data | JSONB | Queryable, indexed |
+| Enums | TEXT with check | More flexible than PostgreSQL ENUM |
+
+```sql
+-- Use TEXT with check instead of ENUM
+status TEXT NOT NULL DEFAULT 'draft'
+  CHECK (status IN ('draft', 'active', 'archived'))
+```
+
+---
+
+## Relationships
+
+### One-to-Many (Most Common)
+
+```sql
+-- A user has many posts
+CREATE TABLE posts (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id UUID NOT NULL REFERENCES users(id),
+  title TEXT NOT NULL
+);
+```
+
+### Many-to-Many
+
+```sql
+-- Users belong to many organizations
+CREATE TABLE memberships (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id UUID NOT NULL REFERENCES users(id),
+  org_id UUID NOT NULL REFERENCES organizations(id),
+  role TEXT DEFAULT 'member',
+  UNIQUE(user_id, org_id)
+);
+```
+
+### When to Use JSONB Instead
+
+Use JSONB for:
+- Metadata that varies per record
+- Settings/preferences
+- Data you query rarely
+
+Don't use JSONB for:
+- Relationships (use foreign keys)
+- Data you filter/sort by frequently
+- Core business data
+
+---
+
+## Indexes (Session 2-3)
+
+### Rules
+
+1. **Foreign keys always get an index** — PostgreSQL doesn't auto-index them
+2. **Columns you filter by get an index** — WHERE clauses need them
+3. **Columns you sort by get an index** — ORDER BY is slow without them
+4. **Don't index everything** — each index slows writes
+
+```sql
+-- Index foreign keys
+CREATE INDEX idx_posts_user_id ON posts(user_id);
+
+-- Index commonly filtered columns
+CREATE INDEX idx_posts_status ON posts(status);
+
+-- Composite index for common query patterns
+CREATE INDEX idx_posts_user_status ON posts(user_id, status);
+```
+
+### When to Add
+
+- Session 1-2: Index foreign keys
+- Session 5+: Add indexes for slow queries (measure first)
+- Don't add indexes "just in case"
+
+---
+
+## Migrations (Session 1+)
+
+### Migration File Naming
+
+```
+20260214_001_create_users.sql
+20260214_002_create_organizations.sql
+20260215_001_add_status_to_users.sql
+```
+
+### Safe Migration Rules
+
+**Safe (can run on live database):**
+- Adding a table
+- Adding a nullable column
+- Adding an index (use CONCURRENTLY)
+- Adding a column with a default
+
+**Dangerous (plan carefully):**
+- Renaming a column (breaks existing queries)
+- Changing a column type
+- Dropping a column (might break code)
+- Dropping a table
+
+**Never in production:**
+- `DROP TABLE` without backup
+- Changing column type with data in it
+- Removing NOT NULL without checking data
+
+### Migration Workflow
+
+```
+1. Write migration SQL
+2. Test locally (reset database)
+3. Ask user to run in production
+4. Wait for confirmation
+5. Regenerate types (if using TypeScript)
+6. THEN build features for new tables
+```
+
+**Never build UI for tables that don't exist yet.**
+
+---
+
+## Query Patterns
+
+### Fetching Lists
+
+```sql
+-- Always paginate, never SELECT * without LIMIT
+SELECT id, name, status, created_at
+FROM items
+WHERE org_id = $1
+ORDER BY created_at DESC
+LIMIT 20 OFFSET 0;
+```
+
+### Counting
+
+```sql
+-- For display ("42 items"), use count
+SELECT COUNT(*) FROM items WHERE org_id = $1;
+
+-- For "has any?", use EXISTS (faster)
+SELECT EXISTS(SELECT 1 FROM items WHERE org_id = $1);
+```
+
+### Soft Deletes
+
+For important data (orders, financial records):
+
+```sql
+ALTER TABLE orders ADD COLUMN deleted_at TIMESTAMPTZ;
+
+-- "Delete" = set timestamp
+UPDATE orders SET deleted_at = NOW() WHERE id = $1;
+
+-- All queries exclude deleted
+SELECT * FROM orders WHERE deleted_at IS NULL;
+```
+
+For unimportant data: just delete it.
+
+---
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Using FLOAT for money | Use INTEGER (cents) |
+| No indexes on foreign keys | Add after creating table |
+| Building UI before migration runs | Wait for confirmation |
+| Storing arrays as comma-separated strings | Use JSONB or junction table |
+| Not testing migration rollback | Always have a rollback plan |
+| Huge tables without pagination | Always LIMIT queries |
+
+---
+
+*Last updated: Baton Protocol v3.1*