omarchy: Instructions file for Codex

Task Guides

Deeper instructions for specific kinds of work live in agents/skills/. Read the matching guide before starting:

• agents/skills/command-metadata.md - adding or changing commands in bin/
• agents/skills/install-scripts.md - working under install/ or on system/user setup commands
• agents/skills/mise-tools.md - adding or changing mise-managed tools
• agents/skills/shell-dev.md - editing the Quickshell desktop under shell/
• agents/skills/icon-font.md - adding branded glyphs to default/fonts/omarchy/omarchy.ttf
• agents/skills/acceptance-tests.md - writing or running graphical acceptance tests under test/acceptance.d/
• agents/skills/oligarchy-tests.md - full omarchy tests that run in qemu to validate behavior
• agents/skills/motion.md - adding or changing any animation or transition in shell/
• agents/skills/visual-verification.md - verifying any change with a visual effect in the running UI
• agents/skills/migrations.md - creating or changing migrations under migrations/

Documentation Layout

Three documentation trees, split by genre and audience:

• agents/skills/ - task procedure ("do this when doing X"), for anyone working on the codebase
• docs/ - reference on how the system is shaped (file layout, update pipeline, theming, shell architecture), for anyone working on the codebase; skills link here for depth
• manual/ - end-user documentation for using Omarchy, published; never codebase internals

Style

• In markdown documents (plans/, docs/, manual/), write full lines — no hard wrapping at 80 columns; break only at structural boundaries like headings and list items
• Two spaces for indentation, no tabs
• Use bash 5 conditionals: use [[ ]] for string/file tests and (( )) for numeric tests
• In [[ ]], don't quote variables, but do quote string literals when comparing values (e.g., [[ $branch == "dev" ]])
• Prefer (( )) over numeric operators inside [[ ]] (e.g., (( count < 50 )), not [[ $count -lt 50 ]])
• Prefer a full if/else conditional for simple two-path control flow; don't rely on exec or exit in one branch to make following statements unreachable
• For strings/paths with spaces, quote them instead of escaping spaces with \ (e.g., "$APP_DIR/Disk Usage.desktop", not $APP_DIR/Disk\ Usage.desktop)
• Shebangs must use #!/bin/bash consistently (never #!/usr/bin/env bash). A security-sensitive entrypoint may use the exact #!/bin/bash -p form only when it must suppress BASH_ENV and exported-function startup injection before its first command; that exception must be explained at the boundary and covered by a regression that rejects an ordinary Bash launch with a decoy -p argument.
• Scripts under install/ and migrations/ may be sourced and intentionally omit shebangs