Add rules/ at root for Open Plugins / cursor.directory compatibility

Author: vibestackdev

rules/ai-collaboration.mdc

@@ -0,0 +1,27 @@
+---
+description: Instructions for AI agent code generation workflow
+globs: ["*"]
+---
+
+# AI Collaboration Guidelines
+
+The 3-stage agentic loop:
+
+1. **PLAN:** 
+"Analyze the current codebase and plan how to implement [feature]. List the files you'll modify and why. Don't write code yet."
+
+2. **IMPLEMENT:** 
+"Implement the plan. Follow all `.cursor/rules/` guidelines. If you're unsure about auth or RLS, check `supabase-auth-security.mdc`."
+
+3. **REVIEW:** 
+"Review what you just generated. Check for:
+- `getSession()` usage (MUST be `getUser()`)
+- Missing error boundaries or `loading.tsx`
+- Next.js 15 async layout/page params
+- TypeScript `any` types (use `unknown` or define interface)
+Report any issues before I run it."
+
+Constraints:
+- NEVER give the AI a task longer than 200 words.
+- NEVER let the AI implement more than 3-4 files in one turn.
+- ALWAYS review the Git diff before committing.

rules/api-design.mdc

@@ -0,0 +1,42 @@
+---
+description: API route handler design patterns
+globs: ["**/app/api/**", "**/route.ts"]
+---
+
+# API Design Patterns
+
+Standard response format for Route Handlers:
+Success: `{ data: T, error: null }`
+Error:   `{ data: null, error: { code: string, message: string } }`
+
+HTTP status codes:
+- 200: Success (GET, PATCH)
+- 201: Created (POST)
+- 204: No content (DELETE)
+- 400: Validation error
+- 401: Unauthenticated
+- 403: Unauthorized  
+- 404: Not found
+- 500: Server error
+
+Route handler template:
+```typescript
+import { NextResponse } from 'next/server'
+import { createServerClient } from '@supabase/ssr'
+
+export async function GET(request: Request, { params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params
+  const supabase = createServerClient(...)
+  
+  const { data: { user } } = await supabase.auth.getUser()
+  if (!user) {
+    return NextResponse.json(
+      { data: null, error: { code: 'UNAUTHORIZED', message: 'Login required' } }, 
+      { status: 401 }
+    )
+  }
+  
+  // ... fetch data
+  return NextResponse.json({ data: { id, status: 'ok' }, error: null })
+}
+```

rules/caching-revalidation.mdc

@@ -0,0 +1,55 @@
+---
+description: Next.js caching and revalidation best practices
+globs: ["**/app/**", "**/lib/**"]
+alwaysApply: false
+---
+
+# Caching & Revalidation
+
+## Default Behavior
+Next.js 15 has specific caching defaults. AI models often get these wrong.
+
+## Rules
+
+### Server Components - Data Fetching
+For dynamic data that changes frequently:
+```typescript
+// Force fresh data on every request
+const data = await fetch(url, { cache: 'no-store' })
+
+// Or revalidate every 60 seconds:
+const data = await fetch(url, { next: { revalidate: 60 } })
+```
+
+### Route Segment Config
+For pages that must always show fresh data:
+```typescript
+// At the top of page.tsx or layout.tsx:
+export const dynamic = 'force-dynamic'  // Never cache this page
+export const revalidate = 0             // Same as above
+```
+
+For static pages that rarely change:
+```typescript
+export const revalidate = 3600  // Revalidate every hour
+```
+
+### Server Actions — Always Revalidate
+After mutations, ALWAYS revalidate affected paths:
+```typescript
+'use server'
+import { revalidatePath } from 'next/cache'
+
+export async function createPost(formData: FormData) {
+  // ... create post in database
+  revalidatePath('/posts')  // ← NEVER forget this
+  revalidatePath('/dashboard')  // ← Revalidate all affected pages
+}
+```
+
+### Anti-Patterns
+- NEVER assume `fetch()` will always return fresh data — check your cache settings
+- NEVER forget `revalidatePath()` after a mutation in a Server Action
+- NEVER use `cache: 'force-cache'` for user-specific data
+- NEVER rely on client-side state to show "updated" data after a mutation — revalidate the server cache
+- ALWAYS use `revalidateTag()` for fine-grained cache invalidation when possible

rules/database-design.mdc

@@ -0,0 +1,65 @@
+---
+description: Database schema design patterns for Supabase with proper types and relationships
+globs: ["**/*.sql", "**/supabase/**", "**/types/**"]
+alwaysApply: false
+---
+
+# Database Design Patterns
+
+## Table Naming
+- Use `snake_case` for tables and columns: `user_profiles`, `created_at`
+- NEVER use camelCase in SQL: `userId` → WRONG, `user_id` → CORRECT
+- Use plural table names: `profiles`, `posts`, `comments`
+
+## Required Columns (Every Table)
+```sql
+CREATE TABLE public.example (
+  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
+  -- your columns here
+  created_at TIMESTAMPTZ DEFAULT NOW() NOT NULL,
+  updated_at TIMESTAMPTZ DEFAULT NOW() NOT NULL
+);
+```
+ALWAYS include `id`, `created_at`, and `updated_at`.
+ALWAYS use UUID for primary keys (not serial/integer).
+ALWAYS use TIMESTAMPTZ (not TIMESTAMP) for timezone safety.
+
+## Foreign Key Pattern
+```sql
+-- Always reference auth.users for user ownership
+user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE NOT NULL
+```
+Use `ON DELETE CASCADE` for user-owned data.
+Use `ON DELETE SET NULL` for optional relationships.
+
+## RLS Template (Copy This Every Time)
+```sql
+ALTER TABLE public.example ENABLE ROW LEVEL SECURITY;
+
+-- Users can only see their own data
+CREATE POLICY "Users own data" ON public.example
+  FOR ALL USING (auth.uid() = user_id);
+
+-- Or for public read + owner write:
+CREATE POLICY "Public read" ON public.example
+  FOR SELECT USING (true);
+CREATE POLICY "Owner write" ON public.example
+  FOR INSERT WITH CHECK (auth.uid() = user_id);
+CREATE POLICY "Owner update" ON public.example
+  FOR UPDATE USING (auth.uid() = user_id);
+CREATE POLICY "Owner delete" ON public.example
+  FOR DELETE USING (auth.uid() = user_id);
+```
+
+## Type Generation
+After schema changes, regenerate types:
+```bash
+npx supabase gen types typescript --project-id YOUR_PROJECT_REF > src/types/database.ts
+```
+ALWAYS use generated types — NEVER manually type database schemas.
+
+## Anti-Patterns
+- NEVER use `TEXT` for fields that should be enums — use PostgreSQL enums or CHECK constraints
+- NEVER store JSON blobs when structured columns work — use `JSONB` only for truly dynamic data
+- NEVER create tables without RLS — see `supabase-rls.mdc`
+- NEVER use `SERIAL` for IDs — use `UUID` for security (prevents enumeration attacks)

rules/env-management.mdc

@@ -0,0 +1,66 @@
+---
+description: Environment variable management and secrets handling
+globs: ["**/*.ts", "**/*.tsx", "**/.env*"]
+alwaysApply: false
+---
+
+# Environment Variable Management
+
+## Classification Rules
+| Prefix | Visibility | Use For |
+|--------|-----------|---------|
+| `NEXT_PUBLIC_` | Client + Server | Non-sensitive public values (Supabase URL, Stripe publishable key) |
+| No prefix | Server Only | ALL secrets (API keys, webhook secrets, database URLs) |
+
+## NEVER Expose These to the Client
+```
+STRIPE_SECRET_KEY         → Server only (NEVER NEXT_PUBLIC_)
+STRIPE_WEBHOOK_SECRET     → Server only
+SUPABASE_SERVICE_ROLE_KEY → Server only (admin bypass key)
+RESEND_API_KEY            → Server only
+DATABASE_URL              → Server only
+```
+
+## Safe for Client
+```
+NEXT_PUBLIC_SUPABASE_URL           → Public Supabase endpoint
+NEXT_PUBLIC_SUPABASE_ANON_KEY      → Rate-limited client key (RLS protects data)
+NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY → Stripe public key (payment form only)
+NEXT_PUBLIC_APP_URL                → Your app's URL
+```
+
+## Validation Pattern
+Use `src/lib/env.ts` to validate at startup:
+```typescript
+function getEnvVar(key: string, required = true): string {
+  const value = process.env[key]
+  if (!value && required) {
+    throw new Error(`❌ Missing required env var: ${key}`)
+  }
+  return value ?? ''
+}
+```
+
+## .env.local Structure
+```bash
+# Supabase (required)
+NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
+NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
+
+# Stripe (optional in dev)
+STRIPE_SECRET_KEY=sk_test_...
+STRIPE_WEBHOOK_SECRET=whsec_...
+NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
+
+# Email (optional in dev)
+RESEND_API_KEY=re_...
+
+# App
+NEXT_PUBLIC_APP_URL=http://localhost:3000
+```
+
+## Anti-Patterns
+- NEVER commit `.env.local` — it's in `.gitignore`
+- NEVER use `process.env.X` directly in components — use the centralized `env` config
+- NEVER hardcode API keys or secrets in source code
+- NEVER use `NEXT_PUBLIC_` for write-access API keys

rules/error-handling.mdc

@@ -0,0 +1,42 @@
+---
+description: Error boundaries and loading states guidelines
+globs: ["**/app/**"]
+---
+
+# Error Handling and Loading States
+
+EVERY page in `app/` router MUST have sibling files if it does data fetching:
+- `loading.tsx` (Suspense boundary)
+- `error.tsx` (Error boundary — must be `'use client'`)
+
+`loading.tsx` template:
+```tsx
+export default function Loading() {
+  return <div className="animate-pulse">Loading...</div>
+}
+```
+
+`error.tsx` template:
+```tsx
+'use client'
+export default function Error({ error, reset }: { error: Error; reset: () => void }) {
+  return (
+    <div>
+      <h2>Something went wrong</h2>
+      <button onClick={reset}>Try again</button>
+    </div>
+  )
+}
+```
+
+Server Action error pattern:
+```typescript
+export async function createItem(formData: FormData) {
+  try {
+    // ... operation
+    return { success: true }
+  } catch (error) {
+    return { error: 'Failed to create item' }
+  }
+}
+```

rules/file-naming.mdc

@@ -0,0 +1,46 @@
+---
+description: File naming conventions and project organization rules
+globs: ["**/*.ts", "**/*.tsx"]
+alwaysApply: false
+---
+
+# File Naming & Organization
+
+## Naming Conventions
+- **Components:** PascalCase → `UserProfile.tsx`, `DashboardLayout.tsx`
+- **Utilities/Libs:** camelCase → `formatDate.ts`, `createClient.ts`
+- **Constants:** SCREAMING_SNAKE → `export const MAX_RETRIES = 3`
+- **Types files:** camelCase → `types/index.ts`, `types/database.ts`
+- **Server Actions:** camelCase in grouped files → `actions.ts` (not one file per action)
+- **Route Handlers:** always `route.ts` (Next.js convention)
+
+## Directory Rules
+- Components in `src/components/` — NEVER in `src/app/`
+- Page-specific components in `src/app/[route]/_components/` (underscore prefix = private)
+- Shared types in `src/types/` — NEVER define types inline in components
+- Business logic in `src/lib/` — NEVER put business logic in components
+- Server actions in the nearest `actions.ts` to where they're used
+
+## Import Order (enforce in every file)
+```typescript
+// 1. React/Next.js imports
+import { Suspense } from 'react'
+import Link from 'next/link'
+
+// 2. Third-party libraries
+import { z } from 'zod'
+
+// 3. Internal aliases (@/)
+import { Button } from '@/components/ui/button'
+import { createClient } from '@/lib/supabase/server'
+import type { UserProfile } from '@/types'
+
+// 4. Relative imports (only for co-located files)
+import { columns } from './columns'
+```
+
+## Anti-Patterns
+- NEVER create `utils/helpers.ts` catch-all files — name files by what they do
+- NEVER put more than 1 exported component per file
+- NEVER use default exports for utilities — use named exports
+- NEVER create `index.ts` barrel files that re-export everything (breaks tree-shaking)

rules/git-conventions.mdc

@@ -0,0 +1,28 @@
+---
+description: Git workflow and commit conventions for AI-assisted development
+globs: ["*"]
+---
+
+# Git Conventions for Vibe Coders
+
+Commit convention (Conventional Commits):
+- `feat:` add user authentication
+- `fix:` resolve RLS policy for shared projects  
+- `chore:` update dependencies
+- `docs:` add API documentation
+- `refactor:` extract auth helper to separate module
+
+Branch naming:
+- `feature/auth-flow`
+- `fix/rls-policy-bug`
+- `chore/update-dependencies`
+
+ALWAYS run before commit (if available):
+1. `npm run lint`
+2. `npm run type-check`
+3. `npm test`
+
+AI session workflow:
+- Create a new branch before starting any AI session
+- Review ALL AI-generated code before committing
+- Break large AI generations into multiple focused commits