docs: establish clean agent branches and default-branch targeting [skip ci]

AGENTS.md

@@ -0,0 +1,11 @@
+# Agent instructions
+
+## Branch and pull-request hygiene
+
+These rules apply to agents working in this repository. Follow repository-specific review, release, and branch-protection policies as well.
+
+1. **Target the actual default branch.** Read the repository's configured default branch before starting (`gh repo view --json defaultBranchRef --jq .defaultBranchRef.name`, or equivalent). Normally it is `main` or `master`, but never guess. Base ordinary change PRs on that branch and keep them up to date with it. Use a release/maintenance branch only when the task or repository policy specifically requires one. Aim to land approved work in the configured default branch; do not merge without the required authorization, reviews, and passing checks.
+2. **Start clean and branch only when needed.** Check `git status` and existing worktrees first; preserve others' uncommitted work. Fetch the default branch, then make one clearly named, short-lived branch (or isolated worktree) per coherent change. Reuse that branch for revisions instead of creating duplicate or speculative branches. Never reset, force-push, or stash away someone else's work to make the checkout look clean.
+3. **Keep work reviewable.** Push only the scoped changes to the work branch, open a PR against the correct base, and keep the branch while its PR is open or other work depends on it. Do not push directly to a protected default branch or bypass approvals.
+4. **Clean up after a verified merge.** Confirm the PR really merged and its changes landed before deleting anything; a squash/rebase merge may not make the old branch an ancestor. Check that the branch is not protected, shared, used by another open PR, or carrying unmerged commits. Then delete only the completed work's remote branch (using the PR's delete-branch option when appropriate), switch away from and remove only its local branch/worktree, and prune stale remote-tracking refs. Never delete the configured default branch, release branches, forks, or anyone else's work.
+5. **Leave a clean environment.** At handoff, check for uncommitted changes and leftover branches/worktrees created for this task; either clean up safely or report precisely what must remain and why. If a merge or deletion is not authorized or cannot be proven safe, leave the branch intact and explain the blocker rather than guessing.