Guides · Overview

One rulebook for your engineering team, read by every coding agent and checked on every change.

The problem it solves, how it works in four steps, what a team has after a week, how it differs from an AI reviewer or hand-written agent files, and what it never does. Ten minutes, no prior context needed.

10 minFor engineering leadership, tech leads and standard owners, developersChecked against the product on 16 October 2026All guides
§ 01the problem

Every team has rules. Where they live today is why agents break them.

Your rules live in three places. All three leak.

Money is stored in cents. Never call Stripe directly. Never log a session cookie. True in every team; written down almost nowhere an agent reads.

01.1

People's heads

New engineers learn the rules in code review, one comment at a time. The same comment is written a hundred times a year.

leaks: nothing scales it
01.2

A wiki or handbook

Written once, rarely read, never checked. Nobody knows which pages are still true.

leaks: nothing enforces it
01.3

Agent files

AGENTS.md, CLAUDE.md, .cursor/rules: copied between repositories, each slightly different, none enforced.

leaks: drift, repository by repository

Coding agents make the gap wider. An agent writes a lot of code, fast, and it follows only the rules it is given. If a rule is not in its instructions, the agent does not know it. If nothing checks the rule, nobody notices until review, or until production. Groundrule closes the gap at both ends: the rule reaches the agent before it writes, and a check catches what slipped through, on every change.

§ 02how it works

Everything downstream is generated from the rulebook, so agent files, checks and reviewer settings can never disagree.

Four steps. One rulebook.

The dashboard, the command-line tool and the coding agents all read the same rulebook. Each step is useful on its own.

02.1 · define

Start from packs, add your own

Groundrule maintains 15 packs, 183 rules: security baseline, TypeScript, Python, Java and Spring, Go, React, Docker, Kubernetes, Terraform, GitHub Actions, HTTP APIs, testing, architecture, agent hygiene. Adopt them rule by rule. Write your own in plain words; AI drafts the standard with examples and a tested check, and a person approves it.

02.2 · import

Bring in what already exists

A scan reads a repository's agent files, lint settings and CODEOWNERS, and the architecture the code already keeps (which modules never import which). Handbooks, PDFs, Notion and Confluence pages and pull-request reviews are read for rules too. Everything found becomes a proposal.

02.3 · review

Nothing changes until a person decides

Proposals wait in an inbox, routed to whoever owns each category. Accept, edit or reject. AI only ever drafts; it never changes the rulebook on its own.

02.4 · teach and enforce

Agents told first, changes checked after

groundrule sync writes the rules into every agent's instructions. Before an agent edits a file it is told the rules that name that file; when it finishes, a hook checks its work. groundrule check runs on laptops, in CI and on pull requests; every finding says which rule, the evidence, and the fix.

Rules move through stages, on evidence.

A rule cannot block anyone by surprise. It is measured first, then taught, then advised, and reaches Enforce only when an owner moves it there, which Groundrule suggests after the rule has been clean in your repositories for long enough.

Observe

Checked silently. You see what it would flag in your code today.

Teach

Written into agent instructions. Nothing is checked yet.

Advise

Findings are shown on pull requests but never block a merge.

Enforce

Findings count at the rule's severity. A blocker fails the check.

§ 03what you get

Six things a team has after its first week, each visible in the product today.

What a team has after a week.

Not a document. Agents that follow the rules, checks on every change, and the numbers to prove it.

  • One rulebookPacks maintained by Groundrule, your own standards, and settings per team and repository, in one place, versioned, with an owner for each category.
  • Agents that follow itAGENTS.md, CLAUDE.md, Cursor rules, Copilot instructions and CodeRabbit's configuration written from the rulebook and kept in step, in every repository. The rules for a file arrive just before the agent edits it.
  • Checks you can trustDeterministic checks (patterns, files, dependencies, imports, Semgrep) run locally, in CI and on pull requests. Each finding is labelled deterministic, static analysis or AI, so nobody mistakes a guess for a fact.
  • Evidence before enforcementSee what a rule would flag across every repository before it can block anyone, and promote it when the numbers say it is ready.
  • Proof of effectThe dashboard shows where violations are stopped: in the agent loop before a commit exists, on pull requests, and what is still on main. Three honest numbers, never added together.
  • Compliance evidenceA report per period: which rules were in effect, pass rates, exceptions used, and the SOC 2 and ISO 27001 controls each rule supports. Signed check results anyone can verify offline. Exportable as CSV.
§ 04how it differs

Groundrule is where the rules live. It writes them into the tools you already use, the reviewer included.

If you already use CodeRabbit, Cursor rules or a wiki.

Not another reviewer, not another place to write rules. The comparison that matters is where a rule lives and when it acts.

QuestionAI reviewer (CodeRabbit, Copilot review)Agent files by hand (Cursor rules, AGENTS.md)Wiki or handbookGroundrule
Where does the rule live?In the reviewer's config, per repositoryIn each repository, each copy differentOn a page nobody checksOne rulebook, written into all of them
When does it act?After the code is written, at reviewBefore, if the agent remembersNever, on its ownBefore the edit, when the agent finishes, in CI, on the pull request
Is the verdict reproducible?A model's opinion; varies run to runNo verdict at allNo verdict at allDeterministic checks, labelled; AI only where you ask, advisory and labelled
Can it block a merge?Noisy if it doesNoNoOnly rules you moved to Enforce, after evidence
Do you know the effect?Comment countsNoNoFlagged before commit, on pull requests, still on main, per rule
Does it see your code?Yes, every pull requestNoNoNo, unless you turn on hosted checks for a repository; then a sealed sandbox, deleted after each check
Can you keep it?Vendor configPlain filesPlain pagesOpen rule format and CLI (Apache-2.0); works offline with no account

Keep your reviewer. Groundrule writes CodeRabbit's .coderabbit.yaml and Copilot's organization instructions from the same rulebook, so the reviewer and the agents read the same rules, and sync --check in CI catches drift.

§ 05for each role

Leaders see effect. Leads own rules. Developers get told once, at the right moment.

What changes for each role.

The same rulebook, read from three seats.

05.1 · engineering leadership

One answer, one number

One answer to "what are our standards, and are they followed?", across every repository. A number you can repeat: how much was stopped before a commit existed, on pull requests, and what is still on main. Compliance evidence on demand. No surprise blocks: rules reach Enforce on evidence, by an owner's decision.

05.2 · tech leads and owners

Write it once, in plain words

AI drafts the standard and a tested check; you approve. An inbox of what your repositories and documents already say, routed to you by category. Per-rule evidence before you turn it on. Architecture rules without writing a glob: a scan proposes the boundaries the code already keeps.

05.3 · developers and agents

Three commands, then it stays current

Connect a repository with login, init and sync; the agent files write themselves. The agent hears the rules for a file right before it edits it, and checks its own work when it finishes. Every finding says which rule, the evidence, and the fix; groundrule explain says why. Propose a rule from the terminal when you correct an agent and it should apply to everyone.

§ 06what it never does

Deliberate limits, and they hold everywhere in the product.

Four things Groundrule never does.

Each one is a design decision, not a missing feature.

  • AI never changes your rulebook.It drafts rules, finds rules in documents, suggests checks and, if you turn it on, answers a question about a change. Every result is labelled AI with a confidence, and a person accepts it or not.
  • It does not upload your source code.Scans and checks send results: counts, which rules pass, one-line snippets you can turn off. The CLI works fully offline. The one exception is opt-in per repository: hosted checks read a pull request's code in a sealed sandbox with no network and delete it when the check ends.
  • It does not block anyone by surprise.A rule reaches Enforce only when an owner moves it there, and Groundrule suggests that only after the rule has been clean long enough.
  • It does not pretend AI is deterministic.AI checks are advisory, capped per run, cached, and never fail a change on their own. Deterministic checks are the ones that can.
§ 07in the box today

Working now. The security page lists what isn't, just as plainly.

What is in the box today.

Everything below is live. Where something isn't built, the product and the website say "not yet".

AreaWhat works todayWhere
Rulebook15 packs, 183 rules; your own standards; stages per organization, team and repository; owners; versions; exceptions that expire.Dashboard
AgentsAGENTS.md (Codex and any agent that reads it), CLAUDE.md, Cursor rules, Copilot instructions and organization instructions, CodeRabbit configuration; MCP server (local and hosted) with list_standards, rules_for, check, propose_rule; hooks for Claude Code, Codex, Cursor and Copilot that decide each tool call against action policies (allow, ask or deny) and run the check when the agent finishes; the rules for a file before Claude Code edits it.CLI, agents
ChecksPatterns, files, dependencies, imports (architecture), change sets, Semgrep; AI checks on hosted pull requests, advisory. Locally, in CI (GitHub Action, GitLab, any CI), posted on GitHub pull requests; hosted checks without CI for repositories you turn on.CLI, CI, GitHub
ImportsScans (agent files, lint settings, CODEOWNERS, architecture boundaries), documents (upload, Notion, Confluence, Google Docs), pull-request reviews, proposals from developers and agents.Inbox
EvidencePer-rule evidence across repositories, promotions, where violations are stopped, the compliance report with SOC 2 and ISO 27001 mappings and CSV, signed results (Ed25519 and Sigstore keyless) with offline verification.Dashboard, CLI
Not yetSingle sign-on and two-factor authentication, billing (pricing is announced), a SOC 2 report of our own.groundrule.dev/security
§ 08questions

The ones that come up first.

Questions.

Short answers; the documentation has the long ones.

What does it cost?

A Free workspace for small teams that never expires; Team and Business per active contributor, on groundrule.dev/pricing. The open-source CLI and the rule format stay free (Apache-2.0).

Which coding agents does it work with?

Any agent that reads AGENTS.md, including OpenAI Codex; Claude Code (CLAUDE.md); Cursor (.cursor/rules); GitHub Copilot (.github/copilot-instructions.md and organization instructions). Agents that speak MCP can list the rules, ask for the rules of the files they are about to change, check their work and propose rules. CodeRabbit reads the same rulebook through .coderabbit.yaml.

Do we have to use the platform?

No. The CLI works offline in one repository with no account: write standards as YAML, run sync and check. The platform adds one rulebook across repositories, teams and owners, the inbox and imports, evidence, promotions, hosted checks and AI. A repository connects with one line in its config.

Will it slow our agents or our CI?

Checks are deterministic and run in well under a second on a change. The before-tool hook decides an action in milliseconds from the rulebook already on disk, and any problem means no decision, never a stalled agent. The stop hook asks once per turn. A platform outage never fails a merge: results stand whatever happens to an upload.

Where is our data, and what do you keep?

Results, rules, proposals and the audit log, separated by workspace in the database itself. Never your code, archives or diffs. Secrets are redacted before anything is sent to a model. The documentation page What we store lists every record and how long it is kept.

Is it open source?

The kernel is: the rule format, the CLI, the checks, the packs and the MCP server, Apache-2.0, at github.com/Metricall-AI-Lab/groundrule-oss. The platform is the proprietary part.

§ 09 · sign-off

See it on your own repository.

The companion guide takes a team from nothing to agents that follow the rules and a check in CI, in about fifteen minutes. The offline path needs no account and takes two.