Template
Florian Wilde
f432122abf
Security was one section among seven in the QA Engineer. That is structurally weak: the agent that wants to recommend "production ready: YES" also judged security, and as a subsection it competes for attention with acceptance criteria, regression and test authoring. The new agent: - has no Write/Edit tools, so "never fix what you find" is enforced by the tool list rather than by instruction — it cannot launder a finding into a patch - reports PASS / FAIL / UNVERIFIED, and UNVERIFIED must reach the spec; an audit that omits what it could not check reads as all-clear - audits against .claude/rules/security.md, the same standard the developer agents are held to, so every mandatory item gets a verdict - holds a veto: BLOCK stops /deploy regardless of functional test results /qa now runs both agents in parallel and keeps the verdicts separate. The QA Engineer is explicitly forbidden from speaking for security.
101 lines
4.5 KiB
Markdown
101 lines
4.5 KiB
Markdown
# 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 — runs the QA Engineer **and** the Security Auditor, which holds a veto |
|
|
| 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 -->
|