@baldurpan/create-ai-workflow 0.2.0

package/templates/standards/tooling/prisma.md

@@ -0,0 +1,152 @@
+# Prisma
+
+## Purpose
+
+Prisma is the ORM of choice for TypeScript backend work. It provides type-safe database access with generated types derived from the schema.
+
+## Key Principles
+
+- Schema is the source of truth — all types are generated from it
+- Use generated Prisma types directly — do not duplicate them as DTOs
+- Use `prisma.$transaction` for multi-step operations that must succeed or fail together
+- Validate external input before passing to Prisma
+
+## Schema Conventions
+
+```prisma
+// prisma/schema.prisma
+
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+model User {
+  id        String   @id @default(cuid())
+  email     String   @unique
+  name      String
+  role      Role     @default(MEMBER)
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+
+  invoices  Invoice[]
+
+  @@map("users")  // snake_case table name
+}
+
+model Invoice {
+  id        String        @id @default(cuid())
+  title     String
+  amount    Decimal       @db.Decimal(10, 2)
+  status    InvoiceStatus @default(DRAFT)
+  dueDate   DateTime
+  userId    String
+  user      User          @relation(fields: [userId], references: [id])
+  createdAt DateTime      @default(now())
+  updatedAt DateTime      @updatedAt
+
+  @@map("invoices")
+}
+
+enum Role {
+  ADMIN
+  MEMBER
+  VIEWER
+}
+
+enum InvoiceStatus {
+  DRAFT
+  OPEN
+  PAID
+  VOID
+}
+```
+
+## Conventions
+
+- Use `cuid()` or `uuid()` for IDs — not auto-increment integers (avoids enumeration)
+- Always include `createdAt` and `updatedAt` with `@default(now())` and `@updatedAt`
+- Use `@@map` to keep table names snake_case while model names are PascalCase
+- Use `Decimal` for monetary values — never `Float`
+
+## Client Singleton
+
+```ts
+// lib/db.ts
+import { PrismaClient } from "@prisma/client";
+
+const globalForPrisma = globalThis as unknown as { prisma: PrismaClient };
+
+export const db =
+  globalForPrisma.prisma ??
+  new PrismaClient({
+    log: process.env.NODE_ENV === "development" ? ["query", "error", "warn"] : ["error"],
+  });
+
+if (process.env.NODE_ENV !== "production") globalForPrisma.prisma = db;
+```
+
+## Using Generated Types
+
+```ts
+import type { Invoice, User, InvoiceStatus } from "@prisma/client";
+
+// Use Prisma's utility types for partial shapes
+import type { Prisma } from "@prisma/client";
+
+type InvoiceWithUser = Prisma.InvoiceGetPayload<{
+  include: { user: true };
+}>;
+```
+
+## Migrations
+
+```bash
+# Create a migration from schema changes
+pnpm prisma migrate dev --name add_invoice_notes
+
+# Apply migrations in production
+pnpm prisma migrate deploy
+
+# Reset development database
+pnpm prisma migrate reset
+
+# Regenerate the Prisma client after schema change
+pnpm prisma generate
+```
+
+## Transactions
+
+```ts
+const [user, invoice] = await db.$transaction([
+  db.user.create({ data: userData }),
+  db.invoice.create({ data: { ...invoiceData, userId: user.id } }),
+]);
+
+// For dependent operations
+await db.$transaction(async (tx) => {
+  const user = await tx.user.create({ data: userData });
+  const invoice = await tx.invoice.create({
+    data: { ...invoiceData, userId: user.id },
+  });
+  return { user, invoice };
+});
+```
+
+## DO NOT
+
+- Expose the Prisma client directly to API route handlers — wrap in a service layer
+- Use raw `$queryRaw` without parameterized inputs (SQL injection risk)
+- Store monetary values as `Float`
+- Duplicate Prisma types as hand-written DTOs
+
+## See Also
+
+- [`../typescript/validation.md`](../typescript/validation.md) — Zod alongside generated Prisma types
+- [`dates.md`](dates.md) — DateTime columns and timezone handling
+- [`../typescript/error-handling.md`](../typescript/error-handling.md) — wrapping database errors
+- [`../security/api-security.md`](../security/api-security.md) — SQL injection prevention

package/templates/standards/tooling/shadcn.md

@@ -0,0 +1,115 @@
+# shadcn/ui
+
+## Purpose
+
+shadcn/ui provides accessible, unstyled UI primitives built on Radix UI. Components are copied into your codebase — you own and modify them directly.
+
+## Key Properties
+
+- Built on Radix UI — keyboard navigation and ARIA patterns are correct by default
+- Styled with Tailwind CSS + CSS variables
+- Not a dependency — components live in your `src/components/ui/` directory
+- Fully customizable — modify any component without fighting against the library
+
+## Setup
+
+```bash
+pnpm dlx shadcn@latest init
+```
+
+This sets up:
+- `components.json` — config
+- `src/components/ui/` — where components are added
+- CSS variable theme in `globals.css`
+
+## Adding Components
+
+```bash
+pnpm dlx shadcn@latest add button
+pnpm dlx shadcn@latest add dialog
+pnpm dlx shadcn@latest add form
+pnpm dlx shadcn@latest add table
+```
+
+Components are added to `src/components/ui/`. They are yours to modify.
+
+## Customization
+
+### Via CSS Variables (Preferred)
+
+Edit the CSS variables in `globals.css`:
+
+```css
+@layer base {
+  :root {
+    --primary: 221.2 83.2% 53.3%;
+    --primary-foreground: 210 40% 98%;
+    --radius: 0.5rem;
+  }
+}
+```
+
+### Via Component Modification
+
+Fork the component directly in `src/components/ui/`. Changes survive upgrades because you own the file.
+
+## Usage with Forms
+
+shadcn/ui's `Form` component wraps React Hook Form:
+
+```tsx
+import { Form, FormField, FormItem, FormLabel, FormControl, FormMessage } from "~/components/ui/form";
+import { useForm } from "react-hook-form";
+import { zodResolver } from "@hookform/resolvers/zod";
+
+const form = useForm({
+  resolver: zodResolver(schema),
+});
+
+<Form {...form}>
+  <form onSubmit={form.handleSubmit(onSubmit)}>
+    <FormField
+      control={form.control}
+      name="title"
+      render={({ field }) => (
+        <FormItem>
+          <FormLabel>Title</FormLabel>
+          <FormControl>
+            <Input {...field} />
+          </FormControl>
+          <FormMessage />
+        </FormItem>
+      )}
+    />
+  </form>
+</Form>
+```
+
+## DO
+
+- Prefer shadcn/ui components over custom implementations for common UI patterns
+- Use CSS variable customization before forking a component
+- Keep `src/components/ui/` for shadcn components; use `src/shared/components/` for your own
+- Update components via `shadcn@latest add <component>` when you want upstream fixes (manual review required)
+
+## DO NOT
+
+- Install shadcn/ui as a package dependency — it is a code generator
+- Modify shadcn components inside `node_modules`
+- Build custom dialog, dropdown, or popover implementations when Radix primitives are available
+- Assume accessibility — review each component in context (color contrast, label associations)
+
+## When to Fork a Component
+
+Fork (copy and modify) when:
+- The component needs significant structural changes
+- You need different default props or variants permanently
+- The upstream component API doesn't fit your use case
+
+Do not fork to change only styles — use CSS variables instead.
+
+## See Also
+
+- [`tailwind.md`](tailwind.md) — utility classes and theming
+- [`../react/accessibility.md`](../react/accessibility.md) — why Radix primitives are preferred
+- [`../react/forms.md`](../react/forms.md) — shadcn/ui form components

package/templates/standards/tooling/tailwind.md

@@ -0,0 +1,135 @@
+# Tailwind CSS
+
+## Core Rules
+
+- Utility-first: use Tailwind classes, not custom CSS, by default
+- Use CSS variables for theming — not hardcoded color values
+- Minimize arbitrary values (`[value]` syntax)
+- Support dark mode via CSS variables and Tailwind's `dark:` variant
+
+## Setup (v4)
+
+```bash
+pnpm add tailwindcss @tailwindcss/vite
+```
+
+```ts
+// vite.config.ts
+import tailwindcss from "@tailwindcss/vite";
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+});
+```
+
+```css
+/* src/styles/globals.css */
+@import "tailwindcss";
+```
+
+## Theming with CSS Variables
+
+Define design tokens as CSS variables. Wire them into Tailwind:
+
+```css
+/* src/styles/globals.css */
+@import "tailwindcss";
+
+@theme {
+  --color-primary: oklch(55% 0.2 250);
+  --color-primary-foreground: oklch(98% 0.01 250);
+  --color-background: oklch(100% 0 0);
+  --color-foreground: oklch(10% 0 0);
+  --color-muted: oklch(95% 0 0);
+  --color-border: oklch(88% 0 0);
+  --radius: 0.5rem;
+}
+
+.dark {
+  --color-background: oklch(10% 0 0);
+  --color-foreground: oklch(98% 0 0);
+  --color-muted: oklch(18% 0 0);
+  --color-border: oklch(25% 0 0);
+}
+```
+
+Usage:
+
+```tsx
+<div className="bg-background text-foreground border-border" />
+```
+
+## DO
+
+- Use `cn()` (clsx + tailwind-merge) for conditional class merging
+- Define component variants with `cva` (class-variance-authority)
+- Use `text-foreground`, `bg-background` etc. for themeable values
+- Group Tailwind classes logically: layout → spacing → typography → color → state
+
+## DO NOT
+
+- Use arbitrary values for things that should be design tokens: `text-[#ff6b35]`
+- Use `@apply` extensively — defeats the purpose of utility-first
+- Write custom CSS for things Tailwind handles natively
+
+## `cn()` Helper
+
+```ts
+// src/shared/utils/cn.ts
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
+```
+
+```tsx
+<button className={cn("px-4 py-2 rounded", isActive && "bg-primary text-white")} />
+```
+
+## Component Variants with `cva`
+
+```tsx
+import { cva, type VariantProps } from "class-variance-authority";
+import { cn } from "~/shared/utils/cn";
+
+const buttonVariants = cva(
+  "inline-flex items-center justify-center rounded font-medium transition-colors",
+  {
+    variants: {
+      variant: {
+        default: "bg-primary text-primary-foreground hover:bg-primary/90",
+        outline: "border border-border bg-transparent hover:bg-muted",
+        ghost: "hover:bg-muted",
+      },
+      size: {
+        sm: "h-8 px-3 text-sm",
+        md: "h-10 px-4",
+        lg: "h-12 px-6 text-lg",
+      },
+    },
+    defaultVariants: { variant: "default", size: "md" },
+  },
+);
+
+interface ButtonProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {}
+
+export function Button({ className, variant, size, ...props }: ButtonProps) {
+  return <button className={cn(buttonVariants({ variant, size }), className)} {...props} />;
+}
+```
+
+## PRIORITY
+
+```
+Design tokens > Utility classes > Arbitrary values > Custom CSS
+```
+
+## See Also
+
+- [`shadcn.md`](shadcn.md) — Tailwind + Radix components
+- [`../react/accessibility.md`](../react/accessibility.md) — focus styles, contrast
+- [`../react/component-design.md`](../react/component-design.md) — `cn` and `cva` patterns

package/templates/standards/tooling/tanstack-query.md

@@ -0,0 +1,214 @@
+# TanStack Query
+
+The default solution for server state management. Replaces manual `useEffect` + `useState` data fetching entirely.
+
+## Core Rules
+
+- Use TanStack Query for any data that lives on the server — never duplicate it into local state
+- Define `queryOptions` once and share them between loaders, components, and prefetches
+- Use `useSuspenseQuery` when paired with route loaders or `<Suspense>` boundaries
+- Use plain `useQuery` only when you need to render before the data resolves
+- Invalidate queries on mutation success — don't manually update component state
+
+## Setup
+
+```tsx
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 60_000,        // data stays fresh for 60s by default
+      retry: 1,
+      refetchOnWindowFocus: false,
+    },
+  },
+});
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <QueryClientProvider client={queryClient}>
+      {children}
+    </QueryClientProvider>
+  );
+}
+```
+
+## Query Options Pattern
+
+Define query options as a function so the same definition works in loaders, components, and prefetches:
+
+```ts
+import { queryOptions } from "@tanstack/react-query";
+
+export function invoiceQueryOptions(id: string) {
+  return queryOptions({
+    queryKey: ["invoices", id],
+    queryFn: () => fetchInvoice(id),
+    staleTime: 30_000,
+  });
+}
+
+// Component (with route loader prefetching — see tanstack-router.md)
+const { data } = useSuspenseQuery(invoiceQueryOptions(invoiceId));
+
+// Loader prefetch
+loader: ({ context }) => context.queryClient.ensureQueryData(invoiceQueryOptions(id)),
+
+// Manual prefetch (e.g., on hover, outside a route)
+queryClient.prefetchQuery(invoiceQueryOptions(id));
+```
+
+This is the canonical pattern. Avoid defining query keys and functions inline at the call site.
+
+## Queries
+
+### Standard Query
+
+Use when the component needs to render before data is available (initial mount without prefetch):
+
+```ts
+const { data, isLoading, error } = useQuery({
+  queryKey: ["invoices", filters],
+  queryFn: () => fetchInvoices(filters),
+});
+
+if (error) return <ErrorState error={error} />;
+if (isLoading) return <LoadingState />;
+return <InvoiceTable invoices={data} />;
+```
+
+### Suspense Query
+
+Use when paired with a route loader or `<Suspense>` boundary. No `isLoading` / `error` checks — boundaries handle them:
+
+```ts
+const { data: invoices } = useSuspenseQuery(invoiceQueryOptions(filters));
+return <InvoiceTable invoices={invoices} />;
+```
+
+`<Suspense>` shows the fallback while loading. `<ErrorBoundary>` catches errors. See [`../react/error-boundaries.md`](../react/error-boundaries.md).
+
+### Infinite Query
+
+For cursor-paginated lists:
+
+```ts
+const { data, fetchNextPage, hasNextPage, isFetchingNextPage } = useInfiniteQuery({
+  queryKey: ["invoices", filters],
+  queryFn: ({ pageParam }) => fetchInvoices({ ...filters, cursor: pageParam }),
+  initialPageParam: undefined as string | undefined,
+  getNextPageParam: (lastPage) => lastPage.nextCursor ?? undefined,
+});
+
+// data.pages is an array of pages; flatten with .flatMap(page => page.items)
+```
+
+See [`../architecture/api-design.md`](../architecture/api-design.md) for cursor pagination conventions.
+
+## Mutations
+
+### Basic Mutation
+
+```ts
+const { mutate, isPending } = useMutation({
+  mutationFn: createInvoice,
+  onSuccess: (newInvoice) => {
+    queryClient.invalidateQueries({ queryKey: ["invoices"] });
+  },
+});
+```
+
+### Optimistic Updates
+
+```ts
+const { mutate } = useMutation({
+  mutationFn: createInvoice,
+  onMutate: async (newInvoice) => {
+    await queryClient.cancelQueries({ queryKey: ["invoices"] });
+    const previous = queryClient.getQueryData<Invoice[]>(["invoices"]);
+    queryClient.setQueryData<Invoice[]>(["invoices"], (old = []) => [
+      ...old,
+      { ...newInvoice, id: "temp", status: "draft" },
+    ]);
+    return { previous };
+  },
+  onError: (_, __, context) => {
+    queryClient.setQueryData(["invoices"], context?.previous);
+  },
+  onSettled: () => {
+    queryClient.invalidateQueries({ queryKey: ["invoices"] });
+  },
+});
+```
+
+## Query Key Conventions
+
+Use arrays. Nest from general to specific. Filters go in a final object so they participate in cache keying:
+
+```ts
+["invoices"]                          // all invoices (broad)
+["invoices", "123"]                   // single invoice
+["invoices", "123", "comments"]       // nested resource
+["invoices", { status: "open" }]      // filtered list
+["invoices", { status: "open", page: 2 }]
+```
+
+Centralize query keys in a `queryKeys` factory for invalidation precision:
+
+```ts
+export const invoiceKeys = {
+  all: ["invoices"] as const,
+  lists: () => [...invoiceKeys.all, "list"] as const,
+  list: (filters: InvoiceFilters) => [...invoiceKeys.lists(), filters] as const,
+  details: () => [...invoiceKeys.all, "detail"] as const,
+  detail: (id: string) => [...invoiceKeys.details(), id] as const,
+};
+
+// Invalidate all lists but keep individual details fresh
+queryClient.invalidateQueries({ queryKey: invoiceKeys.lists() });
+```
+
+## Invalidation Strategies
+
+| After… | Invalidate… |
+|---|---|
+| `create` | List queries (`invoiceKeys.lists()`) |
+| `update` (single resource) | The list **and** the specific detail (`invoiceKeys.detail(id)`) |
+| `delete` | The list; remove the detail from cache (`queryClient.removeQueries`) |
+| `bulk update` | The entire feature (`invoiceKeys.all`) |
+
+`invalidateQueries` marks queries as stale and triggers refetch if they're active. `removeQueries` evicts them entirely.
+
+## `staleTime` vs `gcTime`
+
+- **`staleTime`** — how long data is considered fresh; while fresh, no background refetch
+- **`gcTime`** (formerly `cacheTime`) — how long unused data is kept in memory after the last subscriber unmounts
+
+Sensible defaults:
+- List queries: `staleTime: 30_000`
+- Detail queries: `staleTime: 60_000`
+- Static reference data: `staleTime: Infinity` with explicit invalidation
+
+## DO NOT
+
+- Mix TanStack Query with manual `useEffect` fetch patterns
+- Store server state in Zustand or Context — the query cache is the store
+- Use TanStack Query for pure local UI state (modal open, selected tab without URL state)
+- Define query keys inline at each call site — use `queryOptions` or a key factory
+- Manually `setQueryData` for non-optimistic updates — invalidate instead
+
+## PRIORITY
+
+```
+queryOptions (shared definition) > Inline query at call site
+useSuspenseQuery + boundaries > useQuery + manual loading/error checks
+Invalidate on mutation > Manual cache updates
+```
+
+## See Also
+
+- [`tanstack-router.md`](tanstack-router.md) — loaders + `useSuspenseQuery` pattern
+- [`../react/state-management.md`](../react/state-management.md) — when to use TanStack Query vs other state
+- [`../react/error-boundaries.md`](../react/error-boundaries.md) — Suspense and ErrorBoundary pairing
+- [`../architecture/api-design.md`](../architecture/api-design.md) — pagination, error shape