agentleFS
tstraub89tstraub89/canon-ai/AGENTS.md

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.

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
  1. Very specific:

    Prefer canon task helpers over direct status.json edits so phase state stays consistent.

    line 56
  2. Distinctive:

    Use worktrees for task isolation when canon creates them.

    line 57
  3. Very specific:

    Never edit templates/ mirrors directly.

    line 63
  4. Distinctive:

    Never force-push main; the pipeline and release flow manage branch state.

    line 64
  5. Very specific:

    When a diff adds a gate, exemption, or new routing, trace it through each verdict (approved, approved_with_nits, changes_requested, …

    line 69

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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-check

docs/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 of CANON_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 no templates/docs/ mirror (BACKLOG.md, release-process.md), and CHANGELOG.md — canon init does 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

AgentPrimary RoleWritesReviews
ClaudeArchitect, code reviewer, QASpecs, plans, code reviews, QA summariesCode
Codex (mixed mode)Implementer, spec reviewer, cold code-review lensCode, handoff reportsSpecs
HumanProduct owner, final arbiterProduct decisions, prioritiesSpecs, 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 claude mode 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 phase and canon task accept manage task state; prefer them over hand-editing status.json.
  • canon run drives the pipeline, canon watch observes detached runs, and canon stop terminates them when needed.

Conventions

  • Task artifacts live under tasks/<id>/; tasks/<id>/notes.md is the raw scratchpad and docs/lessons-learned.md is the promotion buffer.
  • Root canon-managed files are authoritative; templates/ is a derived mirror. Edit the root copy, then run npm run sync-templates and verify with npm run sync-templates:check. AGENTS.md and CLAUDE.md are not part of the managed set; they have no templates/ mirror and need no sync.
  • Prefer canon task helpers over direct status.json edits so phase state stays consistent.
  • Use worktrees for task isolation when canon creates them.
  • The managed set lives in src/lib/canon-owned.ts as CANON_OWNED and DELIMITED; 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/, and templates/ 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.md for file locations and entry points.
  • docs/patterns.md for implementation pitfalls and load-bearing patterns.
  • docs/pipeline-orchestrator.md for flags, env vars, reroute, worktrees, PR/ship, and recovery.
  • docs/release-process.md for branch, versioning, and release-cut mechanics.
  • docs/product-context.md for user-visible behavior and terminology.
  • docs/decisions.md for settled rules and architecture decisions.
  • docs/lessons-learned.md for distilled cross-task memory.
  • docs/task-quality-log.md for QA trends and task-quality signals.

Operational Notes

  • Append short raw observations to tasks/<id>/notes.md with a phase prefix.
  • Re-run canon doctor after install or when environment assumptions change.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.