Groundrule

Groundrule

Your engineering standards, taught to every coding agent and checked on every PR.

Write a standard once, as a small YAML file in git. Groundrule:

• teaches your coding agents. It generates AGENTS.md, CLAUDE.md, Cursor rules, and Copilot instructions containing only the standards that apply, without touching what you wrote by hand. An MCP server and hooks let Claude Code, Codex, Cursor and Copilot follow action policies before each tool call and check their own changes before they finish.
• checks the code. It runs locally and in CI against your changes or the whole repository, with deterministic checks (files, patterns, dependencies, imports, layout, metrics, change sets), Semgrep, and optional AI checks on the Groundrule platform.
• tells you why. Every finding names the standard, shows the evidence, says how to fix it, and labels whether it came from a deterministic check or AI.

Everything in this repository works offline and without an account. The Groundrule platform adds a shared rulebook, staged rollout, hosted checks and a compliance report on top of it.

Status: 0.x. Groundrule checks its own repositories with it. The document format is groundrule.dev/v1alpha1 and may still change before 1.0; changes are announced in Discussions.

See it in 60 seconds

Quick start

Thirty seconds, no account, nothing leaves your machine:

npx @groundrule/cli init      # detects your stack, picks packs, writes .groundrule/config.yaml

npx @groundrule/cli sync # writes AGENTS.md / CLAUDE.md / Cursor / Copilot instructions npx @groundrule/cli check # checks your uncommitted changes

 groundrule check · 11 standards · 2 files changed

✕ TS-003 No eval or new Function BLOCKER · deterministic (regex) src/app.ts:3 eval or new Function in application code 3: return eval(input); → Parse the input instead: JSON.parse, a schema, or a lookup table of allowed operations. → groundrule explain TS-003

Failed ✓ 7 passed ✕ 1 failed ◇ 2 guidance · 0.1s

A standard

apiVersion: groundrule.dev/v1alpha1

kind: Standard metadata: id: DEP-008 title: Use the platform HTTP client type: forbidden-tech owner: team:platform spec: severity: warning requirement: Backend services must use @acme/http-client for outbound HTTP calls. examples: forbidden: ["import axios from 'axios'"] checks:

• evaluator: dependencies forbid: [axios, got, node-fetch] allowInstead: ["@acme/http-client"]

More in examples/foundation.

Commands

Exit codes: 0 passed, 1 failed, 2 configuration or usage error.

Using the Groundrule platform (optional)

Everything above works offline. If your organization manages its standards on the Groundrule platform, connect a repository instead of listing packs:

npx @groundrule/cli login               # approve this computer in your browser

npx @groundrule/cli init --org acme # writes platform: { org: acme } to .groundrule/config.yaml npx @groundrule/cli sync # your organization's rules, with every customization

groundrule scan --upload shares a scan with your organization so it can see which rules fit each repository. It also imports what you already have as proposals: instructions from AGENTS.md, CLAUDE.md, Cursor, and Copilot files; ESLint, Biome, Ruff, golangci-lint, Checkstyle, PMD, and tsconfig settings that match catalog rules; CODEOWNERS; and the architecture the code already keeps, as proposed boundary rules with the files that would fail each today (RFC 0011; use --no-import to leave these out). Reports contain counts and at most three one-line, redacted snippets per rule (none for security rules, none at all with --no-snippets); --json shows exactly what would be sent. When uploading, the scan also tests your organization's own rules that have checks, drafts included, so you see their impact before publishing them.

groundrule check --upload sends the result to your organization as a compliance record (RFC 0007): which rules were in effect (as a digest anyone with the same rules can recompute), each rule's version, rollout stage and whether it could fail the change, the exceptions that applied, and which coding agents the change's commits declare, from Co-Authored-By trailers and bot authors (counts only; never commit messages or email addresses). Agent counts are a declaration, not proof; leave them out with --no-authorship.

With a signing key in CI (groundrule keys generate, then the private key as GROUNDRULE_SIGNING_KEY), every uploaded run is signed with Ed25519 (RFC 0008); groundrule verify proves later, offline, that a run wasn't altered. The signature covers everything but code snippets. In GitHub Actions, --sigstore signs with the job's own identity instead of a key (RFC 0009, needs id-token: write; opt-in, since the identity and the result's hash go to Sigstore's public log).

What each command takes from the platform depends on the rule's rollout stage: sync writes rules at Teach, Advise, and Enforce into your agent files; check runs Enforce rules as set and Advise rules as warnings. Rules your repository defines in .groundrule/standards/ still apply. In CI, set GROUNDRULE_TOKEN to a token from Settings → API tokens. Sign-ins are saved in ~/.config/groundrule/credentials.json, readable only by you.

Coding agents (MCP)

groundrule mcp is a Model Context Protocol server (stdio) with four tools:

• list_standards: the rules in effect in the repository, so the agent follows them. Works offline.
• rules_for: the rules that name the files the agent is about to change (by path or language), blocking first, with how to comply (ADR 0010). The server's instructions tell the agent to call it before editing a file; rules that apply everywhere stay in the agent file. Works offline.
• check: the same check CI runs, on the agent's uncommitted changes (or since a base ref, or all files). It lists only what the change introduced, with where and how to fix it, so the agent fixes it before it finishes. Works offline. In a repository connected to its workspace, the counts per rule are reported to the workspace (see below).
• propose_rule: when you correct your agent and say (or agree) that it should apply to everyone, it proposes the rule to your organization's review inbox, with where it came up. Nothing changes until a reviewer accepts it. Needs a connected repository and groundrule login.

Add it to your agent once per repository or user:

claude mcp add groundrule -- npx -y @groundrule/cli mcp          # Claude Code

{ "mcpServers": { "groundrule": { "command": "npx", "args": ["-y", "@groundrule/cli", "mcp"] } } }

The JSON form goes in .cursor/mcp.json for Cursor, .vscode/mcp.json for VS Code (as servers), or your agent's MCP settings. Proposals carry the rule, your reason, and a file and line if given; nothing else from the repository is sent.

Hooks: before each action, and when the agent finishes

groundrule hooks adds two hooks to the agent's project settings. A before-tool hook decides what the agent is about to do against your action policies, and a stop hook runs the check every time the agent finishes a task, whether or not it remembered to:

npx @groundrule/cli hooks        # Claude Code, plus Codex, Cursor and Copilot if the repository uses them

Existing settings and hooks are kept. Without an action policy the before-tool hook answers nothing, and without a Groundrule configuration neither hook does anything. The stop hook asks once per turn, so an agent that can't fix something isn't kept going forever. Commit the files so every developer's agent runs them; --remove takes the hooks out again.

What agents may do (action policies)

A standard says what the code must be. An action policy (RFC 0017) says what the agent may *do*: which shell commands, edits, reads, fetches and MCP calls it may run on its own (allow), which a person confirms first (ask, the default), and which are refused (deny). It lives next to your standards, with the same identity, scope, owner, exceptions and rollout stages:

apiVersion: groundrule.dev/v1alpha1

kind: ActionPolicy metadata: id: ACT-001 title: Never force-push spec: severity: blocker effect: deny requirement: Never force