# repo-canon

Repository documentation, contribution, agent workflow, and GitHub validation standards

* Latest release

  [v0.27.0](https://github.com/lutzseverino/repo-canon/releases/tag/v0.27.0), 12 Nov 2026

* Needs

  Repo Standards CLI ≥ 10.0.0

* Repository

  [github.com/​lutzseverino/​repo-canon](https://github.com/lutzseverino/repo-canon)

## Adopt repo-canon

Give your coding agent the prompt in the repository you want to set up, or run the command there yourself. Either way you choose a version and a profile, and nothing is committed until you review the changes.

Agent prompt

``Run `npx --yes @lutzseverino/repo-standards adopt https://github.com/lutzseverino/repo-canon --json` in this repository and follow what it prints.``

Terminal

`npx @lutzseverino/repo-standards adopt https://github.com/lutzseverino/repo-canon`

Anyone can list a source here. Review one before you adopt it.

## A ready-made setup to start from

Repo Canon is a ready-made setup to start from. Your coding agent installs it in your repository and adapts it to your project, and the same prompt later updates it to a newer release.

### AGENTS.md

An AGENTS.md that coding agents read first, with the project's agent docs beside it in docs/agents/.

* `AGENTS.md`
* `docs/agents/README.md`
* `docs/agents/domain.md`
* `docs/agents/issue-tracker.md`
* `docs/agents/project.md`
* `docs/agents/triage-labels.md`

### Agent skills

Skills in .agents/skills/ for triage, specifications and tickets, test-driven development, code review and pull requests.

* `.agents/skills/babysit/`
* `.agents/skills/code-review/`
* `.agents/skills/codebase-design/`
* `.agents/skills/create-adopted-repo/`
* `.agents/skills/create-repository/`
* `.agents/skills/diagnosing-bugs/`
* `.agents/skills/domain-modeling/`
* `.agents/skills/factory/`
* `.agents/skills/grill-with-docs/`
* `.agents/skills/grilling/`
* `.agents/skills/implement/`
* `.agents/skills/improve-codebase-architecture/`
* `.agents/skills/orchestrate/`
* `.agents/skills/pr/`
* `.agents/skills/prototype/`
* `.agents/skills/research/`
* `.agents/skills/review/`
* `.agents/skills/tdd/`
* `.agents/skills/to-spec/`
* `.agents/skills/to-tickets/`
* `.agents/skills/triage/`
* `.agents/skills/wayfinder/`
* `.agents/skills/writing-for-agents/`

### Contribution guidelines

A CONTRIBUTING.md for the people and the agents who work on the repository.

* `CONTRIBUTING.md`

### Issue and PR templates

GitHub issue forms for bug reports, feature requests, specifications and implementation tickets, and a pull request template.

* `.github/ISSUE_TEMPLATE/bug-report.yml`
* `.github/ISSUE_TEMPLATE/feature-request.yml`
* `.github/ISSUE_TEMPLATE/implementation-ticket.yml`
* `.github/ISSUE_TEMPLATE/specification.yml`
* `.github/PULL_REQUEST_TEMPLATE.md`

### Checks

Checks of the documentation's navigation, the READMEs' structure and the pull request reviewer file, run on adoption and with repo-standards check, and GitHub Actions workflows, among them checks of issue contracts and pull request metadata.

* `.github/workflows/issue-contracts.yml`
* `.github/workflows/pr-metadata.yml`
* `.github/workflows/sandbox-image.yml`
* `.github/workflows/standards-update.yml`
* `documentation-navigation`
* `factory-model-policy`
* `factory-review-policy`
* `project-readme-structure`
* `pull-request-reviewer`
* `repository-readme-structure`
* `required-checks`
* `typescript-astro-stack-manifests`
* `typescript-node-stack-manifests`
* `typescript-vite-stack-manifests`

## Profiles

* standard

  The Repo Canon standards for every adopting repository

* factory

  The standard profile plus the factory's repository files and workflow rules, for a repository a factory serves

* workbench

  Only the workflow skills, with the files they need to run and their license notices, for the orchestrating agent's workbench

## What it installs

Each declaration in its `standards.yaml` at v0.27.0, with the paths it installs or governs and the checks it runs.

| Declaration                                          | Installs or governs                                                  | Checks                                                          | Profiles          |
| ---------------------------------------------------- | -------------------------------------------------------------------- | --------------------------------------------------------------- | ----------------- |
| `agent-configuration-index`File                      | `docs/agents/README.md`                                              |                                                                 | standard, factory |
| `agent-guidance`File                                 | `AGENTS.md`                                                          |                                                                 | standard, factory |
| `bug-report-template`File                            | `.github/ISSUE_TEMPLATE/bug-report.yml`                              |                                                                 | standard, factory |
| `comments`Repository guidance                        | Paths found in each project                                          |                                                                 | standard, factory |
| `contribution-guidance`File                          | `CONTRIBUTING.md`                                                    |                                                                 | standard, factory |
| `documentation`Repository guidance                   | Paths found in each project                                          | `documentation-navigation`                                      | standard, factory |
| `domain-configuration`File                           | `docs/agents/domain.md`                                              |                                                                 | standard, factory |
| `factory-configuration`File                          | `.scriptorium/config.json`                                           |                                                                 | factory           |
| `factory-sandbox-image`Repository guidance           | `.scriptorium/Dockerfile``.factory/Dockerfile``.factory/config.json` |                                                                 | factory           |
| `factory-sandbox-image-workflow`File                 | `.github/workflows/sandbox-image.yml`                                |                                                                 | factory           |
| `factory-workflow`Repository guidance                | Paths found in each project                                          | `factory-model-policy`                                          | factory           |
| `feature-request-template`File                       | `.github/ISSUE_TEMPLATE/feature-request.yml`                         |                                                                 | standard, factory |
| `git-attributes`File                                 | `.gitattributes`                                                     |                                                                 | standard, factory |
| `github-repository-configuration`Repository guidance | Paths found in each project                                          | `required-checks``pull-request-reviewer``factory-review-policy` | standard, factory |
| `github-validator-trigger`File                       | `.github/scripts/validate.mjs`                                       |                                                                 | standard, factory |
| `humanlayer-skills-license`File                      | `.agents/skills/LICENSE.humanlayer-skills`                           |                                                                 | All               |
| `implementation-ticket-template`File                 | `.github/ISSUE_TEMPLATE/implementation-ticket.yml`                   |                                                                 | standard, factory |
| `issue-contract-cutoff`File                          | `scripts/issue-contract-cutoff.mjs`                                  |                                                                 | standard, factory |
| `issue-contract-sources`File                         | `scripts/issue-contract-sources.mjs`                                 |                                                                 | All               |
| `issue-contract-store`File                           | `scripts/issue-contract-store.mjs`                                   |                                                                 | All               |
| `issue-contract-validator`File                       | `vendor/repo-canon/validate-issue-contract.mjs`                      |                                                                 | All               |
| `issue-contract-workflow`File                        | `.github/workflows/issue-contracts.yml`                              |                                                                 | standard, factory |
| `issue-tracker-configuration`File                    | `docs/agents/issue-tracker.md`                                       |                                                                 | standard, factory |
| `marked-license`File                                 | `vendor/marked/LICENSE`                                              |                                                                 | All               |
| `marked-parser`File                                  | `vendor/marked/marked.esm.js`                                        |                                                                 | All               |
| `marked-provenance`File                              | `vendor/marked/README.md`                                            |                                                                 | All               |
| `mattpocock-skills-license`File                      | `.agents/skills/LICENSE.mattpocock-skills`                           |                                                                 | All               |
| `parse5-entities-license`File                        | `vendor/parse5/LICENSE.entities`                                     |                                                                 | All               |
| `parse5-license`File                                 | `vendor/parse5/LICENSE.parse5`                                       |                                                                 | All               |
| `parse5-parser`File                                  | `vendor/parse5/parse5.esm.js`                                        |                                                                 | All               |
| `parse5-provenance`File                              | `vendor/parse5/README.md`                                            |                                                                 | All               |
| `postern-bundle`File                                 | `vendor/postern/postern.mjs`                                         |                                                                 | All               |
| `postern-license`File                                | `vendor/postern/LICENSE`                                             |                                                                 | All               |
| `postern-provenance`File                             | `vendor/postern/README.md`                                           |                                                                 | All               |
| `pr-metadata-validator`File                          | `.github/scripts/validate-pr-metadata.mjs`                           |                                                                 | standard, factory |
| `pr-metadata-workflow`File                           | `.github/workflows/pr-metadata.yml`                                  |                                                                 | standard, factory |
| `project-agent-guidance`File                         | `docs/agents/project.md`                                             |                                                                 | standard, factory |
| `project-readmes`Repository guidance                 | Paths found in each project                                          | `project-readme-structure`                                      | standard, factory |
| `pull-request-template`File                          | `.github/PULL_REQUEST_TEMPLATE.md`                                   |                                                                 | standard, factory |
| `rendered-markdown-runtime`File                      | `operations/lib/rendered-markdown.mjs`                               |                                                                 | All               |
| `repository-license`File                             | `LICENSE`                                                            |                                                                 | standard, factory |
| `repository-readme`File                              | `README.md`                                                          | `repository-readme-structure`                                   | standard, factory |
| `skill-babysit`Skill                                 | `.agents/skills/babysit/`                                            |                                                                 | All               |
| `skill-code-review`Skill                             | `.agents/skills/code-review/`                                        |                                                                 | All               |
| `skill-codebase-design`Skill                         | `.agents/skills/codebase-design/`                                    |                                                                 | All               |
| `skill-create-adopted-repo`Skill                     | `.agents/skills/create-adopted-repo/`                                |                                                                 | workbench         |
| `skill-create-repository`Skill                       | `.agents/skills/create-repository/`                                  |                                                                 | workbench         |
| `skill-diagnosing-bugs`Skill                         | `.agents/skills/diagnosing-bugs/`                                    |                                                                 | All               |
| `skill-domain-modeling`Skill                         | `.agents/skills/domain-modeling/`                                    |                                                                 | All               |
| `skill-factory`Skill                                 | `.agents/skills/factory/`                                            |                                                                 | factory           |
| `skill-grill-with-docs`Skill                         | `.agents/skills/grill-with-docs/`                                    |                                                                 | All               |
| `skill-grilling`Skill                                | `.agents/skills/grilling/`                                           |                                                                 | All               |
| `skill-implement`Skill                               | `.agents/skills/implement/`                                          |                                                                 | All               |
| `skill-improve-codebase-architecture`Skill           | `.agents/skills/improve-codebase-architecture/`                      |                                                                 | All               |
| `skill-orchestrate`Skill                             | `.agents/skills/orchestrate/`                                        |                                                                 | workbench         |
| `skill-pr`Skill                                      | `.agents/skills/pr/`                                                 |                                                                 | All               |
| `skill-prototype`Skill                               | `.agents/skills/prototype/`                                          |                                                                 | All               |
| `skill-research`Skill                                | `.agents/skills/research/`                                           |                                                                 | All               |
| `skill-review`Skill                                  | `.agents/skills/review/`                                             |                                                                 | All               |
| `skill-tdd`Skill                                     | `.agents/skills/tdd/`                                                |                                                                 | All               |
| `skill-to-spec`Skill                                 | `.agents/skills/to-spec/`                                            |                                                                 | All               |
| `skill-to-tickets`Skill                              | `.agents/skills/to-tickets/`                                         |                                                                 | All               |
| `skill-triage`Skill                                  | `.agents/skills/triage/`                                             |                                                                 | All               |
| `skill-wayfinder`Skill                               | `.agents/skills/wayfinder/`                                          |                                                                 | All               |
| `skill-writing-for-agents`Skill                      | `.agents/skills/writing-for-agents/`                                 |                                                                 | All               |
| `specification-template`File                         | `.github/ISSUE_TEMPLATE/specification.yml`                           |                                                                 | standard, factory |
| `standards-update-workflow`File                      | `.github/workflows/standards-update.yml`                             |                                                                 | standard, factory |
| `triage-label-configuration`File                     | `docs/agents/triage-labels.md`                                       |                                                                 | standard, factory |
| `typescript-astro-stack`Repository guidance          | Paths found in each project                                          | `typescript-astro-stack-manifests`                              | standard, factory |
| `typescript-node-stack`Repository guidance           | Paths found in each project                                          | `typescript-node-stack-manifests`                               | standard, factory |
| `typescript-vite-stack`Repository guidance           | Paths found in each project                                          | `typescript-vite-stack-manifests`                               | standard, factory |
| `validator-command`File                              | `vendor/repo-canon/validate.mjs`                                     |                                                                 | standard, factory |
