dev: Instructions file for Codex

AGENTS

This file provides guidance to coding agents (Claude Code, Codex) when working with code in this organization. It is the org-wide root file — every repository under the org loads it alongside its own AGENTS.md, so only org-wide guidance belongs here; repo-specific guidance belongs in each repository's own file.

Especially important points to keep in mind (each expanded in its section below):

• Questions are not edit requests. When a message asks a question without explicitly requesting a change, answer and stop (Communication).
• Write clear and concise English. Write clear, concise, plain English which can be quickly and easily parsed by the user — answer questions directly in short form unless elaboration is requested (Writing Style).
• Seek the best solution, not agreement. When you think the user is wrong, don't be afraid to say so — the right answer matters more than the path of least resistance (Pushing Back).
• Choose solutions that generalize. Define the requirement before choosing an approach. Consider alternatives and base each choice on the problem and known constraints. Do not choose an approach for convenience or overfit it to the cases tried during development (Principled Solutions).

Workflow

Git Workflow

Infer the workflow and authorized Git actions from the user's instructions and the conversation. We provide some common workflows, but tasks may combine them or follow a different arrangement. The user does not need to name a workflow. Follow the agreed scope, and if it is unclear what workflow(s) you should be adopting, it is always better to ask. Once a workflow is adopted, assume that it remains in effect within that scope until the user asks to change it.

• The user may review as work proceeds. This is common for smaller tasks or consequential changes that need close review. The user stages edits to mark them reviewed, then reviews new unstaged edits separately. Leave your changes unstaged. Do not stage, unstage, stash, discard, commit, or push unless the user authorizes that action. Treat newly staged changes as intentional; do not ask why they were staged or restore an earlier staging state. Only deviate when the user has requested you to do so explicitly.
• The user may authorize commits and pushes. Work directly in the repo's main checkout on the agreed branch. Stage, commit, and push the task's changes as you go. Before the first push, ask for permission unless the user has already explicitly authorized it. Ask if the scope of that permission is unclear. Use standing authorization within the agreed task scope without asking for each operation.
• The user may ask for work delivered through a pull request. Use a separate implementation worktree for the PR branch. A request to open or update a PR authorizes the staging, commits, and pushes needed for that PR. Keep the user's main checkout and its staged and unstaged work intact. Merge only when authorized.
• Preserve work outside your task. Git authorization covers the agreed work. Do not include unrelated changes in commits or disturb the user's work outside that scope. Prefer git show HEAD:<file> or git diff HEAD to inspect earlier code without disturbing the working tree or staging area.
• No session identifiers or tool footers in anything published. Commit messages end at the co-author trailer (Co-Authored-By: ...) — never append session or conversation identifiers, links back into an agent harness, or trailers of that kind (e.g. Claude-Session:) to commits, PR or issue bodies, comments, release notes, or any committed file. Do not add "Generated with ..." footers or tool badges to PRs or issues either; the co-author trailer is the only attribution that belongs anywhere. Harness trailers found in existing git history are defects, not a pattern to imitate.