# ToolController-Briefing für HiveGrid 2.0 **Adressat:** ToolController + alle AI-Coding-Agents (Sub-Agents von TC), die an HiveGrid arbeiten. **Stand:** 2026-05-10 **Verbindlichkeit:** dieses Dokument plus die hier referenzierten Pfade definieren das Vorgehen vollständig. --- ## 0. Was du baust HiveGrid 2.0 ist eine Multi-Tenant-SaaS-Plattform für SHK-Handwerksbetriebe. Erstkunde: Geerkens. EU-Stack komplett (kein US-Anbieter). Repository-Wurzel: `/Users/raffaelsheikh/Documents/GitHub/HiveGrid-Cloud`. 176 Milestones in `docs/milestones/M001/` bis `docs/milestones/M176/`. Jedes Verzeichnis enthält genau eine Datei `PLAN.md`. Diese sind deine Arbeits-Aufträge. ## 0.1 Die Boilerplate IST deine Codebase — nicht „eine Vorlage" Das Repo `HiveGrid-Cloud/` enthält die EU-sterilisierte ToolCTRL-Boilerplate als Fundament. Das ist **dein Code**, du editierst, erweiterst und löschst ihn. Du klonst nichts, du importierst nichts „von außen", du baust **nicht** parallel ein neues Projekt. Konkret heißt das: - `apps/web/`, `apps/api/`, `apps/worker/`, `packages/db/`, `packages/mail/`, `packages/queue/`, `packages/ui/`, `prisma/`, `package.json` mit pnpm-Workspace, Tailwind 4, shadcn/Radix, BullMQ, MailerSend → das ist deine Arbeitsbasis. Du nutzt sie. - Du erweiterst, was fehlt: neue `packages/view-models/`, `packages/ui-hivegrid/`, `packages/ui-subframe/` (Phase 1 leer), neue Routes unter `app/routes/...`, neue Module unter `app/domain/...`, neue Prisma-Modelle in `prisma/schema/...` - Du löschst, was nicht zu HiveGrid gehört (Affiliate/Marketing/CMS-Reste aus dem ToolCTRL-Boilerplate, falls noch vorhanden) - Du baust **in** dieser Codebase, nicht **neben** ihr ## 0.2 Pre-Flight-Check beim Start (jedes Mal) Bevor du das erste Milestone planst, verifiziere die Vorbedingungen: 1. `package.json` im Repo-Root existiert mit pnpm-Workspace-Konfig — wenn nein: STOP, melde „Boilerplate-Inhalt fehlt im Repo" 2. `apps/`, `packages/`, `prisma/` existieren — wenn nein: STOP 3. `pnpm install && pnpm typecheck && pnpm test` läuft grün — wenn nein: STOP, melde welche Tests rot sind 4. Kein US-Provider im Code: `grep -rE "@ai-sdk/openai|@ai-sdk/anthropic|remix-auth-google|from \"openai\"" --include="*.ts" --include="*.tsx" --include="*.json" .` ist leer — wenn nein: STOP, EU-Sterilisation nicht abgeschlossen 5. `docs/PROGRESS-TRACKER.md` existiert — wenn nein: STOP Erst nach 5/5 grün beginnst du mit dem ersten Milestone. --- ## 1. Wo du alles findest | Was | Wo | |---|---| | **Verbindliches Pflichtenheft v1.1** | `_bmad-output/pflichtenheft/` | | → Vision + Anti-Liste | `_bmad-output/pflichtenheft/02-vision.md` | | → 20 Architektur-Bauprinzipien | `_bmad-output/pflichtenheft/03-architektur.md` | | → 7 Modul-Blöcke mit Detail-Pflichten | `_bmad-output/pflichtenheft/blocks/block1.md` … `block7.md` | | → Anhang (Geparktes, Noah-Anmerkungen N1-N19) | `_bmad-output/pflichtenheft/99-anhang.md` | | **Master-Milestone-Index** | `docs/milestones/README.md` | | **Pflichtenheft → Milestone Coverage-Map** | `docs/milestones/PFLICHTENHEFT-COVERAGE.md` | | **Per-Milestone-Plan** (176 Stück) | `docs/milestones/M???-/PLAN.md` | | **Live-Progress-Tracker** (du updatest ihn) | `docs/PROGRESS-TRACKER.md` | | **Agent-Regeln + Definition of Done** | `AGENTS.md` (Repo-Root) | | **Integration-Contracts** (Sidebar, Routes, Wiring) | `docs/INTEGRATION-CONTRACTS.md` | | **Mid-Stream-Korrektur-Playbook** | `docs/MID-STREAM-CHANGES.md` | | **Change-Request-Workflow** | `docs/CHANGE-REQUESTS.md` (entsteht in M176) | --- ## 2. Wie du ein Milestone planst (Pflicht-Reihenfolge) Pro Milestone arbeitest du diese Schritte ab — nicht überspringen: 1. **Lies `docs/milestones/M???-/PLAN.md` vollständig.** Sie enthält Ziel, Pflichtenheft-Sektionen, Abhängigkeiten, Out-of-Scope, Erfolgskriterium, Hinweise und am Ende die **Definition of Done**. 2. **Lies die referenzierten Pflichtenheft-Sektionen** (`_bmad-output/pflichtenheft/blocks/blockX.md` Sektion Y.Z). Klartext-Hinweise und Edge-Cases stehen dort, nicht in PLAN.md. 3. **Lies `AGENTS.md`.** Verbindliche Regeln für Layer-Trennung, drei Anti-Patterns, EU-Stack, Querschnitt-Wiring, Klartext-Pflicht. 4. **Lies `docs/INTEGRATION-CONTRACTS.md`.** Hier steht, wo dein Modul in Sidebar / Routes / Tab-Bar / Search-Index andockt. 5. **Prüfe Abhängigkeiten:** Sind alle in PLAN.md genannten Vorbedingungs-Milestones abgeschlossen? Wenn nein: STOP und an User melden. 6. **Plane Slices** (TC-Standard, 5–8 pro Milestone): - Erste Slice ist meist Datenmodell + Migration - Folge-Slices: Domain-Logik → Loader/Action → View-Model → UI-Component → Sidebar/Routing-Wiring → Tests - Letzte Slice: Smoke-Test + Hot-Swap-Drill 7. **Plane Tasks pro Slice** (5 Tasks à 30 Min – 2 Std). Pro Task konkrete Files + Verify-Befehle. 8. **Vor Execute:** prüfe gegen die **Definition of Done** in PLAN.md. Sind alle Punkte über die geplanten Slices abgedeckt? Wenn nicht: ergänze Slices. 9. **Execute pro Slice atomar.** Pro Slice ein Commit. Forward-Only-DB-Migrations mit Inverse-SQL als Kommentar. 10. **Nach jeder Slice: Verify-Gate.** Erst nach grünem Verify zur nächsten. --- ## 3. UI-Bauen ohne Subframe (Phase-1-Bootstrap) **Wichtig:** Der finale UI-Workflow läuft über Subframe (Designer baut → Subframe-Output → AI-Agent integriert via Adapter). **Aber jetzt** baust du UI mit den **vorhandenen Komponenten der Boilerplate** — sauber, austauschbar, testbar. Ziel: Geerkens-tauglich aussehende UI, die später ohne Logik-Bruch durch Subframe-Output ersetzt werden kann. ### Was du verwenden darfst | Layer | Quelle | |---|---| | Primitives | shadcn/ui + Radix-UI (alle `@radix-ui/*`-Pakete sind in der Boilerplate) | | Icons | lucide-react | | Tabellen | bestehende `components/ui/table.*` aus Boilerplate-`packages/ui` | | Forms | react-hook-form + zod (bereits in Deps) | | Charts | recharts oder @tremor/react | | Tipp-Trigger / Suche | kbar | | Editor | TipTap (für Notizen, Marketing-Editor) | | Drag-&-Drop | react-beautiful-dnd / xyflow (für Automation-Editor) | | PDF | @react-pdf/renderer | | Touch-Signatur | signature_pad | | Tailwind 4 | bereits konfiguriert | ### Was du NICHT machst - ❌ KEIN Subframe-MCP-Aufruf für irgendwas in Phase 1. - ❌ KEIN `packages/ui-subframe`-Inhalt füllen — das Verzeichnis bleibt leer (oder mit Dummy-README), bis der Designer kommt. - ❌ KEINE Custom-CSS-Stylesheets pro Komponente — Tailwind-Utility-Klassen. - ❌ KEINE eigenen Component-Libraries erfinden — nur shadcn/Radix-Composites. ### Wie du UI strukturierst Genau gleich wie es später mit Subframe sein wird — **die Layer-Trennung ist jetzt schon Pflicht**, sonst funktioniert der spätere Hot-Swap nicht: ``` app/routes//.tsx → Loader baut View-Model, rendert packages/view-models/src//*.vm.ts → Pure Funktion (entity, ctx) → VM, mit Zod-Schema packages/ui-hivegrid/src/pages//... → React-Component, baut auf shadcn/Radix mit Tailwind, KEIN Server-Code packages/ui-hivegrid/src/components/... → Wiederverwendbare Composites (Tabellen, Karten, Modale) ``` Components in `packages/ui-hivegrid/src/pages//.tsx` empfangen IMMER: - `vm: ` als Prop (das View-Model) - `actions: { onX: (...) => ... }` als Prop (Callbacks) KEINE Hooks für Daten-Fetching innerhalb dieser Components. KEINE direkten Server-Imports. ### Warum das den späteren Hot-Swap erlaubt Wenn der Designer später Subframe-Output liefert, wird der Inhalt von `packages/ui-hivegrid/src/pages//.tsx` durch den Subframe-konformen Adapter ersetzt — die **Schnittstelle** (Props: `vm` + `actions`) bleibt identisch. Routes, View-Models, Domain-Logik werden NICHT angefasst. Der Tausch ist atomar. Genau deshalb gilt für die Phase-1-Bootstrap-UI: - Kein direkter `useLoaderData` in Components (auch jetzt nicht!) - Kein direkter Prisma-Import (auch jetzt nicht!) - Alle Texte über i18n (M003) - Alle Aktionen als Callback-Props - View-Model hat Zod-Schema, das später dem Subframe-Adapter den Vertrag erzwingt ### Visuelles Anspruchsniveau „Sauber genug zum Testen", nicht „pixel-perfect Designer-Output". Konkret: - Konsistentes Spacing (Tailwind 4-Standard) - Hell + Dunkel-Modus respektiert (nutze Tailwind `dark:`) - DE-Long-Strings testen (47-Zeichen-Buttons dürfen nicht überlaufen) - Empty-States, Loading, Error mit Klartext (siehe AGENTS.md Punkt E) - Mobile-Viewport-Test (kein Desktop-Only-Layout) --- ## 4. Pro Milestone — Pflicht-Deliverables (Definition of Done) Aus jeder PLAN.md am Ende. In Stichpunkten: **Erreichbarkeit** (siehe INTEGRATION-CONTRACTS.md §1) - Sidebar-Eintrag in `packages/ui-hivegrid/src/app-shell/sidebar.config.ts` mit Permission-Gate - Route registriert - Breadcrumb für Detail-Routes - Mobile-Tab-Bar-Eintrag falls relevant - Customer-Portal-Sichtbarkeit explizit konfiguriert **Querschnitt-Wiring** - Audit (auto via M001 oder manuell) - Activity-Stream via `logActivity` (M045) - Notifications via `notify()` (M011) - Search-Index in `indexed-entities.ts` - Permission-Filter via `withTenantScope()` + `withPermission()` (M004) - Feature-Flag-fähig (M006) **Code-Layer-Disziplin** (PR-Block bei Verstoß) - Loader baut VM; UI empfängt nur VM + Actions - Keine Prisma-/Server-Imports in `packages/ui-hivegrid/**` - Keine Direktimporte aus `packages/ui-subframe` in `app/routes/**` (ist eh leer in Phase 1) - Alle UI-Texte als i18n-Keys **Tests** - Unit-Test für VM-Builder mit Zod-Schema - Smoke-Test in `e2e/smoke/.spec.ts` - Hot-Swap-Drill grün (Smoke-Test gegen `packages/ui-mock` aus M017) - Visual-Regression-Snapshot (M016) **Klartext** - Fehler-Texte aus M002-Catalog - Empty/Loading/Error mit Klartext + nächster Aktion - Permission-Denied → 404 statt 403 **Rollback-Pfad** - Forward-Only-DB-Migration mit Inverse-SQL als Kommentar - Atomic-Slice-Commits - Feature-Flag vorhanden zum Abschalten ohne Deploy **Klick-Pfad zum Prüfen** (steht in PLAN.md unten) - 4-Schritt-Anleitung, wie der User die Funktion findet und testet --- ## 5. Drei harte Anti-Patterns (sofortiger PR-Block) 1. `@prisma/client` oder `~/db` in `packages/ui-hivegrid/**` 2. Direktimport aus `packages/ui-subframe` in `app/routes/**` (das Paket ist Phase-1 leer, aber der Import-Pfad bleibt verboten) 3. `useLoaderData()` innerhalb von `packages/ui-hivegrid/**` Plus: jede Erweiterung, die der Anti-Liste in `_bmad-output/pflichtenheft/02-vision.md` V.3 widerspricht. Vollständige Liste siehe dort. --- ## 6. EU-Stack — nicht verhandelbar - KEIN `@ai-sdk/anthropic`, `@ai-sdk/openai`, `openai` - KEIN `remix-auth-google`, KEIN Apple-/Google-/Microsoft-Login (Phase 1) - JA Mistral primär, Scaleway sekundär, AlephAlpha tertiär - JA Email+PW + Magic-Link + TOTP-2FA - Hosting Scaleway (EU), DB in EU, Storage Scaleway-S3 (EU) Wenn etwas im Boilerplate-Code noch US-Provider referenziert: STOP und an User melden — die Boilerplate sollte EU-sterilisiert sein. --- ## 7. Wenn du nicht weiterkommst | Situation | Vorgehen | |---|---| | Pflichtenheft-Sektion ist mehrdeutig | STOP. Frage formulieren, an User. Kein Auto-Refactor. | | Abhängigkeits-Milestone fehlt | STOP. An User: „M??? braucht M??? — wann fertig?" | | Boilerplate hat Bug, der dich blockiert | STOP. Bug an User mit konkretem Pfad + Repro. | | Anti-Listen-Punkt in PLAN.md gewünscht | STOP. Change-Request via `docs/CHANGE-REQUESTS.md` (M176). | | Layer-Trennung lässt sich nicht einhalten | STOP. Architektur-Frage, nicht selber lösen. | --- ## 8. Erste konkrete Aufgabe Beginne mit **M001 (Audit-Log default)**. Lies: 1. `docs/milestones/M001-audit-log-default/PLAN.md` 2. `_bmad-output/pflichtenheft/03-architektur.md` Sektion A.6 3. `AGENTS.md` 4. `docs/INTEGRATION-CONTRACTS.md` (§5 Audit-Wiring, §6 — der Audit-Eintrag selbst gehört zu diesem Milestone) Plane M001 in Slices, präsentiere den Plan, warte auf User-Bestätigung, dann Execute. Nach M001 → M002 → ... in der Reihenfolge der Master-Liste, ABER: prüfe in jeder PLAN.md die Abhängigkeiten — manche Milestones lassen sich parallelisieren (siehe `Wird benötigt von`-Felder). --- ## 9. Was du dem User nach jedem Milestone meldest Kurzer Statusbericht in dieser Form: ``` Milestone: M??? — Status: READY-TO-VERIFY | BLOCKED | NEEDS-USER-INPUT Slices: X von Y abgeschlossen Tests: Smoke ✓ / Hot-Swap-Drill ✓ / Visual-Regression: DoD-Score: N/14 erfüllt Sidebar-Eintrag: > Klick-Pfad zum Prüfen: PROGRESS-TRACKER aktualisiert: ✓ Offene Punkte (falls relevant): ``` --- ## 10. Progress-Tracker-Pflicht (`docs/PROGRESS-TRACKER.md`) Diese Datei ist Live-Übersicht für den User. Du updatest sie **nach jedem Status-Wechsel**: ### Bei Milestone-Start 1. Status in der Master-Tabelle: `⚪ NICHT-GESTARTET` → `🔵 IN-ARBEIT` 2. Detail-Sektion gemäß Vorlage (Abschnitt „Vorlage" in der Tracker-Datei) anlegen — kopiere den Block, fülle Pflichtenheft-Bezug, leere Slice-Liste, leere DoD-Checkboxen ein 3. Klick-Pfad-Block aus PLAN.md übernehmen, mit konkreten User-Typ + Sidebar-Pfad ausfüllen ### Bei Slice-Abschluss 4. In der Detail-Sektion die Slice abhaken mit Commit-Hash 5. DoD-Checkboxen abhaken, sobald die jeweilige Pflicht erfüllt ist 6. DoD-Score in der Master-Tabelle aktualisieren (z.B. `8/14`) ### Bei Milestone-Abschluss (alle DoD-Punkte erfüllt + Tests grün) 7. Status in Master-Tabelle: `🔵 IN-ARBEIT` → `🟡 READY-TO-VERIFY` 8. „Notes vom Agent"-Block in Detail-Sektion ausfüllen (was war nicht offensichtlich, was muss User wissen) 9. STOP. Warte auf User-Sign-Off. Starte KEIN nächstes Milestone. ### Nach User-Sign-Off 10. User trägt selbst `🟢 SIGNED-OFF` + Datum in die Detail-Sektion ein 11. Du übernimmst diesen Status in die Master-Tabelle und beginnst das nächste Milestone ### Konsistenz-Pflicht - DoD-Score in Master-Tabelle muss zur Detail-Sektion passen - `🟡 READY-TO-VERIFY` ohne 14/14 DoD = Inkonsistenz → korrigiere sofort - Mehr als 5 Milestones in `🔵 IN-ARBEIT` parallel → STOP, Fokus-Verlust → an User melden