Skip to content
DashboardWebsite

Rules from ADRs

Just want to do it in the dashboard? See the guide: Turn an ADR into a rule.

This page explains how OpenTremor reads architecture decision records (ADRs) from a repository and proposes review rules. It is for engineers and org admins who manage repository settings. OpenTremor reads files from the default branch and creates proposals; a person must approve each proposal before a rule changes. An approved rule then runs like any other rule; see How Rules Apply.

  1. Turn it on for a repository. On the repository’s page, under Rules from ADRs, switch on Read ADRs from this repository. By default, OpenTremor reads Markdown files in adr/, docs/adr/, doc/adr/, docs/decisions/, docs/architecture/decisions/ and doc/architecture/decisions/. Add other folders under Folders.

  2. Sync the files. A sync runs when you click Sync now, when a push to the default branch changes a configured source file, and when the task scheduler finds a repository due for sync. The default interval is 24 hours; see the task scheduler. A sync reads the default branch’s head, never a pull request. It skips files whose content has not changed since the last sync.

  3. The files are checked, then read by an LLM. OpenTremor scans each file for hidden instructions (HTML comments and invisible characters). A flagged file is not processed further unless semantic scoring is enabled for the organization and Also score files read for rule proposals is on under Organization → Features → Agent Injection. Scoring clears a file only when every detected match is judged harmless. See semantic scoring. For ADRs, OpenTremor extracts statements only when the status is Accepted. Otherwise, it lists the file without extracting rules. The repository’s LLM identifies statements a review can check and quotes each statement from the file.

  4. Review and approve proposals. On the Rules page, open the To review tab. Proposals are grouped by source file and by type: changes to existing rules, new rules, and recommendations. Within each group, proposals are grouped by source file, most severe first. Each proposal shows a source quote. Apply creates or changes the rule, Edit changes the draft, Later defers it, and Dismiss drops it. Apply all and Dismiss all act on every proposal from one file in that group. Rules created this way show From ADR in the Rules tab.

The LLM classifies each statement by its strength and whether a review can see it in the code.

StrengthExampleResult
Constraint“All services must use OIDC.”A proposed rule, with the severity the LLM suggests
Preference“Prefer short-lived tokens.”A proposed rule, at LOW severity at most
Rationale“We chose PostgreSQL because the team knows it.”No rule. Shown on the repository page as context
Where a review can see itResult
In one changed file or blockA proposed rule
Across several files (“core never imports a pack”)A proposed rule marked Cross-file. A review of one unit at a time may miss it
In no diff, such as a process or meetingNo rule

OpenTremor drops a statement if its quote does not appear in the file.

File changeWhat is proposed
A new file has status AcceptedA new rule for each extracted statement
Wording changesUpdates to rules that were reworded, new rules for new statements, and disable proposals for removed statements
Status changes to Superseded, Deprecated or RejectedDisable proposals for its rules
File is deletedDisable proposals for its rules

Open proposals from the file’s previous version are withdrawn. Applying an update rewrites the rule’s title, guidance, severity and packs. The category, scope and Needs review setting you chose stay as they are.

Skills and agent instruction files can also contain rules about code. Switch on Read rules written into agent instructions to propose those rules too. OpenTremor reads supported instruction files such as .claude/skills/*/SKILL.md, .claude/agents/*.md, AGENTS.md, CLAUDE.md, Cursor rules and Copilot instructions.

  • OpenTremor keeps statements about the code. It lists procedural steps, such as “run make test first”, on the repository page without proposing them.
  • A file with no rule-like text, such as “must”, “never”, “always”, “do not”, “only use”, or a Rules or Conventions heading, costs no LLM call.
  • A statement that repeats a rule already drawn from another file in the repository, such as an ADR, produces no proposal.
  • Cursor’s globs: and Copilot’s applyTo: can target packs. For example, **/*.py targets packs that review Python files.
  • These files have no status. Deleting one proposes disabling its rules.

A skill is not loaded into a review as a reviewer. Only the rules you approve reach the review.

The Rules apply to setting fills the scope for every rule proposed from the repository’s ADRs. You can change the scope when you approve a rule.

Rules apply toScope of the proposed ruleTypical repository
This repositoryThe repositoryA service with its own adr/
Its productEvery repository in its productA product’s architecture repository; falls back to the repository when it has no product
The whole organizationThe orgA central engineering-decisions repository

To read ADRs from every repository, add an ownership rule with pattern * and ADR sources. It fills repositories that never set their own.

  • An LLM connection. Reading requires the repository’s LLM or the integration’s LLM. Each file read uses one LLM call and counts against your organization’s monthly budget. OpenTremor skips files when the budget is spent until the next month.
  • GitHub: The App needs the Push event. An App created before this feature must add it in its GitHub settings. Until then, Sync now and scheduled syncs can still run.
  • GitLab: The project webhook needs Push events as well as Merge request events and Comments.
EndpointWhat it does
PATCH /v1/orgs/{org_id}/repositories/{provider}/{external_id}Set knowledge.sources to enable reading, for example {"sources": [{"kind": "adr", "paths": null, "applies_to": "repository"}, {"kind": "agent_instructions", "paths": null, "applies_to": "repository"}]}. Set knowledge to null to turn reading off
POST …/repositories/{provider}/{external_id}/knowledge/syncStarts a sync in the background (202); returns {"started": false} when one is already running
GET …/repositories/{provider}/{external_id}/knowledgeLists the files read and each file’s latest outcome
GET /v1/rule-proposals?source=knowledgeLists proposals; see Rule proposals

The repository’s knowledge_sync field shows the last sync state (running, done or failed), the commit read, file count and proposal count. Settings live under knowledge in the platform settings.