docs: add generic agent onboarding and handoff guidance

docs/agent-handoffs/README.md

@@ -0,0 +1,19 @@
+# Agent Handoffs
+
+This folder stores reusable learnings that help future agents work faster and safer.
+
+## Folders
+
+- `learnings/`: patterns that worked and can be reused.
+- `incidents/`: failures, root causes, and prevention notes.
+
+## Filename format
+
+Use: `YYYY-MM-DD-short-topic.md`
+
+Examples:
+
+- `2026-02-14-command-ordering.md`
+- `2026-02-14-lock-timeout-regression.md`
+
+Keep names generic and descriptive.

docs/agent-handoffs/incidents/2026-02-14-example-incident.md

@@ -0,0 +1,7 @@
+# Example Incident: Missing Baseline Context
+
+- **Context:** Agent started editing without reviewing policy files first.
+- **Observation:** Resulting patch required rework to match repo standards.
+- **Action taken:** Re-read policy docs, reverted conflicting edits, reapplied changes correctly.
+- **Validation performed:** Compared final output to policy docs and reran checks.
+- **Recommendation for next agents:** Read `AGENTS.md` and `CLAUDE.md` first on every run to avoid avoidable churn.

docs/agent-handoffs/learnings/2026-02-14-example-learning.md

@@ -0,0 +1,7 @@
+# Example Learning: Validation Before Summary
+
+- **Context:** Multi-file documentation update.
+- **Observation:** Running quick checks before writing summaries catches avoidable mistakes.
+- **Action taken:** Ran status and diff checks before finalizing.
+- **Validation performed:** Confirmed expected files changed and no accidental edits were included.
+- **Recommendation for next agents:** Always run at least one verification command after edits and before committing.