01 / Router files
Task guides before rules
Seven links route command metadata, install scripts, desktop work, icons, acceptance tests, visual checks, and migrations. Only migration work loads the migration guide.
Omarchy Agent Rules
Opinionated Arch Linux desktop, configured as a product.
Overview
Omarchy opens with a table that sends seven kinds of work to focused guides. Its documentation has three audience-specific sections, and project helpers replace several raw shell commands.
Documents
├── ├── · imports AGENTS.md ├── agents │ └── skills │ ├── │ ├── │ ├── │ ├── │ ├── │ ├── │ └── ├── default │ └── agents │ └── skills │ └── omarchy │ └── └── docs ├── └──
Techniques in this file
02
Three documentation trees, split by audience
Task procedure, system reference and end-user documentation each have their own directory, with the audience stated for each. The user manual carries an explicit exclusion.
Source excerpt starting at line 20.- `manual/` - end-user documentation for using Omarchy, published; never codebase internals
03
Helper commands in place of the obvious tool
A list maps project commands onto the tools they replace: a package helper rather than pacman, a notification helper rather than notify-send. The wrappers handle cases the raw commands do not.
04 / Hard prohibitions
Defensive checks ruled out where they are noise
Default-package commands are runtime invariants, so presence checks around them are wrong. Reserve those checks for optional dependencies, pre-install code, and listed exceptions.
Source excerpt starting at line 88.Commands installed by Omarchy's default package set are runtime invariants. Invoke them directly; do not add defensive `omarchy-cmd-present` / `omarchy-cmd-missing` checks around them. Use command-presence helpers only for genuinely optional dependencies or code that can run before the default package set is installed.
05 / Pointing at the source of truth
One list, not two
The command prefix section gives common examples, then points at the array in the router as authoritative, with the stated reason that a second copy drifts.
Source excerpt starting at line 57.Do not maintain a second exhaustive prefix list here. Consult
06
A documented footgun
The config refresh helper checks only whether an interpolated path exists. Traversal can therefore resolve and write outside the config directory, a limitation the guide states plainly.
Ideas for your repo
- Lead with a table of task guides. It is the main lever on what every request pays for.
- If you have more than one documentation directory, state the audience for each.
- List the wrapper commands that replace the obvious tool, and say which defensive checks are noise.
- Where two copies of a list could drift, name the authoritative one and refuse to keep the second.
Sponsored by
Give your agents the whole story.
These instructions explain how to work in Omarchy. Modem shows your agents what customers said, who is affected, and what changed.