Archy: Instructions file for Codex

Working on archy

Notes for a coding agent working on this repository. For using archy as a tool, see skills/archy/SKILL.md and the README.

Everything here was learned by getting it wrong. Each rule names the failure it came from, so you can judge whether it applies to what you are doing rather than following it blindly.

Two rules in Git and GitHub are worth reading before you touch anything, because both fail quietly: never push to main (branch and open a PR instead), and use gh api REST, because gh pr edit and --json go through GraphQL, which can fail while still exiting 0.

Before you push: run what CI runs

uv run ruff check          # NO path argument
uv run ruff format --check
uv run ty check
uv run pytest
uv run archy check .       # archy's own layer rules
uv run archy cycles . --strict
uv run archy conventions . --emit-headers --check   # derived headers still true

ruff check with no path. Running ruff check some/file.py is not the same command and will pass while CI fails: a fixture directory with deliberately unused imports broke the build twice in one session because it was only ever linted per-file.

archy conventions . --emit-headers --check is a gate too. The headers in archy's own modules are derived, so adding a public symbol or changing a mirror set makes them stale, and CI fails. Regenerate with uv run archy conventions . --emit-headers --write; never hand-edit a block, because the next regeneration discards the edit and the point of the block is that it is not hand-authored.

archy check and archy cycles matter as much as ruff check, ruff format, ty and pytest. archy gates itself, so a new fixture tree or bench sample can introduce a real cycle or layer violation in a directory that is not archy's code. Add such trees to exclude: in archy.yaml with the reason, rather than weakening a rule.

Some failures only appear in CI's environment. The bench caches under bench/cache/ are gitignored, so a test that depends on one passes locally and fails on the runner. Before pushing a test that touches one, run mv bench/cache /tmp/bench-cache-aside, re-run the test, then move it back. Assert the invariant, not the message: a test that checks which precondition failed is asserting a fact about your laptop.