Five steps. One rulebook.
Define the rules, bring in the ones you already have, review them, teach them to every agent, and enforce them in stages. Each step is useful on its own, and nothing reaches a build until someone decides it should.
Your rulebook is the packs you adopt, tuned, plus the standards your team writes.
Start from proven standards, then make them yours.
One rulebook serves every repository and every agent. Upstream updates keep flowing underneath your changes.
- 13 packs, 171 standardsSecurity and supply chain, TypeScript, React, Python, Java and Spring, Go, Docker, Kubernetes, Terraform, GitHub Actions, HTTP APIs, testing and agent hygiene. Onboarding preselects the ones that fit your stack.
- Each standard is completeA requirement, the reason it exists, do and don't examples, how to fix it, CWE and OWASP references, compliance mappings, a noise rating, and the stage it should start at.
- Adopt, then tune, never forkTurn a rule off with a reason, raise its severity, narrow its scope or reword it. Each rule shows yours against upstream.
- Organization, team, repositoryA team owns its repositories and can be stricter than the organization, never looser.
fig. 01 · one rule, inherited down the tree
| TS-002 · No deprecated HTTP and UUID packages | Severity | Stage |
|---|---|---|
| Pack default | warning | Teach |
| Acme Payments | warning | Advise |
| Team Payments | blocker | Enforce |
| acme/checkout-api | blocker | Enforce |
A team can be stricter than the organization, never looser. Repositories inherit their team's settings.
Your repositories, documents and code reviews already hold most of your rulebook.
Bring in the rules you already have.
Nobody should write a rulebook from scratch. Groundrule finds what's already written down and turns it into proposals.
| Source | What becomes a proposal |
|---|---|
| Repository scan | Instructions in AGENTS.md, CLAUDE.md, Cursor and Copilot files; ESLint, tsconfig, Ruff and Checkstyle settings that match catalog rules; CODEOWNERS owners |
| Documents | Rules in PDF, Word, Markdown or pasted text, each citing its heading or page |
| Notion, Confluence, Google Docs | The same, from a page you choose, through a read-only connection |
| Pull-request reviews | Requests reviewers keep repeating, and any comment with /groundrule rule |
| Developers and agents | groundrule propose and the MCP propose_rule tool |
$ npx @groundrule/cli scan --upload groundrule scan · acme/checkout-api · 14 files · 0.1s Stack TypeScript, JavaScript, fastify Tools codeowners (2 rules), docker, eslint, github-actions, typescript (strict) Rules 171 in the catalog · 90 apply here ✓ 35 already pass ! 6 with findings (6) ◇ 49 guidance only Imports 4 instructions from agent files · 3 tool settings that match catalog rules · 2 CODEOWNERS entries Already enforced by your tools: TS-001, TS-007 ✓ Uploaded to Acme Payments: app.groundrule.dev/acme-payments/scans/38208a34…
Accepting does the real thing; rejecting records why.
One inbox. The right owner. A person decides.
Everything found waits as a proposal, grouped by category and routed to whoever owns it.
Accept an instruction
It becomes a standard with the next free ID. Draft with AI fills in title, severity, scope and rationale for you to edit.
Adopt a tool setting
The matching catalog rule turns on, at Enforce, because your linter already enforces it.
Assign an owner
From CODEOWNERS, creating the team if it doesn't exist. Proposals in that category route to them.
Read-only stays read-only
Developers propose and everyone can see the inbox. Only owners and admins decide.
Rules at Teach and beyond reach every agent's files, and MCP serves them live.
Every agent gets the same rules.
Rules are written into the files every coding agent already reads, in every repository, scoped to its languages and its team.
- One command
groundrule syncwrites AGENTS.md, CLAUDE.md, Cursor rules and Copilot instructions for this repository's languages and its team. - Your words stayGroundrule writes inside a marked block. Everything else in the file is yours.
- No drift
sync --checkin CI fails when the files are out of date. - Live over MCPAgents call list_standards before they write code, and propose_rule when a developer corrects them.
$ npx @groundrule/cli sync groundrule sync · 79 standards → agents-md, claude-code, cursor From Acme Payments on Groundrule (organization rules): rules at Teach, Advise, and Enforce + .cursor/rules/groundrule.mdc created ~ AGENTS.md updated ~ CLAUDE.md updated ✓ Done. Commit these files so every agent gets the same rules.
The same checks on a laptop, in a pre-commit hook and in CI.
Checks on every change, in stages.
Checks are deterministic, and they look at what a change touches, so old code doesn't block new work.
on: pull_request jobs: groundrule: runs-on: ubuntu-latest env: GROUNDRULE_TOKEN: ${{ secrets.GROUNDRULE_TOKEN }} steps: - uses: actions/checkout@v4 with: { fetch-depth: 0 } # agent files match the rulebook - run: npx @groundrule/cli sync --check # only what this pull request changed - run: npx @groundrule/cli check --base origin/${{ github.base_ref }}
$ npx @groundrule/cli check --all groundrule check · 43 standards · 14 files (full audit) ✕ GHA-003 Do not interpolate untrusted event data into scripts BLOCKER · deterministic (regex) .github/workflows/ci.yml:8 8: - run: echo "${{ github.event.pull_request.title }}" → Move the expression into the step's env: block (e.g. TITLE: ${{ github.event.issue.title }}) and use "$TITLE" in the script, always double-quoted. ⚠ TS-001 No console.log in application code warning · deterministic (regex) src/http/refunds.ts:4 4: console.log("refunding", id, amount); → Replace it with the project's logger, or remove it. Failed ✓ 31 passed ✕ 1 failed ⚠ 5 warnings · 0.0s
Checked on every scan. The results become evidence; nobody sees a finding.
“Clean” means no findings across at least two scans of every repository. Groundrule suggests the move; a person makes it.
Every screen and command is in the documentation, step by step.
About getting started.
How long does setup take?
About 30 minutes: sign up, answer four onboarding questions (Groundrule preselects packs for your stack), connect one repository with login, init and sync, and scan it. The documentation's Get started guide walks through all ten steps.
Do we have to adopt a whole pack?
No. A pack is a starting point. Turn any rule off with a reason, change its severity, scope or wording, or set its stage, for the organization, a team or one repository. Teams and repositories can be stricter than the organization, never looser.
What happens to the AGENTS.md we already wrote?
Nothing you wrote is overwritten. sync writes its rules inside a marked block and leaves the rest of the file as it is. A scan can also import your existing instructions as proposals, so they become real standards.
Which languages do the checks support?
Checks are patterns over files plus dependency and file rules, so they work in any language. The packs cover TypeScript and JavaScript, React, Python, Java and Spring, Go, Docker, Kubernetes, Terraform, GitHub Actions, HTTP APIs and testing. A semgrep check runs where Semgrep is installed.
Give every agent your team's rules.
Create a workspace, adopt the packs that fit your stack, and connect one repository. In half an hour your coding agents follow your standards, and you can see what a check would catch before it blocks anyone.