v5.69.0 Install

Watch it run.
That is the documentation

canon is a CLI and Claude Code plugin that runs your agent's work from plan to merge, holds it to the practices that make code worth keeping, and installs the same setup in every repository. Below is one real session it ran on itself.

Install canon Read the session

your project today

whatever each repo happened to grow

  • CLAUDE.md hand written, if at all
  • .claude/ not there
  • hooks per repo, or none
canon init

after one command

in this order

  1. 1 Base tooling 11 files editorconfig, oxfmt, commitlint, husky hooks, CI
  2. 2 Claude workflow 16 files CLAUDE.md, canon/ docs, .claude/ scaffold, hooks
  3. 3 Governance 10 rules .claude/rules/canon/, from the stack you name

and one it never copies

  • agent skills 71 loaded live from the plugin, so a fix reaches every project at once

One repository is the authoritative copy. Every other project installs it.

operatoryou

“Add a light theme to the design tokens and ship it”

Nothing was configured for this ask.

3 of 22 rules match this path

A rule installs as a file the project owns, and it loads into a Claude session when a matching path is edited, and not before.

edited

src/design/tokens.ts

12 rules did not match it. 7 carry no glob and load every session.

  • typescript

    Enforce strict TypeScript type safety, declarations, and import patterns

    matched **/*.ts
  • code-comments

    Decide when a code comment should exist and what it may claim

    matched **/*.ts
  • dependencies

    Require a dependency to be declared in the manifest before it is imported

    matched **/*.ts

One skill loaded, out of 71 in the catalog

Skills call the CLI and never reimplement it.

  1. session loads one skill 1 of 71
  2. skill asks what exists canon gov list --json
  3. skill matches this project no rule named in the body
  4. CLI does the work canon gov sync

The skill body names no rule and no stack. It asks, matches, and delegates.

canonplan

One plan, written once, and then the planner stops

The plan file is a planner’s only write, and it is decision-ready in one pass.

One controller, and the sessions it launches

Nothing here is one agent talking to itself. The controller holds the plan and launches a session per track.

orchestrator holds no branch and writes no code canon:role-orchestrator
  • planner writes the plan, then stops canon:role-planner

    Asserts the planner role for a session writing one plan, groundwork track, or intake pass under one row, holding what it reads before deciding, what may be written and where, how to read what is already in flight, and what it hands back.

  • worker one branch, one pull request canon:role-worker

    Asserts the worker role for a building session, holding the boundary set, the lifetime, and the two channel obligations a session owes whoever dispatched it.

A dispatch is a separate process rather than a subagent, so each session is steerable, survives the one that launched it, and opens its own pull request.

Three workers and a planner, on disjoint file sets

Each takes its own worktree, its own branch and its own pull request. No fixed number caps the tracks.

main tokens #1699 stylesheet #1703 captures #1705
  • worker · tokens src/design/ #1699 merged
  • worker · stylesheet web/src/styles/ #1703 merged
  • worker · captures assets/captures/ #1705 open
  • planner · readme .canon/plans/ no branch plan written, no branch

Four sessions, four worktrees. The file sets are disjoint, so none of them collided, and nothing caps the number of tracks.

No behavior reaches history ahead of its test

What a worker does inside its own branch, before anything is shown to anyone.

Write the failing test for a behavior before writing the code that satisfies it, confirm it fails for the right reason, implement the smallest change that turns it green, then refactor with the suite green.

claude/skills/test-first/SKILL.mdthe plugin loads it before a planned change
  1. the test written first, and failing
  2. the behavior written until that test passes

The order is enforced rather than advised. canon gov test-order reads the branch before it ships and names anything that reached history ahead of its test.

canonreview

Reviewing #1699 from a session that did not write it

The review attaches what the change actually looks like, as a comment on the pull request.

canon pr evidenceposted by git-pr, re-posted by git-followup#1699

merge base 99ab3bd4
The design token color table at the merge base
current head 78822c31
The design token color table at the current head

Rendered by canon design render, since retired, from each side of the merge, at one viewport and one crop, so the only thing that differs is the tokens.

Reviewed by a session that did not write it

Review is an exchange rather than a verdict, and it closes.

reviewerworker
reads the branch it did not write canon:review-pr
posts findings on the pull request canon pr evidence
addresses them on its own branch canon:review-address
confirms, and the exchange closes approved

A finding posted on the pull request outlives both sessions, which is what an orchestrator and a worker need when neither is still running at merge.

canonmerge

Merged, with every step a fact rather than a claim

A tick is something a session says. A merge is something the trunk shows.

.husky/post-merge fires once, on the trunk, with the pull request number off the squash subject
  • the task closed by this pull request, and its plan with it canon tasks archive
  • every gitignored record folder, off this disk canon records push
  • the fan-in member branches and worktrees an integrator named canon worktrees retire-members
  • the worktree the merged branch was built in canon worktrees reclaim

A tick is a claim a session makes. A merge is a fact the trunk shows, and only the second fires this.

The tokens that merge landed, as this page renders them

Rendered from canon/DESIGN.md by bun run web:previews at build time, and embedded live rather than captured.

Four sessions built it, one reviewed it

No step was claimed by a session that did not run it.

  • planner one plan, and then it stopped .canon/plans/
  • worker · tokens the derived palette anchors #1699, merged
  • worker · stylesheet the regenerated stylesheet #1703, merged
  • worker · captures the re-rendered captures #1705, still open
  • reviewer findings on a branch it did not write the pull request

Three steps to put it in a project

The CLI and the plugin install once per machine. The third step writes files your repository owns from then on.

  1. Install the CLI

    Several skills call the canon CLI to read catalogs and run installs.

    bun install --global @erclx/canon
  2. Add the plugin

    Add the marketplace, then install the Claude Code plugin.

    claude plugin marketplace add https://github.com/erclx/canonclaude plugin install canon@canon
  3. Scaffold a project

    canon init installs base tooling configs, Claude seeds, and governance rules in one pass.

    canon init

Two surfaces, and that session reached into both

The lit names are the ones it used. The rest was there and was not needed.

38 commands 6 used

  • audits
  • browser
  • capture
  • census
  • changelog
  • claude
  • comments
  • context
  • deps
  • design
  • docs
  • drive
  • feedback
  • gate
  • gov
  • hooks
  • indexes
  • init
  • intake
  • inventory
  • labels
  • markdown
  • migrate
  • pr
  • records
  • sandbox
  • secrets
  • serve
  • sessions
  • sync
  • take
  • targets
  • tasks
  • tooling
  • transcripts
  • upgrade
  • upstream
  • worktrees

71 skills 10 used

Set up a project

  • target-setup On a fresh scaffold, to run the install chain
  • deploy-app When a project is ready to publish

Decide what to build

  • plan-intake The input is a pile of findings
  • plan-intake-answer An intake folder holds unread slots
  • backlog-triage The backlog needs pruning
  • plan-groundwork The state is unmeasured and approaches compete
  • decision-escalate Open decisions turn on your preference
  • design-pick The call is taste, wanting candidates side by side
  • task-board A decided item needs a file on the board
  • plan-feature The approach is settled and needs a plan
  • codebase-layout A change adds a file and needs a folder

Build the feature

  • session-worktree Before building a plan in this session
  • auto-ship After plan approval, to chain implement through PR
  • test-first Before implementing a planned change
  • test-craft Writing or changing a test
  • build-in-slices While building, to commit each slice
  • api-design Changing what a caller sees
  • deprecation-migration Deleting or replacing code something may call
  • code-craft Before writing a function, class, or module
  • review-craft Reviewing a change
  • search-craft Before searching outside the project
  • systematic-debugging A test fails or a bug surfaces
  • design-taste Drafting or judging an interface
  • ui-craft Building or judging a component's behavior
  • ui-checklist After a UI change, to list what to check

Check the work before it leaves the branch

  • document-health Documents must answer for length and staleness
  • ui-audit To read UI source for missing states
  • ui-measure To measure paint, processor, and layout cost
  • app-drive To drive a built app with the operator

Ship it

  • git-ship To run the post-feature chain through open PR
  • context-fold The diff left a context entry untrue
  • design-record A picked design needs landing in the record
  • task-complete After the fold, to mark shipped outcomes
  • docs-sync A change left README.md or docs/ stale
  • git-stage Staged changes span several concerns
  • git-commit Staged changes are one concern
  • git-branch A branch needs creating, naming, or renaming
  • git-pr A pull request needs a title and body

After the pull request opens

  • review-pr From an independent session, to post findings
  • review-ui Beside code review, to drive the checklist
  • review-address As the worker, to fix posted findings
  • git-followup A small edit on a branch with an open PR
  • pr-evidence A new head needs its screenshots re-posted
  • git-split A branch carries unrelated commits
  • git-pr-close A pull request closes without merging
  • git-issue Something belongs on the tracker
  • git-worktree After a merge, to reclaim worktrees

Run several tracks at once

  • role-orchestrator To assert the control session that dispatches
  • role-planner To assert the role of a session writing a plan
  • role-reviewer To assert the role of a session reviewing one PR
  • role-worker To assert the role of a session building one branch
  • session-relay This session owes another a message
  • session-resume At session start, to pick up a previous one
  • session-compact Before a compaction, to write a handoff
  • session-map When an orchestrating session closes

Keep the project current with the toolkit

  • target-check In a target, to compare each domain with the toolkit
  • target-update After a release, to catch a target up to the toolkit
  • document-repair Rewrite a failing docs folder to the limits and gate it
  • canon-feedback The toolkit is broken, missing, or off

Generate an artifact on demand

  • create-rule A project rule the toolkit does not ship
  • create-skill A new SKILL.md
  • write-doc A new docs/ page, context entry, or README.md
  • draw-figure A figure or architecture view inside a doc
  • ci-workflow A GitHub Actions workflow file
  • design-identity A logo mark and social card
  • ui-film Real footage of the app for a video

Answer a question at any point

  • canon-cli To pick a canon verb, or learn which can lose edits
  • youtube-transcripts A video transcript wanted as context
  • teach-craft To teach a subject so it sticks
  • markdown-craft Before a substantial markdown edit
  • write-human Before drafting or revising prose

None of that was configured for that session

The rules and the tooling are copied into your project and become yours to edit. The skills are never copied at all, so a fix reaches every project at once and cannot drift.

Install canon Read the source