PostHog Development Guide

Codebase Structure

• Key entry points: posthog/api/__init__.py (API URL routing skeleton; products register their own routes in products/<name>/backend/routes.py via register_routes(routers)), posthog/settings/web.py (Django settings, INSTALLED_APPS), products/ (product apps)
• Monorepo layout - high-level directory structure (products, services, common, tools)
• Products README - how to create and structure products
• Products architecture - DTOs, facades, isolated testing

Commands

• Environment:
  • Use flox when available — prefer flox activate -- bash -c "<command>" if commands fail
    • Never use flox activate in interactive sessions (it hangs if you try)
• Tests:
  • Universal: hogli test <file_or_directory> — auto-detects test type (Python, Jest, Playwright, Rust, Go)
  • Single test: hogli test path/to/test.py::TestClass::test_method
  • Watch mode: hogli test path/to/test.py --watch
  • Changed files only: hogli test --changed
• Lint:
  • Python:
    • ruff check . --fix and ruff format .
  • Frontend: pnpm --filter=@posthog/frontend format
  • TypeScript check: pnpm --filter=@posthog/frontend typescript:check
• Build:
  • Frontend: pnpm --filter=@posthog/frontend build
  • Start dev: ./bin/start or hogli start (interactive TUI). Detached mode: hogli up -d paired with hogli wait / hogli down
• OpenAPI/types: hogli build:openapi (regenerate after changing serializers/viewsets)
• New product: bin/hogli product:bootstrap <name>
• LSP: Pyright is configured against the flox venv. Prefer LSP (goToDefinition, findReferences, hover) over grep when navigating or refactoring Python code.

Commits and Pull Requests

• Use conventional commits for all commit messages and PR titles.
• Check docs for any content that may need updating, you can find these at docs/

Commit types

• feat: New feature or functionality (touches production code)
• fix: Bug fix (touches production code)
• chore: Non-production changes (docs, tests, config, CI, refactoring agents instructions, etc.)
• Scope convention: use llma for LLM analytics changes (for example, feat(llma): ...)

Format

<type>(<scope>): <description>

Examples:

• feat(insights): add retention graph export
• fix(cohorts): handle empty cohort in query builder
• chore(ci): update GitHub Actions workflow
• chore: update AGENTS.md instructions

PR descriptions

Required: Before creating any PR, read .github/pull_request_template.md and use its exact section structure. Do not invent a different format. Always fill the ## 🤖 Agent context section when creating PRs. Keep descriptions high-level, focusing on rationale and architecture for the human reviewer. NEVER share sensitive information in a PR description. Users may share sensitive data in an agent session, but those should never surface to a PR description, or comments. Pass the description straight to the body argument of the PR-creation tool (the GitHub MCP create_pull_request body param, or gh pr create --body-file - via stdin). Do NOT write the body to a temporary file first — it adds a step, can race with parallel tool calls, and the body argument already preserves markdown and newlines verbatim (the no-hard-wrap rule still applies).

Rules

• Scope is optional but encouraged when the change is specific to a feature area
• Description should be lowercase and not end with a period
• Keep the first line under 72 characters

Pushing to remote

Don't open GitHub issues or pull requests without human instruction. Once a branch already has an open PR, push incremental changes and fixes to it without waiting for human guidance — keeping the PR current is part of the work. Pushes still trigger CI, which burns runner credits, so batch related commits and push once the increment is ready rather than after every change.

Public open source repo guidance

This repository is public and all commit messages, pull request titles, and pull request descriptions must be safe for public readers.

• Never mention internal-only systems, private incidents, customer data, private Slack threads, unreleased roadmap details, or security-sensitive implementation details.
• Use product-facing and code-facing context that a public OSS contributor could understand from this repository alone.
• If context is sensitive, summarize it at a high level without naming internal tools, accounts, or people.
• Avoid citing private operational scale or incident metrics (for example, exact affected team counts, internal row-volume anecdotes, or customer-specific performance numbers) unless that data is already public and linkable.

Examples:

• ✅ fix(insights): handle missing series color in trend export
• ❌ fix: patch issue found in acme-co prod workspace after sales escalation — references internal customer
• ❌ fix: will run fine on our 12 million rows there now — leaks private operational scale

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
• Every job in .github/workflows/ must declare timeout-minutes — prevents stuck runners from burning credits indefinitely
• CI workflow changes must stay backwards compatible with open PRs that haven't rebased. A workflow edit hits every in-flight PR immediately (it runs against the PR merged with master), but companion changes — a new dependency, file, or config — only reach a branch once it rebases. If the workflow starts requiring something an unrebased branch lacks, every such PR fails before its tests run. Make the new behavior degrade gracefully when the prerequisite is absent, or gate it so unrebased branches are unaffected. This has broken CI repeatedly.

Security

See .agents/security.md for SQL, HogQL, and semgrep security guidelines.

Architecture guidelines

• API views should declare request/response schemas — prefer @validated_request from posthog.api.mixins or @extend_schema from drf-spectacular. Plain ViewSet methods that validate manually need @extend_schema(request=YourSerializer) — without it, drf-spectacular can't discover the request body and generated code gets empty schemas
• Django serializers are the source of truth for frontend API types — hogli build:openapi generates TypeScript via drf-spectacular + Orval. Generated files (api.schemas.ts, api.ts, api.zod.ts) live in frontend/src/generated/core/ and products/{product}/frontend/generated/ — don't edit them manually, change serializers and rerun. See type system guide for the full pipeline
• MCP tools are generated from the same OpenAPI spec — see implementing MCP tools for the YAML config and codegen workflow
• MCP UI apps (interactive visualizations for tool results) are defined in products/*/mcp/tools.yaml under ui_apps and auto-generated — see services/mcp/CONTRIBUTING.md or use the implementing-mcp-ui-apps skill
• When touching a viewset or serializer, ensure schema annotations are present (@extend_schema or @validated_request on viewset methods, help_text on serializer fields) — these flow into generated frontend types and MCP tool schemas
• New features should live in products/ — read products/README.md for layout and setup. When creating a new product, follow products/architecture.md (DTOs, facades, isolation). Code a single product owns — not just backend/frontend, but scripts, CLIs, services, packages, MCP tools, skills — belongs under products/<product>/; reserve top-level tools//services//packages//cli/ for cross-product things
• Every tenant-data model must have team_id — either as a FK (models.ForeignKey("posthog.Team", ...)) or a plain BigIntegerField (for multi-DB products). This is the primary tenant isolation boundary. Models without team_id must be org-scoped, user-scoped, or instance-global — never silently unscoped. New models should inherit from TeamScopedRootMixin (main DB) or ProductTeamModel (separate DB) so they start fail-closed — see posthog/models/scoping/README.md. CI enforces this via posthog/models/scoping/baseline_unmigrated.txt: any new team-scoped model not on a fail-closed manager fails the IDOR coverage check. In serializers, access the team via self.context["get_team"](). When querying a fail-closed model for one team outside request context (Temporal activities, Celery tasks, management commands), use Model.objects.for_team(team_id) — not Model.all_teams.filter(team_id=...) or objects.unscoped().filter(...); reserve all_teams/unscoped() for genuinely cross-team access and Django framework internals. Caveat: for_team(...).get_or_create(...)/.create(...) still need team_id passed explicitly — queryset filters don't propagate into row creation
• Do not add domain-specific fields to the Team model. Use a Team Extension model instead — see posthog/models/team/README.md for the pattern and helpers
• PostHog event capture in Celery tasks: Do not use posthoganalytics.capture() in Celery tasks — events are silently lost. Use ph_scoped_capture from posthog.ph_client instead (see its docstring for why and usage).
• Django admin ForeignKey fields need explicit widget config. When adding a ForeignKey/OneToOneField to a model that's exposed in Django admin (including via inlines attached to a related admin), list the new field in autocomplete_fields, raw_id_fields, or readonly_fields on every admin class that renders the model — otherwise the default <select> widget loads the entire target table per row on each change-page render. Prefer declaring the config on a shared base inline so per-parent variants (e.g., subclasses differentiated by fk_name) inherit it automatically.
• Use personhog client for all person/group data access — do not query persons DB tables via the Django ORM or raw SQL. The posthog/personhog_client/ gRPC client is the required interface for reading and writing person-related data. This applies to the following tables: posthog_person, posthog_persondistinctid, posthog_cohortpeople, posthog_group, posthog_grouptypemapping, and related override tables (posthog_personoverride, posthog_pendingpersonoverride, posthog_flatpersonoverride, posthog_featureflaghashkeyoverride, posthog_personlessdistinctid, posthog_personoverridemapping). Use the helpers in posthog/models/person/util.py (e.g. get_person_by_uuid, get_persons_by_distinct_ids, get_person_by_distinct_id) and posthog/models/group_type_mapping.py (get_group_types_for_project) — these already route through personhog with ORM fallback via _personhog_routed(). When adding new person/group data access, follow the same _personhog_routed() pattern: provide a personhog_fn using get_personhog_client() and an orm_fn fallback. Never add new direct ORM queries like Person.objects.filter(...) or PersonDistinctId.objects.filter(...) — use the existing routed helpers or create new ones following the established pattern. See posthog/personhog_client/README.md for client details and posthog/personhog_client/client.py for the full RPC interface.
• PostHog does not enable ATOMIC_REQUESTS — there is no implicit per-request transaction. Each database operation runs in autocommit mode unless explicitly wrapped. Use with transaction.atomic(): around the specific writes that must succeed or fail together. Do not wrap an entire view method atomically — keep the block as narrow as possible around the related writes. Avoid performing irreversible side effects (sending emails, calling external APIs, enqueuing Celery tasks) inside an atomic block: if the transaction rolls back, those side effects have already happened. Schedule such side effects after the commit, or use transaction.on_commit() for Celery task dispatch.
• Prefer SeaweedFS over MinIO for object storage — we are working to remove MinIO from the stack. SeaweedFS (the seaweedfs service, S3 API on :8333) is the direction of travel for S3-compatible object storage and already backs session replay v2 (SESSION_RECORDING_V2_S3_* settings, default endpoint http://seaweedfs:8333). MinIO (the objectstorage service, S3 API on :19000) still backs general object storage (OBJECT_STORAGE_* settings — exports, media uploads, error-tracking source maps, query cache, tasks), but it is being phased out. Do not introduce new dependencies on MinIO: don't add new docker-compose services, scripts, tests, or docs that stand up a minio/minio container or hardcode objectstorage:19000. Both stores are S3-compatible, so code that talks to object storage should go through the existing OBJECT_STORAGE_* / SESSION_RECORDING_V2_S3_* config and a standard S3 client rather than hardcoding an endpoint — that keeps backends swappable as MinIO is retired. When a new local-dev feature needs an S3-compatible store, point it at SeaweedFS.
• Temporal activity payloads have a ~2 MiB hard limit — pass large data by reference, not by value. Activity inputs and outputs are serialized across a gRPC boundary that Temporal caps at ~2 MiB per payload (the server rejects larger payloads via blobSizeLimitError). As a conservative field-level rule, if a field could exceed ~256 KB once serialized (serialized query results, exported file contents, LLM context, rendered HTML, image bytes, unbounded list[dict[str, Any]]), write it to Postgres / S3 / object storage from inside the activity and return only the reference (row ID, S3 key). The workflow already has access to any row ID created earlier in the same run; it does not need the content to flow back through. Shuttling large data through the workflow on the way to persistence is a foreseeable failure mode that produces PayloadSizeError (TMPRL1103) the moment the underlying data crosses the limit.

Code Style

• Python: Write as if mypy --strict is enabled — annotate all function signatures (arguments + return types), avoid Any, use TYPE_CHECKING imports for type-only references. Do not run mypy locally (too slow); CI runs it on every PR. The config isn't fully strict yet, but new code should be
• Python imports: keep imports at module level — not inside functions, methods, or conditionals. Inline imports hide dependencies from static analysis, slow hot paths with repeated lookups, and mask circular-import problems instead of fixing them; ruff's PLC0415 enforces this. Defer an import only to (1) break a true unavoidable circular import (fix the structure first if you can), (2) reference types under TYPE_CHECKING, or (3) keep a heavy/optional dependency off the import path so it loads only when its code runs. For (3), add a justified # noqa: PLC0415 on the import line (e.g. # noqa: PLC0415 — keeps the heavy dep off the import path) — never blanket-suppress the rule
• Frontend: for any frontend work — the main app (frontend/src/) or a product frontend (products/*/frontend/) — follow frontend/src/AGENTS.md: reuse existing Lemon/quill components instead of hand-rolling tables/badges/labels, import generated *Api types instead of handwriting them, and run typecheck/typegen at the right moments. Product frontends share the same components and generated types, so the same rules apply there
• Frontend: TypeScript required, explicit return types
• Frontend: If there is a kea logic file, write all business logic there, avoid React hooks at all costs.
• Frontend (quill design system): before writing UI that imports @posthog/quill / lib/ui/quill, read packages/quill/packages/primitives/AGENTS.md — component choice (dropdown vs select vs combobox, accordion vs collapsible, etc.), composition, and spacing rules. Charts: packages/quill/packages/charts/AGENTS.md; DataTable/DateTimePicker: packages/quill/packages/components/AGENTS.md
• Frontend (quill vs LemonUI): LemonUI is the default in the main app. Use quill for menus, comboboxes, and autocompletes (DropdownMenu, Combobox, Autocomplete from @posthog/quill), with the trigger styled to match the surrounding scene's existing UI (LemonButton / ButtonPrimitive). Don't add new LemonMenu or lib/ui/DropdownMenu (Radix) menus — those are legacy. Don't mix quill and Lemon components within one component's internals. Quill uses Base UI's render prop, not Radix's asChild — don't carry asChild over when converting
• Frontend: Any button or form submit that triggers a network request must guard against double-submission — disable the button and show a loading state (loading / disabledReason on LemonButton, or equivalent) while the request is in flight. Never leave a submit button clickable during an active mutation; reset the state in both success and error paths. This applies to <form onSubmit> handlers, onClick handlers that call api.*, and any kea listener that issues a request — wire the in-flight state (loader *Loading selectors, local useState, or a reducer) into the trigger's disabled/loading props.
• Imports: Use oxfmt import sorting (automatically runs on format), avoid direct dayjs imports (use lib/dayjs)
• CSS: Use tailwind utility classes instead of inline styles
• Error handling: Prefer explicit error handling with typed errors
• Naming: Use descriptive names, camelCase for JS/TS, snake_case for Python
• Comments: default to short or 1-line comments. Explain why, not what, and only when a future reader (with no access to this PR or chat) would otherwise be confused
• Comments: never log change history or chat context in code — no "previously did X, now does Y", "per <task/PR>", "changed because…", or "AI:"/"agent:" notes. That goes in the commit message and PR description
• Comments: when refactoring or moving code, preserve existing comments unless they are explicitly made obsolete by the change
• Python tests: do not add doc comments
• Python: do not create empty __init__.py files
• jest tests: when writing jest tests, prefer a single top-level describe block in a file
• Tests: prefer parameterized tests (use the parameterized library in Python) — if you're writing multiple assertions for variations of the same logic, it should be parameterized
• Tests must earn their place: every new test has to catch a realistic regression no existing test already catches (if you can't name it, don't add it), assert observable behavior through the public interface rather than implementation details, and stay cheap — deterministic, isolated, and at the lowest level that catches the bug (see /writing-tests)
• Reduce nesting: Use early returns, guard clauses, and helper methods to avoid deeply nested code
• Markdown: prefer semantic line breaks; no hard wrapping
• Use American English spelling
• When mentioning PostHog products, the product names should use Sentence casing, not Title Casing. For example, 'Product analytics', not 'Product Analytics'. Any other buttons, tab text, tooltips, etc should also all use Sentence casing. For example, 'Save as view' instead of 'Save As View'.

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 lint-staged warning; changes to .claude/settings.json are blocked outright.

Mandatory skill invocation

ALWAYS invoke the matching skill before writing or reviewing code in these areas — do not skip, do not attempt the work without loading the skill first.

Always invoke:

• /improving-drf-endpoints — any DRF viewset or serializer change
• /django-migrations — any Django migration
• /clickhouse-migrations — any ClickHouse migration
• /adopting-generated-api-types — any frontend file using lib/api, api.get<, api.create<, or handwritten API types
• /writing-tests — adding or substantially changing any test (pytest, Jest, or Playwright)

Invoke when in the area:

• /implementing-mcp-tools — adding/modifying endpoints or tools.yaml
• /modifying-taxonomic-filter — any TaxonomicFilter change
• /sending-notifications — adding notification support
• /writing-skills — creating or updating skills in .agents/skills/
• /gating-production-deploys — any workflow that builds and pushes a production image or dispatches a deploy

Awesome Agent Conventions

A curated field guide to the convention files AI agents read, write, and act on.

22 conventions across 11 categories. From common project instruction files to newer agent-web discovery and trust formats.

Agent tools increasingly rely on plain files in a repository or website root: instructions, memory, rules, tool connections, prompt assets, discovery metadata, and protocol hints. The names are easy to mix up, and the adoption levels vary a lot.

This repo keeps the map practical:

• Know what a file is for. Each entry names the convention, usual filename, primary readers, and spec or source.
• Study real examples. Examples are fetched from public repositories by script, with provenance kept at the top of each file.
• Separate practice from proposal. Maturity labels show what is widely used, what is early, and what is still only proposed.

Contents

• Instruction & context · category page
  • 🟢 AGENTS.md
  • 🟢 CLAUDE.md
  • 🟢 Tool-specific instruction files
  • 🟠 OKF (Open Knowledge Format)
• Memory & state · category page
  • 🟢 MEMORY.md
  • 🟢 Memory Bank
• Spec-driven development · category page
  • 🟢 Spec Kit
  • 🟢 Kiro steering files
• Skills & prompt assets · category page
  • 🟢 SKILL.md
  • 🟢 Prompt asset files
  • 🟢 Claude Code commands
  • 🟢 Copilot prompt & instruction files
• Tooling & connections · category page
  • 🟢 MCP server config
• Rules & ignore files · category page
  • 🟢 Rules files
  • 🟢 AI ignore files
• Design · category page
  • 🟢 DESIGN.md
• Web & discoverability · category page
  • 🟢 llms.txt
  • 🟢 pricing.md
• Agent-web trust · category page
  • 🟠 auth.md
  • 🔵 ai.txt
• Identity & protocols · category page
  • 🟠 Agent Cards (A2A)
• Proposed namespace · category page
  • 🔵 The protocols.md namespace

What counts

This list is intentionally narrow. A file belongs here when it is a convention for agent behavior or agent-readable metadata: instructions, memory, skills, rules, tool config, prompt assets, or web-discovery hints.

Any file type can qualify - .md, .txt, .prompty, .json, dotfiles, or a directory pattern. Human-first project docs such as README.md, CONTRIBUTING.md, SECURITY.md, and CHANGELOG.md stay out unless the file has become an agent convention in its own right.

Maturity tiers

The badge is a claim about adoption, not quality. It keeps a proven convention from being presented the same way as a new idea.

Badge	Tier	Meaning
🟢	Adopted	Used in production by multiple tools, projects, or teams.
🟠	Emerging	Published by a real organization, but still early or limited in adoption.
🔵	Proposed	Publicly described, but without clear adoption beyond the proposal.

Instruction & context

Standalone page: categories/instruction-context.md

	Convention	Files	Read by	Spec
🟢	AGENTS.md	AGENTS.md	Most coding agents - OpenAI Codex, Cursor, Jules, Aider, Gemini CLI, Zed, and others	spec ↗
🟢	CLAUDE.md	CLAUDE.md	Claude Code, and tools that read the Claude memory convention	spec ↗
🟢	Tool-specific instruction files	GEMINI.md AGENT.md QWEN.md WARP.md CONVENTIONS.md copilot-instructions.md	Each file is read by its namesake tool - Gemini CLI, Amp, Qwen Code, Warp, Aider, GitHub Copilot - often alongside or as a bridge to AGENTS.md	spec ↗
🟠	OKF (Open Knowledge Format)	.md	Agents over MCP (okfy, openknowledge, superops okf CLIs); Google's knowledge-catalog ingests bundles	spec ↗

• AGENTS.md - A plain-Markdown "README for agents" - build/test commands, conventions, and gotchas an agent needs before touching the code. The most widely adopted cross-tool instruction file.
• CLAUDE.md - Anthropic's memory file for Claude Code - loaded automatically at session start to carry project commands, style rules, and standing instructions across turns.
• Tool-specific instruction files - Per-tool instruction files that predate or coexist with AGENTS.md. Some tools now default to AGENTS.md while keeping legacy filenames alive, so these variants still matter when auditing real repositories.
• OKF (Open Knowledge Format) - A machine-first organizational knowledge base: a version-controlled folder of typed Markdown files (one concept per file) that any agent reads as ground-truth context. Open-sourced by Google Cloud in 2026 as the content layer to MCP's transport.

Memory & state

Standalone page: categories/memory-state.md

	Convention	Files	Read by	Spec
🟢	MEMORY.md	MEMORY.md	Claude Code's auto-memory - the per-project MEMORY.md index it writes and re-reads each session	spec ↗
🟢	Memory Bank	projectbrief.md productContext.md activeContext.md systemPatterns.md techContext.md progress.md	Cline, Roo Code, and Cursor (via the Memory Bank custom-instructions pattern)	spec ↗

• MEMORY.md - A persistent, agent-maintained index of durable facts - written and re-read across sessions so an agent accumulates project memory instead of relearning each time.
• Memory Bank - Cline's structured memory system - a set of Markdown files an agent reads at the start of every task to reconstruct full project context after its session memory resets. The six files shown are Cline's set; tools like Roo Code use an overlapping but different variant.

Spec-driven development

Standalone page: categories/spec-driven-development.md

	Convention	Files	Read by	Spec
🟢	Spec Kit	constitution.md spec.md plan.md tasks.md	GitHub Spec Kit's slash-command agents (Copilot, Claude, Gemini, Cursor, and more)	spec ↗
🟢	Kiro steering files	product.md structure.md tech.md	AWS Kiro (steering files are largely Kiro-specific)	spec ↗

• Spec Kit - GitHub's spec-driven workflow - a constitution plus per-feature spec → plan → tasks files that drive an agent through structured, reviewable implementation.
• Kiro steering files - Kiro's always-on steering docs - product, structure, and tech files that give the agent persistent project context outside of any single spec.

Skills & prompt assets

Standalone page: categories/skills-prompt-assets.md

	Convention	Files	Read by	Spec
🟢	SKILL.md	SKILL.md	Claude Agent Skills, Claude Code, Amp, Agent Skills-compatible tools	spec ↗
🟢	Prompt asset files	.prompty .prompt system_prompt.txt	Prompty tooling, Azure AI / Semantic Kernel, and apps that load externalized prompts	spec ↗
🟢	Claude Code commands	.md	Claude Code - project .claude/commands/ and user ~/.claude/commands/	spec ↗
🟢	Copilot prompt & instruction files	.prompt.md .instructions.md	GitHub Copilot in VS Code / Copilot CLI	spec ↗

• SKILL.md - A self-contained, model-invoked capability file that tells an agent when to load a reusable procedure and how to execute it.
• Prompt asset files - Externalized prompt files - Prompty's YAML-front-mattered .prompty, plain .prompt templates, and system_prompt.txt - that pull the prompt out of source code so it can be versioned and edited on its own. Only .prompty has a formal spec (prompty.ai); .prompt and system_prompt.txt are ad-hoc externalized-prompt filenames.
• Claude Code commands - A Markdown file Claude Code exposes as a /slash-command - a reusable, version-controlled prompt workflow, with optional frontmatter (allowed-tools, model, argument-hint) and $ARGUMENTS and shell placeholders (@file references are a general Claude Code prompt feature, not command-specific). Now converging with Agent Skills, but still widely committed in its own right.
• Copilot prompt & instruction files - Modular, path-scoped Copilot context: *.instructions.md auto-attach to matching files via an applyTo glob, while *.prompt.md are reusable prompts you invoke by name - the granular cousins of a single .github/copilot-instructions.md.

Tooling & connections

Standalone page: categories/tooling-connections.md

	Convention	Files	Read by	Spec
🟢	MCP server config	.mcp.json	Claude Code, Cursor, VS Code / Copilot, and Claude Desktop - every MCP host reads the same mcpServers schema, though the filename and path differ per tool	spec ↗

• MCP server config - A JSON file that tells an agent which Model Context Protocol servers to launch and how (command, args, env) - making a project's tool and data integrations portable, shareable, and version-controlled across every MCP-capable client.

Rules & ignore files

Standalone page: categories/rules-ignore-files.md

	Convention	Files	Read by	Spec
🟢	Rules files	.cursorrules .mdc .clinerules .clinerules/ (pattern) .windsurfrules	Cursor (.cursorrules / .mdc), Cline (.clinerules/ and legacy .clinerules), Windsurf (.windsurfrules)	spec ↗
🟢	AI ignore files	.aiignore .cursorignore .codeiumignore .aiexclude	JetBrains Junie (.aiignore), Cursor (.cursorignore), Codeium/Windsurf (.codeiumignore)	spec ↗

• Rules files - Per-tool rule files that scope agent behavior - older single-file forms (.cursorrules, .clinerules, .windsurfrules) and newer directory-based, glob-scoped forms (.cursor/rules/.mdc, .clinerules/, .windsurf/rules/.md).
• AI ignore files - gitignore-syntax files that fence an AI agent out of paths - secrets, vendored code, generated output - so they're never sent to the model as context.

Design

Standalone page: categories/design.md

	Convention	Files	Read by	Spec
🟢	DESIGN.md	DESIGN.md	Google Stitch natively; and coding agents (e.g. Claude Code) when pointed at it as design context	spec ↗

• DESIGN.md - A structured, machine-readable design specification - tokens, components, and layout intent - that an agent reads to generate or keep UI consistent with an established system. Open-sourced by Google Labs in 2026 as a cross-tool draft spec.

Web & discoverability

Standalone page: categories/web-discoverability.md

	Convention	Files	Read by	Spec
🟢	llms.txt	llms.txt llms-full.txt (pattern)	Docs sites publish it for LLM tools and crawlers - though no major provider has confirmed reading it	spec ↗
🟢	pricing.md	pricing.md	Agents and LLM browsers fetching a clean, parse-able pricing page	spec ↗

• llms.txt - A proposed-turned-widely-published standard: a root-level Markdown file giving LLMs a curated, link-rich map of a site's docs. Published across hundreds of developer-docs sites - though whether the major LLM providers actually read it remains unproven.
• pricing.md - The Markdown twin of a pricing page - same URL with a .md suffix - so an agent gets structured plans and numbers instead of scraping marketing HTML. A concrete, shipping instance of the page.md pattern.

Agent-web trust

Standalone page: categories/agent-web-trust.md

	Convention	Files	Read by	Spec
🟠	auth.md	auth.md	Agents discovering how to authenticate to a service (early adopters)	spec ↗
🔵	ai.txt	ai.txt	AI training/data-mining crawlers that voluntarily honor AI usage preferences; crawler support is not yet reliable	spec ↗

• auth.md - A Markdown file that tells an agent how to authenticate with a service - discovery of auth endpoints and flows. Shipped by WorkOS as a real, working convention, but adoption beyond it is still early.
• ai.txt - A text file declaring machine-readable consent, licensing, or policy preferences for AI training and data-mining. Spawning popularized the deployed root-file pattern, and a 2026 Internet-Draft now proposes a well-known URI; adoption and crawler obedience are still thin, so it stays 🔵.

Identity & protocols

Standalone page: categories/identity-protocols.md

	Convention	Files	Read by	Spec
🟠	Agent Cards (A2A)	agent-card.json agent.json (pattern)	A2A-compatible agents discovering another agent's capabilities	spec ↗

• Agent Cards (A2A) - The Agent2Agent (A2A) capability card - a JSON document at a well-known path advertising an agent's skills, endpoints, and auth so other agents can discover and call it. Now a Linux Foundation project at v1.0; adoption is growing but early.

Proposed namespace

Standalone page: categories/proposed-namespace.md

	Convention	Files	Read by	Spec
🔵	The protocols.md namespace	proof.md	- (no demonstrated readers; aspirational)	spec ↗

• The protocols.md namespace - A single maintainer's pre-registered namespace of ~74 aspirational .md "protocols" (proof.md, signature.md, reputation.md, …) staked as Schelling points for a future agent web. Published concept, no demonstrated adoption - see the page for the audited, honest caveats.

Maintaining examples

Example files are fetched, not invented. The extractor pulls them from public sources, stores them under conventions/<slug>/examples/<source>/<filename>, and adds a line-1 provenance comment. The examples remain under their upstream owners' licenses and terms; see THIRD_PARTY_EXAMPLES.md before reusing them.

To refresh everything:

pip install -r scripts/requirements.txt
python scripts/extract.py          # fetch real files + rebuild each convention's README
python scripts/build_readme.py     # rebuild this README from scripts/targets.json

Re-running is idempotent. A missing target prints a miss and is skipped. Examples are representative samples: any file over 256 KB (for example, a multi-MB llms-full.txt) is truncated with a marker pointing back to the full source. scripts/targets.json remains the source of truth for conventions that have not been migrated yet; the skill-md pilot uses local convention metadata instead. Edit the relevant source and re-run both scripts.

Shortcut targets are available in the Makefile:

make verify          # schema + generated files + example provenance + links
make extract         # refetch public examples and rebuild generated docs
make license-report  # summarize upstream licenses for vendored examples

CI keeps the generated files and links honest. The verify workflow checks that generated docs match catalog metadata and migrated local metadata, and that every spec, example, and instance URL still resolves on each pull request and weekly. Run the same link check locally with python scripts/check_links.py.

Contributing

Read CONTRIBUTING.md. In short: an entry must pass the filter above and carry evidence for its maturity tier. Add sources to scripts/targets.json for non-migrated conventions, run the scripts, and open a PR. The skill-md pilot uses local convention metadata instead. Do not hand-write example files.

Before proposing adjacent standards, check WATCHLIST.md. Project direction lives in ROADMAP.md.

License

The curation, scripts, and original prose in this repository are MIT. Vendored example files remain under their upstream owners' licenses and terms; see THIRD_PARTY_EXAMPLES.md.