Florian Wilde
b0c4e9e9b9
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
3.9 KiB
name, description, argument-hint, user-invocable
| name | description | argument-hint | user-invocable |
|---|---|---|---|
| architecture | Design PM-friendly technical architecture for a feature. No code, only high-level decisions. | PROJ-X or feature-spec-path | true |
Architecture
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.
Hard rule: no code
No SQL, no TypeScript, no API snippets. Describe what gets built and why, never how in detail. Structure and plain language only.
1. Load context
- Read
features/INDEX.md - Read
docs/PRD.md - Read the feature spec
git ls-files src/components/ src/app/api/— what already exists
If the status is "Roadmap" or no spec file exists:
"PROJ-X hat noch keine Spec. Führe erst
/write-spec PROJ-Xaus — ohne User Stories und Acceptance Criteria kann ich das Design nicht entwerfen." → Stop.
2. Resolve the open decisions
One question at a time, each with a recommendation.
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:
Board-Seite
├── Eingabefeld (neue Aufgabe)
├── Spalte "Offen"
│ └── Aufgabenkarte (verschiebbar)
├── Spalte "Erledigt"
└── Leerzustand
B) Data model — in words, no schema:
Eine Aufgabe hat:
- eindeutige ID
- Titel (max. 200 Zeichen)
- Status (offen / erledigt)
- Erstellzeitpunkt
Gespeichert in: Browser-localStorage (kein Server nötig)
C) Tech decisions — each justified in language a PM understands
D) Dependencies — package names with a one-line purpose each
4. Log the decisions
Every meaningful choice goes into the spec's Technical Decisions table:
| Entscheidung | Begründung | Datum |
| localStorage statt Datenbank | Keine Nutzerkonten, Daten bleiben gerätelokal | 2026-08-09 |
Log at minimum: storage approach, ORM/driver if any, auth yes/no, package choices, and anything a future developer would otherwise question.
Anything unresolved goes to Open Questions as - [ ].
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
- Technical Decisions table filled
- Open Questions recorded
- Design written into the spec and re-read to verify
features/INDEX.md→ Architected- User approved
Handoff
"Design steht. Nächster Schritt:
/frontendfür die UI-Komponenten." Braucht das Feature einen Server-Teil, folgt/backenddanach.
Commit
docs(PROJ-X): Add technical design for [feature name]