How Groundrule works

The whole product is built from about a dozen ideas. Once you know them, every screen and command reads plainly. The glossary has the short definitions; this page shows how they fit together.

Standards

A standard is one engineering rule, written so that both people and coding agents can follow it. Examples: “Represent monetary amounts as integer minor units, never floats”, or “Do not interpolate untrusted event data into GitHub Actions scripts”.

Every standard has:

Part	What it is	Example
ID	A short, stable name used everywhere	ACME-004, SEC-001
Title	One line	Route all Stripe calls through the gateway
Requirement	The rule itself, in plain words	Never import stripe outside src/payments/gateway.ts…
Severity	How serious a violation is: blocker, warning, advisory, or info	blocker
Type	What kind of rule it is, such as requirement, prohibition, forbidden-tech, or guidance	prohibition
Scope	Where it applies: file paths, languages, frameworks	src/**, TypeScript
Examples	What to do and what not to do, as code	✓ createPaymentIntent(…) ✕ new Stripe(…)
Checks	Optional machine checks (see below)	a regular expression
Rationale, references	Why the rule exists, plus links such as OWASP or CWE	CWE-798

Standards are stored as YAML in the open rule format. The dashboard edits the same documents the CLI reads.

Guidance and checks

A standard reaches your code in two ways:

• Guidance. The rule’s wording and examples are written into the instructions every coding agent reads: AGENTS.md, CLAUDE.md, Cursor rules, Copilot instructions. Every standard is guidance.
• Checks. Some standards also carry a check that a machine can run on your code. For example: a regular expression that must not match, files that must or must not exist, dependencies that must not be added, or files that must change together. Checks are deterministic: the same code gives the same result, with no AI involved.

Some rules can only be guidance (“Ask before destructive or irreversible operations”). Others are best as checks (“No private keys in the repository”). The dashboard shows which: Agent guidance or Deterministic.

Packs and the catalog

A pack is a maintained set of standards for one topic, such as security-baseline, typescript-node, react, docker, github-actions, or agent-hygiene. The catalog is every standard in every pack: 13 packs and about 170 standards today. Each catalog standard comes with examples, references, compliance mappings (SOC 2, ISO 27001, OWASP ASVS, PCI DSS, HIPAA, NIST SSDF), and a noise rating that says how often it flags code that is actually fine.

You don’t fork a pack. You adopt it, and then tune each rule: turn it off with a reason, change its severity, scope or wording, or set its stage. When Groundrule updates the pack, the updates still reach you, and your changes stay on top. The dashboard shows yours vs upstream for every rule you changed.

Your rulebook

The rulebook is everything in effect for your organization: the packs you adopted, with your changes, plus the standards your team wrote. One rulebook serves every repository, every coding agent and every check.

Severity and stage

Two separate settings decide what a rule does:

• Severity says how serious a violation is.
• Stage says how far the rule has been rolled out.

Stage	In agent instructions	In groundrule check
Observe	No	Runs silently; results are only recorded
Teach	Yes	Runs silently
Advise	Yes	Findings are shown, but never fail the check
Enforce	Yes	Findings count at the rule’s severity; by default, blockers fail the check

Each pack rule starts at the stage Groundrule recommends for it, shown as Starts at Teach or Starts at Enforce in the catalog. Low-noise checks can start at Enforce; anything that might flag existing code starts earlier. Your own standards start at the stage you choose when you publish them. You move a rule forward when you trust it. Rollout stages covers this in detail.

Scope: organization, team, repository

A rule’s settings can be set at three levels:

1. Organization. The default for every repository.
2. Team. For the repositories a team owns, such as Payments.
3. Repository. For one repository.

A team or repository can be stricter than the organization, but never looser: for example, a higher severity or a later stage. To loosen a rule for one place, you change the organization’s setting, or record an exception in the repository. Teams also own categories: proposals about payments rules go to the Payments team’s reviewers.

Proposals and the inbox

Anything that might become a rule arrives as a proposal:

• An instruction found in a repository’s agent files, or in a document.
• A tool setting, such as an ESLint rule that maps to a catalog standard.
• An owner suggestion, from a CODEOWNERS file.
• A rule a developer or coding agent proposed from the CLI or the editor.
• A recurring request from pull-request reviews.

Proposals wait in the inbox, grouped by category and routed to the category’s owners. Accepting a proposal does the real thing: it creates a standard, adopts a catalog rule, or assigns an owner. Rejecting one records why. Proposals written by AI are labelled AI, with a confidence and a citation of where they came from.

Evidence and promotion

When a repository is scanned, every rule is run against it, including rules not yet at Enforce. The results become evidence: for each rule, which repositories pass, how many findings there are, and what moving it to a later stage would flag. You can see the evidence before you change anything.

When a rule has had no findings for long enough (7 days, or 14 before Enforce) across at least two scans of each repository, Groundrule suggests a promotion to the next stage. You promote it with one click, or hide the suggestion for a while.

How a rule travels

Here is one rule, start to finish:

1. A review comment on a pull request says “we never call Stripe directly, use the gateway”. Someone writes /groundrule rule in reply.
2. The rule arrives in the inbox as a proposal, citing the comment. The Payments owners see it first.
3. An owner accepts it, and Draft with AI turns it into a full standard: a regular expression that allows only src/payments/gateway.ts, plus examples that pass the check.
4. The standard is published at Teach. The next groundrule sync writes it into AGENTS.md, CLAUDE.md and the Cursor rules, so every coding agent knows it.
5. Scans show it is clean everywhere for two weeks. Groundrule suggests Enforce, and an owner accepts.
6. From then on, groundrule check in CI fails any change that adds a direct Stripe call.