Document annotation namespace conventions in AGENTS.md #91

What happened

PR #24 introduced five annotations under the rhdh.io/ namespace (rhdh.io/overlay-workspace, rhdh.io/source-repository, rhdh.io/source-revision, rhdh.io/extensions-plugin-refs, rhdh.io/extensions-package-refs). The review agent flagged that rhdh.io/ has no precedent in the codebase — existing annotations use extensions.backstage.io/ and github.com/ — and raised a collision risk with RHDH product annotations. The finding was classified as medium-severity naming-convention. The PR was merged without addressing or documenting the namespace choice.

What could go better

The annotation namespace is a deliberate design decision, but it is undocumented. Without a documented convention, the review agent will flag every future use of rhdh.io/ as a novel namespace with collision risk, generating repeated medium-severity findings that reviewers must manually dismiss. Conversely, if the namespace is wrong, there is no documented alternative for future contributors to follow. Documenting the convention eliminates both failure modes. Confidence: high — this is a straightforward documentation gap with clear benefits for both human and agent reviewers.

Proposed change

Add an 'Annotation Conventions' section to AGENTS.md (under 'Working with Workspaces' or as a new top-level section) that documents:

1. The rhdh.io/ namespace is the project's annotation domain for overlay-workspace metadata annotations.
2. The extensions.backstage.io/ namespace is used for upstream Backstage extension annotations.
3. The github.com/ namespace is used for GitHub-specific annotations (project slug, team).
4. New annotations should use rhdh.io/ for RHDH-specific concepts and include a brief description when introduced.

Example addition:

## Annotation Conventions

Generated catalog-info files use annotations from three namespaces:
- `rhdh.io/` — RHDH-specific overlay metadata (workspace name, source repo, source revision, plugin/package refs)
- `extensions.backstage.io/` — Upstream Backstage extension annotations
- `github.com/` — GitHub-specific annotations (project slug)

New annotations for overlay workspace metadata should use the `rhdh.io/` namespace.

Validation criteria

After the documentation is added: (1) the review agent should not flag future PRs that add rhdh.io/ annotations with a naming-convention finding about namespace precedent, because the convention is now documented in AGENTS.md; (2) contributors adding new annotations have a clear reference for which namespace to use. Verify on the next PR that introduces or modifies rhdh.io/ annotations.

Generated by retro agent from #24