From 42376631097186b24f6e44669ef19eb50c71b4ae Mon Sep 17 00:00:00 2001
From: Anna Garcia <anna.g@posthog.com>
Date: Fri, 11 Sep 2026 10:10:37 -0400
Subject: [PATCH 1/2] docs: agree on public API changes before implementing
 them

---
 AGENTS.md       |  4 ++++
 CONTRIBUTING.md | 12 ++++++++++++
 2 files changed, 16 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..297cb8c5
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,4 @@
+# AGENTS.md
+
+- Read and follow [CONTRIBUTING.md](./CONTRIBUTING.md) before contributing to the SDK. It covers local checks, build checks, and testing against local native SDKs.
+- Before adding or changing public API, follow "Public API changes" in [CONTRIBUTING.md](./CONTRIBUTING.md): the API shape must be agreed on the issue first. For SDK design guidance, read https://posthog.com/handbook/engineering/sdks/guidelines.md.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0c8677af..262c63e6 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -77,3 +77,15 @@ Gradle substitutes `com.posthog:posthog(-android)` with the local source regardl
 of the version floor, so no publishing or `mavenLocal()` is needed. As a fallback you
 can still `make dryRelease` in `posthog-android` (add `-PandroidVersion=<floor>` so the
 published version satisfies the floor) and add `mavenLocal()` to the repositories.
+
+## Public API changes
+
+Public API is hard to change once it ships, so agree on it before writing the implementation. Our [SDK guidelines](https://posthog.com/handbook/engineering/sdks/guidelines) explain how we design it.
+
+- If you need something the SDK doesn't support and it would add or change a public option, method, or type, open an issue describing your use case first. At this stage, context is more useful to us than code.
+- Wait for a maintainer to agree on the API shape on the issue before implementing it.
+- Check first whether an existing option or hook, such as `beforeSend`, already covers the use case. We avoid offering two ways to do the same thing.
+- If a reviewer suggests a different API on your PR, confirm it with them before re-implementing. Treat it as a question, not an instruction.
+- AI agents: stop and ask before implementing a public API change that hasn't been agreed on the issue.
+
+`make updateApiDart` regenerates `api/posthog_flutter.api.json`, and CI runs `make checkApiDart` to catch an outdated snapshot. A diff in that file means your change touches public API.

From 993ccb633a9a73edb5c19396d8d858cac5718272 Mon Sep 17 00:00:00 2001
From: Anna Garcia <anna.g@posthog.com>
Date: Fri, 11 Sep 2026 10:17:47 -0400
Subject: [PATCH 2/2] docs: point agents to RELEASING.md and keep guidance in
 one place

---
 AGENTS.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index 297cb8c5..9e372678 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,4 +1,6 @@
-# AGENTS.md
+# Agent Instructions
 
 - Read and follow [CONTRIBUTING.md](./CONTRIBUTING.md) before contributing to the SDK. It covers local checks, build checks, and testing against local native SDKs.
+- Read and follow [RELEASING.md](./RELEASING.md) when adding changesets or working on publishing.
 - Before adding or changing public API, follow "Public API changes" in [CONTRIBUTING.md](./CONTRIBUTING.md): the API shape must be agreed on the issue first. For SDK design guidance, read https://posthog.com/handbook/engineering/sdks/guidelines.md.
+- Keep shared development guidance in `CONTRIBUTING.md` and release guidance in `RELEASING.md` rather than duplicating it here.