Adopt Repo Canon in five minutes
This page adopts Repo Canon, a ready-made setup to start from, in one of your repositories. What Repo Standards does explains the terms it uses.
Before you start
Section titled “Before you start”- Use macOS or Linux with Node.js 24 or 26, its bundled npm, and Git 2.32 or newer.
- Start from a Git repository with at least one commit and no uncommitted changes, so Git can show and undo every change the adoption makes to your files.
- Optionally, set a GitHub token in
GH_TOKEN. Without one, the CLI shares GitHub’s anonymous quota with everyone on your IP address; see GitHub requests and tokens.
Ask your coding agent
Section titled “Ask your coding agent”Give your coding agent this prompt in the repository:
Run `npx --yes @lutzseverino/repo-standards adopt https://github.com/lutzseverino/repo-canon --json` in this repository and follow what it prints.The command prints the agent’s instructions, so nothing needs installing first. The agent picks the newest version and a profile using Repo Canon’s profile guidance. It then reviews the proposed changes, adapts your documentation and leaves the result uncommitted. It comes back to you only for what it can’t settle itself, such as an unclear profile choice or a change that would overwrite a setting someone chose on GitHub, which Git can’t undo.
Or run it yourself
Section titled “Or run it yourself”In a terminal, from the repository’s root:
npx @lutzseverino/repo-standards adopt https://github.com/lutzseverino/repo-canonadopt asks its questions one at a time, each with a proposed answer: the
version, the profile, and which of your files each part of the setup covers. It
shows the proposed changes and asks before it starts. Then it walks you through
the edits to your own files, running Repo Canon’s checks after each one.
What changes in the repository
Section titled “What changes in the repository”.repo-standards/records the selection, the source version and profile adopted with the CLI version, inselection.yaml. It also holds a copy of the adopted source, the installed rules, the run’s state and a pinned CLI inruntime/, whose installed dependencies Git ignores.- Repo Canon’s exact files are installed, such as
AGENTS.md,CONTRIBUTING.md, issue and pull request templates and workflows under.github/, and agent skills under.agents/skills/. Each replaces what was at its path. - Your own files, such as
README.mdanddocs/, are edited to meet Repo Canon’s rules. They stay yours. - GitHub settings, such as labels and merge settings, are applied when the repository is ready for them, and otherwise deferred to a later run.
Review it before committing
Section titled “Review it before committing”-
Read the diff with
git diff, and list the new files it omits withgit ls-files --others --exclude-standard. -
Check what was discarded. The run starts only after each overwrite that discards edits is confirmed, at a terminal by you or by the agent after it reviews the diff. Git still has every one of those edits in your last commit.
-
Review the scope: the files the run chose to cover, such as which documents count as your documentation. It needs no confirmation of its own. When the work needs a file the scope missed, the scope changes during the run, as Recover a stopped run describes.
-
Run the pinned CLI and record its verdict before committing:
Terminal window .repo-standards/runtime/node_modules/.bin/repo-standards status --summaryIt should say Ready to commit. Its output is the adoption record, which can serve as the pull request body. If any recorded change-set path is absent from Git’s uncommitted changes,
statusreports not ready. A changed directory counts through at least one uncommitted path beneath it. An empty change set satisfies the path condition, so a complete adoption without state errors can remain ready after committing.
Commit through your usual workflow. Adopt a standards source covers every step in detail, including recovering a run that stopped.