Write agent instructions (sync)

groundrule sync writes your rules into the instruction files that coding agents read: AGENTS.md, CLAUDE.md, Cursor rules, and Copilot instructions. It changes only the parts Groundrule owns and leaves everything you wrote yourself. This page explains what it writes for each agent, which rules it includes, and how to keep the files current in CI.

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 first line counts the standards written and names the targets from targets: in .groundrule/config.yaml. In a platform repository, the second line says where the rules came from: “organization rules”, or the registered repository and its team, such as “(acme/checkout-api, team Payments)”.

Each file gets a mark:

Mark	Meaning
+ created	The file didn’t exist.
~ updated	The file changed.
− removed	A file Groundrule wrote earlier is no longer needed, for example because no rule targets those paths any more.
= unchanged	Nothing to do.

When nothing changed, the last line reads “✓ Already up to date.”

What it writes for each agent

Target	File	What Groundrule owns
agents-md	AGENTS.md	A marked block
claude-code	CLAUDE.md	A marked block
cursor	.cursor/rules/groundrule.mdc, plus .cursor/rules/groundrule-<scope>.mdc per path scope	The whole files
copilot	.github/copilot-instructions.md, plus .github/instructions/groundrule-<scope>.instructions.md per path scope	A marked block in the first; the whole of the others

AGENTS.md

The block holds an Engineering standards section. It opens with three lines for the agent:

These are this repository's engineering ground rules. Follow them in every change.
Before you finish a task, run `npx @groundrule/cli check` and fix what it reports.
For the reasoning and examples behind a rule, run `npx @groundrule/cli explain <ID>`.

Rules that apply everywhere come first, under Everywhere. Rules limited to some paths follow, under a heading with those paths. Within each group, the most severe rules come first. Each rule looks like this:

- **TS-001** No console.log in application code · _warning_
  Use the project's logger instead of console.log or console.debug in application code. Tests, scripts, and CLIs may print. (typescript, javascript)
  - Do: `logger.info({ orderId }, "order created")`
  - Don't: `console.log(order)`

That is the ID, title and severity, the requirement (or the rule’s shorter agent summary, when it has one), the languages and frameworks it’s limited to, and the first Do and Don’t examples.

CLAUDE.md

When agents-md is also a target, the block in CLAUDE.md contains only a pointer, so Claude Code doesn’t read the rules twice:

Engineering standards for this repository are in AGENTS.md:

@AGENTS.md

Without agents-md, CLAUDE.md gets the full section instead.

Cursor

Cursor gets one .mdc file per path scope in .cursor/rules/. Each starts with Cursor’s frontmatter:

• groundrule.mdc holds the rules that apply everywhere, with alwaysApply: true.
• groundrule-<scope>.mdc holds rules limited to some paths, with those paths in globs: and alwaysApply: false, so Cursor uses them only for matching files.

Groundrule owns these files completely. Your own .mdc files in the same folder are never touched. Only files named groundrule.mdc or groundrule-….mdc are written or removed.

Copilot

• .github/copilot-instructions.md gets a marked block with the rules that apply everywhere.
• .github/instructions/groundrule-<scope>.instructions.md holds rules limited to some paths, with applyTo: set to those paths.

Only files named groundrule-….instructions.md in .github/instructions/ belong to Groundrule.

The managed block

In AGENTS.md, CLAUDE.md and .github/copilot-instructions.md, Groundrule writes between two markers:

<!-- groundrule:begin -->
<!-- Generated by Groundrule from `.groundrule/`. Edit the standards there, then run `groundrule sync`. -->

## Engineering standards
…
<!-- groundrule:end -->

• Everything outside the markers is yours. Your build commands, notes, and conventions stay as you wrote them.
• Everything inside is replaced on every sync. Don’t edit it: your changes would be lost. Change the rule instead, in the dashboard or in .groundrule/standards/.
• A file without markers gets the block added at the end, after a blank line.
• A missing or empty file is created with only the block.

check and scan skip the managed blocks and Groundrule’s own files. The rules’ Don’t examples there never count as findings.

Which rules it includes

sync includes a standard when all of these hold:

1. It’s in effect.
   • Platform repository: the rule is turned on and at Teach, Advise, or Enforce. Rules at Observe, drafts, and rules turned off aren’t in agent files.
   • Offline repository: the standard is active or deprecated, and not turned off in overrides.
2. It applies to this repository. Its languages, frameworks, tags, and repositories, if it names any, match this repository. A React rule is left out of a repository without React. Path scopes don’t exclude a rule: they decide where it’s grouped.
3. It’s meant for agents. Every standard is, unless its author turned off agent instructions for it.

The repository’s own standards in .groundrule/standards/ are included the same way.

Keep the files current: sync --check

npx @groundrule/cli sync --check

--check writes nothing. It compares the files with what sync would write:

✓ Agent instructions are up to date (79 standards).

When they differ, it lists what would change and exits with code 1:

✕ Agent instructions are out of date:
   AGENTS.md would be updated
   Run groundrule sync and commit the result.

Run it in CI. In a platform repository, the files also go stale when someone changes the rulebook, for example when a rule moves from Observe to Teach. A failing sync --check is then the signal to run sync and commit. See Run Groundrule in CI.

Options

Option	What it does
--check	Write nothing. Exit 1 if any file is out of date.
--refresh	Fetch packs from GitHub again (extends: github:…), even if they’re cached. Pinned references (@v1) are cached; unpinned ones are always fetched.

Exit codes: 0 when the files were written or are up to date, 1 when --check finds them out of date, 2 when the configuration has errors or the rulebook can’t be fetched.

Commit the files

Commit every file sync writes, so every developer and every agent works from the same rules, including agents that run in the cloud from a fresh clone:

git add AGENTS.md CLAUDE.md .cursor/rules .github/copilot-instructions.md .github/instructions
git commit -m "Update agent instructions"

Add only the paths your targets use.

Merge conflicts

If two branches both changed the generated files, resolve the conflict by taking either side, then run npx @groundrule/cli sync and commit the result. sync rewrites the block from the current rules, so which side you took doesn’t matter. Keep any changes you made outside the markers.

If something goes wrong

You see	What to do
No Groundrule config found. Run groundrule init to create one.	Run init first. See Connect a repository.
Not signed in to acme-payments on …	Run npx @groundrule/cli login, or set GROUNDRULE_TOKEN in CI.
… isn't registered in acme-payments, so the organization's rules apply.	Harmless. To use the team’s settings, register the repository in Teams → Repositories.
A rule you expected is missing	Run npx @groundrule/cli standards. It lists every rule, with its stage and “(not applicable here)” where it doesn’t apply.

Related

• Agent instruction files
• Rollout stages
• The MCP server, which gives agents the rules on demand