Rules from developers and coding agents

The best moment to capture a rule is when someone says it: in the terminal, or while correcting a coding agent. Developers can propose a rule with one command, and coding agents can propose one through Groundrule’s MCP server when the developer agrees. Either way, the rule arrives in the inbox for an owner to accept or reject. This page is the reviewer’s view. The commands are in groundrule propose and The MCP server.

How a rule is proposed

From the terminal:

npx @groundrule/cli propose "Never log full card numbers; mask all but the last four digits." --why "PCI DSS" --file src/http/refunds.ts:4

 ✓ Proposed to Acme Payments. Reviewers will see it in the inbox: https://app.groundrule.dev/acme-payments/inbox

From a coding agent: when the developer corrects the agent about how code should be written, and says (or confirms when asked) that it should apply to everyone, the agent calls propose_rule. The agent is told never to propose one-off preferences, rules that already exist, or anything the developer didn’t ask for or agree to.

Both need a sign-in to the workspace, from groundrule login or a token with Propose rules. Any role can propose: a developer doesn’t need an authoring role.

What arrives in the inbox

A proposed rule is an Instruction. It shows:

Part	Example
Who proposed it, and how	“Proposed by Dan Ortiz from the CLI”, or “Proposed by Dan Ortiz via claude-code”
Where it came up	src/http/refunds.ts:4 (when a file was given)
How many times	“proposed 3 times”
The rule	Up to 1,000 characters, with secrets redacted
The example	A code block, when one was given (up to 2,000 characters)
Must, Should or Note	From the wording: must, never, always or do not is Must; should, prefer or avoid is Should
Similar (keyword match)	Existing standards with similar words

The reason given with --why (or the agent’s why) becomes the starting Rationale when you accept it. The repository comes from the developer’s .groundrule/config.yaml or git remote.

Accept it like any instruction: Create a standard, with Draft with AI to fill in the fields, or Already covered. See The review inbox.

Votes, not duplicates

Proposing the same rule again doesn’t create a second proposal. Groundrule compares the wording, ignoring case, punctuation and formatting. A match adds a vote:

• the inbox row shows “proposed N times”;
• the developer sees “Already proposed in Acme Payments; your vote is added.”

If a reviewer already rejected that rule, the developer is told: “A reviewer already rejected this rule in Acme Payments. Ask them to reopen it if things have changed.” You can Reopen it from Rejected in the inbox.

Limits

Limit	Value
Rule length	10 to 1,000 characters (“Say the rule in a sentence.”)
Reason (--why)	Up to 1,000 characters
Example	Up to 2,000 characters
File	A path relative to the repository
Proposals per person	30 per hour
Proposals per workspace	500 per day

Ask your team to use it

1. Make sure everyone can sign in. Invite developers with the Developer role (Settings → Members → Invite). See Members and roles.
2. Connect each repository with groundrule init --org acme-payments, so proposals go to the right workspace. See CLI quickstart.
3. Add the MCP server to your coding agents. See The MCP server.
4. Tell the team when to propose. For example: “When you explain the same thing in review twice, or correct your agent about how we do something, propose it.”
5. Review proposals regularly, and give a reason when you reject one, so people learn what makes a good rule.

Reviewers can also capture rules from pull requests with /groundrule rule. See Rules from pull-request reviews.