Initial commit: Vibe Stack - Next.js 15 boilerplate with 17 AI architecture rules

Author: vibestackdev

.cursor/mcp.json

@@ -0,0 +1,40 @@
+{
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-github"
+      ],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_GITHUB_PAT>"
+      }
+    },
+    "filesystem": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-filesystem",
+        "./"
+      ]
+    },
+    "supabase": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@supabase/mcp-server-supabase@latest",
+        "--read-only"
+      ],
+      "env": {
+        "SUPABASE_ACCESS_TOKEN": "<YOUR_SUPABASE_PAT>"
+      }
+    },
+    "browser": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@anthropic-ai/mcp-server-puppeteer"
+      ]
+    }
+  }
+}

.cursor/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.

.cursor/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 })
+}
+```

.cursor/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' }
+  }
+}
+```

.cursor/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

.cursor/rules/nextjs15-params.mdc

@@ -0,0 +1,55 @@
+---
+description: Critical Next.js 15 breaking changes regarding async params and searchParams
+globs: ["**/app/**/page.tsx", "**/app/**/layout.tsx", "**/app/**/route.ts"]
+alwaysApply: false
+---
+
+# Next.js 15 Async Params (BREAKING CHANGE)
+
+CRITICAL: In Next.js 15+, `params` and `searchParams` are ASYNC Promises.
+This is a breaking change from Next.js 14. The AI MUST await them.
+
+## Rule: Always Use Promise Types
+
+✅ CORRECT (Next.js 15):
+```tsx
+type PageProps = { 
+  params: Promise<{ slug: string }> 
+  searchParams: Promise<{ [key: string]: string | string[] | undefined }> 
+}
+
+export default async function Page({ params, searchParams }: PageProps) {
+  const { slug } = await params;
+  const search = await searchParams;
+}
+```
+
+❌ WRONG (outdated Next.js 14 pattern — will crash silently):
+```tsx
+// DO NOT GENERATE THIS PATTERN
+export default function Page({ params }: { params: { slug: string } }) {
+  const { slug } = params; // BREAKS: params is a Promise in Next.js 15
+}
+```
+
+## Rule: generateMetadata Also Uses Async Params
+```tsx
+export async function generateMetadata({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  return { title: `Post: ${slug}` }
+}
+```
+
+## Rule: Layout Components MUST Await Params
+```tsx
+export default async function Layout({
+  children,
+  params,
+}: {
+  children: React.ReactNode
+  params: Promise<{ teamId: string }>
+}) {
+  const { teamId } = await params;
+  return <div>{children}</div>
+}
+```

.cursor/rules/performance.mdc

@@ -0,0 +1,68 @@
+---
+description: Next.js performance optimization — caching, bundle size, and Core Web Vitals
+globs: ["**/app/**", "**/components/**", "**/*.tsx"]
+alwaysApply: false
+---
+
+# Performance & Caching
+
+## Data Fetching Rules
+1. Use parallel fetching with `Promise.all()` when data is independent:
+```tsx
+// ✅ CORRECT: Parallel — both requests fire simultaneously
+const [user, posts] = await Promise.all([
+  getUser(userId),
+  getPosts(userId),
+])
+
+// ❌ WRONG: Sequential — second request waits for first to finish
+const user = await getUser(userId)
+const posts = await getPosts(userId)
+```
+
+2. NEVER fetch in loops (N+1 problem):
+```tsx
+// ❌ N+1: Fires 100 queries
+for (const id of userIds) {
+  const user = await supabase.from('profiles').select().eq('id', id).single()
+}
+
+// ✅ Batch: Fires 1 query
+const { data } = await supabase.from('profiles').select().in('id', userIds)
+```
+
+3. Use `unstable_cache()` for expensive server-side computations:
+```tsx
+import { unstable_cache } from 'next/cache'
+
+const getCachedPosts = unstable_cache(
+  async (userId: string) => {
+    return supabase.from('posts').select().eq('user_id', userId)
+  },
+  ['user-posts'],
+  { revalidate: 60, tags: ['posts'] }
+)
+```
+
+## Bundle Size Rules
+- Dynamic import heavy libraries: `const { Chart } = await import('chart.js')`
+- Use `next/dynamic` for client components that don't need SSR:
+```tsx
+import dynamic from 'next/dynamic'
+const RichTextEditor = dynamic(() => import('@/components/editor'), {
+  ssr: false,
+  loading: () => <div className="animate-pulse h-40 bg-muted rounded" />,
+})
+```
+- NEVER import entire icon libraries: `import { Search } from 'lucide-react'` not `import * as icons`
+
+## Image Optimization
+- ALWAYS use `next/image` with explicit `width` and `height`
+- Set `priority={true}` on above-the-fold hero images for LCP
+- Use `placeholder="blur"` with `blurDataURL` for smooth loading
+- Serve modern formats: Next.js automatically converts to WebP/AVIF
+
+## Core Web Vitals Targets
+- LCP (Largest Contentful Paint): < 2.5s
+- FID (First Input Delay): < 100ms
+- CLS (Cumulative Layout Shift): < 0.1

.cursor/rules/project-context.mdc

@@ -0,0 +1,50 @@
+---
+description: Core project context — tech stack, folder structure, and global conventions
+alwaysApply: true
+---
+
+# Vibe Stack — Project Context
+
+## Tech Stack
+- Framework: Next.js 15 (App Router) with React 19
+- Language: TypeScript (strict mode)
+- Styling: Tailwind CSS + shadcn/ui components
+- Database: Supabase (PostgreSQL + RLS)
+- Auth: Supabase SSR (cookie-based, @supabase/ssr)
+- Validation: Zod
+- Payments: Stripe (server-side only)
+- Email: Resend
+- Icons: lucide-react
+
+## Architecture Rules
+1. Default to Server Components. Only add 'use client' when the component needs interactivity.
+2. Push 'use client' to the smallest leaf component possible.
+3. All data fetching happens in Server Components or Server Actions.
+4. All mutations happen via Server Actions, never client-side fetch().
+5. All external input MUST be validated with Zod schemas.
+6. Never use getSession() on the server — always use getUser().
+7. All database tables MUST have Row Level Security (RLS) enabled.
+
+## Folder Structure
+```
+src/
+├── app/              # Next.js App Router pages & layouts
+│   ├── (auth)/       # Auth route group (login, signup)
+│   ├── dashboard/    # Protected pages (behind middleware)
+│   └── api/          # Route handlers (webhooks, public APIs)
+├── components/       # Reusable React components
+│   ├── ui/           # shadcn/ui primitives
+│   └── [feature]/    # Feature-specific components
+├── lib/              # Utilities & third-party configs
+│   ├── supabase/     # Supabase client factories  
+│   ├── stripe/       # Stripe helpers (server-only)
+│   └── utils.ts      # General utilities (cn helper)
+└── types/            # Shared TypeScript types
+```
+
+## Naming Conventions
+- Files: kebab-case (e.g., `user-profile.tsx`)
+- Components: PascalCase (e.g., `UserProfile`)
+- Server Actions: camelCase verbs (e.g., `createTodo`, `updateProfile`)
+- Types/Interfaces: PascalCase with `interface` preferred over `type`
+- Database tables: snake_case (e.g., `user_profiles`)