Architektur: Product-Design Monorepo¶

Status: Entwurf — Architekturentscheidung aus Session 2026-03-31 Betrifft: VisiFair, VisiMatch — Product-Design und Spec-Workflow Entscheidung: Ein Git-Monorepo pro Produkt mit LFS und Auto-Sync

1. Entscheidungskontext¶

Problem¶

VisiTrans betreibt 30+ Projekte pro Produkt (VisiFair, VisiMatch). Jedes Projekt durchläuft den Product-Design-Workflow (pd-0 → pd-6) und anschließend den Spec-basierten Entwicklungs-Workflow (activate → finalize). Dabei arbeiten 3–5 Personen gleichzeitig an verschiedenen Projekten.

Anforderungen: - Alle Beteiligten arbeiten auf dem aktuellen Stand der Dokumente - Kein zweites Storage-System parallel zu Git (OneDrive + Git = Verwirrung) - Workflow-Skills (Claude Code Toolkit) müssen funktionieren - Binäre Dateien (PDFs, Word, PowerPoint, Bilder) müssen verwaltbar sein - Setup-Aufwand pro Projekt muss minimal sein

Bewertete Alternativen¶

Alternative A: OneDrive als Single Source¶

Vorteil	Nachteil
Automatische Sync	Keine Branch-Isolation
Nicht-technische Nutzer kennen es	Kein Diff für Markdown
Binärdateien nativ	Workflow-Skills sind git-nativ → Rewrite nötig
Per-Folder-Berechtigungen	Keine Worktrees für parallele Arbeit

Bewertung: Ausgeschieden — würde vollständigen Rewrite aller Workflow-Skills erfordern. Branch-Isolation und Worktrees sind nicht ersetzbar.

Alternative B: Ein Git-Repo pro Projekt (30+ Repos)¶

Vorteil	Nachteil
Saubere Isolation	30+ Repos klonen und aktuell halten
Skills funktionieren ohne Änderung	Auto-Sync-Daemon für jedes Repo nötig
Bewährtes Muster (C035 heute)	Kein produktweiter Überblick über Specs
	Cross-Projekt-Dependencies nicht sichtbar
	GitHub-API-Rate-Limits bei 30 × fetch/60s

Bewertung: Funktional, aber operativ nicht skalierbar für 30+ Projekte mit 5 Personen.

Alternative C: Ein Git-Monorepo pro Produkt (gewählt)¶

Vorteil	Nachteil
Ein Clone, ein Sync-Punkt	Skills brauchen Projekt-Kontext-Erkennung
Produktweiter Spec-Überblick	`.design-state.yaml` wird komplexer
Cross-Projekt-Dependencies sichtbar	Kein Per-Folder-Zugriffsschutz (nur CODEOWNERS)
LFS für Binaries einmal konfiguriert	Repo-Größe wächst (beherrschbar mit LFS)
Worktrees für parallele Spec-Arbeit
Ein CLAUDE.md für alle Projekte

Bewertung: Gewählt — beste Balance aus Skalierbarkeit, Workflow-Kompatibilität und operativem Aufwand.

Entscheidung¶

Ein Git-Monorepo pro Produkt (visifair-product, visimatch-product) mit: - Git LFS von Anfang an für alle Binärdateien - Auto-Sync-Daemon für OneDrive-ähnliche Nutzererfahrung - Projektspezifische Spec-Nummerierung basierend auf bestehenden Projektnummern (C035, C041, etc.) - Code-Repos bleiben separat — Monorepo enthält nur PD- und Spec-Artefakte

2. Repo-Struktur¶

Verzeichnisbaum¶

visifair-product/
├── .gitattributes                     # LFS-Regeln (einmal, für alles)
├── .gitignore
├── .design-state.yaml                 # Produktweites Spec-Registry
├── CLAUDE.md                          # Monorepo-spezifische KI-Arbeitsregeln
├── projects.yaml                      # Projektnummern-Registry
│
├── projects/                          # Ein Ordner pro Projekt
│   ├── C035-consignee-landingpage/
│   │   ├── .design-state.yaml         # PD-Workflow-State (nur dieses Projekt)
│   │   ├── .claude-checkpoint.md      # Phase-Checkpoint (pro Projekt)
│   │   ├── 00-inbox/                  # Projekt-Inbox
│   │   ├── 01-meetings/               # Meeting-Protokolle
│   │   ├── 02-knowledge/              # Personas, Research, Interviews
│   │   │   ├── 02-zielgruppen-personas/
│   │   │   └── 04-dokumente/
│   │   ├── 03-prd/                    # PRD und PID
│   │   │   ├── PRD.md
│   │   │   ├── PID.md
│   │   │   └── PRD-DELTA.md
│   │   └── 06-handoff/                # Übergabepaket an Entwicklung
│   │
│   ├── C041-hall-planning/
│   │   └── ...
│   └── C042-visitor-management/
│       └── ...
│
├── specs/                             # Alle Specs produktweit, nach Projekt gruppiert
│   ├── C035-001-registration/
│   │   ├── spec.md
│   │   ├── state.yaml
│   │   ├── plan.md
│   │   └── tasks.md
│   ├── C035-002-booth-assignment/
│   ├── C041-001-seating-layout/
│   └── C042-001-ticketing/
│
└── docs/
    ├── decisions/                     # Architekturentscheidungen
    └── architecture/                  # Dieses Dokument

Strukturdiagramm¶

graph TB
    subgraph "visifair-product/ (Git Monorepo)"
        ROOT[".design-state.yaml<br/>CLAUDE.md<br/>.gitattributes (LFS)<br/>projects.yaml"]

        subgraph "projects/"
            P1["C035-consignee-landingpage/"]
            P2["C041-hall-planning/"]
            P3["C042-visitor-management/"]

            P1 --> P1DS[".design-state.yaml<br/>(PD-Workflow)"]
            P1 --> P1CP[".claude-checkpoint.md"]
            P1 --> P1IN["00-inbox/"]
            P1 --> P1PRD["03-prd/PRD.md"]
        end

        subgraph "specs/"
            S1["C035-001-registration/<br/>spec.md, plan.md, tasks.md"]
            S2["C035-002-booth-assignment/"]
            S3["C041-001-seating-layout/"]
        end

        ROOT --> P1
        ROOT --> P2
        ROOT --> P3
        ROOT --> S1
        ROOT --> S2
        ROOT --> S3
    end

    subgraph "Separate Repos (Code)"
        CODE1["visifair-exhibitor-app"]
        CODE2["visifair-hall-service"]
    end

    S1 -.->|"Specs referenzieren"| CODE1
    S3 -.->|"Specs referenzieren"| CODE2

Projektnummern-Registry (projects.yaml)¶

# projects.yaml — Zentrale Registry aller Projektnummern
# Projektnummern sind fix und werden nicht wiederverwendet

projects:
  C035:
    name: Consignee Landingpage
    path: projects/C035-consignee-landingpage
    status: active
    lead: rolf
  C041:
    name: Hall Planning
    path: projects/C041-hall-planning
    status: active
    lead: tbd
  C042:
    name: Visitor Management
    path: projects/C042-visitor-management
    status: planned
    lead: tbd

3. Git LFS-Konfiguration¶

Warum LFS von Anfang an¶

Nachträgliche LFS-Migration erfordert git lfs migrate import, was die gesamte Git-History neu schreibt. Alle Beteiligten müssten ihr Repo löschen und neu klonen. Bei 5 Personen und laufenden Feature-Branches ist das ein Breaking Change. Einrichtung bei Repo-Erstellung kostet 2 Minuten.

.gitattributes¶

# Textdateien — normal in Git
* text=auto

# ── Dokumente → LFS ──────────────────────────
*.pdf filter=lfs diff=lfs merge=lfs -text
*.docx filter=lfs diff=lfs merge=lfs -text
*.doc filter=lfs diff=lfs merge=lfs -text
*.pptx filter=lfs diff=lfs merge=lfs -text
*.ppt filter=lfs diff=lfs merge=lfs -text
*.xlsx filter=lfs diff=lfs merge=lfs -text
*.xls filter=lfs diff=lfs merge=lfs -text
*.odt filter=lfs diff=lfs merge=lfs -text

# ── Bilder → LFS ─────────────────────────────
*.png filter=lfs diff=lfs merge=lfs -text
*.jpg filter=lfs diff=lfs merge=lfs -text
*.jpeg filter=lfs diff=lfs merge=lfs -text
*.gif filter=lfs diff=lfs merge=lfs -text
*.bmp filter=lfs diff=lfs merge=lfs -text
*.tiff filter=lfs diff=lfs merge=lfs -text
*.ico filter=lfs diff=lfs merge=lfs -text
*.webp filter=lfs diff=lfs merge=lfs -text
*.svg filter=lfs diff=lfs merge=lfs -text

# ── Design-Dateien → LFS ─────────────────────
*.fig filter=lfs diff=lfs merge=lfs -text
*.sketch filter=lfs diff=lfs merge=lfs -text
*.psd filter=lfs diff=lfs merge=lfs -text
*.ai filter=lfs diff=lfs merge=lfs -text
*.xd filter=lfs diff=lfs merge=lfs -text

# ── Video/Audio → LFS ────────────────────────
*.mp4 filter=lfs diff=lfs merge=lfs -text
*.mov filter=lfs diff=lfs merge=lfs -text
*.avi filter=lfs diff=lfs merge=lfs -text
*.mp3 filter=lfs diff=lfs merge=lfs -text
*.wav filter=lfs diff=lfs merge=lfs -text

# ── Archive → LFS ────────────────────────────
*.zip filter=lfs diff=lfs merge=lfs -text
*.tar.gz filter=lfs diff=lfs merge=lfs -text
*.rar filter=lfs diff=lfs merge=lfs -text

Speicher-Limits¶

Plan	Inklusiv-Storage	Inklusiv-Bandwidth/Monat	Zusatzpakete
GitHub Free	1 GB	1 GB	$5/Monat pro 50 GB
Einzeldatei-Limit	2 GB	—	—
Hartes Maximum	Keins	—	Unbegrenzt zukaufbar

Erwarteter Verbrauch: Bei 30 Projekten mit hauptsächlich Markdown und gelegentlichen PDFs/Word-Dateien bleibt der LFS-Storage voraussichtlich lange unter 1 GB (Free-Tier).

Einrichtung pro Entwickler (einmalig)¶

git lfs install        # Einmalig pro Rechner
git clone <repo-url>   # LFS wird automatisch genutzt

4. Auto-Sync-Daemon¶

Ziel¶

Das Monorepo soll sich für alle Beteiligten wie ein OneDrive-Ordner anfühlen: Änderungen anderer Personen erscheinen automatisch, eigene Änderungen werden automatisch gepusht.

Konzept¶

Ein Hintergrund-Daemon, der als macOS Launch Agent bzw. Windows Task Scheduler läuft:

flowchart TD
    START[Daemon-Zyklus alle 60s] --> CHECK_BRANCH{Auf main Branch?}

    CHECK_BRANCH -->|Ja| FETCH[git fetch origin main]
    CHECK_BRANCH -->|Nein / Feature-Branch| FETCH_FEATURE[git fetch origin]

    FETCH --> COMPARE{Lokal = Remote?}
    COMPARE -->|Ja| CHECK_DIRTY{Lokale Änderungen?}
    COMPARE -->|Nein| PULL[git pull --ff-only]

    PULL --> PULL_OK{Pull erfolgreich?}
    PULL_OK -->|Ja| CHECK_DIRTY
    PULL_OK -->|Nein / Konflikt| NOTIFY_CONFLICT[Notification: Merge-Konflikt]

    CHECK_DIRTY -->|Ja| AUTO_COMMIT[git add + commit]
    CHECK_DIRTY -->|Nein| SLEEP[Warte 60s]

    AUTO_COMMIT --> PUSH[git push]
    PUSH --> PUSH_OK{Push erfolgreich?}
    PUSH_OK -->|Ja| SLEEP
    PUSH_OK -->|Nein| NOTIFY_PUSH[Notification: Push fehlgeschlagen]

    FETCH_FEATURE --> NOTIFY_BEHIND["Notification: Branch X commits hinter main"]
    FETCH_FEATURE --> SLEEP

    NOTIFY_CONFLICT --> SLEEP
    NOTIFY_PUSH --> SLEEP

Verhaltensregeln¶

Situation	Verhalten
Auf `main` Branch	Fetch + Pull --ff-only + Auto-Commit + Push
Auf Feature-Branch	Nur Fetch, kein Pull (Isolation bewahren)
Uncommitted Changes + Pull nötig	Skip Pull, Notification anzeigen
Merge-Konflikt	Stop, Notification, manuell lösen lassen
Kein Netzwerk	Skip, nächsten Zyklus abwarten
Worktree aktiv	Root-Repo und Worktree unabhängig behandeln

Auto-Commit-Regeln¶

Automatische Commits durch den Daemon verwenden ein einheitliches Format:

auto: sync [YYYY-MM-DD HH:MM] — <Anzahl> Dateien geändert

Einschränkungen: - Auto-Commit nur auf main Branch (nicht auf Feature-Branches) - Auto-Commit nur für Dateien in projects/ (nicht in specs/) - Specs werden bewusst manuell committed (Workflow-Gate-Enforcement)

Plattform-Implementierung¶

Plattform	Mechanismus	Konfiguration
macOS	LaunchAgent	`~/Library/LaunchAgents/com.visitrans.git-sync.plist`
Windows	Task Scheduler	Geplante Aufgabe, alle 60 Sekunden
Linux	systemd timer	`~/.config/systemd/user/git-sync.timer`

Offene Design-Entscheidungen¶

Soll der Daemon Husky-Pre-Commit-Hooks respektieren? (Empfehlung: Nein, da Auto-Commits nur Dokumente betreffen)
Soll der Daemon auf Feature-Branches Auto-Push machen? (Empfehlung: Nein, bewusst manuell)
Log-Rotation und -Aufbewahrung?

5. Skill-Impact-Analyse¶

Dieses Kapitel dokumentiert alle Auswirkungen des Monorepo-Ansatzes auf die bestehenden Workflow-Skills. Die Skills sind aktuell für das Modell "ein Repo = ein Projekt" gebaut und müssen für "ein Repo = viele Projekte" angepasst werden.

5.1 Projekt-Resolver: Neuer gemeinsamer Mechanismus¶

Problem: Alle Skills nehmen an, dass CWD = Projekt-Root ist. Im Monorepo ist CWD das Repo-Root, und der Projekt-Kontext muss explizit bestimmt werden.

Lösung: Ein "Projekt-Resolver" als gemeinsame Logik, die alle Skills nutzen:

Auflösungs-Reihenfolge:
1. --project C035 Flag (explizit)
2. Git Branch → feature/C035-001-* → Projektnummer C035 → projects.yaml → Pfad
3. CWD prüfen: Wenn CWD unter projects/C035-*/ liegt → C035
4. .active-project Datei im Repo-Root (Override/Escape-Hatch)
5. Fallback: Nutzer fragen

Projekt-Resolver liefert:

project_id: C035
project_name: Consignee Landingpage
project_path: projects/C035-consignee-landingpage/
specs_prefix: C035
design_state: projects/C035-consignee-landingpage/.design-state.yaml
checkpoint: projects/C035-consignee-landingpage/.claude-checkpoint.md
inbox: projects/C035-consignee-landingpage/00-inbox/

Betroffene Skills: Alle — der Projekt-Resolver ist die Grundlage für alle weiteren Änderungen.

Aufwand: Mittel — muss als gemeinsame Logik definiert werden, die alle Skills referenzieren.

5.2 Spec-Nummerierung: Projektnummer-Präfix¶

Aktuell:

SPEC-001, SPEC-002, ... SPEC-106 (global-sequenziell)
Branch: feature/spec-001-registration
Verzeichnis: specs/1-registration/

Neu:

C035-001, C035-002, C041-001 (Projektnummer-Präfix, pro Projekt sequenziell)
Branch: feature/C035-001-registration
Verzeichnis: specs/C035-001-registration/

Betroffene Skills und konkrete Änderungen:

Skill	Aktuelle Logik	Änderung
`/activate`	Scannt `specs/`, parsed `SPEC-(\d+)`	Scannt `specs/`, parsed `(C\d{3})-(\d+)`, filtert nach aktuellem Projekt
`/complete`	Parsed Branch `feature/spec-(\d+)-*`	Parsed Branch `feature/(C\d{3})-(\d+)-*`
`/specs-from-prd`	`max(alle SPEC-IDs) + 1`	`max(IDs mit gleichem Projekt-Präfix) + 1`
`/spec-from-requirements`	Gleiche ID-Logik wie specs-from-prd	Gleiche Änderung

ID-Generierung (neu):

1. Projekt-Resolver → project_id = "C035"
2. Scan specs/ nach C035-*
3. Finde höchste Nummer: C035-007
4. Nächste ID: C035-008

5.3 Branch-Naming¶

Aktuell:

feature/spec-NNN-slug
Regex: feature/spec-(\d+)-(.*)

Neu:

feature/C035-001-registration
Regex: feature/(C\d{3})-(\d{3})-(.*)

Betroffene Skills: - /activate — Branch-Erstellung - /complete — Branch-Erkennung und Abschluss - /phase-checkpoint — Branch-Name in Checkpoint schreiben - Alle Phase-Skills (2-plan, 3-build, 4-review, 5-finalize) — Branch-Name lesen und Spec-ID ableiten

Änderung: Regex-Update in allen Skills, die git branch --show-current parsen.

5.4 .design-state.yaml: Zwei Ebenen¶

Aktuell: Eine Datei im Repo-Root enthält sowohl PD-Workflow-State als auch Spec-Registry.

Neu: Zwei Dateien mit unterschiedlichen Verantwortlichkeiten:

Root-Level: `.design-state.yaml` (Spec-Registry)¶

# .design-state.yaml — Produktweites Spec-Registry
specs_directory: specs/

specs_status:
  C035-001:
    file: C035-001-registration/spec.md
    project: C035                          # NEU: Projekt-Zuordnung
    priority: P1
    status: completed
    dependencies: []
    specs_dir: specs/C035-001-registration/
    completed_date: 2026-04-15

  C035-002:
    file: C035-002-booth-assignment/spec.md
    project: C035
    priority: P2
    status: in_progress
    dependencies: [C035-001]

  C041-001:
    file: C041-001-seating-layout/spec.md
    project: C041
    priority: P1
    status: draft
    dependencies: []

Projekt-Level: `projects/C035-*/.design-state.yaml` (PD-Workflow-State)¶

# projects/C035-consignee-landingpage/.design-state.yaml
# PD-Workflow-State nur für dieses Projekt

project_id: C035
project_name: Consignee Landingpage
current_phase: pd-3-prototype

artifacts:
  prd:
    path: 03-prd/PRD.md
    version: 2.1
    status: approved
  prototype:
    path: ../../../../code-repos/visifair-exhibitor-app  # Verweis auf Code-Repo
    version: 0.3.0
    status: in_progress

quality_gates:
  pd-1-research: { status: passed, date: 2026-03-15 }
  pd-2-prd: { status: passed, date: 2026-03-22 }
  pd-3-prototype: { status: in_progress }

iterations:
  - trigger: stakeholder_feedback
    from_phase: pd-3
    to_phase: pd-2
    date: 2026-03-20
    reason: "Neue Compliance-Anforderung"

Betroffene Skills:

Skill	Liest	Schreibt	Änderung
`/pd-0-start`	—	Projekt-Level	Erstellt unter `projects/CNNN-*/` statt Repo-Root
`/pd-1-research` bis `/pd-6-handoff`	Projekt-Level	Projekt-Level	Pfad aus Projekt-Resolver statt CWD
`/activate`	Root-Level	Root-Level + Per-Spec state.yaml	Filtert Specs nach Projekt-Präfix
`/complete`	Root-Level	Per-Spec state.yaml	Keine Struktur-Änderung, nur ID-Format
`/pd-analyze-changes`	Projekt-Level	Projekt-Level	Pfad aus Projekt-Resolver
`/pd-inbox-scan`	Projekt-Level	Projekt-Level	Inbox-Pfad aus Projekt-Resolver

5.5 Checkpoint-System: Pro Projekt¶

Aktuell: Eine .claude-checkpoint.md im Repo-Root.

Neu: projects/C035-consignee-landingpage/.claude-checkpoint.md pro Projekt.

---
completed_phase: 3-build
completed_at: 2026-04-01T14:30:00Z
next_phase: 4-review
next_command: /vt-c-4-review
branch: feature/C035-002-booth-assignment   # Projekt-Präfix im Branch
active_spec: C035-002                       # Projekt-Präfix in Spec-ID
project: C035                               # NEU
project_path: projects/C035-consignee-landingpage/  # NEU
---

Betroffene Skills: - /phase-checkpoint — Schreibt Checkpoint unter Projekt-Pfad - Alle Phase-Skills — Lesen Checkpoint aus Projekt-Pfad

Änderung: Checkpoint-Pfad aus Projekt-Resolver statt hardcodiert Repo-Root.

5.6 Scaffold und Init: Zwei Ebenen¶

Repo-Init (einmal pro Monorepo):

/repo-init  →  erstellt:
  .gitattributes (LFS)
  .gitignore
  .design-state.yaml (leer)
  CLAUDE.md
  projects.yaml
  projects/    (leerer Ordner)
  specs/       (leerer Ordner)
  docs/

Projekt-Scaffold (pro Projekt):

/scaffold --project C035  →  erstellt unter projects/C035-consignee-landingpage/:
  .design-state.yaml (PD-Workflow)
  00-inbox/
  01-meetings/
  02-knowledge/
  03-prd/
  06-handoff/

Betroffene Skills:

Skill	Aktuelle Logik	Änderung
`/repo-init`	Erstellt alles im CWD	Zusätzlich: projects.yaml, LFS-Konfiguration
`/scaffold`	Erstellt Struktur im CWD	Neuer `--project`-Parameter; erstellt unter `projects/CNNN-*/`
`/pd-0-start`	Erstellt PD-Struktur im CWD	Erstellt PD-Struktur unter `projects/CNNN-*/`

5.7 Inbox: Pro Projekt¶

Aktuell: intake/inbox/ auf Toolkit-Ebene (gemeinsam).

Neu: projects/C035-consignee-landingpage/00-inbox/ pro Projekt.

Betroffene Skills: - /inbox-qualify — Inbox-Pfad aus Projekt-Resolver - /pd-inbox-scan — Scannt Projekt-spezifische Inbox

Hinweis: Eine produktweite Inbox (inbox/ im Repo-Root) kann zusätzlich bestehen bleiben für Themen, die keinem Projekt zugeordnet sind.

5.8 Worktrees: Keine Änderung nötig¶

Worktrees sind Branch-basiert, nicht Projekt-basiert. Ein Worktree für feature/C035-001-registration checkt das gesamte Monorepo aus, aber die Arbeit findet in specs/C035-001-*/ und projects/C035-*/ statt.

Keine Änderung an /git-worktree nötig.

5.9 Review und Finalize: Spec-ID-Format¶

Betroffene Skills: - /4-review — Parsed Spec-ID aus Branch; Regex-Update - /5-finalize — Validiert Gates; Spec-ID-Format-Update - /complete — Markiert Spec als completed; ID-Format-Update

Änderung: Rein kosmetisch — Regex von SPEC-(\d+) auf (C\d{3})-(\d{3}).

6. Zusammenfassung der Skill-Änderungen¶

Nach Priorität¶

Priorität	Änderung	Betroffene Skills	Aufwand
Hoch	Projekt-Resolver Mechanismus	Alle Skills (gemeinsame Logik)	Mittel
Hoch	Projektnummer-Präfix Spec-IDs	activate, complete, specs-from-prd, spec-from-requirements	Mittel
Hoch	Branch-Naming Regex	activate, complete, alle Phase-Skills	Klein
Mittel	Split .design-state.yaml	pd-0 bis pd-6, activate	Mittel
Mittel	Checkpoint pro Projekt	phase-checkpoint, alle Phase-Skills	Klein
Mittel	Scaffold mit --project	scaffold, pd-0-start, repo-init	Klein
Niedrig	Inbox pro Projekt	inbox-qualify, pd-inbox-scan	Klein

Nach Skill¶

Skill	Änderungen	Aufwand
`/activate`	Projekt-Resolver, Spec-ID-Prefix, Branch-Regex, .design-state-Filter	Hoch
`/complete`	Branch-Regex, Spec-ID-Format	Klein
`/specs-from-prd`	ID-Generierung mit Projekt-Präfix	Mittel
`/spec-from-requirements`	ID-Generierung mit Projekt-Präfix	Mittel
`/scaffold`	--project Parameter, Pfad-Logik	Mittel
`/pd-0-start`	Projekt-Pfad, .design-state unter Projekt	Mittel
`/pd-1-research` bis `/pd-6-handoff`	Pfade aus Projekt-Resolver	Klein pro Skill
`/phase-checkpoint`	Checkpoint-Pfad aus Projekt-Resolver	Klein
`/inbox-qualify`	Inbox-Pfad aus Projekt-Resolver	Klein
`/pd-inbox-scan`	Inbox-Pfad aus Projekt-Resolver	Klein
`/pd-analyze-changes`	State-Pfad aus Projekt-Resolver	Klein
`/repo-init`	LFS-Setup, projects.yaml, Monorepo-Struktur	Mittel
`/git-worktree`	Keine Änderung	—
`/4-review`	Branch-Regex	Klein
`/5-finalize`	Branch-Regex, Gate-Pfade	Klein

Skills ohne Änderungsbedarf¶

/git-worktree — Branch-basiert, nicht Projekt-basiert
/2-plan — Arbeitet relativ zu Spec-Verzeichnis (bleibt gleich)
/3-build — Arbeitet relativ zu Spec-Verzeichnis (bleibt gleich)
Alle Review-Agents (kieran-rails-reviewer, etc.) — Arbeiten auf Code-Diff, nicht auf Projektstruktur

7. Migrationspfad¶

Phase 1: Architektur-Dokument (dieses Dokument)¶

Entscheidung dokumentiert und abgestimmt
Skill-Impact-Analyse vollständig

Phase 2: Repo-Template erstellen¶

Monorepo-Grundstruktur mit .gitattributes, CLAUDE.md, projects.yaml
Template für Projekt-Ordner (projects/CNNN-*/)
.design-state.yaml Vorlagen (Root + Projekt)

Phase 3: Skill-Anpassungen¶

Zuerst: Projekt-Resolver als gemeinsame Logik (alle Skills hängen davon ab)
Dann: /activate und /complete (Kern-Workflow)
Dann: /scaffold, /repo-init, /pd-0-start (Projekt-Setup)
Dann: PD-Skills (pd-1 bis pd-6), Checkpoint, Inbox
Zuletzt: Review/Finalize (nur Regex-Update)

Phase 4: Auto-Sync-Daemon¶

macOS Launch Agent implementieren
Windows Task Scheduler implementieren
Logging und Notification
Deployment-Anleitung für alle Teammitglieder

Phase 5: Pilot-Migration¶

Ein bestehendes Projekt (z.B. C035 Consignee Landingpage) in Monorepo-Struktur migrieren
Workflow durchspielen: pd-0 → pd-6 → activate → finalize
Erkenntnisse in Architektur zurückspeisen

Phase 6: Rollout¶

Alle Projekte migrieren
Alte Einzelrepos archivieren
Team-Schulung (Git-Grundlagen für nicht-technische Beteiligte)

8. Offene Fragen und Risiken¶

Offene Entscheidungen¶

Frage	Optionen	Empfehlung
Projektnummern-Registry: Wer vergibt C-Nummern?	Manuell in projects.yaml / Automatisch bei `/pd-0-start`	Manuell mit Validierung
Cross-Projekt-Dependencies: C041-003 depends on C035-001?	Erlauben / Nur innerhalb eines Projekts	Erlauben — ein zentraler Spec-Überblick ist genau der Vorteil des Monorepos
Auto-Commit-Scope: Was wird automatisch committed?	Alles / Nur projects/ / Nur bestimmte Dateitypen	Nur `projects/` (Specs bleiben manuell)
Prototype-Verzeichnis: Wo liegt der Prototyp?	Im Monorepo / Im Code-Repo / Eigenes Repo	Im Code-Repo (Prototyp wird zu Code; Monorepo enthält nur PD-Artefakte)

Risiken¶

Risiko	Wahrscheinlichkeit	Impact	Mitigation
`.design-state.yaml` Merge-Konflikte bei 5 gleichzeitigen Nutzern	Mittel	Niedrig	YAML mit einem Block pro Spec — Konflikte sind lokalisiert und einfach lösbar
Repo-Größe wächst durch Binaries trotz LFS	Niedrig	Mittel	Monitoring; LFS verlagert Größe auf Storage-Server
Auto-Sync-Daemon erzeugt unerwartete Commits	Mittel	Mittel	Daemon nur auf `main`; klares Commit-Prefix `auto:`; nur `projects/`
Nicht-technische Nutzer kommen mit Git nicht zurecht	Hoch	Hoch	Auto-Sync-Daemon macht Git unsichtbar; Schulung; Finder/Explorer-Ansicht identisch
Spec-Nummerierung kollidiert bei paralleler Erstellung	Niedrig	Niedrig	ID-Generierung scannt bestehende IDs; bei Konflikt inkrementiert

Anhang A: Abgrenzung der Repo-Typen¶

┌─────────────────────────────────┐
│  Product Monorepo               │
│  (visifair-product)             │
│                                 │
│  Enthält:                       │
│  - PRDs, Personas, Research     │
│  - Specs (Anforderungen)        │
│  - Meeting-Protokolle           │
│  - Architekturentscheidungen    │
│  - PD-Workflow-State            │
│                                 │
│  Enthält NICHT:                 │
│  - Quellcode                    │
│  - Prototypen (node_modules)    │
│  - CI/CD-Pipelines             │
│  - Tests                        │
└──────────────┬──────────────────┘
               │ Specs referenzieren
               ▼
┌─────────────────────────────────┐
│  Code-Repos (separat)           │
│  (visifair-exhibitor-app)       │
│  (visifair-hall-service)        │
│                                 │
│  Enthält:                       │
│  - Quellcode                    │
│  - Tests                        │
│  - CI/CD                        │
│  - Prototypen                   │
│  - Deployments                  │
└─────────────────────────────────┘

Anhang B: Vergleich Ist- vs. Soll-Zustand¶

Aspekt	Ist (C035 heute)	Soll (Monorepo)
Repo-Anzahl	1 pro Projekt	1 pro Produkt
.design-state.yaml	1 Datei, alles drin	2 Ebenen (Root: Specs, Projekt: PD-State)
Spec-IDs	SPEC-001 (global)	C035-001 (projekt-scoped)
Branch-Name	feature/spec-001-*	feature/C035-001-*
Checkpoint	Repo-Root	projects/C035-*/.claude-checkpoint.md
Inbox	intake/inbox/ (Toolkit)	projects/C035-*/00-inbox/
Binaries	Im Git (ohne LFS)	Git LFS
Sync	Manuell (git pull)	Auto-Sync-Daemon
Projekt-Erkennung	CWD = Projekt	Projekt-Resolver (Branch/CWD/Flag)