From ff17ebe49a76a86b4ab2cac2f65f611c569bf2a5 Mon Sep 17 00:00:00 2001
From: Tyler Smalley <tyler.smalley@elastic.co>
Date: Fri, 30 Jan 2026 12:28:49 -0800
Subject: [PATCH] Adds initial agents.md file (#250833)

A group effort between @lukeelmers, @clintandrewhall and myself. We're
intentionally starting small and should really only add things as we
notice unintended behavior or the LLM wasting time to figure something
out. We should intentionally keep this small, and use things like skills
for more detailed information.

Assigning Tech Leads as codeowners to ensure we're intentional about the
content here.

Signed-off-by: Tyler Smalley <tyler.smalley@elastic.co>
Co-authored-by: Luke Elmers <luke.elmers@elastic.co>
Co-authored-by: Clint Andrew Hall <clint.hall@elastic.co>
(cherry picked from commit 64e53989d21cd553a1c5592d597d085b6ab0cbca)
---
 .github/CODEOWNERS |  3 ++
 AGENTS.md          | 77 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 80 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
index cd27cdb797205..b3322db927180 100644
--- a/.github/CODEOWNERS
+++ b/.github/CODEOWNERS
@@ -3063,6 +3063,9 @@ x-pack/plugins/observability_solution/synthetics/server/saved_objects/synthetics
 .moon         @elastic/kibana-operations
 /**/moon.yml  @elastic/kibana-operations
 
+# Leads approval
+/AGENTS.md @elastic/kibana-tech-leads
+
 ####
 ## These rules are always last so they take ultimate priority over everything else
 ####
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000000000..fa394c44d17e2
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,77 @@
+# Kibana
+
+## Setup
+- Run `yarn kbn bootstrap` for initial setup, after switching branches, or when encountering dependency errors
+
+## Overview
+- Kibana is organized into modules, each defined by a `kibana.jsonc`: core, packages, and plugin packages. Aside from tooling and testing, most code lives in these modules.
+- Packages are reusable units with explicit boundaries and a single public entry point (no subpath imports), usually with a focused purpose.
+- Plugins are a package type (`type: "plugin"`) that include a plugin class with setup/start/stop lifecycles, utilized by the core platform to enable applications.
+- Plugins that depend on other plugins rely on the contracts returned by those lifecycles, so circular dependencies must be avoided.
+- Module IDs (typically `@kbn/...`) live in `kibana.jsonc`; `package.json` names are derived where present.
+- Plugin IDs are additional camelCase IDs under `plugin.id` in `kibana.jsonc`, used by core platform and other plugins.
+- Modules are grouped by domain (platform vs solutions) with visibility rules (`shared` vs `private`) that limit cross-group access.
+- Utility scripts live in `scripts/` (e.g., `node scripts/generate.js`).
+
+## Critical Thinking
+- Fix root cause (not band-aid).
+- Unsure: read more code; if still stuck, ask w/ short options.
+- Conflicts: call out; pick safer path.
+- Unrecognized changes: assume other agent; keep going; focus your changes. If it causes issues, stop + ask user.
+
+## Testing
+
+### Jest unit
+`yarn test:jest [--config=<pathToConfigFile>] [TestPathPattern]`
+
+### Jest integration
+`yarn test:jest_integration [--config=<pathToConfigFile>] [TestPathPattern]`
+
+### Type check
+`yarn test:type_check [--project path/to/tsconfig.json]`
+
+### Function Test Runner (FTR)
+`yarn test:ftr [--config <file1> [--config <file2> ...]]`
+- For new tests, prefer using Scout
+
+### Scout (UI/API with Playwright)
+`node scripts/scout.js run-tests --stateful --config <scoutConfigPath>` (or `--testFiles <specPath1,specPath2>`)
+
+## Code Style Guidelines
+Follow existing patterns in the target area first; below are common defaults.
+
+### TypeScript & Types
+- Use TypeScript for all new code; avoid `any`.
+- Prefer explicit return types for public APIs and exported functions.
+- Use `import type` for type-only imports.
+- Avoid non-null assertions (`!`) unless locally justified.
+- Prefer `readonly` and `as const` for immutable structures.
+- Prefer const arrow functions
+- Prefer explicit import/exports over "*"
+- Prefer destructuring of variables, rather than property access
+
+### Formatting
+- Follow existing formatting in the file; do not reformat unrelated code.
+- `yarn llm` runs ESLint `--fix` on changed JS/TS files and may apply formatting-style fixes.
+- Prefer single quotes in TS/JS unless the file uses double quotes.
+
+### Naming
+- `PascalCase` for classes, types, and React components.
+- `camelCase` for functions, variables, and object keys.
+- New filenames must be `snake_case` (lowercase with underscores) unless an existing convention requires otherwise.
+- Use descriptive names; avoid single-letter names outside tight loops.
+
+### Control Flow & Error Handling
+- Prefer early returns and positive conditions.
+- Handle errors explicitly; return typed errors from APIs when possible.
+- Keep async logic linear; avoid nested `try` blocks when possible.
+
+### React / UI Conventions
+- Use functional components; type props explicitly.
+- Keep hooks at the top level; avoid conditional hooks.
+- Avoid inline styles unless consistent with the file’s conventions.
+- Use `@elastic/eui` components with Emotion (`@emotion/react`) for styling.
+
+## Contribution Hygiene
+- Make focused changes; avoid unrelated refactors.
+- Update docs when behavior or usage changes.