@kolbo/kolbo-code-linux-arm64-musl 1.1.73 → 2.0.0

package/skills/fullstack-app/SKILL.md

@@ -0,0 +1,621 @@
+---
+name: fullstack-app
+description: "Use when a user wants to build a complete web application from scratch. Triggers: 'build me an app', 'create a SaaS', 'I need a web app', 'make me a dashboard', 'create a todo app', or any request to scaffold a fullstack project. Orchestrates the opinionated stack (Next.js 15 + Tailwind CSS + shadcn/ui + Supabase), page templates, data patterns, and generates AGENTS.md."
+---
+
+# Fullstack App Builder
+
+You are building a production-quality fullstack web application. Follow this skill exactly — do NOT offer alternatives, do NOT ask the user to choose between ORMs/state managers/CSS frameworks. There is ONE stack and ONE way to do things.
+
+## The Stack (non-negotiable)
+
+| Layer | Choice |
+|-------|--------|
+| Framework | Next.js 15 (App Router) |
+| Language | TypeScript (strict) |
+| Styling | Tailwind CSS |
+| Components | shadcn/ui (Radix + Tailwind) |
+| Backend | Supabase (Postgres + Auth + Storage + Realtime) |
+| Data fetching | TanStack Query (React Query) |
+| Forms | react-hook-form + zod |
+| Auth | @supabase/ssr |
+
+If the user explicitly requests React+Vite instead of Next.js, see the Vite Variant section at the bottom. Otherwise, default to Next.js without asking.
+
+---
+
+## 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
+
+```bash
+npx create-next-app@latest <app-name> --ts --tailwind --app --eslint --src-dir --import-alias "@/*"
+cd <app-name>
+```
+
+### Initialize shadcn/ui
+```bash
+npx shadcn@latest init
+```
+When prompted: New York style, Zinc base color, CSS variables YES.
+
+### Install base components (always needed)
+```bash
+npx shadcn@latest add button card input label form separator
+```
+
+### Install core packages
+```bash
+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
+```bash
+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`
+```typescript
+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`
+```typescript
+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`
+```typescript
+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:
+```bash
+npx shadcn@latest add card form input label button separator
+```
+
+#### `src/app/(auth)/layout.tsx`
+```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`
+```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="you@example.com" {...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`
+```typescript
+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:
+```bash
+npx shadcn@latest add sidebar navigation-menu avatar dropdown-menu sheet breadcrumb
+```
+
+#### `src/app/(dashboard)/layout.tsx`
+```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:
+```bash
+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)
+```typescript
+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
+
+```bash
+npx shadcn@latest add tabs switch
+```
+
+`src/app/(dashboard)/settings/page.tsx` — Tabs for Profile, Account, Notifications.
+
+### Landing Page
+
+```bash
+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`
+```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:
+
+```markdown
+# [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.