# 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