TruthKit is a small AI-agent toolkit for making software projects easier to understand, safer to change, and cheaper to work on over time.
It gives an AI a repeatable way to initialise a project source of truth, keep it current, and create repo-local agent instructions such as AGENTS.md and CLAUDE.md.
Most AI coding sessions waste time because the agent has to rediscover the same things again and again:
- What is this product?
- What are the roles?
- What are the important workflows?
- Which files are authoritative?
- What is legacy, what is current, and what is unknown?
- Which commands prove the project still works?
Without a source of truth, every agent starts half-blind. It reads random files, infers behavior from stale code, guesses product intent, and may accidentally change a rule that was decided months ago.
This toolkit fixes that by making the project explain itself.
When an AI is asked to initialise a source of truth, it creates or updates:
source-of-truth/00-overview.mdsource-of-truth/01-product.mdsource-of-truth/02-brand-visuals.mdsource-of-truth/03-user-flows.mdsource-of-truth/04-tech-architecture.mdsource-of-truth/05-data-model.mdsource-of-truth/06-api-contracts.mdsource-of-truth/07-code-rules.mdsource-of-truth/08-deployment.mdsource-of-truth/09-open-questions.mdsource-of-truth/10-glossary.mdsource-of-truth/source-map.yamlAGENTS.mdCLAUDE.md- an app-specific
<appname>-sourceskill when the AI environment supports skills
AGENTS.md becomes the canonical repo-local AI instruction file.
CLAUDE.md normally stays tiny and points to AGENTS.md, so Claude and other tools do not drift into a second competing instruction set.
Give this repository to your AI assistant and say:
Read this TruthKit repository, install or use its skills, then initialise this SoT in my project.
Decide whether my project is new or existing. Inspect the real files first. Create the source-of-truth files, AGENTS.md, CLAUDE.md, and any app-specific source skill you need. Ask one question at a time.
For Codex-style skill installation, run:
./scripts/install-sot-skills.shTo also copy the skills into a specific project:
./scripts/install-sot-skills.sh --project /path/to/my-projectAn AI can also use the skills directly from this repository without installing them, as long as it reads skills/onboard-source/SKILL.md.
The initializer behaves differently depending on the project stage.
For a new or empty project, it asks foundational questions first:
- app name
- audience
- core problem
- main entities
- roles and permissions
- workflows
- data ownership
- deployment target
- verification commands
For an existing project, it inspects the real repo before asking anything:
- README and package metadata
- route trees
- frontend pages
- backend APIs
- migrations and schemas
- env examples
- deployment config
- tests and build scripts
- existing docs
- existing
AGENTS.md/CLAUDE.md
Then it separates:
- what exists live in code
- what is legacy or conflicting
- what is canonical
- what is still unknown
Short term: it burns a little more.
Long term: it saves a lot.
The first onboarding pass costs tokens because the agent has to inspect the project, ask questions, and write the source files. That is intentional. You are paying once to remove repeated confusion.
After that, most future sessions become cheaper because the agent can read the right truth first instead of scanning the whole repo every time.
Typical repeated cost:
- the agent searches the repo
- reads many unrelated files
- infers product rules from code
- asks repeated clarification questions
- misses hidden business logic
- produces changes that need review or rework
- future agents repeat the same discovery again
This looks cheap per prompt, but expensive across a real project.
Initial cost:
- one structured repo inspection
- one set of source files
- one agent instruction file
- one app-specific skill
Repeated future cost:
- read
AGENTS.md - read the relevant source-of-truth file
- inspect only the code paths related to the change
- update the source when behavior changes
That usually means fewer broad searches, fewer wrong assumptions, fewer rework loops, and fewer support/debug sessions caused by drift.
Use this mental model:
- First setup: higher token spend
- Small future tasks: lower token spend
- Large feature tasks: much lower risk, often lower total spend
- Bug fixes: faster because expected behavior is explicit
- Multi-agent work: dramatically better because agents share one truth
If a project is throwaway, SoT may be overkill.
If a project will live, grow, be handed to multiple AIs, or enter production, SoT is worth it.
SoT makes a project more durable because it turns hidden context into explicit project memory.
Benefits:
- fewer hallucinated requirements
- fewer duplicated concepts
- fewer naming mismatches
- fewer accidental rewrites of decided behavior
- faster onboarding for new agents and humans
- safer refactors
- clearer test plans
- better product decisions
- better handoff between Codex, Claude, Cursor, Copilot, and other tools
- less repeated explanation from the human operator
- open questions stay visible instead of becoming silent assumptions
- source, code, docs, and agent behavior stay aligned
It does not make a project magically perfect. It gives every agent a map and a rulebook before it starts driving.
Use Plan Mode when:
- the project is new
- the source of truth is being created for the first time
- the product direction is still fuzzy
- business rules, roles, money, legal, or workflows are unclear
- the operator wants one-question-at-a-time onboarding
Use normal implementation mode when:
- the SoT already exists
- the task is specific
- the source already answers the key decisions
- the operator wants code changes now
Best pattern:
- Use Plan Mode for initial SoT onboarding.
- Switch to normal mode for implementation.
- Require agents to update SoT whenever they change decided behavior.
- Use
remake-sourcewhen an already decided truth needs to change.
This toolkit helps because it forces the project to answer the questions that usually break products later:
- Who are the users?
- What are the roles?
- Who owns which data?
- What states can each workflow enter?
- Which actions are allowed?
- What happens when something fails?
- What is public, private, or role-scoped?
- What money rules exist?
- What notifications exist?
- What APIs and integrations exist?
- What commands prove the system still works?
- What is not decided yet?
That is the difference between an AI guessing and an AI working inside a product operating system.
truthkit/
├── AGENTS.md
├── CLAUDE.md
├── README.md
├── scripts/
│ └── install-sot-skills.sh
├── skills/
│ ├── onboard-source/
│ └── remake-source/
└── templates/
├── AGENTS.md
├── CLAUDE.md
├── app-source-skill/
└── source-of-truth/
The source of truth is not a documentation graveyard.
It is the operating contract for the product.
When product truth changes, update it.
When code disagrees with it, surface the conflict.
When truth is missing, ask.
When truth is decided, do not silently rewrite it.