agents.md — Konventionen für KI-Agenten und Coding-Agenten

Dieses Dokument beschreibt, wie ein KI-Agent (Claude, Codex, Cursor, Continue, etc.) in diesem Repo arbeitet. Es ist verbindlich für jede Session und sollte beim Start jeder neuen Konversation mitgelesen werden — typischerweise zusammen mit HANDOFF.md. Es ist unsere „Way of Working" und wird laufend aktuell gehalten: ändert sich, wie wir zusammenarbeiten, landet es hier (kein paralleles Prozess-Doc — Decision-Sprawl vermeiden, §5.2).

---

1. Repo-Philosophie: „Everything as Code"

Alle Artefakte des Projekts leben im Repo: Spezifikation, Entscheidungen, Architektur, Code, Diagramme, Konventionen. Nichts Überlebenswertes verbleibt im flüchtigen Konversations-Verlauf oder im Session-Memory einer einzelnen Cowork/Claude-Instanz.

Konsequenzen:

• GitHub drkv-com/taktano ist die einzige Quelle der Wahrheit.
• Eine neue Session startet nicht „bei null" — sie liest HANDOFF.md und docs/fachlich/Lastenheft.md und ist sofort im Kontext.
• Wenn etwas entschieden wird, landet es als Commit im Repo, bevor die Konversation endet.

2. Doku-Format: Markdown + Mermaid (kein .docx, kein .pdf)

Regel: Alle versionierten Dokumente sind .md mit Inline-Mermaid für Diagramme. Keine binären Formate (.docx, .pdf, .pptx, .xlsx) als Master-Quelle. Falls ein externer Stakeholder PDF/Word braucht, kann es bei Bedarf aus dem .md exportiert werden (pandoc, Mermaid-CLI für SVG-Diagramme, etc.).

Begründung:

• Git-diffbar, reviewable, mergeable.
• Diagramme als Code (Mermaid) sind genauso versioniert wie der Prosa-Text.
• Coding-Agenten können .md direkt lesen, ändern und Diffs erzeugen.
• Keine Tooling-Abhängigkeit (Word, LibreOffice, Adobe).

Mermaid-Typen, die wir im Repo verwenden:

Typ	Wofür
flowchart	Use-Cases, Architektur, Ampel-Logik
erDiagram	Datenmodell, Entitäts-Beziehungen
stateDiagram-v2	Lifecycle (Auftrag, Teilschritt)
sequenceDiagram	Interaktionen (Protokoll-Submit, Scheduler-Calls)
gantt	Zeitliche Abläufe (Teilschritt + Cool-down im Bay)
pie	nur falls aussagekräftig — selten sinnvoll

2.1 Doku-Navigation: Frontmatter, Kopf-Block, Landkarte

Damit die Doku navigierbar bleibt (nicht nur ist), gelten für jede Datei unter docs/:

1. YAML-Frontmatter ganz oben (Maschinen-/Sidebar-Belange, minimal halten):

   ---
   sidebar_position: 20            # 10er-Schritte = Lesereihenfolge (nicht alphabetisch)
   sidebar_label: Kurz-Label       # nur falls die H1 für die Sidebar zu lang ist
   ---

   Kein title: im Frontmatter — der Titel wird aus der ersten H1 abgeleitet (Single Source). sidebar_position in 10er-Schritten, damit neue Docs ohne Umnummerieren einsortieren.

2. Sichtbarer Kopf-Block in docs/architektur/*.md direkt nach der H1 (rendert auch auf GitHub, Selbsterklärbarkeit) — kanonischer Standard (seit 07-12, Doku-Review E6; per Warn-Gate in check-doc-consistency.sh erzwungen; für andere schwere docs/-Dokumente empfohlen, dort ohne Gate-Pflicht):

   > **Status:** <ehrlich: Design (kein Code) / in Umsetzung, Slice X ✅ / gebaut (vX) / lebend> ·
   > **Bezug:** <Owning-OP + wichtigste IDs> · **Zielgruppe:** <Rolle(n) der sieben Leserkreise> ·
   > **True North:** <ehrlicher Halbsatz — welche Leitfrage, direkt/indirekt; „nur indirekt" ist ok>
   
   > **Kernaussage.** <2–5 Sätze, Antwort/Entscheidung zuerst (Minto)>

   Genau eine Kernaussage je Doc, exakt im Format > **Kernaussage.** (keine Varianten wie ## Kernaussage-Headings oder > **Zweck.**). Bewusst zwei getrennte Blockquotes (Metadaten-Box + Kernaussage-Box, Vorbild Doku-UX-Konzept.md) — der markdownlint-Hinweis MD028 („blank line in blockquote") ist hier kein Fehler, sondern Design. Status/Stand ändern sich oft → bewusst sichtbar (Diff = Audit); Gebaut vs. Geplant nie vermischen (Status-Ehrlichkeit).

3. Landkarte & Sidebar pflegen: neues Doc in den passenden Unterordner legen, in docs/README.md eintragen, und (neuer Ordner) ein _category_.json mit label/position/link: generated-index anlegen.

4. Begriffe & IDs: neuen Fachbegriff in docs-site/src/glossar/glossar.mjs ergänzen (Single Source → generiertes glossar/Glossar.md + Begriffs-Sprechblasen, npm run glossar); bekommt ein OP ein eigenes Dokument, die Zeile in IDs.md (OP → Owning-Doc) ergänzen.

5. OP-Listen tragen klickbare OP-ID-Sprünge (verbindlich). In jeder OP-Liste in der Doku ist die OP-ID selbst ein Hyperlink zum direkten Sprung an ihr Zuhause — konkret:

   • Navigations-Indizes Register.md §1 + IDs.md-Reverse-Lookup: OP-ID → Owning-Doc, sonst das Issue (#n) bzw. per-OP-Anker in Lastenheft §11 (#op-<id>, fachliches Detail); Familien-/Sammelzeilen (OP-R*-*) → passender §11-Sektions-Anker (#11-1-auftraege … #11-10-tests-qs).
   • Volle OP-Liste Offene-Punkte.md (erzeugt aus den Issues, TKT-D-862): jede OP-ID verlinkt ihr Issue; ein **Detail:**-Link im Issue zeigt aufs Owning-Doc bzw. Lastenheft-§11-#op-<id>. (Das frühere HANDOFF-§4-Archiv ist seit 07-12 vollständig migriert.)
   • Fachliche Master-Liste Lastenheft §11: jede führende OP-ID trägt einen expliziten <a id="op-<id>">-Anker (präzises Sprungziel; Sektions-Anker {#11-x-…} zusätzlich).

   Neue/umziehende OPs immer so verlinken + verankern (kein blanker `OP-…`-Code ohne Link/Anker). Anker sind explizite {#…}-Heading-Anker bzw. inline <a id> (stabil, Docusaurus).

Der mechanische Teil (Landkarte-Vollständigkeit, Frontmatter-Präsenz, _category_.json) wird von scripts/check-doc-consistency.sh geprüft (harte Teilmenge blockt in CI, Rest warnt — OP-DOCS-9/-14, §5.1).

3. Identifikator-System

Jede Entscheidung, jedes Feld, jede Empfehlung, jeder offene Punkt hat eine kurze stabile ID. Diese IDs sind über das gesamte Repo durchsuchbar und werden in Commits, PRs, Issues, Chats referenziert.

Präfix	Bedeutung	Quelle
G-n	Globales Prinzip	Lastenheft §3
Rx	Modul (R1 Mitarbeiter, R2 Arbeitsplätze, …)	Lastenheft §4–5
Rx-F##	Feld einer Entität	Lastenheft Tabellen
Rx-S##	Sub-Entität / Tab	Lastenheft
A-n	Architektur-Empfehlung	Lastenheft §9
S-n	Vereinfachung gegenüber Altsystem	Lastenheft §10
UC-x	Kern-Use-Case	Lastenheft §2
OP-Rx-n / #n	Offener Punkt	GitHub-Issue (Label offener-punkt, seit TKT-D-862); Alt-ID → Issue via issue: in ops/<ID>.md (eingefroren; fachliches Detail oft Lastenheft §11)
FR-n	Future-Release-Note	Lastenheft §12
FM-n	Future-Module-Note	Lastenheft §12

Regel für Commits: Wenn ein Commit eine entscheidung-relevante Änderung vornimmt, ID(s) in der Commit-Message nennen, z. B.:

Resolve OP-R7-8: Termin-Ampel Schwellen (4h grün, 0h orange)

4. Verbindliche Dokumente (lesen in dieser Reihenfolge)

1. HANDOFF.md — Wie ist der aktuelle Stand? Status, geparkte Fragen, nächste Schritte. Bei jeder neuen Session zuerst.
2. docs/fachlich/Lastenheft.md — Was bauen wir? Vollständige fachliche Spezifikation mit Diagrammen. Master.
3. docs/konventionen/agents.md — dieses Dokument.
4. README.md — Wie starte ich es? Orientierung, Setup, Deploy.

Außerdem gepflegt (nicht zwingend zuerst zu lesen): docs/betrieb/Timesheet.md — Arbeitszeit-Timesheet (Start/Stop je Session · Gap-Regel · Methodik); am Session-Ende aktualisieren. Protokoll → §5.1 „Arbeitszeit erfassen".

5. Verhaltensregeln für Agenten

5.1 Was tun

• IDs respektieren: Beim Verweis auf existierende Entscheidungen ID nennen (z. B. „gemäß R3a-F04 ist Standzeit in Stunden").
• Lastenheft und HANDOFF gemeinsam pflegen: Eine neue Entscheidung landet als Update im Lastenheft (Kern-Spec) und in HANDOFF.md (kompakt für die nächste Session).
• Markdown + Mermaid: Neue Dokumente in .md anlegen. Diagramme als Mermaid inline.
• Single Source of Truth: Wenn ein Wert (z. B. Status) abgeleitet werden kann, wird er abgeleitet — nirgends doppelt gespeichert. Siehe G-2 / S-2.
• Selbsterklärbarkeit: Taktano soll ohne Schulung verständlich sein — durchgängig sprechende, eindeutige Bezeichnungen für Status, Aktionen, Felder und Räume (Werkstatt-Sprache statt technischer/abstrakter Labels; z. B. „Fahrzeug angeliefert" statt „Reserviert"). Gilt für UI und Doku. Bei neuen Labels diesen Maßstab anlegen. (Lastenheft §1.2 Leitprinzip.)
• Anführungszeichen: gerade ASCII-Zeichen (" und ') sind der Standard — in Code, Doku und UI-Strings (PO-Entscheid 07-18). Keine typografischen/geschwungenen Anführungszeichen in neuem Text; Bestehendes bleibt (kein retroaktiver Umbau, keine ungefragten Sweeps). CodeRabbit ist entsprechend konfiguriert (.coderabbit.yaml → tone_instructions), den Anführungszeichen-Stil nicht mehr zu beanstanden.
• Tests on-demand + CI: Alle automatischen Tests müssen lokal on demand ausführbar sein (Anleitung in README.md) und in der CI/CD-Pipeline laufen. Neue Tests immer beiden Wegen hinzufügen (Lastenheft §11.10; OP-TEST-1/2/3).
• Versioniertes Datenmodell + automatische Migration: Jede Datenmodell-Änderung ist versioniert (z. B. schemaVersion). Für jede neue Version gibt es eine automatische Migration. Jede Instanz wird beim Laden auf die Version geprüft und ggf. automatisch migriert (idempotent, jede Versionsstufe genau einmal). Beispiel im Code: SCHEMA_VERSION + versionierte Remaps in server/party/leitstand.ts (onStart). Persistierte Daten nie ohne Migration „brechen".
• Logging via OpenTelemetry: Anwendungs-Logs (und Traces/Metrics) über das OTel-SDK je Laufzeit (Worker/DO · Angular-Client · Python-Solver) emittieren — nicht roh console.log/print im Laufzeit-/Produktivpfad (CLI-Demos & Self-Tests dürfen console/print). Strukturiert über einen Logger-Wrapper, trace_id-korreliert. Verdrahtung + Collector/Backend: OP-OBS-1 (heute noch console-basiert). Siehe Root-CLAUDE.md → Observability / Logging.
• Tasks tracken: Multi-Step-Arbeit über das Task-System der Coding-Umgebung (Cowork TaskCreate/TaskUpdate, Claude Code TODO-System, etc.) sichtbar machen.
• Bei jeder größeren Aktion: offene Punkte im Auge behalten (Issues offener-punkt → Offene-Punkte.md).
• Jedes Feature wird dokumentiert (goldene Regel): Kein Feature ist „fertig", bevor die zuständige Produkt-/Design-Doku es beschreibt (WORKSPACES.md, OPTIMIERER_TERMINKLASSEN.md, COMPONENTS.md, DESIGN_TOKENS.md, Lastenheft). HANDOFF ist das Arbeitslog, kein Ersatz für die Produkt-Docs.
• Doku-Konsistenz-Check (verbindlich, OP-DOCS-9): Die Doku muss in sich konsistent sein und zur Implementierung passen. Cadence: zu Session-Beginn die relevanten Docs sichten und vor jedem PR/Merge gegenprüfen (zusätzlich zu den Test-Gates). Zwei Achsen:
  • Doku↔Doku (in sich): IDs (G-/R-/A-/S-/OP-…) existieren & sind eindeutig, Glossar-Begriffe einheitlich verwendet (z. B. Crystal-Bar), Workspace-/Phasen-Liste und Status (✅/🟡/⛔) stimmen über HANDOFF.md · docs/fachlich/Lastenheft.md · CHANGELOG.md · design/ überein, Version/Build überall = der gestempelte Stand (server/src/app-version.ts · build-number.ts, zusammengeführt in version.ts), Querverweise (§-Verweise, Datei-/Bildlinks) lösen auf, keine widersprüchlichen Aussagen.
  • Doku↔Implementierung: in der Doku genannte Feldnamen/Enums/DTOs/Routen/Token existieren im Code (und umgekehrt) und tragen dieselbe Bedeutung; beschriebene Features sind gebaut — und Gebautes ist beschrieben (goldene Regel). Bei Abweichung: entweder Code oder Doku angleichen (begründet entscheiden), nie still auseinanderlaufen lassen.
  • Mechanik: der maschinell prüfbare Teil läuft als bash scripts/check-doc-consistency.sh. Seit OP-DOCS-14 Teil 3 zweistufig: die harte Teilmenge (tote Links/Bilder · Version/Build-Single-Source · veraltete generierte Offene-Punkte.md) blockt den Merge (CI-Job checks läuft mit --strict und hängt am ci-gate); alle übrigen Checks (Landkarte/Frontmatter/Sidebar · Log-Hygiene · Zeilenlängen · Footer-Staleness · Landkarte-Rücklink, Generator scripts/gen-doc-footer.mjs) warnen weiter (::warning::). Der semantische Teil (IDs/Glossar/Workspace-Liste · Doku↔Code) ist Agenten-Pflicht und nicht voll automatisierbar — das Skript ersetzt ihn nicht. Bei Unklarheit/Widerspruch: nachfragen (nicht raten).
• Audit-Trail: Entscheidungen + Diskussionsergebnisse festhalten: Jede Design-/Architektur-/Prozess-Entscheidung und jedes Diskussionsergebnis (auch UX-Richtungen, verworfene Optionen mit Begründung) landet in der Doku — fachlich im Lastenheft, offene Punkte als Issue (TKT-D-862), Design in design/, Guiding Principles im Root-CLAUDE.md. Ziel: lückenloser, nachvollziehbarer Audit-Trail.
• CHANGELOG.md pflegen (je PR): ein Eintrag pro PR als Fragment changelog.d/<YYYY-MM-DD>-<branch-slug>.md (TKT-D-861, §6.6 — CHANGELOG.md selbst ist erzeugt): Datum · PR-Nummer mit Link · kurze Beschreibung inkl. getroffener Entscheidungen, neueste zuerst. Der Changelog ist der schnelle chronologische Audit-Trail; die Tiefe steht in HANDOFF/Lastenheft.
• Versionierung (je PR): kein Handgriff im Code — am PR das Label version:patch|minor|major setzen (ohne Label: kein Bump, richtig für Doku-/CI-only). Version und Build-Nummer werden beim Deploy gestempelt (app-version.ts/stamp-version.mjs aus dem höchsten Tag v<semver> + Label · build-number.ts/stamp-build.mjs aus dem Commit-Count) — beide Dateien nie von Hand ändern. Details: Root-CLAUDE.md §Versionierung, TKT-OP-PM-4, OP-PM-2.
• Test-Übersicht mitführen (je PR): Wer eine automatische Prüfung hinzufügt/entfernt (test:*-Script, Smoke, Gate, CI-Job), legt ein Fragment tests.d/<NNNN>-<slug>.md an bzw. ändert es (eine Tabellenzeile: Befehl · Prüfgegenstand · OP-Bezug · CI-Job; Tausender = Tabelle) — daraus entsteht die lebende, vollständige Liste docs/betrieb/Tests.md (TKT-D-865, §6.6). Mechanischer Rückhalt: scripts/check-doc-consistency.sh warnt, wenn ein test:*-Script (server/ + client/) in tests.d/ fehlt; der semantische Teil bleibt Pflicht (§5.1/OP-DOCS-9). Root-CLAUDE.md §Tests & CI.
• Logs nur als Fragment (seit TKT-D-861): CHANGELOG/HANDOFF/Timesheet sind aus changelog.d//handoff.d//timesheet.d/ erzeugt — nie direkt editieren, kein Glätten mehr nötig (das frühere union-Glätten gilt nur noch für Altbestand). Detail: §6.6.
• Annahmen sichtbar machen + Optionen zuerst: Berührt eine Aufgabe versteckte Annahmen oder Produkt-/Datenmodell-Entscheidungen, nicht drauflosbauen — Annahme explizit auflisten + begründen (gegen das Datenmodell prüfen), Optionen mit Empfehlung vorlegen, entscheiden lassen, dann bauen + Entscheidung dokumentieren.
• Verifizieren statt behaupten: Previewbare Änderungen live verifizieren (Preview-Tools, echte Daten) statt den User prüfen zu lassen; reine Logik als self-asserting Demo (in CI, z. B. test:*); bei Client↔Server-Protokollen Symmetrie prüfen (jeder Client-Sender hat einen Server-Handler).
• Arbeitszeit erfassen: je Session ein Fragment timesheet.d/<YYYY-MM-DD>-<branch-slug>.md (erzeugt docs/betrieb/Timesheet.md, §6.6) — Start/Stop je Session, Gap-Regel (> 1 h seit letzter Interaktion → User nach Stop fragen, neue Session). Am Session-Ende aktualisieren.

5.2 Was NICHT tun

• ❌ Keine binären Dokumente als Master-Quelle. Kein .docx, kein .pdf als Spezifikations-Quelle. Wenn vorhanden, sind diese reine Exporte aus dem .md.
• ❌ Keine ungefragten Refactorings am Lastenheft oder Prototyp. Erst klären, dann tun.
• ❌ Kein Pushen ohne Confirm in main, wenn der Wert der Änderung unklar ist. Lieber Branch + PR.
• ❌ Keine duplizierten Decision-Docs außerhalb von Lastenheft + HANDOFF. Wir vermeiden „Decision-Sprawl".
• ❌ Keine Read-Only-Analyse von Drittsystemen ohne expliziten User-Auftrag. Wenn nötig: User loggt selbst ein, Agent navigiert per Browser-Extension.
• ❌ Keine PII / Passwörter in Klartext committen.

5.3 Bei Unsicherheit

• Lieber eine kurze Frage stellen als annehmen.
• Wenn die Antwort nicht entscheidbar ist: Punkt als Issue (Formular „Offener Punkt") parken (§6.2) und weitermachen.

6. Workflow für Änderungen

6.1 Eine Entscheidung treffen

1. ID vergeben (oder bestehende referenzieren) — neu: TKT-D-<nr> = Nummer des auslösenden GitHub-Issues (sonst des PR), mehrere je PR -2, -3; nie „höchste + 1" (TKT-D-861).
2. Lastenheft §X (passender Abschnitt) updaten.
3. HANDOFF-Fragment bzw. das betroffene Issue kommentieren/schließen (Entscheidung kompakt notieren; PR mit Closes #n).
4. Commit-Message: Resolve <ID>: <kurz>.

6.2 Eine offene Frage aufnehmen (Issue = Quelle — verbindlich seit TKT-D-862, #862)

Kernaussage: Ein offener Punkt ist ein GitHub-Issue mit Label offener-punkt — die Issue-Nummer ist die ID, der Status ist der Issue-Zustand. Keine neuen ops/*.md mehr.

1. Issue anlegen (Formular „Offener Punkt", .github/ISSUE_TEMPLATE/offener-punkt.yml: Befund · Optionen · Empfehlung · Bezug; Labels offener-punkt + status: anreicherung bzw. status: umsetzen per Claude). Optional Filter-Labels prio:jetzt|next|spaeter, bereich:<wort>, audience:technik|produkt|stakeholder|legal (die Zielgruppe bewusst setzen — legal ⇒ Risikoregister/Compliance prüfen, CLAUDE.md „Proaktives Flagging").
2. Status = Issue: offen (🟡) · offen + Label status:in-arbeit (🔵) · geschlossen completed (✅) · geschlossen not planned (⚪). Der PR, der den Punkt erledigt, trägt Closes #n.
3. Übersicht docs/betrieb/Offene-Punkte.md (Statistik + Grafik, PO-Vorgabe 07-12) erzeugt scripts/gen-ops.mjs aus den Issues — nicht im PR, sondern im Nachzieh-Lauf nach jedem Merge und täglich (dokumente-nachziehen.yml). Nie von Hand editieren; kein Staleness-Gate mehr im PR.
4. Fachlicher Kontext (falls vorhanden): im Owning-Doc bzw. Lastenheft-Abschnitt kurz verlinken (#n als Status-Quelle nennen); bekommt der Punkt ein eigenes Dokument → Zeile in IDs.md (§2.1).

Altbestand (ops/*.md, eingefroren): die 168 bis 09-26 gespiegelten OPs leben als [<OP-ID>] …-Issues weiter (Label op-sync + offener-punkt; Body-Fuß „Quelle ist jetzt dieses Issue"). Jede Datei trägt issue: <nr> im Frontmatter, damit Alt-IDs auflösbar bleiben; nicht mehr fortschreiben (Status, Diskussion, Grooming → Issue). 31 erledigte Alt-OPs ohne Issue zählen weiter aus der Datei; ein offener OP ohne Issue bricht gen-ops ab. sync-ops.yml/sync-ops-issues.mjs sind entfernt (sie hätten jede Issue-Änderung mit der Datei überschrieben).

Warum (TKT-D-862): zwei Bestände (Datei + Spiegel) veralten gegeneinander, und die im PR committete Übersicht war ein Konfliktherd. Einfachste tragfähige Ableitung: dasselbe Skript wie bisher, nur mit den Issues als Eingang, im bestehenden Nachzieh-Lauf (kein neuer Dienst, keine neue Abhängigkeit; Datei bleibt im Repo, damit Doku-Site, Links und Assistent-Index sie weiter finden — anders als jicos Artefakt-Variante).

Sichten & Steuern (OP-ORG-1, PO-Vorgabe 07-12): Die 📊-Statistik + Grafik in Offene-Punkte.md ist der Standard-Blick — zu Session-Beginn kurz sichten (zusammen mit dem Risikoregister-Check, §5). Fürs Stakeholder-Steuern dient das GitHub-Projects-Board (Auto-Add-Filter künftig is:issue label:offener-punkt; prio:*/bereich:*/audience:* als Filter; „Item closed → Done" automatisch). Kadenz: wöchentlicher PO-Blick aufs Board. Priorität/Status werden direkt am Issue gesetzt — das Board ist keine zweite Quelle mehr.

6.2a OP-Grooming & Diskussion (agentgetrieben, on-demand — PO-Entscheid 07-12)

Bewusst keine Pipeline/Automatik, sondern stehende Tasks, die ein Agent auf Zuruf ausführt; die Quelle ist das Issue (seit TKT-D-862 — kein Zurückholen der Diskussion in eine Datei mehr nötig).

• OP-Diskussion zusammenfassen („fasse die Diskussion zu #n zusammen"): der Agent liest die Kommentare (GitHub-MCP) und schreibt einen Kommentar ## Diskussion (Stand JJJJ-MM-TT) ins Issue (bzw. aktualisiert den Body).
• OP anreichern / grooming („groome #n"): Kommentar ## Grooming (Stand JJJJ-MM-TT) mit Akzeptanzkriterien · Aufwand (grob) · Abhängigkeiten (Issue-/RISK-IDs) · offene Compliance-/DSGVO-Fragen (DE/AT/CH) · prio-Vorschlag — du entscheidest je Punkt (Label setzen). Kein Massen-Lauf.

6.3 Eine neue Architektur-/Vereinfachungs-Idee

1. Eintrag in Lastenheft §9 (A-) oder §10 (S-).
2. Begründung mit ggf. Mermaid-Diagramm.
3. Commit-Message: Propose <ID>: <kurz>.

6.4 Codeänderungen am Prototyp

1. TypeScript-Server: cd server && npm run typecheck muss passen.
2. Angular-Client: cd client && npx ng build --configuration production muss passen (CI-Hook geplant, siehe HANDOFF §7).
3. Commit-Message-Konvention frei, aber mit relevanter Lastenheft-ID, wenn die Änderung eine Anforderung implementiert.

6.5 Doku-Konsistenz prüfen (Session-Start + vor jedem PR)

1. Session-Start: HANDOFF.md → docs/fachlich/Lastenheft.md → docs/konventionen/agents.md lesen; relevante Docs zum Vorhaben sichten (der SessionStart-Hook scripts/session-start-hook.sh blendet diese Erinnerung ein).
2. Vor dem PR: beide Achsen prüfen (Doku↔Doku und Doku↔Implementierung, s. §5.1 „Doku-Konsistenz-Check"); bash scripts/check-doc-consistency.sh für die mechanische Teilmenge laufen lassen.
3. Drift gefunden? Code oder Doku angleichen (begründet) — bei Unklarheit nachfragen. Ergebnis im PR/CHANGELOG vermerken.
4. Commit-Message bei reiner Angleichung: Sync docs <Bereich>: <kurz>.

6.6 Merge-Strategie: Fragmente statt union-Logs (TKT-D-861, vorher OP-PM-2)

Kernaussage: Die je PR fortgeschriebenen Logs werden seit TKT-D-861 aus Fragmenten gebaut — ein PR legt eine eigene Datei an, zwei parallele PRs treffen nie dieselbe Datei. Kanon (repo-übergreifend, nicht hier dupliziert): drkv-com/everything-as-code-template → docs/GitHub-Arbeitsweise.md (BP-1…BP-8).

Warum: merge=union (OP-PM-2) griff nur bei lokalen Merges; GitHubs Server-Merge, „Update branch" und die Mergeability ignorieren den Treiber (422 merge conflict, 06-27 verifiziert) — daher bisher Handarbeit mit smooth-logs/sync-pr-logs. Version/Build/Footer sind schon seit TKT-OP-PM-4 gestempelt statt gepflegt.

Erzeugtes Dokument	Quelle	Fragment je PR (<YYYY-MM-DD>-<branch-slug>.md)	Ordnung
CHANGELOG.md	changelog.d/	eine Zeile - **{PR}** — YYYY-MM-DD — Beschreibung inkl. Entscheidungen (IDs).	neueste zuerst
HANDOFF.md (§2-Tabelle)	handoff.d/	eine Tabellenzeile | Artefakt | Pfad | Status |; §3–§10 + Stand in handoff.d/_fuss.md	neueste zuerst
docs/betrieb/Timesheet.md	timesheet.d/	ein Absatz Session taktano-<Datum>-<branch-slug> ~<Dauer> h (<MM-DD>, {PR}, …)	chronologisch, hinten
docs/betrieb/Funktionsumfang.md (TKT-D-865)	feature.d/ + Issues Feature-Liste	Feature = Issue (Nummer = ID); Fragment feature.d/<Position>-<slug>.md: abschnitt: (aus _abschnitte.md), optional anmerkung:, eine Zeile | Feature | Bereich | Seit | OP | #<Issue> | — Status nie im Fragment (geschlossen ✅ · offen+teilweise 🟡 · offen ⛔); Bau scripts/funktionsumfang_bauen.py (jico-Vorbild)	nach Position
docs/betrieb/Tests.md (TKT-D-865)	tests.d/	eine Tabellenzeile tests.d/<NNNN>-<slug>.md; Tausender = Tabelle (1 Server · 2 Smokes · 3 Client · 4 E2E · 5 Solver · 6 Gates), <N>000-…-kopf.md = Abschnitt + Tabellenkopf	nach Position

• Nie die erzeugten Dateien editieren; {PR} ersetzt der Bau durch den PR-Link (aus dem Squash-Titel). Konfiguration fragmente.json, Builder scripts/fragmente_bauen.py (unveränderte Template-Kopie — nie lokal ändern). Lokal ansehen: python3 scripts/fragmente_bauen.py (Ergebnis nicht committen).
• Gebaut wird nach dem Merge: .github/workflows/dokumente-nachziehen.yml baut auf main und trägt das Ergebnis per Bot-PR mit Auto-Merge nach (wöchentlicher Cron als Netz). Deren Merge löst keinen vollen main-Lauf aus (paths-ignore in ci.yml). Im PR prüft der checks-Job nur --gelesen (Fragmente wohlgeformt).
• Altbestand steht je Quelle in 0000-bestand.md (verlustfrei migriert, nicht mehr fortschreiben). Timesheet: Session-Tabelle, Summen und KW-Verdichtungen sind Altbestand und werden nicht mehr je PR gepflegt (Kollisionsherd). Summe + KW-Verdichtung der Fragmente berechnet scripts/timesheet_summen.py im Nachzieh-Lauf nach dem Fragment-Bau (markierter Block am Dateiende, TKT-D-865; Datum aus dem Dateinamen, Dauer aus ~<Dauer> h, fail-closed ohne Dauer). Eigenes Skript, weil fragmente_bauen.py Template-Kopie bleibt; Folge: fragmente_bauen.py --pruefen meldet die Timesheet-Datei als „veraltet" (der Block fehlt im Roh-Bau) — im Repo wird --pruefen nicht verwendet, das PR-Gate ist --gelesen.
• Aus Issues erzeugt (TKT-D-862/TKT-D-865): docs/betrieb/Offene-Punkte.md (gen-ops.mjs) und docs/betrieb/Funktionsumfang.md (funktionsumfang_bauen.py) lesen die GitHub-Issues und laufen daher nur im Nachzieh-Lauf (nach jedem Merge + täglich, weil Issue-Änderungen keinen Push auslösen) — nie im PR. Die Seiten bleiben im Repo (Doku-Site, Links, Assistent-Index), anders als jicos Artefakt-Variante; im PR laufen nur die netzfreien Tests (gen-ops.test.mjs, test_*.py).
• Session-ID bleibt sprechend, repo- & branch-abgeleitet (taktano-<Datum>-<branch-slug>, OP-PM-3).
• Altwerkzeuge abgebaut (#864): npm run smooth-logs, .github/workflows/sync-pr-logs.yml (+ Secret SYNC_BOT_TOKEN) und die Dubletten-Checks im Doku-Check dienten nur dem union-Glätten und sind entfernt. scripts/check-doc-consistency.sh warnt weiterhin bei Konflikt-Marker-Resten; der Builder bricht bei Konflikt-Markern in Fragmenten ohnehin ab.
• Issues (BP-1): Arbeit beginnt mit einem Issue, Issue-Nummer = ID; Entscheidungen TKT-D-<nr> (§6.1). Formulare .github/ISSUE_TEMPLATE/, Labels als Code .github/labels.yml (+ Workflow labels.yml, legt an, löscht nie). Offene Punkte sind Issues (§6.2, TKT-D-862; ops/*.md eingefroren).
• Repo-Einstellungen (BP-5): Squash-only · Allow auto-merge · Automatically delete head branches · Actions dürfen PRs anlegen · optional Secret AUTOMATION_PAT (Bot-PR startet Checks ohne Klick) — Prüfung §6.7.

6.7 Nicht-automatisierbare Checks (Agenten-Pflicht — „nicht per MCP/Skript prüfbar")

Problem: Einige Sicherheits-/Setup-Kontrollen lassen sich nicht per CI-Skript und nicht über die GitHub-MCP zuverlässig prüfen — entweder fehlt ein MCP-Tool (Repo-Settings/Code-Scanning-Modus) oder der CI-GITHUB_TOKEN hat keinen Admin-Scope. scripts/check-security-setup.sh (im wöchentlichen weekly-audit.yml) prüft die mechanische Teilmenge und meldet diese Punkte best-effort als ℹ️/⚠️ „nicht abfragbar" — die eigentliche Verifikation ist dann Agenten-Pflicht.

Wann: zu Session-Beginn, vor jedem PR und nach jeder Repo-Setting-Änderung.

Wie: wenn ein gh/Token mit ausreichendem Scope vorhanden ist, per gh api prüfen; sonst den Nutzer fragen bzw. aktiv darauf hinweisen (Optionen zeigen, §5.3) und Abweichungen melden — nie still übergehen.

Checkliste (nicht-mechanisch):

1. Merge-Methoden = nur Squash aktiv (Merge-Commits + Rebase aus). — gh api repos/<o>/<r> --jq '.allow_squash_merge,.allow_merge_commit,.allow_rebase_merge'
2. allow_auto_merge = true (OP-PM-2). — gh api repos/<o>/<r> --jq '.allow_auto_merge'
3. delete_branch_on_merge = true (Branch-Cleanup). — gh api repos/<o>/<r> --jq '.delete_branch_on_merge'
4. Code scanning läuft (Entscheidung 06-27: GitHub Default Setup, deckt TS+Python automatisch; kein eigener codeql.yml — advanced + default schließen sich aus). — gh api repos/<o>/<r>/code-scanning/default-setup --jq '.state' (erwartet configured); ergänzend Security-Tab/Alerts sichten.
5. Branch-Protection auf main (erforderliche Checks gesetzt). — gh api repos/<o>/<r>/branches/main/protection (Admin-Scope nötig).
6. Semantische Doku-Konsistenz (§5.1/§6.5) — ohnehin Agenten-Pflicht (kein Skript ersetzt sie).

Soll-Zustand (Stand 06-27): 1–4 ✅ gesetzt; verwaiste Alt-Branches (vor Auto-Delete gemergt) sind manuell aufzuräumen. Abweichungen vom Soll → im PR/HANDOFF vermerken und dem Nutzer melden.

6.8 CI-Pipelines: Concurrency (überholte Läufe abbrechen)

Regel: Jede Workflow-Pipeline bekommt einen concurrency-Block, wo er Nutzen bringt — d. h. überall, wo mehrere Läufe desselben Kontexts (PR/Branch, Deploy-Ziel) überlappen können und der ältere Lauf durch den neueren überflüssig wird. Das spart Runner-Minuten und liefert schneller ein aktuelles Ergebnis. Gemeint ist das GitHub-Actions-Schlüsselwort concurrency: (Läufe gruppieren/canceln) — nicht die Job-Parallelität (die regelt der Job-Graph über needs).

Muster (je Pipeline-Typ):

• CI / PR-Pipelines → nächsten Push auf denselben PR/Branch den vorherigen Lauf abbrechen lassen:

  concurrency:
    group: ci-${{ github.workflow }}-${{ github.ref }}
    cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}

  Nicht auf main abbrechen — dort liefe sonst ein Deploy ins Leere. Umgesetzt in ci.yml.
• Deploy-/Ressourcen-Pipelines (genau ein Ziel, z. B. ein Worker) → überlappende Deploys verhindern: group: <deploy-ziel> (fixer Name), cancel-in-progress: true.
• Serielle Jobs, die nicht abgebrochen werden dürfen (z. B. Log-Sync, Migrationen) → nur serialisieren, nicht canceln: cancel-in-progress: false.

Faustregel cancel-in-progress: true für idempotente/überholbare Läufe (PR-CI, Deploy); false, wenn jeder Lauf zu Ende laufen muss. Ergänzend wirkt die Trigger-Hygiene gegen Doppelläufe (push nur auf main + pull_request statt push auf allen Branches, OP-CI-1) — Concurrency und Event-Trigger greifen zusammen: der eine cancelt überholte Läufe desselben Events, der andere verhindert den doppelten push+pull_request-Lauf desselben Commits.

Kein actions/setup-node-cache: npm auf dem persistenten self-hosted Runner. Der npm-Cache von setup-node ist für ephemere GitHub-Runner gedacht (die nach jedem Lauf verschwinden). Unser Org-Runner ist persistent → ~/.npm ist zwischen Läufen ohnehin warm; cache: npm würde nur ein großes Archiv langsam durch den Actions-Cache-Service tarren/laden (auf flakiger Runner-Anbindung ein Timeout-Risiko). Daher in ci.yml entfernt; npm ci/npm install nutzen das lokale ~/.npm. Auf Fork-PRs (ubuntu-latest, ephemer) lädt npm dann frisch aus der Registry — selten und akzeptabel.

Schnelle Installs: die npm ci-Aufrufe in ci.yml laufen mit --prefer-offline --no-audit --fund=false — nutzt das warme lokale ~/.npm ohne Audit-/Funding-Netz-Calls (spart Zeit, robuster bei flakiger Anbindung). Der Pfad-Filter (changes-Job) hält bereichsfremde/​docs-only-PRs schlank (schwere Jobs skippen; der Pflicht-Check checks bleibt grün, skipped ≠ failure).

Runner-Labels hot vs. ephemeral (wichtig): Die self-hosted Runner der Org tragen ein Label — hot = persistent (Arbeitsordner + ~/.npm + Build-Caches überleben zwischen Läufen), ephemeral = frisch je Lauf. CI pinnte auf hot (runs-on: … || 'hot'; seit #639 ist der Fallback desktop, die Repo-Variable CI_RUNNER hat Vorrang), weil alle Cache-/Offline-Hebel nur dort greifen: warmes ~/.npm (Offline-Installs), fehlender setup-node-npm-Cache (auf ephemeral wäre er sogar nützlich), und der persistente Build-Cache (unten). Fork-PRs bleiben über das Gate auf ubuntu-latest; Umschalten via Repo-Variable CI_RUNNER. Kapazität beachten: Pinnt CI auf hot, ist die Zahl der hot-Runner die Parallelitäts-Obergrenze — genügend hot-Runner bereitstellen (≥ breitester Job-Fächer).

Build-Minuten auf gehosteten Runnern (TKT-OP-CI-3): Läuft CI auf GitHub-Runnern (CI_RUNNER=ubuntu-latest, Fork-PRs), rundet GitHub jeden Job auf volle Minuten auf — ein 5-s-Job kostet 1 Minute. Darum: keine Kleinst-Jobs anlegen (neue Prüfung als Schritt in einen passenden bestehenden Job, z. B. checks/server), dieselbe Arbeit (npm ci, ng build) nicht in zwei Jobs doppeln. Arbeitsweise: Audit-Trail-Nachträge (CHANGELOG/HANDOFF/Timesheet, PR-Link) möglichst im selben Push wie der Code — jeder Folge-Push startet einen neuen Lauf, und der abgebrochene Vorlauf hat seine Minuten bereits verbraucht. Draft-PRs bekommen keine CI (BM-6, PO-Go 09-26): alle ci.yml-Jobs skippen auf Drafts; erst "Ready for review" (ready_for_review-Event) startet den Lauf. Ablauf also: im Draft arbeiten und pushen → fertig → Ready for review → CI → Auto-Merge (auf Drafts ohnehin nicht aktivierbar). Wer vor dem Ready-Schalten CI-Rückmeldung braucht, prüft lokal (Gates/Tests) oder nimmt den PR aus dem Draft. Achtung Merge-Fenster: Ein auf dem Draft übersprungener Pflicht-Check checks zählt für GitHub als erfüllter Required Check — direkt nach "Ready for review" meldet der PR darum für einige Sekunden clean, bevor der neue Lauf registriert ist (am eigenen PR #856 beobachtet). Required sind checks (Sammel-Job ci-gate, drkv-einheitlicher Name, TKT-D-863) und "CodeRabbit" (Stand 09-26); der CodeRabbit-Status verkürzt das Fenster in der Praxis, ersetzt die Regel aber nicht. Nie in diesem Moment direkt mergen: erst prüfen, dass der ready_for_review-Lauf läuft (list_workflow_runs), dann Auto-Merge aktivieren.

Harte Obergrenze je Job (TKT-D-861, drkv BP-4): jeder Job in allen Workflows trägt timeout-minutes — ein hängender Lauf (Runner weg, Netz-Hänger) kostet sonst bis 360 Min. bzw. blockiert den self-hosted Runner.

Persistenter Build-Cache (nur hot): Der Angular-Disk-Cache (.angular/cache) beschleunigt Folge-Builds inkrementell. Zwei Voraussetzungen, beide gesetzt: (1) angular.json → cli.cache.environment: "all" (Angular deaktiviert den Cache in CI sonst per Default), (2) actions/checkout mit clean: false im Client-Job, damit der (gitignorierte) Cache den git clean -ffdx überlebt. Der Cache ist content-adressiert (selbst-invalidierend) → unbedenklich; auf ephemeral/Fork-Runnern ist er wirkungslos (kein Zustand), aber nie schädlich.

Auto-Rerun bei flakigem Runner (auto-rerun.yml): Schlägt ein CI-Lauf fehl, stößt ein workflow_run-getriggerter Job die fehlgeschlagenen Jobs einmalig neu an (run_attempt < 2 deckelt auf genau 1 Retry → kein Loop). Heilt die typische self-hosted-Flakiness (github.com:443-Timeout, Runner mitten im Job gestorben, Laptop zu). Nicht neugestartet: abgebrochene Läufe (Concurrency-Cancel = cancelled ≠ failure) und Fork-PRs. Ein echter Test-Fail läuft im Retry erneut rot (Preis: ein Extra-Lauf je Fehlschlag; auf self-hosted ohne Minuten-Kosten vertretbar). Deploys sind bewusst ausgenommen (bei Bedarf manuell re-runnen).

6.9 Kanonische PR-Checkliste (OP-DOCS-15)

Die vollständige Liste aller Je-PR-Pflichten steht an genau einem Ort: .github/PULL_REQUEST_TEMPLATE.md — GitHub legt sie jedem neuen PR automatisch in den Body (Checkboxen). Hintergrund: das Doku-Review 2026-07 (Befund D5) belegte ~20 Pflichten verstreut über ≥5 Orte, einige nur als Tabellenzelle (z. B. Funktionsumfang-Pflicht) — Rezept für selektive Compliance.

Rollenverteilung (kein neuer Regel-Owner!): Die Checkliste ist eine Sicht; jede Pflicht zitiert ihre Owner-Regel (CLAUDE.md bzw. dieses Dokument). Pflege-Regel: Wer eine Je-PR-Pflicht einführt, ändert oder streicht, zieht das Template im selben PR nach — eine Pflicht, die dort fehlt, existiert praktisch nicht. Agenten, die PRs per API erstellen (eigener Body statt Template), arbeiten die Checkliste inhaltlich ab und spiegeln die Struktur im PR-Body.

7. Branch- und Push-Konventionen

• Default-Branch: main.
• GitHub-Operationen über die GitHub-API/MCP, nicht über lokales git/gh (verbindlich, v. a. in der Remote-/Cloud-Session): Remote-Schreibvorgänge — PR anlegen/mergen, Review-/Issue-Kommentare, Commits/Pushes auf Remote-Branches — laufen über die GitHub-MCP-Tools (create_pull_request, merge_pull_request, create_or_update_file/push_files, add_issue_comment, …); CI-Status & Mergeability über pull_request_read (get_status/get_check_runs) prüfen, nicht erraten. Grund: in der Remote-Ausführungs-Umgebung sind lokale git-Schreibbefehle (push/commit) unzuverlässig (der Permission-Stream bricht intermittierend ab); die API ist robust, atomar und permissions-arm. Lokales git bleibt für lokale Arbeit ok (Branch anlegen, Merge/Rebase + Konflikt-Auflösung im Arbeitsbaum, Reads wie status/diff/log). Der „go"-Gate (unten) gilt unverändert — nur der Transport-Weg ist die API.
• Neuer Code (KI) → immer zuerst einen neuen Branch anlegen und nur dort arbeiten. Verbindlich: Erzeugt/ändert ein KI-Agent Code, legt er vor der ersten Änderung einen Feature-Branch an (git checkout -b …) und committet/pusht ausschließlich dort; Merge nach main nur via PR (mit grüner CI). Niemals Code direkt auf main.
• Doku-Fast-Track statt Direkt-Push: Auch reine Doku-Änderungen laufen über Branch + PR (nie Direkt-Push auf main) — der Audit-/PR-Nummern-Trail bleibt lückenlos (§5.1, CHANGELOG „je PR ein Eintrag"). Damit das friktionsfrei bleibt, gilt für PRs, deren Diff ausschließlich Doku berührt (alle geänderten Dateien liegen unter docs/ oder sind *.md): (1) die schweren CI-Jobs (Server/Client/Solver/Design/SBOM) werden übersprungen — der changes-Job in ci.yml erkennt „docs-only" und der aggregierte Pflicht-Check checks (Job ci-gate, einziger CI-Required-Check) wird trotzdem grün; (2) Auto-Merge darf aktiviert werden (GitHub „Auto-merge", Squash). So ist ein Doku-PR praktisch Ein-Klick, ohne die App-CI zu binden. Sobald eine Nicht-Doku-Datei im Diff ist, läuft die volle CI (Fast-Track entfällt automatisch). Repo-Voraussetzung: Branch-Protection von main verlangt nur den Check CI Gate (nicht die Einzel-Jobs), und „Allow auto-merge" ist aktiv.
• Force-Pushes nur lokal, niemals auf shared Branches.
• „go"-Gate: Commit, Push und Merge erfolgen nur auf explizites „go" des Users. Einen Branch anlegen + Dateien im Arbeitsbaum vorbereiten ist ok; das Schreiben in die Historie / nach außen (Push, PR, Merge) wartet auf „go".
• Auto-Merge ist der Standard (PO-Entscheidung 09-25, „immer automerge"): Der Agent aktiviert auf jedem eigenen PR GitHub-Auto-Merge (Squash), sobald der PR steht — nicht erst nach einer Rückfrage. Das „go"-Gate darüber bleibt unberührt: es braucht weiter ein „go" für die Arbeit und den Push; die Freigabe zum Mergen ist mit dieser Entscheidung dauerhaft erteilt. Zwei Konsequenzen, die der Agent kennen muss und beim Melden benennt: (1) Ein Review-Fund, der nach dem Merge eintrifft (CodeRabbit ist langsamer als die CI), wird zum Folge-PR statt zum Nachzug im selben PR — genau so entstand #846. (2) Die Sorgfalt verschiebt sich vor den Push: was sonst der Review fangen würde, muss der Agent selbst gefunden haben (Gates, E2E, negativ gegengeprüfte Wächter). Wer ohne Netz merged, prüft vorher gründlicher — nicht weniger.
• pr-weise: offene PRs einzeln mergen (einer nach dem anderen), jeweils mit grüner CI — kein Sammel-Merge.
• Branch laufend auf main aktuell halten: Den Feature-Branch nicht nur am Ende, sondern durchgängig auf den aktuellen main bringen — (1) zu Beginn, bevor inhaltliche Änderungen starten (frisch von main abzweigen bzw. direkt aktualisieren); (2) in vernünftigen Abständen während längerer Arbeit; (3) vor dem Erstellen des PR; (4) vor dem Merge. Mechanik: git fetch origin main → git rebase origin/main (bei bereits geteiltem/gestapeltem Branch: git merge origin/main). Grund: main bewegt sich durch parallele Merges; frühes + regelmäßiges Aktualisieren hält die Divergenz klein — etwaige Konflikte entstehen lokal beim Autor (nicht erst beim Merge als „base branch was modified") und bleiben winzig.
• Branch nach Merge schließen: Sobald ein PR gemergt ist, wird der zugehörige Feature-Branch gelöscht (remote und lokal) — kein Sammeln verwaister Branches. Empfohlen ist die GitHub-Repo-Einstellung „Automatically delete head branches" (löscht den Head-Branch automatisch beim Merge); ist sie nicht aktiv, löscht der Agent den Branch unmittelbar nach dem Merge selbst (git push origin --delete <branch> + git branch -d <branch>). Ausnahme nur für Branches, die noch von anderen offenen PRs als Basis dienen.
• Feature-Branches aktuell halten: Laufende Feature-Branches werden regelmäßig gegen main aktualisiert, damit zwischenzeitlich gemergte PRs einfließen und Konflikte klein bleiben. Konkret: zu Session-Beginn und vor PR-Erstellung git fetch origin main und main in den Branch mergen bzw. den Branch darauf rebasen; bei langen Sessions auch zwischendurch, sobald relevante PRs auf main landen.
• Doku-Pflicht je PR & Merge: Jeder PR pflegt HANDOFF und Timesheet mit — seit TKT-D-861 nur als Fragment (handoff.d/, timesheet.d/, changelog.d/, §6.6) — (und die fachlich betroffenen Docs — Lastenheft, Design-Docs, Sanity-Checkliste; goldene Doku-Regel §5.1). Konkret: (a) vor dem Erstellen eines PR ist HANDOFF (§2 Stand) auf den Stand des Branches gebracht (betroffene offene Punkte: Issue kommentiert bzw. Closes #n) und der Timesheet-Eintrag der Session aktualisiert; (b) beim Merge wird, falls sich seit PR-Erstellung etwas geändert hat, HANDOFF nachgezogen. Ein PR ohne HANDOFF-/Timesheet-Pflege gilt als unvollständig.

8. Cowork-Setup-Snippet (für eine neue Session)

Was der User in der ersten Nachricht typischerweise sagt:

Lies HANDOFF.md und docs/konventionen/agents.md. Dann arbeiten wir an: <Aufgabe>.

Damit hat der Agent (a) den aktuellen Stand, (b) die Konventionen, (c) den Auftrag — und kann sofort liefern.

9. Was nicht in dieses Repo gehört

• Personendaten realer Kunden / Mitarbeiter (auch nicht in Beispielen — die im Lastenheft sind synthetisch).
• Secrets, API-Keys, Tokens (für CI: GitHub Encrypted Secrets nutzen).
• Generierte Build-Artefakte (dist/, .angular/, .wrangler/ — siehe .gitignore).
• Binär-Exporte als „Master" (.docx, .pdf). Falls jemand temporär einen Export braucht, kann er ihn lokal aus Lastenheft.md generieren, sollte ihn aber nicht committen.

---

Letztes Update: 27.06.2026 (Way-of-Working: Doku-Fast-Track — reine Doku-PRs überspringen die schwere CI [changes-Job + aggregierter CI Gate als einziger Required-Check] und dürfen per Auto-Merge durch; §7 — baut auf OP-PM-2 [union-Merge-Logs + Auto-Build-Nummer, §6.6] auf). Frühere: 26.06.: GitHub-Operationen über die GitHub-API/MCP statt lokales git/gh für Remote-Writes (§7; lokales git push/commit ist in der Remote-Session unzuverlässig). 23.06.: Branch laufend auf main aktuell halten — zu Beginn, in Abständen, vor PR & vor Merge [fetch+rebase/merge origin/main]. 22.06.: goldene Doku-Regel · Annahmen-sichtbar/Optionen-zuerst · Verifizieren statt behaupten · Timesheet-Pflicht · „go"-Gate · pr-weise · Branch nach Merge schließen · Doku-Pflicht je PR & Merge: HANDOFF + Timesheet.