Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

chore(agents): move topic rules out of the root agents file (#127194)

Michael Reichenbach47d11378f8d0
diff --git a/.agents/agent-automation.md b/.agents/agent-automation.md
new file mode 100644
index 000000000000..820696988e59
--- /dev/null
+++ b/.agents/agent-automation.md
@@ -0,0 +1,12 @@
+# Agent automation
+
+When automating a convention, try these in order — only fall back to the next if the previous isn't suitable:
+
+1. **Linters** (ruff, oxlint, semgrep) — code pattern enforcement, always paired with CI
+2. **lint-staged / husky** — file-level validation or warnings at commit time
+3. **Skills** (`.agents/skills/`) — scaffold with `hogli init:skill`
+4. **AGENTS.md / CLAUDE.md instructions** — when automated enforcement isn't suitable
+
+Claude Code hooks are reserved for environment bootstrapping (`SessionStart` only) — do not add `PreToolUse`, `PostToolUse`, or `Notification` hooks as they add latency and are fragile.
+Changes to `.claude/hooks/` trigger a warning from the `pre-commit` hook; lint-staged allows only repo-wide keys in `.claude/settings.json`, because personal settings belong in the gitignored `.claude/settings.local.json`.
+A warn-only check belongs in the `pre-commit` hook body rather than in a lint-staged task, because lint-staged discards the output of every task that exits 0.
diff --git a/.agents/architecture.md b/.agents/architecture.md
new file mode 100644
index 000000000000..cf374bef750e
--- /dev/null
+++ b/.agents/architecture.md
@@ -0,0 +1,56 @@
+# Architecture guidelines
+
+Each rule is tagged with what catches a violation.
+`[lint: <id>]` means a linter, semgrep rule, or invariant test blocks it, so CI is the check and this text is only the reasoning.
+`[review]` means nothing catches it automatically — a reader is the only control.
+
+## Entrypoints and layering
+
+- **Keep entrypoints thin.** `[review]` The runtime calls the entrypoint first: a DRF view, a management command `handle()`, a Celery task body, an HTTP handler, a Rust `main()`, a React component. An entrypoint reads the input, connects the dependencies, and formats the output. All other logic goes in a function the entrypoint calls, so a test can call it directly. If the area already has a place for that logic, use it rather than making a new one.
+- **A product under `products/` is scaffolded, not hand-rolled.** `[lint: hogli product:lint --all]` Create one with `hogli product:bootstrap <name>`, because the scaffold emits a product that is isolated from its first commit. See "New products must be isolated" in [products/README.md](../products/README.md) for the isolation rules, and [products/architecture.md](../products/architecture.md) for facade and contract design.
+- **Code a single product owns belongs under `products/<product>/`** — backend, frontend, scripts, CLIs, services, packages, MCP tools, skills. `[review]` Reserve top-level `tools/`, `services/`, `packages/`, `cli/` and `hog/` for cross-product things. `product:lint` only scans `products/`, so a single-product feature parked in a top-level directory is invisible to it.
+
+## Tenancy and scoping
+
+- **Every tenant-data model must have `team_id`**, as a FK to `posthog.Team` or a plain `BigIntegerField` for multi-DB products. `[lint: idor-lookup-without-team, check-idor-model-coverage.py]` This is the primary tenant isolation boundary. New models inherit `TeamScopedRootMixin` (main DB) or `ProductTeamModel` (separate DB) so they start fail-closed — see [posthog/models/scoping/README.md](../posthog/models/scoping/README.md).
+- **Classifying a model as unscoped is a review decision, not a checked one.** `[review]` A model without `team_id` must be org-scoped, user-scoped, or instance-global, never silently unscoped. `check-idor-model-coverage.py` only warns when a name lands in `NEEDS_TEAM_ID`, and passes silently for `LEGITIMATELY_UNSCOPED`, so a wrongly exempted tenant model reaches master unless a reader catches it.
+- **Reading a fail-closed model outside request context** — Temporal activities, Celery tasks, management commands — uses `Model.objects.for_team(team_id)`. `[review]` Not `Model.all_teams.filter(team_id=...)` and not `objects.unscoped().filter(...)`; those are for genuinely cross-team access and Django internals. In serializers the team comes from `self.context["get_team"]()`. Caveat: `for_team(...).get_or_create(...)` and `.create(...)` still need `team_id` passed explicitly, because a queryset filter does not propagate into row creation.
+- **Do not add domain-specific fields to the `Team` model.** `[review]` Use a Team Extension model — see [posthog/models/team/README.md](../posthog/models/team/README.md) for the pattern and helpers.
+
+## Person and group data
+
+- **All person/group access goes through the personhog client.** `[review]` Never query these via the Django ORM or raw SQL: `posthog_person`, `posthog_persondistinctid`, `posthog_cohortpeople`, `posthog_group`, `posthog_grouptypemapping`, and the override tables (`posthog_personoverride`, `posthog_pendingpersonoverride`, `posthog_flatpersonoverride`, `posthog_featureflaghashkeyoverride`, `posthog_personlessdistinctid`, `posthog_personoverridemapping`). Use the routed helpers in `posthog/models/person/util.py` and `posthog/models/group_type_mapping.py`. New access follows the same `_personhog_routed()` pattern: a `personhog_fn` using `get_personhog_client()`, plus an `orm_fn` fallback. See [posthog/personhog_client/README.md](../posthog/personhog_client/README.md).
+- **Personhog answers identity questions only.** `[review]` Use it for resolving distinct IDs, point lookups by person id or UUID, and lifecycle writes. Person properties, list hydration, and search come from ClickHouse (HogQL over `persons`, `ActorsQueryRunner`). Avoid reading `properties` from personhog — the API will stop surfacing it. Single-person lookups that need properties are exempt only while no ClickHouse primitive covers them, never in bulk. See [docs/internal/person-data-access.md](../docs/internal/person-data-access.md).
+
+## Transactions and locking
+
+- **There is no implicit per-request transaction** — PostHog does not enable `ATOMIC_REQUESTS`. `[review]` Every operation runs in autocommit unless wrapped. Put `with transaction.atomic():` around the specific writes that must succeed or fail together, never around a whole view method. Keep irreversible side effects out of the block: an email sent or an API called before a rollback has already happened. Schedule them after the commit, or dispatch Celery tasks with `transaction.on_commit()`.
+- **Do not use `Team` or `Organization` rows as mutexes.** `[lint: hot-parent-row-select-for-update]` PostgreSQL takes `KEY SHARE` locks on parent rows for foreign-key checks, and `FOR UPDATE` conflicts with them, so an unrelated child-row write can wait behind a transaction holding a hot parent row. Lock the product's `Team<Product>Config` extension row instead, reached through `get_or_create_team_extension` so the row exists first. For a per-team count limit or number allocation, use a unique constraint, a conditional update, or a dedicated allocation row. Otherwise lock the quiet child row, or take a transaction-scoped advisory lock. Lock `Team` or `Organization` only when the transaction updates or deletes that row, and keep it short — no network calls, no input-sized loops. Each exception needs a short `nosemgrep` justification.
+
+## API schemas and generated types
+
+- **API views declare request/response schemas.** `[review]` Prefer `@validated_request` from `posthog.api.mixins`, or `@extend_schema` from drf-spectacular. A plain `ViewSet` method that validates manually needs `@extend_schema(request=YourSerializer)`; without it drf-spectacular cannot discover the request body and generated code gets an empty schema. Serializer fields need `help_text`. These flow into both frontend types and MCP tool schemas.
+- **Django serializers are the source of truth for frontend API types.** `[lint: build:openapi CI gate, prefer-codegen-api, test_generated_files_are_registered.py]` `hogli build:openapi` generates TypeScript via drf-spectacular and Orval into `frontend/src/generated/core/` and `products/{product}/frontend/generated/`. Never hand-edit `api.schemas.ts`, `api.ts` or `api.zod.ts` — change the serializer and regenerate. A value list the frontend needs comes from a typed serializer field, not from a side script; other checked-in projections are entries in `tools/hogli-commands/hogli_commands/projections.py`. [Type system guide](../docs/published/handbook/engineering/type-system.md) has the full pipeline.
+- MCP tools and MCP UI apps are generated from the same OpenAPI spec. `[review]` See [implementing MCP tools](../docs/published/handbook/engineering/ai/implementing-mcp-tools.md) covers the YAML config and codegen. MCP UI apps live in `products/*/mcp/tools.yaml` under `ui_apps` — see [services/mcp/CONTRIBUTING.md](../services/mcp/CONTRIBUTING.md) or `/implementing-mcp-ui-apps`.
+
+## Async, storage and outbound calls
+
+- **Do not use `posthoganalytics.capture()` in a Celery task** — events are silently lost. `[review]` Use `ph_scoped_capture` from `posthog.ph_client`; its docstring explains why.
+- **Temporal activity payloads cap at ~2 MiB — pass large data by reference.** `[review]` Activity inputs and outputs cross a gRPC boundary the server rejects above that (`blobSizeLimitError`). As a field-level rule: if a field could exceed ~256 KB serialized (query results, exported file contents, LLM context, rendered HTML, image bytes, unbounded `list[dict[str, Any]]`), write it to Postgres or object storage from inside the activity and return only the row ID or S3 key. The workflow already has any ID created earlier in the run. Shuttling large data through the workflow produces `PayloadSizeError` (`TMPRL1103`) as soon as the data crosses the limit.
+- **A Python `requests` call to GitHub or Slack under `common/`, `ee/`, `posthog/` or `products/` goes through `posthog/egress/`.** `[lint: github-api-calls-go-through-egress, slack-api-calls-go-through-egress]` Route it through the gated, recorded transport.
+- **Every other call to those hosts goes through `posthog/egress/` too.** `[lint: github-api-calls-go-through-egress-wide, slack-api-calls-go-through-egress-wide]` The wide rules catch a URL bound to a variable or constant, `requests.Session`, `httpx`, `aiohttp`, `urllib.request`, and an aliased Slack SDK client. Another language, another vendor SDK, or a caller under `tools/` still passes CI, so a reader is the only control there.
+- **Any other third-party API that needs rate-limiting or egress telemetry belongs there too.** `[review]` Add a `<domain>/` incarnation (GitHub is the reference). No semgrep rule covers a new domain, so a raw client for one reaches master unless a reader catches it. `/routing-outbound-api-calls` decides the route and names the reference domain to copy.
+- **Object storage is SeaweedFS — do not add new MinIO dependencies.** `[review]` Both S3-compatible stores are SeaweedFS: `objectstorage` (`:19000`, `OBJECT_STORAGE_*`) for general storage, `seaweedfs` (`:8333`, `SESSION_RECORDING_V2_S3_*`) for session replay v2. MinIO survives only as one-off salvage tooling: `bin/migrate-storage-hobby` starts a temporary container to read an old hobby MinIO volume. Do not add compose services, scripts, tests or docs that stand up a `minio/minio` container. Talk to storage through the existing config and a standard S3 client, never a hardcoded endpoint. Note `objectstorage` registers credentials at runtime and returns `InvalidAccessKeyId` until that finishes, so wait for its readiness sentinel rather than the container start.
+- **A new DNS-resolution or outbound-host entry point calls the shared out-of-band domain check.** `[lint: test_oob_denylist_coverage.py]` Every host guard here is IP-based, and an out-of-band interaction domain resolves to an ordinary public IP, so a resolver that skips the check restores the gap in silence. The list and the edit procedure live in `posthog/security/crosslang/`.
+
+## Configuration and secrets
+
+- **A key in `posthog/settings/dynamic_settings.py` exists only because operators must change its value live, without a deploy.** `[review]` These instance settings are Postgres rows that staff edit at runtime, and a stored row overrides the environment variable. Kill switches and tuning knobs for incidents qualify. Secrets and static config are environment variables read in `posthog/settings/`, with values from the deployment secret store and charts. Never store a secret as an instance setting, because the database keeps it as plain text. A per-team rollout or a team allowlist is a feature flag.
+
+## Django admin
+
+- **A new `ForeignKey`/`OneToOneField` on an admin-exposed model needs explicit widget config.** `[review]` List the field in `autocomplete_fields`, `raw_id_fields`, or `readonly_fields` on **every** admin class that renders the model, including inlines attached to a related admin. Otherwise the default `<select>` loads the entire target table per row on each change-page render. Declare it on a shared base inline so per-parent variants inherit it.
+
+## LLM gateway
+
+- **`services/llm-gateway` is under an unofficial code freeze** while callers move to [`PostHog/ai-gateway`](https://github.com/PostHog/ai-gateway). `[review]` If a task asks you to change it, tell the user about the freeze in your reply. New callers and features belong on the Go gateway. A Python gateway change needs a documented parity blocker for an active caller and stays limited to it — read [`services/llm-gateway/PARITY.md`](../services/llm-gateway/PARITY.md). Its Postgres role reads only allowlisted tables: a new table read needs the SELECT grant landed in posthog-cloud-infra for every environment first, then a declaration in `required_tables.py`. The readiness probe checks every declared grant on every probe, so a missing grant holds a rollout instead of serving 500s. Use `/auditing-llm-gateway-parity` for contract changes, `/finding-llm-gateway-migration-candidates` to pick the next caller, `/migrating-llm-gateway-callers` to move one.
diff --git a/.agents/ci.md b/.agents/ci.md
new file mode 100644
index 000000000000..8fd39fd8c84e
--- /dev/null
+++ b/.agents/ci.md
@@ -0,0 +1,8 @@
+# CI and GitHub Actions
+
+- `.nvmrc` controls the Node.js version for all CI workflows (via `actions/setup-node`) — changing it affects every CI job that runs Node
+- CI uploads test results to Trunk Flaky Tests; the `trunk` MCP server in `.mcp.json` queries per-test flakiness on a PR or `master` (authenticate via `/mcp`, or a `TRUNK_API_TOKEN` bearer header when headless) — see `/debugging-ci-failures` and `/fixing-flaky-tests`
+- **A workflow edit reaches every open PR before those branches rebase.** It runs against the PR merged with master, but a companion change — a new dependency, file, or config — only arrives when the branch rebases. A workflow that starts requiring something unrebased branches lack fails every in-flight PR before its tests run. Make the new behavior degrade gracefully, or gate it. This has broken CI repeatedly.
+- Mechanical workflow rules (`timeout-minutes`, concurrency, dispatch budget, path filters, gate hygiene) are enforced by `hogli lint:workflows` and actionlint, which are the source of truth. `/authoring-ci-workflows` explains the reasoning behind each.
+- **A directory of tests that read event properties belongs in `.github/new-events-schema-targets.txt`.** Backend CI reruns the listed paths against the native-JSON events table. A test outside the list runs on the legacy table only. Add the `test-new-events-schema` label when a diff needs the whole backend suite on both tables, such as an event ingestion change or event reads tested outside the list. Label while the PR is a draft, or push again after labeling, because label events do not start Backend CI.
+- **A pull request never publishes a package or release.** `[lint: github-actions-publish-on-pull-request]` A published version is public forever, and a pull request run executes code its author controls. Publish only from a `push` to `master`, a release tag, or a `workflow_dispatch` on `master`. A pull request run only builds and validates, for example with `--dry-run`. The semgrep rule cannot see a publisher inside a reusable workflow, so gate that job in the called workflow too. Never run a publish command by hand from a pull request branch. [`build-hogql-parser-npm.yml`](../.github/workflows/build-hogql-parser-npm.yml) is the reference shape.
diff --git a/.agents/code-style.md b/.agents/code-style.md
new file mode 100644
index 000000000000..145cfa5c087e
--- /dev/null
+++ b/.agents/code-style.md
@@ -0,0 +1,40 @@
+# Code style
+
+Each rule is tagged with what catches a violation, as in [architecture.md](architecture.md).
+`[lint: <id>]` is machine-enforced. `[review]` is not.
+
+## Python
+
+- **Write as if mypy `--strict` were on.** `[review]` Annotate every signature, avoid `Any`, put type-only references under `TYPE_CHECKING`. The config is not fully strict yet; new code should be. When a change is type-risky run mypy the way CI does — `uv run mypy .`, repo-wide, never a file subset. It follows imports, so a subset misses reverse-dependency breakage.
+- **Imports stay at module level.** `[review]` ruff's `PLC0415` catches this, but `posthog/**`, `ee/**`, `common/**`, `tools/**` and most of `products/` are on grandfathered exemption lists, so CI does not block it in the trees you are most likely to be editing. Defer one only to break a true unavoidable circular import, to reference types under `TYPE_CHECKING`, or to keep a heavy or optional dependency off the import path. For the last case add a justified `# noqa: PLC0415 — keeps the heavy dep off the import path` on the line. Never blanket-suppress the rule.
+- **A stdlib `@dataclass` must declare `frozen=` explicitly.** `[lint: prefer-frozen-dataclasses, test_dataclass_defaults.py]` A bare `@dataclass` fails the ratchet; `@dataclass(frozen=False)` passes it, so intentional mutability is a choice you state.
+- **The house decorator is `@frozen` from `posthog.dataclasses`.** `[review]` Neither check prefers it over a declared stdlib `@dataclass`. Invoke `/writing-dataclasses` before adding or changing one, before returning or passing several values together, and before passing a dataclass through layers.
+- **`product:lint` and the pytest collision test say where an `__init__.py` is required, and print the fix.** `[lint: product:lint, test_pytest_module_collisions.py]` Run them rather than reasoning about it.
+- **Do not add or delete an `__init__.py` speculatively.** `[review]` Whether a directory needs one depends on what sits above it. Neither check objects to a needless one outside `products/` that creates no module-name collision, so only a reader catches that.
+- Prefer classes over loose functions unless a class genuinely does not fit. `[review]` Use `pathlib` over `os.path`. Order functions and methods so a definition appears before its first call.
+
+## Frontend
+
+- **Follow [frontend/src/AGENTS.md](../frontend/src/AGENTS.md) for all frontend work** — the main app and `products/*/frontend/` alike, since they share components and generated types. `[review]` It covers reusing Lemon/quill components instead of hand-rolling tables, badges and labels, importing generated `*Api` types instead of handwriting them, when to run typecheck and typegen, and when to read [frontend/src/platform-ux.md](../frontend/src/platform-ux.md) (before you build, edit, simplify or redesign any UI).
+- **TypeScript with explicit return types. Business logic goes in the kea logic file, not a React hook.** `[review]`
+- **Guard every network-triggering button against double submission.** `[review]` Disable it and show a loading state (`loading` / `disabledReason` on `LemonButton`, or equivalent) while the request is in flight, and reset in both the success and error paths. Applies to `<form onSubmit>`, any `onClick` that calls `api.*`, and any kea `listener` that issues a request. Wire in the in-flight state from a loader `*Loading` selector, a reducer, or local `useState`.
+- **Every surface must hold up narrow.** `[review]` The nav sidebar plus an open side panel leave a 1280px window about 520px of scene. Break on container queries, not `md:`/`lg:`/`xl:`. Wrap or truncate rather than clip, and stack halves that no longer fit. Render at a few widths before calling it done. We do not support mobile — no phone-width layouts, no touch-sized targets. See "Rule 6" in [frontend/src/AGENTS.md](../frontend/src/AGENTS.md).
+- **quill is for MCP apps, the desktop app, and the web app UI behind the `today-rail-nav` feature flag; LemonUI is for the rest of the web app.** `[review]` `today-rail-nav` gates a quill redesign of the whole web app UI, built alongside the current UI and kept behind the flag for months. Build or change UI on that path with quill, and read [frontend/src/design.md](../frontend/src/design.md) first: it holds the components, tokens and decision rules. The current UI stays on LemonUI while the flag exists: do not add quill to it or convert it in place. On that flag-off path in `frontend/src/` and `products/*/frontend/` use LemonUI, including menus — `LemonMenu` with a `LemonButton` trigger. `lib/ui/DropdownMenu` (Radix) is legacy; do not add new ones. Where quill is right, do not mix the two inside one component, and remember quill uses Base UI's `render` prop, not Radix's `asChild`. Read [primitives/AGENTS.md](../packages/quill/packages/primitives/AGENTS.md) before importing quill — it covers component choice and spacing. Charts: [/working-with-charts](skills/working-with-charts/SKILL.md) for consumers, [charts/AGENTS.md](../packages/quill/packages/charts/AGENTS.md) for library changes. DataTable and DateTimePicker: [components/AGENTS.md](../packages/quill/packages/components/AGENTS.md).
+- Use tailwind utility classes over inline styles, and `lib/dayjs` over a direct dayjs import. `[review]` oxlint warns on a `style` prop through `react/forbid-dom-props`, but a warning does not block.
+
+## Comments
+
+- **Explain _why_, not _what_,** and only where a future reader with no access to this PR or chat would otherwise be confused. `[review]` Default to one line. Python tests get no doc comments.
+- **Never log change history or chat context in code.** `[review]` No "previously did X, now does Y", no "per <task/PR>", no "changed because…", no "AI:" or "agent:" notes. That belongs in the commit message and PR description.
+- **When refactoring or moving code, keep the existing comments** unless the change actually makes them obsolete. `[review]`
+- Use ASD-STE100 Simplified Technical English: active voice, simple tenses, one idea per sentence, consistent terms. `[review]`
+
+## Tests
+
+- **Every new test must catch a realistic regression no existing test catches.** `[review]` If you cannot name that regression, do not add the test. Assert observable behavior through the public interface, not implementation details, and keep it cheap — deterministic, isolated, at the lowest level that catches the bug. See `/writing-tests`.
+- **Extend a relevant existing test rather than adding a standalone one** where practical, and parameterize variations of the same behavior (`parameterized` in Python, `test.each` in Jest). `[review]`
+- Jest: one top-level `describe` per file. `[review]` Node.js Jest: `.test.ts` by default, `.serial.test.ts` only when shared mutable infrastructure cannot be isolated (a test that resets a shared database).
+
+## Markdown and prose
+
+- Semantic line breaks, no hard wrapping. American English spelling. `[review]`
diff --git a/.agents/feature-usage-tracking.md b/.agents/feature-usage-tracking.md
new file mode 100644
index 000000000000..8bf4c4084162
--- /dev/null
+++ b/.agents/feature-usage-tracking.md
@@ -0,0 +1,8 @@
+# Feature usage tracking
+
+- **Every feature is tracked end to end.** A user's path through a feature, from entry to outcome, emits events that show whether people start it, finish it, and where they drop off.
+- **Features adjacent to your work get tracking too.** A feature is adjacent when it shares a scene or a user flow with your change. When an adjacent feature has no tracking, add it in the same change.
+- **Check usage of tracked adjacent features.** Run a subagent that queries each tracked adjacent feature's usage over the last 6 months.
+ - Fewer than 100 interactions a week counts as low usage. Zero events in 6 months is the extreme case of low usage.
+ - Before you act on low usage, confirm the tracking fires: trigger the feature locally and check that the events arrive. Missing events can mean broken tracking, not an unused feature.
+ - Post each low-usage feature and its usage numbers in the platform UX Slack channel (Channel ID: `C08499A7REU`). The decision to keep or remove the feature is made there. Do not remove a feature before that decision.
diff --git a/.agents/skills/building-product-empty-states/SKILL.md b/.agents/skills/building-product-empty-states/SKILL.md
index 35ab4c1ecba8..5b4674017d2b 100644
--- a/.agents/skills/building-product-empty-states/SKILL.md
+++ b/.agents/skills/building-product-empty-states/SKILL.md
@@ -69,7 +69,7 @@ Statuses: `loading` (not yet known - the gate holds a spinner, never flashes the
- **`featureFlag`**: set it when the scene is already flag-gated (so the scene's own gate keeps handling flag-off) or to roll the empty state out gradually.
- **Scene modules that serve more than one surface**: `scenes` narrows where the gate applies, and omitting it gates everything the module serves. A plain scene id covers that whole scene. When one scene id serves several tabs, pass `{ scene, tabs }` and list every value of the `tab` route param you gate, including `undefined` for the URL with no tab segment - `products/workflows/frontend/emptyState/workflowsEmptyState.tsx` gates its workflow list while channels, opt-outs, suppression, and reputation stay reachable with no workflows yet. Gating the scene instead would take those tabs down with it.
- **Hedgehog**: a `pngHoggie(...)`-wrapped module — import only inside the product chunk (eager-graph guard: `frontend/bin/check-eager-graph.mjs`). Never hardcode image URLs (e.g. Cloudinary) — `@posthog/brand` assets only.
-- **`text` is keyed by mode**: provide the `needs-setup` base; add a `waiting-for-data` entry only if your product has that middle state (missing fields fall back to the base). Sentence case, benefit-first, no AI tells (see "User-facing copy" in `CLAUDE.md`).
+- **`text` is keyed by mode**: provide the `needs-setup` base; add a `waiting-for-data` entry only if your product has that middle state (missing fields fall back to the base). Sentence case, benefit-first, no AI tells (see `/writing-user-facing-copy`).
- **Key `wizard` by mode when the install command stops applying**: a product whose `waiting-for-data` means "events are flowing, a scheduled job hasn't run yet" has nothing left to install, so pass `wizard: { 'needs-setup': { slug } }` and the terminal, the manual link, and the hint leave the waiting screen (clusters). Leave it flat when re-running setup still makes sense there (MCP analytics: "Instrumenting another server?").
- **Key `primaryAction` by mode when it only fits one**: a one-click opt-in ("Enable session recording") is done once the status is `waiting-for-data`, and clicking it again re-sends the same team update. Pass `primaryAction: { 'needs-setup': { ... } }` and the button, along with the `hint` that introduces it, leaves the waiting screen. A single flat action still covers both modes - keep that when it reads correctly either way (support's "Open support settings").
- **Product header**: the gate keeps the product header (name, description, icon) above the empty state automatically, sourced from the scene's `SceneConfig` in your product manifest — make sure your manifest's scene entry has `name`, `description`, and `iconType` set.
diff --git a/.agents/skills/editing-agents-md/SKILL.md b/.agents/skills/editing-agents-md/SKILL.md
index e2b1e03d3537..b08235da408b 100644
--- a/.agents/skills/editing-agents-md/SKILL.md
+++ b/.agents/skills/editing-agents-md/SKILL.md
@@ -27,7 +27,7 @@ Do not reorder for attention. Reorder only when a heading makes a rule easier fo
## 1. Does this belong in the file at all?
-Work down this ladder and stop at the first rung that fits. It is the same ladder `AGENTS.md` states for itself.
+Work down this ladder and stop at the first rung that fits. It is the same ladder [`.agents/agent-automation.md`](../../agent-automation.md) states for the repo.
| Rung | Mechanism | Use when |
| ---- | ------------------------------------------------------------ | ------------------------------------------------------- |
@@ -69,7 +69,7 @@ Keep to the repo's prose conventions: ASD-STE100 Simplified Technical English, a
## 4. Tag what enforces it
-Every rule in **Architecture guidelines** and **Code Style** carries a tag. Extend the convention when you add to those sections.
+Every rule in [`.agents/architecture.md`](../../architecture.md) and [`.agents/code-style.md`](../../code-style.md) carries a tag. Extend the convention when you add to those guides.
```markdown
- **Do not use `Team` or `Organization` rows as mutexes.** `[lint: hot-parent-row-select-for-update]` PostgreSQL takes …
@@ -79,7 +79,7 @@ Every rule in **Architecture guidelines** and **Code Style** carries a tag. Exte
- `[lint: <id>]` — a semgrep rule id, a `ruff <CODE>`, or an invariant test filename. A reviewer skips it, because CI is the gate.
- `[review]` — nothing catches this. A reader is the only control, so it earns its place in the file.
-Every rule in those two sections carries one of the two tags, and every tag must resolve against the repo.
+Every rule in those two guides carries one of the two tags, and every tag must resolve against the repo.
`posthog/test/repo_invariants/test_agents_md_enforcement_tags.py` fails the build on an untagged rule, and on a `[lint: …]` that names a rule, code, or file which no longer enforces anything.
A ruff code moved to the `ignore` list stops counting, so a tag cannot survive its rule being switched off.
That is the point: a stale tag is worse than no tag, because a reviewer trusts it and skips the check.
@@ -89,10 +89,12 @@ A rule that stays `[review]` for a long time is a candidate for rung 1. That vis
## 5. Root or nested?
-Both files get the same smells check. The budget differs.
+All three get the same smells check. The budget differs.
**Root `AGENTS.md`** — loads every session, in every tool, for every task. Strict. A rule earns its place only if it applies across the repo, or if getting it wrong is expensive and nothing catches it (the public-repo rules are the model). Keep the enforcement tags current.
+**Topic guides** (`.agents/<topic>.md`: architecture, code style, CI, feature usage tracking, agent automation, security) load when the routing table in the root file's "Read the guide for your area first" section sends an agent there. A repo-wide rule that applies only to one kind of work, such as application code or CI workflows, belongs in a guide. Each guide keeps its heading in the root file, and its table row is the only place that says when to read it. Put a new trigger in the row, never in the section under the heading, because two triggers drift apart.
+
**Nested `AGENTS.md`** (about 27 of them: `posthog/temporal/`, `rust/`, `frontend/src/`, most of `products/`) — loads when an agent works in that subtree, so a local convention is cheap here and expensive in the root. Move a directory-specific rule down rather than up. No tag convention required, though it does no harm.
Never state the same rule in both. That is how conflicting instructions start.
@@ -101,7 +103,7 @@ Never state the same rule in both. That is how conflicting instructions start.
- The rule is on rung 4 because rungs 1 to 3 genuinely do not fit.
- It reads as an invariant, with a trigger a reader can spot in a diff.
-- It is tagged, if it sits in Architecture guidelines or Code Style.
+- It is tagged, if it sits in `.agents/architecture.md` or `.agents/code-style.md`.
- No other line in the file, or in a nested `AGENTS.md`, says something different.
- Every link you added says when to read it.
- Every link and skill reference resolves:
diff --git a/.agents/skills/optimizing-clickhouse-and-hogql-queries/SKILL.md b/.agents/skills/optimizing-clickhouse-and-hogql-queries/SKILL.md
index 23bff1f67d0e..5e116835c48f 100644
--- a/.agents/skills/optimizing-clickhouse-and-hogql-queries/SKILL.md
+++ b/.agents/skills/optimizing-clickhouse-and-hogql-queries/SKILL.md
@@ -92,7 +92,7 @@ Eyeball the ClickHouse SQL for these before reaching for tools. To instead work
- **`LIMIT 1 BY` with `ORDER BY version DESC`** for one row per group with a monotonic version column.
- **Filter before FINAL** (if truly needed): make the WHERE selective on the sort-key prefix so few parts are merged.
-PostHog-specific: per [`CLAUDE.md`](../../../CLAUDE.md), new person/group access should go through personhog (`get_personhog_client`), not raw `person` / `groups`. A raw `FROM person FINAL` in new code usually wants the personhog move, not tuning.
+PostHog-specific: per [`.agents/architecture.md`](../../architecture.md), new person/group access should go through personhog (`get_personhog_client`), not raw `person` / `groups`. A raw `FROM person FINAL` in new code usually wants the personhog move, not tuning.
### JSON operations on properties
diff --git a/.agents/skills/writing-kea-logics/SKILL.md b/.agents/skills/writing-kea-logics/SKILL.md
index 06fe7ca4bd29..b887c99618cd 100644
--- a/.agents/skills/writing-kea-logics/SKILL.md
+++ b/.agents/skills/writing-kea-logics/SKILL.md
@@ -33,8 +33,8 @@ If your work overlaps it, read the companion skill first.
## Core principles
1. **Business logic lives in a logic, not in a component.**
- [CLAUDE.md](../../../CLAUDE.md) is explicit: "If there is a kea logic file, write all
- business logic there, avoid React hooks at all costs." Hooks are for view concerns.
+ [`.agents/code-style.md`](../../code-style.md) is explicit: "Business logic goes in the
+ kea logic file, not a React hook." Hooks are for view concerns.
2. **One concept, one source of truth.** Pick exactly one of: action-driven reducer,
derived selector, async loader. Don't mirror the same value into multiple places.
diff --git a/.agents/skills/writing-kea-logics/references/testing.md b/.agents/skills/writing-kea-logics/references/testing.md
index f5d372783565..4f90d79bc588 100644
--- a/.agents/skills/writing-kea-logics/references/testing.md
+++ b/.agents/skills/writing-kea-logics/references/testing.md
@@ -106,7 +106,7 @@ rule. Never add logic-path exceptions to the Jest breakpoint wrapper.
## Parameterise
-Per repo convention ([CLAUDE.md](../../../../CLAUDE.md)), parameterise variations of the
+Per repo convention ([`.agents/code-style.md`](../../../code-style.md)), parameterise variations of the
same shape rather than copy-pasting describe bodies:
```ts
diff --git a/.agents/skills/writing-ui-components/SKILL.md b/.agents/skills/writing-ui-components/SKILL.md
index e9de94386dd6..e62309e14880 100644
--- a/.agents/skills/writing-ui-components/SKILL.md
+++ b/.agents/skills/writing-ui-components/SKILL.md
@@ -184,7 +184,7 @@ acts on it.
- Scene-level first-run ("product not set up") belongs to the
[ProductEmptyState gate](../building-product-empty-states/SKILL.md), not bespoke branching.
- Any submit that fires a network request disables the trigger and shows a loading state while
- in flight (root `CLAUDE.md` rule) — reset in both success and error paths.
+ in flight (`.agents/code-style.md` rule) — reset in both success and error paths.
## Visual discipline
diff --git a/.agents/skills/writing-user-facing-copy/SKILL.md b/.agents/skills/writing-user-facing-copy/SKILL.md
index e5dc9c7ad77a..8ae22a6cee59 100644
--- a/.agents/skills/writing-user-facing-copy/SKILL.md
+++ b/.agents/skills/writing-user-facing-copy/SKILL.md
@@ -21,7 +21,7 @@ Does not apply to: code comments, commit messages, log lines, variable/function
Write the way a person would. Neutral and humane.
- **Sentence case.** Capitalize only the first word and proper nouns. "Save as view", not "Save As View". "Product analytics", not "Product Analytics".
-- **Be direct and friendly.** Say what happened and what to do next.
+- **Be direct and friendly.** Keep one tone across surfaces, say only what happened and what to do next.
- **Plain language, no jargon.** Use the label the user sees, not the internal name. `surveyPopupDelaySeconds` becomes "Delay the survey popup".
- **Don't editorialize.** State what is, not how exciting it is. Cut "powerful", "seamless", "effortless", "simply", "just", "easily", "supercharge", "unlock".
- **No sales-y or edgy copy.** No marketing hooks, no clever one-liners, no hype.
diff --git a/.claude/agents/code-reviewer.md b/.claude/agents/code-reviewer.md
index 3f4fe6a57e9c..713db8c38e44 100644
--- a/.claude/agents/code-reviewer.md
+++ b/.claude/agents/code-reviewer.md
@@ -7,7 +7,7 @@ model: opus
**Role:** You are a senior code reviewer. Goal: ship safe, maintainable code fast while mentoring. Explain _what_ and _why_, and propose minimal patches.
-**PostHog Conventions:** Before reviewing, read [conventions](.claude/commands/conventions.md), [AGENTS.md](AGENTS.md), and [security guidelines](.agents/security.md) to understand PostHog's coding standards, architecture rules, and security requirements. Key points to check:
+**PostHog Conventions:** Before reviewing, read [conventions](.claude/commands/conventions.md), [AGENTS.md](AGENTS.md), [architecture guidelines](.agents/architecture.md), [code style](.agents/code-style.md), and [security guidelines](.agents/security.md) to understand PostHog's coding standards, architecture rules, and security requirements. Key points to check:
- **Frontend:** Kea for state (not useState/useEffect), named exports, PascalCase components, camelCase logics, Tailwind CSS, logic tests
- **Backend:** Structured logging with structlog, proper log levels, no sensitive data in logs, pytest assertions, parameterized tests
@@ -52,7 +52,7 @@ model: opus
**Process:**
-1. Read [conventions](.claude/commands/conventions.md), [AGENTS.md](AGENTS.md), and [security guidelines](.agents/security.md).
+1. Read [conventions](.claude/commands/conventions.md), [AGENTS.md](AGENTS.md), [architecture guidelines](.agents/architecture.md), [code style](.agents/code-style.md), and [security guidelines](.agents/security.md).
2. Scan for critical safety/security issues.
3. Check for convention violations (state management, naming, testing patterns).
4. Walk through the performance checklist against changed code.
diff --git a/.claude/rules/agents-md.md b/.claude/rules/agents-md.md
index 7e2f60f36d58..302197b42ffb 100644
--- a/.claude/rules/agents-md.md
+++ b/.claude/rules/agents-md.md
@@ -4,6 +4,12 @@ paths:
- 'CLAUDE.md'
- '**/AGENTS.md'
- '**/CLAUDE.md'
+ - '.agents/agent-automation.md'
+ - '.agents/architecture.md'
+ - '.agents/ci.md'
+ - '.agents/code-style.md'
+ - '.agents/feature-usage-tracking.md'
+ - '.agents/security.md'
---
Invoke the `/editing-agents-md` skill before adding, editing, or removing any instruction here.
@@ -11,8 +17,8 @@ Invoke the `/editing-agents-md` skill before adding, editing, or removing any in
The root file loads in full at the start of every session, so a line added to it is paid for by
every task in the repo. The skill carries the ladder that decides whether a rule belongs in a
linter, a skill, or this file at all; the six smells to check the diff against; and the
-`[lint: <id>]` / `[review]` tag convention that the root file's Architecture guidelines and Code
-Style sections use.
+`[lint: <id>]` / `[review]` tag convention that `.agents/architecture.md` and `.agents/code-style.md`
+use.
Do not reorder sections to make a rule more prominent — instruction position has no measured
effect on whether an agent follows it. Reorder only to help a human find or cite a rule.
diff --git a/.depot/workflows/ci-backend.yml b/.depot/workflows/ci-backend.yml
index ca5369b1d73c..fe030d8f5100 100644
--- a/.depot/workflows/ci-backend.yml
+++ b/.depot/workflows/ci-backend.yml
@@ -504,16 +504,17 @@ jobs:
tasks_temporal:
- 'products/tasks/backend/temporal/**/*'
repo_invariants:
- # posthog/test/repo_invariants/ reads AGENTS.md and the semgrep
- # rule ids it names. Both are excluded from the backend filter
- # (markdown is dropped outright, .semgrep is not listed), so a
- # change to either would skip repo-checks and report green while
+ # posthog/test/repo_invariants/ reads AGENTS.md, the .agents/
+ # guides, and the semgrep rule ids they name. All are excluded
+ # from the backend filter (markdown is dropped outright,
+ # .semgrep is not listed), so a change to any would skip repo-checks and report green while
# leaving a tag pointing at a rule that no longer exists.
# The out-of-band domain ratchet reads these trees, so a resolver added there must run it.
- 'nodejs/src/**'
- 'rust/**'
- 'products/desktop/**'
- 'AGENTS.md'
+ - '.agents/*.md'
- '.semgrep/**'
- 'pyproject.toml'
# A generated file in a frontend-only PR still needs a known producer.
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
index 9337c5f561a0..673c68a7c080 100644
--- a/.github/CODEOWNERS
+++ b/.github/CODEOWNERS
@@ -90,6 +90,11 @@ products/isolation_baseline.txt @PostHog/team-devex
# with the teams that own their directories.
/AGENTS.md @PostHog/team-devex
/CLAUDE.md @PostHog/team-devex
+/.agents/agent-automation.md @PostHog/team-devex
+/.agents/architecture.md @PostHog/team-devex
+/.agents/ci.md @PostHog/team-devex
+/.agents/code-style.md @PostHog/team-devex
+/.agents/feature-usage-tracking.md @PostHog/team-devex
.github/pull_request_template.md @PostHog/team-devex
.agents/skills/writing-pr-descriptions/ @PostHog/team-devex
diff --git a/.github/scripts/check-claude-hooks.sh b/.github/scripts/check-claude-hooks.sh
index 6b9a7ecbb7b1..040fbdfa0195 100755
--- a/.github/scripts/check-claude-hooks.sh
+++ b/.github/scripts/check-claude-hooks.sh
@@ -14,5 +14,5 @@ staged=$(git diff --cached --name-only)
if grep -q '^\.claude/hooks/' <<< "$staged"; then
printf "\n\033[33mWarning: hooks in .claude/ are reserved for env bootstrapping (SessionStart only).\n"
- printf "Prefer skills, AGENTS.md instructions, or lint-staged rules. See Agent automation in AGENTS.md.\033[0m\n\n"
+ printf "Prefer skills, AGENTS.md instructions, or lint-staged rules. See .agents/agent-automation.md.\033[0m\n\n"
fi
diff --git a/.github/workflows/ci-dagster.yml b/.github/workflows/ci-dagster.yml
index acaa275a6147..d9eeb914a45c 100644
--- a/.github/workflows/ci-dagster.yml
+++ b/.github/workflows/ci-dagster.yml
@@ -730,7 +730,7 @@ jobs:
# file granularity only when the installed pytest-split offers them, else
# duration_based_chunks / item. A workflow edit runs merged with master, so
# an unrebased PR on older pytest-split must not hit an unknown
- # --splitting-algorithm / --split-granularity. See AGENTS.md (CI).
+ # --splitting-algorithm / --split-granularity. See .agents/ci.md.
SPLITTING_ALGORITHM=duration_based_chunks
SPLIT_GRANULARITY=()
if python -c "from pytest_split.algorithms import Algorithms; from pytest_split.plugin import PytestSplitFilePlugin; raise SystemExit(0 if 'optimal_chunks' in Algorithms.names() else 1)" 2>/dev/null; then
diff --git a/.greptile/files.json b/.greptile/files.json
index f014508cea48..6336b9b9553b 100644
--- a/.greptile/files.json
+++ b/.greptile/files.json
@@ -2,7 +2,19 @@
"files": [
{
"path": "AGENTS.md",
- "description": "Repository conventions: architecture guidelines, code style, commit and PR rules"
+ "description": "Repository conventions: commands, commit and PR rules, security rules, and mandatory skills"
+ },
+ {
+ "path": ".agents/architecture.md",
+ "description": "Architecture guidelines: layering, team scoping, person data, transactions, API schemas, async work, outbound calls, storage, settings"
+ },
+ {
+ "path": ".agents/code-style.md",
+ "description": "Code style for Python, frontend, comments, tests, and Markdown"
+ },
+ {
+ "path": ".agents/ci.md",
+ "description": "CI and GitHub Actions rules"
},
{
"path": "products/warehouse_sources/backend/temporal/data_imports/sources/AGENTS.md",
diff --git a/.semgrep/rules/devex/tuple-return-prefer-dataclass.yaml b/.semgrep/rules/devex/tuple-return-prefer-dataclass.yaml
index 6f098be8e363..eda88703f710 100644
--- a/.semgrep/rules/devex/tuple-return-prefer-dataclass.yaml
+++ b/.semgrep/rules/devex/tuple-return-prefer-dataclass.yaml
@@ -1,7 +1,7 @@
# Flags function return annotations that are tuples where callers can silently
# swap same-typed elements (e.g. `tuple[int, int]` for `(start, end)`) or must
# read 3+ elements positionally. Partial enforcement of the frozen-dataclass
-# convention in the Code Style section of AGENTS.md.
+# convention in .agents/code-style.md.
#
# See: https://github.com/PostHog/posthog/pull/75818 for context
rules:
@@ -28,7 +28,7 @@ rules:
call site (two share a type) or must be read positionally (3+
elements). Prefer a frozen dataclass with named fields: `@frozen`
from `posthog.dataclasses` (frozen, kw_only, slots by default). See
- the Python bullets in the Code Style section of AGENTS.md.
+ the Python bullets in .agents/code-style.md.
Pre-existing findings are grandfathered; only newly-introduced ones
block CI.
languages: [python]
diff --git a/.stamphog/README.md b/.stamphog/README.md
index 768838ea1984..1a995fe634b3 100644
--- a/.stamphog/README.md
+++ b/.stamphog/README.md
@@ -13,7 +13,7 @@ What each file contains and how per-folder overrides resolve: [the engine's "Pol
- `ci_workflows` is an extra, owner-only category. It matches every file under `.github/workflows/` and `.depot/workflows/`, and its `exempt_author_teams` lets stamphog approve there only for authors on `team-devex`.
- `stamphog_policy` extends its paths with `packages/owners-yaml/`, `owners.yaml` and `product.yaml`, because those are gate inputs here.
- `devex_guardrails` is an extra category. It matches the semgrep rules, ratchet baselines, invariant tests and lint code that guard the house patterns, so an edit to a guard always gets a human review.
-- `agent_steering` is an extra, owner-only category. It matches the root `AGENTS.md`, the PR template, the `writing-pr-descriptions` skill, `.claude/settings.json`, `.claude/hooks/` and `.mcp.json`, and its `exempt_author_teams` lets stamphog approve there only for authors on `team-devex`.
+- `agent_steering` is an extra, owner-only category. It matches the root `AGENTS.md`, the five topic guides moved out of it (`.agents/agent-automation.md`, `architecture.md`, `ci.md`, `code-style.md` and `feature-usage-tracking.md`), the PR template, the `writing-pr-descriptions` skill, `.claude/settings.json`, `.claude/hooks/` and `.mcp.json`, and its `exempt_author_teams` lets stamphog approve there only for authors on `team-devex`.
- `workflows_delivery` is an extra, owner-only category. It matches the CDP, Workflows and Messaging API, models and plugin-server worker code, and its `exempt_author_teams` lets stamphog approve there only for authors on `team-workflows`.
- `deny_exceptions` lifts `auth` and `billing` for `products/warehouse_sources/backend/temporal/data_imports/sources/` and `products/warehouse_sources/sources/`, because connector code does OAuth and talks to the Stripe API without touching PostHog's auth system or its billing. It lifts `workflows_delivery` for the CDP and Messaging API test directories.
- `allow` extends its path patterns with `.github/CODEOWNERS`.
diff --git a/.stamphog/policy.yml b/.stamphog/policy.yml
index 30ab3cac30e6..bff369ba0cbe 100644
--- a/.stamphog/policy.yml
+++ b/.stamphog/policy.yml
@@ -68,6 +68,7 @@ deny:
paths:
- '^agents\.md$'
- '^claude\.md$'
+ - '^\.agents/(agent-automation|architecture|ci|code-style|feature-usage-tracking)\.md$'
- '^\.github/pull_request_template\.md$'
- '^\.agents/skills/writing-pr-descriptions/'
- '^\.claude/settings\.json$'
diff --git a/AGENTS.md b/AGENTS.md
index bbd38bba6357..2b9c8ccc06f2 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -143,14 +143,25 @@ Examples:
- ❌ A PR description that quotes verbatim what a coworker said in a Slack thread
- ❌ A test fixture adapted from a real support conversation with the names and domains replaced
+## Read the guide for your area first
+
+Most topic rules live in guides under `.agents/`, not in this file.
+Before your first edit, plan, or review finding, open every guide whose area the task touches.
+Reviewing a diff counts: the diff touches the areas it changes.
+Each guide's row below holds its full trigger. A section may still link one part of a guide for a rule it states.
+
+| Guide | Read it before you write or review |
+| ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [.agents/architecture.md](.agents/architecture.md) | Application or dev-stack code in any language, such as a model, view, serializer, task, or React component: entrypoints, `team_id` scoping, personhog, transactions, API schemas, Celery and Temporal, outbound calls, storage, Django settings, Django admin, and the `services/llm-gateway` freeze |
+| [.agents/code-style.md](.agents/code-style.md) | Python; frontend code such as a component, kea logic, a button, or a form; comments; tests; Markdown; or a choice between quill and LemonUI |
+| [.agents/feature-usage-tracking.md](.agents/feature-usage-tracking.md) | A feature a user interacts with, such as a new action, menu item, or scene, a change to what a user can do there, or the removal of a feature for low usage |
+| [.agents/ci.md](.agents/ci.md) | A workflow, `.nvmrc`, a publish job, event ingestion, tests that read event properties, or a flaky CI run |
+| [.agents/agent-automation.md](.agents/agent-automation.md) | The automation of a convention, a Claude Code hook, `.claude/settings.json`, a lint-staged task, or a pre-commit check |
+| [.agents/security.md](.agents/security.md) | Auth, secrets, service-to-service calls, raw SQL, HogQL string building, a new external origin, an inline script under the Content Security Policy, or a PR for a security fix |
+
## CI / GitHub Actions
-- `.nvmrc` controls the Node.js version for all CI workflows (via `actions/setup-node`) — changing it affects every CI job that runs Node
-- CI uploads test results to Trunk Flaky Tests; the `trunk` MCP server in `.mcp.json` queries per-test flakiness on a PR or `master` (authenticate via `/mcp`, or a `TRUNK_API_TOKEN` bearer header when headless) — see `/debugging-ci-failures` and `/fixing-flaky-tests`
-- **A workflow edit reaches every open PR before those branches rebase.** It runs against the PR merged with master, but a companion change — a new dependency, file, or config — only arrives when the branch rebases. A workflow that starts requiring something unrebased branches lack fails every in-flight PR before its tests run. Make the new behavior degrade gracefully, or gate it. This has broken CI repeatedly.
-- Mechanical workflow rules (`timeout-minutes`, concurrency, dispatch budget, path filters, gate hygiene) are enforced by `hogli lint:workflows` and actionlint, which are the source of truth. `/authoring-ci-workflows` explains the reasoning behind each.
-- **A directory of tests that read event properties belongs in `.github/new-events-schema-targets.txt`.** Backend CI reruns the listed paths against the native-JSON events table. A test outside the list runs on the legacy table only. Add the `test-new-events-schema` label when a diff needs the whole backend suite on both tables, such as an event ingestion change or event reads tested outside the list. Label while the PR is a draft, or push again after labeling, because label events do not start Backend CI.
-- **A pull request never publishes a package or release.** `[lint: github-actions-publish-on-pull-request]` A published version is public forever, and a pull request run executes code its author controls. Publish only from a `push` to `master`, a release tag, or a `workflow_dispatch` on `master`. A pull request run only builds and validates, for example with `--dry-run`. The semgrep rule cannot see a publisher inside a reusable workflow, so gate that job in the called workflow too. Never run a publish command by hand from a pull request branch. [`build-hogql-parser-npm.yml`](.github/workflows/build-hogql-parser-npm.yml) is the reference shape.
+The rules for CI and GitHub Actions live in [.agents/ci.md](.agents/ci.md). Its row in [Read the guide for your area first](#read-the-guide-for-your-area-first) says when to read it.
## Security
@@ -163,7 +174,7 @@ The private mirror carries this file, and its `origin` points at the private rep
Before the first push of a branch, run `git remote get-url origin`.
If it names `posthog-private` and the change is not an embargoed fix, open the PR from a `PostHog/posthog` checkout.
Do not add new `INTERNAL_API_SECRET` callers.
-Read [.agents/security.md](.agents/security.md) before touching auth, secrets, service-to-service calls, raw SQL, or HogQL string building — it covers least privilege, the injection rules, and how to respond when semgrep flags your code.
+[.agents/security.md](.agents/security.md) covers least privilege, the injection rules, and how to respond when semgrep flags your code.
`.semgrep/rules/security/` is the enforced set; run `semgrep --config .semgrep/rules/security/ .` to check a change locally.
**Treat the Content Security Policy in `CSPMiddleware` as enforced.**
@@ -175,135 +186,25 @@ Read [.agents/security.md](.agents/security.md#content-security-policy) for the
## Architecture guidelines
-Each rule is tagged with what catches a violation.
-`[lint: <id>]` means a linter, semgrep rule, or invariant test blocks it, so CI is the check and this text is only the reasoning.
-`[review]` means nothing catches it automatically — a reader is the only control.
-
-### Entrypoints and layering
-
-- **Keep entrypoints thin.** `[review]` The runtime calls the entrypoint first: a DRF view, a management command `handle()`, a Celery task body, an HTTP handler, a Rust `main()`, a React component. An entrypoint reads the input, connects the dependencies, and formats the output. All other logic goes in a function the entrypoint calls, so a test can call it directly. If the area already has a place for that logic, use it rather than making a new one.
-- **A product under `products/` is scaffolded, not hand-rolled.** `[lint: hogli product:lint --all]` Create one with `hogli product:bootstrap <name>`, because the scaffold emits a product that is isolated from its first commit. See "New products must be isolated" in [products/README.md](products/README.md) for the isolation rules, and [products/architecture.md](products/architecture.md) for facade and contract design.
-- **Code a single product owns belongs under `products/<product>/`** — backend, frontend, scripts, CLIs, services, packages, MCP tools, skills. `[review]` Reserve top-level `tools/`, `services/`, `packages/`, `cli/` and `hog/` for cross-product things. `product:lint` only scans `products/`, so a single-product feature parked in a top-level directory is invisible to it.
-
-### Tenancy and scoping
-
-- **Every tenant-data model must have `team_id`**, as a FK to `posthog.Team` or a plain `BigIntegerField` for multi-DB products. `[lint: idor-lookup-without-team, check-idor-model-coverage.py]` This is the primary tenant isolation boundary. New models inherit `TeamScopedRootMixin` (main DB) or `ProductTeamModel` (separate DB) so they start fail-closed — see [posthog/models/scoping/README.md](posthog/models/scoping/README.md).
-- **Classifying a model as unscoped is a review decision, not a checked one.** `[review]` A model without `team_id` must be org-scoped, user-scoped, or instance-global, never silently unscoped. `check-idor-model-coverage.py` only warns when a name lands in `NEEDS_TEAM_ID`, and passes silently for `LEGITIMATELY_UNSCOPED`, so a wrongly exempted tenant model reaches master unless a reader catches it.
-- **Reading a fail-closed model outside request context** — Temporal activities, Celery tasks, management commands — uses `Model.objects.for_team(team_id)`. `[review]` Not `Model.all_teams.filter(team_id=...)` and not `objects.unscoped().filter(...)`; those are for genuinely cross-team access and Django internals. In serializers the team comes from `self.context["get_team"]()`. Caveat: `for_team(...).get_or_create(...)` and `.create(...)` still need `team_id` passed explicitly, because a queryset filter does not propagate into row creation.
-- **Do not add domain-specific fields to the `Team` model.** `[review]` Use a Team Extension model — see [posthog/models/team/README.md](posthog/models/team/README.md) for the pattern and helpers.
-
-### Person and group data
-
-- **All person/group access goes through the personhog client.** `[review]` Never query these via the Django ORM or raw SQL: `posthog_person`, `posthog_persondistinctid`, `posthog_cohortpeople`, `posthog_group`, `posthog_grouptypemapping`, and the override tables (`posthog_personoverride`, `posthog_pendingpersonoverride`, `posthog_flatpersonoverride`, `posthog_featureflaghashkeyoverride`, `posthog_personlessdistinctid`, `posthog_personoverridemapping`). Use the routed helpers in `posthog/models/person/util.py` and `posthog/models/group_type_mapping.py`. New access follows the same `_personhog_routed()` pattern: a `personhog_fn` using `get_personhog_client()`, plus an `orm_fn` fallback. See [posthog/personhog_client/README.md](posthog/personhog_client/README.md).
-- **Personhog answers identity questions only.** `[review]` Use it for resolving distinct IDs, point lookups by person id or UUID, and lifecycle writes. Person properties, list hydration, and search come from ClickHouse (HogQL over `persons`, `ActorsQueryRunner`). Avoid reading `properties` from personhog — the API will stop surfacing it. Single-person lookups that need properties are exempt only while no ClickHouse primitive covers them, never in bulk. See [docs/internal/person-data-access.md](docs/internal/person-data-access.md).
-
-### Transactions and locking
-
-- **There is no implicit per-request transaction** — PostHog does not enable `ATOMIC_REQUESTS`. `[review]` Every operation runs in autocommit unless wrapped. Put `with transaction.atomic():` around the specific writes that must succeed or fail together, never around a whole view method. Keep irreversible side effects out of the block: an email sent or an API called before a rollback has already happened. Schedule them after the commit, or dispatch Celery tasks with `transaction.on_commit()`.
-- **Do not use `Team` or `Organization` rows as mutexes.** `[lint: hot-parent-row-select-for-update]` PostgreSQL takes `KEY SHARE` locks on parent rows for foreign-key checks, and `FOR UPDATE` conflicts with them, so an unrelated child-row write can wait behind a transaction holding a hot parent row. Lock the product's `Team<Product>Config` extension row instead, reached through `get_or_create_team_extension` so the row exists first. For a per-team count limit or number allocation, use a unique constraint, a conditional update, or a dedicated allocation row. Otherwise lock the quiet child row, or take a transaction-scoped advisory lock. Lock `Team` or `Organization` only when the transaction updates or deletes that row, and keep it short — no network calls, no input-sized loops. Each exception needs a short `nosemgrep` justification.
-
-### API schemas and generated types
-
-- **API views declare request/response schemas.** `[review]` Prefer `@validated_request` from `posthog.api.mixins`, or `@extend_schema` from drf-spectacular. A plain `ViewSet` method that validates manually needs `@extend_schema(request=YourSerializer)`; without it drf-spectacular cannot discover the request body and generated code gets an empty schema. Serializer fields need `help_text`. These flow into both frontend types and MCP tool schemas.
-- **Django serializers are the source of truth for frontend API types.** `[lint: build:openapi CI gate, prefer-codegen-api, test_generated_files_are_registered.py]` `hogli build:openapi` generates TypeScript via drf-spectacular and Orval into `frontend/src/generated/core/` and `products/{product}/frontend/generated/`. Never hand-edit `api.schemas.ts`, `api.ts` or `api.zod.ts` — change the serializer and regenerate. A value list the frontend needs comes from a typed serializer field, not from a side script; other checked-in projections are entries in `tools/hogli-commands/hogli_commands/projections.py`. [Type system guide](docs/published/handbook/engineering/type-system.md) has the full pipeline.
-- MCP tools and MCP UI apps are generated from the same OpenAPI spec. `[review]` See [implementing MCP tools](docs/published/handbook/engineering/ai/implementing-mcp-tools.md) covers the YAML config and codegen. MCP UI apps live in `products/*/mcp/tools.yaml` under `ui_apps` — see [services/mcp/CONTRIBUTING.md](services/mcp/CONTRIBUTING.md) or `/implementing-mcp-ui-apps`.
-
-### Async, storage and outbound calls
-
-- **Do not use `posthoganalytics.capture()` in a Celery task** — events are silently lost. `[review]` Use `ph_scoped_capture` from `posthog.ph_client`; its docstring explains why.
-- **Temporal activity payloads cap at ~2 MiB — pass large data by reference.** `[review]` Activity inputs and outputs cross a gRPC boundary the server rejects above that (`blobSizeLimitError`). As a field-level rule: if a field could exceed ~256 KB serialized (query results, exported file contents, LLM context, rendered HTML, image bytes, unbounded `list[dict[str, Any]]`), write it to Postgres or object storage from inside the activity and return only the row ID or S3 key. The workflow already has any ID created earlier in the run. Shuttling large data through the workflow produces `PayloadSizeError` (`TMPRL1103`) as soon as the data crosses the limit.
-- **A Python `requests` call to GitHub or Slack under `common/`, `ee/`, `posthog/` or `products/` goes through `posthog/egress/`.** `[lint: github-api-calls-go-through-egress, slack-api-calls-go-through-egress]` Route it through the gated, recorded transport.
-- **Every other call to those hosts goes through `posthog/egress/` too.** `[lint: github-api-calls-go-through-egress-wide, slack-api-calls-go-through-egress-wide]` The wide rules catch a URL bound to a variable or constant, `requests.Session`, `httpx`, `aiohttp`, `urllib.request`, and an aliased Slack SDK client. Another language, another vendor SDK, or a caller under `tools/` still passes CI, so a reader is the only control there.
-- **Any other third-party API that needs rate-limiting or egress telemetry belongs there too.** `[review]` Add a `<domain>/` incarnation (GitHub is the reference). No semgrep rule covers a new domain, so a raw client for one reaches master unless a reader catches it. `/routing-outbound-api-calls` decides the route and names the reference domain to copy.
-- **Object storage is SeaweedFS — do not add new MinIO dependencies.** `[review]` Both S3-compatible stores are SeaweedFS: `objectstorage` (`:19000`, `OBJECT_STORAGE_*`) for general storage, `seaweedfs` (`:8333`, `SESSION_RECORDING_V2_S3_*`) for session replay v2. MinIO survives only as one-off salvage tooling: `bin/migrate-storage-hobby` starts a temporary container to read an old hobby MinIO volume. Do not add compose services, scripts, tests or docs that stand up a `minio/minio` container. Talk to storage through the existing config and a standard S3 client, never a hardcoded endpoint. Note `objectstorage` registers credentials at runtime and returns `InvalidAccessKeyId` until that finishes, so wait for its readiness sentinel rather than the container start.
-
-- **A new DNS-resolution or outbound-host entry point calls the shared out-of-band domain check.** `[lint: test_oob_denylist_coverage.py]` Every host guard here is IP-based, and an out-of-band interaction domain resolves to an ordinary public IP, so a resolver that skips the check restores the gap in silence. The list and the edit procedure live in `posthog/security/crosslang/`.
-
-### Configuration and secrets
-
-- **A key in `posthog/settings/dynamic_settings.py` exists only because operators must change its value live, without a deploy.** `[review]` These instance settings are Postgres rows that staff edit at runtime, and a stored row overrides the environment variable. Kill switches and tuning knobs for incidents qualify. Secrets and static config are environment variables read in `posthog/settings/`, with values from the deployment secret store and charts. Never store a secret as an instance setting, because the database keeps it as plain text. A per-team rollout or a team allowlist is a feature flag.
-
-### Django admin
-
-- **A new `ForeignKey`/`OneToOneField` on an admin-exposed model needs explicit widget config.** `[review]` List the field in `autocomplete_fields`, `raw_id_fields`, or `readonly_fields` on **every** admin class that renders the model, including inlines attached to a related admin. Otherwise the default `<select>` loads the entire target table per row on each change-page render. Declare it on a shared base inline so per-parent variants inherit it.
-
-### LLM gateway
-
-- **`services/llm-gateway` is under an unofficial code freeze** while callers move to [`PostHog/ai-gateway`](https://github.com/PostHog/ai-gateway). `[review]` If a task asks you to change it, tell the user about the freeze in your reply. New callers and features belong on the Go gateway. A Python gateway change needs a documented parity blocker for an active caller and stays limited to it — read [`services/llm-gateway/PARITY.md`](services/llm-gateway/PARITY.md). Its Postgres role reads only allowlisted tables: a new table read needs the SELECT grant landed in posthog-cloud-infra for every environment first, then a declaration in `required_tables.py`. The readiness probe checks every declared grant on every probe, so a missing grant holds a rollout instead of serving 500s. Use `/auditing-llm-gateway-parity` for contract changes, `/finding-llm-gateway-migration-candidates` to pick the next caller, `/migrating-llm-gateway-callers` to move one.
+The rules for architecture live in [.agents/architecture.md](.agents/architecture.md). Its row in [Read the guide for your area first](#read-the-guide-for-your-area-first) says when to read it.
## Code Style
-Same tags as above: `[lint: <id>]` is machine-enforced, `[review]` is not.
-
-### Python
-
-- **Write as if mypy `--strict` were on.** `[review]` Annotate every signature, avoid `Any`, put type-only references under `TYPE_CHECKING`. The config is not fully strict yet; new code should be. When a change is type-risky run mypy the way CI does — `uv run mypy .`, repo-wide, never a file subset. It follows imports, so a subset misses reverse-dependency breakage.
-- **Imports stay at module level.** `[review]` ruff's `PLC0415` catches this, but `posthog/**`, `ee/**`, `common/**`, `tools/**` and most of `products/` are on grandfathered exemption lists, so CI does not block it in the trees you are most likely to be editing. Defer one only to break a true unavoidable circular import, to reference types under `TYPE_CHECKING`, or to keep a heavy or optional dependency off the import path. For the last case add a justified `# noqa: PLC0415 — keeps the heavy dep off the import path` on the line. Never blanket-suppress the rule.
-- **A stdlib `@dataclass` must declare `frozen=` explicitly.** `[lint: prefer-frozen-dataclasses, test_dataclass_defaults.py]` A bare `@dataclass` fails the ratchet; `@dataclass(frozen=False)` passes it, so intentional mutability is a choice you state.
-- **The house decorator is `@frozen` from `posthog.dataclasses`.** `[review]` Neither check prefers it over a declared stdlib `@dataclass`. Invoke `/writing-dataclasses` before adding or changing one, before returning or passing several values together, and before passing a dataclass through layers.
-- **`product:lint` and the pytest collision test say where an `__init__.py` is required, and print the fix.** `[lint: product:lint, test_pytest_module_collisions.py]` Run them rather than reasoning about it.
-- **Do not add or delete an `__init__.py` speculatively.** `[review]` Whether a directory needs one depends on what sits above it. Neither check objects to a needless one outside `products/` that creates no module-name collision, so only a reader catches that.
-- Prefer classes over loose functions unless a class genuinely does not fit. `[review]` Use `pathlib` over `os.path`. Order functions and methods so a definition appears before its first call.
-
-### Frontend
-
-- **Follow [frontend/src/AGENTS.md](frontend/src/AGENTS.md) for all frontend work** — the main app and `products/*/frontend/` alike, since they share components and generated types. `[review]` It covers reusing Lemon/quill components instead of hand-rolling tables, badges and labels, importing generated `*Api` types instead of handwriting them, when to run typecheck and typegen, and when to read [frontend/src/platform-ux.md](frontend/src/platform-ux.md) (before you build, edit, simplify or redesign any UI).
-- **TypeScript with explicit return types. Business logic goes in the kea logic file, not a React hook.** `[review]`
-- **Guard every network-triggering button against double submission.** `[review]` Disable it and show a loading state (`loading` / `disabledReason` on `LemonButton`, or equivalent) while the request is in flight, and reset in both the success and error paths. Applies to `<form onSubmit>`, any `onClick` that calls `api.*`, and any kea `listener` that issues a request. Wire in the in-flight state from a loader `*Loading` selector, a reducer, or local `useState`.
-- **Every surface must hold up narrow.** `[review]` The nav sidebar plus an open side panel leave a 1280px window about 520px of scene. Break on container queries, not `md:`/`lg:`/`xl:`. Wrap or truncate rather than clip, and stack halves that no longer fit. Render at a few widths before calling it done. We do not support mobile — no phone-width layouts, no touch-sized targets. See "Rule 6" in [frontend/src/AGENTS.md](frontend/src/AGENTS.md).
-- **quill is for MCP apps, the desktop app, and the web app UI behind the `today-rail-nav` feature flag; LemonUI is for the rest of the web app.** `[review]` `today-rail-nav` gates a quill redesign of the whole web app UI, built alongside the current UI and kept behind the flag for months. Build or change UI on that path with quill, and read [frontend/src/design.md](frontend/src/design.md) first: it holds the components, tokens and decision rules. The current UI stays on LemonUI while the flag exists: do not add quill to it or convert it in place. On that flag-off path in `frontend/src/` and `products/*/frontend/` use LemonUI, including menus — `LemonMenu` with a `LemonButton` trigger. `lib/ui/DropdownMenu` (Radix) is legacy; do not add new ones. Where quill is right, do not mix the two inside one component, and remember quill uses Base UI's `render` prop, not Radix's `asChild`. Read [primitives/AGENTS.md](packages/quill/packages/primitives/AGENTS.md) before importing quill — it covers component choice and spacing. Charts: [/working-with-charts](.agents/skills/working-with-charts/SKILL.md) for consumers, [charts/AGENTS.md](packages/quill/packages/charts/AGENTS.md) for library changes. DataTable and DateTimePicker: [components/AGENTS.md](packages/quill/packages/components/AGENTS.md).
-- Use tailwind utility classes over inline styles, and `lib/dayjs` over a direct dayjs import. `[review]` oxlint warns on a `style` prop through `react/forbid-dom-props`, but a warning does not block.
-
-### Comments
-
-- **Explain _why_, not _what_,** and only where a future reader with no access to this PR or chat would otherwise be confused. `[review]` Default to one line. Python tests get no doc comments.
-- **Never log change history or chat context in code.** `[review]` No "previously did X, now does Y", no "per <task/PR>", no "changed because…", no "AI:" or "agent:" notes. That belongs in the commit message and PR description.
-- **When refactoring or moving code, keep the existing comments** unless the change actually makes them obsolete. `[review]`
-- Use ASD-STE100 Simplified Technical English: active voice, simple tenses, one idea per sentence, consistent terms. `[review]`
-
-### Tests
-
-- **Every new test must catch a realistic regression no existing test catches.** `[review]` If you cannot name that regression, do not add the test. Assert observable behavior through the public interface, not implementation details, and keep it cheap — deterministic, isolated, at the lowest level that catches the bug. See `/writing-tests`.
-- **Extend a relevant existing test rather than adding a standalone one** where practical, and parameterize variations of the same behavior (`parameterized` in Python, `test.each` in Jest). `[review]`
-- Jest: one top-level `describe` per file. `[review]` Node.js Jest: `.test.ts` by default, `.serial.test.ts` only when shared mutable infrastructure cannot be isolated (a test that resets a shared database).
-
-### Markdown and prose
-
-- Semantic line breaks, no hard wrapping. American English spelling. `[review]`
+The rules for code style live in [.agents/code-style.md](.agents/code-style.md). Its row in [Read the guide for your area first](#read-the-guide-for-your-area-first) says when to read it.
## User-facing copy
-For any text a person reads (UI labels, tooltips, empty/error states, notifications, docs, support replies). Invoke `/writing-user-facing-copy` before writing or editing it — that skill carries the full voice, em-dash, and feature-naming rules. When unsure whether copy reads well, ask a human.
-
-- Sentence case, not Title Case: capitalize only the first word and proper nouns ('Product analytics', 'Save as view').
-- Avoid the tells of AI-generated text: em dashes (—), "not just X, but Y", rule-of-three padding, hedging preambles. Write like a person typed it; if you can't tell, ask a human.
-- Plain language, no jargon. Use the labels users see, not internal names (`surveyPopupDelaySeconds` becomes "Delay the survey popup").
-- Be direct and friendly: short sentences, consistent tone across surfaces.
-- Errors and empty states guide, don't dead-end: say what happened and the next action.
+Invoke `/writing-user-facing-copy` before you write or edit text a person reads. It carries the voice, sentence-case, em-dash, and feature-naming rules. When unsure whether copy reads well, ask a human.
## Feature usage tracking
-- **Every feature is tracked end to end.** A user's path through a feature, from entry to outcome, emits events that show whether people start it, finish it, and where they drop off.
-- **Features adjacent to your work get tracking too.** A feature is adjacent when it shares a scene or a user flow with your change. When an adjacent feature has no tracking, add it in the same change.
-- **Check usage of tracked adjacent features.** Run a subagent that queries each tracked adjacent feature's usage over the last 6 months.
- - Fewer than 100 interactions a week counts as low usage. Zero events in 6 months is the extreme case of low usage.
- - Before you act on low usage, confirm the tracking fires: trigger the feature locally and check that the events arrive. Missing events can mean broken tracking, not an unused feature.
- - Post each low-usage feature and its usage numbers in the platform UX Slack channel (Channel ID: `C08499A7REU`). The decision to keep or remove the feature is made there. Do not remove a feature before that decision.
+The rules for feature usage tracking live in [.agents/feature-usage-tracking.md](.agents/feature-usage-tracking.md). Its row in [Read the guide for your area first](#read-the-guide-for-your-area-first) says when to read it.
## Agent automation
-When automating a convention, try these in order — only fall back to the next if the previous isn't suitable:
-
-1. **Linters** (ruff, oxlint, semgrep) — code pattern enforcement, always paired with CI
-2. **lint-staged / husky** — file-level validation or warnings at commit time
-3. **Skills** (`.agents/skills/`) — scaffold with `hogli init:skill`
-4. **AGENTS.md / CLAUDE.md instructions** — when automated enforcement isn't suitable
-
-Claude Code hooks are reserved for environment bootstrapping (`SessionStart` only) — do not add `PreToolUse`, `PostToolUse`, or `Notification` hooks as they add latency and are fragile.
-Changes to `.claude/hooks/` trigger a warning from the `pre-commit` hook; lint-staged allows only repo-wide keys in `.claude/settings.json`, because personal settings belong in the gitignored `.claude/settings.local.json`.
-A warn-only check belongs in the `pre-commit` hook body rather than in a lint-staged task, because lint-staged discards the output of every task that exits 0.
+The rules for agent automation live in [.agents/agent-automation.md](.agents/agent-automation.md). Its row in [Read the guide for your area first](#read-the-guide-for-your-area-first) says when to read it.
-### Mandatory skill invocation
+## Mandatory skill invocation
Each entry below is a trigger, not a task list: it fires on what the diff contains, whether you are writing that code or reading someone else's.
ALWAYS invoke the matching skill **first** — do not skip it, and do not attempt the work or the review without loading it.
@@ -333,7 +234,7 @@ ALWAYS invoke the matching skill **first** — do not skip it, and do not attemp
- `/profiling-slow-api-endpoints` — an endpoint, list, picker, or scene is slow, a p95 latency number needs explaining, or a Postgres query plan needs checking against production rather than a local database
- `/placing-product-frontend-code` — adding a frontend file or directory for a product, or deciding between `products/<name>/frontend/` and `frontend/src/scenes/<name>/`
- `/building-the-toolbar`: any change under `frontend/src/toolbar/`, floating toolbar or extension. Build and check both, and keep them in sync
-- [`products/conversations/skills/organizing-conversations-code/SKILL.md`](products/conversations/skills/organizing-conversations-code/SKILL.md) — adding, moving, renaming, or reviewing files under `products/conversations/`
+- `/organizing-conversations-code` — adding, moving, renaming, or reviewing files under `products/conversations/`
- `/integrating-with-posthog-ai` — making a product surface work with PostHog AI: injecting scene context or custom instructions, reacting to the agent's tool calls, or rendering your product's tool cards in a thread
- `/sending-notifications` — adding notification support
- `/routing-outbound-api-calls` — adding or changing Python code that calls a third-party HTTP API, or changing any domain under `posthog/egress/` (budget, lanes, identity, metrics, headers)
diff --git a/docs/internal/ci-things-already-tried.md b/docs/internal/ci-things-already-tried.md
index 198c04b06443..38daba9b98aa 100644
--- a/docs/internal/ci-things-already-tried.md
+++ b/docs/internal/ci-things-already-tried.md
@@ -746,7 +746,7 @@ One narrow PR from the same window did merge. [#41620](https://github.com/PostHo
The setting is in `posthog/settings/data_stores.py`, and `Person.Meta.db_table` reads it. It defaults to `posthog_person`, so the cutover is off.
The switch exists. The eight PRs above failed at what surrounds it: the test setup, the dual reads, and the partition guard.
`posthog_person_new` comes from the sqlx migrations in `rust/persons_migrations/`. Three Dagster jobs read it, and one carries a comment about a future name swap.
-Person and group data now goes through the gRPC client in `posthog/personhog_client/`. `AGENTS.md` makes that client the required interface and prohibits new ORM queries against the person tables.
+Person and group data now goes through the gRPC client in `posthog/personhog_client/`. `.agents/architecture.md` makes that client the required interface and prohibits new ORM queries against the person tables.
Read this entry before you propose a Django-level cutover. The setting is already there.
What is missing is everything that must be true before a person changes its value.
diff --git a/frontend/src/AGENTS.md b/frontend/src/AGENTS.md
index 48b340c8d6aa..8c2400997b0a 100644
--- a/frontend/src/AGENTS.md
+++ b/frontend/src/AGENTS.md
@@ -1,6 +1,6 @@
# Frontend agent guide (`frontend/src`)
-Applies to any change under `frontend/src`. This is a **discovery + cadence** guide: the rules below exist because agents tend to generate before they look. The root `AGENTS.md` and the quill package guides remain authoritative, except that [`design.md`](./design.md) wins over a quill package guide for UI behind `today-rail-nav` — this file does not repeat them, it points at them.
+Applies to any change under `frontend/src`. This is a **discovery + cadence** guide: the rules below exist because agents tend to generate before they look. The root `AGENTS.md`, [`.agents/code-style.md`](../../.agents/code-style.md), and the quill package guides remain authoritative, except that [`design.md`](./design.md) wins over a quill package guide for UI behind `today-rail-nav` — this file does not repeat them, it points at them.
Before you build or edit any UI, or when a task asks to simplify or redesign one, read [`platform-ux.md`](./platform-ux.md). It decides what a surface shows and when (progressive disclosure first), on LemonUI and quill alike. Only the platform UX team changes the nav rail.
@@ -36,7 +36,7 @@ If nothing fits, say so and propose extending the existing component before addi
The same goes for patterns, not just components: before building a new scene or view, read 2–3 comparable ones and model yours on those that follow these rules. Precedent that violates Rule 5 or `/writing-ui-components` is legacy to route around, not license to repeat — conventions outrank precedent, and compliant precedent outranks invention.
-> LemonUI vs quill lives in the root `AGENTS.md` ("Code Style → Frontend (quill vs LemonUI)"). If you're working somewhere quill applies (an MCP app, the desktop app, UI behind `today-rail-nav`), [`design.md`](./design.md) and `packages/quill/packages/primitives/AGENTS.md` have its component-choice and spacing rules, and the two libraries must not be mixed inside one component's internals.
+> LemonUI vs quill lives in [`.agents/code-style.md`](../../.agents/code-style.md) ("Frontend"). If you're working somewhere quill applies (an MCP app, the desktop app, UI behind `today-rail-nav`), [`design.md`](./design.md) and `packages/quill/packages/primitives/AGENTS.md` have its component-choice and spacing rules, and the two libraries must not be mixed inside one component's internals.
## Rule 2 — A product's UI goes in `products/<name>/frontend/`
@@ -64,7 +64,7 @@ When touching `lib/api`, `api.get<`, `api.create<`, or any handwritten API inter
## Rule 4 — Business logic in kea, not React hooks
-Covered by the root `AGENTS.md` (Code Style → Frontend). The discovery hint for this tree: if a scene/component has a `*Logic.ts`, that's where actions/reducers/selectors/listeners belong. See `/writing-kea-logics` and `/using-kea-disposables`.
+Covered by [`.agents/code-style.md`](../../.agents/code-style.md) ("Frontend"). The discovery hint for this tree: if a scene/component has a `*Logic.ts`, that's where actions/reducers/selectors/listeners belong. See `/writing-kea-logics` and `/using-kea-disposables`.
## Rule 5 — Structure and abstraction
@@ -146,7 +146,7 @@ These are slow; run them at the right moment, not after every edit.
## Lint & format
-Run `pnpm --filter=@posthog/frontend fix` before finishing. It applies safe Oxlint fixes, never suggestion fixes, and always runs Oxfmt; it fails if either tool fails. `format` runs Oxfmt only, while `lint` and `format:check` only verify. Config: root `.oxlintrc.json`. CSS, spelling, and copy-casing rules live in the root `AGENTS.md` (Code Style).
+Run `pnpm --filter=@posthog/frontend fix` before finishing. It applies safe Oxlint fixes, never suggestion fixes, and always runs Oxfmt; it fails if either tool fails. `format` runs Oxfmt only, while `lint` and `format:check` only verify. Config: root `.oxlintrc.json`. CSS and spelling rules live in [`.agents/code-style.md`](../../.agents/code-style.md), and copy-casing rules in `/writing-user-facing-copy`.
## Adding actions to a scene
@@ -156,7 +156,7 @@ Adding a button/toggle/action to a scene's `ScenePanel`? It must also go in that
## Deeper references
-- Root `AGENTS.md` — full Code Style + architecture rules (authoritative).
+- [`.agents/code-style.md`](../../.agents/code-style.md) and [`.agents/architecture.md`](../../.agents/architecture.md) — full code style and architecture rules (authoritative).
- `layout/scenes/AGENTS.md` (scene action surfaces: `ScenePanel` + `SceneMenuBar` dual-write rule).
- `packages/quill/packages/primitives/AGENTS.md` — component selection matrix.
- `/working-with-charts`: chart consumption workflow with links to the relevant examples and package docs.
diff --git a/posthog/test/repo_invariants/test_agents_md_enforcement_tags.py b/posthog/test/repo_invariants/test_agents_md_enforcement_tags.py
index c0d7aa555822..e9305675907a 100644
--- a/posthog/test/repo_invariants/test_agents_md_enforcement_tags.py
+++ b/posthog/test/repo_invariants/test_agents_md_enforcement_tags.py
@@ -16,8 +16,11 @@ EXECUTED_CHECK_ROOTS = ("posthog/test/repo_invariants", ".github/scripts")
# is not loaded by a blocking job, so it cannot back a tag.
LOADED_SEMGREP_ROOTS = (".semgrep/rules/security", ".semgrep/rules/devex")
-# Sections whose every rule must declare what enforces it.
-TAGGED_SECTIONS = (("## Architecture guidelines", "## Code Style"), ("## Code Style", "## User-facing copy"))
+# Agent guides whose every rule must declare what enforces it.
+TAGGED_GUIDES = (".agents/architecture.md", ".agents/code-style.md")
+
+# Root sections that only point at a tagged guide, so a rule added there would skip the tag check.
+POINTER_SECTIONS = ("## Architecture guidelines", "## Code Style")
# Tags naming a command or CI job rather than a rule id. Add to this set only
# when no single rule id covers the check.
@@ -32,21 +35,28 @@ def _repo_root() -> Path:
return Path(__file__).resolve().parents[3]
-def _agents_md(repo_root: Path) -> str:
- return (repo_root / "AGENTS.md").read_text()
+def _read(repo_root: Path, guides: tuple[str, ...]) -> str:
+ return "\n".join((repo_root / guide).read_text() for guide in guides)
+
+
+def _guides_with_tags(repo_root: Path) -> tuple[str, ...]:
+ agents_dir = repo_root / ".agents"
+ return ("AGENTS.md", *sorted(str(path.relative_to(repo_root)) for path in agents_dir.glob("*.md")))
+
+
+def _section(markdown: str, heading: str) -> str:
+ start = markdown.index(heading) + len(heading)
+ end = markdown.find("\n## ", start)
+ return markdown[start:] if end == -1 else markdown[start:end]
-def _tags(agents_md: str) -> list[str]:
- tags = (tag.strip() for marker in MARKER.findall(agents_md) for tag in marker.split(","))
+def _tags(guides: str) -> list[str]:
+ tags = (tag.strip() for marker in MARKER.findall(guides) for tag in marker.split(","))
return [tag for tag in tags if tag != LEGEND_PLACEHOLDER]
-def _rules(agents_md: str) -> list[str]:
- rules: list[str] = []
- for start, end in TAGGED_SECTIONS:
- section = agents_md[agents_md.index(start) : agents_md.index(end)]
- rules.extend(line for line in section.split("\n") if line.startswith("- "))
- return rules
+def _rules(guides: str) -> list[str]:
+ return [line for line in guides.split("\n") if line.startswith("- ")]
def _semgrep_ids(repo_root: Path) -> set[str]:
@@ -98,13 +108,13 @@ def test_agents_md_lint_tags_name_something_real() -> None:
repo_root = _repo_root()
semgrep_ids = _semgrep_ids(repo_root)
- tags = _tags(_agents_md(repo_root))
- assert tags, "AGENTS.md has no [lint: ...] tags — did the marker format change?"
+ tags = _tags(_read(repo_root, _guides_with_tags(repo_root)))
+ assert tags, "The agent guides have no [lint: ...] tags — did the marker format change?"
unresolved = [tag for tag in tags if not _resolves(tag, repo_root, semgrep_ids)]
assert not unresolved, (
- f"AGENTS.md tags these as machine-enforced, but nothing by that name enforces them: {unresolved}. "
+ f"The agent guides tag these as machine-enforced, but nothing by that name enforces them: {unresolved}. "
"Either the rule was renamed or deleted, or a ruff code moved to `ignore` or a per-file exemption "
"list (fix the tag, or retag the "
f"rule as [review]), or the tag names a command rather than a rule id (add it to FREE_FORM in {Path(__file__).name})."
@@ -113,13 +123,25 @@ def test_agents_md_lint_tags_name_something_real() -> None:
def test_every_architecture_and_code_style_rule_is_tagged() -> None:
# An untagged rule reads as review-only without saying so, which is the ambiguity the tags remove.
- rules = _rules(_agents_md(_repo_root()))
- assert rules, "Found no rules to check — did the section headings change?"
+ rules = _rules(_read(_repo_root(), TAGGED_GUIDES))
+ assert rules, "Found no rules to check — did the guides move?"
untagged = [rule[:80] for rule in rules if not WELL_FORMED.search(rule)]
assert not untagged, (
- f"These AGENTS.md rules carry no well-formed enforcement tag: {untagged}. "
+ f"These architecture and code style rules carry no well-formed enforcement tag: {untagged}. "
"Add `[lint: <rule-id>]` when a linter or invariant test blocks the violation, or `[review]` when "
"nothing catches it. An empty or unclosed marker does not count."
)
+
+
+def test_root_pointer_sections_hold_no_rules() -> None:
+ # A rule written under a pointer heading in the root file would escape the tag check above.
+ agents_md = (_repo_root() / "AGENTS.md").read_text()
+
+ misplaced = [heading for heading in POINTER_SECTIONS if _rules(_section(agents_md, heading))]
+
+ assert not misplaced, (
+ f"These AGENTS.md sections only point at a guide under .agents/, but hold rules: {misplaced}. "
+ "Move each rule into the guide the section points at."
+ )
diff --git a/products/ai_observability/AGENTS.md b/products/ai_observability/AGENTS.md
index 1ae3bb5abc5c..4d22a534f5e5 100644
--- a/products/ai_observability/AGENTS.md
+++ b/products/ai_observability/AGENTS.md
@@ -1,7 +1,8 @@
# AI observability agent guide
-Repo-wide conventions live in [`../../AGENTS.md`](../../AGENTS.md) — kea over hooks, generated
-API over `api.get`, `ph_scoped_capture` in Celery, etc. Read that first.
+Repo-wide conventions live in [`../../AGENTS.md`](../../AGENTS.md) and the guides it links,
+[`code-style.md`](../../.agents/code-style.md) and [`architecture.md`](../../.agents/architecture.md) — kea over hooks, generated
+API over `api.get`, `ph_scoped_capture` in Celery, etc. Read those first.
This file is only for rules that are specific to `products/ai_observability/`
(and to the query runners in `posthog/hogql_queries/ai/`).
diff --git a/products/review_hog/backend/management/commands/reset_review_hog.py b/products/review_hog/backend/management/commands/reset_review_hog.py
index b14ce18a0dd8..efbf62156eda 100644
--- a/products/review_hog/backend/management/commands/reset_review_hog.py
+++ b/products/review_hog/backend/management/commands/reset_review_hog.py
@@ -46,7 +46,7 @@ class Command(BaseCommand):
skip_confirm: bool = options["yes"]
# A full local wipe is genuinely cross-team, so go through `unscoped()` — the fail-closed
- # managers would otherwise raise without a team context (CLAUDE.md cross-team escape hatch).
+ # managers would otherwise raise without a team context (.agents/architecture.md cross-team escape hatch).
artefacts = ReviewReportArtefact.objects.unscoped()
reports = ReviewReport.objects.unscoped()
configs = ReviewSkillConfig.objects.unscoped()
diff --git a/products/stamphog/AGENTS.md b/products/stamphog/AGENTS.md
index 185f97a6095d..9335f820dad5 100644
--- a/products/stamphog/AGENTS.md
+++ b/products/stamphog/AGENTS.md
@@ -64,7 +64,7 @@ A team left with none of those is not a digest audience at all.
Subtracting rather than only dropping the all-generated case came from the same channel getting swept again: one regenerated file next to one real one read as a two-file stake, which is above the graze rule's threshold, so the sweep looked like ownership.
Three things keep it from being the harmless-file rule above.
It decides who hears about a merge, never whether code is safe to approve.
-The root `CLAUDE.md` forbids hand-editing those files, so the hand-edited-and-still-ships case does not apply to this path.
+[`.agents/architecture.md`](../../.agents/architecture.md) forbids hand-editing those files, so the hand-edited-and-still-ships case does not apply to this path.
And it names one exact directory shape rather than any `generated/` directory, which is the match that would catch hand-editable code elsewhere.
Both sides are read with `compare_diff`, from the base and head shas the run and the payload already fixed.
diff --git a/products/stamphog/packages/pr-approval-agent/gates.py b/products/stamphog/packages/pr-approval-agent/gates.py
index d7f80c68de16..cedd58773d70 100644
--- a/products/stamphog/packages/pr-approval-agent/gates.py
+++ b/products/stamphog/packages/pr-approval-agent/gates.py
@@ -265,7 +265,7 @@ TEAM_FILE_SAMPLE = 10
#
# Deliberately narrow. This is a "these files carry no news" rule, which AGENTS.md says needs an
# argument, and the argument only holds for this one directory shape: the repo forbids hand-editing
-# it (root CLAUDE.md, "don't edit them manually, change serializers and rerun"), every product's
+# it (.agents/architecture.md: change the serializer and regenerate instead), every product's
# generated directory has this exact path, and its only consumer decides who hears about a merge
# rather than whether code is safe to approve. A bare `generated/` match would also catch
# hand-editable directories elsewhere in the tree, which is the case AGENTS.md warns about.
diff --git a/products/stamphog/packages/pr-approval-agent/test_gates.py b/products/stamphog/packages/pr-approval-agent/test_gates.py
index 3c3b6dedd0f4..16195cfb00cf 100644
--- a/products/stamphog/packages/pr-approval-agent/test_gates.py
+++ b/products/stamphog/packages/pr-approval-agent/test_gates.py
@@ -290,6 +290,11 @@ def test_no_false_positive(files: list[str]) -> None:
"devex_guardrails",
id="egress-agents-md-matches-lowercased",
),
+ pytest.param(
+ [".agents/code-style.md"],
+ "agent_steering",
+ id="root-agents-topic-guide",
+ ),
pytest.param(
["posthog/ingress/verify/hmac.py"],
"devex_guardrails",
diff --git a/products/stamphog/packages/pr-approval-agent/test_policy.py b/products/stamphog/packages/pr-approval-agent/test_policy.py
index a26a183676f5..e6d3ec9e058f 100644
--- a/products/stamphog/packages/pr-approval-agent/test_policy.py
+++ b/products/stamphog/packages/pr-approval-agent/test_policy.py
@@ -152,6 +152,7 @@ OLD_DENY_PATTERN_DEFS = {
"paths": [
"^agents\\.md$",
"^claude\\.md$",
+ "^\\.agents/(agent-automation|architecture|ci|code-style|feature-usage-tracking)\\.md$",
"^\\.github/pull_request_template\\.md$",
"^\\.agents/skills/writing-pr-descriptions/",
"^\\.claude/settings\\.json$",