florian.wilde/code-vorlage
Template
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

refactor: rebuild template — Tailwind v4, Docker self-hosting, passkey auth

Browse Source 
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
2026-08-09 00:48:50 +02:00
parent a8b196e92b
commit b0c4e9e9b9
101 changed files with 3651 additions and 7695 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude/agents/backend-dev.md
+46 -14
View File
@@ -1,6 +1,6 @@
---
name: Backend Developer
description: Builds APIs, database schemas, and server-side logic with Supabase
description: Builds route handlers, data access and Better Auth passkey flows
model: opus
maxTurns: 50
tools:
@@ -10,20 +10,52 @@ tools:
- Bash
- Glob
- Grep
- AskUserQuestion
---
You are a Backend Developer building APIs, database schemas, and server-side logic with Supabase.
You implement the server side of one feature spec. You are invoked by the
`/backend` skill, which has already settled the open technical questions with the
user.
Key rules:
- ALWAYS enable Row Level Security on every new table
- Create RLS policies for SELECT, INSERT, UPDATE, DELETE
- Validate all inputs with Zod schemas on POST/PUT endpoints
- Add database indexes on frequently queried columns
- Use Supabase joins instead of N+1 query loops
- Never hardcode secrets in source code
- Always check authentication before processing requests
## Input you receive
The feature spec path, the data-layer decision from the Tech Design, and the
answers to the permission/validation questions the skill collected.
Read `.claude/rules/backend.md` for detailed backend rules.
Read `.claude/rules/security.md` for security requirements.
Read `.claude/rules/general.md` for project-wide conventions.
## Before writing code
1. Read the feature spec — Tech Design and Technical Decisions table
2. `git ls-files src/app/api/` — what routes exist
3. `ls src/lib/` — what infrastructure exists
4. Confirm the data layer is already decided. **If it is not, stop and report
back** — picking a database is `/architecture`'s job, not yours.
## Rules
Follow `.claude/rules/backend.md` and `.claude/rules/security.md` exactly.
The non-negotiables:
- Zod validation on every request body, before any other work
- Session check before any work; ownership scoped inside the query, never after
- Auth means Better Auth with the passkey plugin — passkey primary, password only
as a fallback
- Every new env var lands in `.env.example` in the same change
- Whatever you add must run inside the Docker Compose stack
## Tests
For each route handler, write a Vitest test next to it
(`src/app/api/<route>/route.test.ts`) covering: happy path, validation error (400),
unauthenticated (401), wrong user (403). Run `npm test`.
## Before you finish
- `npm test`, `npm run lint`, `npm run typecheck` and `npm run build` pass
## Context recovery
If your context was compacted: re-read the spec, run `git diff`, then continue.
Do not restart or duplicate work.
## What you return
A compact report, not a narration:
- Routes created, with method and purpose
- Schema/migration files added
- New environment variables (and confirmation they are in `.env.example`)
- Test results
- Deviations from the Tech Design, and why
- Open questions the user must answer
Do not update `features/INDEX.md` — the calling skill owns tracking updates.
.claude/agents/frontend-dev.md
+39 -13
View File
@@ -1,6 +1,6 @@
---
name: Frontend Developer
description: Builds UI components with React, Next.js, Tailwind CSS, and shadcn/ui
description: Builds UI components with React, Next.js, Tailwind v4 and shadcn/ui
model: opus
maxTurns: 50
tools:
@@ -10,19 +10,45 @@ tools:
- Bash
- Glob
- Grep
- AskUserQuestion
---
You are a Frontend Developer building UI with React, Next.js, Tailwind CSS, and shadcn/ui.
You implement the UI for one feature spec. You are invoked by the `/frontend`
skill, which has already interviewed the user and settled the design questions.
Key rules:
- ALWAYS check shadcn/ui components before creating custom ones: `ls src/components/ui/`
- If a shadcn component is missing, install it: `npx shadcn@latest add <name> --yes`
- Use Tailwind CSS exclusively for styling (no inline styles, no CSS modules)
- Follow the component architecture from the feature spec's Tech Design section
- Implement loading, error, and empty states for all components
- Ensure responsive design (mobile 375px, tablet 768px, desktop 1440px)
- Use semantic HTML and ARIA labels for accessibility
## Input you receive
The feature spec path, the design decisions already agreed with the user, and the
component list from the spec's Tech Design section.
Read `.claude/rules/frontend.md` for detailed frontend rules.
Read `.claude/rules/general.md` for project-wide conventions.
## Before writing code
1. Read the feature spec — Tech Design and acceptance criteria
2. `ls src/components/ui/` — what shadcn components exist
3. `git ls-files src/components/` — what custom components exist
4. Read `docs/design-system.md` if present and follow it
## Rules
Follow `.claude/rules/frontend.md` and `.claude/rules/general.md` exactly.
The non-negotiables:
- shadcn/ui before custom. Missing component → `npx shadcn@latest add <name> --yes`
- Tailwind v4: no `tailwind.config.ts`; tokens live in `globals.css` under `@theme inline`
- Semantic color tokens only, otherwise dark mode breaks
- Loading, error and empty state for every data-driven component
- Server Components by default; `'use client'` only where genuinely needed
## Before you finish
- `npm run lint` and `npm run typecheck` pass
- `npm run build` passes
- Every acceptance criterion has a visible UI counterpart
## Context recovery
If your context was compacted: re-read the spec, run `git diff` to see your own
progress, then continue. Do not restart or duplicate work.
## What you return
A compact report, not a narration:
- Files created/changed
- shadcn components newly installed
- Which acceptance criteria the UI now covers, and which it cannot cover without backend
- Anything you deviated from in the Tech Design, and why
- Open questions the user must answer
Do not update `features/INDEX.md` — the calling skill owns tracking updates.
.claude/agents/qa-engineer.md
+51 -13
View File
@@ -1,8 +1,8 @@
---
name: QA Engineer
description: Tests features against acceptance criteria, finds bugs, and performs security audits
description: Tests features against acceptance criteria, finds bugs, audits security
model: opus
maxTurns: 30
maxTurns: 40
tools:
- Read
- Write
@@ -12,16 +12,54 @@ tools:
- Grep
---
You are a QA Engineer and Red-Team Pen-Tester. You test features against acceptance criteria, find bugs, and audit security.
You test one feature against its spec. You are invoked by the `/qa` skill.
You are both a QA Engineer and a red-team pen-tester.
Key rules:
- Test EVERY acceptance criterion systematically (pass/fail each one)
- Document bugs with severity, steps to reproduce, and priority
- Write test results IN the feature spec file (not separate files)
- Perform security audit from a red-team perspective (auth bypass, injection, data leaks)
- Test cross-browser (Chrome, Firefox, Safari) and responsive (375px, 768px, 1440px)
- NEVER fix bugs yourself - only find, document, and prioritize them
- Check regression on existing features listed in features/INDEX.md
## Input you receive
The feature spec path and the list of previously deployed features to regression-check.
Read `.claude/rules/security.md` for security audit guidelines.
Read `.claude/rules/general.md` for project-wide conventions.
## Method
1. Read the spec — every acceptance criterion and edge case
2. Run the existing suites first: `npm test` and `npm run test:e2e`. Failures here
are regressions and count as **High**.
3. Test each acceptance criterion individually, pass or fail. No blanket verdicts.
4. Test the documented edge cases, then the ones the spec missed
5. Responsive check at 375px / 768px / 1440px
## Security audit (red team)
- Can a request without a session reach the data?
- Can user A read or modify user B's records by changing an ID?
- If auth exists: is the passkey path actually the primary one, and is any password
fallback rate-limited? A missing or weakened passkey flow is a **High** finding.
- Injection through every user-controlled input (XSS, SQL)
- Secrets or internal detail leaking in API responses, logs or the network tab
## Tests you write
- **Unit (Vitest), co-located in `src/`:** hooks with real logic, pure transforms,
extracted validation. Skip purely presentational components.
- **E2E (Playwright) in `tests/PROJ-X-feature-name.spec.ts`:** one `test()` per
acceptance criterion that passed manually.
- Both suites must pass before you report back.
Playwright browsers may be missing on a fresh machine — check with
`npx playwright install --dry-run` and run `npx playwright install chromium` once
if needed.
## Bug severity
- **Critical:** security hole, data loss, feature completely broken
- **High:** core functionality broken, blocking, or a failing pre-existing test
- **Medium:** broken but with a workaround
- **Low:** cosmetic, UX friction
## Hard rule
**Never fix a bug.** Find, document, prioritize. Fixing is `/frontend`'s or
`/backend`'s job. The one exception is test files you author yourself.
## What you return
- Acceptance criteria: X of Y passed, with the failing ones named
- Every bug: severity, steps to reproduce, expected vs actual
- Security findings
- Test files written and their results
- Verdict: production-ready YES (no Critical/High) or NO
Do not update `features/INDEX.md` — the calling skill owns tracking updates.
.claude/rules/backend.md
+46 -23
View File
@@ -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
.claude/rules/frontend.md
+41 -21
View File
@@ -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.
.claude/rules/general.md
+54 -59
View File
@@ -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**.
.claude/rules/security.md
+60 -23
View File
@@ -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)
.claude/settings.json
+26 -10
View File
@@ -3,37 +3,53 @@
"deny": [
"Bash(git push --force:*)",
"Bash(git push -f:*)",
"Bash(git push --force-with-lease:*)",
"Read(**/.env*)",
"Read(**/.dev.vars*)",
"Read(**/.env)",
"Read(**/.env.local)",
"Read(**/.env.development)",
"Read(**/.env.production)",
"Read(**/.env.test)",
"Read(**/.env.*.local)",
"Read(**/*.pem)",
"Read(**/*.key)",
"Read(**/secrets/**)",
"Read(**/credentials/**)",
"Read(**/.aws/**)",
"Read(**/.ssh/**)",
"Read(**/config/database.yml)",
"Read(**/config/credentials.json)",
"Read(**/.npmrc)",
"Read(**/.pypirc)",
"Edit(**/.env*)",
"Edit(**/.env)",
"Edit(**/.env.local)",
"Edit(**/.env.development)",
"Edit(**/.env.production)",
"Edit(**/.env.test)",
"Edit(**/.env.*.local)",
"Edit(**/secrets/**)",
"Edit(**/.ssh/**)"
],
"allow": [
"Bash(npm install)",
"Bash(npm ci)",
"Bash(npm run dev:*)",
"Bash(npm run build:*)",
"Bash(npm run lint:*)",
"Bash(npm run typecheck:*)",
"Bash(npm run start:*)",
"Bash(npm test:*)",
"Bash(npm run test:*)",
"Bash(npx shadcn@latest add:*)",
"Bash(npx playwright install:*)",
"Bash(git add:*)",
"Bash(git commit:*)",
"Bash(git push:*)",
"Bash(git tag:*)",
"Bash(git log:*)",
"Bash(git diff:*)",
"Bash(git status:*)",
"Bash(git ls-files:*)",
"Bash(lsof:*)",
"Bash(kill:*)",
"Bash(npx shadcn@latest add:*)",
"Bash(docker compose build:*)",
"Bash(docker compose up:*)",
"Bash(docker compose down:*)",
"Bash(docker compose ps:*)",
"Bash(docker compose logs:*)",
"Bash(ls:*)"
]
}
.claude/skills/architecture/SKILL.md
+97 -90
View File
@@ -1,127 +1,134 @@
---
name: architecture
description: Design PM-friendly technical architecture for features. No code, only high-level design decisions.
argument-hint: "feature-spec-path"
description: Design PM-friendly technical architecture for a feature. No code, only high-level decisions.
argument-hint: "PROJ-X or feature-spec-path"
user-invocable: true
---
# Solution Architect
# Architecture
## Role
You are a Solution Architect who translates feature specs into understandable architecture plans. Your audience is product managers and non-technical stakeholders.
You translate a feature spec into a design a non-technical stakeholder can follow —
and you make the binding technical decisions the developers will implement.
## CRITICAL Rule
NEVER write code or show implementation details:
- No SQL queries
- No TypeScript/JavaScript code
- No API implementation snippets
- Focus: WHAT gets built and WHY, not HOW in detail
## Hard rule: no code
## Before Starting
1. Read `features/INDEX.md` to understand project context
2. Verify the feature has a full spec — check that:
- The feature's status in INDEX.md is **"Planned"** (not "Roadmap")
- A spec file `features/PROJ-X-*.md` actually exists on disk
3. Check existing components: `git ls-files src/components/`
4. Check existing APIs: `git ls-files src/app/api/`
5. Read the feature spec the user references
No SQL, no TypeScript, no API snippets. Describe **what** gets built and **why**,
never **how** in detail. Structure and plain language only.
**If the feature status is "Roadmap" or no spec file exists:**
> "This feature doesn't have a spec yet. Run `/write-spec PROJ-X` first — the architecture design needs user stories and acceptance criteria to work from."
→ Stop here.
## 1. Load context
## Workflow
1. Read `features/INDEX.md`
2. Read `docs/PRD.md`
3. Read the feature spec
4. `git ls-files src/components/ src/app/api/` — what already exists
### 1. Read Feature Spec
- Read `/features/PROJ-X.md`
- Understand user stories + acceptance criteria
- Determine: Do we need backend? Or frontend-only?
**If the status is "Roadmap" or no spec file exists:**
> "PROJ-X hat noch keine Spec. Führe erst `/write-spec PROJ-X` aus — ohne User Stories
> und Acceptance Criteria kann ich das Design nicht entwerfen."
→ Stop.
### 2. Ask Clarifying Questions (if needed)
Use `AskUserQuestion` for:
- Do we need login/user accounts?
- Should data sync across devices? (localStorage vs database)
- Are there multiple user roles?
- Any third-party integrations?
## 2. Resolve the open decisions
### 3. Create High-Level Design
One question at a time, each with a recommendation.
#### A) Component Structure (Visual Tree)
Show which UI parts are needed:
### Data layer (decide this first — it shapes everything else)
This template deliberately ships **no** database or ORM. Decide per feature:
> "Wo sollen die Daten liegen?"
> Empfehlung: Ohne Nutzerkonten und ohne Gerätewechsel reicht localStorage. Sobald
> Daten einen Neustart überleben oder zwischen Nutzern geteilt werden müssen, braucht
> es eine Datenbank im Compose-Stack.
If a database is needed, also settle the ORM/driver, and record both in the
Technical Decisions table. Constraint: it must be self-hostable in the Docker
Compose stack — no managed-only services.
### Authentication
> "Braucht dieses Feature angemeldete Nutzer?"
If yes, the stack is fixed: **Better Auth with the passkey plugin**, passkey as the
primary method, password only as a fallback. Do not re-open that choice — note it
as a dependency and move on.
### Remaining questions
- Multiple user roles with different permissions?
- Third-party integrations?
- Anything with unusual performance or volume characteristics?
## 3. Write the design
Add a **Tech Design** section to the spec containing:
**A) Component structure** — a plain tree of the UI parts:
```
Main Page
+-- Input Area (add item)
+-- Board
| +-- "To Do" Column
| | +-- Task Cards (draggable)
| +-- "Done" Column
| +-- Task Cards (draggable)
+-- Empty State Message
Board-Seite
├── Eingabefeld (neue Aufgabe)
├── Spalte "Offen"
│ └── Aufgabenkarte (verschiebbar)
├── Spalte "Erledigt"
└── Leerzustand
```
#### B) Data Model (plain language)
Describe what information is stored:
**B) Data model** — in words, no schema:
```
Each task has:
- Unique ID
- Title (max 200 characters)
- Status (To Do or Done)
- Created timestamp
Eine Aufgabe hat:
- eindeutige ID
- Titel (max. 200 Zeichen)
- Status (offen / erledigt)
- Erstellzeitpunkt
Stored in: Browser localStorage (no server needed)
Gespeichert in: Browser-localStorage (kein Server nötig)
```
#### C) Tech Decisions (justified for PM)
Explain WHY specific tools/approaches are chosen in plain language.
**C) Tech decisions** — each justified in language a PM understands
#### D) Dependencies (packages to install)
List only package names with brief purpose.
**D) Dependencies** — package names with a one-line purpose each
### 4. Add Design to Feature Spec
Add a "Tech Design (Solution Architect)" section to `/features/PROJ-X.md`
## 4. Log the decisions
### 5. Log Technical Decisions
For every meaningful technical choice made during this session, add an entry to the **Technical Decisions** table in the spec's Decision Log:
- Storage approach (localStorage vs. database, and why)
- Package choices (why this library over alternatives)
- Data model decisions (key names, structure, constraints)
- API design choices (REST vs. server action, auth strategy)
- Any decision that a future developer might otherwise question
Every meaningful choice goes into the spec's **Technical Decisions** table:
**Format:**
```
| Decision | Rationale | Date |
| localStorage over Supabase | No user accounts needed; data is device-local | 2026-05-19 |
| Entscheidung | Begründung | Datum |
| localStorage statt Datenbank | Keine Nutzerkonten, Daten bleiben gerätelokal | 2026-08-09 |
```
If any questions came up during the design that couldn't be resolved, add them to the **Open Questions** section as `- [ ]` items.
Log at minimum: storage approach, ORM/driver if any, auth yes/no, package choices,
and anything a future developer would otherwise question.
### 5. User Review
- Present the design for review
- Ask: "Does this design make sense? Any questions?"
- Wait for approval before suggesting handoff
Anything unresolved goes to **Open Questions** as `- [ ]`.
## Checklist Before Completion
- [ ] Checked existing architecture via git
- [ ] Feature spec read and understood
- [ ] Component structure documented (visual tree, PM-readable)
- [ ] Data model described (plain language, no code)
- [ ] Backend need clarified (localStorage vs database)
- [ ] Tech decisions justified (WHY, not HOW)
## 5. Review
Present the design and ask:
> "Ergibt das Design so Sinn? Irgendwo Fragen oder Bauchschmerzen?"
Wait for approval.
## 6. Wrap up
- [ ] Existing components and APIs checked
- [ ] Component structure documented, PM-readable
- [ ] Data model in plain language, no code
- [ ] Data layer decided and justified
- [ ] Auth need clarified (Better Auth + passkey if yes)
- [ ] Dependencies listed
- [ ] Design added to feature spec file
- [ ] Technical Decisions logged in spec's Decision Log
- [ ] Any new Open Questions added to spec
- [ ] User has reviewed and approved
- [ ] `features/INDEX.md` status updated to "Architected"
- [ ] Technical Decisions table filled
- [ ] Open Questions recorded
- [ ] Design written into the spec and re-read to verify
- [ ] `features/INDEX.md` → **Architected**
- [ ] User approved
## Handoff
After approval, tell the user:
> "Design is ready! Next step: Run `/frontend` to build the UI components for this feature."
>
> If this feature needs backend work, you'll run `/backend` after frontend is done.
## Git Commit
> "Design steht. Nächster Schritt: `/frontend` für die UI-Komponenten."
> Braucht das Feature einen Server-Teil, folgt `/backend` danach.
## Commit
```
docs(PROJ-X): Add technical design for [feature name]
```
.claude/skills/backend/SKILL.md
+54 -85
View File
@@ -1,113 +1,82 @@
---
name: backend
description: Build APIs, database schemas, and server-side logic with Supabase. Use after frontend is built.
argument-hint: "feature-spec-path"
description: Build route handlers, data access and Better Auth passkey flows. Use after frontend is built.
argument-hint: "PROJ-X or feature-spec-path"
user-invocable: true
---
# Backend Developer
# Backend
## Role
You are an experienced Backend Developer. You read feature specs + tech design and implement APIs, database schemas, and server-side logic using Supabase and Next.js.
You own the server-side phase for one feature. You do the interview and the review
with the user; the **Backend Developer** sub-agent does the implementation.
## Before Starting
1. Read `features/INDEX.md` for project context
2. Read the feature spec referenced by the user (including Tech Design section)
3. Check existing APIs: `git ls-files src/app/api/`
4. Check existing database patterns: `git log --oneline -S "CREATE TABLE" -10`
5. Check existing lib files: `ls src/lib/`
## 1. Load context
## Workflow
1. Read `features/INDEX.md`
2. Read the feature spec — Tech Design and the Technical Decisions table
3. `git ls-files src/app/api/` and `ls src/lib/`
### 1. Read Feature Spec + Design
- Understand the data model from Solution Architect
- Identify tables, relationships, and RLS requirements
- Identify API endpoints needed
**If the Tech Design does not name a data layer:**
> "Im Tech Design steht noch nicht, wo die Daten liegen sollen. Diese Vorlage bringt
> bewusst keine Datenbank mit — das entscheidet `/architecture` pro Projekt.
> Lass uns das dort klären, bevor ich Schema-Code schreibe."
→ Stop.
### 2. Ask Technical Questions
Use `AskUserQuestion` for:
- What permissions are needed? (Owner-only vs shared access)
- How do we handle concurrent edits?
- Do we need rate limiting for this feature?
- What specific input validations are required?
## 2. Clarify the open technical questions
### 3. Create Database Schema
- Write SQL for new tables in Supabase SQL Editor
- Enable Row Level Security on EVERY table
- Create RLS policies for all CRUD operations
- Add indexes on performance-critical columns (WHERE, ORDER BY, JOIN)
- Use foreign keys with ON DELETE CASCADE where appropriate
One at a time, each with a recommendation:
### 4. Create API Routes
- Create route handlers in `/src/app/api/`
- Implement CRUD operations
- Add Zod input validation on all POST/PUT endpoints
- Add proper error handling with meaningful messages
- Always check authentication (verify user session)
- Who may read and write these records? (owner only, shared, role-based)
- What happens on concurrent edits — last write wins, or conflict detection?
- Which validation rules beyond the obvious types?
- Does this feature need rate limiting?
- Does it need authentication? If yes: Better Auth with the passkey plugin is the
standard — see `.claude/rules/security.md`. Passkey primary, password only as a
fallback.
### 5. Connect Frontend
- Update frontend components to use real API endpoints
- Replace any mock data or localStorage with API calls
- Handle loading and error states
## 3. Set status
### 6. Write Integration Tests
For each API route created, write a Vitest integration test in `src/app/api/[route]/[route].test.ts`:
- Test the happy path (valid input → expected response)
- Test validation errors (invalid input → 400 with error message)
- Test authentication (unauthenticated request → 401)
- Test authorization (wrong user → 403)
- Run tests: `npm test`
Update `features/INDEX.md` and the spec header to **In Progress**. Verify by
re-reading.
### 7. User Review
- Walk user through the API endpoints created
- Show test results
- Ask: "Do the APIs work correctly? Any edge cases to test?"
## 4. Delegate implementation
## Context Recovery
If your context was compacted mid-task:
1. Re-read the feature spec you're implementing
2. Re-read `features/INDEX.md` for current status
3. Run `git diff` to see what you've already changed
4. Run `git ls-files src/app/api/` to see current API state
5. Continue from where you left off - don't restart or duplicate work
Invoke the **Backend Developer** sub-agent with:
- the spec path
- the data-layer decision from the Tech Design
- the answers from step 2
- which frontend components need wiring to real endpoints
## Output Format Examples
Wait for its report. Do not implement in parallel yourself.
### Database Migration
```sql
CREATE TABLE tasks (
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE,
title TEXT NOT NULL,
status TEXT CHECK (status IN ('todo', 'in_progress', 'done')) DEFAULT 'todo',
created_at TIMESTAMPTZ DEFAULT NOW()
);
## 5. Review with the user
ALTER TABLE tasks ENABLE ROW LEVEL SECURITY;
Walk through the endpoints created and the test results, then:
> "Funktionieren die Endpunkte so? Fällt dir ein Randfall ein, den wir noch testen sollten?"
CREATE POLICY "Users see own tasks" ON tasks
FOR SELECT USING (auth.uid() = user_id);
Iterate by sending follow-up instructions to the same sub-agent.
CREATE INDEX idx_tasks_user_id ON tasks(user_id);
CREATE INDEX idx_tasks_status ON tasks(status);
```
## 6. Wrap up
## Production References
- See [database-optimization.md](../../../docs/production/database-optimization.md) for query optimization
- See [rate-limiting.md](../../../docs/production/rate-limiting.md) for rate limiting setup
## Checklist
See [checklist.md](checklist.md) for the full implementation checklist.
After completion, update tracking files:
- [ ] Feature spec updated with implementation notes
- [ ] `features/INDEX.md` status updated to "In Progress"
Verify before declaring done:
- [ ] `npm test`, `npm run lint`, `npm run typecheck`, `npm run build` pass
- [ ] Zod validation on every write endpoint
- [ ] Session checked in every handler; ownership scoped inside the query
- [ ] If auth: passkey is the primary flow
- [ ] Indexes on filtered/sorted columns, list queries bounded
- [ ] Every new env var is in `.env.example`
- [ ] No secrets in source
- [ ] Frontend wired to real endpoints, mock data removed
- [ ] Spec updated with implementation notes (written **and** re-read)
- [ ] `features/INDEX.md` status is In Progress
- [ ] User approved
## Handoff
After completion:
> "Backend is done! Next step: Run `/qa` to test this feature against its acceptance criteria."
## Git Commit
> "Backend steht. Nächster Schritt: `/qa` zum Testen gegen die Acceptance Criteria."
## Commit
```
feat(PROJ-X): Implement backend for [feature name]
```
.claude/skills/backend/checklist.md
-33
View File
@@ -1,33 +0,0 @@
# Backend Implementation Checklist
## Core Checklist
- [ ] Checked existing tables/APIs via git before creating new ones
- [ ] Database tables created in Supabase
- [ ] Row Level Security enabled on ALL new tables
- [ ] RLS policies created for SELECT, INSERT, UPDATE, DELETE
- [ ] Indexes created on performance-critical columns
- [ ] Foreign keys set with appropriate ON DELETE behavior
- [ ] All planned API endpoints implemented in `/src/app/api/`
- [ ] Authentication verified (no access without valid session)
- [ ] Input validation with Zod on all POST/PUT requests
- [ ] Meaningful error messages with correct HTTP status codes
- [ ] No TypeScript errors in API routes
- [ ] All endpoints tested manually
- [ ] No hardcoded secrets in source code
- [ ] Frontend connected to real API endpoints
- [ ] User has reviewed and approved
## Verification (run before marking complete)
- [ ] `npm run build` passes without errors
- [ ] All acceptance criteria from feature spec addressed in API
- [ ] All API endpoints return correct status codes (test with curl or browser)
- [ ] `features/INDEX.md` status updated to "In Progress"
- [ ] Code committed to git
## Performance Checklist
- [ ] All frequently filtered columns have indexes
- [ ] No N+1 queries (use Supabase joins instead of loops)
- [ ] All list queries use `.limit()`
- [ ] Zod validation on all write endpoints
- [ ] Slow queries cached where appropriate (optional for MVP)
- [ ] Rate limiting on public-facing APIs (optional for MVP)
.claude/skills/deploy/SKILL.md
+96 -86
View File
@@ -1,114 +1,124 @@
---
name: deploy
description: Deploy to Vercel with production-ready checks, error tracking, and security headers setup.
argument-hint: "feature-spec-path or 'to Vercel'"
description: Deploy the Docker Compose stack to a server, with pre-flight checks and rollback.
argument-hint: "PROJ-X or 'production'"
user-invocable: true
---
# DevOps Engineer
# Deploy
## Role
You are an experienced DevOps Engineer handling deployment, environment setup, and production readiness.
Self-hosted Docker Compose. There is no Vercel, no managed platform. The stack runs
one app container; TLS and routing are handled by a reverse proxy already present
on the host.
## Before Starting
1. Read `features/INDEX.md` to know what is being deployed
2. Check QA status in the feature spec
3. Verify no Critical/High bugs exist in QA results
4. If QA has not been done, tell the user: "Run `/qa` first before deploying."
## 1. Gate
## Workflow
1. Read `features/INDEX.md` — what is being shipped
2. Read the feature spec's QA section
### 1. Pre-Deployment Checks
- [ ] `npm run build` succeeds locally
- [ ] `npm run lint` passes
- [ ] QA Engineer has approved the feature (check feature spec)
- [ ] No Critical/High bugs in test report
- [ ] All environment variables documented in `.env.local.example`
- [ ] No secrets committed to git
- [ ] All database migrations applied in Supabase (if applicable)
- [ ] All code committed and pushed to remote
**No QA section:** → "Für PROJ-X gibt es noch kein QA-Ergebnis. Führe erst `/qa` aus." → Stop.
**Critical or High bugs open:** → name them and stop. Those get fixed first.
### 2. Vercel Setup (first deployment only)
## 2. Pre-flight
> **Prerequisite (manual, do this first):** The user must create a Vercel account in the browser before this step — go to [vercel.com](https://vercel.com) and sign up (e.g. "Sign up with GitHub"). Account creation and login are browser/OAuth steps that cannot be automated by the skill. Also ensure the repo is pushed to a GitHub remote so Vercel can connect to it.
Run and show the results — do not proceed on a failure:
Guide the user through:
- [ ] Create Vercel project: `npx vercel` or via vercel.com
- [ ] Connect GitHub repository for auto-deploy on push
- [ ] Add all environment variables from `.env.local.example` in Vercel Dashboard
- [ ] Build settings: Framework Preset = Next.js (auto-detected)
- [ ] Configure domain (or use default `*.vercel.app`)
```bash
npm run lint
npm run typecheck
npm test
npm run build
```
### 3. Deploy
- Push to main branch → Vercel auto-deploys
- Or manual: `npx vercel --prod`
- Monitor build in Vercel Dashboard
Then check:
- [ ] Every env var used in code is in `.env.example` with a dummy value
- [ ] No secrets in the diff (`git diff --cached`)
- [ ] Pending migrations are committed
- [ ] Everything committed and pushed to the remote the server pulls from
### 4. Post-Deployment Verification
- [ ] Production URL loads correctly
- [ ] Deployed feature works as expected
- [ ] Database connections work (if applicable)
- [ ] Authentication flows work (if applicable)
- [ ] No errors in browser console
- [ ] No errors in Vercel function logs
## 3. First deployment only
### 5. Production-Ready Essentials
Walk the user through this once. It happens on the server, over SSH.
For first deployment, guide the user through these setup guides:
**Prerequisites the user provides manually:** a server with Docker and the Compose
plugin, a reverse proxy (nginx, Caddy, Traefik) terminating TLS, and a DNS record
pointing at it.
**Error Tracking (5 min):** See [error-tracking.md](../../../docs/production/error-tracking.md)
**Security Headers (copy-paste):** See [security-headers.md](../../../docs/production/security-headers.md)
**Performance Check:** See [performance.md](../../../docs/production/performance.md)
**Database Optimization:** See [database-optimization.md](../../../docs/production/database-optimization.md)
**Rate Limiting (optional):** See [rate-limiting.md](../../../docs/production/rate-limiting.md)
```bash
git clone <repo-url> /srv/<app-name> && cd /srv/<app-name>
cp .env.example .env
```
### 6. Post-Deployment Bookkeeping
- Update feature spec: Add deployment section with production URL and date
- Update `features/INDEX.md`: Set status to **Deployed**
- Create git tag: `git tag -a v1.X.0-PROJ-X -m "Deploy PROJ-X: [Feature Name]"`
- Push tag: `git push origin v1.X.0-PROJ-X`
Then edit `.env`:
- `NEXT_PUBLIC_APP_URL` — the real public URL. **If auth is used, this must match
the domain exactly**: the WebAuthn relying-party ID comes from this hostname, and
a mismatch makes every passkey fail without a useful error.
- `APP_PORT` — the port the reverse proxy forwards to
- `APP_BIND` — leave at `127.0.0.1` so the container is not exposed directly
- `BETTER_AUTH_SECRET` — `openssl rand -base64 32`, unique per environment
## Common Issues
```bash
docker compose up -d --build
curl -fsS http://127.0.0.1:${APP_PORT:-3000}/api/health
```
### Build fails on Vercel but works locally
- Check Node.js version (Vercel may use different version)
- Ensure all dependencies are in package.json (not just devDependencies)
- Review Vercel build logs for specific error
Point the reverse proxy at `127.0.0.1:$APP_PORT` and make sure it forwards
`X-Forwarded-Proto` and `X-Forwarded-Host`, otherwise redirects and WebAuthn origin
checks break.
### Environment variables not available
- Verify vars are set in Vercel Dashboard (Settings → Environment Variables)
- Client-side vars need `NEXT_PUBLIC_` prefix
- Redeploy after adding new env vars (they don't apply retroactively)
Passkeys need HTTPS in production — confirm TLS works before testing auth.
### Database connection errors
- Verify Supabase URL and anon key in Vercel env vars
- Check RLS policies allow the operations being attempted
- Verify Supabase project is not paused (free tier pauses after inactivity)
## 4. Subsequent deployments
## Rollback Instructions
If production is broken:
1. **Immediate:** Vercel Dashboard → Deployments → Click "..." on previous working deployment → "Promote to Production"
2. **Fix locally:** Debug the issue, `npm run build`, commit, push
3. Vercel auto-deploys the fix
On the server:
## Full Deployment Checklist
- [ ] Pre-deployment checks all pass
- [ ] Vercel build successful
- [ ] Production URL loads and works
- [ ] Feature tested in production environment
- [ ] No console errors, no Vercel log errors
- [ ] Error tracking setup (Sentry or alternative)
- [ ] Security headers configured in next.config
- [ ] Lighthouse score checked (target > 90)
- [ ] Feature spec updated with deployment info
- [ ] `features/INDEX.md` updated to Deployed
- [ ] Git tag created and pushed
- [ ] User has verified production deployment
```bash
./scripts/update.sh
```
It pulls the branch, rebuilds, restarts, waits for the healthcheck, and rolls back
to the previous commit if the new container never turns healthy. `--force` rebuilds
without a new commit; `--branch <name>` deploys a different branch.
If a data layer exists, migrations run before the new container serves traffic —
see `docs/DEPLOYMENT.md`.
## 5. Verify
- [ ] Public URL loads over HTTPS
- [ ] `/api/health` returns `{"status":"ok"}`
- [ ] The deployed feature works end to end
- [ ] Sign-in works and offers passkey first (if auth exists)
- [ ] No console errors, no errors in `docker compose logs app`
- [ ] Security headers survived the proxy (DevTools → Network → Response Headers)
## 6. Bookkeeping
- Add a Deployment section to the spec: URL, date, commit SHA
- `features/INDEX.md` → **Deployed** (write, then re-read to verify)
- Tag: `git tag -a v1.X.0-PROJ-X -m "Deploy PROJ-X: [name]"` and push it
## Rollback
`scripts/update.sh` rolls back automatically on an unhealthy container. Manually:
```bash
git reset --hard <previous-sha>
docker compose up -d --build
```
## Common failures
| Symptom | Cause |
|---------|-------|
| Build works locally, fails in Docker | A dependency sits in devDependencies but is needed at build time |
| Env var undefined at runtime | Not in `.env` on the server, or missing `NEXT_PUBLIC_` for client use |
| Container healthy, proxy returns 502 | Proxy points at the wrong port, or `APP_BIND` is not reachable from it |
| Passkeys fail after deploy | `NEXT_PUBLIC_APP_URL` does not match the real domain, or TLS is missing |
| Redirect loop | Proxy not forwarding `X-Forwarded-Proto` |
## Commit
## Git Commit
```
deploy(PROJ-X): Deploy [feature name] to production
- Production URL: https://your-app.vercel.app
- Deployed: YYYY-MM-DD
```
.claude/skills/frontend/SKILL.md
+54 -65
View File
@@ -1,95 +1,84 @@
---
name: frontend
description: Build UI components with React, Next.js, Tailwind CSS, and shadcn/ui. Use after architecture is designed.
argument-hint: "feature-spec-path"
description: Build UI components with React, Next.js, Tailwind v4 and shadcn/ui. Use after architecture is designed.
argument-hint: "PROJ-X or feature-spec-path"
user-invocable: true
---
# Frontend Developer
# Frontend
## Role
You are an experienced Frontend Developer. You read feature specs + tech design and implement the UI using React, Next.js, Tailwind CSS, and shadcn/ui.
You own the UI phase for one feature. You do the interview and the review with the
user; the **Frontend Developer** sub-agent does the implementation.
## Before Starting
1. Read `features/INDEX.md` for project context
2. Read the feature spec referenced by the user (including Tech Design section)
3. Check installed shadcn/ui components: `ls src/components/ui/`
4. Check existing custom components: `ls src/components/*.tsx 2>/dev/null`
5. Check existing hooks: `ls src/hooks/ 2>/dev/null`
6. Check existing pages: `ls src/app/`
## 1. Load context
## Workflow
1. Read `features/INDEX.md`
2. Read the feature spec, including its Tech Design section
3. `ls src/components/ui/` — installed shadcn components
4. `git ls-files src/components/` — existing custom components
### 1. Read Feature Spec + Design
- Understand the component architecture from Solution Architect
- Identify which shadcn/ui components to use
- Identify what needs to be built custom
**If the spec has no Tech Design section:**
> "Für PROJ-X gibt es noch kein technisches Design. Führe zuerst `/architecture` aus —
> ohne Komponentenstruktur baue ich sonst am Entwurf vorbei."
→ Stop.
### 2. Clarify Design Requirements
First check for a project design system: `cat docs/design-system.md 2>/dev/null`
## 2. Clarify design
If `docs/design-system.md` exists → read it and apply its colors, typography, and component guidelines throughout. Do not ask the user about design choices already covered there.
Check for a design system: `cat docs/design-system.md 2>/dev/null`
If it does not exist, check for other design files: `ls -la design/ mockups/ assets/ 2>/dev/null`
If it exists, follow it and do not ask about anything it already answers.
Otherwise check `ls design/ mockups/ 2>/dev/null`, and if nothing exists, ask the
user — one question at a time, each with a recommendation:
If no design specs exist at all, ask the user:
- Visual style preference (modern/minimal, corporate, playful, dark mode)
- Reference designs or inspiration URLs
- Brand colors (hex codes or use Tailwind defaults)
- Layout preference (sidebar, top-nav, centered)
- Visual style (modern/minimal, corporate, playful)
- Brand colors, or Tailwind/shadcn defaults
- Layout (sidebar, top-nav, centered)
- Interactions beyond the basics (drag & drop, animations)
### 3. Clarify Technical Questions
- Mobile-first or desktop-first?
- Any specific interactions needed (hover effects, animations, drag & drop)?
- Accessibility requirements beyond defaults (WCAG 2.1 AA)?
## 3. Set status
### 4. Implement Components
- Create components in `/src/components/`
- ALWAYS use shadcn/ui for standard UI elements (check `src/components/ui/` first!)
- If a shadcn component is missing, install it: `npx shadcn@latest add <name> --yes`
- Only create custom components as compositions of shadcn primitives
- Use Tailwind CSS for all styling
Update `features/INDEX.md` and the spec header to **In Progress**. Verify by
re-reading.
### 5. Integrate into Pages
- Add components to pages in `/src/app/`
- Set up routing if needed
- Connect to backend APIs or localStorage as specified in tech design
## 4. Delegate implementation
### 6. User Review
- Tell the user to test in browser (localhost:3000)
- Ask: "Does the UI look right? Any changes needed?"
- Iterate based on feedback
Invoke the **Frontend Developer** sub-agent with:
- the spec path
- the design decisions from step 2
- the component list from the Tech Design
- the shadcn components already installed
## Context Recovery
If your context was compacted mid-task:
1. Re-read the feature spec you're implementing
2. Re-read `features/INDEX.md` for current status
3. Run `git diff` to see what you've already changed
4. Run `git ls-files src/components/ | head -20` to see current component state
5. Continue from where you left off - don't restart or duplicate work
Wait for its report. Do not implement in parallel yourself.
## After Completion: Backend & QA Handoff
## 5. Review with the user
Check the feature spec - does this feature need backend?
Present the sub-agent's report, then:
> "Läuft unter http://localhost:3000. Schau es dir an — passt das so?"
**Backend needed if:** Database access, user authentication, server-side logic, API endpoints, multi-user data sync
Iterate on feedback by sending follow-up instructions to the same sub-agent, so it
keeps its context.
**No backend if:** localStorage only, no user accounts, no server communication
## 6. Wrap up
If backend is needed:
> "Frontend is done! This feature needs backend work. Next step: Run `/backend` to build the APIs and database."
Verify before declaring done:
- [ ] `npm run lint`, `npm run typecheck`, `npm run build` pass
- [ ] Every acceptance criterion has a UI counterpart
- [ ] shadcn used everywhere it could be; no hand-written duplicates
- [ ] Loading, error and empty states exist
- [ ] Responsive at 375 / 768 / 1440px
- [ ] Spec updated with implementation notes (written **and** re-read)
- [ ] `features/INDEX.md` status is In Progress
- [ ] User approved
If no backend needed:
> "Frontend is done! Next step: Run `/qa` to test this feature against its acceptance criteria."
## Handoff
## Checklist
See [checklist.md](checklist.md) for the full implementation checklist.
Does the feature need a server side (data storage, auth, APIs, cross-device sync)?
After completion, update tracking files:
- [ ] Feature spec updated with implementation notes
- [ ] `features/INDEX.md` status updated to "In Progress"
- Yes → "Frontend steht. Nächster Schritt: `/backend` für APIs und Datenhaltung."
- No → "Frontend steht. Nächster Schritt: `/qa` zum Testen gegen die Acceptance Criteria."
## Commit
## Git Commit
```
feat(PROJ-X): Implement frontend for [feature name]
```
.claude/skills/frontend/checklist.md
-38
View File
@@ -1,38 +0,0 @@
# Frontend Implementation Checklist
Before marking frontend as complete:
## shadcn/ui
- [ ] Checked shadcn/ui for EVERY UI component needed
- [ ] No custom duplicates of shadcn components created
- [ ] Missing shadcn components installed via `npx shadcn@latest add`
## Existing Code
- [ ] Checked existing project components via `git ls-files src/components/`
- [ ] Reused existing components where possible
## Design
- [ ] Design preferences clarified with user (if no mockups)
- [ ] Component architecture from Solution Architect followed
## Implementation
- [ ] All planned components implemented
- [ ] All components use Tailwind CSS (no inline styles, no CSS modules)
- [ ] Loading states implemented (spinner/skeleton during data fetches)
- [ ] Error states implemented (user-friendly error messages)
- [ ] Empty states implemented ("No data yet" messages)
## Quality
- [ ] Responsive: Mobile (375px), Tablet (768px), Desktop (1440px)
- [ ] Accessibility: Semantic HTML, ARIA labels, keyboard navigation
- [ ] TypeScript: No errors (`npm run build` passes)
- [ ] ESLint: No warnings (`npm run lint`)
## Verification (run before marking complete)
- [ ] `npm run build` passes without errors
- [ ] All acceptance criteria from feature spec addressed in UI
- [ ] `features/INDEX.md` status updated to "In Progress"
## Completion
- [ ] User has reviewed and approved the UI in browser
- [ ] Code committed to git
.claude/skills/help/SKILL.md
+38 -84
View File
@@ -1,104 +1,58 @@
---
name: help
description: Context-aware guide that tells you where you are in the workflow and what to do next. Use anytime you're unsure.
description: Context-aware guide — where the project stands and what to do next.
argument-hint: "optional question"
user-invocable: true
---
# Project Help Guide
# Help
You are a helpful project assistant. Your job is to analyze the current project state and tell the user exactly where they are and what to do next.
Work out where the project actually stands, then say what to do next. Be concrete,
be short.
## When Invoked
## 1. Read the state
### Step 1: Analyze Current State
1. `docs/PRD.md` — still the empty template, or filled in?
2. `features/INDEX.md` — which features exist, at which status?
3. For the active feature, check which sections its spec already has:
Tech Design (`/architecture`), QA Test Results (`/qa`), Deployment (`/deploy`)
4. Quick scan: `ls src/components/ui/`, `ls src/app/api/ 2>/dev/null`, `ls tests/ 2>/dev/null`
Read these files to understand where the project stands:
Trust the files over the status column if they disagree — and say so when they do.
1. **Check PRD:** Read `docs/PRD.md`
- Is it still the empty template? → Project not initialized yet
- Is it filled out? → Project has been set up
## 2. Name the next step
2. **Check Feature Index:** Read `features/INDEX.md`
- No features listed? → No features created yet
- Features exist? → Check their statuses
| State | Next step |
|-------|-----------|
| PRD is the empty template | `/init` mit einer kurzen Beschreibung der Idee |
| PRD filled, no features | `/write-spec` für das erste Feature |
| Status Roadmap | `/write-spec PROJ-X` — Spec schreiben |
| Status Planned | `/architecture PROJ-X` — technisches Design |
| Status Architected | `/frontend PROJ-X` — UI bauen |
| Frontend done, needs a server side | `/backend PROJ-X` |
| Implemented, no QA section | `/qa PROJ-X` |
| Status Approved | `/deploy PROJ-X` |
| Everything deployed | `/write-spec` für das nächste Feature aus der PRD-Roadmap |
3. **Check Feature Specs:** For each feature in INDEX.md, check if:
- Tech Design section exists (added by /architecture)
- QA Test Results section exists (added by /qa)
- Deployment section exists (added by /deploy)
## 3. Answer the question, if there was one
4. **Check Codebase:** Quick scan of what's been built
- `ls src/components/*.tsx 2>/dev/null` → Custom components
- `ls src/app/api/ 2>/dev/null` → API routes
- `ls src/components/ui/` → Installed shadcn components
If the user asked something specific, answer that **first**, then show the status.
Common ones: which skills exist, how to add a feature, how to customize the
template (CLAUDE.md, `.claude/rules/`, `.claude/skills/`), how deployment works
(Docker Compose, `scripts/update.sh` — no Vercel).
### Step 2: Determine Next Action
## Output
Based on the state analysis, determine what the user should do next:
### Stand
_Zwei, drei Sätze: wo das Projekt steht._
**If PRD is empty template:**
> Your project hasn't been initialized yet.
> Run `/init` with a description of what you want to build.
> Example: `/init I want to build a task management app for small teams`
### Features
_Tabelle aus INDEX.md._
**If PRD exists but no features:**
> Your PRD is set up but no features have been created yet.
> Run `/write-spec` to create your first feature specification.
### Nächster Schritt
_Der eine wichtigste Schritt, mit dem exakten Kommando._
**If features exist with status "Planned" (no Tech Design):**
> Feature PROJ-X is ready for architecture design.
> Run `/architecture` to create the technical design for `features/PROJ-X-name.md`
### Sonst möglich
_Kurze Liste weiterer sinnvoller Aktionen._
**If features have Tech Design but no implementation:**
> Feature PROJ-X has a tech design and is ready for implementation.
> Run `/frontend` to build the UI for `features/PROJ-X-name.md`
> (If backend is needed, run `/backend` after frontend is done)
**If features are implemented but no QA:**
> Feature PROJ-X is implemented and ready for testing.
> Run `/qa` to test `features/PROJ-X-name.md` against its acceptance criteria.
**If features have passed QA but aren't deployed:**
> Feature PROJ-X has passed QA and is ready for deployment.
> Run `/deploy` to deploy to production.
**If all features are deployed:**
> All current features are deployed! You can:
> - Run `/write-spec` to spec out a new feature
> - Check `docs/PRD.md` for planned features not yet specified
### Step 3: Answer User Questions
If the user asked a specific question (via arguments), answer it in the context of the current project state. Common questions:
- "What skills are available?" → List all available skills with brief descriptions
- "How do I add a new feature?" → Explain `/write-spec` workflow (or `/init` if the project isn't set up yet)
- "How do I customize this template?" → Point to CLAUDE.md, rules/, skills/
- "What's the project structure?" → Explain the directory layout
- "How do I deploy?" → Explain `/deploy` workflow and prerequisites
## Output Format
Always respond with this structure:
### Current Project Status
_Brief summary of where the project stands_
### Features Overview
_Table of features and their current status (from INDEX.md)_
### Recommended Next Step
_The single most important thing to do next, with the exact command_
### Other Available Actions
_Other things the user could do right now_
If the user asked a specific question, answer that FIRST, then show the status overview.
## Important
- Be concise and actionable
- Always give the exact command to run
- Reference specific file paths
- Don't explain the framework architecture in detail unless asked
- Focus on: "Here's where you are, here's what to do next"
Give exact commands and real file paths. Do not explain the framework unless asked.
.claude/skills/init/SKILL.md
+81 -107
View File
@@ -1,146 +1,120 @@
---
name: init
description: Initialize a new project. Creates the PRD and a prioritized feature map. Run once at the very start of a new project. If a PRD is empty (raw template stucture) use this skill to plan out the project togehter with the user.
description: Initialize a new project — PRD and prioritized feature map. Run once at the very start.
argument-hint: "description of what you want to build"
user-invocable: true
---
# Project Initializer
# Init
## Role
You are an experienced Product Strategist. Your job is to help the user articulate their project vision and break it down into a prioritized feature map — before any code is written.
You are a product strategist. You interview the user until the project is genuinely
understood, then write the PRD and break it into a feature map. No code, no specs.
## The Grill Me Principle
Interview the user relentlessly until you reach a **complete shared understanding** of the project. Follow these rules strictly:
## Grill Me principle
- **One question at a time** — never list multiple questions
- **Always provide a recommended answer** — the user confirms or corrects it
- **Follow the conversation** — open new branches based on answers, don't follow a fixed script
- **Explore before asking** — if a question can be answered by reading existing files, read them first
- **No fixed question limit** — stop when you truly understand the project, not after N questions
- **One question at a time** — never a list
- **Always offer a recommended answer** — the user confirms or corrects it
- **Follow the conversation** — open branches based on answers, no fixed script
- **Read before asking** — if a file answers it, read the file
- **No question limit** — stop when you understand, not after N questions
## Before Starting
1. Read `docs/PRD.md` — check if it's still the empty template
2. Read `features/INDEX.md` — check if features already exist
## Before starting
**If the project is already initialized** (PRD is filled out and not the empty template):
→ Tell the user: "This project is already initialized. Use `/write-spec` to create a feature spec, or `/refine PROJ-X` to update an existing one."
→ Stop here.
Read `docs/PRD.md` and `features/INDEX.md`.
## Interview Phase
**If the PRD is already filled in:**
> "Dieses Projekt ist bereits initialisiert. Nutze `/write-spec` für eine neue
> Feature-Spec oder `/refine PROJ-X`, um eine bestehende zu überarbeiten."
→ Stop.
Start the conversation based on the argument the user provided. If they described their idea, acknowledge it and ask your first clarifying question about the most important open point. If no argument was given, ask:
## Interview
> "What do you want to build, and what problem does it solve?"
> My recommendation: Start with the user pain — what frustrates people today that your product will fix?
Start from whatever the user passed as argument. If nothing, ask:
> "Was willst du bauen, und welches Problem löst es?"
> Empfehlung: Fang beim Schmerz an — was nervt heute, das dein Produkt beseitigt?
Cover these topics through natural conversation (not as a checklist):
- Core problem being solved
- Primary target users and their specific pain points
- Must-have features for MVP vs. nice-to-have later
- Existing alternatives / competitors — what's different here?
- Constraints: timeline, budget, team size
- Success metrics: how do you know this product worked?
- Non-goals: what are you explicitly NOT building in this version?
Cover through natural conversation: the core problem, the target users and their
specific pain, MVP versus later, existing alternatives and the difference, constraints
(time, budget, team), success metrics, and explicit non-goals.
### Mandatory: Backend Decision (ask before building the feature map)
This question MUST be resolved before you create the feature map — it determines the entire architecture and feature list.
### Mandatory: persistence
Ask:
> "Does the app need to store data persistently or sync between users/devices?"
> My recommendation: Yes — most apps need at least local persistence. If multiple users or cross-device sync is needed, a backend is required.
Resolve before the feature map — it shapes the architecture.
**If yes → follow up:**
> "Should we use Supabase (the template's built-in backend: PostgreSQL + Auth + Storage) or keep it frontend-only with localStorage?"
> My recommendation: Supabase — if users need accounts or data needs to survive a browser refresh, local storage won't be enough.
> "Müssen Daten dauerhaft gespeichert oder zwischen Nutzern und Geräten synchronisiert werden?"
> Empfehlung: Ja — sobald Daten einen Browser-Neustart überleben sollen, reicht
> localStorage nicht mehr.
**If Supabase is chosen:**
- Add **"Supabase Infrastructure Setup"** as **PROJ-1, P0** in the feature map
- All features that require auth, data storage, or file uploads must list PROJ-1 as a dependency
- This feature covers: project setup, environment variables, database schema outline, auth configuration
This template ships **no** database. If persistence is needed, note it as a
constraint; `/architecture` picks the concrete data layer per feature. The only
hard requirement: it must run self-hosted in the Docker Compose stack.
**If frontend-only (localStorage):**
- No infrastructure feature needed
- Note "No backend — localStorage only" in the PRD Constraints section
### Mandatory: authentication
### Mandatory: Design System (ask before building the feature map)
Ask:
> "Do you have an existing design system, brand guidelines, or UI reference I should follow?"
> My recommendation: Even a rough color palette and font preference saves a lot of back-and-forth later.
> "Brauchen Nutzer eigene Konten?"
**Three ways the user can provide it:**
1. **File upload** — an HTML or Markdown file with colors, typography, component styles
2. **Manual input** — the user describes it directly (e.g. "dark theme, Inter font, blue primary #2563EB")
3. **None** — use the template's default (Tailwind + shadcn/ui defaults)
If yes, add **"Auth-Grundlage (Better Auth + Passkeys)"** as **PROJ-1, P0** with no
dependencies. Every feature that needs a logged-in user depends on PROJ-1.
The stack is fixed: Better Auth with the passkey plugin, passkey primary, password
only as a fallback. Do not offer alternatives — record it and move on.
**If a design system is provided:**
- Save it to `docs/design-system.md` (create the file with the provided content or a structured summary)
- Add a note in `docs/PRD.md` under Constraints: "Design system: see `docs/design-system.md`"
- The `/frontend` skill will read this file when building UI components
### Mandatory: design system
## After the Interview: Create the PRD
> "Hast du ein bestehendes Design-System, Brand Guidelines oder eine UI-Referenz?"
> Empfehlung: Schon eine grobe Farbpalette und Schriftwahl spart später viel Hin und Her.
Once you have a complete understanding, write `docs/PRD.md` with:
- **Vision:** 2-3 sentences — what it is and why it matters
- **Target Users:** Who they are, their specific needs and pain points
- **Core Features (Roadmap):** Prioritized table (P0 = MVP, P1 = next, P2 = later)
- **Success Metrics:** Measurable outcomes
- **Constraints:** Timeline, team, budget, technical limitations
- **Non-Goals:** What will NOT be built in this version
If provided (as a file or described in words), save it to `docs/design-system.md`
and reference it in the PRD constraints. `/frontend` reads it. If nothing, the
Tailwind/shadcn defaults apply.
Present the draft PRD to the user for review before saving. Apply feedback, then save.
## Write the PRD
## After PRD: Create the Feature Map
Fill `docs/PRD.md`, in German:
- **Vision** — 2–3 sentences
- **Zielgruppe** — who, and their concrete pain
- **Roadmap** — prioritized table, P0 = MVP, P1 = next, P2 = later
- **Erfolgsmetriken** — measurable
- **Rahmenbedingungen** — time, team, budget, technical limits, persistence decision
- **Nicht-Ziele** — explicitly out for this version
Apply Single Responsibility to break the roadmap into individual features:
- Each feature = ONE testable, deployable unit
- Identify dependencies between features
- Assign recommended build order (respecting dependencies)
- Assign priority: P0 = MVP, P1 = next, P2 = later
Present the draft, apply feedback, then save.
**What each feature entry in `features/INDEX.md` contains:**
- Feature ID (PROJ-1, PROJ-2, ...)
- Feature name
- One-line description
- Priority (P0/P1/P2)
- Dependencies (which other features it needs, or "None")
- Status: Roadmap
## Build the feature map
Present the feature map to the user:
> "I've identified X features. Here's the breakdown and recommended build order:"
Single Responsibility: each feature is one testable, deployable unit.
Apply feedback, then update `features/INDEX.md` and the "Next Available ID" line.
Each entry in `features/INDEX.md` carries: ID, name, one-line description,
priority, dependencies, status **Roadmap**.
## What NOT to do
- Do NOT create individual `features/PROJ-X-*.md` spec files — that is `/write-spec`'s job
- Do NOT write code or make technical decisions
- Do NOT ask multiple questions at once
- Do NOT stop early — keep going until you have full clarity on the project
Present it as a build order that respects dependencies:
> "Ich habe X Features identifiziert. Hier die Aufteilung und die empfohlene Reihenfolge:"
## Checklist Before Completion
- [ ] PRD fully filled out (Vision, Target Users, Roadmap, Metrics, Constraints, Non-Goals)
- [ ] Backend decision resolved (Supabase vs. localStorage)
- [ ] If Supabase: "Supabase Infrastructure Setup" added as PROJ-1, P0, no dependencies
- [ ] If Supabase: all data/auth-dependent features list PROJ-1 as dependency
- [ ] If frontend-only: noted in PRD Constraints
- [ ] Design system decision resolved
- [ ] If design system provided: saved to `docs/design-system.md` and referenced in PRD
- [ ] Every feature respects Single Responsibility
- [ ] Dependencies between features documented
- [ ] All features added to `features/INDEX.md` with status "Roadmap"
- [ ] "Next Available ID" updated in INDEX.md
- [ ] Build order recommended
- [ ] User has reviewed and approved PRD and feature map
Apply feedback, then write `features/INDEX.md` and update "Next Available ID".
Re-read the file to verify.
## Do not
- Create `features/PROJ-X-*.md` spec files — that is `/write-spec`
- Write code or pick concrete libraries beyond the fixed auth stack
- Ask several questions at once
- Stop before you actually understand the project
## Wrap up
- [ ] PRD complete (Vision, Zielgruppe, Roadmap, Metriken, Rahmenbedingungen, Nicht-Ziele)
- [ ] Persistence resolved and noted
- [ ] Auth resolved; if yes, PROJ-1 auth feature added and depended on
- [ ] Design system resolved; if provided, saved to `docs/design-system.md`
- [ ] Every feature is a single responsibility, dependencies documented
- [ ] `features/INDEX.md` written with status Roadmap, next ID updated, verified
- [ ] User approved PRD and feature map
## Handoff
After user approval:
> "Project setup complete. Run `/write-spec` to start speccing your first feature: **[recommended first feature name]** (PROJ-1)."
> "Projekt steht. Nächster Schritt: `/write-spec` für das erste Feature: **[Name]** (PROJ-1)."
## Commit
## Git Commit
```
feat: Initialize project — PRD and feature map
- Created docs/PRD.md with vision, target users, and roadmap
- Added X features to features/INDEX.md
```
```
.claude/skills/qa/SKILL.md
+75 -131
View File
@@ -1,159 +1,103 @@
---
name: qa
description: Test features against acceptance criteria, find bugs, and perform security audit. Use after implementation is done.
argument-hint: "feature-spec-path"
description: Test a feature against acceptance criteria, find bugs, audit security. Use after implementation is done.
argument-hint: "PROJ-X or feature-spec-path"
user-invocable: true
---
# QA Engineer
# QA
## Role
You are an experienced QA Engineer AND Red-Team Pen-Tester. You test features against acceptance criteria, identify bugs, and audit for security vulnerabilities.
You own the test phase for one feature. The **QA Engineer** sub-agent does the
testing; you set up its context, then present and prioritize the results with the
user.
## Before Starting
1. Read `features/INDEX.md` for project context
2. Read the feature spec referenced by the user
3. Check recently implemented features for regression testing: `git log --oneline --grep="PROJ-" -10`
4. Check recent bug fixes: `git log --oneline --grep="fix" -10`
5. Check recently changed files: `git log --name-only -5 --format=""`
## 1. Load context
### Check Playwright Browser Installation
Run: `npx playwright install --dry-run 2>&1 | head -5`
1. Read `features/INDEX.md` — note which features are already **Deployed**
(those are the regression surface)
2. Read the feature spec
3. `git log --oneline -10` — what changed recently
If browsers are not installed, tell the user:
> "Playwright browsers need to be installed once. I'll do this now — it downloads ~300MB of browser binaries."
> Then run: `npx playwright install chromium`
> This is a one-time setup per machine. After cloning the repo, always run this once before E2E tests.
## 2. Set status
## Workflow
Update `features/INDEX.md` and the spec header to **In Review**. Verify by
re-reading.
### 1. Read Feature Spec
- Understand ALL acceptance criteria
- Understand ALL documented edge cases
- Understand the tech design decisions
- Note any dependencies on other features
## 3. Delegate testing
### 2. Manual Testing
Test the feature systematically in the browser:
- Test EVERY acceptance criterion (mark pass/fail)
- Test ALL documented edge cases
- Test undocumented edge cases you identify
- Cross-browser: Chrome, Firefox, Safari
- Responsive: Mobile (375px), Tablet (768px), Desktop (1440px)
Invoke the **QA Engineer** sub-agent with:
- the spec path
- the list of deployed features to regression-check
- any areas the developer flagged as risky
### 3. Security Audit (Red Team)
Think like an attacker:
- Test authentication bypass attempts
- Test authorization (can user X access user Y's data?)
- Test input injection (XSS, SQL injection via UI inputs)
- Test rate limiting (rapid repeated requests)
- Check for exposed secrets in browser console/network tab
- Check for sensitive data in API responses
Wait for its report.
### 4. Regression Testing
Verify existing features still work:
- Check features listed in `features/INDEX.md` with status "Deployed"
- Test core flows of related features
- Verify no visual regressions on shared components
## 4. Write results into the spec
### 5. Run Automated Tests
Run existing test suites before manual testing:
```bash
npm test # Vitest: integration tests for API routes
npm run test:e2e # Playwright: E2E tests from previous QA runs
Append this to the feature spec — not to a separate file:
```markdown
---
## QA Test Results
**Getestet:** YYYY-MM-DD
**Tester:** QA Engineer (AI)
### Acceptance Criteria
- [x] AC-1: [Kriterium]
- [ ] AC-2: [Kriterium] — BUG-1
### Edge Cases
- [x] EC-1: [Randfall] — korrekt behandelt
### Security-Audit
- [x] Ohne Session kein Zugriff
- [x] Kein Zugriff auf fremde Datensätze
- [x] Passkey ist der primäre Anmeldeweg
- [x] Eingaben validiert, keine Injection
### Gefundene Bugs
#### BUG-1: [Titel]
- **Severity:** Critical | High | Medium | Low
- **Reproduktion:** 1. … 2. … 3. …
- **Erwartet:** …
- **Tatsächlich:** …
### Zusammenfassung
- **Acceptance Criteria:** X von Y bestanden
- **Bugs:** N gesamt (C critical, H high, M medium, L low)
- **Produktionsreif:** JA / NEIN
```
Note any failures — these are regressions and must be treated as High bugs.
### 6. Write Unit Tests
Before E2E tests, identify and test isolated logic with Vitest. Place tests **co-located** next to the source file (e.g. `src/hooks/useFeature.test.ts` next to `src/hooks/useFeature.ts`):
Re-read the file afterwards to confirm it landed.
**What to unit test (evaluate each):**
- Custom hooks with non-trivial logic (e.g. `useKanbanStorage`: localStorage read/write, error fallback)
- Pure utility/transformation functions (e.g. drag-and-drop reorder logic)
- Form validation logic (if extracted from components)
## 5. Review with the user
**What NOT to unit test:**
- Pure presentational components with no logic
- Logic already fully covered by E2E tests
Present: criteria passed/failed, bugs by severity, security findings, verdict.
Then ask:
> "Welche Bugs sollen zuerst behoben werden?"
For each unit test:
- Test the happy path
- Test error paths and edge cases (e.g. corrupt input, empty state)
- Mock only external dependencies (localStorage, fetch) — not internal logic
## 6. Wrap up
Run to confirm all pass: `npm test`
### 7. Write E2E Tests
For each acceptance criterion that passed manual testing, write a Playwright test in `tests/PROJ-X-feature-name.spec.ts`:
- One `test()` per acceptance criterion
- Tests describe the user journey in plain language
- Run to confirm all pass: `npm run test:e2e`
These tests become the permanent regression suite for this feature.
### 8. Document Results
- Add QA Test Results section to the feature spec file (NOT a separate file)
- Use the template from [test-template.md](test-template.md)
### 9. User Review
Present test results with clear summary:
- Total acceptance criteria: X passed, Y failed
- Bugs found: breakdown by severity
- Security audit: findings
- Production-ready recommendation: YES or NO
Ask: "Which bugs should be fixed first?"
## Context Recovery
If your context was compacted mid-task:
1. Re-read the feature spec you're testing
2. Re-read `features/INDEX.md` for current status
3. Check if you already added QA results to the feature spec: search for "## QA Test Results"
4. Run `git diff` to see what you've already documented
5. Continue testing from where you left off - don't re-test passed criteria
## Bug Severity Levels
- **Critical:** Security vulnerabilities, data loss, complete feature failure
- **High:** Core functionality broken, blocking issues
- **Medium:** Non-critical functionality issues, workarounds exist
- **Low:** UX issues, cosmetic problems, minor inconveniences
## Important
- NEVER fix bugs yourself - that is for Frontend/Backend skills
- Focus: Find, Document, Prioritize
- Be thorough and objective: report even small bugs
## Production-Ready Decision
- **READY:** No Critical or High bugs remaining
- **NOT READY:** Critical or High bugs exist (must be fixed first)
## Checklist
- [ ] Feature spec fully read and understood
- [ ] All acceptance criteria tested (each has pass/fail)
- [ ] All documented edge cases tested
- [ ] Additional edge cases identified and tested
- [ ] Cross-browser tested (Chrome, Firefox, Safari)
- [ ] Responsive tested (375px, 768px, 1440px)
- [ ] Security audit completed (red-team perspective)
- [ ] Regression test on related features
- [ ] Every bug documented with severity + steps to reproduce
- [ ] Screenshots added for visual bugs
- [ ] Unit tests written for non-trivial hooks and utility functions (`npm test` passes)
- [ ] E2E tests written for all passing acceptance criteria (`npm run test:e2e` passes)
- [ ] QA section added to feature spec file
- [ ] User has reviewed results and prioritized bugs
- [ ] Production-ready decision made
- [ ] `features/INDEX.md` status updated to "In Review" (at QA start)
- [ ] `features/INDEX.md` status updated to "Approved" (if production-ready) OR kept "In Review" (if bugs remain)
- [ ] Every acceptance criterion has an individual pass/fail
- [ ] Documented and undocumented edge cases tested
- [ ] Security audit done from a red-team angle
- [ ] Regression check against deployed features
- [ ] Unit tests for non-trivial logic (`npm test` passes)
- [ ] E2E test per passing criterion (`npm run test:e2e` passes)
- [ ] QA section written into the spec and verified
- [ ] `features/INDEX.md` → **Approved** if no Critical/High, otherwise stays **In Review**
## Handoff
If production-ready:
> "All tests passed! Status updated to **Approved**. Next step: Run `/deploy` to deploy this feature to production."
If bugs found:
> "Found [N] bugs ([severity breakdown]). Status remains **In Review**. The developer needs to fix these before deployment. After fixes, run `/qa` again."
- Clean → "Alle Tests bestanden, Status **Approved**. Nächster Schritt: `/deploy`."
- Bugs → "[N] Bugs gefunden ([Aufschlüsselung]). Status bleibt **In Review**.
Erst `/frontend` bzw. `/backend` zum Beheben, danach nochmal `/qa`."
## Commit
## Git Commit
```
test(PROJ-X): Add QA test results for [feature name]
```
.claude/skills/qa/test-template.md
-56
View File
@@ -1,56 +0,0 @@
# QA Test Results Template
Add this section to the END of the feature spec `/features/PROJ-X.md`:
```markdown
---
## QA Test Results
**Tested:** YYYY-MM-DD
**App URL:** http://localhost:3000
**Tester:** QA Engineer (AI)
### Acceptance Criteria Status
#### AC-1: [Criterion Name]
- [x] Sub-criterion passed
- [ ] BUG: Sub-criterion failed (describe what went wrong)
#### AC-2: [Criterion Name]
- [x] All sub-criteria passed
### Edge Cases Status
#### EC-1: [Edge Case Name]
- [x] Handled correctly
#### EC-2: [Edge Case Name]
- [ ] BUG: Not handled (describe expected vs actual behavior)
### Security Audit Results
- [x] Authentication: Cannot access without login
- [x] Authorization: Users cannot access other users' data
- [x] Input validation: XSS attempts blocked
- [x] Rate limiting: Excessive requests handled
- [ ] BUG: [Security issue description]
### Bugs Found
#### BUG-1: [Bug Title]
- **Severity:** Critical | High | Medium | Low
- **Steps to Reproduce:**
1. Go to [page]
2. Do [action]
3. Expected: [what should happen]
4. Actual: [what actually happens]
- **Screenshot:** [if visual bug]
- **Priority:** Fix before deployment | Fix in next sprint | Nice to have
### Summary
- **Acceptance Criteria:** X/Y passed
- **Bugs Found:** N total (C critical, H high, M medium, L low)
- **Security:** [Pass / Issues found]
- **Production Ready:** YES / NO
- **Recommendation:** [Deploy / Fix bugs first]
```
.claude/skills/refine/SKILL.md
+64 -78
View File
@@ -1,113 +1,99 @@
---
name: refine
description: Always use when the user wants to discuss an exsiting feature or specification. Open an existing feature spec to improve, extend, or fundamentally challenge it. Pass the feature ID as argument (e.g. /refine PROJ-2).
description: Reopen an existing feature spec to improve, extend or fundamentally challenge it. Pass the feature ID.
argument-hint: "PROJ-X"
user-invocable: true
---
# Feature Spec Refiner
# Refine
## Role
You are an experienced Product Manager reviewing a live spec. Your job is to improve, extend, or fundamentally challenge the spec based on what the user tells you.
You are a product manager reviewing a live spec. Improve it, extend it, or challenge
it — depending on what brought the user back.
## Before Starting
1. Read the feature spec `features/PROJ-X-*.md` — understand the full current state
2. Read `features/INDEX.md` — understand dependencies, status, and context
3. Read `docs/PRD.md` — keep the project vision in mind
## Before starting
**If no argument was provided** (no PROJ-X ID given):
> "Which feature spec would you like to refine?" — list all existing features from INDEX.md.
1. Read `features/PROJ-X-*.md` — the full current state
2. Read `features/INDEX.md` — status and dependencies
3. Read `docs/PRD.md` — keep the vision in view
**If the PROJ-X ID doesn't exist**: tell the user and list existing features.
**No argument given:** ask which spec, listing the features from INDEX.md.
**Unknown ID:** say so and list what exists.
## Opening Question (ALWAYS ask this first)
> "What brought you back to this spec?"
## Always open with this
This answer determines everything. Listen carefully — it will tell you which of the three paths to take.
> "Was bringt dich zurück zu dieser Spec?"
## Three Paths
The answer decides the path.
### Path 1: Something Changed
*Trigger: "scope changed", "we got user feedback", "business logic is different", "stakeholder changed the requirements"*
## Three paths
Run a targeted interview on the affected areas only:
- What specifically changed?
- Which user stories are affected?
- Which acceptance criteria need to be updated or removed?
- Do any edge cases change?
- Do dependencies change?
- Does the Out of Scope section need updating? (something previously excluded is now included, or vice versa)
### Path 1 — Something changed
*"Scope hat sich geändert", "wir haben Nutzerfeedback", "die Anforderung ist anders"*
### Path 2: Implementation Revealed Gaps
*Trigger: "during implementation we found...", "the backend doesn't support...", "we didn't think about X scenario"*
Targeted interview on the affected areas only: what exactly changed, which user
stories and criteria are affected, which edge cases shift, whether dependencies
move, and whether Out of Scope needs updating in either direction.
Focus on making the spec tighter:
- What specific scenario was missing?
- Should this become a new acceptance criterion or edge case?
- Does this change any existing criteria?
- Are there related gaps we should close now while we're here?
### Path 2 — Implementation revealed a gap
*"Bei der Umsetzung kam raus, dass…", "an den Fall haben wir nicht gedacht"*
### Path 3: Fundamental Challenge
*Trigger: "I'm not sure this feature is right", "maybe we should rethink this", "this might actually be two features"*
Tighten the spec: which scenario was missing, does it become a new acceptance
criterion or an edge case, does it invalidate an existing criterion, and are there
adjacent gaps worth closing now.
Challenge the entire spec from first principles:
- What assumption is being questioned?
- Is the user story still the right framing?
- Should this feature be split? If so, what are the two features?
- Should it be merged with another feature?
- What would the absolute minimal version of this feature look like?
- What moves to Out of Scope as a result of this challenge?
### Path 3 — Fundamental challenge
*"Ich bin nicht sicher, ob das Feature so richtig ist", "das sind vielleicht zwei Features"*
If the feature should be split: create the new spec file using the `/write-spec` workflow, and update `features/INDEX.md` accordingly.
Challenge from first principles: which assumption is in doubt, is the user story
still the right framing, should this split or merge, what is the minimal version,
and what moves to Out of Scope as a result.
## The Grill Me Principle
Same as in `/init` and `/write-spec`:
- **One question at a time** — never list multiple questions
- **Always provide a recommended answer** — the user confirms or corrects it
- **Follow the conversation** — don't follow a fixed script
- **Explore codebase first** if it can answer a question
- **Stop when you have full clarity** on what needs to change
If it should split: create the new spec via the `/write-spec` workflow and update
`features/INDEX.md`.
## After the Interview: Update the Spec
## Grill Me principle
Make the changes to `features/PROJ-X-*.md`. After saving, re-read the file to verify the changes are present.
One question at a time, always with a recommendation, following the conversation
rather than a script. Read the codebase before asking anything it can answer. Stop
when the change is fully clear.
### Maintain the Decision Log and Open Questions
## Update the spec
**Close resolved Open Questions:**
For any `- [ ]` items in Open Questions that are now answered, mark them as `- [x]` and add a brief resolution note:
Edit `features/PROJ-X-*.md`, then re-read it to verify the change landed.
**Close resolved open questions** — mark `- [x]` with the resolution:
```
- [x] Should we support bulk delete? → No, deferred to P1 (2026-05-19)
- [x] Sollen wir Massenlöschen unterstützen? → Nein, verschoben auf P1 (2026-08-09)
```
**Log new decisions:**
Any decision made during this refinement session belongs in the Decision Log. Add to the relevant sub-section (Product or Technical) with rationale and date. Decisions made here are often the most important — they reflect real-world feedback changing the original plan.
**Log new decisions** in the Entscheidungslog with rationale and date. Decisions
made here matter most — they are reality correcting the original plan.
**Add new Open Questions:**
If the refinement surfaced questions that couldn't be resolved now, add them as `- [ ]` items.
**Add new open questions** as `- [ ]` if anything stays unresolved.
## Update Tracking Files
- Update `features/INDEX.md` if status or dependencies changed
- Update `docs/PRD.md` if the roadmap is affected
## Update tracking
## Checklist Before Completion
- [ ] Opening question asked and path determined
- [ ] All interview questions resolved
- [ ] Spec file updated and verified (re-read after editing)
- [ ] Out of Scope updated if scope boundaries changed
- [ ] Resolved Open Questions marked as `- [x]` with resolution note
- [ ] New decisions logged in Decision Log with rationale
- [ ] New Open Questions added if anything remains unresolved
- [ ] `features/INDEX.md` updated if status or dependencies changed
- [ ] `docs/PRD.md` updated if roadmap affected
- [ ] User has reviewed the changes
- `features/INDEX.md` if status or dependencies changed
- `docs/PRD.md` if the roadmap is affected
## Wrap up
- [ ] Opening question asked, path identified
- [ ] Interview resolved
- [ ] Spec updated and re-read to verify
- [ ] Out of Scope adjusted if boundaries moved
- [ ] Resolved questions marked `- [x]` with a note
- [ ] New decisions logged with rationale
- [ ] INDEX.md / PRD updated where affected
- [ ] User reviewed the changes
## Handoff
Depends on the path taken:
- Path 1 or 2: "Spec updated. Continue with the next step in your workflow."
- Path 3 (split): "New spec created for PROJ-X. Run `/architecture` to design the technical approach."
## Git Commit
- Path 1 or 2 → "Spec aktualisiert. Mach mit deinem nächsten Workflow-Schritt weiter."
- Path 3 with a split → "Neue Spec für PROJ-Y angelegt. Nächster Schritt: `/architecture`."
## Commit
```
feat(PROJ-X): Refine feature specification — [reason]
```
feat(PROJ-X): Refine feature specification — [brief reason]
```
.claude/skills/write-spec/SKILL.md
+86 -119
View File
@@ -1,159 +1,126 @@
---
name: write-spec
description: Write a full feature spec for a feature. Works for features already on the roadmap (status "Roadmap" from /init) and for features added later. Pass a feature name or PROJ-X ID as argument.
argument-hint: "feature name or PROJ-X ID"
description: Write a full feature spec — user stories, acceptance criteria, edge cases. Pass a feature name or PROJ-X ID.
argument-hint: "feature name or PROJ-X"
user-invocable: true
---
# Feature Spec Writer
# Write Spec
## Role
You are an experienced Product Manager. Your job is to turn a feature idea into a complete, testable specification — with user stories, acceptance criteria, and edge cases.
You are a product manager turning one feature idea into a complete, testable
specification. No code, no technical decisions — that is `/architecture`'s job.
## The Grill Me Principle
Interview the user until you reach a **complete shared understanding** of the feature. Rules:
## Grill Me principle
- **One question at a time** — never list multiple questions
- **Always provide a recommended answer** — the user confirms or corrects it
- **Follow the conversation** — open new branches, resolve dependencies between decisions one by one
- **Explore before asking** — if a question can be answered by reading the codebase, read it first
- **No fixed question limit** — stop when you truly understand the feature, not after N questions
- **One question at a time** — never a list
- **Always offer a recommended answer**
- **Follow the conversation**, resolve dependencies between decisions as they surface
- **Read the codebase before asking** anything it can answer
- **No question limit** — stop when you understand the feature
## Before Starting
1. Read `docs/PRD.md` — understand the project vision and target users
2. Read `features/INDEX.md` — see existing features, find the next available PROJ-X ID, check for duplicates
3. Check existing components: `git ls-files src/components/`
4. Check existing APIs: `git ls-files src/app/api/`
## Before starting
**If the project has not been initialized** (PRD is still the empty template):
> "The project hasn't been set up yet. Run `/init` first to define the project vision and feature map."
→ Stop here.
1. Read `docs/PRD.md` and `features/INDEX.md`
2. `git ls-files src/components/ src/app/api/`
**If no argument was provided**, ask: "Which feature would you like to spec out?" and list all features with status "Roadmap" from INDEX.md.
**If the PRD is still the empty template:**
> "Das Projekt ist noch nicht aufgesetzt. Führe erst `/init` aus." → Stop.
## Three Entry Points
**If no argument:** list all features with status Roadmap and ask which one.
### Entry Point A: Feature exists in INDEX.md with status "Roadmap"
The feature was identified during `/init`. Proceed directly to the Interview Phase.
## Three entry points
### Entry Point B: Feature does NOT exist in INDEX.md yet
The feature was forgotten during `/init` or is being added later. Before the full interview, quickly clarify:
- What is the feature called?
- What priority? (P0 = MVP, P1 = next, P2 = later) — provide a recommendation based on PRD context
- Does it depend on any existing features?
| Situation | What to do |
|-----------|------------|
| Status **Roadmap** in INDEX.md | Go straight to the interview |
| **Not in INDEX.md** | Clarify name, priority (with a recommendation) and dependencies, add it with the next PROJ-X ID and status Roadmap, then interview |
| Status **Planned** or higher | "PROJ-X hat schon eine Spec. Nutze `/refine PROJ-X`." → Stop |
Add it to `features/INDEX.md` with status "Roadmap" and the next available PROJ-X ID, then continue directly to the Interview Phase — no separate skill run needed.
## Interview
### Entry Point C: Feature already has a spec (status "Planned" or higher)
> "This feature already has a spec. Use `/refine PROJ-X` to update it."
→ Stop here.
Start from the PRD and the INDEX entry. First question targets the biggest open
point about this specific feature. Cover through conversation:
## Interview Phase
Start with what you know from `docs/PRD.md` and the feature entry in INDEX.md. Your first question should target the most important open point about this specific feature.
Cover these topics through natural conversation (not as a checklist):
- Who specifically uses this feature? (be precise — refer to the user types from the PRD)
- What is the core user action / job-to-be-done?
- What does success look like from the user's perspective?
- What are the must-have behaviors for MVP?
- What are the validation rules and constraints?
- Error states: what happens when things go wrong?
- Empty states: what does the user see before they have any data?
- Who exactly uses it (refer to the PRD's user types)
- The core action — the job to be done
- What success looks like from the user's side
- Must-have behaviour for the MVP
- Validation rules and limits
- Error states: what happens when things go wrong
- Empty states: what the user sees before any data exists
- Edge cases: concurrent edits, network failure, invalid input, permission boundaries
- Dependencies on other features (auth, data, etc.)?
- Performance or security requirements?
- Dependencies on other features (auth, data)
- Performance or security requirements
**For edge cases, always be concrete:**
- "What happens when the user submits an empty form?"
- "What if two users edit the same record simultaneously?"
- "What should happen if the API call times out?"
Be concrete about edge cases: "Was passiert, wenn zwei Nutzer denselben Datensatz
gleichzeitig bearbeiten?" beats "Gibt es Randfälle?"
## After the Interview: Write the Spec
## Write the spec
Use [template.md](template.md) to create the feature spec:
- Use the PROJ-X ID already in INDEX.md (or the one assigned in Entry Point B)
- Save to `features/PROJ-X-feature-name.md` (kebab-case filename)
Use `template.md`. Save to `features/PROJ-X-feature-name.md` (kebab-case).
**German**, per the project language rule.
**Populate Out of Scope, Decision Log, and Open Questions while the interview is fresh:**
Three sections carry the memory of this interview — do not skip them:
- **Out of Scope** — explicitly list everything that came up in the interview but was consciously excluded from this feature. Reference other features by ID where relevant (e.g. "Bulk delete — deferred to PROJ-5"). This section is critical for developer handoffs: without it, developers don't know what NOT to build.
- **Out of Scope** — everything discussed and consciously excluded, referencing
other features by ID ("Massenlöschen — verschoben auf PROJ-5"). Without it,
developers do not know what *not* to build.
- **Produkt-Entscheidungen** — every scoping and UX decision with its rationale
- **Offene Fragen** — anything unresolved, as `- [ ]` so it stays visible
Present the draft, apply feedback, then save.
## Acceptance criteria format
- **Product Decisions** — log every conscious scoping or UX decision made during the interview, with the rationale. Examples: "Why limit to X items?", "Why this user role and not another?", "Why include/exclude this edge case?"
- **Open Questions** — log anything that couldn't be resolved during the interview (pending user research, dependency on another team, unclear requirements). Mark as `- [ ]` so they're visible as unresolved.
Do not skip these sections — they are the memory of the spec interview.
Present the draft spec to the user for review. Apply feedback, then save.
## After Saving: Update Tracking Files
Update `features/INDEX.md`:
- Change the feature's status from "Roadmap" to "Planned"
- If Entry Point B: also update the "Next Available ID" line
Update `docs/PRD.md`:
- Update the status column in the roadmap table for this feature (if listed there)
## Feature Granularity (Single Responsibility)
Each spec = ONE testable, deployable unit.
**Never combine:**
- Multiple independent functionalities
- CRUD for different entities
- User functions + admin functions
- Different UI screens or areas
**Split when:**
1. Can it be tested independently? → Own spec
2. Can it be deployed independently? → Own spec
3. Does it target a different user role? → Own spec
4. Is it a separate UI screen? → Own spec
**Document dependencies:**
```markdown
## Dependencies
- Requires: PROJ-1 (User Authentication) — for logged-in user checks
```
## Important
- NEVER write code — that is for Frontend/Backend skills
- NEVER make technical decisions — that is for the Architecture skill
- Focus: WHAT the feature does (not HOW)
## Acceptance Criteria Format
Always write acceptance criteria in German using the Angenommen/Wenn/Dann format:
German, Angenommen/Wenn/Dann — one testable statement per line:
```
- [ ] Angenommen [Vorbedingung], wenn [Aktion], dann [Ergebnis]
```
Examples:
- [ ] Angenommen der Nutzer ist eingeloggt, wenn er ein leeres Formular abschickt, dann wird für jedes Pflichtfeld eine Validierungsfehlermeldung angezeigt
- [ ] Angenommen eine Aufgabe existiert, wenn der Nutzer auf „Löschen" klickt, dann erscheint ein Bestätigungsdialog bevor die Aufgabe entfernt wird
- [ ] Angenommen die API ist nicht erreichbar, wenn der Nutzer das Formular abschickt, dann wird eine Fehlermeldung angezeigt und die Eingabe bleibt erhalten
- [ ] Angenommen der Nutzer ist angemeldet, wenn er ein leeres Formular abschickt, dann erscheint pro Pflichtfeld eine Validierungsmeldung
- [ ] Angenommen eine Aufgabe existiert, wenn der Nutzer auf „Löschen" klickt, dann erscheint erst ein Bestätigungsdialog
- [ ] Angenommen die API antwortet nicht, wenn der Nutzer speichert, dann wird eine Fehlermeldung gezeigt und die Eingabe bleibt erhalten
This format ensures every criterion is unambiguous and directly testable by QA.
Each one must be directly testable by `/qa` without interpretation.
## Checklist Before Completion
- [ ] At least 3–5 user stories defined
- [ ] Out of Scope filled in (everything discussed but excluded, with references to other features where applicable)
- [ ] Every acceptance criterion uses Given/When/Then format
- [ ] Product Decisions logged with rationale
- [ ] Open Questions logged for anything unresolved
- [ ] At least 3–5 edge cases documented
- [ ] Feature ID assigned (PROJ-X)
- [ ] File saved to `features/PROJ-X-feature-name.md`
- [ ] `features/INDEX.md` updated (status: Roadmap → Planned; next ID updated if Entry Point B)
- [ ] `docs/PRD.md` roadmap table updated if applicable
- [ ] User has reviewed and approved the spec
## Granularity (Single Responsibility)
One spec = one testable, deployable unit. Split when it targets a different user
role, a different screen, or can be tested and shipped on its own. Never combine
CRUD for different entities, or user plus admin functions.
Document dependencies explicitly:
```markdown
## Abhängigkeiten
- Benötigt PROJ-1 (Auth-Grundlage) — für die Prüfung auf angemeldete Nutzer
```
## After saving
- `features/INDEX.md`: status Roadmap → **Planned** (and next ID if newly added)
- `docs/PRD.md`: update the roadmap status column if the feature is listed there
- Re-read both to verify
## Wrap up
- [ ] 3–5 user stories
- [ ] Out of Scope filled in with references
- [ ] Every criterion in Angenommen/Wenn/Dann form
- [ ] Produkt-Entscheidungen logged with rationale
- [ ] Offene Fragen logged
- [ ] 3–5 edge cases documented
- [ ] Saved as `features/PROJ-X-feature-name.md`
- [ ] INDEX.md and PRD updated and verified
- [ ] User approved
## Handoff
> "Spec is ready. Run `/architecture` to design the technical approach for PROJ-X."
## Git Commit
> "Spec steht. Nächster Schritt: `/architecture` für das technische Design von PROJ-X."
## Commit
```
feat(PROJ-X): Write feature specification for [feature name]
```
.claude/skills/write-spec/template.md
+38 -41
View File
@@ -1,63 +1,60 @@
# PROJ-X: Feature Name
# PROJ-X: Feature-Name
## Status: Planned
**Created:** YYYY-MM-DD
**Last Updated:** YYYY-MM-DD
**Status:** Planned
**Erstellt:** YYYY-MM-DD
**Zuletzt geändert:** YYYY-MM-DD
## Dependencies
- None
## Abhängigkeiten
- Keine
## User Stories
- As a [user type], I want to [action] so that [goal]
- Als [Nutzertyp] möchte ich [Aktion], um [Ziel] zu erreichen
## Out of Scope
<!-- What this feature explicitly does NOT cover. Critical for developer handoffs. -->
- _Example: Bulk operations (deferred to P1 — PROJ-X)_
- _Example: Admin view of other users' data (separate admin feature)_
<!-- Was dieses Feature bewusst NICHT abdeckt. Kritisch für die Übergabe an die Entwicklung. -->
- _Beispiel: Massenbearbeitung — verschoben auf PROJ-5_
- _Beispiel: Admin-Sicht auf fremde Daten — eigenes Feature_
## Acceptance Criteria
**Format:** Angenommen [Vorbedingung] / Wenn [Aktion] / Dann [Ergebnis]
- [ ] Angenommen [Vorbedingung], wenn [Aktion], dann [Ergebnis]
- [ ] Angenommen [Vorbedingung], wenn [Aktion], dann [Ergebnis]
<!-- Format: Angenommen [Vorbedingung], wenn [Aktion], dann [Ergebnis] -->
- [ ] Angenommen …, wenn …, dann …
- [ ] Angenommen …, wenn …, dann …
## Edge Cases
- What happens when...?
- How do we handle...?
- Was passiert, wenn …?
- Wie behandeln wir …?
## Technical Requirements (optional)
- Performance: < 200ms response time
- Security: Authentication required
- Browser Support: Chrome, Firefox, Safari
## Technische Anforderungen (optional)
- Performance: …
- Sicherheit: Anmeldung erforderlich (Better Auth, Passkey primär)
- Browser: Chrome, Firefox, Safari
## Open Questions
<!-- Unresolved questions from the spec interview. Close them in /refine when answered. -->
- [ ] Question 1
## Offene Fragen
<!-- Ungeklärtes aus dem Interview. Wird in /refine geschlossen. -->
- [ ] Frage 1
## Decision Log
<!-- Record of conscious decisions made and why. Added to by /write-spec and /architecture. -->
## Entscheidungslog
### Product Decisions
<!-- Added by /write-spec -->
| Decision | Rationale | Date |
|----------|-----------|------|
| _Example: Limit to 3 tags per item_ | _Keeps UI simple for MVP; can be raised later_ | YYYY-MM-DD |
### Produkt-Entscheidungen
<!-- von /write-spec -->
| Entscheidung | Begründung | Datum |
|--------------|------------|-------|
| _Beispiel: max. 3 Tags pro Eintrag_ | _Hält die UI im MVP einfach, später erweiterbar_ | YYYY-MM-DD |
### Technical Decisions
<!-- Added by /architecture -->
| Decision | Rationale | Date |
|----------|-----------|------|
| _Example: localStorage over Supabase_ | _No user accounts needed; data is device-local_ | YYYY-MM-DD |
### Technische Entscheidungen
<!-- von /architecture -->
| Entscheidung | Begründung | Datum |
|--------------|------------|-------|
| _Beispiel: localStorage statt Datenbank_ | _Keine Nutzerkonten, Daten bleiben gerätelokal_ | YYYY-MM-DD |
---
<!-- Sections below are added by subsequent skills -->
<!-- Die folgenden Abschnitte ergänzen die nachgelagerten Skills -->
## Tech Design (Solution Architect)
_To be added by /architecture_
## Tech Design
_wird von /architecture ergänzt_
## QA Test Results
_To be added by /qa_
_wird von /qa ergänzt_
## Deployment
_To be added by /deploy_
_wird von /deploy ergänzt_