toolctrl-labs/HiveGrid-Wireframes
9
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3cb93a81bea50927864585d1fafe0af4c4772a09
HiveGrid-Wireframes/hivegrid-cloud/docs/TC-PLANNING-BRIEFING.md
T

14 KiB
Raw Blame History

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???-<slug>/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???-<slug>/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/<modul>/<route>.tsx              → Loader baut View-Model, rendert <Page vm={...} actions={{...}} />
packages/view-models/src/<modul>/*.vm.ts    → Pure Funktion (entity, ctx) → VM, mit Zod-Schema
packages/ui-hivegrid/src/pages/<modul>/...  → 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/<modul>/<Component>.tsx empfangen IMMER:

  • vm: <ModulVM> 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/<modul>/<Component>.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/<modul>.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<typeof loader>() 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??? — <Titel>
Status: READY-TO-VERIFY | BLOCKED | NEEDS-USER-INPUT
Slices: X von Y abgeschlossen
Tests: Smoke ✓ / Hot-Swap-Drill ✓ / Visual-Regression: <Anzahl Diffs zu prüfen>
DoD-Score: N/14 erfüllt
Sidebar-Eintrag: <Gruppe> > <Eintrag>
Klick-Pfad zum Prüfen: <wie aus PLAN.md>
PROGRESS-TRACKER aktualisiert: ✓
Offene Punkte (falls relevant): <Liste>

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

  1. In der Detail-Sektion die Slice abhaken mit Commit-Hash
  2. DoD-Checkboxen abhaken, sobald die jeweilige Pflicht erfüllt ist
  3. DoD-Score in der Master-Tabelle aktualisieren (z.B. 8/14)

Bei Milestone-Abschluss (alle DoD-Punkte erfüllt + Tests grün)

  1. Status in Master-Tabelle: 🔵 IN-ARBEIT → 🟡 READY-TO-VERIFY
  2. „Notes vom Agent"-Block in Detail-Sektion ausfüllen (was war nicht offensichtlich, was muss User wissen)
  3. STOP. Warte auf User-Sign-Off. Starte KEIN nächstes Milestone.

Nach User-Sign-Off

  1. User trägt selbst 🟢 SIGNED-OFF + Datum in die Detail-Sektion ein
  2. 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
Reference in new issue View Git Blame Copy Permalink