Groundrule

Groundrule

[npm] [CI] [License] [Docs]

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

[Groundrule 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.yamlnpx @groundrule/cli sync      # writes AGENTS.md / CLAUDE.md / Cursor / Copilot instructionsnpx @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/v1alpha1kind: Standardmetadata:  id: DEP-008  title: Use the platform HTTP client  type: forbidden-tech  owner: team:platformspec:  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 browsernpx @groundrule/cli init --org acme     # writes platform: { org: acme } to .groundrule/config.yamlnpx @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/v1alpha1kind: ActionPolicymetadata:  id: ACT-001  title: Never force-pushspec:  severity: blocker  effect: deny  requirement: Never force-push. Ask the developer, or push to a new branch.  when:    actions: [shell]    commands: ["git push --force*", "git push -f*"]

The before-tool hook decides it in the agent's own permission flow, on your computer, in milliseconds, and the reason names the policy and what to do instead. A matching exception in .groundrule/exceptions.yaml lifts it; a wrong decision never holds up the agent, because any problem means no decision. groundrule:packs/agent-actions ships ten policies to start from: force-pushes, history rewrites, hook bypass, piping downloads into a shell, publishing, infrastructure changes, elevated privileges, deleting outside the repository, secret files and CI workflows. Agent files get a section "What you may not do alone", so an agent without the hook knows too.

What the workspace learns. In a repository with platform: in its config, when this computer is signed in, the hook and the MCP check tool send the workspace a report after the agent has its answer (RFC 0012): the agent, which rules found something and how many times, how many files and rules were checked, and whether the agent was stopped. Never a path, a line, a snippet, or anything the agent or you wrote. It is sent with a two-second timeout and every failure is ignored, so it can't slow the agent or change the check. The workspace uses it to show how much is caught before a commit exists. platform.reports: none turns it off; groundrule doctor says which applies. Offline repositories send nothing.

Checks

Packs

groundrule packs lists the bundled packs (security, TypeScript/Node, React, Python, Java/Spring, Go, Docker, Kubernetes, Terraform, GitHub Actions, HTTP APIs, testing, AI agent hygiene, and what agents may do). Your organization's own packs work the same way: github:your-org/engineering-standards//packs/backend@v1.

GitHub

Metricall-AI-Lab/groundrule-action@v1 checks every pull request, writes a job summary, and uploads findings to code scanning. Source in action/.

Development

pnpm installpnpm check

See CONTRIBUTING.md. Groundrule checks itself: see .groundrule/.

License

Apache-2.0. "Groundrule" is a trademark; see GOVERNANCE.md.