English | 简体中文

DocCanon

Stop making every coding agent rediscover your codebase.

DocCanon is a verified context layer for coding agents.

It keeps a compact, trustworthy understanding of your project beside the code, so coding agents can reuse the same context instead of repeatedly scanning and re-interpreting the repository from scratch.

Reuse context. Keep it fresh. Switch agents.

Quick Start

Install DocCanon into your current project:

gh skill install Heluhan/Doccanon doccanon --agent universal

Then tell your coding agent:

Set up DocCanon for this project.

That's it.

Once configured, use your coding agent normally. DocCanon handles context routing, verification, and documentation synchronization as part of the workflow.

gh skill is currently a GitHub CLI preview feature. For host-specific or manual installation, see Installation.

Why DocCanon?

1. Stop rediscovering the same codebase

A new task often starts with the same expensive routine:

Task
  ↓
Search the repository
  ↓
Read entry points
  ↓
Trace dependencies
  ↓
Reconstruct architecture
  ↓
Find the relevant code
  ↓
Start working

Much of that understanding is durable. It should not have to be rebuilt for every task or every new agent session.

DocCanon gives the agent a compact project map first:

Task
  ↓
Load relevant project context
  ↓
Inspect relevant code
  ↓
Start working

The agent still verifies the source code where needed.

It just does not have to treat the entire repository as unknown territory every time.

This is designed to reduce repeated repository exploration — and therefore the context, tool calls, and time spent getting oriented.

Actual token savings depend on the repository, task, model, and agent, so DocCanon does not claim a universal percentage.

2. Switch agents without losing project context

Your project's understanding should belong to the project, not to one model, IDE, or session.

DocCanon keeps canonical knowledge in plain Markdown beside the code:

CONTEXT.md
docs/

Different coding agents can work from the same project understanding:

Codex ──────────┐
Claude Code ────┤
Cursor ─────────┼──→ Project context ──→ Codebase
OpenCode ───────┤
Copilot ────────┤
Gemini CLI ─────┘

Use one agent today and another tomorrow without rebuilding the project's mental model from zero.

Switch agents, not context.

3. Don't let shared context silently go stale

Persistent context creates a new problem:

What happens when the code changes but the documentation doesn't?

A stale project map can be worse than no map at all.

DocCanon treats freshness as part of the system.

It checks whether canonical project knowledge is valid for the current branch, tracks which current-state owners are affected by implementation changes, and refuses to treat the project as synchronized while relevant changes remain unaccounted for.

Code changes
     ↓
Affected project knowledge?
     ↓
   yes
     ↓
Update + verify
     ↓
Synchronized

So DocCanon is not just persistent context.

It is governed, verifiable context.

How it works

For a governed project, the basic loop is:

1. Check trust — verify that canonical context is usable on the current branch.
2. Route context — load only the project knowledge relevant to the task.
3. Verify code — inspect the source, tests, configuration, or runtime evidence needed for the change.
4. Implement — make the actual code change.
5. Keep context aligned — update affected current-state knowledge and verify the result.

The user does not need to run this workflow manually.

The skill owns it.

New task
   ↓
Verified context
   ↓
Relevant code
   ↓
Implementation
   ↓
Context update
   ↓
Verification

Why not just use AGENTS.md, CLAUDE.md, or normal docs?

Those files are useful. DocCanon solves a different problem.

A normal project document can persist knowledge, but it can also silently become stale.

A tool-specific memory file can help one agent, but the knowledge may not travel cleanly to another.

And asking every agent to reconstruct the project directly from source works — but repeats the same exploration again and again.

DocCanon adds three things:

• Portable context — project knowledge lives with the repository.
• Task routing — agents load the smallest relevant context before inspecting code.
• Verification — reusable context is checked against the implementation instead of being trusted blindly.

DocCanon does not replace source-code inspection.

It changes where the agent starts.

Read the map first. Verify against the territory.

Agent entry files are generated, not hand-maintained

Codex, Cursor, GitHub Copilot, and OpenCode read AGENTS.md at session start; Claude Code reads it directly or through a thin CLAUDE.md import. That file is the first thing every agent sees, so one stale or retired paragraph there can poison every session.

DocCanon treats the agent entry as a generated projection instead:

• AGENTS.md is rendered from verified current-state owners only. Retired, historical, draft, or unclassified material never enters it by construction.
• Rendering is idempotent: if canonical content did not change, nothing is written and no diff appears.
• check and preflight are read-only and fail on a missing or out-of-date projection; sync complete refreshes it after canonical updates.
• The user-owned custom section at the end is preserved verbatim, so project- or tool-specific notes survive regeneration.

The entry file is a view, not a second source of truth.

Retired material leaves the searchable tree

Retiring a document is one operation: DocCanon moves it into the archive root, stamps it as historical or superseded with a short notice naming its owner or reason, and records the archive pattern in .ignore so routine text search skips it. Archaeology is still possible by explicit path or with ignore and hidden-file flags. migrate scan skips the archive, so retired material never comes back as a migration candidate.

Future work has a governed home

Roadmaps, launch conditions, and known gaps live in docs/plans/ with doccanon_authority: plan. Plans route to agents when relevant, never pretend to be shipped behavior, and a release cannot complete while a plan targeting that version is still unresolved (active or abandoned). When a goal ships, its outcome moves into release history and the plan retires.

Try the failure mode

Want to see the trust boundary directly?

git clone https://github.com/Heluhan/Doccanon.git
cd Doccanon
python3 scripts/demo.py

The demo creates a disposable Git repository, establishes a governed baseline, changes covered code without updating its canonical owner, and shows DocCanon refusing to treat the stale state as synchronized.

Installation

GitHub CLI

For agents that use the shared project skill directory:

gh skill install Heluhan/Doccanon doccanon --agent universal

You can also install for a specific host:

# Codex
gh skill install Heluhan/Doccanon doccanon --agent codex

# Claude Code
gh skill install Heluhan/Doccanon doccanon --agent claude-code

# Cursor
gh skill install Heluhan/Doccanon doccanon --agent cursor

# OpenCode
gh skill install Heluhan/Doccanon doccanon --agent opencode

Preview the skill before installing:

gh skill preview Heluhan/Doccanon doccanon

Manual install

DocCanon also ships with its own installer:

git clone https://github.com/Heluhan/Doccanon.git
cd Doccanon

python3 install.py \
  --agent universal \
  --scope project \
  --project /path/to/project

DocCanon has no runtime service, API key, vector database, or model dependency.

The helper requires Git and Python 3.10+.

Updating DocCanon

Skill updates and project upgrades are separate layers. The skill copy is updated by the user or host tooling; a project agent never pulls code, and nothing updates automatically.

• gh skill installs: run gh skill update (GitHub CLI preview).
• install.py installs: update the source checkout and rerun the same command; owned copies are backed up first. python3 install.py --check --json reports installed versus source versions without writing.
• Symlinked development checkouts: update the source checkout behind the link.

After the skill copy is current, run doccanon upgrade status inside the project and reconcile the reported steps; upgrade apply stamps the new version once no semantic step remains.

See the full agent compatibility matrix for host-specific placement and discovery details.

Supported agents

DocCanon includes installation targets for:

• Codex
• Claude Code
• Cursor
• GitHub Copilot
• Gemini CLI
• OpenCode
• Cline

Host discovery and activation behavior varies. The canonical project knowledge itself remains local to the repository and portable across supported hosts.

Token efficiency

DocCanon is designed around a simple idea:

Don't repeatedly spend context rediscovering knowledge the project already knows.

Instead of broad repository exploration before every task, DocCanon routes the agent to a small, fresh canonical bundle followed by targeted code verification.

You can measure the context-volume mechanism locally:

python3 /path/to/doccanon/skills/doccanon/scripts/measure_context.py \
  --project . \
  --intent "change session recovery" \
  --baseline tracked-code \
  --json

This is a context-reduction proxy, not observed model token usage or cost.

For controlled measurements, see the token benchmark protocol.

What DocCanon is not

DocCanon is not a replacement for source code, a vector database, or a codebase RAG service.

Code, tests, schemas, configuration, and direct runtime evidence remain the final proof of implementation behavior.

DocCanon gives agents a better starting point — and keeps that starting point accountable to the code.

Learn more

• 简体中文 README
• Agent compatibility
• DocCanon skill specification
• Token benchmark protocol
• Contributing
• Security

License

MIT.

DocCanon turns codebase understanding from something every agent repeatedly reconstructs into something the project can preserve, verify, and reuse.