Agent guidance

Repository purpose

See README.md for why this repository exists, who or what uses it, and its responsibility boundary.

Versioning

When a change breaks backward compatibility, update version-next to the appropriate next major version as part of the same change. If version-next already targets that major release, keep it; multiple breaking changes in one unreleased version do not each require another major bump.

Develocity compatibility

Preserve compatibility between the Develocity Gradle plugin and the deployed Develocity server. The server observed during the 2.0.0 release was 2025.3.3, which supports plugin 4.2.x; use 4.2.2 until a server upgrade is verified. Before changing either Develocity dependency, verify the deployed server version against Gradle's compatibility matrix. Keep the versions in settings.gradle.kts and plugins/elastic-conventions/build.gradle.kts aligned, and preserve the matching allowedVersions constraint in renovate.json.

Build scans are required. Verify a successfully published build scan URL from a build using the changed conventions plugin before releasing. A successful Gradle exit code or green CI build is insufficient: incompatible Develocity versions can reject build scan uploads without failing the build. Do not release while scan publication is failing.

Secret scanning

Never place credentials, tokens, private keys, cookies, or production secret values in tracked files, examples, tests, prompts, logs, or generated output. Use the approved Vault-backed secret store and runtime injection mechanism instead.

Secret scanning controls are layered:

• Pre-commit hook — elastic/gitleaks-hooks at v1.0.0 runs Gitleaks via ./bin/gitleaks (Hermit-managed, v8.30.1). Install once with pre-commit install. The hook scans staged content before each commit.
• GitHub secret scanning — enabled, with push protection and non-provider patterns (private keys, connection strings, authorization headers). Push protection blocks a matching secret at git push.
• Buildkite CI — elastic/hermit#v1.0.2 + elastic/pre-commit#v1.0.3 plugins run the normal pre-commit hook set (including gitleaks) on every PR via the gradle-plugins-ci pipeline.

Setting up the hook

Both humans and coding agents are expected to use this tooling; it is the first layer that stops a secret before it becomes a commit.

pre-commit and Gitleaks are both pinned via Hermit, so no global install is needed. From a fresh clone:

./bin/pre-commit install    # once per clone, installs the git hook

Thereafter the hook runs automatically on git commit. To run it on demand:

./bin/pre-commit run gitleaks              # scan staged content
./bin/pre-commit run gitleaks --all-files  # scan the whole tree

./bin/pre-commit and ./bin/gitleaks are Hermit launchers and work without activating Hermit. If you activate the environment (. bin/activate-hermit), plain pre-commit and gitleaks resolve to the same pinned versions. Python 3.9 or newer must be available: pre-commit uses it to build the hook's isolated environment, though it does not provision Gitleaks itself.

If Gitleaks detects a secret, treat the finding as exposed, stop immediately, and rotate or revoke the credential before pushing. Never bypass the hook with --no-verify, SKIP=gitleaks, an allowlist entry, or a GitHub push-protection bypass reason unless the repository owner explicitly authorizes that exact override after reviewing the finding. A request to complete, commit, push, or open a pull request does not constitute override authorization.

AI attribution

For every AI tool that materially contributes to code, tests, documentation, configuration, or the substance of a change:

• Resolve the tool's runtime identity and add one unformatted trailer to the commit message. Use the exact model or agent slug and reasoning effort whenever exposed; omit unavailable components rather than guessing:

  Assisted-by: <tool name> (<most specific verified runtime identity>)

• Repeat the same trailer in the pull-request description.
• Preserve the spelling and specificity of exposed runtime values; do not shorten a specific model slug to a broader model family.
• Preserve valid tool-native attribution, such as Made with [Cursor](https://cursor.com) or a genuine Co-authored-by trailer, in addition to Assisted-by.
• Never invent a bot identity, model name, or email address.
• Keep trailers on their own lines without bullets, Markdown emphasis, or surrounding underscores.
• Keep the human author or committer accountable for understanding and verifying the change.

For a squash merge, verify that the final squash commit message contains every attribution trailer. GitHub may populate that message from the pull-request description, commit information, or only the pull-request title depending on repository settings, so putting attribution in the PR description improves preservation but does not guarantee it.

When preparing a commit or pull request, offer to create it with the correct attribution. If the user will create it manually, show the exact trailers to copy into both places.