The four files
Drop one of these next to your project (or under ~/.omp/agent/ for global scope) and omp picks it up at the next session start. No reload, no config entry — discovery is filesystem-driven.
| File | What it does | When the agent sees it | …
Where they live
Project files are walked from the current working directory upward to the repository root (or your home directory when outside a repo), so any ancestor checkout root is fair game. Global files sit under ~/.omp/agent/ and apply to every session.
…
Neighbouring harness files are also discovered: Codex `AGENTS.md`, Claude `CLAUDE.md`, Cursor rules, `.clinerules`, Copilot instructions, opencode context files. Each loaded entry shows up in [`/extensions`](reference/slash) with its source path.
## Resolution order
When more than one `AGENTS.md` exists, omp concatenates them in this order, most general first:
1. Global — `~/.omp/agent/AGENTS.md`
…
For `SYSTEM.md` and `APPEND_SYSTEM.md`, only one file applies: the nearest project file wins over the global one rather than concatenating with it. For `RULES.md`, both scopes apply — the global `~/.omp/agent/RULES.md` and the nearest project `.omp/RULES.md` are each loaded as always-apply rules when present.
## AGENTS.md in practice
Treat `AGENTS.md` as a README for the agent. Conventions, build commands, the one file that’s deceptively load-bearing, the directory layout it should default to. The agent reads it once at session start, so keep it tight — a long file burns context every turn.
```md
…
## RULES.md and sticky behaviour
`RULES.md` is the file you reach for when an instruction has to stay enforced. omp loads it as an always-apply rule and injects its full contents into the system prompt, so it rides along on every request — even after many turns of conversation. Use it for hard constraints (“never commit secrets”, “always run `just test` before yielding”), not for general notes — those belong in `AGENTS.md`.
## Replacing the system prompt
`SYSTEM.md` swaps the built-in system prompt wholesale. You lose the carefully tuned instructions that ship with omp, including tool-usage guidance. Prefer `APPEND_SYSTEM.md` unless you specifically want a different agent persona.
```md
…
## Disabling discovery
| Knob | Effect |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `disabledProviders` (setting) | Disable individual discovery providers (e.g. `agents-md`, `claude`) — toggle them from [`/extensions`](reference/slash). |
| `--no-rules` | Skip rule discovery entirely for this run — `RULES.md`, `.omp/rules/`, and other rule sources. |
| `--system-prompt <text\\ | @file>` | Override the system prompt from the CLI — takes priority over `SYSTEM.md`. |
Run `omp -p '/extensions'` to confirm which files actually loaded. See [CLI reference](cli) for full flag details and [Skills](skill-playbooks), [Prompt templates](prompt-templates), and [Hooks](hooks) for the other customization surfaces.
[…44ln elided; re-read needed ranges, e.g. /home/usr/funday/dev/docs/content/omp/context-files.md:16-20,27-36]