docs: add generic agent onboarding and handoff guidance

AGENTS.md

@@ -0,0 +1,69 @@
+# AGENTS.md
+
+Repository-wide instructions for any autonomous or semi-autonomous coding agent.
+
+## Purpose
+
+This repository is intended to be reusable across many projects. Keep changes and documentation generic unless you are actively working inside a specific downstream repo that requires project-specific customization.
+
+## Startup checklist (every run)
+
+1. Read this file (`AGENTS.md`).
+2. Read `CLAUDE.md` for operating conventions.
+3. Read `CONTRIBUTING.md` for commit/PR quality expectations.
+4. Check `KNOWN_ISSUES.md` before making changes.
+5. If present, check `docs/agent-handoffs/` for recent agent learnings.
+
+## Generic-first policy
+
+- Do not hardcode organization, product, customer, or brand-specific details.
+- Do not assume a single deployment environment unless explicitly configured.
+- Prefer neutral names such as `project`, `service`, `integration`, `consumer`, `provider`.
+- Add project-specific notes only when working in that project's repo and label them clearly.
+
+## Agent learning + handoff protocol
+
+Agents are expected to leave concise, reusable notes for later agents.
+
+### Where to write
+
+- `docs/agent-handoffs/README.md` for folder usage.
+- `docs/agent-handoffs/learnings/` for new practical learnings.
+- `docs/agent-handoffs/incidents/` for issue/incident writeups and mitigations.
+
+### Naming convention
+
+Use generic, descriptive filenames:
+
+- `YYYY-MM-DD-short-topic.md` (example: `2026-02-14-lock-timeout-tuning.md`)
+
+Avoid brand, team, or person-specific prefixes in filenames.
+
+### Required note structure
+
+Each note should contain:
+
+- Context
+- Observation
+- Action taken
+- Validation performed
+- Recommendation for next agents
+
+Keep each note short and actionable.
+
+## Safety and quality baseline
+
+- Make smallest safe change first.
+- Prefer explicit commands over assumptions.
+- Validate with available tests/checks.
+- If blocked by environment limits, document the blocker and fallback.
+
+## Priority order
+
+When instructions conflict, follow this order:
+
+1. System/developer/user instructions in-session
+2. `AGENTS.md`
+3. `CLAUDE.md`
+4. `CONTRIBUTING.md`
+5. Inline comments and prompt files