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/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_