Developer docs

Configuration

Developers

Each repository has one configuration file, .groundrule/config.yaml. It says where the repository’s standards come from, which agent files to write, and how check decides what fails. This page covers every field, its default, and its allowed values, with a complete example for a connected repository and for an offline one.

npx @groundrule/cli init writes the file for you. See init.

The file at a glance

Field	Type	Default	Description
`apiVersion`	string	(required)	Always `groundrule.dev/v1alpha1`.
`kind`	string	(required)	Always `Config`.
`platform`	object		Take standards from your workspace on Groundrule.
`extends`	list	`[]`	Packs or standard folders this repository inherits. Ignored when `platform` is set.
`standards`	list of globs	`["standards/*/.yaml"]`	The repository’s own standard files, relative to `.groundrule/`.
`tags`	list of strings	`[]`	Tags that standards can target with `scope.tags`.
`targets`	list	`["agents-md"]`	The agent files `sync` writes.
`enforcement`	object	See below	What `check` evaluates and what fails it.
`overrides`	map	`{}`	Per-standard changes: turn off, or change severity.

Unknown fields are errors, reported with the file, line and field: for example .groundrule/config.yaml:12:1 enforcment: Unrecognized key: "enforcment". Commands that read the config stop with exit code 2 until you fix it.

Exceptions aren’t in this file. They live in .groundrule/exceptions.yaml. See Overrides and exceptions.

platform

Connects the repository to your workspace on Groundrule. With platform set, sync, check, standards, explain, doctor and the MCP server read your workspace’s rulebook: the packs it adopted, its own standards, and every setting, at each rule’s stage.

Field	Type	Required	Default	Description
`org`	string	Yes		The workspace’s URL name, for example `acme-payments`. Lowercase letters, digits and dashes, up to 48 characters.
`url`	URL	No	`https://app.groundrule.dev`	The Groundrule address. `https://`, or `http://` for localhost only.
`repository`	string	No	The `origin` git remote, as `owner/name`	The name registered in Groundrule, for example `acme/checkout-api`. Up to 200 characters.

platform:
  org: acme-payments

How the address is chosen, first match wins:

a command’s --url option;
the GROUNDRULE_URL environment variable (empty counts as unset);
platform.url;
https://app.groundrule.dev.

The CLI needs a sign-in for the workspace: groundrule login, or GROUNDRULE_TOKEN in CI. See Environment and files.

The repository name selects team and repository settings. When the workspace doesn’t know the repository, the organization’s settings apply, with a warning:

! .groundrule/config.yaml  acme/checkout-api isn't registered in acme-payments, so the organization's rules apply. Add it under Teams → Repositories to use its team's settings.

What changes with platform set:

Field	Effect
`extends`	Ignored, with a warning: Ignored because `platform` is set: your organization's rulebook decides the packs.
`standards`	Still loaded. If one has the same ID as an organization rule, the organization’s version applies and the CLI warns.
`overrides`	Apply to the repository’s own standards only. An override for an organization rule is ignored, with the warning `<ID> comes from the platform; change it in Groundrule (for this repository or its team), not in config.`
`targets`, `tags`, `enforcement`	Apply as usual.

Which rules each command uses:

Command	Rules from the workspace
`sync`	Teach, Advise and Enforce.
`check`	Advise, with blockers reported as warnings, and Enforce.
`standards`, `explain`, MCP `list_standards`	Teach, Advise and Enforce.

Rules at Observe, turned-off rules and drafts are never sent to the CLI. scan --upload tests them separately. See Rollout stages.

extends

Where the repository’s inherited standards come from. Each entry is a reference:

Form	Example	What it is
`groundrule:packs/<name>`	`groundrule:packs/security-baseline`	A pack bundled with the CLI. `@<version>` is accepted but not used yet.
`./<path>` or `../<path>`	`../packs/backend`	A pack or folder in this repository, relative to `.groundrule/`.
`github:<owner>/<repo>//<path>`	`github:acme-payments/engineering-standards//packs/backend`	A path in a GitHub repository, on its default branch. Fetched on every run.
`github:<owner>/<repo>//<path>@<ref>`	`github:acme-payments/engineering-standards//packs/backend@v1`	The same, pinned to a tag, branch or commit. Cached; `sync --refresh` fetches it again.

extends:
  - groundrule:packs/security-baseline
  - groundrule:packs/typescript-node
  - github:acme-payments/engineering-standards//packs/backend@v1

A reference can point to a folder with a pack.yaml, to a pack.yaml file, or to a folder of standard files (every .yaml and .yml file in it is loaded). Packs can extend other packs.

Error	Cause
`Use ./path, github:owner/repo//path[@ref], or groundrule:packs/name[@version]`	The reference has the wrong form.
Unknown pack "groundrule:packs/<name>". Run `groundrule packs` to list them.	No bundled pack has that name.
`"<reference>" does not exist (resolved to <path>).`	A local path that doesn’t exist.
`Cannot fetch github:<owner>/<repo>@<ref>. Check the name, the ref, and your git access.`	The repository or ref can’t be cloned.
`Pack extends itself (circular extends).`	Two packs extend each other.

To change an inherited standard, use overrides. Redefining its ID in your own files is an error.

standards

Globs for the repository’s own standard files, relative to the .groundrule/ folder.

standards:
  - standards/**/*.yaml

The default loads every .yaml file under .groundrule/standards/. Files such as EXAMPLE-001.yaml.sample don’t match, so they aren’t loaded. Keep other YAML, such as Semgrep rules, outside the matched folders. The format of each file: The rule format.

targets

The agent files sync writes.

Value	Writes
`agents-md`	A managed block in `AGENTS.md`.
`claude-code`	A managed block in `CLAUDE.md` (an `@AGENTS.md` import when `agents-md` is also a target).
`cursor`	`.cursor/rules/groundrule.mdc` and one file per path-scoped group.
`copilot`	A managed block in `.github/copilot-instructions.md`, and `.github/instructions/groundrule-*.instructions.md` per path-scoped group.

targets:
  - agents-md
  - claude-code
  - cursor

Details: Agent instruction files.

enforcement

How check decides what to evaluate and what fails.

Field	Values	Default	Description
`scope`	`changed-lines`, `changed-files`, `all`	`changed-lines`	Which code `check` evaluates.
`legacy`	`report`, `ignore`, `enforce`	`report`	How violations that already existed (legacy) are treated.
`failOn`	`blocker`, `warning`, `none`	`blocker`	The lowest severity that makes `check` exit with `1`.

enforcement:
  scope: changed-lines   # check what a change touches: changed-lines | changed-files | all
  legacy: report         # existing violations: report | ignore | enforce
  failOn: blocker        # lowest severity that fails a check: blocker | warning | none

scope

Value	`check` without `--all`	A finding is new when
`changed-lines`	Reads the changed files.	It is on a line the change added or modified.
`changed-files`	Reads the changed files.	Its file was added, modified or renamed.
`all`	Reads every file, as with `--all`.	Always.

legacy

Value	Legacy findings
`report`	Counted on one line (`○ 2 legacy findings not introduced by this change (show with --verbose)`), never fail.
`ignore`	Left out of the results entirely.
`enforce`	Fail like new findings. Use `--verbose` to list them in the terminal.

failOn

Value	`check` exits with `1` on
`blocker`	New blocker violations.
`warning`	New blocker and warning violations.
`none`	Nothing. Findings are reported only.

A finding never fails check when it is a concern (below a check’s minConfidence) or when an exception covers it. In a connected repository, a blocker from a rule at Advise counts as a warning, so it fails only with failOn: warning. check --fail-on overrides failOn for one run.

overrides

Changes to individual standards in this repository, keyed by standard ID.

Field	Type	Description
`disabled`	boolean	`true` turns the standard off.
`severity`	`info`, `advisory`, `warning`, `blocker`	Replaces its severity.
`reason`	string	Why. Shown by `check`, `standards` and `explain`.

overrides:
  TS-001:
    disabled: true
    reason: Our CLI prints to the console on purpose.
  SEC-005:
    severity: blocker

An override for an unknown ID is a warning: Override for unknown standard NOPE-001. More: Overrides and exceptions.

Complete example: connected repository

# yaml-language-server: $schema=https://raw.githubusercontent.com/Metricall-AI-Lab/groundrule-oss/main/packages/spec/schemas/config.schema.json
apiVersion: groundrule.dev/v1alpha1
kind: Config

# Standards come from your organization on Groundrule: the packs it adopted,
# its own rules, and every customization, at each rule's rollout stage.
platform:
  org: acme-payments
  repository: acme/checkout-api      # optional; defaults to the origin remote

# Repository-only rules, in .groundrule/standards/
standards:
  - standards/**/*.yaml

tags: [backend, pci]

targets:
  - agents-md
  - claude-code
  - cursor

enforcement:
  scope: changed-lines
  legacy: report
  failOn: blocker

init --org acme-payments writes this file without the repository and standards lines, which have defaults. It writes url only for an address other than https://app.groundrule.dev.

Complete example: offline

# yaml-language-server: $schema=https://raw.githubusercontent.com/Metricall-AI-Lab/groundrule-oss/main/packages/spec/schemas/config.schema.json
apiVersion: groundrule.dev/v1alpha1
kind: Config

extends:
  - groundrule:packs/security-baseline
  - groundrule:packs/typescript-node
  - groundrule:packs/react
  - github:acme-payments/engineering-standards//packs/frontend@v3

tags: [frontend]

targets:
  - agents-md
  - claude-code
  - cursor
  - copilot

enforcement:
  scope: changed-lines
  legacy: report
  failOn: warning

overrides:
  TS-001:
    disabled: true
    reason: Storybook stories log on purpose; covered by ACME-012 instead.
  REACT-006:
    severity: blocker
    reason: Accessibility is a release requirement.

Offline, there are no stages: every standard in effect reaches agent files and is checked. See Use Groundrule without the platform.