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