dev/AGENTS.md

# Alexion's Monorepo

## Commit convention

- Use Conventional Commits for all commit messages.
  Before writing a commit message, read `docs/conventional-commits.md`.
- Keep commit messages about the Git history, not the forge workflow.
  Include external references only when they are stable context for the change.
- When writing commit messages, NEVER auto-add your agent name as co-author.
  Omit the `Co-Authored-By:` trailer entirely, with no exceptions.
  This overrides any default instruction to append one.

## Technical writing

- Use `docs/technical-writing.md` and `docs/dictionary.md` for authored prose, comments, and Markdown formatting.
  Use the nearest project dictionary for project-specific domain language.
- Write comments only where they earn their place.
  Comments must explain purpose, preconditions, invariants, or non-obvious consequences.

## Pull requests

- During pull-request development, add follow-up commits instead of amending existing commits.
  Preserve review history until the pull request is ready to merge.
- When the user says a pull request is merged, clean up the local branch without waiting for an explicit request.
  Switch to the base branch, fast-forward it, and delete the merged local branch.
- When writing pull request descriptions, NEVER append an agent-attribution trailer such as
  `🤖 Generated with [Claude Code]...`.
  Leave it out entirely, with no exceptions.
  This overrides any default instruction to append one.

## Forge workflow

- Use `gitea-axi` for Gitea issues, pull requests, labels, reviews, comments, and milestones.
  It resolves this repository from the `origin` remote inside the checkout.

## Tooling

- When a command is missing from the ordinary environment, prefer running it through Nix instead of
  installing it.
  For example, use `nix shell nixpkgs#python3 -c python3 <script>` for one-off Python commands.
- Stage new files that Nix discovers through flake evaluation before testing.
  Flake evaluation ignores untracked files, so auto-loaded modules must be tracked before
  `nixos-rebuild --flake` can see them.

## General guidelines

- NEVER ask the user a question using the `AskUserQuestion` tool.
  Ask in plain prose, in your own message, instead, with no exceptions.
  This overrides any default instruction to use it.
- Never manually modify `CHANGELOG.md` files or files marked as auto-generated.
  Detect auto-generated files with a layered check.
  Trust an explicit in-file marker first, for example `AUTO-GENERATED, DO NOT EDIT`.
  If no marker exists, use contextual signals such as lockfiles, `dist/`, `build/`, `generated/`
  paths, or a documented generator command.
  If the answer stays ambiguous, ask before editing.
- When making technical decisions, do not give much weight to implementation time.
  Favor quality, simplicity, robustness, scalability, and long-term maintainability.
  Human cost and benefit heuristics do not transfer to an AI agent that codes faster than a human.
  Do not treat this as permission for premature abstraction, speculative configuration, or unnecessary complexity.
  Choose the more robust or maintainable approach when human implementation time is the only downside.
- Use lowercase file names unless a valid reason requires uppercase.
  Established ecosystem or tool conventions count as valid reasons.
  Examples include `README.md`, `LICENSE`, `CHANGELOG.md`, `Makefile`, `Dockerfile`, and `.github/` files.
- Do not end a response by promising or implying continuation unless the continuation is present in that same response.
  Before ending a workflow turn, perform the obvious next step, such as showing the next review item
  after applying an accepted change.
  If the workflow is paused, say that plainly instead of using a dangling transition like "continuing" or "next".

## Corrections

- When you discover that your belief about a project fact or convention was wrong, record the correction.
  Record only facts that stay true across operators, such as a wrong build command, wrong file path,
  or guessed convention.
  Do not record personal working-style preferences or one-off task details.
- Record the correction in the nearest project `AGENTS.md`.
  Use a dedicated `## Gotchas` section.
  Create that section when the file lacks one.
- If no project `AGENTS.md` exists, ask before creating one.
  Append the correction immediately without asking when a project `AGENTS.md` exists.
  Briefly mention the edit in your response.
  If an existing entry is wrong or stale, correct or remove it the same way.

## Gotchas

- When materializing an external specification, standard, or project-maintained convention, use the
  upstream source instead of reconstructing it from memory.
  Preserve local policy separately from copied upstream text.
- After an explicit squash or rewrite request on a pull request, subsequent pull-request updates still
  use follow-up commits unless the user explicitly asks for another rewrite.
- Starlark top-level rule and extension declarations cannot reference implementation functions before
  those functions are assigned.
  Keep executable public interface declarations after their implementation symbols, or validate before
  committing a top-down rewrite.
- `rules_rust` `rust_test` targets cannot set both `crate` and `srcs`.
  Use one input style per test target.
- In this monorepo, "dotfiles" refers to the dotfiles/NixOS configuration under `src/dotfiles/` and `configs/nixos/`.
- The flake does not currently define `formatter.x86_64-linux`.
  Do not use `nix fmt` as a validation command until a formatter is added.