OP-Management — Gold-Standard für offene Punkte (OP-DOCS-11)

Kernaussage. Offene Punkte leben als eine Markdown-Datei je OP im Repo (ops/<ID>.md, Frontmatter status/prio/bereich) — das bleibt die Quelle der Wahrheit, git-nativ konfliktfrei bei vielen parallelen KI-Agenten-Branches. Eine generierte Übersicht (docs/betrieb/Offene-Punkte.md) macht sie browsebar; ein einseitiger Spiegel nach GitHub Issues macht sie für nicht-technische Stakeholder diskutierbar/priorisierbar, ohne Git-Kenntnisse zu brauchen. Dieses Muster ist für alle drkv-Projekte gedacht — nicht nur Taktano.

1. Das Problem, das dieses Muster löst

Drei Anforderungen, die sich auf den ersten Blick widersprechen:

1. Everything-as-Code: Entscheidungen/offene Punkte gehören ins Repo (Diff-Historie, kein Tool-Lock-in, kein Datenverlust bei Vendor-Wechsel).
2. Stakeholder-Zugänglichkeit: Nicht-technische Beteiligte (Gründer, Vertrieb, Kunden) sollen offene Punkte diskutieren und priorisieren können, ohne Git/Markdown/PRs lernen zu müssen.
3. KI-Agenten-Tauglichkeit: Coding-Agenten (Claude Code, Codex, …) sollen Punkte lesen, umsetzen und abhaken können — deterministisch, ohne Kontext-Overhead, ohne Merge-Konflikte zwischen parallelen Branches.

2. Warum nicht die naheliegenden Alternativen

Option	Warum (nicht)
Eine große Markdown-Liste (Status quo vieler Projekte, z. B. HANDOFF.md §4 vorher)	Kollidiert bei jedem parallelen PR (alle Agenten editieren dieselbe Datei) → Merge-Konflikte, Drift zwischen mehreren redundanten Listen (Roadmap/IDs/Register/Timesheet).
Reine GitHub Issues als Quelle	Verlässt das Repo (Everything-as-Code verletzt) — Historie/Kontext lebt außerhalb der Codebasis, kein git blame, kein Offline-Zugriff, Vendor-Lock-in.
GitBook (oder ähnliche Doku-Reader-Tools)	Ist ein Rendering-Tool für Konsum, kein Tracking-Tool — kein natives Status/Owner/Board-Modell, keine Diskussions-Threads pro Punkt, kein „abhaken". Würde eine dritte Quelle neben Repo und GitHub schaffen → mehr Drift statt weniger.
Linear / separates SaaS-Projektmanagement-Tool	Neuer Vendor, Kosten, eigener Sync-Aufwand — während GitHub in praktisch jedem drkv-Projekt schon Teil des Stacks ist (Leitprinzip Einfachheit: vorhandene Bausteine nutzen). Kann sich lohnen, wenn ein Team GitHub-Issues-UX konkret ablehnt — dann denselben Sync-Mechanismus (§4) auf die Linear-API umstellen, das Repo-Format bleibt unverändert.

3. Die Lösung: drei Schichten

1. ops/<OP-ID>.md — eine Datei je offener Punkt, Frontmatter (id/title/status/audience/ prio/bereich/bezug/detail) + Freitext-Body. Format-Doku: ops/README.md, Vorlage: ops/_Vorlage.md. Agenten (Claude Code/Codex) arbeiten hier — ein Edit-Aufruf pro Statuswechsel, kein Suchen in einer Mega-Datei, keine Kollision mit parallelen Branches an anderen OPs. audience ist Pflicht (technik/produkt/stakeholder/legal, mehrere möglich) — bei jedem OP bewusst festlegen, wer entscheiden/es sehen muss, statt es implizit zu lassen; legal-OPs verweisen zusätzlich ins Risikoregister/Compliance-Tracking (CLAUDE.md „Proaktives Flagging"). gen-ops.mjs schlägt hart fehl, wenn audience fehlt.
2. scripts/gen-ops.mjs — generiert docs/betrieb/Offene-Punkte.md (Tabellen nach Status gruppiert, sortiert nach Priorität). Hart fehlschlagend bei kaputtem Frontmatter (wie gen-glossar.mjs beim Glossar) — ein Tippfehler bricht den Build, statt still zu degradieren. Dasselbe Muster wie design/tokens/tokens.json → tokens.css und docs-site/src/glossar/glossar.mjs → docs/glossar/Glossar.md: strukturierte Quelle → generiertes Artefakt, nicht handeditieren.
3. scripts/sync-ops-issues.mjs + .github/workflows/sync-ops.yml — spiegelt ops/*.md einseitig (Repo → GitHub) in Issues mit Label op-sync. Idempotent über Titel-Suche ([OP-ID] Titel), kein Zurückschreiben in die .md-Dateien nötig. status: erledigt/ verworfen schließt das Issue automatisch. Läuft bei jedem Push auf ops/** mit dem Standard-GITHUB_TOKEN der Action — kein zusätzliches Secret.
4. GitHub Issues + optional Projects-Board — die Stakeholder-Oberfläche: Kommentar-Threads pro Punkt (die „ordentliche Diskussion"), ein Kanban-Board (Projects, einmalig manuell angelegt, Issues per gespeicherter Ansicht/Filter auf label:op-sync automatisch aufnehmen) für Priorisierung ohne Git-Kenntnisse.

4. Rollout-Checkliste für ein neues drkv-Projekt

1. ops/README.md + ops/_Vorlage.md aus diesem Repo übernehmen (Format ist projekt-agnostisch).
2. scripts/gen-ops.mjs + scripts/sync-ops-issues.mjs kopieren, REPO-Default in sync-ops-issues.mjs auf das Ziel-Repo anpassen (oder GITHUB_REPOSITORY-Env verlassen, wenn's aus einer Action läuft — dann automatisch korrekt).
3. .github/workflows/sync-ops.yml kopieren, CI_RUNNER-Variable falls nötig setzen.
4. Ersten OP anlegen (ops/_Vorlage.md kopieren), node scripts/gen-ops.mjs laufen lassen, pushen → Issue erscheint automatisch.
5. Optional: GitHub-Projects-Board einmalig anlegen, Filter/Ansicht auf label:op-sync.
6. Bestehende alte OP-Listen (falls vorhanden) schrittweise migrieren — nicht in einem großen Schritt (Risiko für Historie); neue OPs entstehen ab sofort im neuen Format. Wichtig (Lehre aus Taktano, Doku-Review D4): den Alt-Bestand explizit als Archiv labeln und den neuen Weg im Way-of-Working-Doc verbindlich verankern — sonst beanspruchen zwei Orte gleichzeitig die Quelle der Wahrheit. In Taktano seit 07-12 umgesetzt: agents.md §6.2 (ops/-first) · HANDOFF-§4-Archiv-Banner · Migrations-Zähler in der generierten Übersicht (gen-ops.mjs). In Taktano wurde der Alt-Bestand am 12.07.2026 per Big-Bang abgeschlossen (PO-Auftrag; ~166 Alt-OPs → ops/*.md, §4 nur noch Pointer, Lastenheft §11 bleibt fachliches detail:-Ziel) — „wandert bei Berührung" trägt also bis der PO den Schlussstrich zieht.

5. Warum das die drei Anforderungen aus §1 erfüllt

• Everything-as-Code: die Datei im Repo ist und bleibt die einzige Quelle; Issues sind reiner, regenerierbarer Konsum — bei Tool-Wechsel (weg von GitHub) geht nichts verloren.
• Stakeholder-Zugänglichkeit: Kommentar + Board in einer UI, die die meisten technisch nicht versierten Beteiligten schon aus PR-Benachrichtigungen kennen — kein neues Tool zu lernen.
• Agenten-Tauglichkeit: ein OP = eine Datei = ein Edit-Aufruf; Claude Code und Codex haben beide native GitHub-Tool-Unterstützung, falls sie zusätzlich mit den gespiegelten Issues interagieren sollen (z. B. Kommentare lesen) — aber die Umsetzung passiert immer im Repo.

Bezug: OP-DOCS-11 (ops/OP-DOCS-11.md), Pilot-OPs: OP-VERTRIEB-1/-2/-3.

---

↩ Zurück zur Doku-Landkarte · Lesepfade · Register (alle OPs)