new-project

# /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 ```