Canon

Agents that keep building the same architecture.

Canon turns the way your software is built into a contract the coding agent can follow. The next feature lands in the same shape as the code you already trust. Review stops the structural regressions the project already decided to reject.

Created by Gustavo Franco (gfrancodev).

What you get

• One architecture on every prompt. The agent reads .canon/ before it plans. It does not invent a new folder layout, a new home for repositories, or a new naming system for each task.
• Project decisions outrank generic patterns. Onion, modular monolith, vertical slice, and repository stay available as reference. What this project accepted is what the agent follows.
• The pattern of each kind of file. Ports, entities, adapters, controllers, use cases, and any kind the project identified have a place, a shape, and a short description of how to write them. A use case is one example, not the whole rule.
• New code stays inside that pattern. Review fails a new or edited file that breaks the shape of its kind. Code that was already there stays in the baseline until you confirm a new pattern.
• A contract that can change on purpose. When the architecture should move, Canon asks first. After you confirm, project docs, the map, the naming table, practices, and the review gate move together.
• The same contract on every host. Cursor, Claude Code, Codex, and OpenCode share one engine and one agent, canon-architect.

When it helps

Moment	What Canon produces
New product	Starter kinds become the pattern for the first files you write
Existing code	The repeated pattern of each kind, with the current gaps kept as baseline debt
Architecture change	A proposal you confirm before the pattern itself changes
Every edit	A review of new files against the kind they belong to
Legacy migration	Small waves, a baseline of known debt, and no new violations

The agent runs create, inspect, sync-conventions, review, refactor, and publish for you.

Install

Canon ships plugin metadata for every major coding-agent host. You do not need a separate installer per tool.

Fastest path: open your agent (Cursor, Claude Code, Codex, or OpenCode), paste the repository link, and ask it to install Canon:

Install the Canon plugin from https://github.com/gfrancodev/canon

The agent reads the host manifest in the repo (.cursor-plugin/, .claude-plugin/, .codex-plugin/, or opencode.json), enables skills and hooks, and uses bin/canon-engine plus bin/canon-hook from the checkout or release zip.

Host	Manifest	After install
Cursor	.cursor-plugin/plugin.json	Enable Canon under Settings → Plugins
Claude Code	.claude-plugin/plugin.json	Load the repo as a local plugin
Codex	.codex-plugin/plugin.json	Point Codex at the plugin root
OpenCode	opencode.json	Set CANON_PLUGIN_ROOT to the plugin directory

Manual path (clone, CI, or contributors):

git clone https://github.com/gfrancodev/canon.git
cd canon
npm run build:binaries          # once, if bin/ is missing
npm run install:cursor          # stages runtime plugin for Cursor (~/.cursor/plugins/local/canon)
npm run install:skills          # optional: copy public skills to ~/.agents/skills

scripts/package-plugin.sh copies only what the plugin needs at runtime: skills, agents, knowledge, hooks, templates, and binaries for the current OS. It does not ship Go source, examples/, tests, or cross-platform binaries. Release zips are built the same way.

When the plugin ships with knowledge/, create uses that local catalog. A project can still point manifest.yaml at a GitHub catalog.

The contract next to the code

.canon/
├── project.md
├── conventions.yaml
├── architecture.md
├── naming.md
├── practices/
├── decisions/
├── manifest.yaml
└── canon.lock

Precedence: accepted project decision, accepted convention, observed code, organization knowledge, selected architecture, ecosystem binding, patterns, practices, catalog inspiration.

Version

Canon 0.2.2. History is in CHANGELOG.md.

License

MIT © 2026 Gustavo Franco.