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