Root conventions also apply: read ../AGENTS.md; where they disagree, the closest file wins for its directory and below. If your tool cannot read it, restart it from the repository root.

AI Context Authoring

This directory is the source of the repository's AI context:

• manifest.yaml — the repository's identity for assembly (product and modules). Declaring a new module takes three steps together: add its path under modules:, add its CLAUDE.md negation to .gitignore (or the new shim silently never enters git), and run gbuddy setup, committing the generated files. Every directory where product code is written is declared; deliberately not modules: dependency-management poms (gravitee-apim-bom, gravitee-apim-parent), the gravitee-gamma reactor root (its children are declared), gamma-ui-shared (no build file), and repository tooling (.circleci, release).
• rules/ — repo-specific always-on rules, assembled into the generated AGENTS.md files together with the shared organisation-wide layers. A rule with dirs: in its frontmatter lands in those directories' files instead of root.
• guides/ — depth loaded on demand; rules point at guides with one-line breadcrumbs.
• generated.yaml — the record of generated files; AGENTS.md, CLAUDE.md, and .github/instructions/** are generated from the sources above. Never edit generated files by hand — edit a rule, run gbuddy setup, and commit the result; gbuddy check verifies no generated file was hand-edited since the last regeneration. If generated.yaml conflicts on a rebase or merge, do not resolve it by hand: once the source rules are resolved, delete .ai/generated.yaml, run gbuddy setup, add the regenerated files, and continue the rebase or merge. gbuddy is a Gravitee-internal tool: if you cannot run it, edit only the source rule under .ai/rules/, say so in your PR, and leave the generated files untouched for a maintainer to regenerate.

What earns a rule

• Only add rules that earn their token cost — not things easily inferred from context (scripts in package.json, standard framework behaviour, language syntax).
• The best rules come from observed agent mistakes; if an agent hasn't failed at it here, it probably doesn't need writing down.
• Place content at the right level, and ask of every always-on line: would a competent agent do this anyway (cut it); does it apply to every task or only some (move it beside the moment it applies — a guide or a dirs:-scoped rule); is it a constraint or a procedure (procedures load on demand); can an agent check it while writing, or only believe it (reframe until it is binary or checkable)?