docs: exempt maintainers from the public API issue-first rule

[turnipdabeets]

Problem

Port of PostHog/posthog-js#5044.

The "Public API changes" section in CONTRIBUTING.md and the matching line in AGENTS.md say the API shape must be agreed on an issue first. Nothing in either file exempts maintainers. So when a Client Libraries maintainer's agent changes public API in their own PR, it doesn't find an agreed issue and opens one. We end up closing duplicate issues and paying for the turns and tokens. For the team, the PR is where we discuss API shape.

Changes

• CONTRIBUTING.md: says the issue-first rule is for external contributors, and adds a path for contributors who already have a PR open. They call out the public API change at the top of the PR description and link or open an issue to discuss it, instead of stopping.
• AGENTS.md: agents skip the issue when the author is a PostHog maintainer (git email ends in @posthog.com). For contributors, agents stop and ask, or draft an issue body for the user to post. Agents never open an issue on their own.
• Removed the separate "AI agents: stop and ask" bullet from CONTRIBUTING.md, because AGENTS.md now covers it.

Testing

Docs only. Same wording as posthog-js#5044, which was reviewed and approved.

🤖 Generated with Claude Code

[github-actions]

posthog-ruby-sync Compliance Report

Date: 2026-09-21T14:38:38.849200+00:00
Duration: 94117ms

⚠️ Some Tests Failed

45/47 tests passed, 2 failed

---

Capture Tests

⚠️ 29/30 tests passed, 1 failed

View Details

Test	Status	Duration
Format Validation.Event Has Required Fields	✅	9ms
Format Validation.Event Has Uuid	✅	7ms
Format Validation.Event Has Lib Properties	✅	6ms
Format Validation.Distinct Id Is String	✅	9ms
Format Validation.Token Is Present	✅	8ms
Format Validation.Custom Properties Preserved	✅	6ms
Format Validation.Event Has Timestamp	✅	8ms
Format Validation.Non Utc Event Timestamp Is Converted To Utc	✅	7ms
Retry Behavior.Retries On 503	✅	5258ms
Retry Behavior.Does Not Retry On 400	✅	2010ms
Retry Behavior.Does Not Retry On 401	✅	2012ms
Retry Behavior.Respects Retry After Header	✅	8014ms
Retry Behavior.Implements Backoff	✅	15319ms
Retry Behavior.Retries On 500	✅	5150ms
Retry Behavior.Retries On 502	✅	5159ms
Retry Behavior.Retries On 504	✅	5114ms
Retry Behavior.Max Retries Respected	✅	15538ms
Deduplication.Generates Unique Uuids	✅	21ms
Deduplication.Preserves Uuid On Retry	✅	5148ms
Deduplication.Preserves Uuid And Timestamp On Retry	✅	10282ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry	✅	5156ms
Deduplication.No Duplicate Events In Batch	✅	19ms
Deduplication.Different Events Have Different Uuids	✅	9ms
Compression.Sends Gzip When Enabled	✅	6ms
Batch Format.Uses Proper Batch Structure	✅	6ms
Batch Format.Flush With No Events Sends Nothing	✅	3ms
Batch Format.Multiple Events Batched Together	❌	17ms
Error Handling.Does Not Retry On 403	✅	2007ms
Error Handling.Does Not Retry On 413	✅	2010ms
Error Handling.Retries On 408	✅	5156ms

Failures

batch_format.multiple_events_batched_together

Expected 1 requests, got 5

Feature_Flags Tests

⚠️ 16/17 tests passed, 1 failed

View Details

Test	Status	Duration
Request Payload.Request With Person Properties Device Id	✅	8ms
Request Payload.Flags Request Uses V2 Query Param	✅	7ms
Request Payload.Flags Request Hits Flags Path Not Decide	✅	6ms
Request Payload.Flags Request Omits Authorization Header	✅	7ms
Request Payload.Token In Flags Body Matches Init	✅	6ms
Request Payload.Groups Round Trip	✅	7ms
Request Payload.Groups Default To Empty Object	✅	8ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False	✅	8ms
Request Payload.Disable Geoip Omitted Defaults To False	❌	8ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key	✅	7ms
Request Lifecycle.No Flags Request On Init Alone	✅	3ms
Request Lifecycle.No Flags Request On Normal Capture	✅	6ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests	✅	10ms
Request Lifecycle.Mock Response Value Is Returned To Caller	✅	6ms
Retry Behavior.Retries Flags On 502	✅	109ms
Retry Behavior.Retries Flags On 504	✅	138ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event	✅	8ms

Failures

request_payload.disable_geoip_omitted_defaults_to_false

Field 'geoip_disable' not found in /flags request body at path 'geoip_disable'. Available keys: ['distinct_id', 'groups', 'person_properties', 'group_properties', 'flag_keys_to_evaluate', 'token']

[github-actions]

posthog-ruby-async Compliance Report

Date: 2026-09-21T14:38:53.543725+00:00
Duration: 98296ms

⚠️ Some Tests Failed

46/47 tests passed, 1 failed

---

Capture Tests

✅ 30/30 tests passed

View Details

Test	Status	Duration
Format Validation.Event Has Required Fields	✅	9ms
Format Validation.Event Has Uuid	✅	105ms
Format Validation.Event Has Lib Properties	✅	108ms
Format Validation.Distinct Id Is String	✅	107ms
Format Validation.Token Is Present	✅	107ms
Format Validation.Custom Properties Preserved	✅	107ms
Format Validation.Event Has Timestamp	✅	106ms
Format Validation.Non Utc Event Timestamp Is Converted To Utc	✅	9ms
Retry Behavior.Retries On 503	✅	5411ms
Retry Behavior.Does Not Retry On 400	✅	2109ms
Retry Behavior.Does Not Retry On 401	✅	2109ms
Retry Behavior.Respects Retry After Header	✅	8116ms
Retry Behavior.Implements Backoff	✅	15623ms
Retry Behavior.Retries On 500	✅	5212ms
Retry Behavior.Retries On 502	✅	5213ms
Retry Behavior.Retries On 504	✅	5213ms
Retry Behavior.Max Retries Respected	✅	15522ms
Deduplication.Generates Unique Uuids	✅	112ms
Deduplication.Preserves Uuid On Retry	✅	5212ms
Deduplication.Preserves Uuid And Timestamp On Retry	✅	10318ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry	✅	5215ms
Deduplication.No Duplicate Events In Batch	✅	113ms
Deduplication.Different Events Have Different Uuids	✅	109ms
Compression.Sends Gzip When Enabled	✅	107ms
Batch Format.Uses Proper Batch Structure	✅	107ms
Batch Format.Flush With No Events Sends Nothing	✅	4ms
Batch Format.Multiple Events Batched Together	✅	111ms
Error Handling.Does Not Retry On 403	✅	2109ms
Error Handling.Does Not Retry On 413	✅	2109ms
Error Handling.Retries On 408	✅	5213ms

Feature_Flags Tests

⚠️ 16/17 tests passed, 1 failed

View Details

Test	Status	Duration
Request Payload.Request With Person Properties Device Id	✅	108ms
Request Payload.Flags Request Uses V2 Query Param	✅	106ms
Request Payload.Flags Request Hits Flags Path Not Decide	✅	107ms
Request Payload.Flags Request Omits Authorization Header	✅	107ms
Request Payload.Token In Flags Body Matches Init	✅	106ms
Request Payload.Groups Round Trip	✅	106ms
Request Payload.Groups Default To Empty Object	✅	106ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False	✅	106ms
Request Payload.Disable Geoip Omitted Defaults To False	❌	106ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key	✅	106ms
Request Lifecycle.No Flags Request On Init Alone	✅	3ms
Request Lifecycle.No Flags Request On Normal Capture	✅	106ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests	✅	109ms
Request Lifecycle.Mock Response Value Is Returned To Caller	✅	107ms
Retry Behavior.Retries Flags On 502	✅	250ms
Retry Behavior.Retries Flags On 504	✅	208ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event	✅	107ms

Failures

request_payload.disable_geoip_omitted_defaults_to_false

Field 'geoip_disable' not found in /flags request body at path 'geoip_disable'. Available keys: ['distinct_id', 'groups', 'person_properties', 'group_properties', 'flag_keys_to_evaluate', 'token']

[greptile-apps]

The documentation is safe to merge after replacing the unreliable git-email maintainer check; the current issue is non-blocking but undermines the change’s intended workflow.

_{Reviews (1) · Last reviewed commit: "docs: exempt maintainers from the public..."}

[greptile-apps]

Git email misidentifies maintainers

The @posthog.com check treats maintainers who commit with GitHub noreply or personal addresses as external contributors. This causes agents to request the duplicate issues this change is intended to prevent. Determine maintainer status from the PR author's verified GitHub identity or team membership instead.

Prompt To Fix With AI

This is a comment left during a code review.
Path: AGENTS.md
Line: 5

Comment:
**Git email misidentifies maintainers**

The `@posthog.com` check treats maintainers who commit with GitHub noreply or personal addresses as external contributors. This causes agents to request the duplicate issues this change is intended to prevent. Determine maintainer status from the PR author's verified GitHub identity or team membership instead.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[dustinbyrne]

The maintainer exemption looks good. One non-blocking clarification about identifying maintainers.

AI-assisted review: source inspection and existing CI; no new tests executed.

[dustinbyrne]

Minor (non-blocking): Could we treat @posthog.com as one signal of maintainer status rather than the exclusive test? A confirmed Client Libraries maintainer can use a GitHub noreply address, which sends them through the external-contributor issue-first flow despite the exemption in CONTRIBUTING.md. Consider accepting independently confirmed maintainer identity too.