truthmark/README.md

Truthmark

Truthmark installs repository truth workflows for AI software development.

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

AI coding agents already write code fast. The expensive part is keeping repository truth aligned with what changed.

Truthmark adds a finish-time workflow guard to that workflow. The normal path is simple:

• agent changes functional code
• run relevant tests
• the installed Truth Sync workflow updates mapped truth docs before the agent finishes
• review the truth-doc diff if one was produced

Most tools ask teams to adopt a habit. Truthmark turns the habit into repository workflow infrastructure.

Truthmark turns an AI workflow into repo infrastructure, not personal tooling. It installs a Git-native, branch-scoped truth layer inside the repository, gives agents explicit routing and bounded workflow surfaces, and keeps that truth reviewable in Git instead of scattering it across prompt history, stale docs, or private tool memory.

That matters because the workflow lives with the branch. Once a repository is initialized, the rules, routing, and installed workflow surfaces travel in-repo, so collaboration and handoffs are less dependent on one person's machine setup.

For teams who already know agents can generate code, Truthmark answers the next problem: how to keep the repository itself legible, reviewable, and governable as AI-assisted work scales.

Visual overview

Features What Truthmark installs and how the workflow surface is split.	Position Where Truthmark fits relative to prompts, memory, and spec workflows.
Sync flow How Truth Sync closes out normal code changes before handoff.

Why teams adopt it

Truthmark is not trying to make agents sound smarter. It is trying to make AI-assisted repository change easier to trust.

• Installed Truth Sync after code changes turns documentation maintenance into a workflow safeguard instead of a team habit.
• Branch-scoped truth moves with the code, so reviewers can inspect current truth in ordinary Git diffs.
• Repository-native workflow surfaces make rollout lighter and handoffs more resilient than per-user setup alone.
• Explicit routing in docs/truthmark/areas.md and delegated child route files gives agents ownership boundaries and safer write paths.
• Local-first operation avoids a daemon, database, remote service, or MCP dependency.
• The routing model is language-agnostic, with coverage diagnostics for common JavaScript, TypeScript, Go, Python, C#, and Java code surfaces.

For tech leads, the value is governance without extra infrastructure: tests, code review, and ownership still do the real work; Truthmark makes the agent's context durable, inspectable, and branch-scoped.

Where Truthmark fits

Truthmark is not a general AI productivity suite. It occupies a specific layer of the stack: branch-scoped, reviewable repository truth that stays aligned with implementation.

If you need	Best fit
Better results from a single coding session	Better prompts and tighter task framing
Convenience across sessions for one agent or one operator	Memory tools
Spec-first planning for new features	Spec tools such as Spec Kit
Branch-scoped, reviewable repository truth that travels with the code	Truthmark

The point is not that prompts, memory, or specs are useless. The point is that none of them, by themselves, turn repository truth into a committed, inspectable asset that survives handoffs, review, and branch divergence.

Table of Contents

• Why teams adopt it
• What Truthmark solves
• Where Truthmark fits
• Get started
• How it runs
• What it installs
• Commands
• Why it exists
• Project status
• Documentation
• Non-goals
• License

What Truthmark solves

Truthmark turns repository truth into an explicit workflow surface for agents:

• .truthmark/config.yml defines the committed hierarchy contract.
• docs/truthmark/areas.md and delegated child route files map code areas to the docs that own them.
• Truth Document generates or repairs canonical truth docs for existing implemented behavior when no code change is needed.
• Truth Sync keeps mapped truth docs aligned with functional changes.
• Truth Preview previews likely workflow routing before edits without authorizing writes.
• Truth Realize gives doc-first changes a bounded code-update path.
• truthmark check validates the resulting truth artifacts.
• The whole model stays local-first and Git-native.

This is the core promise: agent context becomes committed repository state instead of a private session artifact.

Get started

Install Truthmark in the repository you want to initialize:

cd /path/to/your-repo
npm install -g truthmark
truthmark config
truthmark init
truthmark check

If you want to try unreleased changes from a source checkout instead:

cd /path/to/truthmark
npm install
npm run build

cd /path/to/your-repo
node /path/to/truthmark/dist/main.js config
node /path/to/truthmark/dist/main.js init
node /path/to/truthmark/dist/main.js check

Review .truthmark/config.yml before init; it is the committed hierarchy contract. After init, review the generated workflow surface and route files so the routed docs match the docs that actually own your code:

.truthmark/config.yml
docs/truthmark/areas.md
docs/truthmark/areas/repository.md
docs/templates/behavior-doc.md
docs/truth/README.md
docs/truth/repository/README.md
docs/truth/repository/overview.md
AGENTS.md
CLAUDE.md
GEMINI.md

Supported platforms are codex, opencode, claude-code, github-copilot, and gemini-cli. The default config includes all of them; remove platforms you do not use from .truthmark/config.yml before rerunning truthmark init.

The default scaffold keeps truth README.md files as indexes and starts current behavior truth in bounded leaf docs such as docs/truth/repository/overview.md.

Existing repositories usually need one cleanup pass after init: run the installed Truth Structure workflow when the generated repository route is too broad, ownership spans multiple products or services, or route files still point at placeholder docs. Truth Structure splits broad routing, creates or repairs starter canonical truth docs, and gives Truth Sync precise destinations before functional-code work begins. Codex, Claude Code, and supported Copilot IDEs can invoke it with /truthmark-structure; OpenCode-style hosts can invoke /skill truthmark-structure.

/truthmark-structure split the broad repository area into auth, billing, and notifications

How it runs

Truthmark is strongest on the default path, not as a pile of manual commands. The acting agent and host environment decide whether to delegate or run the installed workflow inline.

Existing behavior without docs

Use this when implementation already exists but the canonical truth docs are missing or weak:

user identifies an implemented behavior or API endpoint
user explicitly invokes Truth Document
agent reads implementation, tests, routing, and existing docs
agent writes truth docs and routing only
review the truth-doc diff

Truth Document is manual and implementation-first: code is inspected as evidence, truth docs are created or repaired, and functional code must not be changed. Codex, Claude Code, and supported Copilot IDEs can invoke it with /truthmark-document. OpenCode-style hosts can invoke /skill truthmark-document.

/truthmark-document document the implemented session timeout behavior under docs/truth/authentication

Normal code changes

Most users should not need to invoke Truth Sync directly. The important behavior is that the installed agent workflow treats Truth Sync as a finish-time guard when functional code changed. The normal path is:

agent changes functional code
run relevant tests
the installed Truth Sync workflow runs before the agent finishes
review the truth-doc diff if one was produced
commit or hand off the work

Truth Sync is code-first: code leads, truth docs follow, and Truth Sync must not rewrite functional code. Its main job is to run through the installed agent workflow as a finish-time guard when functional code changed. Direct invocation is mainly for troubleshooting, forcing an early sync before handoff, or running the workflow intentionally.

Codex, Claude Code, and supported Copilot IDEs can invoke it with /truthmark-sync. OpenCode-style hosts can invoke /skill truthmark-sync.

/truthmark-sync sync the repository truth now before handoff

Doc-first changes

Use this when a product or architecture decision starts in docs:

user edits truth docs
user explicitly invokes Truth Realize
agent reads truth docs and relevant code
agent updates code only
run relevant tests
commit or hand off the work

Truth Realize is manual and doc-first: truth docs lead, code follows, and the agent must not edit the truth docs it is realizing.

Codex, Claude Code, and supported Copilot IDEs can invoke it with /truthmark-realize. OpenCode-style hosts can invoke /skill truthmark-realize.

/truthmark-realize realize docs/truth/authentication/session-timeout.md into code

What it installs

Truthmark keeps the durable workflow surface small and repository-native. After truthmark init, the repo itself carries the routing, rules, and installed workflow surfaces, so teams are not relying only on one operator's local setup.

Truthmark installs two distinct surfaces:

• human-facing CLI commands, run by people or CI to configure the repo, refresh installed files, validate truth artifacts, and optionally generate derived review context

• agent workflow surfaces, invoked by coding agents or agent hosts during implementation workflows; they are not extra daily terminal commands for humans

• .truthmark/config.yml for the machine-readable committed hierarchy contract

• docs/truthmark/areas.md for the root route index

• docs/truthmark/areas/**/*.md for delegated child route files

• docs/templates/behavior-doc.md plus the other kind-specific templates under docs/templates/ for the editable truth-doc standards used by generated workflows

• managed instruction blocks for configured platforms such as AGENTS.md, CLAUDE.md, Copilot instructions, and GEMINI.md

• host-native skills, prompts, or commands for Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Realize, and Truth Check

• Codex, Claude Code, GitHub Copilot, and OpenCode project-scoped read-only verifiers plus leased truth-doc-writer agents where hosts support agents, under .codex/agents/, .claude/agents/, .github/agents/, and .opencode/agents/ for workflow-owned audits and parent-leased doc shards

The installed workflow surfaces are the runtime:

• Truth Structure creates or repairs area routing and starter truth docs.
• Truth Document creates or repairs truth docs for existing implemented behavior.
• Truth Sync keeps mapped truth docs aligned with functional changes.
• Truth Preview previews likely workflow routing before edits without writing files.
• Truth Realize updates code to match truth docs.
• Truth Check audits repository truth health.

Truth README.md files are indexes. Truth Sync is expected to read and update bounded leaf docs for current behavior. Generated workflow surfaces preserve repository-rule authority while treating implementation code and canonical truth docs as evidence for current behavior.

Generated surfaces are managed by Truthmark, include a version marker, and may be refreshed by truthmark init.

Commands

Truthmark V1 keeps the terminal CLI focused. Most human users only need setup, refresh, and validation:

Human-facing CLI	Use
truthmark config	Create .truthmark/config.yml; writes only that file unless --stdout is used.
truthmark init	Install or refresh local workflow files from the reviewed config.
truthmark check	Validate configuration, authority, routing, decision-bearing docs, frontmatter, internal links, branch scope, and coverage diagnostics.

The remaining CLI commands are optional repository-intelligence helpers. They generate derived review context for the active checkout; they are not sources of truth:

Optional CLI	Use
truthmark index	Build RepoIndex and RouteMap JSON for the active checkout.
truthmark impact --base <ref>	Map changed files to routed truth docs, owning routes, nearby tests, and public symbols.
truthmark context --workflow <workflow> [--base <ref>]	Generate a bounded ContextPack for Truth Sync, Truth Document, or Truth Realize. --format markdown renders a human-readable pack.

All CLI commands above support --json where structured output is useful for automation.

Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Realize, and Truth Check are installed agent workflows, not top-level daily CLI commands.

They run through the configured agent host surfaces, for example Codex/Claude/Copilot /truthmark-*, OpenCode /skill truthmark-*, or Gemini /truthmark:*.

These invocations look command-like because agent hosts expose skills through slash commands. Treat them as instructions to an agent, not as terminal commands a human is expected to run.

/truthmark-check audit routing and truth coverage before review

Why it exists

Most AI coding workflows optimize for the next answer. Truthmark optimizes for the next handoff.

It assumes serious teams need:

• branch-specific product truth
• durable architecture and API decisions
• explicit ownership between docs and code
• safe write boundaries for agents
• ordinary Git diffs that humans can review
• readable Markdown that teammates can inspect without special tooling
• truth that travels with the branch instead of living in hidden session state
• workflows that still work when the package is not installed globally

Truthmark is not a memory server and it is not an MCP server. It is a repository practice packaged as a small CLI installer plus agent-native workflow surfaces that turn AI workflow rules into repo infrastructure.

Project status

V1 currently provides:

• truthmark config
• truthmark init
• truthmark check
• truthmark index
• truthmark impact
• truthmark context
• managed AGENTS.md workflow instructions
• generated Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Realize, and Truth Check skill surfaces for configured agent hosts
• branch-scope metadata
• config, authority, routing, decision-structure, frontmatter, link, freshness, and polyglot coverage diagnostics
• derived RepoIndex, RouteMap, ImpactSet, and ContextPack artifacts for faster local review when the CLI is available

Documentation

The root README is for people evaluating and trying the package. Detailed functional and business specifications live under docs/:

• Docs index
• Architecture overview
• API and CLI contracts
• Init and scaffold behavior
• Check diagnostics
• Installed workflows
• Repository truth maintenance guide

Current behavior belongs in the canonical docs tree above.

Non-goals

Truthmark V1 is not:

• a hosted service
• an MCP server
• a vector database
• a documentation website generator
• a CI or PR enforcement product
• a replacement for tests, code review, or technical leadership
• an autonomous code rewrite engine

It is a lightweight way to make local AI coding agents respect the truth your team keeps in Git.

License

MIT. See LICENSE.