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.
How it works
Section titled “How it works”-
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/anddoc/architecture/decisions/. Add other folders under Folders. -
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.
-
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. -
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.
What becomes a rule
Section titled “What becomes a rule”The LLM classifies each statement by its strength and whether a review can see it in the code.
| Strength | Example | Result |
|---|---|---|
| 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 it | Result |
|---|---|
| In one changed file or block | A 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 meeting | No rule |
OpenTremor drops a statement if its quote does not appear in the file.
When an ADR changes
Section titled “When an ADR changes”| File change | What is proposed |
|---|---|
A new file has status Accepted | A new rule for each extracted statement |
| Wording changes | Updates to rules that were reworded, new rules for new statements, and disable proposals for removed statements |
Status changes to Superseded, Deprecated or Rejected | Disable proposals for its rules |
| File is deleted | Disable 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.
Rules written into agent instructions
Section titled “Rules written into agent instructions”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 testfirst”, 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’sapplyTo:can target packs. For example,**/*.pytargets 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.
Where a rule applies
Section titled “Where a rule applies”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 to | Scope of the proposed rule | Typical repository |
|---|---|---|
| This repository | The repository | A service with its own adr/ |
| Its product | Every repository in its product | A product’s architecture repository; falls back to the repository when it has no product |
| The whole organization | The org | A 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.
Before you start
Section titled “Before you start”- 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.
| Endpoint | What 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/sync | Starts a sync in the background (202); returns {"started": false} when one is already running |
GET …/repositories/{provider}/{external_id}/knowledge | Lists the files read and each file’s latest outcome |
GET /v1/rule-proposals?source=knowledge | Lists 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.