Canon

AI-assisted engagement framework. A structured knowledge system for consulting and design engagements, distributed as an npm package so the methodology can be updated independently of the work.

What it is

Canon gives every engagement a consistent shape: how sessions are planned, how findings are captured, how conclusions are synthesized, and how the AI layer (Claude Code, Cursor) is wired into that structure. The framework lives in node_modules/ — your work lives in your repo. npm update refreshes the methodology; your content is never touched.

Quick start

# In a new project directory:
npm install --save-dev @nicolas-botero-mejia/canon
npx canon init

init asks which AI layers to enable (Claude Code / Cursor), then scaffolds:

plans/          findings/       conclusions/         raw/
wiki/project/   wiki/standards/ scripts/project/
CLAUDE.md       CONTENT_INDEX.md  log.md
.claude/        .cursor/
.framework-version  .gitignore

Staying up to date

npm update @nicolas-botero-mejia/canon
npx canon sync

sync re-vendors the framework dirs (.claude/skills, .claude/agents, .claude/rules, .cursor/rules, .cursor/hooks) from the updated package. It never writes to plans/, findings/, conclusions/, raw/, CLAUDE.md body, or any other file you own.

If any vendored file was modified by hand, sync warns and skips it. Pass --force to overwrite.

Verify at any time:

npx canon doctor

The update-safety guarantee

npm update + npx canon sync will only write to the wiring bucket (discovered dirs + settings dispatcher + .framework-version). It will never write to your content dirs or your CLAUDE.md body.

This is enforced structurally (the manifest lists every path sync may write) and tested automatically:

bash test/update-safety.sh

Framework docs

After init, the framework methodology is available inside your node_modules/:

| Doc | Path | |-----|------| | System index | node_modules/@nicolas-botero-mejia/canon/lib/wiki/system-index.md | | Knowledge architecture | node_modules/@nicolas-botero-mejia/canon/lib/wiki/system-architecture.md | | Design decisions | node_modules/@nicolas-botero-mejia/canon/lib/wiki/system-decisions.md | | Operations guide | node_modules/@nicolas-botero-mejia/canon/lib/wiki/system-operations.md | | Prompting principles | node_modules/@nicolas-botero-mejia/canon/lib/wiki/system-principles.md | | Template standards | node_modules/@nicolas-botero-mejia/canon/lib/wiki/system-template-standards.md | | Verification guide | node_modules/@nicolas-botero-mejia/canon/lib/wiki/system-verification.md | | Template index | node_modules/@nicolas-botero-mejia/canon/lib/templates/template-index.md |

These update with the package. Your AI session loads CLAUDE.base.md automatically via the @import line in your CLAUDE.md.

Versioning policy

Canon follows semver with one opinionated rule about what counts as breaking:

| Change | Version bump | |--------|-------------| | New template, new wiki section, new skill, new script | patch | | Renamed file, changed skill interface, new required wiring field | minor | | Change that requires a manual migration step in consumer projects | major |

The update-safety contract is the invariant — if sync would ever write a user file, that is a bug regardless of version, not a breaking change.

0.x releases may make minor-level changes in patches while the framework stabilizes. Semver guarantees kick in at 1.0.0.

Package name

Published as @nicolas-botero-mejia/canon. The canonical name is set in package.json and bin/lib/paths.mjs (PKG_NAME).

Package structure

bin/                → CLI (canon init / sync / doctor)
  commands/         → init.mjs, sync.mjs, doctor.mjs
  lib/              → CLI shared helpers (paths.mjs, sync-ops.mjs)
  hook.sh           → Hook dispatcher (called by consumer settings.json)
lib/                → Framework IP shipped in the package
  CLAUDE.base.md    → @imported by consumer CLAUDE.md
  .claude/          → agents, skills, rules — vendored on sync
  .cursor/          → rules — vendored on sync
  scripts/          → hook scripts dispatched by bin/hook.sh
  templates/        → all templates (knowledge + script-generated)
  wiki/             → methodology docs (system-*.md)
manifest.json       → declares every path sync may write
docs/               → contributor docs (not shipped) — architecture.md