dev/AGENTS.md

Alexion's Monorepo

Commit convention

• Use Conventional Commits for all commit messages.
• 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

• Always create a new branch before opening a pull request. Never open a pull request directly from a shared or existing work branch.
• 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.
• Rust tests in this monorepo live in separate *_test.rs files, not inline #[cfg(test)] modules.
• rnix::ast::HasEntry::entries() includes assignments and inherit statements. Use attrpath_values() when code needs only assignment entries.
• Ariadne Rust tests are declared in Bazel BUILD files; do not add [[test]] entries to src/ariadne/Cargo.toml unless explicitly requested.
• 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.
• The fix app passes its current directory to Deadnix. Run nix run .#fix from the repository root so path exclusions match.
• Git pathspec searches started in a subdirectory default to that subtree. Use git -C <repository-root> or top-anchored pathspecs for repository-wide history searches.
• A **/*.nix Git pathspec does not include Nix files directly in its starting directory. Include both *.nix and **/*.nix, or use a recursive *.nix pathspec, when linting every Nix file.
• Ariadne extraction must preserve the game-root season prefix for archived source. Different game installs can contain compiled scripts with the same internal path.
• Clew owns Ren'Py extraction, preparation, and compiled-script AST export. Ariadne owns analysis over Clew-produced data.
• Bazel Python targets require PYTHON_TOOLCHAIN_ROOT to point at a Python installation root.
• When checking whether a package exists in nixpkgs, check both this repository's pinned nixpkgs inputs and the relevant current upstream channel. A package can exist on current nixos-unstable while being absent from the pinned revision or from a different branch such as nixpkgs-unstable.
• OMP does not discover project skills from .pi/skills. Put skills shared by Pi and OMP under .agents/skills, or configure OMP's skills.customDirectories.
• Pi is vendored under third_party/pi as a linear vendor import. pkgs.alexion.pi-coding-agent packages that source and does not use Nixpkgs Pi. Do not use git subtree add or git subtree pull for Pi PR branches. Gitea rebases the synthetic upstream root commit without the third_party/pi prefix. Preserve git-subtree-dir and git-subtree-split trailers on Pi vendor commits.
• The default Pi model for NixOS user configuration is set in configs/nixos/modules/shell/pi/default.nix, not in vendored Pi source.
• The monorepo and status libraries do not have README.md files.