Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/INTERIM-HANDOVER-GUIDE.md
T

6.4 KiB
Raw Blame History

Interim-UI → David-Handover — Agent-Anleitung

Zweck: Wenn ein Ticket mit einer Interim-UI (Vorschau-Screen aus ~/ui, AD-28) fertig wird, kann der Interim-Screen an Designer David übergeben werden, damit er die finale Subframe-Optik bauen kann. Diese Doc ist die Schritt-für-Schritt-Anleitung, wie ein Agent diese Übergabe erzeugt. Basis-Regeln: INTERIM-UI-PLAYBOOK.md

  • INTERIM-UI-DESIGN-STANDARDS.md.

Wann triggern: Immer wenn im Zuge eines Tickets mindestens ein Interim-Screen (apps/web/app/components/screens/<domain>/<Screen>Page.tsx) neu entsteht. Nicht ungefragt bauen — das ist Arbeit außerhalb des Ticket-Scopes. Der Agent fragt den User (Rückfrage), ob zusätzlich die zwei Handover-Artefakte erzeugt werden sollen. Erst nach explizitem OK ausführen.

Was erzeugt wird — zwei Artefakte

  1. One-Liner Brief-Pointer — eine Zeile im passenden .planning/designer-briefs/PXX-*.md dieses Repos, die David von seinem gewohnten Intake-Kanal auf die Handover-Seite verweist. (Lokale Doc-Änderung in HiveGrid-Cloud; erreicht David beim nächsten git pull seines gebundelten hivegrid-cloud/-Checkouts.)
  2. Handover-Seite — eine Domänen-Seite in Davids Vault ../HiveGrid-Wireframes/Tickets/Interim-Handover/PXX-<Domain>.md mit je Screen: D-*-Ziel, Archetyp, Route, VM-Quelle, benötigte ~/ui-Elemente, Actions, States, leerer „Davids Delta"-Block. Plus eine Zeile im INDEX.md desselben Ordners.

Grundregel (Designer-First): Die Handover-Seite listet nur Elemente / Daten / Aktionen / States — NIE Layout. Anordnung ist Davids freie Hand.

Schritt 0 — Rückfrage an den User

Melde: „Für Ticket <ID> ist eine Interim-UI (<N> Screen(s) in screens/<domain>/) entstanden. Soll ich zusätzlich (a) den One-Liner-Brief-Pointer in designer-briefs/<PXX>.md und (b) die David-Handover-Seite in ../HiveGrid-Wireframes/Tickets/Interim-Handover/ erzeugen?" — Erst bei OK weiter.

Kläre bei OK zwei Dinge: welcher Designer-Brief PXX und welches D-*-Ziel-Ticket die Domäne hat (steht im Header-Kommentar der <Screen>Page.tsx und in der Ticket-Doc). Bei Unklarheit nachfragen.

Schritt 1 — Screens extrahieren (read-only)

Für jede apps/web/app/components/screens/<domain>/<Screen>Page.tsx (Test-/reine Helfer-Dateien wie DateField überspringen) diese Felder rein aus dem Code ziehen — nichts raten:

Feld Quelle im Code
D-*-Ziel + Archetyp (A1–A7) Header-Kommentar oben in der <Screen>Page.tsx (nennt „D-… , archetype A…")
Route(n) passende Datei unter apps/web/app/routes/app.$tenant/<domain>.*.tsx (bzw. routes/admin/* für Admin-Host)
Daten (VM) der aus @hivegrid/view-models importierte VM-Typ + Quelle packages/view-models/src/<domain>/*.vm.ts
Benötigte UI-Elemente die ~/ui/components/*-Imports + @subframe/core-Icon-Imports (= das, was David nachbauen muss)
Interaktionen (Actions) die exportierte …Actions-Typ-Shape (Callback-Namen + Argumente); bei server-<form>-Screens die intent-Werte
States Empty / Loading / Permission-Denied(404) — im JSX belegt (EmptyState, status!=="ready", Guard/404)

Bei vielen Screens: pro Domäne einen read-only Subagenten parallel laufen lassen, der die Datensätze im unten stehenden Format zurückgibt. Keine Datei editieren, nur lesen + Markdown zurückliefern.

Schritt 2 — Handover-Seite schreiben (in Davids Vault)

Lege bei Bedarf ../HiveGrid-Wireframes/Tickets/Interim-Handover/ an. Schreibe PXX-<Domain>.md mit Kopf-Notiz

  • je Screen einem ###-Record nach dieser Vorlage:
# PXX · <Domäne> (<Bau-Ticket> → <D-*-Ziel>)

> Interim-UI-Referenz (AD-28). Lauffähige `~/ui`-Vorschau-Screens (VM als Prop) im gebundelten
> `03 Quellen und Referenzen/hivegrid-cloud/`-Checkout. **Layout = Davids freie Hand.**

### <ScreenName> · <D-*-Screen-Titel + Archetyp>
- **Interim-Screen:** `apps/web/app/components/screens/<domain>/<Screen>Page.tsx`
- **Route(n):** `<url>` (`routes/app.$tenant/<file>.tsx`)
- **Daten (VM):** `<VMTypeName>` — `packages/view-models/src/<domain>/<file>.vm.ts`
- **Benötigte UI-Elemente (KEIN Layout):** <~/ui-Komponenten> · Icons: <Icons>
- **Interaktionen (Actions):** <callbackName(args), …>
- **States:** <Empty / Loading / Permission-Denied(404) — was zutrifft>
- **Davids Delta (offen):**
  - [ ] Überschriebene/geänderte Spec-Punkte:
  - [ ] Neue UI/UX-Entscheidungen:
  - [ ] Subframe-Screen-Link(s):
  - [ ] Offene Fragen an Dev:

Danach im INDEX.md desselben Ordners je Screen eine Zeile ergänzen (anlegen, falls INDEX noch fehlt — mit Intro „Was ist das?" + Domänen-Übersichtstabelle + Screen-Index):

| <ScreenName> | <D-*> | <Ax> | <Route> | offen |

Ist die Domäne bei David bereits fertig (D-* liegt als Tickets/Fertige Tickets/D-*.md vor), Status-Spalte = David fertig und Kopf-Notiz „dient dem Konsistenz-Abgleich, kein neuer Design-Request".

Schritt 3 — One-Liner Brief-Pointer setzen (in diesem Repo)

Im passenden .planning/designer-briefs/PXX-*.md direkt unter die **Subframe:**-Zeile des Kopfblocks diese eine Zeile splicen (chirurgisch, keine JSON-/Struktur-Umbauten):

🖥️ **Interim-UI gebaut (AD-28):** lauffähige Screen-Referenz + genutzte Elemente/VM/Actions in `../HiveGrid-Wireframes/Tickets/Interim-Handover/PXX-<Domain>.md`. Layout bleibt frei.

Schritt 4 — Ausliefern

  • Handover-Seite(n) + INDEX liegen in Davids Vault (eigenes Repo). Auf einem eigenen Branch committen (z.B. interim-ui-handover), nicht auf main. Der Push/PR gehört dem User — Push nur mit expliziter Freigabe; im Zweifel Branch + Commit lokal lassen und dem User den Push-Befehl geben: git -C ../HiveGrid-Wireframes push -u origin <branch>.
  • Brief-Pointer ist eine Doc-Änderung in diesem Repo (HiveGrid-Cloud) — läuft über den normalen Ticket-/Commit-Flow dieses Repos, nicht in den gebundelten hivegrid-cloud/-Checkout des Vaults schreiben (der ist read-only / nur-zum-Pullen).

Verifikation

  • Jede <Screen>Page.tsx der Domäne taucht genau einmal in Handover-Seite und INDEX auf (Gegencheck: ls apps/web/app/components/screens/<domain>/*Page.tsx).
  • Jedes D-*-Ziel + Archetyp stammt aus dem Header-Kommentar (nicht geraten).
  • Kein Layout in der Handover-Seite (nur Elemente/Daten/Actions/States).
  • Brief-Pointer greppbar: grep -rl "Interim-Handover" .planning/designer-briefs/.