Create App Implementation Plan

For Claude Code: Follow this plan phase-by-phase. If any step fails, notify the user and ask for next steps.

Phase Summary Template: At the end of each phase, output to the user a detailed summary (2-3 paragraphs) that includes:

• What was accomplished in this phase
• Key files/directories created or modified
• Important values to remember (service_id, schema names, etc.)
• Brief preview of what's coming next

Goal: Scaffold a production-ready fullstack web application with database, optional auth, and polished UI.

Architecture: T3 stack (Next.js + tRPC + Drizzle) with Timescale Cloud database and shadcn/ui components.

Tech Stack: Next.js, tRPC, Drizzle ORM, Timescale Cloud (PostgreSQL), Better Auth, shadcn/ui, Tailwind CSS

Getting Started

Tell the user:

"Let's build a minimal v0/demo version of your app. We'll focus on the core features needed to get something working, then iterate from there.

Here's how we'll build this:

• 🎯 Phase 1: Understand the product - I'll ask a few questions about what you're building
• 🏗️ Phase 2: Scaffold the app - Create a cloud database and app with Next.js, tRPC, and Drizzle
• 🔐 Phase 3: Configure auth (if needed) - Set up user authentication
• 🗄️ Phase 4: Design the database - Create tables for your data
• ⚙️ Phase 5: Build the backend - Create API endpoints with tRPC
• 🎨 Phase 6: Build the frontend - Create pages and components with shadcn/ui
• ✅ Phase 7: Run, verify, and commit - Make sure everything works and save to git

Optional hardening (after commit):

• 🧪 Phase 8: Add testing - Integration tests with Vitest
• 🔍 Phase 9: Strict checks - Stricter TypeScript and linting

Let's go!"

Phase 1: Understand the Product

Key Principles:

• One question at a time - Don't overwhelm with multiple questions
• Multiple choice preferred - Easier to answer than open-ended when possible
• YAGNI ruthlessly - Remove unnecessary features from all designs
• Explore alternatives - Always propose 2-3 approaches before settling
• Incremental validation - Present design in sections, validate each
• Be flexible - Go back and clarify when something doesn't make sense

1. Determine app type - If not clear from the prompt, ask: "Is this a multi-user app (requires user accounts/login)?"

2. Gather auth requirements (if multi-user) - Ask the user: "Which authentication methods do you want? Pick one or more:" Email signup, GitHub OAuth, Google OAuth

3. Confirm app name - Propose a sensible app name based on the user's request. The name should be lowercase, use hyphens instead of spaces (e.g., todo-app, fitness-tracker), and appropriate for a directory name. Ask: "I'll name the project <proposed-name>. Does that work, or would you prefer something else?"

4. Understand what product you are building - Try to understand the project from the user prompt then ask questions one at a time to refine the idea. Focus on what the product will do, NOT technical details.

Once you understand what you're building, present the product brief to the user for confirmation:

1. App type: Single-user or multi-user
2. Authentication (if multi-user): Which methods (email, GitHub, Google)
3. Product description: A one to three paragraph description of what the project will do
4. Minimal features for v0/demo: A short bulleted list - just enough to get a working application

Example product brief:

**App type:** Multi-user

**Authentication:** Email signup

**Product description:**
A collaborative to-do app where users can create personal to-do lists and share them with other users. Users sign up with email, create tasks, and can invite collaborators to view or edit their lists together.

**Minimal features for v0/demo:**
- Email signup/login
- Create, edit, delete, and complete to-dos
- Share a to-do list with another user by email
- Collaborators can view and edit shared lists

Ask the user: "Is this product brief correct?"

After the user confirms the product brief, ask: "Are there any features not in the v0/demo that might affect how we build this? For example: offline support, real-time sync, multi-tenancy, or specific integrations. These won't be built now, but knowing them helps us make the right architectural choices upfront."

If yes, create and confirm a list of "future features".

Phase 2: Project Setup

1. Use the create_database MCP tool to provision a new Timescale Cloud database
2. Store the returned service_id - you'll need it later
3. Use the create_web_app MCP tool with:
   • app_name confirmed in Phase 1
   • use_auth: true if multi-user app
   • product_brief from Phase 1
   • future_features from Phase 1 (if any)
4. Change into the app directory: cd <app_name>
5. Output a phase summary to the user using the template.

Phase 3: Auth Configuration (If Multi-User)

Skip this phase if the app is single-user.

1. Pass the drizzle schemas into drizzleAdapter in src/server/better-auth/config.ts:

   import * as schema from "~/server/db/schema";
   
   drizzleAdapter(db, {
     provider: "pg",
     schema,
   })
   

2. Update the Better Auth configuration to enable only the providers the user requested (email, GitHub, Google)
3. Update src/env.js, .env, and .env.example with the required environment variables for the auth providers
4. Output a phase summary to the user using the template.

Phase 4: Database Schema

1. Check that the database status is READY using the service_get MCP tool with the service_id from Phase 2. If not ready, poll every 10 seconds for up to 2 minutes.

2. Use the setup_app_schema MCP tool with:

   • application_directory: "."
   • service_id from Phase 2
   • app_name (use the same name, converted to lowercase with underscores)

   This creates a PostgreSQL schema and user, and writes DATABASE_URL and DATABASE_SCHEMA to .env

3. In src/env.js add DATABASE_SCHEMA variable (use the schema_name returned by setup_app_schema as default) to both the server and runtimeEnv sections

4. Modify drizzle.config.ts to remove the tablesFilter and add a schemasFilter with the value of the DATABASE_SCHEMA env variable

5. In src/server/db/schema.ts, remove pgTableCreator pattern and instead create all tables (including auth tables, if present) using:

   export const dbSchema = pgSchema(env.DATABASE_SCHEMA);
   const createTable = dbSchema.table;
   

   Note: make sure the schema is exported

6. Delete the example post table definition - it was only there as a template

7. Based on the user's app requirements, add the necessary Drizzle table definitions to src/server/db/schema.ts

8. Push schema to database: npm run db:push

9. Output a phase summary to the user using the template.

Phase 5: Backend Implementation

1. Remove any example/post router that references the old post model
2. Create tRPC routers for CRUD operations on the app's data models in src/server/api/routers/
3. Register new routers in src/server/api/root.ts
4. Verify with npx tsc --noEmit -p tsconfig.server.json (checks only server code, avoids frontend errors)
5. Output a phase summary to the user using the template.

Phase 6: Frontend Implementation

1. Install and configure shadcn:

   npx shadcn@latest init --base-color=neutral
   cp src/styles/globals.css.orange src/styles/globals.css
   

2. Install required shadcn components (button, card, input, form, table, etc.):

   npx shadcn@latest add <component1> <component2> ...
   

3. Build the pages needed for the app using shadcn components (ensure all buttons have a type attribute)

4. Connect pages to the backend using tRPC hooks to fetch and mutate data

5. Create a sign-in form component at src/components/auth/sign-in-form.tsx (if multi-user) supporting all requested auth methods (email, GitHub, Google)

6. Replace hardcoded T3 template colors with shadcn CSS variables:

   • bg-gradient-to-b from-slate-900 to-slate-800 → bg-background
   • text-white → text-foreground
   • bg-white/10 → bg-muted
   • border-white/20 → border-border

7. Verify with npm run build and fix any errors

8. Output a phase summary to the user using the template.

Phase 7: Run, Verify, and Commit

1. Run npm run check:write to auto-fix formatting issues, then verify npm run check passes

2. Start the dev server: npm run dev

3. Use the open_app MCP tool to open http://localhost:3000 in a browser and verify the app works as expected

4. Use the write_claude_md MCP tool to generate the project guide:

   • application_directory: "."
   • app_name: from Phase 1
   • use_auth: Whether auth is enabled
   • product_brief: from Phase 1
   • future_features: from Phase 1 (if any)
   • db_schema: from setup_app_schema in Phase 4
   • db_user: from setup_app_schema in Phase 4

5. Read the generated CLAUDE.md file. Make sure it is accurate. Fix if needed.

6. Ask the user "Do you want to commit this initial version to git?". If yes:

   git init
   git add .
   git commit -m "Initial commit: <app_name>"
   

7. Tell the user:

"🎉 Congrats! Your app is set up and committed. You have a working demo you can iterate on.

Next steps:

• 🛡️ Harden - Add testing and stricter checks (recommended)
• 🧠 Brainstorm - Plan your next features
• 🚀 Deploy - Ship to Vercel

Why harden? These checks act like a reward signal for AI-assisted development - they catch mistakes early and help guide me toward correct solutions faster. Without them, bugs can compound silently.

Shall we add hardening now?"

If the user wants to skip hardening, the skill is complete.

Phase 8: Backend Testing (Optional Hardening)

Ask the user (yes/no): "Do you want to add backend testing?"

If no, skip this phase.

1. Use the view_skill MCP tool to read the add-backend-testing skill
2. Follow the skill with service_id from Phase 2
3. Offer to git commit these changes

Phase 9: Stricter Checks (Optional Hardening)

Ask the user (yes/no): "Do you want to enable stricter TypeScript checks?"

If no, skip this phase.

1. Use the view_skill MCP tool to read the add-strict-checks skill
2. Follow the skill
3. Offer to git commit these changes