florian.wilde/code-vorlage

Template

Files

T

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

Toolchain fixes (all previously broken):
- npm run lint: next lint was removed in Next 16 -> eslint with flat config
- .eslintrc.json was ignored by ESLint 9 -> eslint.config.mjs
- npm test / test:e2e exited 1 with no tests -> passWithNoTests
- Vitest scanned tests/ and would have run Playwright specs -> scoped to src/
- Playwright targeted Mobile Safari while docs installed only chromium
- reuseExistingServer silently tested a foreign server on :3000 -> E2E_PORT
- 11 high-severity vulns -> npm audit fix
- deny rule Read(**/.env*) also blocked .env.example -> precise patterns

Stack changes:
- Tailwind v3 -> v4 (CSS-first, no tailwind.config.ts, tw-animate-css)
- shadcn regenerated for v4; 33 components -> 6 core, bundled radix-ui
- Supabase removed entirely; data layer is now chosen per project
- Vercel removed; Docker Compose self-hosting with scripts/update.sh
- Better Auth + passkey plugin as the binding auth standard
- ThemeProvider and Sonner mounted; dark mode and toasts now actually work

Workflow system:
- Sub-agents wired: /frontend, /backend, /qa delegate to .claude/agents
- Checklists folded into their SKILL.md; one file per skill
- Rules rewritten: DB-agnostic backend, passkey security, v4 frontend
- Spec language settled as German, skill instructions English

2026-08-09 00:48:50 +02:00

4.5 KiB

Raw Blame History

name, description, argument-hint, user-invocable

name	description	argument-hint	user-invocable
write-spec	Write a full feature spec — user stories, acceptance criteria, edge cases. Pass a feature name or PROJ-X ID.	feature name or PROJ-X	true

Write Spec

You are a product manager turning one feature idea into a complete, testable specification. No code, no technical decisions — that is /architecture's job.

Grill Me principle

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

Read docs/PRD.md and features/INDEX.md
git ls-files src/components/ src/app/api/

If the PRD is still the empty template:

"Das Projekt ist noch nicht aufgesetzt. Führe erst /init aus." → Stop.

If no argument: list all features with status Roadmap and ask which one.

Three entry points

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

Interview

Start from the PRD and the INDEX entry. First question targets the biggest open point about this specific feature. Cover through conversation:

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)
Performance or security requirements

Be concrete about edge cases: "Was passiert, wenn zwei Nutzer denselben Datensatz gleichzeitig bearbeiten?" beats "Gibt es Randfälle?"

Write the spec

Use template.md. Save to features/PROJ-X-feature-name.md (kebab-case). German, per the project language rule.

Three sections carry the memory of this interview — do not skip them:

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

German, Angenommen/Wenn/Dann — one testable statement per line:

- [ ] Angenommen [Vorbedingung], wenn [Aktion], dann [Ergebnis]

Examples:

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

Each one must be directly testable by /qa without interpretation.

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:

## 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 steht. Nächster Schritt: /architecture für das technische Design von PROJ-X."

Commit

feat(PROJ-X): Write feature specification for [feature name]