agentleFS
tstraub89tstraub89/canon-ai/.claude/skills/canon-init/SKILL.md

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

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
  1. Distinctive:

    Follow these phases in order.

    line 13
  2. Distinctive:

    Test setup: runner, test file patterns, any global fixtures or helpers

    line 32
  3. Distinctive:

    Ask the sub-agent to return:

    line 36
  4. Distinctive:

    Testing: test runner, where tests live, any E2E framework

    line 40
  5. Distinctive:

    Test runner and file conventions

    line 59
  6. Distinctive:

    Wait for explicit confirmation.

    line 65
  7. Distinctive:

    Ask questions one at a time.

    line 71
  8. Distinctive:

    Do not ask a question the codebase already answered.

    line 73
  9. Very specific:

    Write every stub doc with real, project-specific content.

    line 106
  10. Very specific:

    Run canon doctor and read the .claude/settings.json line under "Config".

    line 116
  11. Very specific:

    If anything's missing, ask the project owner: *"Want me to add canon's recommended permission allowlist to .claude/settings.json?

    line 117
  12. Very specific:

    Read .claude/settings.json if it exists (or start from {}).

    line 119
  13. Distinctive:

    Write back with 2-space indentation.

    line 147
  14. Very specific:

    If no, skip — canon works without it.

    line 148
  15. Very specific:

    Read the .claude/hooks/canon-guard.mjs line in canon doctor.

    line 149
  16. Distinctive:

    If no, skip — registration is optional.

    line 174

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

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

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, scripts
  • README.md: product description, setup summary
  • src/ 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: true domain examples in docs/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.

  1. Run canon doctor and read the .claude/settings.json line under "Config". The detail tells you whether the recommended canon perms are present, partially present, or absent.
  2. 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."
  3. If yes:
    • Read .claude/settings.json if 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.
  4. If no, skip — canon works without it; every canon run will just prompt per subprocess.
  5. Read the .claude/hooks/canon-guard.mjs line in canon 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."
  6. If yes:
    • Read .claude/settings.json if it exists (or start from {}).
    • Merge this entry into hooks.PreToolUse, preserving existing entries and other hook keys such as SessionStart:

      {
        "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.
  7. 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 --short

Then 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 --staged to 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.

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.