Skip to content

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.

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.

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.

FieldValue
formatrepo-standards/v2
nameNonempty descriptive string
descriptionNonempty descriptive string
requiresMapping containing only repo-standards, a nonempty npm SemVer range compatible with the running CLI; declare an open-ended minimum such as >=7.0.0
defaultsMapping containing only declarations, a mapping of IDs to declarations (possibly empty)
profilesNonempty mapping of profile names to complete profiles

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.

defaults:
declarations:
ci-workflow:
kind: file
platform: github
target: .github/workflows/check.yml
exact: content/check.yml
profiles:
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.

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.yml

Platform 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.

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:

FormRequired fields
Exact filekind: file, one target, and exact referencing a regular source file
Contextual filekind: file, one target, and guidance, its adoption guidance, referencing a regular source file
Exact skillkind: skill, name, and source referencing a whole directory containing a regular SKILL.md
Repository guidancekind: 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.

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.

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.

format: repo-standards/v2
name: project-documentation
description: Documentation for maintained projects
requires: { repo-standards: "<validated CLI SemVer range>" }
defaults:
declarations:
project-documentation:
kind: repository
guidance: guidance/documentation.md
rules: rules/documentation.md
discovery: guidance/find-projects.md
profiles:
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.

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: 60

A 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.

hosting-settings:
kind: repository
guidance: guidance/hosting.md
rules: rules/hosting.md
discovery: discovery/hosting.md
optional: true

A 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.

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.

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: 60

run 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 ./-wrapper for 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.

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: 30

Only 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.

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.

CodeMeaning
SOURCE_READSource document or referenced material cannot be read
YAML_SYNTAXInvalid YAML, unsupported tag, or multiple documents
YAML_STRUCTUREUnresolved/recursive alias or YAML expansion/depth limit
DUPLICATE_IDENTITYDuplicate YAML key, operation ID, or platform of a profile
UNKNOWN_FIELDField outside the author schema
REQUIRED_FIELDRequired field omitted
INVALID_TYPEWrong mapping, list, scalar, or string type
INVALID_FORMATFormat identity other than repo-standards/v2
INVALID_VERSIONMalformed SemVer range
INCOMPATIBLE_CLIRunning CLI does not satisfy the source range; the message recommends an open-ended minimum
EMPTY_PROFILESNo complete named profile
UNSUPPORTED_PLATFORMA profile or declaration names a platform this CLI does not support
UNSUPPORTED_CHECK_LOCATIONA check-locations array names an unsupported value
EMPTY_CHECK_LOCATIONSA profile or declaration has an empty check-locations array
EMPTY_PLATFORMSA profile’s platforms list is empty
INVALID_IDDeclaration, skill, or operation identity is malformed
INVALID_DECLARATIONUnknown kind, file without exactly one content mode, repository guidance without exactly one scope mode, or a discovery script without discovery
SKILL_INVOCATION_MISMATCHSkill’s Claude Code and Codex invocation settings disagree; message names the skill and both effective values
INVALID_EXCLUSIONInvalid exclusion value, level, or default identity
INVALID_EXECUTABLEExecutable violates the documented name/path syntax
INVALID_TIMEOUTTimeout is not a positive safe integer
EMPTY_TARGETSRepository guidance has no targets
UNSAFE_PATHPath can escape its root or uses unsupported path syntax
MISSING_REFERENCEReferenced file or directory does not exist
REFERENCE_TYPEReferenced entry has the wrong filesystem type
SOURCE_SYMLINKSource document or selected material contains a symlink
RESERVED_NAMEAn author tries to supply a product-owned system skill, or names a declaration with rules readme
RESERVED_TARGETTarget overlaps reserved storage
TARGET_OVERLAPTwo resolved targets that can apply on one platform and check location overlap, including folded collisions

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.