/truthmark-documentDocument what already exists
Read implementation and tests, then create or update bounded truth docs without changing functional code.
Repository truth carried by the branch
@@ -898,14 +1169,14 @@
Truthmark gives AI-assisted work a reviewable truth layer: current claims, ownership routes, product promises, and implementation facts travel with the same Git branch as the code.
-
-
+ Checkout-nativeAfter setup, normal agent work can proceed from committed repository files.
- Claim-level reviewDocs change as small, source-backed claims instead of anonymous summaries.
- Topology awareWhen truth gets too broad, ownership gets repaired rather than hidden.
- Host-shapedInstructions meet agents in their existing coding environments.
+ Explore the workflows
-
+
- Checkout-nativeAfter setup, normal agent work can proceed from committed repository files. +
- Claim-level reviewDocs change as small, source-backed claims instead of anonymous summaries. +
- Topology awareWhen truth gets too broad, ownership gets repaired rather than hidden. +
- Host-shapedInstructions meet agents in their existing coding environments. +
+
+
+
+
+
+
@@ -987,6 +1275,13 @@
+
+
+ Workflow field guide
+ Five workflows. One reviewable loop.
Truthmark does not turn every activity into a command. Three workflows are clear user entry points; Sync closes functional code changes; Structure appears only when ownership needs repair.
+ You start · truth writes
+ You start · code writes
+ You start · read only
+ Agent finish-time · truth writes
+ Only when needed · topology
+
+ /truthmark-realizeTurn accepted truth into code
Use product truth as requirements and engineering truth as implementation context. The source docs remain unchanged.
/truthmark-checkAudit before review
Inspect routing, evidence, lane shape, and truth health without authorizing writes.
Truth SyncClose the branch honestly
After functional code changes, review mapped truth, capture supported decisions, and update or explicitly leave claims unchanged with evidence.
Truth StructureRepair ownership before adding prose
Split broad routes and overgrown docs when the repository can no longer identify a bounded owner.
@@ -948,10 +1236,10 @@
-
-
-
-
+
+
+
+
+
+
+
@@ -996,10 +1291,19 @@
- Repository truth model
+ Keep the promise and the mechanism in different rooms.
Truthmark links what users can rely on to how the repository currently realizes it. The relationship is explicit, but neither document inherits authority from the other.
Two lanes, linked on purpose.
Truthmark can let product and engineering documents reference each other without forcing them into the same voice or authority level.
Three committed layers make the handoff legible.
The route map decides ownership, truth docs preserve current claims, and host-native guidance tells the coding agent when each surface may change.
+ Route
+ Truth
+ Guidance
+
+ Find the bounded owner
Changed paths map to an area and its canonical product or engineering truth docs.
Preserve the claim
Human-facing Markdown records current behavior, rationale, boundaries, and evidence in the right lane.
Meet the agent in its host
Committed skills, prompts, commands, and instruction blocks carry write boundaries into normal coding work.
The workflow is deliberately boring at runtime.
Truthmark's ambition is in the repository model, not in requiring every contributor to adopt a new always-on system.
-
+
+
+
+ 1. SetupConfigure routes and install agent-facing surfaces.
→
2. WorkAgent changes code in its normal host.
@@ -1008,45 +1312,139 @@
+
+
+
-
+# After setup, agent guidance and truth routes live in the checkout.
+
+
+
+
Adoption path
+ Install the contract, then get out of the way.
Choose the agent host your team already uses. Truthmark commits its guidance, routes, and truth docs to the repository, so the next branch can continue without a background service.
Start with the repo, not a server.
Install once, commit the workflow surface, and let future branches carry their truth updates through normal review.
$ cd /path/to/your-repo +
+
+ What lands in the repo
+
+
+ Choose your first move
+
+
+ A small contract with visible parts
+Every durable surface can be reviewed, blamed, reverted, and carried by the branch.
+
+
+ 1
+ Config and routesChoose platforms and map code areas to bounded truth owners.
2
+ Human-facing truthKeep product capabilities and engineering reality separate but linked.
3
+ Host-native guidanceInstall the workflow shape where your coding agent already looks.
Begin with one bounded area
+Document one implemented behavior with code and test evidence. Then keep coding normally and let finish-time Sync review future changes.
+-
+
- Codex
- Claude Code
- GitHub Copilot
- OpenCode
- Antigravity
- Cursor +
Presentation is not authority.
+ This website explains the product. Canonical behavior remains in the repository's README, routed truth docs, source, tests, and configuration. Truthmark adds no required daemon, database, hosted service, or hidden memory layer.