canon runs your agent's work from plan to merge
A CLI and Claude Code plugin that holds the work to established engineering practice, and installs the same setup in every repo.
claude plugin marketplace add https://github.com/erclx/canon claude plugin install canon@canon Install canon Follow the change
The film follows one real change, from the question that started it to its merge as erclx/canon#2418. Here is each step, with what it left behind.
groundwork
Measured before anyone plans it
Context had grown from 16,109 words to 218,865. The track searched, measured, and spiked before it decided anything.
218,865
words of context, up from 16,109 in July
- Search every outside claim carries a link
- Measure the whole corpus, by word
- Spike one entry, 741 words to 93
Decision: three sections per entry
Measured 2026-10-17, groundwork 156-context-token-budget
plan
One plan, every question already answered
The plan names the files it touches and the test that proves them. Each open question carries a suggested answer, so a blank reply still moves.
- ## Files to touch
- src/context/audit.ts
- ## Verification
- bun test src/context/audit.test.ts
- ## Risks
- 1. Should a gotcha carry its own length limit?
- Suggested: no, one line is enough
dispatch
You talk to one session, and it launches the rest
An orchestrator places each plan on the board and starts a worker per change, each in its own worktree.
- planner Two plans landed, linked to their tasks.
- orchestrator Both standards plans are in, and I've dispatched their workers on Opus.
- orchestrator-canon pinned
- feat/context-entry-shape editing audit.ts
- feat/docs-page-shape entered worktree
- Documentation density… plans linked
build
Each worker in its own worktree, held to the rules
Rules load on the path being edited, and the gate runs every stage before the pull request opens.
rule loaded → code-craft
export const GOTCHA_CAP = 5 export const LAYOUT_BULLET_CAP = 5
rule loaded → test-craft
- context-citations
- types
- tests
- passed pull request opened
review
A fresh session reviews, until nothing is open
A session that did not write the change reads it against the plan. The worker fixes what it finds, and the review closes only when nothing is left.
-
the fold still says to write decisions -
internal-docs puts decisions back - review-address: fixed at f64e35a
- ## Review closed re-reviewed f64e35a
- ungated entry reports, exit 0
- six gotchas count as six
- seed tree gates by prefix
merge
You merge, and the next wave starts
The task archives with its plan, and the board moves to the next row.
canon pr merge 2418
- merged into main
- task archived with its plan
-
v152.3 entry shape - v152.4 rebuild next
- v152.6 docs rebuild
Quick start
The skills land as /canon:<name>, and the CLI needs Bun on your path. canon runs on Linux and macOS.
Set up a repository with canon init, which lays down its rules, seeds, and configs.
claude plugin marketplace add https://github.com/erclx/canon claude plugin install canon@canon bun install --global @erclx/canon