Template
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
115 lines
3.9 KiB
Markdown
115 lines
3.9 KiB
Markdown
# AI Coding Starter Kit
|
|
|
|
Next.js template with an AI-driven development workflow for [Claude Code](https://docs.anthropic.com/en/docs/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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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](docs/DEPLOYMENT.md).
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
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
|