Give your coding agent a persistent memory. source-of-truth keeps a living docs/ catalog of what exists, why, and what rules apply — so AI stops rebuilding, deleting, and breaking things it never...
Обзор
source-of-truth gives your coding agent a persistent memory: it reads what already exists writing code, and updates the record a feature ships — so it stops rebuilding, deleting, and breaking things it never knew were there. — Claude Code · Codex · Cursor · Gemini · Copilot · Kimi · Pi. → Install Under the hood it's a self-maintaining catalog skill: a docs/ folder that acts as the project's source of truth for what exists, why it exists, and what rules apply. The is the source of truth for "what exists, why, and what rules apply". The is the source of truth for "how it works". See the live explainer for the full visual walkthrough of the workflow. Source-of-Truth is a catalog skill, not a workflow engine — it's designed to sit alongside a development methodology, not replace one. Pairing it with one of these is a great fit: - drives how you work (brainstorming → planning → TDD → review).
README
source-of-truth
Stop your AI from silently deleting features it doesn’t know exist.
source-of-truth gives your coding agent a persistent memory: it reads what already exists before writing code, and updates the record after a feature ships — so it stops rebuilding, deleting, and breaking things it never knew were there.
One skill, every coding agent — Claude Code · Codex · Cursor · Gemini · Copilot · Kimi · Pi. → Install
Under the hood it’s a self-maintaining Spec-Driven Development (SDD) catalog skill: a docs/ folder that acts as the project’s source of truth for what exists, why it exists, and what rules apply.
The catalog is the source of truth for “what exists, why, and what rules apply”. The code is the source of truth for “how it works”.
See the live explainer for the full visual walkthrough of the workflow.
Works well with
Source-of-Truth is a catalog skill, not a workflow engine — it’s designed to sit alongside a development methodology, not replace one. Pairing it with one of these is a great fit:
- superpowers drives how you work (brainstorming → planning → TDD → review). Source-of-Truth keeps the persistent record of what exists and why, so each superpowers cycle reads the catalog before coding and syncs it after shipping.
- spec-kit generates specs and plans up front for a feature. Source-of-Truth turns those one-off specs into a living catalog that stays in sync with the code as the project evolves.
In short: the methodology produces the work; Source-of-Truth keeps the source of truth honest across sessions.
Quickstart (Claude Code)
Using Codex, Cursor, Gemini, Copilot, Kimi, or Pi instead? Skip to Installation for the per-platform steps — the skill itself is identical everywhere.
1. Install the plugin, then reload so the skill activates:
/plugin marketplace add ngocquang/source-of-truth
/plugin install source-of-truth@source-of-truth-dev
/reload-plugins
2. Have a PRD or SDD ready first. The catalog is built from your intent, not guessed from scratch — so before you run anything, have a Product Requirements Document (PRD) or Software Design Document (SDD) on hand, even a rough one. Already ran superpowers or spec-kit for the feature? Their specs and plans count too. Bootstrap pulls whatever you have in as the primary source of feature intent and mission (code shows how; the doc shows why).
3. Then just type /source-of-truth. That’s the whole trigger. It reads your PRD/SDD, bootstraps the docs/ catalog, and from then on activates on its own — READ before each change, SYNC after each ship.
Using another agent (Codex, Cursor, Gemini, Copilot, Kimi, Pi)? See Installation for per-platform steps.
Why it exists
When an AI edits a codebase with no reference source, four failures recur:
- Rebuilding a feature that already exists.
- Silently deleting features during a refactor.
- Breaking invariants by changing behavior without knowing the contract.
- Building features that violate project principles or aren’t on the roadmap.
The catalog is the reference that blocks all four — read before code is written, kept in sync after it ships.
How it works
The catalog enforces a gate chain — each layer authorizes the one below it:
constitution → mission → roadmap → specs → code
Principles gate plans → mission gates the roadmap → the roadmap gates specs → specs gate code. Read top-down to learn why a line of code exists; nothing reaches code until the layer above permits it.
It all lives in a docs/ folder of plain, greppable markdown:
overview.md— index linking every project doc and feature spec.constitution.md— principles: tech stack, code quality, testing, UX, performance.mission.md— why the project exists: problem, users, value, success metrics.roadmap.md— forward plan (Now / Next / Later); shipped work leaves it.changelog/YYYY-MM-DD-.md— removals, renames, contract changes, constitution changes. One flat file per entry, so parallel sessions never merge-conflict.decisions/YYYY-MM-DD-.md— decisions spanning two or more features, or the constitution: what was chosen, what lost, and why. Append-only — a change of mind supersedes, never overwrites.debugging/YYYY-MM-DD-.md— post-mortems for bugs whose root cause was not where the symptom pointed: what it looked like, what it actually was, how to recognise it next time.specs/spec-.md— one file per feature: Plan + Requirement + Validation.
The catalog owns what exists & why; the code owns how it works. Exact schemas live in the skill’s references/. The last two folders are created the first time something qualifies — a fresh catalog has neither.
Installation
Installation differs by agent. If you use more than one, install source-of-truth separately for each. The skill is identical across them — each platform just needs to discover the skills/ directory, then it activates automatically when a task touches a docs/ spec catalog.
Claude Code
Register the marketplace shipped in this repo:
/plugin marketplace add ngocquang/source-of-truth
Then install the plugin:
/plugin install source-of-truth@source-of-truth-dev
Update later:
/plugin marketplace update source-of-truth-dev
Codex
Codex reads .codex-plugin/plugin.json, which registers ./skills/. Point Codex’s plugin manager at this repository (or a local clone) to install it.
Cursor
Cursor reads .cursor-plugin/plugin.json, which registers ./skills/. Install it from this repository (or a local clone) via Cursor’s plugin manager.
Gemini CLI
Install the extension from this repository:
gemini extensions install https://github.com/ngocquang/source-of-truth
Update later:
gemini extensions update source-of-truth
Gemini loads GEMINI.md, which imports the skill so it’s active from the first message.
GitHub Copilot CLI
Copilot reads the same marketplace as Claude Code. Register it, then install:
copilot plugin marketplace add ngocquang/source-of-truth
copilot plugin install source-of-truth@source-of-truth-dev
Kimi Code
Install directly from this repository:
/plugins install https://github.com/ngocquang/source-of-truth
Pi
Install source-of-truth as a Pi package from this repository:
pi install git:github.com/ngocquang/source-of-truth
The package loads the skill via the .pi/extensions/source-of-truth.ts extension’s resources_discover hook.
The Basic Workflow
You don’t invoke the skill manually — it activates on context. The whole loop is bootstrap once → READ before each change → SYNC after each ship:
- First time in a project — bootstrap the catalog (once). Ask “set up the source-of-truth catalog”. The skill auto-detects your stack, asks a single batch of questions (principles, mission), and writes
docs/after you confirm. Skip this ifdocs/overview.mdalready exists. - Ask for a change as usual. Before writing any code the skill enters READ: it loads the catalog and prints a Catalog check (what exists, invariants, roadmap status, conflicts) for you to review.
- Resolve conflicts, then approve. If the change collides with an existing feature, a documented invariant, the constitution, or isn’t on the roadmap, the skill stops and asks. Add a roadmap entry or adjust the plan, then let it proceed.
- Implement. The skill writes code against the approved plan and the documented contracts.
- Ship / commit. Say “done”, “commit”, or “merge”. The skill enters SYNC: it reads the diff, updates the affected specs, moves shipped items off the roadmap, records removals/renames as changelog entry files and cross-cutting decisions/debugging as their own record folders, shows you the catalog diff, then commits code and catalog together.
The catalog stays true to the code with no separate “update the docs” step — READ and SYNC are the only two touchpoints you need to remember.
Example prompts
| Prompt | What the skill does |
|---|---|
/source-of-truth in a repo with code and no docs/overview.md |
BOOTSTRAP: detects the stack, asks one batch of questions, and writes docs/ after you confirm. |
| “Is there already something that exports invoices to CSV?” | READ: matches your words against the catalog’s keyword lines and names the owning spec, or says none exists. |
| “Add rate limiting to the login endpoint.” | READ: prints the Catalog check before any code, and stops to add a roadmap entry if the work isn’t tracked yet. |
| “Done — commit this.” | SYNC: updates the affected specs and roadmap, shows you the catalog diff, then commits code and catalog together. |
What’s Inside
The skill operates in three modes, selected automatically by context:
| Mode | When | What happens |
|---|---|---|
| BOOTSTRAP | docs/overview.md does NOT exist + project has code, and you run /source-of-truth or ask to set up the catalog |
Auto-detect stack → interview user for principles/mission → confirm & write the catalog. Runs once. |
| READ | Before writing / modifying / deleting code (incl. bug fixes, refactors, “does X already exist?”) | Load catalog, output a Catalog check to the user, stop on conflicts, only then write code. |
| SYNC | A feature shipped (“ship it”, “done”, “commit”, “merge”, “xong rồi”) or “update/sync the catalog” | Reconcile catalog with the diff: update specs, remove shipped entries from the roadmap, record deletions/renames as changelog entry files, decisions/debugging as their own record folders. |
RE-BOOTSTRAP: a special case of BOOTSTRAP — when docs/overview.md exists but constitution.md or mission.md is missing/empty, re-bootstrap the missing file before any code change.
Commit gate: a commit request is itself a SYNC trigger. When you ask to commit (or the agent is about to), SYNC runs and completes before the commit — so the code and the catalog are committed together. This is automatic, not a question.
Ambiguous? Ask once: “Sync the catalog now, or keep going?”
READ mode — the Catalog check
Before any code is written, the skill prints this to the user (so it can be overridden):
Catalog check:
- Constitution:
- Roadmap status:
- Related existing features:
- Prior decisions:
- Known debugging traps:
- Invariants I must preserve:
- Acceptance criteria that must still pass:
- Already exists?
- Plan:
If the change collides with an existing feature, a documented invariant, a constitution principle, or the roadmap — the skill stops and asks instead of proceeding.
SYNC mode — after shipping
SYNC reconciles the catalog with what changed: it reads the diff (git diff --name-only, current commit, date), updates the affected specs, moves shipped roadmap entries off Now, and records removals / renames / contract changes as per-entry files in docs/changelog/, plus qualifying cross-cutting decisions and bug post-mortems in docs/decisions/ and docs/debugging/. Full procedure lives in the skill’s references/.
BOOTSTRAP mode — three phases
- A — Auto-detect (no user input): scan repo for tech stack, test framework, design system, README intro, and feature entry points.
- B — Interview (single batch): ask only what can’t be detected (code-quality rules, performance budgets, mission users/value/metrics).
- C — Confirm & write: show populated docs, get OK, then write the 4 project docs plus the changelog bootstrap entry and per-feature specs, and update the agent memory file (
CLAUDE.md, withAGENTS.mdsymlinked to it for Codex).
constitution.md and mission.md must have real content before bootstrap completes — _TBD: _ markers are acceptable for deferred sections, but blank fields and fabricated content are not.
Philosophy
Source-of-Truth is rigid, not advisory — its value comes from being followed exactly:
- Read before you write; sync after you ship. Don’t skip a mode or shortcut the Catalog check to “save time” — small changes break invariants most often.
- Every unit of work goes on the roadmap. New feature, enhancement, refactor, and bug fix — each gets a
roadmap.mdentry before code is written. The rule blocks the agent’s own “too small to track” rationalizing; an explicit user override (e.g. a live hotfix) is honored, with a recommended retroactive entry. - Never fabricate. If it isn’t visible in code, tests, or stated by the user, don’t assert it — tests are the best source of invariants; the user is the only source of mission and code-quality principles. A vague invariant is worse than none.
- The catalog owns what & why; the code owns how. The two never compete for the same truth.
Privacy & security
source-of-truth is Markdown instructions your coding agent follows: no server, no network calls, no telemetry. Besides the code you ask for, it writes the docs/ catalog, creates a git worktree per change, and — during bootstrap, after you confirm — updates CLAUDE.md / AGENTS.md. Details: PRIVACY.md. To report a vulnerability, see SECURITY.md.
Contributing
Issues and pull requests are welcome at github.com/ngocquang/source-of-truth. The skill itself lives in skills/source-of-truth/ — SKILL.md is the entry point, with references/ for the detailed BOOTSTRAP / SYNC / changelog procedures. Edit there and the change reaches every supported agent.
License
MIT © QuangDN. See the plugin metadata in .claude-plugin/plugin.json.
Community
Questions, ideas, or bugs? Open an issue or start a discussion on GitHub.
Рекомендуемые инструменты
Попробуйте другой запрос или уберите фильтр.
Установка
npx skillfish add ngocquang/source-of-truth