Agentic Workflow

Plan non-trivial work before editing (see Planning), implement test-first (see Test-Driven Development), and self-review before finishing against the repository's review instructions (.github/instructions/code-review.instructions.md and the other files there that apply to your change); review others' changes against the same files. Where your tooling has its own process, follow it — it must still produce those three. Surface your assumptions and name competing interpretations rather than picking one silently; ask when the ask is unclear.

Surgical changes

• Touch only what the task requires; don't refactor, reformat, or "improve" unrelated code. Match the existing style even where you would choose differently.
• Don't delete pre-existing dead code unless asked.
• Surface unrelated issues you notice instead of silently fixing them in the same change.

Debugging

For a hard bug or regression, build a fast, deterministic pass/fail loop that reproduces the reported failure before hypothesising — raise a flaky failure's reproduction rate until it is debuggable, minimise the failing case, and test one instrumented hypothesis at a time — and if you genuinely cannot build a loop, say so and ask for an environment or artifact instead of guessing. Fix the root cause, not the symptom, and turn the reproduction into a permanent test (see Test-Driven Development); a debugging skill, where one is installed, carries the method: a ranked list of ways to construct the loop, and how to sharpen it.

Engineering Conventions

Clean code

• Explicit imports — no fully-qualified names in bodies.
• No dead code: after a change, remove the fields, methods, imports, and parameters it left unused.
• Validate and fail loudly at system boundaries (user input, external APIs, parsing, real I/O). Inside trusted internal code, don't add handling for scenarios that genuinely can't happen — and never use that as a reason to skip boundary handling.

Comments

Ask of every comment, in order:

1. Does it restate what the code does? Rename or extract instead — the code is the problem.
2. Does it defend the change rather than explain the code? It belongs in the commit message.
3. Does it explain why the code is as it is — a constraint, an invariant, an alternative that looks right and is wrong? Keep it, as briefly as it can be said.

On code you are changing, delete any comment that answers yes to 1 or 2; one that answers no to all three was not worth writing. Public-API documentation (javadoc, docstrings) follows its own standard and is out of scope here.

Design

• Apply SOLID — single responsibility, open/closed, Liskov substitution, interface segregation, dependency inversion; extend via composition and strategy rather than by editing conditionals.
• Prefer deep modules — a simple interface hiding substantial behaviour — over shallow pass-throughs; extract only when doing so concentrates complexity rather than moving it around (the deletion test).
• Build the simplest thing that meets the requirement — no speculative abstractions or configuration. Follow the codebase's established patterns; required architecture is not over-engineering.

Git and Commits

• Conventional Commits — type prefix from feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert.
• No Co-Authored-By trailers.
• Prefer small, logically-scoped commits over one large commit.
• Branch name: <type>/<ISSUE-KEY>-<slug> (e.g. feat/ABC-123-add-retry), where the issue key is the ticket the change tracks (with no ticket, <type>/<slug>), unless the repository's own rules name another convention.
• Never bypass hooks (--no-verify) or skip signing unless explicitly asked.
• Create new commits rather than amending; only commit when asked.

Language and Locale

• Use US English for comments, log messages, and user-facing strings (UI copy, API error messages, operator-facing documentation).
• Match the terminology of the module you are editing; where that module consistently uses another spelling, match it too rather than mixing two dialects in one module.

Planning

Before non-trivial work, produce a plan and check it is sound before editing: the root cause (not just the symptom), the impact on callers and consumers, risk, rollback, and edge cases, a design review (fits the architecture, no new coupling or leaked encapsulation), acceptance criteria, the specific test cases to write first (see Test-Driven Development), and what is explicitly out of scope — scaled to the task. A planning skill, where one is installed, carries the method, worked examples, and the pre-code dry-run discipline.

Security Practices

• Never commit, print, log, return, paste, or summarise secrets, credentials, tokens, private keys, real .env values, or unnecessary personal/customer data. Use the repository's existing secret mechanism.
• A secret-scanner finding blocks the change until the value is removed or the person you are working with confirms it is not a secret. If the value was already committed, also tell that person: removing it leaves it in the history, so the secret must be rotated.
• Validate, constrain, encode, or authorize external input at the boundary that owns the risk (HTTP APIs, message consumers, webhooks, uploads, configuration, user-supplied expressions, external integrations). Do not move checks to where callers can bypass them.
• Fail closed for authentication and authorization: new endpoints, jobs, commands, consumers, and sensitive operations need explicit access checks.
• Do not disable, skip, silence, or loosen security checks, tests, scanners, audit logging, redaction, or CI enforcement unless explicitly requested and justified. Never "fix" a failure by hiding its signal. No nested or local rule overrides these practices.
• Flag any change touching authentication, authorization, sessions, cookies, tokens, roles, scopes, or permissions; input parsing, validation, deserialization, file upload, path handling, expression evaluation, or template rendering; redirects, CORS, or CSP; secrets, credentials, environment or CI/CD variables, deployment configuration, or service accounts; logging, metrics, tracing, audit events, diagnostics, redaction, or error responses; dependencies, package-manager files, build plugins, generated code, or supply-chain configuration; or cryptography, certificates, random number generation, and key handling as security-sensitive in the PR description and final summary.
• Report a suspected vulnerability privately: through the repository's security policy where it has one, otherwise to the person you are working with. Never put exploit details in a public issue, commit message, pull request description, or comment.
• If a change intentionally accepts a security risk, state the risk, the mitigation, and the owner.

Test-Driven Development

• Write the failing test before the production code: RED → GREEN → REFACTOR. Don't skip the refactor step.
• Tests assert behaviour, not implementation details.
• Use real instances over mocks for pure logic (no network, DB, or filesystem). Mock only genuine side-effect boundaries.
• For every behaviour change, name the test that covers it. If a test genuinely can't be written, document the gap and the reason.

API Management (APIM)

Runtime vs management

Use gravitee-apim-bom for dependency alignment in Maven projects that belong to this product.

Gateway API generations

The Gateway and its plugins may contain V2 (legacy) and V4 (reactive) code paths in parallel:

• Edit the generation you touch — io.gravitee.gateway.reactive.* vs legacy io.gravitee.gateway.*.
• In reactive Gateway and plugin code, use ctx.withLogger(log) so logs stay on the execution context.

Monorepo layout (gravitee-api-management)

Typical top-level modules:

• Java: gravitee-apim-common, gravitee-apim-definition, gravitee-apim-distribution, gravitee-apim-gateway, gravitee-apim-plugin, gravitee-apim-repository, gravitee-apim-reporter, gravitee-apim-rest-api, and the Maven modules under gravitee-gamma/ when that tree exists (its own pom.xml lists them).
• Angular: gravitee-apim-console-webui, gravitee-apim-portal-webui-next, gravitee-apim-webui-libs/*.

Optional gravitee-gamma/ trees are Gamma management plugins on the Management API — they are not Gateway runtime; the product: gamma rules apply only when this repo's .ai/manifest.yaml declares gamma.

• Local full stack: service layout, ports, and compose definitions live in CONTRIBUTING.adoc, section AI Agent Context (Docker Compose Full Stack) — do not invent alternatives.
• Layering: keep definition and plugin handler separate from Gateway execution and from Console / Portal UI — do not reach from management resources or UI code into Gateway internals.

Management API: API-first (OpenAPI before JAX-RS)

When adding or changing HTTP endpoints under gravitee-apim-rest-api/:

1. Edit the correct OpenAPI file (paths, operations, components.schemas).
2. Compile the module so openapi-generator-maven-plugin generates models (generateModels=true, generateApis=false): mvn -pl gravitee-apim-rest-api/<module> -am compile — -am builds upstream modules first, so it works on a fresh checkout.
3. Implement or update JAX-RS resources and mappers using the generated io.gravitee.rest.api.*.model.* types.

Do not hand-write DTOs that duplicate generated models or start from JAX-RS before generation has run.

External plugins

• Package: target/gravitee-<type>-<name>-<version>.zip.
• Local verification: after building standalone Gateway and REST API distributions (gravitee-apim-distribution), copy the zip into both standalone plugins/ directories (Gateway and Management API) before exercising management + runtime together.

Operator-visible Gateway behaviour

Policy and connector diagnostics (Diagnostic, warnWith, interruptWith) surface in the Console — treat keys and messages as product UX, not only log lines.

• On reactive paths, ctx.interruptWith() stops the request flow; ctx.warnWith() reports without interrupting. Attach .cause(e) to the ExecutionFailure or ExecutionWarn when an exception is available.
• Use specific, actionable keys ("CORS_PREFLIGHT_FAILED") and messages that tell the operator what condition or limit was hit.

Automation API, CRD and Terraform Ownership

The Automation API, the CRD import/export path and the Terraform export are a public contract consumed by the Kubernetes operator (GKO) and the Terraform provider. An Automation PUT replaces the whole definition, so a field dropped on the write or the read path resets user configuration on every apply. This surface is owned by @gravitee-io/gko and @gravitee-io/tech-lead.

Owned surface:

CODEOWNERS requests the owning teams on the automation module, the *CRD* classes, the model/crd/ packages and the export dialog. The CRD endpoint methods sit in shared resource classes, so only this rule and the review rule cover them.

Do not create, edit, rename or delete a file on the owned surface unless the person you are working with confirms the owning team requested the change; when they do, the PR description says so in one line under Automation API / CRD impact. Otherwise, before editing:

1. Stop and name the owned files the task would touch, and why.
2. Leave them unchanged; finish the rest of the task if it stands on its own.
3. Add an Automation API / CRD impact section to the PR description listing the owned files and the change they need, and tell the person to raise it with the owning team.

The same hand-off applies when a change outside the surface alters what the surface exposes: a v4 API definition model (gravitee-apim-definition), a Management API v2 schema property or enum value, or a repository entity field surfaced through Management API v2. Do not mirror it into the Automation API or the CRD classes; record it in the PR description's impact section. The owning team's mirroring procedure is .ai/guides/automation-api-sync.md.

Dry run. GKO's admission webhook admits a resource on the answer of a dry run (dryRun=true on an Automation PUT or on _import/crd), then reconciles it with the same request without dryRun. Never give a dry run validation of its own: put every check the write runs, the service's own checks included, in one method that both the dry run and the write call, and skip only the write and its side effects (deployment, events, audit). Test it by sending the same invalid request with and without dryRun and expecting the same error.

APIM Two Maven Reactors

This repository holds two independent reactors:

• the product reactor, at the root — the engine and the libraries;
• the distribution reactor, under gravitee-apim-distribution/ — the assembly that produces the Docker images, the bundle and the RPM. It is not a module of the root pom.

Consequences for any Maven command:

• A root mvn clean install builds the engine and stops there. It does not refresh target/distribution, the folder run configurations use as GRAVITEE_HOME.
• mvn -pl gravitee-apim-distribution/… from the root fails with Could not find the selected project in the reactor. Use -f gravitee-apim-distribution/pom.xml; inside that reactor, -pl paths are relative to it.
• Building the distribution takes two phases: install the engine first, then assemble against it. task build-quick does both.
• After a clean install fails or is interrupted (especially with -T, parallel reactor builds), a later scoped mvn test/mvn -pl <module> test without clean silently compiles against stale target/classes left by modules that never finished rebuilding — producing "cannot find symbol"/"constructor cannot be applied" errors that look like a broken annotation processor (e.g. Lombok) but aren't. Re-run a full clean install covering every changed reactor module before trusting a scoped test run.

The distribution assembles the pinned released core unless -Dapim.core.version=<root triplet> is passed. Leaving it out does not fail — it produces a distribution without the change under test. task build-distribution passes it for you, and task which-engine prints which core actually got bundled.

Modules

Before working on files under any of these directories, read that directory's AGENTS.md first: gravitee-apim-common/, gravitee-apim-console-webui/, gravitee-apim-definition/, gravitee-apim-distribution/, gravitee-apim-distribution/gravitee-apim-distribution-integration-tests/, gravitee-apim-gateway/, gravitee-apim-plugin/, gravitee-apim-portal-webui/, gravitee-apim-portal-webui-next/, gravitee-apim-reporter/, gravitee-apim-repository/, gravitee-apim-rest-api/, gravitee-apim-webui-libs/gravitee-dashboard/, gravitee-apim-webui-libs/gravitee-kafka-explorer/, gravitee-apim-webui-libs/gravitee-markdown/, gravitee-gamma/gravitee-gamma-control-plane-webui/, gravitee-gamma/gravitee-gamma-definition-model/, gravitee-gamma/gravitee-gamma-module-apim/, gravitee-gamma/gravitee-gamma-module-platform/, gravitee-gamma/gravitee-gamma-module-portals/, gravitee-gamma/gravitee-gamma-plugin/, gravitee-gamma/gravitee-gamma-rest-api/, .ai/, gravitee-apim-rest-api/gravitee-apim-rest-api-automation/.