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

• 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.
• Ariadne Rust tests are declared in Bazel BUILD files; do not add [[test]] entries to src/ariadne/Cargo.toml unless explicitly requested.
• Rust package validation in this monorepo uses Bazel rust_test targets. Do not claim or require cargo test as the standard Rust validation path 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.
• Keep third_party/** excluded from treefmt. Vendored code can contain syntax fixtures, generated files, or upstream formatting that local formatters must not rewrite.
• 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. 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.
• rules_rust crates_vendor can vendor direct crate specs through the packages attribute. Do not create a placeholder Rust package only to anchor a future vendored dependency.