Author format: repo-standards/v2
An independently authored standards repository supplies one root
standards.yaml and ordinary referenced files. Run
repo-standards source validate [directory] [--json] before publication. The
directory defaults to the current directory. All profiles are validated; there
is no profile filter. This command reads local sources, never executes author
scripts or prerequisite probes, and does not change the source or Git state.
Local-directory adoption is not an interface of this product.
Format identity
Section titled “Format identity”Every source declares format: repo-standards/v2, the only supported format.
Validation rejects any other value with INVALID_FORMAT. Repository guidance
uses either explicit targets or project-specific discovery; file declarations,
skills, operations, and profile resolution are the same for both scope modes.
Set the CLI compatibility range to versions actually validated; the format
identity and CLI package version are independent. Older CLIs reject unsupported
formats.
This implementation supports discovery authoring, validation, and
two-pass scope inspection.
A selected profile with unresolved discovery returns guidance, eligible evidence,
a discovery request identity, the draft of each
discovery script, and a DISCOVERY_REQUIRED start blocker.
inspect --scope validates an evidence-backed repo-standards/scope/v2 proposal
and presents concrete paths in the complete inspection. Initial adoption passes
the same proposal to start --scope, bound to that inspection’s identity.
Contextual assessment reviews coverage again after fixes and before
submission. Empty scope retains the declaration and its operations; an
optional declaration may instead have no scope, which
installs none of its rules and runs none of its operations. Source
validation alone proves neither project-specific safety nor semantic coverage.
An active run cannot change its confirmed scope; when contextual work needs
other paths, a new run
adopts again with a new confirmed scope.
Fresh discovery proposals also apply during every update, including one that
applies an unchanged selection again. adopt reuses the recorded entry in that
proposal only while the declaration’s discovery guidance, rules and fresh
discovery-script draft are unchanged and every path the entry names exists,
and otherwise proposes it for review
(reused answers): changing discovery guidance,
rules, or what a discovery script drafts makes adopters review the scope again.
Changing a contextual declaration’s rules, or its adoption guidance when it has
no rules, likewise makes adopters assess it again. Between complete runs, scope
can add or remove individual paths; removals end governance without deleting
project content.
Root and profiles
Section titled “Root and profiles”The root requires exactly these fields, and may set one optional field,
adopter-action. Unknown fields at every schema level
are errors, including adoption hooks, environment overrides, shell options,
custom working directories, and profile inheritance fields.
| Field | Value |
|---|---|
format | repo-standards/v2 |
name | Nonempty descriptive string |
description | Nonempty descriptive string |
requires | Mapping containing only repo-standards, a nonempty npm SemVer range compatible with the running CLI; declare an open-ended minimum such as >=7.0.0 |
defaults | Mapping containing only declarations, a mapping of IDs to declarations (possibly empty) |
profiles | Nonempty mapping of profile names to complete profiles |
Adopter action
Section titled “Adopter action”The optional root field adopter-action holds one nonempty line of plain text
that tells adopters of this release what to do outside adoption, such as
rotating a credential the standards stop using. It is additive within
repo-standards/v2. Validation rejects an empty or blank value, a value with
more than one line or a control character, and a value that is not a string,
with INVALID_TYPE. The CLI cannot check that the action lies outside
adoption, which the run already performs: the author is responsible for that.
Older CLIs reject the field as UNKNOWN_FIELD, so a source that sets it raises
requires.repo-standards to the first CLI release that accepts it. The CLI
retains the line with the other source metadata, shows it in the
inspection summary and the adoption record’s
Impact and Migration sections, and renders each newer release’s line in
outdated. It derives the rest of
the adopter action itself.
Each profile requires a nonempty description and a declarations mapping,
which may be empty, and may name the hosting platforms it
supports. Declaration IDs, skill names, and operation IDs use
lower-case ASCII kebab-case: letters or digits separated by single hyphens.
Declaration IDs are local to the source. Operation IDs are unique across the
checks and fixes of their declaration; another declaration may reuse one.
Exactly two resolution levels exist: defaults and one selected profile.
Omitting an ID inherits its whole declaration. Repeating it replaces the whole
declaration, including checks and fixes. A new ID adds a declaration.
id: {exclude: true} removes an existing default declaration and its operations;
it cannot have any other fields, appear in defaults, or name a nonexistent
default. Fields never merge. Resolved declarations are ordered by ID, with
operation list order preserved. No targets are compared across separate
profiles. Every declared reference is checked, including a default replaced or
excluded by all profiles.
YAML is a single document with string mapping keys and standard YAML 1.2
scalar types. Quote version ranges and literal numeric arguments. Duplicate
mapping keys are errors, including repeated profile and declaration IDs.
Anchors and nonrecursive aliases are supported; custom tags and merge keys are
not part of the format. Recursive, excessively deep, or excessively expanded
YAML is rejected with YAML_STRUCTURE. Duplicate fields remain invalid, but
their alternative values are still validated for independent errors; more than
256 ambiguous interpretations also produces YAML_STRUCTURE.
Platforms
Section titled “Platforms”defaults: declarations: ci-workflow: kind: file platform: github target: .github/workflows/check.yml exact: content/check.ymlprofiles: work: description: Work projects platforms: [github] declarations: {}A profile lists the hosting platforms an adopting project can select it on in
platforms, a nonempty list of distinct platform names. A profile without
platforms supports github alone, so a source that names no platform is
unchanged. The adopting project selects its platform separately from its
profile; see choose the hosting platform.
Do not split a profile per platform, such as react-github and
react-gitlab: declare the platform choice inside the profile.
Any declaration may name the one platform it applies on, in defaults or a
profile. On every other platform the declaration is left out of the resolved
profile, before scope, so it installs nothing, runs no operation and needs no
discovery. That differs from an optional declaration’s
no scope, which each project decides in its scope answer. A declaration without platform
applies on every platform of its profile. An exclusion takes no platform.
Older CLIs reject platforms and platform as unknown fields, so a source
that uses them raises requires.repo-standards to the first CLI that accepts
them. Platforms are named as Postern names them. This CLI supports github only, so
every other name fails with UNSUPPORTED_PLATFORM, an empty list with
EMPTY_PLATFORMS, and a repeated platform with DUPLICATE_IDENTITY. Until
another platform is supported, published files stay GitHub-shaped.
Declarations for different platforms never apply together, so their targets
may overlap; targets of declarations that can apply together may not.
Check locations
Section titled “Check locations”A profile may offer check-locations: [github, runner, self-reported], or any
nonempty subset. github means hosted GitHub Actions, runner a
repository-named machine posting commit statuses, and self-reported the
authoring agent’s sandbox. Omitting the profile key means [github].
The project selects exactly one through --checks or an answers-file checks
answer, independently of its hosting platform; see
choose the check location.
Any declaration, in defaults or a profile, may filter applicability through
check-locations: [...]. Without that key it applies at every location the
profile offers. Both arrays must contain unique supported strings and be
nonempty. Invalid types, empty arrays, duplicates and unknown values name the
offending field and, for an invalid entry, its value.
profiles: work: description: Work projects check-locations: [github, runner, self-reported] declarations: ci-workflow: kind: file platform: github check-locations: [github] target: .github/workflows/check.yml exact: content/check.ymlPlatform and check-location filters apply together before scope: a declaration
left out installs nothing, contributes no rules, executes no checks, fixes or
discovery script, and asks for no scope. This is distinct from confirming an
optional declaration with no scope. Defaults, whole replacements and exclusions
keep their usual meaning; an exclusion accepts only exclude: true.
Declarations that cannot apply together on any offered location and platform
may share targets; overlapping applicability keeps the usual target conflicts.
Declaration checks still names executable operations, never a location filter.
Sources using either optional author key must set requires.repo-standards to
an open-ended minimum CLI release that understands check locations. Older CLIs
reject the keys. The optional author keys keep repo-standards/v2 because
sources that omit them keep their meaning.
Declarations
Section titled “Declarations”All four forms may contain optional checks and fixes lists. Omitted lists
resolve to empty lists, and every form but an exact skill may name optional
rules. Their remaining fields are:
| Form | Required fields |
|---|---|
| Exact file | kind: file, one target, and exact referencing a regular source file |
| Contextual file | kind: file, one target, and guidance, its adoption guidance, referencing a regular source file |
| Exact skill | kind: skill, name, and source referencing a whole directory containing a regular SKILL.md |
| Repository guidance | kind: repository, guidance, its adoption guidance, referencing a regular file, and exactly one scope mode: explicit targets containing both paths and directories lists, or discovery referencing a regular file, optionally with a discovery-script |
A file must have exactly one of exact or guidance. Repository guidance
requires exactly one of targets or discovery, and explicit targets need at
least one path or directory.
Rules and adoption guidance
Section titled “Rules and adoption guidance”Every form but an exact skill may also name rules, referencing a regular
source file: human-readable Markdown stating the declaration’s lasting
requirements. Adoption installs each active declaration’s rules at
.repo-standards/rules/<declaration ID>.md as exact content the CLI owns, with
a generated index, and checks and assessments cite them; see
installed rules. guidance is the declaration’s adoption guidance:
one-time instructions for the run, such as a migration, a question for the
maintainer, or how to assess the declaration. It is kept only with the
retained inputs and never installed. Keep lasting requirements in rules and
one-time steps in guidance.
A skill declaration with rules fails with UNKNOWN_FIELD. A declaration with
rules cannot have the ID readme, whose installed rules would collide with
the index README.md; it fails with RESERVED_NAME. A repository guidance
declaration whose confirmed scope is empty is repository-wide: its rules cover
every path of the adopting project. An
optional declaration confirmed with no scope installs
no rules at all. Exact skills target
.agents/skills/<name> as a whole, and adoption also installs the skill’s
skill link at .claude/skills/<name>, which is a
target of the skill too: no other target may overlap it. repository-standards,
author-standards, and adopt-repository-standards are product-owned system skill names reserved against
author skills. The retired adopt-standards and standards-updates names are
not reserved. Author skill content remains ordinary Agent Skill material; source
validation verifies its directory, SKILL.md references, and invocation agreement, not prose quality or
skill behavior.
Skill invocation
Section titled “Skill invocation”Claude Code reads disable-model-invocation from the YAML frontmatter in
SKILL.md. Codex reads policy.allow_implicit_invocation from the skill’s
agents/openai.yaml. These settings must agree: manual-only skills use true
and false, respectively; model-invocable skills use false and true.
An absent setting means model-invocable, including absent frontmatter or an
absent agents/openai.yaml. A skill that states neither passes unchanged.
Present invocation settings must be YAML booleans. Other skill metadata is
outside the author schema.
Unrelated duplicate keys, invalid YAML, or non-mapping metadata with no invocation setting use the setting’s default without a diagnostic. A duplicated invocation key, a non-boolean setting, or an unparseable document containing a line for that setting produces a diagnostic naming its metadata file. Frontmatter delimiters accept trailing spaces or tabs and a leading byte-order mark before the opening delimiter.
source validate checks every declared skill, including replaced or excluded
defaults and skills in unselected profiles. A disagreement produces
SKILL_INVOCATION_MISMATCH, naming the skill and both effective values.
Discovery guidance
Section titled “Discovery guidance”format: repo-standards/v2name: project-documentationdescription: Documentation for maintained projectsrequires: { repo-standards: "<validated CLI SemVer range>" }defaults: declarations: project-documentation: kind: repository guidance: guidance/documentation.md rules: rules/documentation.md discovery: guidance/find-projects.mdprofiles: work: description: Documentation for all maintained projects declarations: {}Replace the compatibility placeholder with the CLI SemVer range actually tested,
and supply the referenced files. rules/documentation.md states what the
discovered documentation must keep satisfying, such as documenting real
commands. guidance/documentation.md is the adoption guidance: how to assess
or adapt project content during the run, such as preserving useful facts while
moving them. guidance/find-projects.md describes where that guidance applies: for
example, evidence of maintained projects including projects missing READMEs, and
criteria for distinguishing fixtures, generated output, and organizational
directories. Discovery guidance is prose that an agent or person interprets.
A declaration may also name a discovery script that
drafts the proposal; the prose remains valid with or without one.
A source-resolved discovery declaration has a discovery reference and no
targets; this is unresolved scope, not an empty or whole-repository entitlement.
Project discovery must eventually identify individual existing or intended file
paths, including migration sources, destinations, and link repairs. Semantic
coverage requires agent interpretation and adopter review. Discovered directory
trees, globs, root scope, protect fields, and subtracting exact descendants
from contextual trees are unsupported. Explicit directory scopes remain disjoint,
including from exact configuration beneath them.
Discovery scripts
Section titled “Discovery scripts”project-documentation: kind: repository guidance: guidance/documentation.md discovery: guidance/find-projects.md discovery-script: run: executable: node script: discovery/find-projects.mjs resources: [discovery/data] arguments: [] prerequisite: version-arguments: ["--version"] version: ">=24.0.0 <25.0.0 || >=26.0.0 <27.0.0" timeout-seconds: 60A declaration with discovery may name a discovery-script, declared like a
check without an id: run, prerequisite and
timeout-seconds have the same fields and rules. A discovery-script without
discovery is INVALID_DECLARATION. Source validation checks its fields and
references and never runs it. When discovery is required, inspection runs it
read-only to draft the declaration’s scope proposal and its open questions; it
never decides scope. The
discovery script protocol defines its
input, output and failures.
Optional discovery
Section titled “Optional discovery”hosting-settings: kind: repository guidance: guidance/hosting.md rules: rules/hosting.md discovery: discovery/hosting.md optional: trueA declaration with discovery may be marked optional: true when an
adopting project may have nothing it governs. Its confirmed scope may then be
no scope, which a scope proposal
marks with noScope. No scope differs from an empty scope:
- an empty scope makes the declaration repository-wide, so its rules cover every path, and its checks and fixes run;
- no scope installs none of its rules, is never repository-wide, and runs none of its checks or fixes. The adoption still assesses whether no project file belongs in its scope.
A proposal without noScope keeps its ordinary meaning for an optional
declaration too, so an optional declaration’s empty scope is still
repository-wide. Each update reviews the scope again: an update can give an
optional declaration a scope it had none of, which installs its rules and runs
its operations, or take its scope away, which removes its installed rules and
leaves project content in place.
optional must be true. On repository guidance with explicit targets it
fails with INVALID_DECLARATION, and on a file or a skill with
UNKNOWN_FIELD. Only discovered scope can be no scope.
Paths and ownership
Section titled “Paths and ownership”Source and target paths use repository-relative forward-slash syntax. Absolute
paths, drive prefixes, backslashes, control characters, empty components, .
and .. components are rejected. Write src/file.ts, not ./src/file.ts.
Targets also reject glob metacharacters (* ? [ ] { }). Paths are relative to
the source root or future adopting-project root, never the YAML file’s section.
All referenced files, directory ancestors, and whole skill/resource trees must
exist and contain only regular files and directories, with no symbolic links.
The source root and standards.yaml cannot themselves be symbolic links.
Root license entries and their contents retained by adoption are selected
material too and cannot contain symbolic links. Entries may be files or
directories. Their root names match LICENSE or LICENCE case-insensitively,
optionally followed by a dot or hyphen suffix.
Unreferenced source files are outside validation’s selected material. Targets
need not exist in the standards repository; adopting-project symlink and
ownership checks belong to inspection and adoption.
Within each resolved profile, no explicit target can equal, contain, or be contained
by another target, including two entries of one repository declaration.
Comparison also catches case-insensitive and Unicode-normalized collisions.
Product state (.repo-standards), every system skill target
(.agents/skills/repository-standards, .agents/skills/author-standards,
and .agents/skills/adopt-repository-standards)
and its skill link
(.claude/skills/<name>), Git metadata (.git), and their ancestors and descendants are reserved targets.
These restrictions apply to exact files, contextual files, and repository
guidance as well as skills, using the same case-folded and Unicode-normalized
comparison. Validation checks defaults and every profile, including profiles
other than the one selected for inspection.
Reservation applies within the standards format; it does not manage unrelated
global skill installations. Adoption installs the repository-standards
system skill matched to the project’s exact CLI pin. It
does not automatically install the standalone author-standards or
adopt-repository-standards skills or change runtime ownership,
integrity baselines, or update behavior.
Checks and fixes
Section titled “Checks and fixes”Every operation requires all of the following fields:
checks: - id: headings run: executable: python3 script: defaults/checks/readme.py resources: [defaults/checks/data] arguments: ["--strict", "two words", ""] prerequisite: version-arguments: ["--version"] version: ">=3.12.0 <4.0.0" timeout-seconds: 60run and prerequisite are mappings with exactly the fields shown.
executable identifies one command name or executable path with this syntax:
- Allowed characters are ASCII letters, digits,
.,_,+,-, and/. - The value cannot begin with
-. Use an explicit path such as./-wrapperfor an executable whose basename starts with a hyphen. /separates path components; a leading/denotes an absolute path. Empty components elsewhere, a trailing/, and basenames.or..are rejected. Directory components.and..are allowed.
Examples: python3, clang++, /usr/bin/python3, ./tools/checker, and
../tools/checker. This explicit character set rejects shell expressions,
quoting, whitespace, controls, and non-ASCII executable spellings. Executable
paths refer to installed tools on the adopting machine; they are not retained
source paths. Relative executable paths resolve from the adopting-project root.
The value is preserved literally and is not looked up or run during source
validation. A syntactically valid executable may be unavailable; adoption’s
prerequisite checking reports that separately.
script must reference a regular source file.
resources explicitly lists any additional source files or whole directory
trees; an empty list is valid. arguments and version-arguments are literal
string lists; empty lists and empty string arguments are valid. NUL bytes
cannot occur in strings. The prerequisite version is a nonempty npm SemVer
range. timeout-seconds is a positive safe integer.
Adoption invokes the executable directly with the retained script path followed by literal arguments, from the adopting-project root. No shell expansion is applied to arguments. Scripts are trusted code; resources describe retention and do not restrict host or network access. Fixes must be safe to repeat; checks must not mutate project content. A fix that would overwrite an existing setting holding a different value asks for the maintainer’s confirmation instead, unless its request allows overwriting. See the public script protocol for the versioned input/result protocol and execution rules. Source validation does not execute these operations.
Remote setup
Section titled “Remote setup”A fix that changes the hosting platform’s settings, rather than project files,
can declare itself remote setup with an optional remote-setup mapping. It
holds exactly one field, probe: a readiness probe declared like a check,
with exactly run, prerequisite, and timeout-seconds, validated as above,
and no id; the probe belongs to its fix.
fixes: - id: labels run: executable: gh script: fixes/labels.sh resources: [fixes/labels.json] arguments: [] prerequisite: version-arguments: ["--version"] version: ">=2.40.0" timeout-seconds: 60 remote-setup: probe: run: executable: gh script: probes/labels.sh resources: [] arguments: [] prerequisite: version-arguments: ["--version"] version: ">=2.40.0" timeout-seconds: 30Only fixes take remote-setup; on a check it is an unknown field. Inspection
runs the probe read-only before anything is written, and the adopter can defer
a remote setup that is not ready and complete adoption without it; see
remote setup and the probe’s
protocol. The probe’s script and
resources are selected material, retained like an operation’s. Remote setup
names no platform: the probe states what readiness means, such as a reachable
remote, a signed-in tool, or a sufficient role.
Results and diagnostics
Section titled “Results and diagnostics”Exit status is 0 for a valid source, 1 for source validation errors, and 2
for unsupported CLI usage. --help and --version are available. Human success
output lists profiles; human errors go to stderr as
file:line:column [CODE] message (path).
With --json, stdout is one JSON object, and expected validation failures do
not write stderr. A successful report contains valid: true, errors: [],
normalized root source metadata, and profiles, keyed by profile name. Each
profile has its description, its platforms, its offered check-locations, and the complete source-resolved
declarations array, which holds the declarations of every platform.
Declarations include their id, any platform and check-locations filter, and explicit operation checks and
fixes arrays; a remote setup fix keeps its remote-setup probe.
The source retains its authored format identity. A successful report also includes
scope.verified describing the source-owned facts checked, scope.limitations
explaining project-specific limits, and scope.discoveryRequired, a mapping of
all profile names to their active discovery declaration IDs (empty lists for
profiles without discovery). Human output presents these same facts and limits.
Validation verifies every profile’s schema, references (including guidance, discovery guidance and rules files), operations, identities, reservations, and all determinable explicit-target conflicts. It cannot establish concrete scope safety or semantic completeness in an unfamiliar adopting project, even when all explicit source targets are valid. Excluded discovery declarations do not require project discovery; their source references are still validated like every other default reference.
A failed report contains valid: false, errors, and profiles: {}. Invalid
selections are never offered as resolved results. Each diagnostic contains a
stable code, explanatory message, absolute file, one-based line and
column, and an RFC 6901 JSON-pointer path into the YAML. Conflict errors
also identify profile, including conflicts inherited from defaults. Missing
fields point to their containing mapping; unreadable root documents use 1:1
and an empty path. Independent errors are collected across all profiles;
structurally invalid YAML may limit what can be determined.
| Code | Meaning |
|---|---|
SOURCE_READ | Source document or referenced material cannot be read |
YAML_SYNTAX | Invalid YAML, unsupported tag, or multiple documents |
YAML_STRUCTURE | Unresolved/recursive alias or YAML expansion/depth limit |
DUPLICATE_IDENTITY | Duplicate YAML key, operation ID, or platform of a profile |
UNKNOWN_FIELD | Field outside the author schema |
REQUIRED_FIELD | Required field omitted |
INVALID_TYPE | Wrong mapping, list, scalar, or string type |
INVALID_FORMAT | Format identity other than repo-standards/v2 |
INVALID_VERSION | Malformed SemVer range |
INCOMPATIBLE_CLI | Running CLI does not satisfy the source range; the message recommends an open-ended minimum |
EMPTY_PROFILES | No complete named profile |
UNSUPPORTED_PLATFORM | A profile or declaration names a platform this CLI does not support |
UNSUPPORTED_CHECK_LOCATION | A check-locations array names an unsupported value |
EMPTY_CHECK_LOCATIONS | A profile or declaration has an empty check-locations array |
EMPTY_PLATFORMS | A profile’s platforms list is empty |
INVALID_ID | Declaration, skill, or operation identity is malformed |
INVALID_DECLARATION | Unknown kind, file without exactly one content mode, repository guidance without exactly one scope mode, or a discovery script without discovery |
SKILL_INVOCATION_MISMATCH | Skill’s Claude Code and Codex invocation settings disagree; message names the skill and both effective values |
INVALID_EXCLUSION | Invalid exclusion value, level, or default identity |
INVALID_EXECUTABLE | Executable violates the documented name/path syntax |
INVALID_TIMEOUT | Timeout is not a positive safe integer |
EMPTY_TARGETS | Repository guidance has no targets |
UNSAFE_PATH | Path can escape its root or uses unsupported path syntax |
MISSING_REFERENCE | Referenced file or directory does not exist |
REFERENCE_TYPE | Referenced entry has the wrong filesystem type |
SOURCE_SYMLINK | Source document or selected material contains a symlink |
RESERVED_NAME | An author tries to supply a product-owned system skill, or names a declaration with rules readme |
RESERVED_TARGET | Target overlaps reserved storage |
TARGET_OVERLAP | Two resolved targets that can apply on one platform and check location overlap, including folded collisions |
Alice’s complete example
Section titled “Alice’s complete example”The executable Alice fixture uses the
accepted architecture example verbatim. Its work profile replaces agent
guidance, inherits README guidance, the review skill, and source-layout
guidance, and excludes contribution guidance. Exclusion leaves the future
adopting project’s employer-owned CONTRIBUTING.md outside governance.
The example’s Python check reads the public operation input and checks README headings. It reports structural evidence; the agent separately assesses whether commands and explanations are useful for the actual project. See Author workflow for validation, publication and evolution.