pedroknigge/documentation-manager

Dokumentations-Manager

Lebendiges Projektwissen für Menschen und KI-Agents. Code ist die Quelle der Wahrheit für wie und ob eine Behauptung wahr ist.
AGENTS.md + docs/ erfassen was, warum, Entscheidungen und Pläne — aber überschreiben niemals den Code, wenn sie widersprechen.

Kernregeln

1. Bevorzuge AGENTS.md als zentralen Hub. Wenn agents.md bereits existiert, verwende es. Wenn nur CLAUDE.md existiert, erweitere es entweder mit einem Docs-Index oder füge AGENTS.md hinzu und verlinke kreuzweise — erstelle nicht drei konkurrierende Hubs.
2. Jedes generierte/aktualisierte Dokument verwendet relative Markdown-Links zurück zum Hub und zu verwandten Dokumenten.
3. Lösche niemals dauerhaftes Wissen ohne Grund; bevorzuge Veraltet durch-Notizen bei ADRs.
4. Auto-Commit und Auto-Push sind nicht erlaubt. Überlasse Git dem Benutzer.
5. Schreibe generierte Inhalte in der Sprache des Benutzers (oder der dominanten Sprache des Repos). Dieser Skill-Text ist aus Ökosystem-Kompatibilität auf Englisch gehalten.
6. Bevorzuge Genauigkeit und Nützlichkeit gegenüber Umfang. Zuerst Kernset; optionale Docs bei Bedarf.
7. Absicht zuerst (Projektebene). Klassifiziere Intent: integrate | audit | from-zero (und optional hybrid). Siehe Schritt 0. Nicht erforderlich für reine Feature-/Plan-/Sync-Aufgaben.
8. Code gewinnt bei Konflikten. Doc-Behauptungen, die die strukturelle Überprüfung nicht bestehen, werden als Widersprochen/Fehlend markiert — erfinde keinen Code, um Docs zu entsprechen; korrigiere oder markiere das Doc.
9. Integrate-first (wenn Intent=integrate). Reife Docs → Index + Lücken + kanonische Links; keine parallele Neuschreibung von Produktvision/Anforderungen/ADRs. Siehe adopt-integrate.
10. Eine Autorität pro Thema. Jedes Thema hat ein kanonisches Dokument; alles andere verlinkt darauf.
11. Abdeckungsmatrix bei adopt/from-zero-Projekt. Produktoberflächen (Nav, ModuleId, Paket) erscheinen als dokumentiert / verlinkt / Lücke.
12. Feature-Atomizität. Ein Slug ≈ eine ModuleId oder ein begrenzter Kontext. Cluster = Index + Kinder.
13. Status-Taxonomie. references/status-taxonomy.de.md.
14. Sandbox opt-in / first-class from-zero. Out: sandbox:p Pfad wenn vom Benutzer angefordert (test/, usw.). Sandbox-Hubs zeigen Banner als Nicht-SSOT + Promotionsplan.
15. Feature-Autopilot (v1.5 / v2). Einfach „neues Feature X“ / „dokumentiere X“ → Skill wählt Plan vs Feature-Pack, wendet Standard-Non-writes an, setzt Kind (neues Feature | Spike | Epic | Redesign). Implementierungsbrücke (Platzierung / Stubs) nur bei Opt-in („implementiere“, „Stubs“, „Scaffold“) — Standard ist Docs-only + einzeiliger Hinweis. Siehe modes.de.md §3 und implementation-bridge.de.md.
16. Plan-Modus (v1.3+). Greenfield-Feature-Ideen landen in docs/plans/<slug>/, nicht in einem Fake-Implementierungspaket und nicht in einem vollständigen Projekt-Bootstrap. Befördere zu docs/features/<slug>/, wenn Code real ist (nicht nur Stubs).
17. ArkGate-Brücke (v1.4). Wenn ArkGate erkannt wird (ark.config.json, ark-check, .ark/, Ark-Skills) oder der Benutzer gerade ein Gate abgeschlossen hat, führe den Bridge-Teilablauf aus: Inventar aus dem Vertrag anreichern; nach Gate-Bestehen → bereichsbezogene Sync / Audit; verbleibende Verstöße → markiere Behauptungen als Widersprochen/Teilweise — schreibe niemals Docs um, um kaputte Architektur zu entschuldigen. Kein Ark → keine Operation. Platzierungshinweise in der Implementierungsbrücke verwenden Ark-Ebenen, wenn erkannt. Siehe arkgate-bridge.de.md und modes.de.md §9.
18. Wissensdashboard (v1.6). Optionale statische HTML-Ansicht von Plänen/Features/Behauptungen (scripts/generate-docs-dashboard.sh → docs/audit/generated/dashboard.html). Markdown ist SSOT; HTML ist gitignorierte Ansicht nur. Biete nach einem Audit einmal an oder auf „Dashboard“-Anfrage. Siehe knowledge-dashboard.de.md und modes.de.md §10.
19. Skill-Härtung (v1.7). Betreiber: führe validate-skill.sh + test-skill-hardening.sh vor der Veröffentlichung aus. Agents: erkenne Installation/Version über skill-discovery.de.md; schlage Neuinstallation vor, wenn veraltet (kein stiller Auto-Patch).
20. v2.0-Paket. Vervollständigt die 10×-Linie: Fähigkeiten 1.4–1.7 plus docs/adoption-matrix.de.md Tracking. Basis-Installations-Schwelle bleibt 2.0.0; polyglot 2.1.0; monorepo 2.2.0; team 2.3.0; Bridge komplett 2.4.0; aktuelle Linie ist 2.5.0+ (Knowledge OS erster Schritt zu 100× — lebendige Behauptungen + CI-Audit; keine zweite 10×).
21. Polyglotte Stack-Erkennung (v2.1 Slice A / skill 2.1.0). Bei Projekterkennung (integrate / audit / from-zero / adopt) erkenne Stack aus Dateisystem (package.json, pyproject.toml, go.mod, …) über skill-discovery.de.md Polyglotte Stack-Erkennung (oder scripts/detect-stack.sh). Verwende Inventar nach Stack und Docs-Layout-Anleitung nach Stack — nimm nicht Node/TS an. Erfinde niemals ModuleIds/Endpunkte für Frameworks ohne Code-Nachweis. Siehe modes.de.md §0.3.
22. Monorepo-Hubs (v2.2 Slice B). Erkenne Multi-Package-Bäume (pnpm-workspace.yaml, package.json workspaces, go.work, Multi-Package-Verzeichnisse) über skill-discovery.de.md Monorepo-Hubs (oder scripts/detect-packages.sh). Root-Hub ist eine Karte + Paketindex, kein Dump; Multi-Package-Abdeckung markiert Lücken-Pakete; Standard Paket-Non-writes bei nur Indexierung des Roots. Siehe modes.de.md §0.4.
23. Team-Governance (v2.3 Slice C). Optionales docs/team/ mit Owners + Zustimmungsnotizen (last-approved-Stil). Erstellen vs. Verlinken pro team-governance.de.md; Hub verlinkt Team, ohne ein HR-Wiki zu werden; Integrate-first — Hinzufügen des Teams muss nicht Produktvision / Anforderungen / ADRs umschreiben. Kein CODEOWNERS-Engine oder BPM. Siehe modes.de.md §11.
24. Template-Telemetrie (v2.4 Slice D). Opt-in lokales Ledger für nur Template-/Skill-UX-Lücken (template-telemetry.de.md; scripts/template-telemetry.sh). Standardmäßig aus; sende niemals Quellen/Geheimnisse/Repo-URLs; niemals Netzwerk; keine Operation bei Luftspalt, wenn Opt-in aus ist. Siehe modes.de.md §12.
25. Lebendige Behauptungen + CI-Strukturaudit (v2.5 / Knowledge OS erster Schritt). Audit-Matrizen verwenden lebendige Behauptungen v0: anchor.path / optional anchor.symbol / optional anchor.hash, severity (critical | normal), Urteile unverändert. Matrix-zuerst (audit-template.de.md); Verfahren living-claims.de.md; Draht ADR-0001.de.md. Wahrheitswert bleibt beratend (Dashboard-Heuristik); lokal, luftspalt scripts/audit-claims.sh / Beispiel docs-audit CI ist das Tor (Fehlschlag bei kritischem Widersprochen). Kein SaaS. Siehe modes.de.md §6 / §13.

Schritt 0 — Umfang, Modus und Absicht erkennen

Umfang (erforderlich):

Umfang	Wann	Ausgabefokus
project	Gesamtes Produkt / „Dokumentation für das Projekt“	Hub + Projektdokumente (pro Absicht)
feature	Benanntes Feature/Modul mit Code (oder Aktualisierungspaket)	docs/features/<slug>/ + Hub-Link
plan	Benanntes neues Feature / Epic vor oder ohne soliden Code	docs/plans/<slug>/ + Hub-Link
hybrid	Feature/Plan, wenn noch kein Hub vorhanden	Paket oder Plan + minimaler Hub

Modus (erforderlich):

Modus	Signale
bootstrap	Greenfield, kein Hub/Docs, oder Intent from-zero auf leer/dünn
adopt	Code existiert; Docs dünn/fehlend oder Intent integrate
audit	„Docs auditieren“, „Docs vs Code“, Abweichung, Behauptungen validieren
plan	„neues Feature“, „Plan“, „Epic“, „vamos a construir X“ ohne Code
feature	Ein Feature/Modul dokumentieren, das Code hat (oder ist)
sync	Diff / PR / Docs für eine Änderung aktualisieren; nach Gate, wenn Ark gerade bestanden
roadmap	Release / Epic-Liste aktualisieren planen

Absicht (nur für Projektebene erforderlich):

Absicht	Benutzersignale (Beispiele)	Verhalten
integrate	„Docs verbessern“, „ordnen“, „Hub sync“, reife Verbesserung	adopt-integrate (oder vollständig, wenn dünn); optionale Pre-Audit, wenn Abweichung vermutet
audit	„auditar“, „lügen die Docs?“, „Docs vs Code“, „Pfade validieren“	Nur Code-Inventar + Behauptungsmatrix (oder dann übergeben)
from-zero	„komplett neu“, „von Null“, „generiere Docs in test/“, „volles KB in Ordner X“	Vollständige Wissensbasis; bevorzuge Sandbox, wenn Pfad angegeben; code-inferiert; alte Docs = nur Hypothese

Inferenz (nicht überfragen):

• „neue Feature X“ / „new feature X“ / „quiero agregar X“ → Feature-Autopilot (Plan, wenn kein Code, Feature, wenn Code; Kind aus Formulierung). Absicht = n/a
• „implementiere X“ / „generiere Stubs“ / „scaffold X“ → Autopilot Stufe A, falls nötig + Implementierungsbrücke Opt-in (Code nur, wenn Stubs angefordert)
• „generiere die gesamte Dokumentation in test/“ → Intent: from-zero | Out: sandbox:test/
• Reifes Repo + „verbessere / integriere / indexiere“ → Intent: integrate
• „Docs auditieren“ / „Code vs Docs“ → Intent: audit
• Mehrdeutige Projektarbeit mit vorhandenem docs/ → einmal fragen: integrate | audit | from-zero
• Benannte einzelne Oberfläche → nie verlangen, dass der Benutzer Non-writes auflistet oder Ordner wählt
• „nach ark-check“ / „post-gate Docs“ / Gate gerade gelaufen + Docs-Absicht → sync oder audit mit ArkGate-Brücke
• „Dashboard“ / „Docs HTML“ / „Wissensbericht“ → generiere Wissensdashboard (knowledge-dashboard.de.md)
• „Owners“ / „quién es dueño“ / „team docs“ / „approval notes“ / „docs/team“ → Team-Governance (team-governance.de.md; Modi §11)
• „template telemetry“ / „opt-in telemetry“ / „record template gap“ → Template-Telemetrie nur, wenn Benutzer zustimmt (template-telemetry.de.md; Modi §12); Standard aus
• „lebendige Behauptungen“ / „Wahrheitswert“ / „Docs CI“ / „Fehlschlag bei Widersprochen“ → Lebendige Behauptungen + lokales CI-Tor (living-claims.de.md; Modi §13)

Reife (wenn relevant): dünn | gemischt | reif — siehe modes.de.md.

Wenn Umfang/Modus nach Inferenz noch mehrdeutig, einmal fragen. Lade Verfahren aus references/modes.de.md.

Vor dem Schreiben ankündigen:

Scope: <x> | Mode: <y> | Intent: <integrate|audit|from-zero|n/a> | Variant: <full|integrate|arkgate-bridge|n/a> | Maturity: <…|n/a> | Out: <root|sandbox:path> | Stack: <node-ts|python|go|mixed|unknown|n/a> | Monorepo: <yes|no|n/a> | ArkGate: <none|detected> | Slug: <slug|n/a>

Wenn integrate, liste Non-writes (Paket-Non-writes einschließen, wenn monorepo nur Root-Index). Wenn audit, liste Matrix-Pfad und Hauptwidersprüche. Wenn from-zero + Sandbox, Promotionsplan einschließen. Wenn plan oder feature, liste Pfad + Standard-Non-writes. Wenn ArkGate-Brücke, liste Signale und Post-Gate-Sync vs Audit-Anreicherung. Wenn Projektebene, Stack und Monorepo aus der Erkennung einschließen.

Empfohlenes Layout

project-root/
├── AGENTS.md
└── docs/
    ├── product-vision.md      # bootstrap / from-zero / adopt-full
    ├── requirements.md
    ├── architecture.md
    ├── roadmap.md
    ├── team/                  # v2.3 team governance (optional)
    │   ├── OWNERS.md
    │   └── approval-notes.md
    ├── audit/                 # Intent audit (optional)
    │   └── claims-matrix.md   # living claims v0 columns
    ├── adr/                   # package / project ADRs (optional)
    ├── plans/<slug>/          # v1.3 plan mode (pre-code / epic)
    │   └── README.md
    ├── decisions/
    └── features/<slug>/       # code-backed feature packs

Unterstützende Docs nur, wenn gerechtfertigt (außer from-zero, das ein vollständiges minimales Kernset erstellen kann).

Artefakt-Matrix (Zusammenfassung)

Artefakt	from-zero / bootstrap	integrate (reif)	audit	plan	feature	sync
Hub	erstellen	erweitern / indizieren	Status optional aktualisieren	Plans verlinken	verlinken	falls nötig
Kern-Docs	ja	keine Neuschreibung	nein (nur lesen)	nein	nein	falls Auswirkung
Abdeckungsmatrix	ja	erforderlich	Teil des Inventars	Zeile optional	Zeile	aktualisieren
Behauptungsmatrix	optional vor	empfohlen, wenn Abweichung	erforderlich	n/a	bereichsbezogen, wenn Audit	falls Abweichung
Plans docs/plans/	n/a	n/a	n/a	erforderlich	verlinken, falls vorhanden	falls Auswirkung
Feature-Pakete	Schlüsseldomänen	Lücken / Einträge	nein (außer gefragt)	nein (bis Beförderung)	erforderlich	falls Auswirkung
Team docs/team/	wenn Owners bekannt	erstellen/verlinken, wenn gefragt	nein	n/a	n/a	falls Auswirkung
Paralleler vollständiger Baum	Sandbox ok	verboten bei Root	n/a	n/a	n/a	n/a

Arbeitsablauf (alle Modi)

1. Schritt 0 — Umfang, Modus, Intent (wenn Projekt), Reife/Variante, Out, Slug; erkenne ArkGate-Signale, wenn relevant; erkenne Stack und Monorepo für Projektarbeit (skill-discovery.de.md Polyglot + Monorepo-Hubs).
2. Code zuerst erkennen — Stack-bewusstes Inventar; wenn monorepo, Paketindex + pro-Paket-Inventar; Baum, Manifeste, Einstiegspunkte, Beispiel-Tests. Dann Docs (falls vorhanden). Für benannte Features diese Oberfläche zuerst durchsuchen. Wenn Ark erkannt, Inventar pro arkgate-bridge.de.md anreichern.
3. Wenn audit oder Docs existieren und Intent integrate/from-zero mit vermuteter Abweichung: Abgleich durchführen (modes.de.md § Audit, audit-template.de.md). Nach Gate → Bridge-Übergabe (modes.de.md §9).
4. Dateien planen — erstellt/aktualisiert und Non-writes (Standard für Feature/Plan).
5. …

[truncated]