Update hivegrid-cloud reference to latest main
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
1 parent
e98d38e716
commit
7b21524c86
3781 files changed
+373484
-225607
No files matched your search
@@ -1,6 +1,6 @@
|
||||
# HiveGrid 2.0 — Agent-Regeln
|
||||
|
||||
Zentrale Regel-Datei für AI-Agents (Coding-Agents, ToolController-Worker), die an HiveGrid arbeiten.
|
||||
Zentrale Regel-Datei für AI-Agents (Coding-Agents, HiveGrid-Worker), die an HiveGrid arbeiten.
|
||||
|
||||
**Letzte Aktualisierung:** 2026-06-19
|
||||
**Architektur-Quelle:** Party-Mode-Diskussion mit Sally/Winston/Amelia, dokumentiert in `docs/milestones/README.md`.
|
||||
@@ -8,13 +8,13 @@ Zentrale Regel-Datei für AI-Agents (Coding-Agents, ToolController-Worker), die
|
||||
## Arbeitsmodus & Wo-finde-ich-was (Stand 16.06.)
|
||||
|
||||
**Team — 2 Devs bauen PARALLEL** (+ David = Screens/Subframe, Dejan = Website, Haris = Vertrieb):
|
||||
- **Raffael** — kritische Kern-Kette, SEQUENZIELL: P1 → P2 → P5 → P6 → P7 → P8 → P9 → P11 → P12 → P13.
|
||||
- **Raffael** — kritische Kern-Kette, SEQUENZIELL: P1 → P2 → P5 → P6 → P7 → P8 → P9 → P11 → P12. **P13 entfällt nach AD-26** (kein v1-KI-Layer); v2-Neuschnitt ist `VR-MCP`/`VD-MCP`.
|
||||
- **Akeshan** — unabhängige Trabanten parallel dazu: Infra, P3, P4, P17, P19, dann (nach P5) P14, P15, P16, P20, P21.
|
||||
- **Sync-Punkt:** P14/P15/P16 brauchen Raffaels P5 (Apps-Engine). **Parallel-Regel (AD-21):** jedes Modul bekommt eine eigene `prisma/schema/<modul>.prisma`; auf dem Feature-Branch `prisma db push`, **Migration erst beim Merge** — sonst Konflikte im Schema/in der Migrations-Historie. `core.prisma`/`accounts.prisma` nur für Relationen zu Tenant/User anfassen. Siehe §„Prisma-Schema & Migrationen".
|
||||
|
||||
**GSD = nur Infrastruktur, NICHT die Slash-Commands.** Wir nutzen die `.planning/`-Struktur + Codebase-Konventionen, arbeiten aber **ticket-getrieben** — KEINE `/gsd-plan-phase` / `/gsd-execute-phase`-Befehle.
|
||||
|
||||
**Ein Ticket bauen:** Du bekommst eine Ticket-ID → lies `.planning/ticket-docs/<ID>.md` (self-contained Bau-Spec: Was/Screens/DoD/Technische-Bausteine/Quellen/Abhängigkeiten) **und** diese AGENTS.md. Voller Einstiegs-Prompt + Designer-first-Regel (UI wartet auf „Davids Delta" im Screen-Ticket): **`.planning/ticket-docs/README.md`**. Vor dem Bauen die `blocked-by` aus der Doc prüfen. **Strikt im Ticket-/Ticket-Doc-Scope bleiben, Verbesserungen nur explizit ausgewiesen vorschlagen, Fortschritt als % der DoD melden** → siehe §„Ticket-Treue, Verbesserungs-Vorschläge & Fortschritt".
|
||||
**Ein Ticket bauen:** Du bekommst eine Ticket-ID → lies `.planning/ticket-docs/<ID>.md` (self-contained Bau-Spec: Was/Screens/DoD/Technische-Bausteine/Quellen/Abhängigkeiten) **und** diese AGENTS.md. Voller Einstiegs-Prompt + Designer-first-Regel (UI wartet auf „Davids Delta" im Screen-Ticket): **`.planning/ticket-docs/README.md`**. **Interim-UI-Regel (AD-28):** UI-lastige Tickets bleiben nicht bis zu Davids Delta auf „On Hold" — der Dev baut eine **Interim-UI (Vorschau-Screen) aus `~/ui`** (VM als Prop, kein handgeschriebenes Tailwind) und stellt das Ticket damit fertig; die finale Subframe-Optik wird ein **getrackter Nachzug** (Label `design-nachzug`), nicht Done-blockierend. Details: **`.planning/INTERIM-UI-PLAYBOOK.md`**. Vor dem Bauen die `blocked-by` aus der Doc prüfen. **Strikt im Ticket-/Ticket-Doc-Scope bleiben, Verbesserungen nur explizit ausgewiesen vorschlagen, Fortschritt als % der DoD melden** → siehe §„Ticket-Treue, Verbesserungs-Vorschläge & Fortschritt". **Vor jedem Commit/Push die operative Checkliste [`docs/AGENT-CHECKLIST.md`](docs/AGENT-CHECKLIST.md) abarbeiten** (lokal typecheck+lint+test grün, passende `verify:*`, Footguns).
|
||||
|
||||
**Wo finde ich was:**
|
||||
|
||||
@@ -28,6 +28,7 @@ Zentrale Regel-Datei für AI-Agents (Coding-Agents, ToolController-Worker), die
|
||||
| Requirements je Modul | `.planning/REQUIREMENTS.md` |
|
||||
| Screen-Briefs (Designer) | `.planning/designer-briefs/PXX.md` |
|
||||
| Architektur-Entscheidungen | `docs/ARCHITECTURE-DECISIONS.md` (u.a. AD-1 RLS · AD-17 PWA-only · AD-20 Projekt-zentrisch · AD-21 Prisma) |
|
||||
| **Pre-Push/Pre-Merge-Checkliste** | `docs/AGENT-CHECKLIST.md` (lokal grün: typecheck+lint+test · `verify:*` · Footguns) |
|
||||
| Live-Tickets/Status/Cycles | Plane: `project.tool-ctrl.de`, Projekt HiveGrid |
|
||||
|
||||
**Pivot-Vorrang:** Bei Widerspruch zwischen `ENTITY-MODEL.md` und den `_bmad-output/specs/M0x` (teils pre-pivot) gilt **immer das ENTITY-MODEL** (AD-20: ein `Projekt`-Kern, Pipelines=Views, „Deal"/„Auftrag"=Typen, Lead→Projekt, kein Won-Handoff). Die betroffenen Specs tragen oben einen 🔴 Pivot-Block.
|
||||
@@ -61,42 +62,39 @@ Vor jeder maßgeblichen Ticket-Änderung (Start-/Zieldatum, Scope, Assignee/Owne
|
||||
|
||||
Geteilte Dev-`.env`-Werte liegen **verschlüsselt** in `secrets/dev.sops.env` (SOPS+age, beide Devs als Recipients). `pnpm env:pull` entschlüsselt nach `./.env`, `pnpm env:edit` ändert sie. Onboarding/Regeln: `secrets/README.md`. Der age-Private-Key bleibt lokal (`~/.config/sops/age/keys.txt`), **nie ins Repo**. Nur geteilte API-Keys liegen im Blob; lokale DB/Redis = Defaults aus `.env.example`.
|
||||
|
||||
## Die Boilerplate IST deine Codebase — kritisch
|
||||
## Bespoke-HiveGrid auf ehemaligem Boilerplate-Fundament — kritisch
|
||||
|
||||
**Du baust HiveGrid NICHT from scratch.** Das `HiveGrid-Cloud/`-Repo enthält die EU-sterilisierte Boilerplate als Fundament. Das ist DEIN Code, du editierst, erweiterst und löschst ihn — du klonst nichts, du importierst nichts „von außen".
|
||||
**HiveGrid wird bespoke gebaut.** Das `HiveGrid-Cloud/`-Repo stammt historisch aus der EU-sterilisierten Boilerplate und nutzt weiterhin sinnvolle Fundament-Pakete, aber wir planen **keine laufende Upstream-Produktmerge-Strategie mehr**. Boilerplate-Reste sind Arbeitsmaterial, kein Produktziel. Du editierst, erweiterst und löschst sie, wenn HiveGrid dadurch kohärenter wird.
|
||||
|
||||
Konkret:
|
||||
- `apps/web/`, `apps/api/`, `apps/worker/`, `packages/db/`, `packages/mail/`, `packages/queue/`, `packages/ui/`, alles weitere → das ist deine Arbeitsbasis
|
||||
- `apps/web/`, `apps/api/`, `apps/worker/`, `packages/db/`, `packages/mail/`, `packages/queue/`, `packages/ui*`, alles weitere → das ist deine Arbeitsbasis
|
||||
- `package.json` mit pnpm-Workspace, Prisma, BullMQ, MailerSend, shadcn/Radix → bestehender Stack, den du nutzt
|
||||
- Du erweiterst, was fehlt (z. B. neue `packages/view-models/`, `packages/ui-app/`, neue Routes)
|
||||
- Du löschst, was nicht zu HiveGrid gehört (Affiliate-Reste, Marketing-Demo-Inhalte aus dem ToolCTRL-Boilerplate, falls noch vorhanden)
|
||||
- Du löschst, was nicht zu HiveGrid gehört (Affiliate-Reste, Scaffolder, Demo-/Marketing-Boilerplate, Storybook-/Docs-Ballast, falls nicht mehr gebraucht)
|
||||
- Du baust neue Module **in** dieser Codebase, nicht **neben** ihr
|
||||
|
||||
**Pre-Flight-Check beim Start (jedes Mal):**
|
||||
1. `package.json` im Repo-Root existiert mit pnpm-Workspace-Konfig → wenn nein: STOP, melde „Boilerplate-Inhalt fehlt"
|
||||
1. `package.json` im Repo-Root existiert mit pnpm-Workspace-Konfig → wenn nein: STOP, melde „Workspace-Inhalt fehlt"
|
||||
2. `apps/`, `packages/`, `prisma/` existieren → wenn nein: STOP
|
||||
3. `pnpm typecheck && pnpm test` läuft grün → wenn nein: STOP
|
||||
4. Keine US-Provider-Imports mehr (`grep -rE "@ai-sdk/openai[^-]|@ai-sdk/anthropic|remix-auth-google" --include="*.ts"` leer) → wenn nein: STOP, EU-Sterilisation nicht abgeschlossen. (Das `[^-]` lässt `@ai-sdk/openai-compatible` durch — das ist der EU-taugliche provider-agnostische SDK für Mistral/Scaleway, KEIN US-Import.)
|
||||
|
||||
Erst danach beginnst du mit dem ersten Milestone.
|
||||
|
||||
## Naming-Konvention (Stand 2026-06-04, siehe `docs/ARCHITECTURE-DECISIONS.md` AD-10)
|
||||
## Naming-Konvention (Stand 2026-07-01, Bespoke-Re-Cut)
|
||||
|
||||
**Wichtige Korrektur zu „benenne frei um":** Dieses Repo ist ein **git-Downstream** der Boilerplate
|
||||
(`upstream` = `git@git.tool-ctrl.de:toolctrl-labs/boilerplate.git`). Boilerplate-Verbesserungen werden
|
||||
via `git merge upstream/main` eingespielt. Deshalb wird **NICHT** umbenannt:
|
||||
**Wichtige Korrektur:** Dieses Repo hat einen Boilerplate-Ursprung, aber HiveGrid wird bespoke weitergeführt. Stabilität im laufenden Code zählt mehr als künstliche Upstream-Mergebarkeit.
|
||||
|
||||
- **Geteilte Boilerplate-Pakete behalten `@toolctrl/*`** (z.B. `@toolctrl/foundation`,
|
||||
`@toolctrl/view-models`, `@toolctrl/db`, `@toolctrl/search`) — mergebar mit upstream.
|
||||
- **Alle Workspace-Pakete nutzen den `@hivegrid/*`-Scope** (z.B. `@hivegrid/foundation`,
|
||||
`@hivegrid/view-models`, `@hivegrid/db`, `@hivegrid/search`, `@hivegrid/cli`). Es gibt keine
|
||||
Alt-Scope-Aliase und keine parallel gepflegten Alt-Namen.
|
||||
- **UI-Pakete heißen real `packages/ui-app`, `packages/ui-subframe`, `packages/ui-mock`** —
|
||||
NICHT `packages/ui-hivegrid`. Wo Docs/PLANs „`packages/ui-hivegrid`" sagen, ist **`packages/ui-app`** gemeint.
|
||||
- **`@hivegrid/*` nur für genuin NEUE HiveGrid-Pakete**, die upstream nie existieren (z.B. das
|
||||
neue Activity-Paket). Diese kollidieren beim Merge nicht.
|
||||
NICHT `packages/ui-hivegrid`. Alte `ui-hivegrid`-Erwähnungen sind Doku-Drift und zu korrigieren.
|
||||
- Pfad-Korrekturen ggü. älteren Docs: Sidebar liegt in `apps/web/app/application/sidebar/`
|
||||
(nicht `sidebar.config.ts`); Such-Index/`indexedEntities` gehört nach `packages/search/`
|
||||
(nicht `packages/db/src/search/indexed-entities.ts`).
|
||||
|
||||
Die DoD-, Anti-Pattern- und Workflow-Pfade unten nennen ab hier bereits die realen Pfade (`packages/ui-app`, `apps/web/app/application/sidebar/`, `packages/search/`); nur Punkt oben behält `ui-hivegrid` als Mapping-Hinweis für ältere Docs/PLANs.
|
||||
Die DoD-, Anti-Pattern- und Workflow-Pfade unten nennen ab hier bereits die realen Pfade (`packages/ui-app`, `apps/web/app/application/sidebar/`, `packages/search/`).
|
||||
|
||||
## Pflichtenheft als Quelle der Wahrheit
|
||||
|
||||
@@ -137,7 +135,7 @@ Ein Milestone gilt **nur dann als erledigt**, wenn ALLE folgenden Punkte wahr si
|
||||
### C. Querschnitt-Wiring (Pflicht-Service-Aufrufe)
|
||||
|
||||
13. **Schreib-Aktion** ist auditiert (auto via M001-Prisma-Middleware oder manuell via `auditEvent`).
|
||||
14. **Activity-Stream-Eintrag** auf relevanter Entität (Kontakt/Firma/Lead/Verkaufsfall/Auftrag) bei jeder relevanten Aktion via `logActivity`.
|
||||
14. **Activity-Stream-Eintrag** auf relevanter Entität (Kontakt/Firma/Lead/Projekt) bei jeder relevanten Aktion via `logActivity`.
|
||||
15. **Notifications** via M011-Service (`notify({...})`), niemals direkt Email/Push.
|
||||
16. **Search-Index** registriert in `packages/search/` (indexed-entities-Registry — M00-Neubau), falls suchbar.
|
||||
17. **Permission-Filter** via `withTenantScope()` + `withPermission()` (M004) — kein manueller Query-Filter im Modul-Code.
|
||||
@@ -147,7 +145,9 @@ Ein Milestone gilt **nur dann als erledigt**, wenn ALLE folgenden Punkte wahr si
|
||||
18. **Unit-Tests** für View-Model-Builder (pure-function-test mit Fixture).
|
||||
19. **Smoke-Test** in `e2e/smoke/<modul>.spec.ts` — Login → Route öffnen → Hauptaktion klicken → erwartetes Ergebnis sichtbar.
|
||||
20. **Hot-Swap-Drill** (M017): Smoke-Tests müssen mit `packages/ui-mock` als Drop-in-Replacement laufen.
|
||||
21. **Visual-Regression-Snapshot** (M016) für die Hauptansicht.
|
||||
21. **Visual-Regression-Snapshot** (M016) für die Hauptansicht — bei Interim-UI (AD-28) gegen die **Interim-Baseline**, mit Re-Baseline-Pflicht beim David-Nachzug.
|
||||
|
||||
> **Interim-UI & Done (AD-28, `.planning/INTERIM-UI-PLAYBOOK.md`):** Für UI-lastige Tickets zählt als Done: **Dev-DoD 100 % + Interim-Screen aus `~/ui` (VM als Prop, kein handgeschriebenes Tailwind) + Tests grün** (B 6–10, D 18–21 gegen Interim-Baseline). Die **finale Subframe-Optik** ist dann **kein Done-Blocker**, sondern ein **getrackter Nachzug**. `/planning` bleibt Single Source of Truth: der `🎨 design-nachzug: offen`-Tag unter der Header-Tabelle der Ticket-Doc + Interim-UI-Vermerk in der „Dev-Nachzug"-Sektion sind führend; das gleichnamige Plane-Label spiegelt nur. Die Layer-Trennung (Block A) und die drei Anti-Patterns bleiben unangetastet.
|
||||
|
||||
### E. Klartext-Hinweise (User-facing)
|
||||
|
||||
@@ -170,6 +170,14 @@ Ein Milestone gilt **nur dann als erledigt**, wenn ALLE folgenden Punkte wahr si
|
||||
2. Direktimport aus `packages/ui-subframe` in `app/routes/**`
|
||||
3. `useLoaderData<typeof loader>()` innerhalb von `packages/ui-app/**`
|
||||
|
||||
## Entity-Builder: KEIN neuer Konsument + Ablöse-Pflicht (AD-2, verbindlich seit 2026-06-29)
|
||||
|
||||
Der generische Entity-Builder (`Entity`/`Row`/`RowValue`, `modules/rows`, `utils/db/entities`, `EntitiesSingleton`, die `*Api.server`-Entity-Layer, `modules/crm`-`CrmService`-Legacy) ist **Alt-Last** und wird abgelöst — bisher nur für den CRM-Pfad raus (R-P6/R-P6B-α/R-P6C), generisch läuft er noch.
|
||||
|
||||
- **PR-Block:** Ein **neues** Fachmodul/Feature, das den Entity-Builder als Datenmodell nutzt (statt typisierter Prisma-Tabellen wie CRM), wird abgelehnt — wie ein Anti-Listen-Verstoß. Neue Entitäten = typisiert.
|
||||
- **Pflicht (kein „optional"):** Der generische Builder MUSS vollständig abgelöst werden. Die bereits **gebauten** Konsumenten — EmailMarketing (AK-P14, dringend), WorkflowEngine, formulas, codeGenerator, onboarding, `CrmService`-Legacy — werden **typisiert abgelöst, sobald sie ohnehin angefasst werden** („Migration durch Neubau", billiger als späterer Refactor). Noch nicht gebaute Module (AK-P14b/P15/P16c/d/DEMO1) sowieso direkt typisiert.
|
||||
- Konsumenten-Matrix (rückwirkend vs. neu), Reihenfolge & Ownership: `docs/ARCHITECTURE-DECISIONS.md` AD-2 + `.planning/ticket-docs/R-P6B.md` §Migrationskette & Ownership / §Rückwirkungs-Audit.
|
||||
|
||||
## Daten-Fluss (verbindlich)
|
||||
|
||||
**Synchron im Loader.** Server bereitet das View-Model einmal auf, UI rendert. KEIN client-seitiges Re-Compute.
|
||||
@@ -200,7 +208,7 @@ Das Schema ist ein **Ordner** (`prisma/schema/`, Prisma 7), nicht eine Datei. Be
|
||||
- **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 (M083, M084)
|
||||
- **KEIN eigenes LLM/RAG/Whisper in v1/v2** (AD-26). HiveGrid wird stattdessen Remote-MCP-Server (`VR-MCP`/`VD-MCP`); externe KI-Clients bringen die Inferenz mit.
|
||||
- **JA** Email+Passwort + Magic-Link + TOTP (M020, M021, M022)
|
||||
- Hosting: Hetzner + Coolify (EU); Datenbank: in EU; Storage: Hetzner Object Storage / S3 (EU) — vgl. ADR-009 (löst den früheren Scaleway-Hosting-Plan ab)
|
||||
|
||||
@@ -307,9 +315,8 @@ kennzeichnen und vom **selbst machbaren** Rest trennen (z.B. „86 % done · 1 P
|
||||
**Code-Kommentare werden auf Englisch geschrieben** — passe dich der umgebenden Datei an, und
|
||||
der Code-Bestand ist praktisch durchgaengig englisch kommentiert (Messung 2026-06-19: nur ~1% der
|
||||
Quelldateien mit Kommentaren enthalten Deutsch, meist Alt-Bestand). Das gilt fuer `*.ts`/`*.tsx`,
|
||||
`*.prisma` sowie SQL/Migrations in `prisma/**`. Grund: dies ist ein git-Downstream der
|
||||
`@toolctrl`-Boilerplate (siehe Naming-Konvention) — englische Kommentare bleiben mergebar und
|
||||
konsistent mit upstream.
|
||||
`*.prisma` sowie SQL/Migrations in `prisma/**`. Grund: der ausführbare Code bleibt
|
||||
tool- und teamübergreifend konsistent; Projektkontext und Umsetzungsnotizen bleiben deutsch.
|
||||
|
||||
**Deutsch bleibt nur in den Projekt-Dokus:** `.planning/**` (inkl. `ticket-docs/`),
|
||||
`docs/**`, `_bmad-output/**`, `local/**`-Planungsartefakte sowie die Umsetzungs-Notizen und
|
||||
|
||||
Reference in new issue
Block a user