New Project

---
name: new-project
disable-model-invocation: true
description: >
  Interactive project scaffolding wizard with stack selection, theme, tokens, and ecosystem
  integration. Use when user says "/new-project", "scaffold project", "setup new repo",
  "create project structure", "bootstrap a project", "scaffolde un projet", "nouveau projet",
  "initialise un repo", or "crée la structure d'un projet". For scaffolding + full product
  pipeline (vision, PRD, brand, UX, build), see /new. For pipeline on existing projects, see
  /build. For rapid idea-to-MVP, see /team.
allowed-tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep", "AskUserQuestion", "Task", "ToolSearch"]
---

# /new-project v2.1 - Complete Project Scaffolding Wizard

Create production-ready projects with beautiful UI, proper architecture, and full ecosystem integration.

**Key Features:**
- 🔄 **Latest versions** via Context7 (Next.js, Convex, Clerk, etc.)
- 🧠 **Smart defaults** based on project type
- 🎨 **oklch themes** with shadcn/ui
- 🚀 **Production-ready** CI/CD, testing, monitoring

---

## Single-voice craft (do NOT parallelize)

This wizard is a **single coherent build**, not a multi-angle analysis. The 16-step EXECUTION
sequence is **order-dependent and stateful** — do NOT fan it out to parallel agents:
- `mkdir`/`cd` must precede file writes; `git init` must precede `.gitignore`; theme must land
  before pages reference its tokens; Convex init produces env values later steps consume.
- Two agents writing the same project tree = corruption + merge conflicts (R-SCOPE: one writer
  per file). Run the whole pipeline as ONE driver, sequentially, in the project's directory.
- The single "voice" here is **consistency**: one stack decision, one theme, one naming
  convention threaded through every file. Splitting it fragments that consistency.
- The ONLY safe parallelism is *independent* read-only Context7 doc fetches in Step 0 (batch
  the `resolve-library-id` / `query-docs` calls together). Everything that *writes* stays serial.

### Portability note (VPS-specific bits — keep the logic, swap the coordinates)
This skill was authored for the OmegaOS VPS. The logic is portable; only these constants are
host-specific — substitute them for your environment before running on another machine:
`/home/hacker/...` paths, the `72.61.197.216` dev IP, per-category port rules, the git
identities, and the `SUPERMEMORY_CC_API_KEY` in Step 13. **The hardcoded Supermemory key in
Step 13 is a live secret — rotate it and read it from `~/.omega` / an env var instead of
inlining it (R-ENV: secrets live outside the repo).** On a non-VPS host, skip Steps 11–13
and 15 (tmux alias, port allocation, Supermemory index, rules docs) — they are ecosystem
bookkeeping, not part of the buildable project.

## OUTPUT contract

A successful run produces, on disk and verifiable:
1. A project directory at the resolved category path containing a **building** Next.js (or
   chosen-stack) app — installed deps, applied oklch theme (`:root` + `.dark`), the selected
   pages/screens, env files (`.env.local` + `.env.example`), `CLAUDE.md`, `@fix_plan.md`,
   `@AGENT.md`, `.gitignore`, and any selected extras (CI/CD, testing, Husky, Sentry, SEO,
   rate-limit, i18n) actually wired — not just mentioned.
2. An initialized git repo (and, if chosen, a pushed GitHub remote).
3. The Phase 8 summary reporting **real** values (actual installed versions, real path, real
   port), never placeholders.

## VERIFY (run before claiming done — L4 / R-PROD)

Do NOT report success until these pass; cite the actual output of each:
```bash
cd "$PROJECT_PATH"
bun install            # deps resolve clean
bun run type-check     # no TS errors  (tsc --noEmit)
bun run lint           # lint clean
bun run build          # production build SUCCEEDS — this is the truth gate (L1)
git status             # repo initialized; expected files tracked
```
A green build with the wrong files, placeholder envs, or an unapplied theme is NOT done.
If a step is genuinely blocked (e.g. user skipped a required token), finish every
file-disjoint safe step anyway and record the blocker explicitly in `@fix_plan.md`.

## Evidence / no-hallucination guardrail
- **Never invent versions.** Report the versions Context7 returned and that actually installed
  (`cat package.json` / lockfile) — not numbers from memory (L1: runtime is the only truth).
- **Never claim a file exists without writing it.** Every item in the Phase 8 summary must
  correspond to a file actually created — verify with `ls`/`Glob`, don't assert from the plan.
- **No silent substitution.** If Context7 is unavailable, say so and use the template patterns
  explicitly — don't pretend you fetched latest.
- A 403/401 from Context7, gh, or Vercel is an ABORT for that step, never a PASS (L5).

---

## CRITICAL: ALWAYS USE LATEST VERSIONS

**Before ANY installation**, fetch latest documentation via Context7:

```
ToolSearch(query: "select:mcp__context7__resolve-library-id")
ToolSearch(query: "select:mcp__context7__query-docs")
```

**Libraries to check:**
- `next` → Next.js setup and App Router patterns
- `convex` → Convex initialization and best practices
- `@clerk/nextjs` → Clerk integration patterns
- `stripe` → Stripe API and webhook setup
- `tailwindcss` → Tailwind v4 configuration
- `expo` → Expo SDK latest setup (for mobile)

---

## PHASE 1: PROJECT IDENTITY

### Q1: Project Type
Ask using AskUserQuestion:
```yaml
question: "What type of project are you building?"
header: "Type"
options:
  - label: "SaaS Web App"
    description: "Dashboard, auth, billing, user management"
  - label: "Landing Page / Marketing Site"
    description: "Product showcase, pricing, lead capture"
  - label: "Mobile App (iOS)"
    description: "Native iOS experience with Expo"
  - label: "Mobile App (iOS + Android)"
    description: "Cross-platform mobile with Expo"
  - label: "Desktop App"
    description: "macOS/Windows with Tauri or Electron"
  - label: "Chrome Extension"
    description: "Browser extension"
  - label: "API Backend"
    description: "Backend service only"
```

### Q2: Category & Name
```yaml
question: "Project category?"
header: "Category"
options:
  - label: "Work (personal)"
    description: "Personal projects → /VibeCoding/work/"
  - label: "Client"
    description: "Client work → /VibeCoding/clients/"
  - label: "AgentikOS"
    description: "AgentikOS ecosystem → /VibeCoding/work/"
  - label: "Life"
    description: "Life management → /VibeCoding/1-life/"
```

Then ask: "What's the project name?" (free text)

### Q3: Business Model (if SaaS or App)
```yaml
question: "Business model?"
header: "Revenue"
options:
  - label: "Freemium"
    description: "Free tier + paid upgrades"
  - label: "Subscription only"
    description: "Paid plans from the start"
  - label: "One-time purchase"
    description: "Single payment"
  - label: "Free / Open source"
    description: "No monetization"
```

---

## PHASE 2: TECH STACK (Dynamic based on type)

### For SaaS Web App:
```yaml
question: "Backend & Database?"
header: "Backend"
options:
  - label: "Convex (Recommended)"
    description: "Real-time, TypeScript, serverless"
  - label: "Supabase"
    description: "PostgreSQL, real-time, auth included"
  - label: "Custom API (Hono)"
    description: "Build your own backend"
```

```yaml
question: "Authentication?"
header: "Auth"
options:
  - label: "Clerk (Recommended)"
    description: "Best UX, social logins, MFA"
  - label: "Better Auth"
    description: "Self-hosted, flexible"
  - label: "Auth.js (NextAuth)"
    description: "Open source, customizable"
```

```yaml
question: "Payments?" (if Freemium/Subscription/One-time)
header: "Payments"
options:
  - label: "Stripe (Recommended)"
    description: "Industry standard, subscriptions"
  - label: "LemonSqueezy"
    description: "Simple, handles taxes"
  - label: "None for now"
    description: "Add later"
```

### For Mobile App:
```yaml
question: "Mobile framework?"
header: "Framework"
options:
  - label: "Expo (Recommended)"
    description: "Faster dev, OTA updates, EAS"
  - label: "React Native CLI"
    description: "More control, native modules"
```

```yaml
question: "UI Library?"
header: "Mobile UI"
options:
  - label: "NativeWind (Recommended)"
    description: "Tailwind for React Native"
  - label: "Tamagui"
    description: "Universal, performant"
  - label: "React Native Paper"
    description: "Material Design"
```

---

## PHASE 3: DESIGN & THEME

### Q: Theme Source
```yaml
question: "How do you want to set up the design theme?"
header: "Theme"
options:
  - label: "Paste custom theme (oklch CSS)"
    description: "I'll paste my shadcn theme"
  - label: "Use preset: Minimal Light"
    description: "Clean, neutral, professional"
  - label: "Use preset: Dark Techy"
    description: "Dark mode, modern, like Vercel"
  - label: "Use preset: Warm Earthy"
    description: "Cozy, organic tones"
  - label: "Generate from primary color"
    description: "I'll give you a hex color"
```

If "Paste custom theme" → Ask user to paste the full CSS (like the oklch example they provided)

### Theme Application
The theme will be written to:
- `src/app/globals.css` - CSS variables (oklch format)
- Tailwind config updated to use CSS variables
- Both `:root` (light) and `.dark` (dark) modes

### Icons
Default: **Lucide Icons** (`lucide-react`)
```bash
bun add lucide-react
```

---

## PHASE 4: INITIAL PAGES/SCREENS

### For SaaS Web:
```yaml
question: "Which pages should I scaffold?"
header: "Pages"
multiSelect: true
options:
  - label: "Landing Page (hero, features, CTA)"
  - label: "Pricing Page"
  - label: "Dashboard"
  - label: "Settings Page"
  - label: "User Profile"
  - label: "Auth Pages (sign-in, sign-up)"
```

### For Mobile:
```yaml
question: "Which screens?"
header: "Screens"
multiSelect: true
options:
  - label: "Onboarding Flow"
  - label: "Home/Feed"
  - label: "Profile"
  - label: "Settings"
  - label: "Notifications"
```

---

## PHASE 5: TOKENS & SECRETS

Ask user to provide (or skip for later):

### Required Tokens
```
I need some API keys to fully configure the project.
You can skip any and add them later to .env.local

1. VERCEL_TOKEN (for deployment)
   → Get from: https://vercel.com/account/tokens

2. GITHUB_TOKEN (for repo creation)
   → Already configured if using gh CLI

3. CONVEX_DEPLOYMENT (after `bunx convex init`)
   → Will be created during setup

4. CLERK_SECRET_KEY
   → Get from: https://dashboard.clerk.com
   → Create app first, then copy keys

5. STRIPE_SECRET_KEY (if payments)
   → Get from: https://dashboard.stripe.com/apikeys

Paste each token when prompted, or type "skip" to configure later.
```

### Environment Setup
Create both:
- `.env.local` - Actual secrets (gitignored)
- `.env.example` - Template with placeholders

---

## PHASE 6: EXTRAS (Smart Defaults)

### Extras Selection
Present options with **intelligent defaults** based on project type:

```yaml
question: "Which extras do you want to include?"
header: "Extras"
multiSelect: true
options:
  - label: "CI/CD (GitHub Actions)"
    description: "Lint, type-check, tests on PR + preview deploys"
  - label: "Testing Setup (Vitest + Playwright)"
    description: "Unit tests + E2E tests pre-configured"
  - label: "Pre-commit Hooks (Husky)"
    description: "Lint + type-check before each commit"
  - label: "Error Tracking (Sentry)"
    description: "Capture errors in production"
```

### Smart Defaults by Project Type

| Project Type | CI/CD | Testing | Hooks | Sentry | SEO | i18n | Rate Limit |
|--------------|-------|---------|-------|--------|-----|------|------------|
| **SaaS Web App** | ✅ | ✅ | ✅ | ✅ | ✅ | ❓ | ✅ |
| **Landing Page** | ✅ | ❌ | ✅ | ❌ | ✅ | ❓ | ❌ |
| **Mobile App** | ✅ | ✅ | ✅ | ✅ | ❌ | ❓ | ❌ |
| **Desktop App** | ✅ | ✅ | ✅ | ✅ | ❌ | ❓ | ❌ |
| **Chrome Extension** | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
| **API Backend** | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ |

*❓ = Ask user (depends on target audience)*

### Extra: CI/CD (GitHub Actions)

Create `.github/workflows/ci.yml`:
```yaml
name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  lint-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v1

      - name: Install dependencies
        run: bun install --frozen-lockfile

      - name: Lint
        run: bun run lint

      - name: Type check
        run: bun run type-check

      - name: Unit tests
        run: bun run test

      - name: Build
        run: bun run build
        env:
          NEXT_PUBLIC_CONVEX_URL: ${{ secrets.NEXT_PUBLIC_CONVEX_URL }}

  # Vercel handles preview deployments automatically
```

Create `.github/dependabot.yml`:
```yaml
version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    commit-message:
      prefix: "deps"
    groups:
      minor-and-patch:
        patterns:
          - "*"
        update-types:
          - "minor"
          - "patch"
```

### Extra: Testing Setup

**Unit Tests (Vitest):**
```bash
bun add -D vitest @vitejs/plugin-react @testing-library/react @testing-library/jest-dom
```

Create `vitest.config.ts`:
```typescript
import { defineConfig } from 'vitest/config'
import react from '@vitejs/plugin-react'
import path from 'path'

export default defineConfig({
  plugins: [react()],
  test: {
    environment: 'jsdom',
    setupFiles: ['./src/test/setup.ts'],
    include: ['**/*.test.{ts,tsx}'],
  },
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
})
```

Create `src/test/setup.ts`:
```typescript
import '@testing-library/jest-dom'
```

**E2E Tests (Playwright):**
```bash
bun add -D @playwright/test
bunx playwright install chromium
```

Create `playwright.config.ts`:
```typescript
import { defineConfig, devices } from '@playwright/test'

export default defineConfig({
  testDir: './e2e',
  fullyParallel: true,
  retries: process.env.CI ? 2 : 0,
  reporter: 'html',
  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'Mobile Safari', use: { ...devices['iPhone 13'] } },
  ],
  webServer: {
    command: 'bun run dev',
    url: 'http://localhost:3000',
    reuseExistingServer: !process.env.CI,
  },
})
```

Add scripts to `package.json`:
```json
{
  "scripts": {
    "test": "vitest",
    "test:ui": "vitest --ui",
    "test:e2e": "playwright test",
    "test:e2e:ui": "playwright test --ui",
    "type-check": "tsc --noEmit"
  }
}
```

### Extra: Pre-commit Hooks (Husky + lint-staged)

```bash
bun add -D husky lint-staged
bunx husky init
echo "bunx lint-staged" > .husky/pre-commit
```

Add to `package.json`:
```json
{
  "lint-staged": {
    "*.{ts,tsx}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.{json,md,css}": [
      "prettier --write"
    ]
  }
}
```

### Extra: Error Tracking (Sentry)

```bash
bun add @sentry/nextjs
```

Create `sentry.client.config.ts`:
```typescript
import * as Sentry from "@sentry/nextjs"

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  tracesSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
  replaysSessionSampleRate: 0.1,
  integrations: [
    Sentry.replayIntegration(),
  ],
})
```

Add to `.env.local`:
```env
NEXT_PUBLIC_SENTRY_DSN=
SENTRY_AUTH_TOKEN=
```

### Extra: SEO Setup (for SaaS/Landing)

Create `src/lib/metadata.ts`:
```typescript
import type { Metadata } from 'next'

export function generateMetadata({
  title,
  description,
  path = '/',
  image = '/og-image.png',
}: {
  title: string
  description: string
  path?: string
  image?: string
}): Metadata {
  const url = `https://${process.env.NEXT_PUBLIC_SITE_URL}${path}`

  return {
    title,
    description,
    openGraph: {
      title,
      description,
      url,
      siteName: process.env.NEXT_PUBLIC_SITE_NAME,
      images: [{ url: image, width: 1200, height: 630 }],
      type: 'website',
    },
    twitter: {
      card: 'summary_large_image',
      title,
      description,
      images: [image],
    },
    alternates: {
      canonical: url,
    },
  }
}
```

Create `public/robots.txt`:
```
User-agent: *
Allow: /
Sitemap: https://${SITE_URL}/sitemap.xml
```

Create `src/app/sitemap.ts`:
```typescript
import { MetadataRoute } from 'next'

export default function sitemap(): MetadataRoute.Sitemap {
  const baseUrl = process.env.NEXT_PUBLIC_SITE_URL || 'https://example.com'

  return [
    { url: baseUrl, lastModified: new Date(), changeFrequency: 'daily', priority: 1 },
    { url: `${baseUrl}/pricing`, lastModified: new Date(), changeFrequency: 'weekly', priority: 0.8 },
    // Add more pages as needed
  ]
}
```

### Extra: Rate Limiting (Vercel Edge)

Create `src/middleware.ts`:
```typescript
import { NextResponse, type NextRequest } from 'next/server'
import { Ratelimit } from '@upstash/ratelimit'
import { Redis } from '@upstash/redis'

const ratelimit = new Ratelimit({
  redis: Redis.fromEnv(),
  limiter: Ratelimit.slidingWindow(10, '10 s'), // 10 requests per 10 seconds
  analytics: true,
})

export async function middleware(request: NextRequest) {
  // Only rate limit API routes
  if (!request.nextUrl.pathname.startsWith('/api')) {
    return NextResponse.next()
  }

  const ip = request.ip ?? '127.0.0.1'
  const { success, limit, reset, remaining } = await ratelimit.limit(ip)

  if (!success) {
    return NextResponse.json(
      { error: 'Too many requests' },
      {
        status: 429,
        headers: {
          'X-RateLimit-Limit': limit.toString(),
          'X-RateLimit-Remaining': remaining.toString(),
          'X-RateLimit-Reset': reset.toString(),
        },
      }
    )
  }

  return NextResponse.next()
}

export const config = {
  matcher: '/api/:path*',
}
```

Add dependencies:
```bash
bun add @upstash/ratelimit @upstash/redis
```

Add to `.env.local`:
```env
UPSTASH_REDIS_REST_URL=
UPSTASH_REDIS_REST_TOKEN=
```

### Extra: i18n (next-intl)

Ask only if project targets multiple languages:
```yaml
question: "Will your app support multiple languages?"
header: "i18n"
options:
  - label: "Yes, multiple languages"
    description: "Set up next-intl for internationalization"
  - label: "No, single language"
    description: "Skip i18n setup"
```

If yes:
```bash
bun add next-intl
```

Create `src/i18n.ts`:
```typescript
import { getRequestConfig } from 'next-intl/server'

export default getRequestConfig(async ({ locale }) => ({
  messages: (await import(`../messages/${locale}.json`)).default
}))
```

---

## PHASE 7: EXECUTION

Execute in this EXACT order:

### Step 0: Fetch Latest Versions via Context7

**CRITICAL: Always fetch latest docs before installing anything!**

```
# 1. Resolve library IDs
mcp__context7__resolve-library-id(libraryName: "next")
mcp__context7__resolve-library-id(libraryName: "convex")
mcp__context7__resolve-library-id(libraryName: "@clerk/nextjs")

# 2. Query for setup instructions
mcp__context7__query-docs(
  context7CompatibleLibraryID: "/vercel/next.js",
  topic: "app router setup installation",
  tokens: 5000
)

mcp__context7__query-docs(
  context7CompatibleLibraryID: "/convex-dev/convex-js",
  topic: "nextjs setup initialization",
  tokens: 5000
)

mcp__context7__query-docs(
  context7CompatibleLibraryID: "/clerk/clerk-docs",
  topic: "nextjs app router integration",
  tokens: 5000
)
```

**Use the returned docs** to ensure setup follows latest patterns!

### Step 1: Create Project Directory
```bash
# Determine path
CATEGORY_PATH="/home/hacker/VibeCoding/{category}/"
PROJECT_PATH="${CATEGORY_PATH}${PROJECT_NAME}"
mkdir -p "$PROJECT_PATH"
cd "$PROJECT_PATH"
```

### Step 2: Initialize Stack (USING LATEST PATTERNS FROM CONTEXT7)
Based on selections AND Context7 docs, run appropriate commands.

**For Next.js + Convex + Clerk:**
```bash
# Create Next.js (latest version)
bunx create-next-app@latest . --typescript --tailwind --eslint --app --src-dir --import-alias "@/*" --use-bun --yes

# Add dependencies (Context7 tells us the latest compatible versions)
bun add convex @clerk/nextjs clsx tailwind-merge lucide-react
bun add -D @types/node

# Initialize Convex (interactive - needs user input)
bunx convex init
```

**IMPORTANT:** If Context7 docs show different setup patterns (e.g., new API routes, new middleware format), **use the Context7 patterns** instead of this template!

### Step 3: Apply Theme
Write the user's theme to `src/app/globals.css`:
- Include `:root` variables
- Include `.dark` variables
- Include `@theme inline` block
- Configure Tailwind to use CSS variables

### Step 4: Setup shadcn/ui
```bash
bunx shadcn@latest init -y
bunx shadcn@latest add button card input label -y
```

### Step 5: Create Project Structure
```
src/
├── app/
│   ├── (auth)/
│   │   ├── sign-in/[[...sign-in]]/page.tsx
│   │   └── sign-up/[[...sign-up]]/page.tsx
│   ├── (marketing)/
│   │   ├── page.tsx (landing)
│   │   └── pricing/page.tsx
│   ├── (dashboard)/
│   │   ├── layout.tsx
│   │   ├── page.tsx
│   │   └── settings/page.tsx
│   ├── api/
│   │   └── webhooks/
│   ├── layout.tsx
│   └── globals.css
├── components/
│   ├── ui/ (shadcn)
│   ├── landing/
│   │   ├── hero.tsx
│   │   ├── features.tsx
│   │   └── cta.tsx
│   ├── dashboard/
│   │   ├── sidebar.tsx
│   │   └── header.tsx
│   └── providers/
│       ├── convex-provider.tsx
│       └── theme-provider.tsx
├── lib/
│   ├── utils.ts
│   └── convex.ts
└── convex/
    └── schema.ts
```

### Step 6: Create Core Files

**Root Layout with Providers:**
```typescript
// src/app/layout.tsx
import { ClerkProvider } from "@clerk/nextjs";
import { ConvexClientProvider } from "@/components/providers/convex-provider";
import { ThemeProvider } from "@/components/providers/theme-provider";

export default function RootLayout({ children }) {
  return (
    <ClerkProvider>
      <html lang="en" suppressHydrationWarning>
        <body>
          <ThemeProvider
            attribute="class"
            defaultTheme="system"
            enableSystem
          >
            <ConvexClientProvider>
              {children}
            </ConvexClientProvider>
          </ThemeProvider>
        </body>
      </html>
    </ClerkProvider>
  );
}
```

**Landing Page Hero (reference DentistryGPT style):**
Use components from `/home/hacker/.claude/resources/ui-components/` as reference.

### Step 7: Create Environment Files

**.env.local:**
```env
# ===================
# {PROJECT_NAME} - Local Environment
# ===================

# Convex
CONVEX_DEPLOYMENT={FROM_INIT}
NEXT_PUBLIC_CONVEX_URL={FROM_INIT}

# Clerk
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY={USER_PROVIDED}
CLERK_SECRET_KEY={USER_PROVIDED}
CLERK_WEBHOOK_SECRET=

# Clerk URLs
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL=/dashboard
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL=/dashboard

# Stripe (if applicable)
STRIPE_SECRET_KEY={USER_PROVIDED}
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=
STRIPE_WEBHOOK_SECRET=

# Vercel (for deployment)
VERCEL_TOKEN={USER_PROVIDED}
```

**.env.example:**
Same structure but with placeholder values like `your_key_here`

### Step 8: Setup Convex-Clerk Integration

**convex/auth.config.ts:**
```typescript
export default {
  providers: [
    {
      domain: process.env.CLERK_JWT_ISSUER_DOMAIN,
      applicationID: "convex",
    },
  ],
};
```

### Step 9: Configure Task Tracking
```bash
mkdir -p specs

cat > @fix_plan.md << 'EOF'
# Fix Plan - {PROJECT_NAME}

## Priority Tasks
- [ ] Complete initial setup
- [ ] Configure API keys in .env.local
- [ ] Set up Convex schema
- [ ] Build core features

## Completed
- [x] Project scaffolded with /new-project

## Notes
- Stack: {STACK_SUMMARY}
- Created: {DATE}
EOF

cat > @AGENT.md << 'EOF'
# Agent Instructions - {PROJECT_NAME}

## Build
bun run build

## Dev
bun run dev
# In separate terminal:
bunx convex dev

## Test
bun run test

## Lint
bun run lint

## Deploy
bunx convex deploy
vercel --prod --token $VERCEL_TOKEN
EOF
```

### Step 10: Setup Git
```bash
# Determine git account
# AgentikOS / Work → agentik-os / x@agentik-os.com
# Clients → Ask user

git init
git config user.email "{EMAIL}"
git config user.name "{NAME}"

# Create comprehensive .gitignore
cat > .gitignore << 'EOF'
# Dependencies
node_modules/
.pnp
.pnp.js

# Build
.next/
out/
dist/
build/

# Environment
.env
.env.local
.env.*.local

# Logs
*.log
npm-debug.log*

# IDE
.idea/
.vscode/
*.swp
*.swo

# OS
.DS_Store
Thumbs.db

# Convex
.convex/
EOF

# If creating GitHub repo
gh repo create {PROJECT_NAME} --{visibility} --source=. --remote=origin --push
```

### Step 11: Add Tmux Alias
```bash
# Determine alias (lowercase, short)
ALIAS=$(echo "{PROJECT_NAME}" | tr '[:upper:]' '[:lower:]' | cut -c1-10)

# Add to .zshrc
echo "" >> ~/.zshrc
echo "# {PROJECT_NAME}" >> ~/.zshrc
echo "alias c-${ALIAS}='tmux-project {PROJECT_NAME} ${PROJECT_PATH}'" >> ~/.zshrc

# Reload
source ~/.zshrc
```

### Step 12: Allocate Port
```bash
# Find next available port in category range
# Read current ports from rules file
# Assign next available
# Update /home/hacker/.claude/rules/01-project-ports.md
```

### Step 13: Index to Supermemory
```bash
export SUPERMEMORY_CC_API_KEY="sm_YiBVFZ1vPijXgoQKtcgVJN_MyIIGBDIpClaHGeTRDZrxuxTZqbITalqJnPKHcAJgUcVZvmvBzaJhkdYDuXSefKf"
/home/hacker/.claude/lib/supermemory-batch-index.sh "$PROJECT_PATH" "{CONTAINER}"
```

### Step 14: Create CLAUDE.md
Write comprehensive CLAUDE.md with:
- Project overview
- Tech stack details
- All commands
- Environment setup instructions
- Architecture decisions
- Ecosystem reference
- Deployed URLs (when available)

### Step 15: Update Documentation
- Add to `/home/hacker/.claude/rules/01-project-ports.md`
- Add to `/home/hacker/.claude/rules/04-tmux-sessions.md`

### Step 16: Install Selected Extras

Based on Phase 6 selections, install and configure:

**If CI/CD selected:**
```bash
mkdir -p .github/workflows
# Create ci.yml and dependabot.yml (see Phase 6)
```

**If Testing selected:**
```bash
bun add -D vitest @vitejs/plugin-react @testing-library/react @testing-library/jest-dom
bun add -D @playwright/test
bunx playwright install chromium
# Create vitest.config.ts, playwright.config.ts, src/test/setup.ts
# Add scripts to package.json
```

**If Husky selected:**
```bash
bun add -D husky lint-staged prettier
bunx husky init
echo "bunx lint-staged" > .husky/pre-commit
# Add lint-staged config to package.json
```

**If Sentry selected:**
```bash
bun add @sentry/nextjs
bunx @sentry/wizard@latest -i nextjs
# Create sentry.client.config.ts
# Add SENTRY_DSN to .env.local
```

**If SEO selected:**
```bash
# Create src/lib/metadata.ts
# Create public/robots.txt
# Create src/app/sitemap.ts
```

**If Rate Limiting selected:**
```bash
bun add @upstash/ratelimit @upstash/redis
# Create src/middleware.ts
# Add UPSTASH_* to .env.local
```

**If i18n selected:**
```bash
bun add next-intl
# Create src/i18n.ts
# Create messages/ directory
```

---

## PHASE 8: FINAL SUMMARY

Output a beautiful summary:

```
╔══════════════════════════════════════════════════════════════╗
║  ✅ PROJECT CREATED: {PROJECT_NAME}
╚══════════════════════════════════════════════════════════════╝

📁 Location: {PROJECT_PATH}
🖥️  Tmux: c-{alias}
🌐 Dev URL: http://72.61.197.216:{PORT}
🧠 Memory: {SUPERMEMORY_CONTAINER}

┌─────────────────────────────────────────────────────────────┐
│ TECH STACK (Latest versions via Context7)                   │
├─────────────────────────────────────────────────────────────┤
│ Frontend: Next.js {VERSION} + React {VERSION} + Tailwind    │
│ Backend:  Convex {VERSION} (real-time)                      │
│ Auth:     Clerk {VERSION}                                   │
│ Payments: Stripe                                            │
│ UI:       shadcn/ui + Lucide Icons                          │
│ Theme:    Custom oklch (light + dark)                       │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ EXTRAS INSTALLED                                            │
├─────────────────────────────────────────────────────────────┤
│ {if CI/CD}     ✅ CI/CD: GitHub Actions (lint, test, build) │
│ {if Testing}   ✅ Testing: Vitest + Playwright              │
│ {if Husky}     ✅ Pre-commit: Husky + lint-staged           │
│ {if Sentry}    ✅ Error tracking: Sentry                    │
│ {if SEO}       ✅ SEO: meta, sitemap, robots.txt            │
│ {if RateLimit} ✅ Rate limiting: Upstash Redis              │
│ {if i18n}      ✅ i18n: next-intl                           │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ PAGES CREATED                                               │
├─────────────────────────────────────────────────────────────┤
│ ✅ Landing Page (/, hero, features, CTA)                    │
│ ✅ Pricing Page (/pricing)                                  │
│ ✅ Dashboard (/dashboard)                                   │
│ ✅ Settings (/dashboard/settings)                           │
│ ✅ Auth Pages (/sign-in, /sign-up)                          │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ ⚠️  NEXT STEPS (DO THIS NOW)                                │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│ 1. Configure Clerk:                                         │
│    → Go to https://dashboard.clerk.com                      │
│    → Create app, copy keys to .env.local                    │
│    → Set up webhook: /api/webhooks/clerk                    │
│                                                             │
│ 2. Configure Convex:                                        │
│    → Run: bunx convex dev                                   │
│    → This will prompt for Convex login                      │
│                                                             │
│ 3. Configure Stripe (if payments):                          │
│    → Go to https://dashboard.stripe.com                     │
│    → Copy keys to .env.local                                │
│    → Create products/prices                                 │
│                                                             │
│ 4. Start development:                                       │
│    → Terminal 1: bun run dev                                │
│    → Terminal 2: bunx convex dev                            │
│                                                             │
│ 5. Open your app:                                           │
│    → http://72.61.197.216:{PORT}                            │
│                                                             │
└─────────────────────────────────────────────────────────────┘

📚 Documentation:
   - CLAUDE.md in project root
   - @fix_plan.md for task tracking

🚀 Quick start:
   c-{alias}
```

---

## REFERENCE: Available Resources

### UI Component Libraries
| Library | Components | Path |
|---------|------------|------|
| shadcn/ui | 53 | `/home/hacker/.claude/resources/ui-components/shadcnui-components/` |
| KokonutUI | 44 | `/home/hacker/.claude/resources/ui-components/kokonutui-components/` |
| CultUI | 49 | `/home/hacker/.claude/resources/ui-components/cultui-components/` |
| MotionUI | 33 | `/home/hacker/.claude/resources/ui-components/motionui-components/` |
| PromptKitUI | 21 | `/home/hacker/.claude/resources/ui-components/promptkitui-components/` |

### Templates
| Template | Path |
|----------|------|
| Dashboard Reference | `/home/hacker/VibeCoding/work/templates/dashboard-reference/` |
| PRD Template | `/home/hacker/VibeCoding/work/templates/PRD_BASE_TEMPLATE.md` |
| Env Template | `/home/hacker/VibeCoding/work/templates/project.env.template` |

### Reference Projects
| Project | Type | Path |
|---------|------|------|
| DentistryGPT | SaaS + AI | `/home/hacker/VibeCoding/clients/DentistryGPT/` |
| Kommu | SaaS + Real-time | `/home/hacker/VibeCoding/work/kommu/` |
| LifePixels | Mobile iOS | `/home/hacker/VibeCoding/work/LifePixels/` |

### Git Accounts
| Category | Account | Email |
|----------|---------|-------|
| Work / AgentikOS | agentik-os | x@agentik-os.com |
| Clients | (ask) | (ask) |

---

## IMPORTANT NOTES

1. **ALWAYS use Context7 first** - Fetch latest docs before ANY installation
2. **Use hacker user** - Never root
3. **Theme is critical** - Apply the full oklch theme correctly
4. **Reference existing projects** - Use DentistryGPT/Kommu as quality benchmarks
5. **Verify each step** - Don't proceed if something fails
6. **Landing page quality** - Must be as clean as DentistryGPT
7. **Dashboard quality** - Use dashboard-reference as guide
8. **Smart defaults** - Pre-select extras based on project type
9. **Latest patterns** - If Context7 shows different setup than template, USE CONTEXT7
10. **Version tracking** - Note actual installed versions in CLAUDE.md

## VERSION CHECKING PROTOCOL

Before creating any project, ALWAYS run:

```
# 1. Check Next.js latest
mcp__context7__resolve-library-id(libraryName: "next")
→ Then query for "app router setup create-next-app"

# 2. Check Convex latest
mcp__context7__resolve-library-id(libraryName: "convex")
→ Then query for "nextjs setup initialization"

# 3. Check Clerk latest
mcp__context7__resolve-library-id(libraryName: "@clerk/nextjs")
→ Then query for "app router middleware setup"

# 4. Check Tailwind latest
mcp__context7__resolve-library-id(libraryName: "tailwindcss")
→ Then query for "v4 configuration"
```

**WHY?** APIs change frequently. A setup that worked in January might be different in February.
The templates in this file are guidelines - Context7 docs are the source of truth.