canon-init
Skill3 starsChanged 9 days agoMITView on GitHub
Use right after running `canon init` on a fresh repo, or when canon's scaffold docs (`docs/product-context.md`, `docs/architecture.md`, `docs/codebase-map.md`, `docs/decisions.md`, `docs/patterns.md`) still contain `TODO[canon]` markers, `<placeholder>` text or "TBD" stubs. Triggers on "fill in the canon docs", "set up canon for this project", "go from scaffold to real content", or explicit `/canon-init` invocation. Run once per project lifecycle.
- Reads credentials
In this repository10 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- canon-changelogSkill
- canon-inline-reviewSkill
- canon-pipelineSkill
- canon-spec-reviewSkill
- canon-specSkill
- canon-statusSkill
- canon-sweepSkill
- docs-auditSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
16 rules. About 0 are common, 10 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈10
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 13
Follow these phases in order.
- Distinctive: line 32
Test setup: runner, test file patterns, any global fixtures or helpers
- Distinctive: line 36
Ask the sub-agent to return:
- Distinctive: line 40
Testing: test runner, where tests live, any E2E framework
- Distinctive: line 59
Test runner and file conventions
- Distinctive: line 65
Wait for explicit confirmation.
- Distinctive: line 71
Ask questions one at a time.
- Distinctive: line 73
Do not ask a question the codebase already answered.
- Very specific: line 106
Write every stub doc with real, project-specific content.
- Very specific: line 116
Run canon doctor and read the .claude/settings.json line under "Config".
- Very specific: line 117
If anything's missing, ask the project owner: *"Want me to add canon's recommended permission allowlist to .claude/settings.json?
- Very specific: line 119
Read .claude/settings.json if it exists (or start from {}).
- Distinctive: line 147
Write back with 2-space indentation.
- Very specific: line 148
If no, skip — canon works without it.
- Very specific: line 149
Read the .claude/hooks/canon-guard.mjs line in canon doctor.
- Distinctive: line 174
If no, skip — registration is optional.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill 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 Init Grill
This skill fills your canon scaffold docs with real project content. Expected output: filled docs/product-context.md, docs/architecture.md, docs/codebase-map.md, docs/decisions.md, docs/patterns.md — no placeholders, no "TBD".
Follow these phases in order. Do not skip or combine phases. ⛔ STOP points require the project owner's explicit confirmation before continuing.
Phase 0 — Check for existing canon files
Before doing anything else, check whether AGENTS.md or CLAUDE.md exists in the project root. If either is present, note it — they are adopter-owned; canon does not insert, merge, or read managed content into them. Note any team conventions, terminology, or pitfalls you find from the codebase and docs — you'll need them in Phase 4.
Phase 1 — Explore the codebase
Delegate codebase exploration to an Explore sub-agent via the Agent tool. Prompt it to read and return:
package.json(or equivalent build file): name, description, main dependencies, scriptsREADME.md: product description, setup summarysrc/or equivalent source root: top-level directory structure with one-line descriptions per directory- Config files:
tsconfig.json, linter/formatter config (eslint.config.*,.oxlintrc.json,biome.json, etc.),.env.example,Dockerfile,docker-compose.*,vercel.json, any CI workflow files (.github/workflows/) - Test setup: runner, test file patterns, any global fixtures or helpers
- Auth mechanism: how are users authenticated? (JWT, sessions, OAuth, Clerk, NextAuth, Passport, etc.)
- Database / ORM: what data layer is used? (Prisma, Drizzle, TypeORM, raw SQL, none, etc.)
Ask the sub-agent to return:
- Tech stack: language + version, framework, major libraries
- Auth: mechanism and the file where session/token logic lives
- Database: ORM or client, where the schema is defined
- Testing: test runner, where tests live, any E2E framework
- Deployment: platform and config file(s)
- Source structure: top-level module map — each directory with a one-line description
- CI: workflow files present, what gates block merges (or "no CI found")
- Surprises: anything non-obvious that a new contributor or AI agent would need to know
Synthesize the findings before proceeding. You do not need to re-read files the sub-agent already read.
Phase 2 — Confirm inferences
⛔ STOP — present your inferences and wait for the project owner to confirm before grilling.
List what you inferred from the codebase:
- Tech stack (language, framework, key libraries with versions)
- Auth mechanism
- Database / ORM
- Test runner and file conventions
- Deployment target
- Anything uncertain or ambiguous — flag these explicitly
Say: "Confirming these before I ask questions — correct anything that's wrong or missing."
Wait for explicit confirmation.
Phase 3 — Grill on gaps
Ask questions one at a time. For every question, state your recommended answer (infer from the codebase where possible). Wait for the project owner to confirm, redirect, or override before moving to the next question.
Do not ask a question the codebase already answered. Continue until you have enough to fill every section in every stub doc.
Topics to cover — skip any that the codebase already answered:
Product identity
- What does this product do, in one sentence?
- Who are the primary users?
- What are the 2–4 core user workflows?
Business model (skip if not applicable)
- Free vs. paid tiers? What's gated behind paid?
- What are the "paid surfaces" that regression-test guardrails should protect?
Delicate surfaces
- Which areas have unbounded blast radius if broken? (auth flows, billing, payments, data migrations, security-critical logic)
- These become the project's
delicate: truedomain examples indocs/product-context.md.
Team conventions
- Branch naming convention?
- PR process — required approvals, review channels?
- Anything the pipeline should know about how the team works?
Known pitfalls
- What footguns exist in this codebase that a fresh agent session would likely step on?
- Any recent incidents or regressions worth calling out?
Terminology (only if relevant)
- Are any domain nouns overloaded or easily confused? (e.g., "workspace" vs. "project" vs. "account")
Phase 4 — Write the docs
Write every stub doc with real, project-specific content. No placeholders. No "TBD". Delete every TODO[canon] blockquote and example row once its section is filled. If you realize you're missing information for a section mid-write, ask one targeted question before writing that section.
For the section-by-section breakdown of what goes in each doc — docs/product-context.md, docs/architecture.md, docs/codebase-map.md, docs/decisions.md, docs/patterns.md, and docs/lessons-learned.md — see write-guide.md. Read it once at the start of Phase 4, then write each doc.
Phase 5 — Set up Claude permissions and guard hook (optional)
By default, Claude Code prompts on every git, gh, codex, and canon subprocess. Canon ships with a recommended allowlist that eliminates the prompts.
- Run
canon doctorand read the.claude/settings.jsonline under "Config". The detail tells you whether the recommended canon perms are present, partially present, or absent. - If anything's missing, ask the project owner: "Want me to add canon's recommended permission allowlist to
.claude/settings.json? I'll preserve your existing entries." - If yes:
- Read
.claude/settings.jsonif it exists (or start from{}). Merge canon's recommended entries into
permissions.allow— the full block is below. Preserve all existing entries; only add what's missing.{ "permissions": { "allow": [ "Bash(git *)", "Bash(gh *)", "Bash(sed *)", "Bash(awk *)", "Bash(ls *)", "Bash(find *)", "Bash(fd *)", "Bash(cat *)", "Bash(head *)", "Bash(tail *)", "Bash(grep *)", "Bash(rg *)", "Bash(wc *)", "Bash(echo *)", "Bash(tr *)", "Bash(xargs *)", "Bash(tee *)", "Bash(jq *)", "Bash(npm run *)", "Bash(npm test)", "Bash(npm test *)", "Bash(npm audit)", "Bash(npm audit *)", "Bash(npm ci)", "Bash(npm ci *)", "Bash(npx canon *)", "Bash(npx tsc *)", "Bash(canon *)", "Bash(codex *)", "Skill(canon-init)", "Skill(canon-spec)", "Skill(canon-spec:*)", "Skill(canon-pipeline)", "Skill(canon-pipeline:*)", "Skill(canon-status)", "Skill(canon-status:*)", "Skill(canon-changelog)", "Skill(canon-changelog:*)", "Skill(canon-spec-review)", "Skill(canon-spec-review:*)", "Skill(canon-inline-review)", "Skill(canon-inline-review:*)", "Skill(canon-sweep)", "Skill(canon-sweep:*)" ] } }The shell-tool entries are for pipeline composition (e.g.
cat foo.json | jq '.bar'), not raw file reads — built-in Read/Glob/Grep stay preferred.- Write back with 2-space indentation.
- Read
- If no, skip — canon works without it; every
canon runwill just prompt per subprocess. - Read the
.claude/hooks/canon-guard.mjsline incanon doctor. If the hook is not registered for Bash, Edit, Write and MultiEdit, ask the project owner: "Want me to add canon's guard hook to.claude/settings.json? I'll preserve your existing hook entries." - If yes:
- Read
.claude/settings.jsonif it exists (or start from{}). Merge this entry into
hooks.PreToolUse, preserving existing entries and other hook keys such asSessionStart:{ "hooks": { "PreToolUse": [ { "matcher": "Bash|Edit|Write|MultiEdit", "hooks": [ { "type": "command", "command": "test -f \"$CLAUDE_PROJECT_DIR/.claude/hooks/canon-guard.mjs\" && node \"$CLAUDE_PROJECT_DIR/.claude/hooks/canon-guard.mjs\" || true", "timeout": 10 } ] } ] } }- Write back with 2-space indentation.
- Read
- If no, skip — registration is optional; canon still works without the guard hook.
The allowlist is purely ergonomics: it reduces permission prompts. The guard hook makes canon refuse pipeline bypasses and points Claude at the command to use. The committed .claude/settings.json is project-level (shared with the team). Personal "full send" overrides belong in a gitignored settings.local.json beside it.
Phase 6 — Stage and summarize
Stage all written docs (and .claude/settings.json if Phase 5 modified it):
git add docs/ 2>/dev/null
[ -f .claude/settings.json ] && git add .claude/settings.json
git status --shortThen print a summary:
- Which docs were filled (list them)
- Whether the Claude permissions allowlist was updated
- Any sections left intentionally thin, and why
- Next step:
git diff --stagedto review, then commit when satisfied - How to run the pipeline once you have a task ready:
canon run <id>
Related
/canon-spec— author the first task once scaffold docs are filled./canon-status— verify the project's task state./canon-pipeline— once a task exists, drive it through the pipeline.AGENTS.md/CLAUDE.md— adopter-owned; generate them with the built-in/init(Claude Code or Codex) when you don't already have them.docs/pipeline-orchestrator.md— pipeline internals for when tasks are running.
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.

