Template
refactor: rebuild template — Tailwind v4, Docker self-hosting, passkey auth
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
This commit is contained in:
Florian Wilde
+46
-23
@@ -1,32 +1,55 @@
|
||||
---
|
||||
paths:
|
||||
- "src/app/api/**"
|
||||
- "src/lib/supabase*"
|
||||
- "supabase/**"
|
||||
- "src/lib/**"
|
||||
- "src/server/**"
|
||||
- "drizzle/**"
|
||||
- "prisma/**"
|
||||
---
|
||||
|
||||
# Backend Development Rules
|
||||
# Backend Rules
|
||||
|
||||
## Database (Supabase)
|
||||
- ALWAYS enable Row Level Security on every table
|
||||
- Create RLS policies for SELECT, INSERT, UPDATE, DELETE
|
||||
- Add indexes on columns used in WHERE, ORDER BY, and JOIN clauses
|
||||
- Use foreign keys with ON DELETE CASCADE where appropriate
|
||||
- Never skip RLS - security first
|
||||
## No preselected data layer
|
||||
|
||||
## API Routes
|
||||
- Validate all inputs using Zod schemas before processing
|
||||
- Always check authentication: verify user session exists
|
||||
- Return meaningful error messages with appropriate HTTP status codes
|
||||
- Use `.limit()` on all list queries
|
||||
This template ships **no** database, ORM or BaaS. `/architecture` picks one per
|
||||
project and records the choice in the spec's Technical Decisions table. Until that
|
||||
decision exists, do not install an ORM or write schema code.
|
||||
|
||||
## Query Patterns
|
||||
- Use Supabase joins instead of N+1 query loops
|
||||
- Use `unstable_cache` from Next.js for rarely-changing data
|
||||
- Always handle errors from Supabase responses
|
||||
Whatever is chosen must be self-hostable inside the Docker Compose stack —
|
||||
the deployment target is a plain server, not a managed platform.
|
||||
|
||||
## Security
|
||||
- Never hardcode secrets in source code
|
||||
- Use environment variables for all credentials
|
||||
- Validate and sanitize all user input
|
||||
- Use parameterized queries (Supabase handles this)
|
||||
## Route Handlers
|
||||
|
||||
- Validate every request body with a Zod schema before touching it. Reuse the
|
||||
schema the form already uses; never trust client-side validation alone.
|
||||
- Check authentication before doing any work — see `.claude/rules/security.md`
|
||||
- Return correct status codes: 400 validation, 401 unauthenticated,
|
||||
403 unauthorized, 404 missing, 409 conflict, 500 unexpected
|
||||
- Error responses carry a message safe to show a user. Log the detail server-side;
|
||||
never leak stack traces, SQL or internal IDs to the client.
|
||||
|
||||
## Data Access
|
||||
|
||||
- **Scope every query by the current user.** Ownership is checked in the query
|
||||
itself (`where userId = session.user.id`), not after fetching. A filter applied
|
||||
in application code after a broad read is a data leak waiting for a bug.
|
||||
- Index columns used in WHERE, ORDER BY and JOIN
|
||||
- Foreign keys with an explicit ON DELETE behaviour
|
||||
- Always paginate or `.limit()` list queries — no unbounded reads
|
||||
- Use joins instead of looping queries (N+1)
|
||||
- Only parameterized queries. Never build SQL through string concatenation.
|
||||
- Handle the error branch of every database call
|
||||
|
||||
## Migrations
|
||||
|
||||
- Schema changes go through checked-in migration files, never manual edits on a
|
||||
running database
|
||||
- Migrations must be reversible or explicitly documented as one-way
|
||||
- The deployment step runs pending migrations before the new container serves
|
||||
traffic — see `docs/DEPLOYMENT.md`
|
||||
|
||||
## Secrets
|
||||
|
||||
- Read configuration from `process.env`, never hardcode it
|
||||
- Every new variable goes into `.env.example` with a dummy value in the same commit
|
||||
- `NEXT_PUBLIC_` only for values that are safe in a browser bundle
|
||||
|
||||
+41
-21
@@ -6,29 +6,49 @@ paths:
|
||||
- "src/hooks/**"
|
||||
---
|
||||
|
||||
# Frontend Development Rules
|
||||
# Frontend Rules
|
||||
|
||||
## shadcn/ui First (MANDATORY)
|
||||
- Before creating ANY UI component, check if shadcn/ui has it: `ls src/components/ui/`
|
||||
- NEVER create custom implementations of: Button, Input, Select, Checkbox, Switch, Dialog, Modal, Alert, Toast, Table, Tabs, Card, Badge, Dropdown, Popover, Tooltip, Navigation, Sidebar, Breadcrumb
|
||||
- If a shadcn component is missing, install it: `npx shadcn@latest add <name> --yes`
|
||||
- Custom components are ONLY for business-specific compositions that internally use shadcn primitives
|
||||
## shadcn/ui first (mandatory)
|
||||
|
||||
## Import Pattern
|
||||
```tsx
|
||||
import { Button } from "@/components/ui/button"
|
||||
import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card"
|
||||
Pre-installed: `button`, `card`, `input`, `label`, `form`, `sonner`.
|
||||
|
||||
Before building any UI element, check `ls src/components/ui/`. If shadcn has the
|
||||
component and it is not installed yet, install it — do not hand-write it:
|
||||
|
||||
```bash
|
||||
npx shadcn@latest add dialog table tabs --yes
|
||||
```
|
||||
|
||||
## Component Standards
|
||||
- Use Tailwind CSS exclusively (no inline styles, no CSS modules)
|
||||
- All components must be responsive (mobile 375px, tablet 768px, desktop 1440px)
|
||||
- Implement loading states, error states, and empty states
|
||||
- Use semantic HTML and ARIA labels for accessibility
|
||||
- Keep components small and focused
|
||||
- Use TypeScript interfaces for all props
|
||||
Never write a custom Button, Input, Select, Checkbox, Switch, Dialog, Alert,
|
||||
Table, Tabs, Card, Badge, Dropdown, Popover, Tooltip, Sidebar or Breadcrumb.
|
||||
Custom components are only compositions of these primitives plus business logic.
|
||||
|
||||
## Auth Best Practices (Supabase)
|
||||
- Use `window.location.href` for post-login redirect (not `router.push`)
|
||||
- Always verify `data.session` exists before redirecting
|
||||
- Always reset loading state in all code paths (success, error, finally)
|
||||
## Tailwind v4
|
||||
|
||||
- **There is no `tailwind.config.ts`.** Theme tokens live in `src/app/globals.css`
|
||||
under `@theme inline`. Add a design token there, not in a config file.
|
||||
- Use semantic tokens (`bg-background`, `text-muted-foreground`, `border-border`),
|
||||
not raw palette values like `bg-slate-900` — otherwise dark mode breaks.
|
||||
- Tailwind classes only. No inline `style`, no CSS modules.
|
||||
|
||||
## Component Standards
|
||||
|
||||
- TypeScript interfaces for all props
|
||||
- Responsive at 375px / 768px / 1440px
|
||||
- Every data-driven component handles three states: loading, error, empty
|
||||
- Semantic HTML and ARIA labels; keyboard reachable
|
||||
- Server Components by default — add `'use client'` only when you need state,
|
||||
effects or browser APIs
|
||||
|
||||
## Feedback and Theming
|
||||
|
||||
- Toasts via `sonner`: `import { toast } from 'sonner'`. The `Toaster` is already
|
||||
mounted in `layout.tsx` — do not mount a second one.
|
||||
- Dark mode is class-based via next-themes; never read the theme during render in
|
||||
a way that differs between server and client (hydration mismatch)
|
||||
|
||||
## Forms
|
||||
|
||||
`react-hook-form` + `zod` through `@hookform/resolvers/zod`, using the shadcn
|
||||
`form` component. The Zod schema is the single source of truth — the same schema
|
||||
validates again on the server.
|
||||
|
||||
+54
-59
@@ -1,75 +1,70 @@
|
||||
# General Project Rules
|
||||
|
||||
## New Project Detection (MANDATORY)
|
||||
Before starting ANY work, check if the project has been initialized:
|
||||
1. Read `docs/PRD.md` - if it still contains placeholder text like "_Describe what you are building_", the project is NOT initialized
|
||||
2. Read `features/INDEX.md` - if the features table is empty, no features have been defined
|
||||
## Before any work: is the project initialized?
|
||||
|
||||
**If the project is not initialized:**
|
||||
- Do NOT write any code or create any components
|
||||
- Do NOT skip ahead to implementation
|
||||
- Instead, tell the user: "This project hasn't been set up yet. Let's start by defining what you want to build. Run `/init` with a description of your idea (e.g. `/init I want to build a task management app`)."
|
||||
- If the user already described their idea in the current message, run `/init` automatically with their description
|
||||
1. Read `docs/PRD.md` — placeholder text like "_Describe what you are building_" means **not** initialized
|
||||
2. Read `features/INDEX.md` — an empty feature table means no features defined
|
||||
|
||||
**If the project is initialized but the user requests a feature not yet in INDEX.md:**
|
||||
- Guide them to run `/write-spec` first to create the feature spec before any implementation
|
||||
**Not initialized:** do not write code or create components. Say:
|
||||
> "Dieses Projekt ist noch nicht aufgesetzt. Starte mit `/init` und beschreibe kurz deine Idee
|
||||
> (z. B. `/init Ich will eine Aufgabenverwaltung bauen`)."
|
||||
|
||||
If the user already described their idea in that same message, run `/init` with it directly.
|
||||
|
||||
**Initialized, but the requested feature is not in INDEX.md:** guide the user to `/write-spec` first.
|
||||
|
||||
## Feature Tracking
|
||||
- All features are tracked in `features/INDEX.md` - read it before starting any work
|
||||
- Feature specs live in `features/PROJ-X-feature-name.md`
|
||||
- Feature IDs are sequential: check INDEX.md for the next available number
|
||||
- One feature per spec file (Single Responsibility)
|
||||
- Never combine multiple independent functionalities in one spec
|
||||
|
||||
## Git Conventions
|
||||
- Commit format: `type(PROJ-X): description`
|
||||
- Types: feat, fix, refactor, test, docs, deploy, chore
|
||||
- Check existing features before creating new ones: `ls features/ | grep PROJ-`
|
||||
- Check existing components before building: `git ls-files src/components/`
|
||||
- Check existing APIs before building: `git ls-files src/app/api/`
|
||||
- `features/INDEX.md` is the index — read it before starting anything
|
||||
- Specs live in `features/PROJ-X-feature-name.md`, IDs are sequential
|
||||
- One feature per spec file. Never combine independent functionality.
|
||||
|
||||
## Human-in-the-Loop
|
||||
- Always ask for user approval before finalizing deliverables
|
||||
- Present options using clear choices rather than open-ended questions
|
||||
- Never proceed to the next workflow phase without user confirmation
|
||||
## Status Flow
|
||||
|
||||
## Status Updates (MANDATORY - Write-Then-Verify)
|
||||
After completing work on any feature, you MUST update tracking files. Follow this exact sequence:
|
||||
`Roadmap` → `Planned` → `Architected` → `In Progress` → `In Review` → `Approved` → `Deployed`
|
||||
|
||||
1. **Read** the feature spec (`features/PROJ-X-*.md`) and `features/INDEX.md` BEFORE editing
|
||||
2. **Write** your changes using the Edit tool — do NOT just describe what you would write
|
||||
3. **Re-read** the file AFTER editing to verify the changes are actually present
|
||||
4. **If changes are missing**, repeat step 2 — never claim updates were made without verifying
|
||||
| Status | Set by |
|
||||
|--------|--------|
|
||||
| Roadmap | `/init` — feature identified, no spec file yet |
|
||||
| Planned | `/write-spec` |
|
||||
| Architected | `/architecture` |
|
||||
| In Progress | `/frontend` or `/backend` |
|
||||
| In Review | `/qa` starts |
|
||||
| Approved | `/qa` passes with no Critical/High bugs |
|
||||
| Deployed | `/deploy` |
|
||||
|
||||
**What to update in the feature spec:**
|
||||
- Status field in the header (Planned → In Progress → In Review → Deployed)
|
||||
- Implementation notes: what was built, what changed, any deviations from the original spec
|
||||
- Bug fixes or design changes discovered during implementation
|
||||
## Status Updates (write, then verify)
|
||||
|
||||
**What to update in `features/INDEX.md`:**
|
||||
- Feature status column must match the feature spec header
|
||||
- Valid statuses: Roadmap → Planned → Architected → In Progress → In Review → Approved → Deployed
|
||||
- **Roadmap**: after `/init` — feature identified, no spec file yet
|
||||
- **Planned**: after `/write-spec`
|
||||
- **Architected**: after `/architecture`
|
||||
- **In Progress**: after `/frontend` or `/backend` starts
|
||||
- **In Review**: after `/qa` starts
|
||||
- **Approved**: after `/qa` passes (no critical/high bugs)
|
||||
- **Deployed**: after `/deploy`
|
||||
1. **Read** the spec and `features/INDEX.md` before editing
|
||||
2. **Write** with the Edit tool — describing the change in chat is not doing it
|
||||
3. **Re-read** the file afterwards to confirm the change landed
|
||||
4. If it did not land, repeat step 2
|
||||
|
||||
**NEVER do this:**
|
||||
- Do NOT say "I've updated the feature spec" without actually calling the Edit tool
|
||||
- Do NOT summarize changes in chat as a substitute for writing them to the file
|
||||
- Do NOT skip updates because "it's obvious" or "minor"
|
||||
Update in the spec: status header, implementation notes, deviations, bugs found.
|
||||
Update in `INDEX.md`: the status column must match the spec header.
|
||||
|
||||
Never claim a file was updated without having called Edit and verified the result.
|
||||
|
||||
## File Handling
|
||||
- ALWAYS read a file before modifying it - never assume contents from memory
|
||||
- After context compaction, re-read files before continuing work
|
||||
- When unsure about current project state, read `features/INDEX.md` first
|
||||
- Run `git diff` to verify what has already been changed in this session
|
||||
- Never guess at import paths, component names, or API routes - verify by reading
|
||||
|
||||
## Handoffs Between Skills
|
||||
- After completing a skill, suggest the next skill to the user
|
||||
- Format: "Next step: Run `/skillname` to [action]"
|
||||
- Handoffs are always user-initiated, never automatic
|
||||
- Read a file before modifying it — never work from memory
|
||||
- After context compaction, re-read before continuing
|
||||
- Verify import paths, component names and API routes by reading, never guess
|
||||
- `git diff` shows what this session already changed
|
||||
|
||||
## Git
|
||||
|
||||
- Commit format: `type(PROJ-X): description` (feat, fix, refactor, test, docs, deploy, chore)
|
||||
- Check what exists before building: `git ls-files src/components/`, `git ls-files src/app/api/`
|
||||
|
||||
## Human-in-the-Loop
|
||||
|
||||
- Ask for approval before finalizing a deliverable
|
||||
- Offer clear choices instead of open-ended questions
|
||||
- Never advance to the next phase without confirmation
|
||||
- End each skill with: "Nächster Schritt: `/skillname` — [Aktion]"
|
||||
|
||||
## Language
|
||||
|
||||
Specs, PRD and acceptance criteria are written in **German**. Code, comments,
|
||||
commit messages and these instructions stay **English**.
|
||||
|
||||
+60
-23
@@ -1,36 +1,73 @@
|
||||
---
|
||||
paths:
|
||||
- "src/app/api/**"
|
||||
- "src/lib/auth*"
|
||||
- "src/server/**"
|
||||
- ".env*"
|
||||
- "supabase/**"
|
||||
- "next.config.*"
|
||||
- "Dockerfile"
|
||||
- "compose.yaml"
|
||||
---
|
||||
|
||||
# Security Rules
|
||||
|
||||
## Secrets Management
|
||||
- NEVER commit secrets, API keys, or credentials to git
|
||||
- Use `.env.local` for local development (already in .gitignore)
|
||||
- Use `NEXT_PUBLIC_` prefix ONLY for values safe to expose in browser
|
||||
- Document all required env vars in `.env.local.example` with dummy values
|
||||
## Authentication: Better Auth with passkeys (mandatory)
|
||||
|
||||
## Input Validation
|
||||
- Validate ALL user input on the server side with Zod
|
||||
- Never trust client-side validation alone
|
||||
- Sanitize data before database insertion
|
||||
Whenever a project needs authentication, it uses **Better Auth** with the
|
||||
**passkey plugin**. Do not substitute another auth library, and do not build a
|
||||
custom session/credential layer.
|
||||
|
||||
## Authentication
|
||||
- Always verify authentication before processing API requests
|
||||
- Use Supabase RLS as a second line of defense
|
||||
- Implement rate limiting on authentication endpoints
|
||||
```bash
|
||||
npm install better-auth
|
||||
# passkey support ships as a Better Auth plugin — enable it in the auth config
|
||||
```
|
||||
|
||||
## Security Headers
|
||||
- X-Frame-Options: DENY
|
||||
- X-Content-Type-Options: nosniff
|
||||
- Referrer-Policy: origin-when-cross-origin
|
||||
- Strict-Transport-Security with includeSubDomains
|
||||
**Passkeys are the primary method.** The sign-in screen offers passkey first and
|
||||
presents it as the default path. A password flow is permitted only as a fallback
|
||||
for users whose device cannot do WebAuthn.
|
||||
|
||||
## Code Review Triggers
|
||||
- Any changes to RLS policies require explicit user approval
|
||||
- Any changes to authentication flow require explicit user approval
|
||||
- Any new environment variables must be documented in .env.local.example
|
||||
Requirements whenever auth is present:
|
||||
|
||||
- Passkey registration is offered during sign-up, not hidden in settings
|
||||
- Existing password users are prompted to add a passkey after signing in
|
||||
- The WebAuthn relying-party ID must match the deployment hostname. It is derived
|
||||
from `NEXT_PUBLIC_APP_URL` / `BETTER_AUTH_URL` — a mismatch makes every passkey
|
||||
fail verification, and it fails silently.
|
||||
- Passkeys require HTTPS in production (localhost is exempt). The reverse proxy
|
||||
terminates TLS — see `docs/DEPLOYMENT.md`.
|
||||
- If the password fallback exists: rate-limit it, never reveal whether an account
|
||||
exists, and store hashes only through Better Auth's own primitives
|
||||
|
||||
## Authorization
|
||||
|
||||
- Verify the session in every route handler before any work
|
||||
- Authorization is per resource, not per route: having a session does not mean
|
||||
owning the record. Scope the query by the session user.
|
||||
- Never trust an ID coming from the client as proof of ownership
|
||||
|
||||
## Secrets
|
||||
|
||||
- Never commit secrets. `.env` is gitignored; only `.env.example` is committed.
|
||||
- Every new variable is documented in `.env.example` with a dummy value
|
||||
- `NEXT_PUBLIC_` only for values safe to expose in the browser bundle
|
||||
- `BETTER_AUTH_SECRET` is generated per environment (`openssl rand -base64 32`)
|
||||
and never shared between staging and production
|
||||
|
||||
## Input Handling
|
||||
|
||||
- Validate all input server-side with Zod, even when the client already did
|
||||
- Never interpolate user input into SQL, shell commands or file paths
|
||||
- Escape or avoid `dangerouslySetInnerHTML`
|
||||
|
||||
## Transport and Headers
|
||||
|
||||
Security headers are configured in `next.config.ts`: `X-Frame-Options: DENY`,
|
||||
`X-Content-Type-Options: nosniff`, `Referrer-Policy: origin-when-cross-origin`,
|
||||
`Strict-Transport-Security`. Verify they survive the reverse proxy after deploying.
|
||||
|
||||
## Changes That Need Explicit User Approval
|
||||
|
||||
- Any change to the authentication flow
|
||||
- Weakening or removing the passkey requirement
|
||||
- Any change to authorization or ownership checks
|
||||
- New environment variables (must land in `.env.example` in the same commit)
|
||||
|
||||
Reference in New Issue
Block a user