Plan 010: Add AGENTS.md so agent executors know the house rules

[duyetbot]

Plan 010: Add AGENTS.md so agent executors know the house rules

Executor instructions: Follow this plan step by step. Run every
verification command and confirm the expected result before moving to the
next step. If anything in the "STOP conditions" section occurs, stop and
report — do not improvise. When done, update the status row for this plan
in plans/README.md — unless a reviewer dispatched you and told you they
maintain the index.

Drift check (run first): ls AGENTS.md CLAUDE.md 2>/dev/null
If either file now exists, STOP — this plan is moot; report that.

Status

• Priority: P3
• Effort: S
• Risk: LOW (docs only)
• Depends on: none
• Category: dx/docs
• Planned at: commit 61ee3c7, 2026-08-26

Why this matters

Most changes to this repo are written by coding agents (the maintainer's own
tooling and CI assume it), yet the repo ships no AGENTS.md/CLAUDE.md.
Every session re-derives the same facts — build/test commands, the 0.1.x
version lock, the release-please no-auto-merge rule, the binary-size budget,
key-redaction conventions — from README + workflow files, and occasionally
gets them wrong (e.g. bumping minor versions, merging release PRs). A short,
stable rules file removes that tax and encodes the invariants.

Current state

• No AGENTS.md, no CLAUDE.md anywhere in the repo.
• Facts the file must capture (all verifiable today):
  • Build/test/lint: cargo test --locked --all-targets; cargo clippy --locked --all-targets;
    cargo fmt --check. Size gate: python scripts/bench.py measure … ≤ 4.0 MiB stripped linux-x86_64.
  • Version lock 0.1.x: Cargo.toml, package.json,
    .release-please-manifest.json stay on 0.1.x; "versioning": "always-bump-patch"
    in release-please-config.json means feat! still bumps patch only.
  • Never auto-merge release-please PRs (human merges).
  • Conventional commits; .githooks/prepare-commit-msg appends two
    Co-authored-by trailers; opt-out with ANYR_SKIP_COAUTHORS=1.
  • Never print full API keys (sk-ar-v1-…) or relay tokens (rk_…) in
    output/tests — mask with mask_api_key; tests assert redaction (e.g.
    upgrade_does_not_print_full_sk_ar_key).
  • Config lives at ~/.anyrouter/config.yaml shared with the TS CLI — field
    names are a cross-tool contract (relay_token, relay_device_id).
  • wasm job builds with --no-default-features; keep new code compiling
    there when adding deps to non-native paths.
• Style guidance for the file itself: short, imperative, pointer-heavy
  (<80 lines). The maintainer's convention elsewhere is "tiny router files +
  pointers", not architecture dumps.

Commands you will need

Purpose	Command	Expected on success
Verify facts still hold	grep -n "always-bump-patch|always_bump_patch" release-please-config.json	≥1 match
Markdown renders	head -5 AGENTS.md	shows title

Scope

In scope:

• AGENTS.md (create)

Out of scope:

• README edits, CONTRIBUTING, any code.

Git workflow

• Branch: advisor/010-agents-md
• Commit style: e.g. docs: add AGENTS.md with repo invariants for coding agents
• Do NOT push or open a PR.

Steps

Step 1: Write AGENTS.md

Sections (keep total <80 lines):

1. What this is — one sentence: native Rust CLI (anyr) for the
   AnyRouter gateway; single crate, lib+bin.
2. Commands — test/clippy/fmt/bench table with exact commands above.
3. Invariants (do not break) — version lock 0.1.x incl. always-bump-patch;
   no auto-merge of release-please PRs; binary size budget 4 MiB; config.yaml
   is a cross-tool contract (TS CLI reads it) — never rename fields;
   never print full keys/tokens; keep wasm (--no-default-features) compiling.
4. Conventions — conventional commits; co-author hook; error strings are
   human sentences via map_err format!; inline #[cfg(test)] per module;
   integration tests spawn CARGO_BIN_EXE_anyr with fresh ANYROUTER_HOME.
5. Gotchas — ratatui/crossterm exact-pinned on purpose; npm @latest stays
   at old JS CLI until human retags; beta prereleases come from ci.yml matrix.

Write it in plain imperative English matching the tone of README.md.

Step 2: Cross-check every claim

For each invariant line, confirm against the live repo (greps above plus your
own). Fix the doc if reality disagrees — the doc describes the repo, not
wishes.

Verify: manual checklist in commit body listing each claim → source file.

Test plan

None (docs). Optional sanity: tests/release_lock.rs already asserts some of
these invariants in code — cite it in AGENTS.md as the enforcement point.

Done criteria

ALL must hold:

• AGENTS.md exists at repo root, <100 lines.
• Every command mentioned appears verbatim-working (run cargo fmt --check && cargo test --locked --test release_lock once).
• No secrets/hostnames beyond what's already public in README.
• Only AGENTS.md added.

STOP conditions

Stop and report if:

• An AGENTS.md or CLAUDE.md appeared meanwhile.
• Any "fact" above contradicts the current repo in a way you can't resolve
  by checking sources (list the contradiction).

Maintenance notes

• Keep it a router: when a rule needs >2 sentences of explanation, link the
  authoritative file instead of expanding here.
• Reviewer: verify no duplication drift risk — each fact stated once, here.