Standardize documentation with headers and archive old files

Applied a unified header format to all documentation files for better status identification, referencing, and ownership tracking. Archived outdated roadmaps, reports, and journal entries. Updated playbooks with new responsibilities, lifecycle rules, and consistent handover formats to align with the new archiving strategy.
2026-01-16 12:17:47 +01:00
parent 39ba21fd77
commit 3465cab246
23 changed files with 393 additions and 212 deletions
@@ -0,0 +1,44 @@
+# Journal: Ideen zur Verbesserung der Agenten-Zusammenarbeit
+
+**Datum:** 15.01.2026
+**Autor:** Documentation & Knowledge Curator
+**Kontext:** Analyse des Status Quo der Agenten-Playbooks und Prozessoptimierung.
+
+## 1. Status Quo Analyse
+
+Die aktuelle Struktur mit spezialisierten Agenten-Playbooks (`docs/04_Agents/Playbooks/`) und einer zentralen Dokumentation (`docs/`) ist sehr solide.
+- **Stärken:** Klare Verantwortlichkeiten, "Docs-as-Code" als Fundament, Unterscheidung zwischen Konzept (Gemini) und Umsetzung (Junie).
+- **Potenzial:** Die Schnittstellen zwischen den Agenten (Handover) sind implizit definiert, könnten aber formalisiert werden, um Reibungsverluste zu minimieren.
+
+## 2. Vorschläge zur Verbesserung
+
+### A. Formalisierte Handover-Artefakte
+Statt nur Text zu übergeben, sollten Agenten strukturierte Formate nutzen, die vom nächsten Agenten direkt weiterverarbeitet werden können.
+
+*   **Domain Expert -> Backend/QA:**
+    *   Statt Prosa: Nutzung von **Gherkin** (Given/When/Then) für Akzeptanzkriterien.
+    *   Vorteil: QA kann dies direkt in Tests überführen, Backend Dev versteht die Edge-Cases.
+    *   *Beispiel:* `docs/03_Domain/UseCases/UC001_Nennung.feature`
+
+*   **Architect -> Devs:**
+    *   Statt nur ADR-Text: Bereitstellung von **PlantUML/Mermaid** Diagrammen, die ins Repo eingecheckt werden.
+    *   Vorteil: Visualisierung ist direkt in der Doku eingebunden und versioniert.
+
+### B. Cross-Agent Review Checklisten
+Jedes Playbook könnte eine kurze "Pre-Flight Checklist" erhalten, bevor ein Task als "Done" markiert wird.
+
+*   *Backend Dev:* "Habe ich die API-Änderungen mit dem Frontend-Expert (bzw. dessen Doku) abgeglichen?"
+*   *Architect:* "Habe ich das ADR vom Domain Expert auf fachliche Korrektheit prüfen lassen?"
+
+### C. "Session Context" Header
+Um den Kontext für die KI-Modelle (Junie/Gemini) schneller herzustellen, könnte ein standardisierter Header für Prompts etabliert werden, der auf die relevanten Doku-Pfade verweist.
+
+*   *Idee:* Ein kleines "Context-File" oder ein Abschnitt im Journal, der sagt: "Wir arbeiten gerade an Feature X, relevante Doku ist A, B und C."
+
+### D. Explizite "Shift-Left" QA
+Der **QA Specialist** wird oft erst am Ende aktiv. Er sollte explizit aufgefordert werden, schon während der **Domain-Analyse** Fragen zu stellen ("Wie testen wir das?", "Brauchen wir Testdaten dafür?").
+
+## 3. Nächste Schritte
+1.  Diskussion dieser Vorschläge mit dem Lead Architect (User).
+2.  Bei Zustimmung: Ergänzung der Playbooks um die spezifischen Handover-Formate und Checklisten.
+3.  Pilotierung des "Gherkin-Handovers" bei der nächsten fachlichen Anforderung.
@@ -0,0 +1,49 @@
+# Journal: Strategie für Archivierung und Dokumenten-Lifecycle
+
+**Datum:** 15.01.2026
+**Autor:** Documentation & Knowledge Curator
+**Kontext:** Entwicklung einer Strategie zur Handhabung veralteter Dokumente (ToDos, Roadmaps) und Vereinheitlichung des Dokumenten-Status.
+
+## 1. Problemstellung
+Aktuell existieren Dokumente wie `MASTER_ROADMAP_2026_Q1.md` neben älteren Roadmaps oder Status-Reports. Es ist nicht immer sofort ersichtlich, was "Single Source of Truth" (SSOT) ist und was historische Relevanz hat.
+Zudem fehlen einheitliche Header, die den Status eines Dokuments (z.B. "DRAFT", "ACTIVE", "DEPRECATED") auf den ersten Blick klarmachen.
+
+## 2. Lösungsansatz: Lifecycle-Management
+
+### A. Ordner-Struktur für Archivierung
+Wir führen in jedem Hauptbereich (`01_Architecture`, `05_Backend`, etc.) einen Unterordner `_archive/` ein.
+*   **Regel:** Sobald ein Dokument (z.B. eine Roadmap oder eine ToDo-Liste) abgearbeitet oder obsolet ist, wird es **nicht gelöscht**, sondern in den `_archive/`-Ordner verschoben.
+*   **Benennung:** Beim Verschieben wird das Datum vorangestellt: `YYYY-MM-DD_OriginalName.md`.
+
+### B. Standardisierter Header (Frontmatter-Style)
+Jedes Dokument erhält einen standardisierten Header-Block ganz oben.
+
+```markdown
+---
+type: [Roadmap | Concept | Reference | ADR | Report]
+status: [DRAFT | ACTIVE | DEPRECATED | ARCHIVED]
+owner: [Rolle, z.B. Lead Architect]
+last_update: YYYY-MM-DD
+context: [Link zu Ticket/Epic oder "General"]
+---
+```
+
+*   **ACTIVE:** Die aktuelle Wahrheit. Darf nur einmal pro Thema existieren (SSOT).
+*   **DEPRECATED:** Noch gültig, aber Ablösung geplant.
+*   **ARCHIVED:** Historisch, nur noch zum Nachlesen. (Liegt idealerweise im `_archive/` Ordner).
+
+### C. Umgang mit ToDo-Listen
+ToDo-Listen in Markdown-Dateien neigen dazu, zu veralten.
+*   **Strategie:** ToDos gehören primär in den Issue-Tracker (wenn vorhanden) oder in die `MASTER_ROADMAP`.
+*   **Temporäre ToDos:** Wenn ToDos in Konzepten stehen, müssen sie bei Abschluss in die Roadmap oder das Backlog überführt werden. Das Dokument selbst wird dann zum "Reference"-Dokument (ohne offene ToDos) oder archiviert.
+
+## 3. Umsetzungsschritte
+
+1.  **Curator Playbook Update:** Der Curator ist verantwortlich für das Verschieben in `_archive/` am Ende einer Session.
+2.  **Template Erstellung:** Definition des Standard-Headers für alle neuen Dokumente.
+3.  **Cleanup:** Einmaliges Aufräumen der bestehenden Ordner (`01_Architecture`, `90_Reports`).
+
+## 4. Beispiel-Workflow
+1.  Architect erstellt `Roadmap_Q1.md` (Status: ACTIVE).
+2.  Quartal endet. Architect erstellt `Roadmap_Q2.md`.
+3.  Curator verschiebt `Roadmap_Q1.md` nach `01_Architecture/_archive/2026-03-31_Roadmap_Q1.md` und setzt Status auf ARCHIVED.
@@ -0,0 +1,35 @@
+# Session Log: Prozess-Optimierung & Cleanup
+
+**Datum:** 15.01.2026
+**Autor:** Documentation & Knowledge Curator
+**Thema:** Verbesserung der Agenten-Kollaboration und Dokumentations-Hygiene.
+
+## 1. Zusammenfassung
+In dieser Session wurden die Arbeitsabläufe der KI-Agenten optimiert und die Projektdokumentation grundlegend aufgeräumt. Ziel war es, Reibungsverluste bei der Übergabe (Handover) zu minimieren und eine klare Unterscheidung zwischen "aktuell" und "veraltet" zu schaffen.
+
+## 2. Durchgeführte Änderungen
+
+### A. Agent Playbooks (Prozess)
+Alle Playbooks in `docs/04_Agents/Playbooks/` wurden aktualisiert:
+*   **Domain Expert:** Nutzt nun **Gherkin** für Requirements-Handover.
+*   **Architect:** Liefert Diagramme (Mermaid/PlantUML) statt nur Text.
+*   **QA Specialist:** "Shift-Left" Ansatz (Prüfung schon während der Analyse).
+*   **Devs (Backend/Frontend/DevOps):** Einführung von **Pre-Flight Checks** vor der Umsetzung.
+*   **Curator:** Neue Rolle als **Quality Gate** für Dokumentations-Standards.
+
+### B. Dokumentations-Strategie
+*   **Archivierung:** Einführung von `_archive/` Unterordnern in allen Bereichen. Veraltete Dokumente werden nicht gelöscht, sondern verschoben (mit Datums-Präfix).
+*   **Standard-Header:** Jedes Dokument muss nun einen YAML-Frontmatter Header haben (`status: ACTIVE | ARCHIVED`, `owner`, `last_update`).
+*   **Single Source of Truth:** Die `MASTER_ROADMAP` wurde als alleinige Quelle für die Planung etabliert.
+
+### C. Cleanup
+Folgende Bereiche wurden bereinigt und archiviert:
+*   `01_Architecture`: Alte Roadmaps archiviert.
+*   `05_Backend`: Alte Roadmap archiviert.
+*   `90_Reports`: Veraltete Status-Reports archiviert.
+*   `06_Frontend` & `07_Infrastructure`: Header aktualisiert.
+
+## 3. Ergebnis
+Das Projekt verfügt nun über einen sauberen, konsistenten Dokumentations-Stand. Die Regeln für die Zusammenarbeit der Agenten sind formalisiert und in den Playbooks verankert.
+
+**Status:** ✅ Session erfolgreich abgeschlossen.