# AI Coding Starter Kit

> Next.js template with an AI-driven development workflow. Skills cover Requirements,
> Architecture, Frontend, Backend, QA and Deployment. Every phase writes its result
> into the feature spec, so state lives in files rather than in the conversation.

## Tech Stack (binding for every new app)

| Layer | Choice | Notes |
|-------|--------|-------|
| Framework | Next.js 16, App Router | React 19, Server Components by default |
| Language | TypeScript, `strict` | `@/*` maps to `src/*` |
| Styling | Tailwind CSS v4 | CSS-first config in `src/app/globals.css`. **There is no `tailwind.config.ts`** — theme tokens live in `@theme inline`. |
| Components | shadcn/ui (`new-york`) | 6 pre-installed. Add more with `npx shadcn@latest add <name> --yes`. Never hand-write an equivalent. |
| Icons | lucide-react | |
| Forms | react-hook-form + Zod | Zod schema is the single source of truth for a form's validation |
| Notifications | sonner | Mounted in `layout.tsx`. The deprecated shadcn `toast` is deliberately absent. |
| Theming | next-themes | `attribute="class"`, dark mode via `.dark` |
| Auth | Better Auth + passkey plugin | Only when the project needs auth. Passkeys are the primary method — see `.claude/rules/security.md`. |
| Data layer | **decided per project** | The template ships none. `/architecture` picks and documents it. |
| Tests | Vitest (unit) + Playwright (E2E) | Vitest only scans `src/`, Playwright only `tests/` |
| Deployment | Docker Compose, self-hosted | App container only; TLS/routing via a reverse proxy on the host |

Deliberately **not** part of this template: Supabase, Vercel, any preselected ORM
or database. Do not reintroduce them without the user asking.

## Project Structure

```
src/
  app/              Pages and route handlers (App Router)
    api/health/     Liveness probe used by Docker + update script
  components/
    ui/             shadcn/ui — NEVER recreate these by hand
  hooks/            Custom React hooks
  lib/utils.ts      cn() helper
features/           One spec per feature: PROJ-X-name.md
  INDEX.md          Status of every feature — read this first
docs/
  PRD.md            Product Requirements Document
  DEPLOYMENT.md     Docker Compose operations
tests/              Playwright E2E specs
scripts/update.sh   Pull, rebuild, restart, roll back on failure
```

## Workflow

| Step | Command | Produces |
|------|---------|----------|
| 1 | `/init` | PRD + feature map (once per project) |
| 2 | `/write-spec` | Full spec for one feature |
| 3 | `/architecture` | Tech design inside the spec |
| 4 | `/frontend` | UI components |
| 5 | `/backend` | APIs, data layer, auth |
| 6 | `/qa` | Test results inside the spec |
| 7 | `/deploy` | Live Docker Compose stack |

`/refine PROJ-X` reopens an existing spec. `/help` reports where the project stands.

## Conventions

- **Feature IDs:** `PROJ-1`, `PROJ-2`, … sequential, tracked in `features/INDEX.md`
- **Commits:** `type(PROJ-X): description` — feat, fix, refactor, test, docs, deploy, chore
- **One feature per spec file** — never combine independent functionality
- **Spec language:** German (PRD, specs, acceptance criteria). Code, comments and
  skill instructions stay English.
- **Human-in-the-loop:** every skill ends with a user approval checkpoint
- **Tests:** unit tests co-located (`useThing.test.ts` beside `useThing.ts`), E2E in `tests/`

## Commands

```bash
npm run dev          # Dev server on :3000
npm run build        # Production build (standalone output)
npm run lint         # ESLint (flat config)
npm run typecheck    # tsc --noEmit
npm test             # Vitest
npm run test:e2e     # Playwright
npm run test:all     # Both
npm run docker:up    # Build and start the Compose stack
./scripts/update.sh  # Deploy latest commit on the server
```

## Product Context

@docs/PRD.md

## Feature Overview

@features/INDEX.md

<!-- BEGIN:nextjs-agent-rules -->

# This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.

This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.

<!-- END:nextjs-agent-rules -->