Introduces `AGENTS.md` (+ Simplified Chinese mirror) as this repo's
rules for AI-agent-assisted contributions, along with pointers from
`CONTRIBUTING` and a PR-template checklist item.

`AGENTS.md` is the de-facto standard filename that agent tools (Claude
Code, Codex, Cursor, Devin, etc.) pick up automatically, so agents on
external forks get these rules without extra setup.

### What the guidelines cover

1. **Motivation first** — every non-trivial change must answer four
questions (what can't be done today, who needs it, why in core rather
than an interceptor/adapter/transformer/plugin, cost). `Closes #NNNN`
alone does not count as prior discussion — the referenced issue must
show maintainer buy-in. One PR = one concern.
2. **Mandatory, effective, non-duplicated tests** — tests must fail
without the change; coverage minimum is a floor, not a target; no
test-theater for coverage numbers.
3. **Compatibility is sacred** — additive-by-default; deprecations with
`Use XXX instead. This will be removed in X.0.0` targeting the next
major (X is a placeholder — pick the actual next major from the affected
package's `pubspec.yaml`); no SDK-lower-bound bumps outside the
Compatibility Policy; watch behavioral breaks. Explicit
**sensitive-area** list (SSL/TLS + cert pinning, redirects, cookies,
headers, timeout/cancellation/connection pooling, interceptor pipeline,
request-body encoding) and **dependency-change** rules (no drive-by
bumps; state motivation; narrowest constraint; disclose new
transitives).
4. **Understand before you change** — no API guessing; cross-platform
pub-cache paths + `PUB_CACHE` env var.
5. **Production quality only** — no
`TODO`/mock/simplified-and-called-done code.
6. **When to stop and ask** — general rule for ambiguity and
out-of-scope work, distinct from §3's breaking-change escalation.
7. **Repository layout** — Melos mono-repo, per-package SDK lower
bounds.
8. **Commits, changelog, and PR hygiene**
   - §8.1 **Branch naming** — `category/ticket-id-or-short-description`
- §8.2 **Commit format** — gitmoji **or** Conventional Commits (either
is acceptable) with an emoji reference table matched to the repo's
actual usage
- §8.3 **AI attribution mandatory** — every contributing agent gets a
`Co-Authored-By:` trailer; the PR body discloses agent + stage (design /
implementation / tests / review)
   - §8.4 CHANGELOG rules
- §8.5 **Self-review your diff and commit message** — remove debug
prints, commented code, unrelated formatting; `git add .` / `-A`
forbidden; re-read the commit message against the staged diff so a
message from a prior attempt doesn't land verbatim
- §8.6 **Opening the PR** — draft PRs for large/exploratory changes;
**describe verification honestly** in prose rather than a boilerplate
"Test plan" checklist; anything genuinely un-verifiable goes under an
`Unverified` paragraph
- §8.7 **Review iteration** — append commits (no squash-force-push
mid-review); no close/reopen to reset state; design feedback is
conversation, not instruction; CI failures require log-reading, not
retry-until-green
9. **Patterns that may lead to closure** — cross-reference table linking
each anti-pattern back to the rule it violates, softened wording (`may`
/ `might`).

### Iteration notes

Follow-ups after the initial commit addressed:

- **@AmosHuKe** (first round) — cross-platform pub-cache paths and
`PUB_CACHE`, `「包」 → package` in the Chinese version, mainland-accessible
Melos URL, softened minor-version breaking-change wording per dio's own
CHANGELOG preamble.
- **@AmosHuKe** (second round) — the concrete `6.0.0` in the deprecation
example could mislead agents that don't check `pubspec.yaml`; replaced
with an `X.0.0` placeholder plus a note to derive the real next major
from the affected package.
- **@CaiJingLong via GLM-5.2** (first round) — expanded the workflow
gaps GLM flagged (commit format, self-review, review iteration,
when-to-ask, sensitive areas, dependency rules, branch naming, draft
PRs); collapsed the "patterns that may lead to closure" section from a
full restatement of §§1–8 into a cross-reference table.
- **@AlexV525** direct edit — softened §8.2 from "gitmoji **and**
Conventional Commits" to "gitmoji **or** Conventional Commits", matching
the actual mix in `git log` (recent commits use one or the other, not
both).
- **@CaiJingLong via GLM-5.2** (re-review) — flagged a duplicated §8.7
block (removed), a garbled §8.2 sentence in the English version
(rewritten to match the ZH), the `🥅` gitmoji being frequent in the repo
but missing from the reference table (added), and a missing §5 row in
the closure cross-reference table (added).
- **Self-application** — the "re-read the commit message against the
staged diff" clause in §8.5 was added after an actual near-miss on this
branch, where a stale message (`Fix deprecation hints`) was almost
applied to a different fix. Documenting the source in the commit and the
doc keeps the rule from looking arbitrary.
- **Stress-tested against #2556** (opened by @CaiJingLong via GLM-5.2 +
Devin right after this PR) — that PR validated the branch-naming
convention and motivated the "describe verification honestly" rule in
§8.6, after its Test-plan section carried a well-intentioned but
misleading "existing tests still cover" note on an untested new code
path.

### Files

- `AGENTS.md` — English rules
- `AGENTS-ZH.md` — Simplified Chinese mirror
- `CONTRIBUTING.md` / `CONTRIBUTING-ZH.md` — link to the new guidelines
- `.github/PULL_REQUEST_TEMPLATE.md` — checklist item pointing to
`AGENTS.md`

### Verification

Documentation change; no code paths to exercise. All internal
`§`-references were grep-verified for consistency after each renumbering
pass. The gitmoji reference table in §8.2 was cross-checked against the
last 300 commits (`git log --pretty=format:'%s' -300 | grep -oE
'^[^A-Za-z0-9 (]+' | sort | uniq -c`) to ensure the emojis it endorses
match the repo's real usage frequency.

---------

Co-authored-by: Claude <[email protected]>