Write and publish a standards source
A standards source is a published, versioned setup: a public GitHub repository
whose root standards.yaml declares the files, skills, guidance, rules and
operations a repository adopts. You write it once, and every repository that
adopts it receives the same setup and its later versions. A standards
repository supplies ordinary content, complete profiles and trusted
operations; the product owns adoption. The
author-standards skill guides
creation, revision, and resumption of a source, and ends at author-reviewed,
validated local material; it does not provision, commit, tag, release, or
adopt, and a local directory is not yet adoptable. Publication, below, is
separate work.
Author format defines the four declaration forms, complete profiles, and discovery; the Alice example shows defaults, a complete work replacement and an employer-content exclusion. The Mira example uses operational guidance, a repeat-safe fix and a different check. Guidance should give an agent observable goals, useful evidence requirements and boundaries, while letting it describe the actual project; generic replacement prose discards project facts. Operations follow the script protocol; document the tools they require so adopters can install them deliberately before adoption.
A published working source is repo-standards-example, based on synthetic Mira material. It was published with the same validation and discovery commands below.
Validate
Section titled “Validate”Validate all profiles with an installed compatible CLI:
repo-standards source validate /path/to/standards --jsonValidation checks declarations and references; it executes neither operations nor probes and does not assess guidance or author-skill quality, concrete scope safety, or semantic completeness in an unfamiliar project. The skill’s exercise guide runs operations against disposable directories through the script protocol, without a Git repository or adoption. The separate adoption workflow exercises integration against published sources and committed adopting projects.
Publish and evolve
Section titled “Publish and evolve”Choose a public GitHub repository for this standards source, independently of
the product repository. Commit the root standards.yaml, all referenced files
and a root LICENSE or LICENCE file (recognized suffixes include .md and
.txt). Choose licensing that permits the intended copying and use. Adoption
retains root license entries and their contents alongside selected source
material and records their hashes and Git provenance. Entries may be files or
directories; neither the root entry nor its contents may contain symbolic links.
Local validation and remote acquisition reject these links with
SOURCE_SYMLINK. It does not infer permission from a public repository
or copy unrelated files and other profiles into retained inputs.
Set requires.repo-standards to an open-ended minimum: the oldest CLI version
you have tested, such as >=7.0.0, without an upper bound or exact version.
The range gates only which CLI versions can select this standards version from
its source. An adopter’s later CLI update keeps their retained standards
whenever the new CLI supports this source format, so an upper bound protects no
one and blocks adopters from selecting your next version. Validation checks
compatibility with the running CLI and resolves all profiles. A stable
standards version and the adopter’s exact CLI package version are independent;
use a new standards version when you change material or compatibility.
Write an adopter-action only for something an adopter must do outside
adoption, such as rotating a credential or changing a hosting setting the
standards cannot fix. It is one line of plain text at the root of
standards.yaml. Adoption already tells adopters about the exact content, the
contextual work and the remote setup it handles, so repeating them adds noise;
the CLI cannot check that your line lies outside adoption. Because older CLIs
reject the field as an unknown field, raise requires.repo-standards to the
first CLI release that accepts it in the same release. See
the author format.
After validating the committed contents with a compatible installed CLI, publish
the same commit. The following commands run in your standards repository; replace
OWNER/SOURCE and choose an unused version. They require GitHub CLI access with
permission to push and publish releases in that repository:
repo-standards source validate . --jsongit status --short# Commit any intended changes and validate that commit before publication.git tag -a v1.0.0 -m 'Standards v1.0.0'git push origin HEADgit push origin refs/tags/v1.0.0gh release create v1.0.0 --repo OWNER/SOURCE --verify-tag \ --title 'Standards v1.0.0' --notes 'Initial stable standards release.'gh repo edit OWNER/SOURCE --add-topic repo-standardsrepo-standards source search --jsonThe release must be published, not a draft or prerelease, and its tag must be
stable SemVer, such as 1.0.0 or v1.0.0. Direct inspection needs only the stable
Git tag; discovery additionally requires a GitHub release and the
repo-standards topic. A release’s tagged snapshot must contain the exact root
standards.yaml path and pass validation; merely adding the file to the default
branch does not repair an older release. Publication uses ordinary GitHub
features and does not add workflows or create a marketplace entry.
Confirm your repository, tag and commit in the search report. GitHub indexing can lag behind publication; check the topic and release, then retry later. Share the canonical URL, exact stable tag and one profile for direct inspection, which does not depend on discovery:
repo-standards inspect --source https://github.com/OWNER/SOURCE \ --standards-version v1.0.0 --profile work --project /path/to/project --jsonAcquire the executable and its matching documentation through public npm installation. The standards source itself is an ordinary public GitHub repository.
Keep published tags immutable: an observed moved tag is rejected. For an update, publish another stable tag and describe replacements, retired declarations, changed scripts/prerequisites and CLI compatibility. Removing/excluding an ID relinquishes governance and removes its installed content, except content the adopter edited, which stays as the adopter’s own. Renaming an ID retires one and adds another. A still-declared skill replaces its whole directory, removing obsolete resources. Adopters review each update’s inspection, which lists each local exact-content edit that the update replaces, and each edited target that leaves the selection and stays; a replacement that discards an edit needs confirmation before the run starts. One update can change their CLI pin, standards version, source, and profile together; your declared range gates only which CLI versions can select a standards version.