AGENTS.md

1# rules-engine — Rule Discovery + Matching (Core)
2 
3**Generated:** 2026-06-16
4 
5## OVERVIEW
6 
7`@oh-my-opencode/rules-engine` (renamed from `rules-core`). Harness-neutral TypeScript package that discovers markdown rule files and matches them against target paths. Consumed by the `rules-injector` hook in `omo-opencode`, the `rules` component in `omo-codex`, and `agents-md-core` for AGENTS.md walk-up discovery.
8 
9## KEY FILES
10 
11| File | Role |
12|------|------|
13| `src/index.ts` | Barrel: legacy/simple API (`findRuleFiles`, `shouldApplyRule`, `findAgentsMdUp`) |
14| `src/engine/index.ts` | Barrel: comprehensive engine API (`createEngine`, `findRuleCandidates`, `matchRule`) |
15| `src/finder.ts` | `findRuleFiles()` — walks project + user home directories to collect rule candidates |
16| `src/matcher.ts` | `shouldApplyRule()` — picomatch against rule globs/paths with LRU cache |
17| `src/agents-md.ts` | `findAgentsMdUp()` — walk-up discovery for `AGENTS.md` from start dir to root |
18| `src/engine/engine.ts` | `createEngine()` — static + dynamic loading, session state, formatting, truncation |
19| `src/engine/finder.ts` | `findRuleCandidates()` + `findPluginBundledCandidates()` with source filtering |
20| `src/engine/matcher.ts` | `matchRule()` with content-hash dedup |
21| `src/engine/scanner.ts` | `scanRuleFiles()` — recursive directory scanner with caching |
22| `src/engine/formatter.ts` | `formatStaticBlock()` / `formatDynamicBlock()` with per-mode char budgets |
23| `src/constants.ts` | Rule sources, extensions, source priority map, project root markers |
24 
25## FLOW
26 
27Discovery (`finder.ts` / `engine/finder.ts`)
28  Walk UP from cwd toward project root
29    Scan `.omo/rules`, `.claude/rules`, `.cursor/rules`, `.github/instructions`
30    Collect `.md` / `.mdc` files + single-file rules (`copilot-instructions.md`, `CONTEXT.md`)
31  Walk user home: `~/.omo/rules`, `~/.opencode/rules`, `~/.claude/rules`
32  Plugin bundled: platform-gated rules under `bundled-rules/`
33 
34Matching (`matcher.ts` / `engine/matcher.ts`)
35  Parse YAML frontmatter (globs, paths, applyTo, alwaysApply)
36  Picomatch against target file path (relative + basename)
37  Negative globs (`!`) excluded; `alwaysApply: true` bypasses matching
38 
39Ordering
40  Source priority map (`SOURCE_PRIORITY`) + distance from target file
41  Lower priority value = earlier; closest distance wins
42 
43## NOTES
44 
45- Two APIs: root `src/` (simple functions) and `src/engine/` (stateful engine with truncation budgets). Both consumed in production.
46- Default char budgets: static 12K rule / 40K total; dynamic 4K / 10K; post-compact 3.5K / 4K.
47- `AGENTS.md` discovery lives here but injection logic is in `agents-md-core`.
48- Parent: [`packages/AGENTS.md`](../AGENTS.md)
49