Fullstack App

Phase 0: Understand the App

Ask the user (skip any already answered):

1. What does the app do? (e.g., "todo app", "SaaS dashboard", "booking system")
2. What are the main entities? (e.g., "tasks, projects, users" — if unclear, suggest based on #1)
3. Do they already have a Supabase project? (yes → get URL + anon key; no → will guide setup)

Do NOT ask about framework, styling, or component library — the stack is decided.

Phase 1: Scaffold the Project

npx create-next-app@latest <app-name> --ts --tailwind --app --eslint --src-dir --import-alias "@/*"
cd <app-name>

Initialize shadcn/ui

npx shadcn@latest init

When prompted: New York style, Zinc base color, CSS variables YES.

Install base components (always needed)

npx shadcn@latest add button card input label form separator

Install core packages

npm install @supabase/supabase-js @supabase/ssr @tanstack/react-query react-hook-form @hookform/resolvers zod lucide-react

Create directory structure

src/
├── app/
│   ├── (auth)/           # Auth pages (login, signup, etc.)
│   │   ├── layout.tsx
│   │   ├── login/page.tsx
│   │   ├── signup/page.tsx
│   │   ├── forgot-password/page.tsx
│   │   └── callback/route.ts
│   ├── (dashboard)/      # Protected app pages
│   │   ├── layout.tsx
│   │   ├── page.tsx       # Dashboard home
│   │   ├── settings/page.tsx
│   │   └── <entity>/     # One per entity
│   │       ├── page.tsx   # List view
│   │       └── [id]/page.tsx
│   ├── (marketing)/      # Public pages
│   │   ├── layout.tsx
│   │   └── page.tsx       # Landing page
│   ├── layout.tsx         # Root layout
│   └── providers.tsx      # TanStack Query provider
├── components/
│   ├── ui/               # shadcn/ui components (auto-generated)
│   └── <shared components>
├── hooks/
│   └── use-<entity>.ts   # TanStack Query hooks per entity
├── lib/
│   └── supabase/
│       ├── client.ts      # Browser client
│       └── server.ts      # Server client
├── middleware.ts           # Auth middleware
└── types/
    └── database.ts        # Supabase types

Run and verify

npm run dev

Fix ANY errors before proceeding.

Phase 2: Backend Setup

Load the supabase-quickstart skill and execute its Phases 1-2:

• Phase 1: Supabase project setup (or connect existing)
• Phase 2: CLI install, MCP server config, project linking

Skip supabase-quickstart's Phase 3 (frontend scaffolding) — we already have the frontend.

After Supabase is connected, create the client files:

src/lib/supabase/client.ts

import { createBrowserClient } from "@supabase/ssr"

export function createClient() {
  return createBrowserClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
  )
}

src/lib/supabase/server.ts

import { createServerClient } from "@supabase/ssr"
import { cookies } from "next/headers"

export async function createClient() {
  const cookieStore = await cookies()
  return createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    {
      cookies: {
        getAll() { return cookieStore.getAll() },
        setAll(cookiesToSet) {
          try {
            cookiesToSet.forEach(({ name, value, options }) =>
              cookieStore.set(name, value, options))
          } catch {}
        },
      },
    },
  )
}

src/middleware.ts

import { createServerClient } from "@supabase/ssr"
import { NextResponse, type NextRequest } from "next/server"

export async function middleware(request: NextRequest) {
  let response = NextResponse.next({ request })
  const supabase = createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    {
      cookies: {
        getAll() { return request.cookies.getAll() },
        setAll(cookiesToSet) {
          cookiesToSet.forEach(({ name, value }) => request.cookies.set(name, value))
          response = NextResponse.next({ request })
          cookiesToSet.forEach(({ name, value, options }) =>
            response.cookies.set(name, value, options))
        },
      },
    },
  )
  const { data: { user } } = await supabase.auth.getUser()

  if (!user && request.nextUrl.pathname.startsWith("/(dashboard)")) {
    return NextResponse.redirect(new URL("/login", request.url))
  }

  if (user && request.nextUrl.pathname.startsWith("/(auth)")) {
    return NextResponse.redirect(new URL("/", request.url))
  }

  return response
}

export const config = {
  matcher: ["/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)"],
}

.env.local

NEXT_PUBLIC_SUPABASE_URL=<from Supabase dashboard>
NEXT_PUBLIC_SUPABASE_ANON_KEY=<from Supabase dashboard>

Run npm run dev — fix any errors before proceeding.

Phase 3: Page Templates

Auth Pages

Install components:

npx shadcn@latest add card form input label button separator

src/app/(auth)/layout.tsx

export default function AuthLayout({ children }: { children: React.ReactNode }) {
  return (
    <div className="flex min-h-screen items-center justify-center bg-muted/50 p-4">
      <div className="w-full max-w-md">{children}</div>
    </div>
  )
}

src/app/(auth)/login/page.tsx

"use client"

import { useRouter } from "next/navigation"
import { useForm } from "react-hook-form"
import { zodResolver } from "@hookform/resolvers/zod"
import { z } from "zod"
import Link from "next/link"
import { createClient } from "@/lib/supabase/client"
import { Button } from "@/components/ui/button"
import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card"
import { Form, FormControl, FormField, FormItem, FormLabel, FormMessage } from "@/components/ui/form"
import { Input } from "@/components/ui/input"

const schema = z.object({
  email: z.string().email(),
  password: z.string().min(6, "Password must be at least 6 characters"),
})

export default function LoginPage() {
  const router = useRouter()
  const supabase = createClient()
  const form = useForm<z.infer<typeof schema>>({
    resolver: zodResolver(schema),
    defaultValues: { email: "", password: "" },
  })

  async function onSubmit(values: z.infer<typeof schema>) {
    const { error } = await supabase.auth.signInWithPassword(values)
    if (error) {
      form.setError("root", { message: error.message })
      return
    }
    router.push("/")
    router.refresh()
  }

  return (
    <Card>
      <CardHeader>
        <CardTitle>Log in</CardTitle>
        <CardDescription>Enter your credentials to access your account</CardDescription>
      </CardHeader>
      <CardContent>
        <Form {...form}>
          <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">
            <FormField control={form.control} name="email" render={({ field }) => (
              <FormItem>
                <FormLabel>Email</FormLabel>
                <FormControl><Input type="email" placeholder="[email protected]" {...field} /></FormControl>
                <FormMessage />
              </FormItem>
            )} />
            <FormField control={form.control} name="password" render={({ field }) => (
              <FormItem>
                <FormLabel>Password</FormLabel>
                <FormControl><Input type="password" {...field} /></FormControl>
                <FormMessage />
              </FormItem>
            )} />
            {form.formState.errors.root && (
              <p className="text-sm text-destructive">{form.formState.errors.root.message}</p>
            )}
            <Button type="submit" className="w-full" disabled={form.formState.isSubmitting}>
              {form.formState.isSubmitting ? "Signing in..." : "Sign in"}
            </Button>
          </form>
        </Form>
        <div className="mt-4 text-center text-sm text-muted-foreground">
          Don&apos;t have an account? <Link href="/signup" className="underline">Sign up</Link>
        </div>
        <div className="mt-2 text-center text-sm">
          <Link href="/forgot-password" className="text-muted-foreground underline">Forgot password?</Link>
        </div>
      </CardContent>
    </Card>
  )
}

Create similar pages for /signup (uses supabase.auth.signUp) and /forgot-password (uses supabase.auth.resetPasswordForEmail). Follow the same pattern: Card + Form + zod schema.

src/app/(auth)/callback/route.ts

import { createClient } from "@/lib/supabase/server"
import { NextResponse } from "next/server"

export async function GET(request: Request) {
  const { searchParams, origin } = new URL(request.url)
  const code = searchParams.get("code")
  const next = searchParams.get("next") ?? "/"

  if (code) {
    const supabase = await createClient()
    const { error } = await supabase.auth.exchangeCodeForSession(code)
    if (!error) return NextResponse.redirect(`${origin}${next}`)
  }

  return NextResponse.redirect(`${origin}/login?error=auth`)
}

Dashboard Layout

Install components:

npx shadcn@latest add sidebar navigation-menu avatar dropdown-menu sheet breadcrumb

src/app/(dashboard)/layout.tsx

import { createClient } from "@/lib/supabase/server"
import { redirect } from "next/navigation"
import { AppSidebar } from "@/components/app-sidebar"
import { SidebarProvider, SidebarTrigger } from "@/components/ui/sidebar"

export default async function DashboardLayout({ children }: { children: React.ReactNode }) {
  const supabase = await createClient()
  const { data: { user } } = await supabase.auth.getUser()
  if (!user) redirect("/login")

  return (
    <SidebarProvider>
      <div className="flex min-h-screen w-full">
        <AppSidebar user={user} />
        <main className="flex-1 overflow-auto">
          <div className="flex items-center gap-2 border-b px-4 py-3">
            <SidebarTrigger />
          </div>
          <div className="p-6">{children}</div>
        </main>
      </div>
    </SidebarProvider>
  )
}

Create src/components/app-sidebar.tsx using shadcn/ui Sidebar components. Include:

• App logo/name at top
• Navigation links to each entity + settings
• User avatar + dropdown at bottom (with sign-out action)

CRUD Pages (per entity)

Install components:

npx shadcn@latest add table dialog alert-dialog badge pagination select textarea

For each entity (e.g., tasks), create:

src/app/(dashboard)/tasks/page.tsx (list view)

• Server component that fetches initial data
• Client component TasksTable with:
  • Data table using shadcn Table
  • Search input
  • "Create" button that opens a Dialog with form
  • Row actions: edit, delete (with AlertDialog confirmation)
  • Pagination

src/hooks/use-tasks.ts (data hook)

import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query"
import { createClient } from "@/lib/supabase/client"
import type { Task } from "@/types/database"

export function useTasks() {
  const supabase = createClient()
  return useQuery({
    queryKey: ["tasks"],
    queryFn: async () => {
      const { data, error } = await supabase.from("tasks").select("*").order("created_at", { ascending: false })
      if (error) throw error
      return data as Task[]
    },
  })
}

export function useCreateTask() {
  const supabase = createClient()
  const queryClient = useQueryClient()
  return useMutation({
    mutationFn: async (values: Omit<Task, "id" | "created_at" | "user_id">) => {
      const { data, error } = await supabase.from("tasks").insert(values).select().single()
      if (error) throw error
      return data
    },
    onSuccess: () => queryClient.invalidateQueries({ queryKey: ["tasks"] }),
  })
}

export function useUpdateTask() {
  const supabase = createClient()
  const queryClient = useQueryClient()
  return useMutation({
    mutationFn: async ({ id, ...values }: Partial<Task> & { id: string }) => {
      const { data, error } = await supabase.from("tasks").update(values).eq("id", id).select().single()
      if (error) throw error
      return data
    },
    onSuccess: () => queryClient.invalidateQueries({ queryKey: ["tasks"] }),
  })
}

export function useDeleteTask() {
  const supabase = createClient()
  const queryClient = useQueryClient()
  return useMutation({
    mutationFn: async (id: string) => {
      const { error } = await supabase.from("tasks").delete().eq("id", id)
      if (error) throw error
    },
    onSuccess: () => queryClient.invalidateQueries({ queryKey: ["tasks"] }),
  })
}

Replicate this pattern for every entity. The hook filename is always use-<entity>.ts.

Settings Page

npx shadcn@latest add tabs switch

src/app/(dashboard)/settings/page.tsx — Tabs for Profile, Account, Notifications.

Landing Page

npx shadcn@latest add button badge

src/app/(marketing)/page.tsx — Hero section, features grid (3-4 cards), pricing (if SaaS), CTA, footer. Use semantic HTML + Tailwind. Load the frontend-design skill for styling.

src/app/(marketing)/layout.tsx — Simple layout with navbar (logo + Login/Sign up buttons) + footer.

Providers

src/app/providers.tsx

"use client"

import { QueryClient, QueryClientProvider } from "@tanstack/react-query"
import { useState } from "react"

export function Providers({ children }: { children: React.ReactNode }) {
  const [queryClient] = useState(() => new QueryClient({
    defaultOptions: { queries: { staleTime: 60 * 1000 } },
  }))
  return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
}

Wrap the root layout.tsx body with <Providers>.

Run npm run dev — fix ALL errors before proceeding.

Phase 4: Database Schema

Load the supabase skill. Design tables for the entities from Phase 0.

For every table:

1. Include user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE NOT NULL
2. Include created_at TIMESTAMPTZ DEFAULT now()
3. Enable RLS: ALTER TABLE public.<table> ENABLE ROW LEVEL SECURITY
4. Create policies for SELECT, INSERT, UPDATE, DELETE using auth.uid() = user_id

Use MCP execute_sql if available, otherwise supabase db query.

Generate migration: supabase db pull --local --yes

Create TypeScript types in src/types/database.ts matching the schema.

Phase 5: Design Polish

Load the frontend-design skill. Apply its principles to all generated pages:

• Choose a distinctive color palette (update globals.css / Tailwind theme)
• Typography: pick a characterful font pair from Google Fonts
• Micro-interactions: hover states, transitions, loading states
• Empty states: show helpful illustrations/text when no data exists
• Consistent spacing and visual rhythm

Phase 6: Generate AGENTS.md

Create AGENTS.md in the project root. Adapt this template:

# [App Name] — Agent Rules

## Stack
- Framework: Next.js 15 (App Router) + TypeScript
- Styling: Tailwind CSS + shadcn/ui
- Backend: Supabase (Database, Auth, RLS)
- Data: TanStack Query hooks + react-hook-form + zod
- Auth: @supabase/ssr with middleware token refresh

## Project Structure
- `src/app/(auth)/` — Login, signup, forgot-password, OAuth callback
- `src/app/(dashboard)/` — Protected pages (requires auth)
- `src/app/(marketing)/` — Public landing pages
- `src/components/ui/` — shadcn/ui components (do not edit manually)
- `src/hooks/use-<entity>.ts` — TanStack Query hooks per entity
- `src/lib/supabase/` — Supabase client (client.ts for browser, server.ts for server)

## Conventions
- **Add shadcn/ui components**: `npx shadcn@latest add <component-name>`
- **New entity CRUD**: Create `hooks/use-<entity>.ts` + `app/(dashboard)/<entity>/page.tsx`
- **Forms**: Always use react-hook-form + zod schema validation
- **Data fetching**: Always use TanStack Query hooks, never raw useEffect+fetch
- **Auth check**: Server components use `createClient()` from `@/lib/supabase/server`
- **Protected routes**: All pages in `(dashboard)` route group — middleware handles redirect

## Supabase
- MCP server configured in `opencode.json`
- **RLS is ON for all tables** — every new table MUST have RLS + policies
- **user_id pattern**: All user-owned tables have `user_id UUID REFERENCES auth.users(id)`
- **Migrations**: `supabase db pull --local --yes`
- **Never use `user_metadata`** for authorization

## Database Schema
[List tables and purposes — update as schema evolves]

## Environment
- `.env.local` — Supabase URL + anon key (gitignored)
- Never expose `service_role` key in client code

Phase 7: Iterative Verification

DO NOT stop after scaffolding. After each phase, run npm run dev and fix ALL errors.

After all phases complete, verify the full flow:

1. npm run dev starts clean — no errors, no warnings
2. Landing page loads at /
3. Navigate to /login — styled form renders
4. Click "Sign up" → signup page works
5. Sign up a test user — success
6. Log in with test user — redirects to dashboard
7. Dashboard shows sidebar + content area
8. Create an entity via the form — appears in list
9. Edit the entity — changes persist
10. Delete the entity — removed from list
11. Sign out works — redirects to login
12. .env.local is in .gitignore
13. AGENTS.md exists with correct content

If ANY check fails, fix it and re-verify. Do not declare done until all checks pass.

Vite + React Variant

Only use this section if the user explicitly requests React+Vite instead of Next.js.

Key differences:

• Scaffold: npm create vite@latest <name> -- --template react-ts
• Routing: npm install react-router-dom with <BrowserRouter> + <Routes>
• No server components — everything is client-side
• Supabase client: single createClient() (no SSR variant)
• No middleware — auth checks in route guards
• No route groups — use pages/ directory convention
• Data fetching: TanStack Query only (no Server Actions)

File structure:

src/
├── pages/
│   ├── auth/
│   │   ├── Login.tsx
│   │   ├── Signup.tsx
│   │   └── ForgotPassword.tsx
│   ├── dashboard/
│   │   ├── Dashboard.tsx
│   │   ├── Settings.tsx
│   │   └── <Entity>.tsx
│   └── Landing.tsx
├── components/
│   ├── ui/          # shadcn/ui
│   ├── Layout.tsx
│   └── ProtectedRoute.tsx
├── hooks/
│   └── use-<entity>.ts
├── lib/
│   └── supabase.ts  # Single client
├── App.tsx           # Router setup
└── main.tsx

Everything else (shadcn/ui, TanStack Query, react-hook-form, Supabase patterns) stays the same.