From 0ae15aee639ea5f3cdad1977009894065c4deefa Mon Sep 17 00:00:00 2001
From: fullsend-code
 <278716306+fullsend-ai-coder[bot]@users.noreply.github.com>
Date: Fri, 7 Aug 2026 20:07:45 +0000
Subject: [PATCH] docs(#1797): add product and tool name casing conventions

Add a "Product and Tool Name Conventions" section to AGENTS.md
documenting the canonical casing for product names used in this
codebase. This gives both human contributors and the review agent
a single source of truth for domain-specific terminology.

Covers roxctl, cosign, Sigstore, Rekor, Fulcio, Tekton, SLSA,
Conforma, Clair, OPA, and Rego with correct casing, incorrect
examples, and authoritative references. Includes notes clarifying
that CLI command usage and Rego identifiers are exempt.

Motivated by PR #1795 where a human reviewer caught inconsistent
roxctl casing that automated review agents missed due to the
absence of documented conventions.

Closes #1797
---
 AGENTS.md | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 42fe47bd0..ced5fb970 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -73,6 +73,32 @@ Rego is a declarative policy language (Datalog-inspired), not imperative code:
 - Do NOT suggest imperative patterns that Rego does not provide: early returns, try/catch, or
   exception handling. These concepts do not exist in Rego.
 
+## Product and Tool Name Conventions
+
+Use the canonical casing for product and tool names in documentation, code comments, and policy
+annotations. Incorrect casing is a review finding.
+
+| Name | Correct | Incorrect examples | Reference |
+|------|---------|-------------------|-----------|
+| roxctl | `roxctl` | Roxctl, ROXCTL | [Red Hat ACS docs](https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_security_for_kubernetes/4.0/html-single/roxctl_cli/index) |
+| cosign | `cosign` | Cosign, COSIGN | [Sigstore project](https://docs.sigstore.dev/) |
+| Sigstore | `Sigstore` | sigstore, SIGSTORE | [Sigstore project](https://www.sigstore.dev/) |
+| Rekor | `Rekor` | rekor, REKOR | [Sigstore project](https://docs.sigstore.dev/logging/overview/) |
+| Fulcio | `Fulcio` | fulcio, FULCIO | [Sigstore project](https://docs.sigstore.dev/certificate_authority/overview/) |
+| Tekton | `Tekton` | tekton, TEKTON | [Tekton project](https://tekton.dev/) |
+| SLSA | `SLSA` | slsa, Slsa | [SLSA spec](https://slsa.dev/) |
+| Conforma | `Conforma` | conforma (when referring to the product) | Project convention |
+| Clair | `Clair` | clair, CLAIR | [Clair project](https://quay.github.io/clair/) |
+| OPA | `OPA` | opa (when referring to the product) | [Open Policy Agent](https://www.openpolicyagent.org/) |
+| Rego | `Rego` | rego (when referring to the language) | [OPA docs](https://www.openpolicyagent.org/docs/latest/policy-language/) |
+
+**Notes:**
+- CLI tool names used as commands (e.g., `opa check`, `cosign verify`) naturally appear in
+  lowercase — that is correct. The table above applies when referring to the tool or project
+  by name in prose.
+- Package paths, variable names, and Rego identifiers follow their own naming conventions and
+  are not subject to these rules (e.g., `data.lib.sigstore` is a valid package path).
+
 ## Common Change Patterns
 
 - **Add a release policy rule:** follow the pattern in `policy/release/attestation_type/attestation_type.rego` (rule + `_test.rego` in a subdirectory, declare `collections:` in METADATA)