canon-ai
AGENTS.md2 starsChanged 8 days agoMITView on GitHub
canon-ai is a TypeScript/Node CLI published as an npm package. It scaffolds a Claude + Codex spec-driven pipeline into other repositories, and canon-ai dogfoods that same pipeline on itself. That's why tasks/, worktree isolation, and templates/ mirrors exist. This is canon-ai's shared project overview. It gives both agents the same starting picture; detailed operating rules arrive just in time through skills, prompt templates, and the docs below. Node 24 (engines), TypeScript, ESM, built with tsup; unit tests use the Node…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository10 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- canon-changelogSkill
- canon-initSkill
- canon-inline-reviewSkill
- canon-pipelineSkill
- canon-spec-reviewSkill
- canon-specSkill
- canon-statusSkill
- canon-sweepSkill
- docs-auditSkill
The file
We split this AGENTS.md into the rules it gives an agent
5 rules. About 0 are common, 2 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Very specific: line 56
Prefer canon task helpers over direct status.json edits so phase state stays consistent.
- Distinctive: line 57
Use worktrees for task isolation when canon creates them.
- Very specific: line 63
Never edit templates/ mirrors directly.
- Distinctive: line 64
Never force-push main; the pipeline and release flow manage branch state.
- Very specific: line 69
When a diff adds a gate, exemption, or new routing, trace it through each verdict (approved, approved_with_nits, changes_requested, …
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
canon-ai
canon-ai is a TypeScript/Node CLI published as an npm package. It scaffolds a Claude + Codex spec-driven pipeline into other repositories, and canon-ai dogfoods that same pipeline on itself. That's why tasks/, worktree isolation, and templates/ mirrors exist.
This is canon-ai's shared project overview. It gives both agents the same starting picture; detailed operating rules arrive just in time through skills, prompt templates, and the docs below.
Commands
Node 24 (engines), TypeScript, ESM, built with tsup; unit tests use the Node native test runner with tsx.
npm run build && npm run type-check && npm run lint && npm test
npm run sync-templates:check # root canon-managed files vs their templates/ mirrors
npm run docs-refs-checkdocs/architecture.md holds the canonical validation and CI commands; run that section before checks. canon run <id> --pr opens a draft PR at human_review; canon run <id> --ship runs the post-merge cleanup path after approval. Other CLI subcommands: canon --help.
Adopter Scope
Every string in src/ that reaches an adopter at runtime — CLI output, error and warning text, and agent prompts (including the .md templates in src/orchestrator/prompts/templates/, which tsup bundles into dist/) — must make sense in an arbitrary repo. Before naming a path, file, or convention in one, check that an adopter has it:
- They do: the docs in
templates/docs/,.canon/templates/*, the rest ofCANON_OWNED, task artifacts canon creates (spec.md,handoff.md,status.json, …), and adopter-owned files canon expects (AGENTS.md,CLAUDE.md,package.json,.claude/settings.json). - They do not: canon-ai's own tree (
src/**,scripts/**,tests/**),templates/as a literal path,docs/files with notemplates/docs/mirror (BACKLOG.md,release-process.md), andCHANGELOG.md—canon initdoes not scaffold one.
Describe what to change rather than citing a canon-ai file the reader cannot open; write "the canon-ai README" so it can't read as the adopter's own; gate anything optional on its existence ("if the project keeps one"). Watch for predicates inherited from the project canon was extracted from — a doc-read condition like "if the task touches Pro features" is unmeetable in a repo with no such concept. The test is whether an adopter can read the string, so source comments are exempt — tsup strips them (the // <path> module separators left in dist/ are esbuild's own and are never printed).
Roles
| Agent | Primary Role | Writes | Reviews |
| Claude | Architect, code reviewer, QA | Specs, plans, code reviews, QA summaries | Code |
| Codex (mixed mode) | Implementer, spec reviewer, cold code-review lens | Code, handoff reports | Specs |
| Human | Product owner, final arbiter | Product decisions, priorities | Specs, previews, test plans |
In claude mode (CANON_PROVIDER=claude) every role runs on Claude Code, and code review uses two Claude lenses; see docs/pipeline-orchestrator.md §"Provider Selection".
Shared Norms
- Cross-review: no agent reviews its own output. In mixed mode, Claude writes specs and Codex reviews them; Codex writes code and Claude reviews it. In
claudemode separate Claude sessions hold each side. - Communication: lead with the finding, surface real disagreement, and make risks and tradeoffs visible to the human. Tone is project taste; honest signal is canon discipline.
Workflow
canon-ai runs a phase pipeline: spec -> spec_review -> plan -> implement -> code_review -> qa -> human_review.
- Fast tier collapses spec and plan into one Claude session.
- Full tier keeps spec, review, plan, implement, code review, and QA separate.
canon task phaseandcanon task acceptmanage task state; prefer them over hand-editingstatus.json.canon rundrives the pipeline,canon watchobserves detached runs, andcanon stopterminates them when needed.
Conventions
- Task artifacts live under
tasks/<id>/;tasks/<id>/notes.mdis the raw scratchpad anddocs/lessons-learned.mdis the promotion buffer. - Root canon-managed files are authoritative;
templates/is a derived mirror. Edit the root copy, then runnpm run sync-templatesand verify withnpm run sync-templates:check.AGENTS.mdandCLAUDE.mdare not part of the managed set; they have notemplates/mirror and need no sync. - Prefer
canon taskhelpers over directstatus.jsonedits so phase state stays consistent. - Use worktrees for task isolation when canon creates them.
- The managed set lives in
src/lib/canon-owned.tsasCANON_OWNEDandDELIMITED; add managed files there, not here.
Boundaries
- This repo is public. Code, tests, fixtures, docs, commit messages, issues, and PR text must not name any private adopter project: no product names, task ids, file paths, or PR numbers from other repositories. Use neutral placeholders (
example-app,tasks/example-task/). - Never edit
templates/mirrors directly; edit the root copy and sync. - Never force-push
main; the pipeline and release flow manage branch state.
Code Review Rules
- When a diff changes a contract (accepted parser forms, a verdict or phase meaning, a required heading, a CLI flag), find every other place that restates it: skills,
.canon/templates/, orchestrator prompt templates,docs/, andtemplates/mirrors. A restatement that is now stale or contradictory is a P2. - When a diff adds a gate, exemption, or new routing, trace it through each verdict (
approved,approved_with_nits,changes_requested,spec_gap,sanctioned) and each recovery path (canon task accept,--reroute,reset-*). Flag any path that skips the gate or advertises a recovery that can't succeed.
Where to Go Deeper
docs/codebase-map.mdfor file locations and entry points.docs/patterns.mdfor implementation pitfalls and load-bearing patterns.docs/pipeline-orchestrator.mdfor flags, env vars, reroute, worktrees, PR/ship, and recovery.docs/release-process.mdfor branch, versioning, and release-cut mechanics.docs/product-context.mdfor user-visible behavior and terminology.docs/decisions.mdfor settled rules and architecture decisions.docs/lessons-learned.mdfor distilled cross-task memory.docs/task-quality-log.mdfor QA trends and task-quality signals.
Operational Notes
- Append short raw observations to
tasks/<id>/notes.mdwith a phase prefix. - Re-run
canon doctorafter install or when environment assumptions change.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

