truthmark/README.de.md

Truthmark

Deine Agenten schreiben Code. Truthmark hält menschenlesbare Dokumentation in Git überprüfbar.

English | Deutsch | 中文 | Español | Русский

KI-Coding-Agenten können ein Repository schneller verändern, als Menschen die Dokumentation ausrichten können.

Truthmark repariert den Teil, der normalerweise nach dem Code-Schreiben bricht: die Repository-Truth.

Es installiert eine Git-native, branch-gebundene Workflow-Schicht, die KI-Coding-Agenten hilft, die richtigen Dokumente zu aktualisieren, Ownership-Grenzen zu respektieren und Menschen normale Diffs zur Prüfung zu hinterlassen.

Kein gehosteter Dienst.

Keine Datenbank.

Keine verborgene Memory-Schicht.

Kein zusätzlicher Server im Betrieb.

Nur Repository-Truth, die mit dem Branch mitwandert.

Das Problem

KI-Coding-Agenten sind gut darin, Code zu erzeugen. Dadurch entsteht eine neue Fehlerart.

Die Implementierung ändert sich, aber die Repository-Erzählung driftet ab:

• Verhalten lebt im Chatverlauf
• Architekturdokumente fallen zurück
• Produktentscheidungen verschwinden nach der Übergabe
• Reviewer sehen Code-Diffs ohne die zugehörigen Truth-Diffs
• Branches entwickeln unbemerkt unterschiedliche Versionen davon, „was wahr ist“
• jede Agentensitzung muss Repository-Truth neu entdecken

Truthmark verwandelt diese fragile Repository-Truth in versionierte Repository-Infrastruktur.

Statt darauf zu vertrauen, dass jeder Mensch und jeder Agent die richtige Dokumentationsgewohnheit beibehält, installiert Truthmark diese Gewohnheit im Repository.

Das Versprechen

Wenn ein Agent funktionalen Code ändert, sollte die Arbeit nicht mit einem reinen Code-Diff enden.

Der normale Truthmark-Pfad ist:

agent ändert funktionalen Code
relevante Tests laufen
Truth Sync prüft zugeordnete Truth-Dokumente
Truth-Dokumente werden bei Bedarf aktualisiert
Mensch prüft Code-Diff + Truth-Diff
committen oder übergeben

Das ist der Kernwert: KI-Arbeit wird leichter vertrauenswürdig, weil das Repository lesbar bleibt.

Zwei Schnittstellen, ein Truth-System

Truthmark ist nicht nur eine CLI.

Es hat zwei unterschiedliche Schnittstellen, und diese Unterscheidung ist wichtig.

1. CLI für Menschen

Die CLI ist für Maintainer, Reviewer und Automatisierung.

Nutze sie, um ein Repository zu konfigurieren, Workflow-Dateien zu installieren oder zu aktualisieren, Truth-Artefakte zu validieren und optionales Review-Material zu erzeugen.

truthmark config
truthmark init
truthmark check

Die CLI bereitet die Repository-Umgebung vor und validiert sie.

Sie ist nicht die Runtime für den KI-Workflow.

2. KI-seitige Workflow-Schnittstellen

Die KI-seitigen Schnittstellen sind für Coding-Agenten.

Truthmark installiert host-native Skills, Prompts, Commands, verwaltete Instruktionsblöcke und unterstützte Subagent-Schnittstellen, damit KI-Agenten repository-spezifische Truth-Workflows in ihren normalen Coding-Tools befolgen können.

Beispiele:

/truthmark-sync
/truthmark-document
/truthmark-structure
/truthmark-realize
/truthmark-preview
/truthmark-check

Sie sehen wie Befehle aus, weil Agenten-Hosts Workflows über Slash-Commands, Prompts, Skills oder Projektbefehle bereitstellen.

Es sind keine Shell-Befehle.

Es sind KI-seitige Workflow-Einstiegspunkte.

Die Trennung ist das Produkt:

Menschen besitzen den Repository-Vertrag
Truthmark installiert den Vertrag ins Repo
Agenten arbeiten innerhalb dieses Vertrags
Truth-Updates erscheinen als Git-Diffs
Menschen prüfen das Ergebnis

Quick Start

Voraussetzungen

• Node.js >=20
• npm
• ein Git-Repository

Truthmark installieren

Führe dies in dem Repository aus, das du initialisieren möchtest:

cd /path/to/your-repo
npm install -g truthmark

Den Repository-Truth-Vertrag erstellen

truthmark config

Das erzeugt:

.truthmark/config.yml

Prüfe diese Datei, bevor du fortfährst. Sie definiert den versionierten Hierarchievertrag für das Repository.

Die Workflow-Schnittstellen installieren

truthmark init

Das installiert oder aktualisiert:

• Routendateien
• Truth-Doc-Scaffolding
• verwaltete Instruktionsblöcke
• KI-seitige Workflow-Schnittstellen für konfigurierte Plattformen

Die Standardvorlagen für Truth-Dokumente werden in Template Standards begründet. Dort werden sie anerkannten Software-Engineering-Referenzen wie ISO/IEC/IEEE 42010, ISO/IEC/IEEE 29148, ISO/IEC/IEEE 12207, ISO/IEC 25010, C4, arc42, OpenAPI, SemVer, Google SRE und Diátaxis zugeordnet.

Das Setup validieren

truthmark check

Prüfe danach die generierten Dateien, bevor du committest.

Die konkreten Dateien hängen von .truthmark/config.yml ab, aber die Installation hat immer dieselbe Form: Routing, Truth-Scaffolding, kompakte verwaltete Instruktionen und host-native Workflow-Schnittstellen für die aktivierten Plattformen.

Erste echte Nutzung

Die meisten Repositories brauchen nach der Initialisierung einen Aufräumschritt.

Das Standard-Scaffold beginnt mit einem vorläufigen breiten Bootstrap-Bereich repository. Bevor echter Code normal synchronisiert wird, teile diese Bootstrap-Route in präzises Routing auf.

Bitte deinen Agenten, die breite Route in tatsächliche Produkt-, Service-, Domänen- oder Ownership-Bereiche aufzuteilen:

/truthmark-structure die breite repository-area in auth, billing und notifications aufteilen

Wenn das Projekt bereits implementierte Features hat, aber Truth-Dokumente fehlen oder schwach sind, bitte den installierten Truth-Document-Workflow, einen fokussierten Bereich zu dokumentieren:

/truthmark-document dokumentiere das implementierte payment-retry-verhalten in src/billing/retry.ts und den zugehörigen tests

Truth Document ist der häufigste erste Workflow für bestehende Projekte. Er inspiziert Implementierung, Tests, Routen und vorhandene Dokumentation und erstellt oder repariert danach Truth-Dokumente und Routing, ohne funktionalen Code zu ändern.

Danach nutzt du deinen KI-Coding-Agenten normal.

Wenn der Agent funktionalen Code ändert, wirkt Truth Sync als Abschlusskontrolle und prüft vor der Übergabe, ob zugeordnete Truth-Dokumente geändert werden müssen.

Was du bekommst

Fähigkeit	Was sie tut
Git-native Repository-Truth	Hält Repository-Truth in versioniertem Markdown und Config.
Branch-gebundene Dokumentation	Repository-Truth wandert mit dem Branch statt in einer privaten Sitzung zu leben.
CLI für Menschen	Gibt Maintainern Befehle für Setup, Aktualisierung, Validierung und Inspektion.
KI-seitige Workflows	Gibt Agenten host-native Workflows für Sync, Dokumentation, Struktur, Preview, Realisierung und Audit.
Explizites Routing	Ordnet Codebereiche kanonischen Truth-Dokumenten zu.
Prüffähige Übergaben	Erzeugt normale Git-Diffs für Code und Truth-Dokumente.
Local-first-Betrieb	Benötigt keinen gehosteten Dienst, keinen Daemon, keine Datenbank und keinen MCP-Server.
Sicherere Schreibgrenzen	Trennt code-first, doc-first, read-only und doc-only Workflows.
Validierung	Meldet Probleme bei Routing, Autorität, Frontmatter, Links, generierten Schnittstellen, Branch-Scope, Freshness und Coverage.
Optionales Portal	Erzeugt eine versionierte statische HTML-Präsentationssite aus Markdown-Truth-Dokumenten, wenn es ausdrücklich aktiviert und angefragt wird.

Visueller Überblick

Funktionen: was Truthmark installiert und wie die Workflow-Oberfläche aufgeteilt ist.

Positionierung: wo Truthmark im Verhältnis zu Prompts, Memory und Spec-Workflows steht.

Sync-Ablauf: wie Truth Sync normale Codeänderungen vor der Übergabe abschließt.

Warum Teams es nutzen

Truthmark ist für Teams, die bereits wissen, dass KI-Agenten Code erzeugen können.

Das nächste Problem ist Governance.

Nicht Governance als Zeremonie. Governance als einfache Frage:

Erzählt das Repository nach dieser KI-gestützten Änderung noch den aktuellen Stand?

Truthmark hilft Teams, diese Frage mit versionierten Dateien, explizitem Routing und prüffähigen Diffs zu beantworten.

Es ist nützlich, wenn du Folgendes brauchst:

• weniger Dokumentationsdrift
• bessere Übergaben
• branch-spezifische Produktwahrheit
• dauerhafte Architektur- und API-Dokumentation
• explizite Ownership zwischen Dokumentation und Code
• sicherere Schreibgrenzen für Agenten
• prüffähige Dokumentation statt verborgener Memory
• KI-Workflows, die weiterhin aus versionierten Repo-Dateien funktionieren

Wo Truthmark hineinpasst

Truthmark ersetzt keine Prompts, Memory, Specs, Tests oder Code Review.

Es gibt diesen Workflows einen dauerhaften Ort in Git.

Bedarf	Besser passend
Bessere Ausgabe aus einer Agentensitzung	Besserer Prompt
Persönliche oder sitzungsbezogene Kontinuität	Memory-Tool
Plan-first Feature-Arbeit	Spec-Workflow
Branch-bezogene Repository-Truth, die mit dem Code mitwandert	Truthmark
Korrektheit von Verhalten validieren	Tests und Review
KI-gestützte Dokumentationsänderungen prüfen	Truthmark plus Git-Review

Truthmarks Spur ist absichtlich eng:

Repository-Truth explizit machen
sie zu Code routen
Agenten-Workflows darum installieren
das Ergebnis in Git prüffähig halten

Wie Truthmark läuft

Truthmark läuft lokal gegen den aktiven Git-Worktree.

Die CLI für Menschen liest und schreibt Repository-Dateien und beendet sich danach.

Die KI-seitigen Workflow-Schnittstellen sind versionierte Dateien, die Agenten-Hosts später laden können. Dadurch können Agenten dem installierten Workflow aus dem Repository-Zustand folgen, statt von einem Hintergrundprozess von Truthmark abzuhängen.

Die Schichten greifen so ineinander:

flowchart LR
  Human["Human / CI"] --> CLI["Truthmark CLI"]
  CLI --> Config["Config und Routing"]
  CLI --> Truth["Kanonische Truth-Dokumente"]
  CLI --> Surfaces["Generierte host-native Workflows"]
  Surfaces --> Hosts["Codex / Claude Code / Copilot / OpenCode / Gemini"]
  Hosts --> Worktree["Aktiver Git-Worktree"]
  Hosts -->|"helper checks / validate / index"| CLI
  Worktree --> Truth

Agents sprechen nicht mit einem Truthmark-Daemon, können aber die installierte Truthmark CLI ausführen, wenn ein Workflow Validierung, Indexing oder Helper-Checks verlangt.

Truthmark besitzt die generierten Workflow-Schnittstellen, aber der wichtige Vertrag ist architektonisch: repo-lokale Config und Routing zeigen Agents auf kanonische Truth-Dokumente, während host-native Workflows jedem unterstützten Agent einen eigenen Weg geben, dieselben Truthmark-Prozeduren auszuführen.

Generierte Workflow-Schnittstellen enthalten Truthmark-Versionsmarker. Nach einem Upgrade von Truthmark erneut ausführen:

truthmark init

Prüfe danach die generierten Diffs.

Unterstützte Agentenplattformen

Die Standardkonfiguration enthält jede unterstützte Plattform.

Entferne Plattformen, die du nicht nutzt, aus .truthmark/config.yml, und führe danach erneut aus:

truthmark init

Plattform-Configname	Generierte Oberfläche	Aufrufform
codex	.agents/skills/truthmark-*/, .codex/agents/	/truthmark-* oder $truthmark-*
claude-code	.claude/skills/truthmark-*/, .claude/agents/, CLAUDE.md	/truthmark-*
github-copilot	.github/skills/truthmark-*/, .github/prompts/, .github/agents/, .github/copilot-instructions.md	/truthmark-* in unterstützten Copilot-IDEs; @truth-* Custom Agents in Copilot CLI
opencode	.opencode/skills/truthmark-*/, .opencode/agents/	/skill truthmark-*
gemini-cli	.gemini/skills/truthmark-*/, .gemini/commands/truthmark/, .gemini/agents/, GEMINI.md	/truthmark:*

Unbekannte Plattformnamen sind Config-Fehler.

Das Entfernen einer Plattform stoppt künftige Aktualisierungen für diese Plattform. Es löscht zuvor generierte Dateien nicht.

KI-seitige Workflows

Diese Workflows werden in unterstützte KI-Coding-Hosts installiert.

Sie werden von Agenten oder Agenten-Hosts während der Repository-Arbeit genutzt. Sie sind keine Top-Level-Shell-Befehle.

Workflow	Richtung	Nutze ihn, wenn	Schreibgrenze
Truth Structure	topology-first	Die Standardroute zu breit ist, Ownership mehrere Bereiche umfasst oder Routendateien noch auf Platzhalter zeigen.	Erstellt oder repariert Routing und Starter-Truth-Dokumente.
Truth Document	implementation-first	Verhalten bereits im Code existiert, aber kanonische Truth-Dokumente fehlen oder schwach sind.	Schreibt nur Truth-Dokumente und Routing. Funktionaler Code darf nicht geändert werden.
Truth Sync	code-first	Funktionaler Code geändert wurde und zugeordnete Truth-Dokumente vor der Übergabe aktualisiert werden müssen könnten.	Aktualisiert Truth-Dokumente. Funktionaler Code darf von Truth Sync nicht umgeschrieben werden.
Truth Preview	read-only	Der Agent vor Änderungen wahrscheinliches Routing einschätzen muss.	Liest nur. Autorisiert keine Schreibzugriffe.
Truth Realize	doc-first	Produkt- oder Architektur-Truth-Dokumente führen und Code daran angepasst werden soll.	Aktualisiert nur Code. Der Agent darf die Truth-Dokumente, die er realisiert, nicht bearbeiten.
Truth Check	audit-first	Ein Reviewer oder Agent die Gesundheit der Repository-Truth auditieren muss.	Auditiert und berichtet.
Truthmark Portal	presentation-only	Ein Mensch ausdrücklich eine durchsuchbare statische HTML-Portalansicht über Repository-Truth-Dokumente anfordert.	Schreibt generierte nicht-kanonische statische Dateien nur unter dem konfigurierten Portal-Ausgabeverzeichnis.

Wichtige Unterscheidung

Verwechsle diese zwei Schnittstellen nicht:

Schnittstelle	Genutzt von	Beispiel	Bedeutung
CLI für Menschen	Menschen, Skripte, CI-ähnliche Checks	truthmark check	Truth-Artefakte des Repositorys im Terminal validieren.
KI-seitiger Workflow	Coding-Agenten und Agenten-Hosts	/truthmark-check	Einen Agenten bitten, den installierten Audit-Workflow auszuführen.

Die Namen sind absichtlich verwandt, aber die Schnittstellen sind unterschiedlich.

Normale KI-gestützte Codeänderung

Die meisten Nutzer sollten Truth Sync nicht jedes Mal manuell aufrufen müssen.

Truth Sync ist die installierte Abschlusskontrolle für funktionale Codeänderungen.

agent ändert funktionalen Code
agent führt relevante Tests aus oder fordert sie an
installierter Workflow erkennt, dass funktionaler Code geändert wurde
Truth Sync prüft zugeordnete Truth-Dokumente
agent aktualisiert Truth-Dokumente bei Bedarf
Mensch prüft Code-Diff + Truth-Diff

Der direkte Aufruf ist trotzdem nützlich für Fehlersuche, frühes Synchronisieren oder eine explizite Übergabe:

/truthmark-sync die Repository-Truth jetzt vor der Übergabe synchronisieren

Bestehendes Verhalten ohne Doku

Nutze Truth Document, wenn die Implementierung bereits existiert, aber die Repository-Truth unvollständig ist. Das ist der normale Weg für etablierte Repositories, die Truthmark übernehmen, nachdem die Codebasis bereits existiert.

/truthmark-document dokumentiere das implementierte session-timeout-verhalten über src/auth/session.ts, src/auth/middleware.ts und tests/auth/session.test.ts

Gib den Feature-Namen, Codepfade, Testpfade oder den gewünschten Truth-Doc-Bereich an. In OpenCode-ähnlichen Hosts rufst du denselben Workflow als /skill truthmark-document ... auf; in Gemini CLI nutzt du /truthmark:doc ....

Bei einem großen Repo, das noch eine breite Platzhalterroute hat, führe zuerst Truth Structure aus und rufe danach Truth Document für jeweils ein abgegrenztes Feature oder einen Bereich auf.

Truth Document prüft Implementierung, Tests, Routendateien und vorhandene Dokumente als Evidenz.

Es schreibt nur Truth-Dokumente und Routing.

Es darf keinen funktionalen Code ändern.

Doc-first-Änderungen

Nutze Truth Realize, wenn eine Produkt- oder Architekturentscheidung in Dokumenten beginnt und Code daran angepasst werden soll.

/truthmark-realize docs/truthmark/product/capabilities/session-timeout.md in Code realisieren

Truth Realize ist doc-first.

Die Truth-Dokumente führen. Der Code folgt.

Der Agent darf die Truth-Dokumente, die er realisiert, nicht bearbeiten.

Read-only-Routing-Preview

Nutze Truth Preview vor einer Änderung, wenn der Agent wahrscheinliches Routing verstehen muss.

/truthmark-preview das wahrscheinliche Truth-Routing für Änderungen an der Billing-API prüfen

Truth Preview ist read-only.

Es ist Auswahl- und Planungshilfe, keine Schreibautorisierung und kein Ersatz für Truth Check.

Repository-Truth-Audit

Nutze Truth Check, wenn du einen agentenorientierten Audit-Workflow möchtest.

/truthmark-check Routing und Truth-Coverage vor dem Review auditieren

Nutze die CLI für Menschen, wenn du Terminalvalidierung möchtest:

truthmark check

Beides ist nützlich. Es ist nicht dieselbe Oberfläche.

CLI-Befehle für Menschen

Die meisten Maintainer beginnen mit drei Befehlen.

Befehl	Zweck
truthmark config	Erstellt .truthmark/config.yml. Schreibt nur diese Datei, außer --stdout wird verwendet.
truthmark init	Installiert oder aktualisiert konfigurierte Workflow-Schnittstellen aus der geprüften Config.
truthmark check	Validiert Config, Autorität, Routing, entscheidungstragende Dokumente, Frontmatter, interne Links, Branch-Scope, generierte Oberflächen, Freshness und Coverage-Diagnostik.

Optionale Repository-Intelligence-Helfer erzeugen abgeleitetes Review-Material für den aktiven Checkout, etwa RepoIndex-, RouteMap-, ImpactSet- und kompaktes WorkflowState/action-context-JSON. Generierte Workflow-Skill-Pakete können außerdem Helper-Manifeste und Helper-Policies bereitstellen, die installierte truthmark validate ... --json CLI-Validatoren aufrufen; diese Helpers sind Beschleuniger, keine im Repository gebündelten lokalen Skripte und keine Quellen der Wahrheit. Eigenständige Copilot-Prompts und Gemini-Commands verwenden denselben CLI-Validator-Vertrag, wenn der installierte Runner verfügbar ist; andernfalls melden sie einen sichtbaren übersprungenen Helper-Status und führen eine manuelle Validierung durch.

Sie sind keine Quellen der Wahrheit.

Befehl	Zweck
truthmark index	Baut RepoIndex- und RouteMap-JSON für den aktiven Checkout.
truthmark impact --base <ref>	Ordnet geänderte Dateien gerouteten Truth-Dokumenten, besitzenden Routen, nahen Tests und öffentlichen Symbolen zu.
truthmark workflow status --workflow <workflow> [--base <ref>] --json	Liefert Workflow-Anwendbarkeit, Schreibgrenzen, Ziel-Truth-Dokumente, Checks, Helper-Commands und kompakte Hinweise zu betroffenen Tests.

Strukturierte Ausgabe ist mit --json verfügbar, wo sie unterstützt wird.

Truthmark Portal

Truthmark Portal ist ein optionaler Präsentations-Workflow für Teams, die eine menschenlesbare Site über ihren versionierten Truth-Dokumenten möchten.

Er ist bewusst vom Kern-Truth-Workflow getrennt:

• Markdown-Truth-Dokumente bleiben kanonisch.
• Generiertes Portal-HTML dient nur der Präsentation.
• Portal wird nur manuell ausgeführt; es läuft nicht als Completion-Gate, Truth-Sync-Schritt, truthmark check-Schritt oder automatischer Post-Change-Hook.
• Portal-Schreibzugriffe bleiben im konfigurierten Ausgabeverzeichnis, sofern der Nutzer den Scope nicht ausdrücklich ändert.
• Generierte Seiten sollten lokale Assets, Quellen-Provenance und einen sichtbaren Markdown-ist-kanonisch-Hinweis verwenden.

Aktiviere es mit dem namespaced Config-Block:

truthmark:
  generated:
    portal:
      enabled: true

Dann erneut ausführen:

truthmark init

Wenn aktiviert, installiert Truthmark host-native Portal-Workflow-Schnittstellen für die konfigurierten Plattformen, etwa /truthmark-portal oder /truthmark:portal je nach Agenten-Host.

Konfiguration

Truthmark ist config-first.

Die wichtigste Config-Datei ist:

.truthmark/config.yml

Neue Repositories sollten ausführen:

truthmark config

Prüfe danach die generierte Config, bevor du ausführst:

truthmark init

Wichtige Config-Bereiche sind:

Config-Bereich	Zweck
version	Version des Config-Vertrags.
platforms	Agenten-Hosts, die plattformspezifische generierte Oberflächen erhalten sollen.
truthmark.workspace	Truthmark-eigener Workspace für Routen, Truth-Dokumente, Vorlagen und generierte Präsentationsausgabe.
Feste Routen	Routen liegen unter routes/areas.md und routes/areas/ innerhalb von truthmark.workspace; die Standard-Area ist repository, die Delegationstiefe ist 1.
Feste Truth-Lanes	Product-Truth liegt unter product/ und Engineering-Truth unter engineering/ innerhalb von truthmark.workspace.
Feste Vorlagen	Truth-Dokumentvorlagen liegen unter templates/ innerhalb von truthmark.workspace.
truthmark.generated.portal	Optionale manuelle Präsentations-Workflow-Aktivierung: enabled.
instruction_targets	Dateien, die gemeinsam verwaltete Instruktionsblöcke erhalten, etwa AGENTS.md.
frontmatter.required	Metadatenfelder, die bei Fehlen Error-Diagnostik erzeugen.
frontmatter.recommended	Metadatenfelder, die bei Fehlen Review-Diagnostik erzeugen.
ignore	Glob-Muster, die von relevanten Checks und Routing-Logik ausgeschlossen sind.

Repository-Truth-Routing

Truthmark ordnet Codeoberflächen Truth-Dokumenten zu.

Die wichtigsten Routendateien sind:

docs/truthmark/routes/areas.md
docs/truthmark/routes/areas/**/*.md

Eine Route sagt dem Agenten:

• welche Codeoberfläche zu einem Bereich gehört
• welche Truth-Dokumente diesen Bereich besitzen
• wann Truth aktualisiert werden sollte
• welche Art von Truth-Dokument beteiligt ist

Das Standard-Scaffold beginnt mit einer vorläufigen breiten Bootstrap-Route, damit ein neues Repository routbar ist. Wenn echter Code berührt wird, teile diese Bootstrap-Route vor normalem Truth Sync in echte Produkt-, Service-, Domänen- oder Ownership-Bereiche auf; mache den Bootstrap-Handoff nicht zu einem Catch-all-Verhaltensdokument.

Beispiel:

/truthmark-structure die breite repository-area in frontend, backend, billing und deployment aufteilen

Gutes Routing gibt Truth Sync präzise Ziele.

Schlechtes Routing zwingt Agenten zum Raten.

Was Truthmark installiert

Truthmark installiert eine kompakte, repository-native Truth-Schicht.

Das geschieht in vier Schichten:

• Config und Routing für Ownership-Grenzen
• kanonische Truth-Dokumente und Starter-Templates
• kompakte verwaltete Instruction-Blöcke für repositoryweite Agent-Instruktionen
• host-native Workflow-Pakete, Commands, Prompts und Verifier-Agents für die in der Config aktivierten Plattformen

Truthmark bewahrt manuellen Inhalt außerhalb verwalteter Instruktionsblöcke.

Generierte Workflow-Schnittstellen werden von Truthmark verwaltet und können durch erneutes Ausführen aktualisiert werden:

truthmark init

Subagents und begrenzte Evidenzprüfungen

Wo der Host es unterstützt, kann Truthmark projektbezogene Prüf-Agenten und einen geleasten truth-doc-writer installieren.

Diese helfen, große Truth-Aufgaben begrenzt zu halten:

• Route Auditors prüfen Route-Ownership
• Claim Verifiers prüfen, ob Dokumentclaims durch Evidenz gestützt sind
• Doc Reviewers prüfen Truth-Doc-Qualität
• geleaste Doc Writers bearbeiten begrenzte Truth-Doc-Schreib-Shards

Der Parent-Workflow besitzt weiterhin finale Interpretation, Schreibgrenzen, Diff-Validierung und Abnahme.

Das ist wichtig: Subagents helfen bei begrenzter Evidenzarbeit. Sie ersetzen den Haupt-Workflow-Vertrag nicht.

Review-Schleife

Truthmark ist für normalen Git-Review entworfen.

Eine gute KI-gestützte Übergabe sollte Folgendes zeigen:

Code-Diff
Test-Evidenz
Truth-Doc-Diff, falls nötig
Routing-Änderungen, falls nötig
Agentenbericht

Der Reviewer sollte beantworten können:

• Welcher Code hat sich geändert?
• Welche Truth-Dokumente besitzen diesen Code?
• Mussten diese Dokumente aktualisiert werden?
• Falls nicht, warum nicht?
• Ist der Agent innerhalb der Workflow-Schreibgrenze geblieben?
• Sind Test- oder Verifikationsevidenz enthalten?

Beispiele

Ein Repository initialisieren

npm install -g truthmark
truthmark config
truthmark init
truthmark check

Unbenutzte Agentenplattformen entfernen

Bearbeiten:

.truthmark/config.yml

Danach erneut ausführen:

truthmark init
truthmark check

Breites Routing aufteilen

/truthmark-structure die breite repository-area in auth, billing, notifications und deployment aufteilen

Implementiertes Verhalten dokumentieren

/truthmark-document den implementierten Password-Reset-Flow unter docs/truthmark/engineering/behaviors/authentication dokumentieren

Nach Codeänderungen synchronisieren

/truthmark-sync die Repository-Truth jetzt vor der Übergabe synchronisieren

Eine doc-first Entscheidung realisieren

/truthmark-realize docs/truthmark/product/capabilities/invoice-retry-policy.md in Code realisieren

Truth-Gesundheit im Terminal auditieren

truthmark check

Branch-Impact-Zusammenfassung erzeugen

truthmark impact --base main

Workflow-Status prüfen

truthmark workflow status --workflow truthmark-sync --base main --json

Optionalen Portal-Workflow aktivieren

truthmark:
  generated:
    portal:
      enabled: true

truthmark init

Bitte den Agenten-Host anschließend ausdrücklich, den installierten Portal-Workflow auszuführen, wenn die statische Präsentationssite erzeugt oder aktualisiert werden soll.

Projektstatus

Truthmark V1 bietet derzeit:

• truthmark config
• truthmark init
• truthmark check
• truthmark index
• truthmark impact
• truthmark workflow status
• Branch-Scope-Metadaten
• verwaltete Instruktionsblöcke
• generierte Truth-Structure-Workflow-Schnittstellen
• generierte Truth-Document-Workflow-Schnittstellen
• generierte Truth-Sync-Workflow-Schnittstellen
• generierte Truth-Preview-Workflow-Schnittstellen
• generierte Truth-Realize-Workflow-Schnittstellen
• generierte Truth-Check-Workflow-Schnittstellen
• optionale generierte Truthmark-Portal-Workflow-Schnittstellen
• Diagnostik für Route, Autorität, Entscheidungsstruktur, Frontmatter, Links, Freshness, generierte Schnittstellen und Coverage
• abgeleitete RepoIndex-, RouteMap-, ImpactSet- und WorkflowState-Artefakte
• host-spezifische Schnittstellen für Codex, Claude Code, GitHub Copilot, OpenCode und Gemini CLI

Entwicklung

Abhängigkeiten installieren:

npm install

Die lokale Entwicklungs-CLI ausführen:

npm run dev -- init
npm run dev -- check

Den vollständigen Projektcheck ausführen:

npm run check

Nützliche Skripte:

Skript	Zweck
npm run dev	Führt den TypeScript-CLI-Einstiegspunkt mit tsx aus.
npm run build	Baut das Paket.
npm run lint	Führt ESLint aus.
npm run typecheck	Führt TypeScript-Checks aus.
npm run test	Führt Tests aus.
npm run check	Führt Lint, Typecheck, Tests und Build aus.
npm run release:check	Führt release-orientierte Validierung aus.

Wenn du Truthmark selbst änderst, siehe CONTRIBUTING.md.

Dokumentation

Die README ist der schnelle Pfad für Evaluation und Setup.

Aktuelles Verhalten im Detail lebt unter docs/:

• Dokumentationsindex
• Architekturüberblick
• API- und CLI-Verträge
• Init- und Scaffold-Verhalten
• Check-Diagnostik
• Installierte Workflows
• Leitfaden zur Pflege von Repository-Truth

Designgrenzen

Truthmark ist absichtlich klein.

Es ist nicht:

• ein gehosteter Dienst
• ein MCP-Server
• eine Vektordatenbank
• ein kanonischer Dokumentations-Website-Generator oder eine gehostete Docs-Plattform
• ein CI- oder PR-Enforcement-Produkt
• ein Ersatz für Tests, Code Review oder technische Führung
• eine autonome Code-Rewrite-Engine
• ein Framework für Modelltraining oder Fine-Tuning
• eine verborgene Memory-Schicht

Diese Grenzen sind Teil des Produkts.

Truthmark hält den Workflow lokal, versioniert, branch-gebunden und prüffähig.

Sicherheit und Review-Disziplin

Truthmark hilft dem Repository, ehrlich zu bleiben. Es beweist nicht, dass der Code korrekt ist.

Teams sollten weiterhin:

• relevante Tests ausführen
• funktionale Codeänderungen prüfen
• Truth-Doc-Änderungen prüfen
• Secrets aus der Dokumentation heraushalten
• repository-spezifische Instruktionen außerhalb verwalteter Blöcke halten
• Diffs generierter Workflow-Schnittstellen nach Upgrades prüfen
• menschliche Ownership über Produkt- und Architekturentscheidungen behalten

Truthmark macht agentenseitige Repository-Truth sichtbar. Es ersetzt menschliches Urteil nicht.

Roadmap-Richtung

Die aktuelle Zukunftsrichtung betont:

• stärkere Evidenzberichte in truthmark check
• klarere Adoptionsbeispiele
• Beispiel-Repositories mit echten Truth-Sync-Zyklen
• Migrationsleitfäden für Teams, die bereits Agenten-Instruktionsdateien nutzen
• Konformitätstests für generierte Host-Schnittstellen
• route-aware Hinweise auf stale truth
• begrenzte Implementierungschecklisten für doc-first Arbeit

Der Schwerpunkt bleibt gleich:

Repository-Truth
agent-native Workflows
Git-Review
branch-gebundene Dokumentation

Lizenz

MIT. Siehe LICENSE.