# Guidance for AI coding agents

**Read `CLAUDE.md` first — it is the authoritative, detailed guide for this repo.**
This file exists so that non-Claude tools find the same rules; `CLAUDE.md` is
canonical. Also read **`STATUS.md`** to learn what actually exists versus what is
only designed — much of the ADR-described design is not built yet.

## Non-negotiables (full detail in CLAUDE.md)

- **Verify before claiming done.** Run `make lint` and the relevant `make check` /
  `make test`, and report the real output. Never assert success you haven't observed.
- **Never edit generated files** (e.g. `inventories/*/hosts.yml`). Edit the source
  (`terraform/environments/<env>/main.tf`) and regenerate with `make tf-inventory`.
  Generated files carry a header saying so.
- **Secrets only in `vault.yml`** files — never plaintext elsewhere. The master
  vault password comes from Vaultwarden via `rbw`; never print or commit it.
- **No `make deploy` / `make tf-apply`** without running `make check` / `make tf-plan`
  first and showing the output.
- **Before deleting or overwriting a file you did not create, read it first** and
  surface what you find rather than proceeding blind.
- **Check `STATUS.md`** before assuming a role, provider, or pipeline exists.
- **Git**: `main` must always work; branch for sweeping changes. Commit your work in
  logical units with imperative ≤72-char subjects and a `Co-Authored-By` trailer.