Florian Wilde
b0c4e9e9b9
Toolchain fixes (all previously broken): - npm run lint: next lint was removed in Next 16 -> eslint with flat config - .eslintrc.json was ignored by ESLint 9 -> eslint.config.mjs - npm test / test:e2e exited 1 with no tests -> passWithNoTests - Vitest scanned tests/ and would have run Playwright specs -> scoped to src/ - Playwright targeted Mobile Safari while docs installed only chromium - reuseExistingServer silently tested a foreign server on :3000 -> E2E_PORT - 11 high-severity vulns -> npm audit fix - deny rule Read(**/.env*) also blocked .env.example -> precise patterns Stack changes: - Tailwind v3 -> v4 (CSS-first, no tailwind.config.ts, tw-animate-css) - shadcn regenerated for v4; 33 components -> 6 core, bundled radix-ui - Supabase removed entirely; data layer is now chosen per project - Vercel removed; Docker Compose self-hosting with scripts/update.sh - Better Auth + passkey plugin as the binding auth standard - ThemeProvider and Sonner mounted; dark mode and toasts now actually work Workflow system: - Sub-agents wired: /frontend, /backend, /qa delegate to .claude/agents - Checklists folded into their SKILL.md; one file per skill - Rules rewritten: DB-agnostic backend, passkey security, v4 frontend - Spec language settled as German, skill instructions English
3.9 KiB
AI Coding Starter Kit
Next.js template with an AI-driven development workflow for Claude Code. Nine skills cover the path from idea to a running deployment; every phase writes its result into a feature spec, so the project state lives in files rather than in a chat log.
Quick start
git clone <repo-url> my-project
cd my-project
npm install
cp .env.example .env
npm run dev
Then open Claude Code and describe what you want to build:
/init Ich will eine Aufgabenverwaltung für kleine Teams bauen
/init interviews you one question at a time — always with a recommended answer you
just confirm or correct — and writes docs/PRD.md plus a prioritized feature map.
From there:
/write-spec PROJ-1 Spec: user stories, acceptance criteria, edge cases
/architecture PROJ-1 Tech design (no code, PM-readable)
/frontend PROJ-1 UI components
/backend PROJ-1 Route handlers, data, auth
/qa PROJ-1 Test against the criteria + security audit
/deploy PROJ-1 Docker Compose stack
/refine PROJ-X reopens a spec. /help tells you where you stand.
Handoffs are always user-initiated — no skill jumps ahead on its own.
Stack
Next.js 16 (App Router) · React 19 · TypeScript · Tailwind CSS v4 · shadcn/ui · react-hook-form + Zod · sonner · next-themes · Vitest + Playwright · Docker Compose
No database and no ORM ship with this template. /architecture picks one per
project — the only constraint is that it runs self-hosted in the Compose stack.
Authentication is fixed: Better Auth with the passkey plugin. Passkeys are the primary sign-in method; a password flow is only a fallback for devices that cannot do WebAuthn.
Six shadcn components are pre-installed (button, card, input, label, form,
sonner). Everything else is one command away:
npx shadcn@latest add dialog table tabs --yes
Tailwind v4 is CSS-first: there is no tailwind.config.ts. Theme tokens live in
src/app/globals.css under @theme inline.
How the workflow is wired
| Directory | Contents |
|---|---|
CLAUDE.md |
Loaded every session — stack, structure, conventions |
.claude/rules/ |
Applied automatically based on which files are being edited |
.claude/skills/ |
The nine /commands, one folder each |
.claude/agents/ |
Sub-agents for the implementation-heavy phases |
features/ |
INDEX.md plus one spec per feature |
docs/ |
PRD.md, DEPLOYMENT.md |
/frontend, /backend and /qa run the interview and the review with you in the
main conversation, then hand the heavy file work to their sub-agent. The sub-agent
reports back; the skill keeps ownership of the spec and status updates.
State is deliberately file-based: if the context is compacted mid-task, the skill
re-reads the spec and git diff, and continues without redoing work.
Deployment
Self-hosted Docker Compose. The stack publishes the app on loopback; a reverse proxy on the host terminates TLS.
docker compose up -d --build # first start
./scripts/update.sh # deploy the latest commit
update.sh pulls, rebuilds, restarts and waits for the healthcheck — and rolls back
to the previous commit if the new container never turns healthy.
Details in docs/DEPLOYMENT.md.
Commands
npm run dev # Dev server on :3000
npm run build # Production build (standalone output)
npm run lint # ESLint
npm run typecheck # tsc --noEmit
npm test # Vitest — unit tests, co-located in src/
npm run test:e2e # Playwright — E2E specs in tests/
npm run test:all # Both
Playwright needs its browser once per machine: npx playwright install chromium
Customizing
CLAUDE.md for stack and conventions · .claude/rules/ for coding standards ·
.claude/skills/ for the workflow itself · .claude/settings.json for permissions.
License
MIT