chore(agent-readiness): bootstrap basic AGENTS.md and minor repo updates for agents

[johnmcollier]

Description

Ran the agent-ready (https://github.com/redhat-developer/rhdh-skill/blob/main/skills/agent-ready/SKILL.md) skill against the repository, to address some gaps called out by the https://github.com/ambient-code/agentready CLI (to assess an individual repository's readiness to be consumed by agents).

• Adds an AGENTS.md / CLAUDE.md with basic one-line build and test commands, and a link to some repo docs that could be found
  • To the maintainers: I recommend populating the Key conventions and Architecture sections for stuff that isn't immediately obvious to an agent
    • Do not auto generate this information, as it can actively harm agent effectiveness
• A couple minor updates to the repo and some claude rules to improve agent consumption

Which issue(s) does this PR fix or relate to

N/A, but see https://docs.google.com/spreadsheets/d/1Gk3nDQFJ2PBaaPiMZ3naJqAWf-nmL14OwK-Y83k7cuc/edit for more information

PR acceptance criteria

• Tests
• Documentation

How to test changes / Special notes to the reviewer

Building Container Images for Testing

Need to test container images from this PR?

For Maintainers: To trigger a test image build, review the code and comment /build-images.
This always builds the HEAD of the PR branch.

For Contributors: Ask a maintainer to run /build-images.

Images will be built and pushed to Quay with links posted in comments.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 61.51%. Comparing base (1fb800b) to head (4c53132).
⚠️ Report is 30 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3094      +/-   ##
==========================================
+ Coverage   61.41%   61.51%   +0.09%     
==========================================
  Files          37       37              
  Lines        2159     2162       +3     
==========================================
+ Hits         1326     1330       +4     
  Misses        691      691              
+ Partials      142      141       -1     

Flag	Coverage Δ
nightly	?
unittests	61.51% <ø> (+0.09%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 2 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[rhdh-qodo-merge]

Code Review by Qodo

Sorry, something went wrong

We weren't able to complete the code review on our side. Please try again

[rhdh-qodo-merge]

PR Summary by Qodo

Bootstrap AGENTS.md and Claude rules for agent-ready repo workflows
📝 Documentation ⚙️ Configuration changes 🕐 20-40 Minutes

Description

• Add AGENTS.md/CLAUDE.md with canonical build, test, lint, and generation commands.
• Introduce Claude path-scoped rules for API, controller, and integration test changes.
• Tighten automation defaults by running go vet as part of make lint.

Diagram

graph TD
  A["Agent/Contributor"] --> B["AGENTS.md"] --> C["Makefile (targets)"] --> D["Go codebase"]
  A --> E[".claude rules"] --> D
  E --> F[".claude/settings.json"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Fold agent guidance into existing contributor docs (README/CONTRIBUTING)

• ➕ Avoids adding a new top-level doc that can drift from existing guidance
• ➕ Keeps developer workflow documentation in one canonical place
• ➖ Some agent tooling explicitly looks for AGENTS.md/CLAUDE.md conventions
• ➖ Harder for agents to quickly locate minimal, actionable commands

2. Use fewer, broader Claude rules (single rules.md)

• ➕ Less surface area to maintain
• ➕ Reduces risk of inconsistencies between rule files
• ➖ Loses the benefit of path-scoped, domain-specific guidance (API vs controller vs tests)
• ➖ Harder to keep rules concise without becoming generic

Recommendation: Current approach is the better fit for agent-readiness tooling: keep AGENTS.md/CLAUDE.md as the fast entrypoint, and use path-scoped rules so agents get targeted guidance where mistakes are costly (API/controller/test areas). If duplication becomes a concern, link out from AGENTS.md to longer-form contributor docs rather than moving the quick-start commands elsewhere.

Files changed (7) +92 / -1

Documentation (2) +40 / -0

AGENTS.mdAdd AGENTS.md with build/test/lint commands and maintainer TODOs +39/-0

Add AGENTS.md with build/test/lint commands and maintainer TODOs

• Provides a single entrypoint for agents with one-line make commands, pointers to examples/docs, and TODO placeholders for maintainers to document non-obvious conventions and architecture.

AGENTS.md

CLAUDE.mdAdd CLAUDE.md pointing to AGENTS.md +1/-0

Add CLAUDE.md pointing to AGENTS.md

• Creates a minimal CLAUDE.md that references AGENTS.md as the canonical agent instructions.

CLAUDE.md

Other (5) +52 / -1

api.mdAdd path-scoped Claude rules for API type changes +12/-0

Add path-scoped Claude rules for API type changes

• Introduces agent guidance for changes under api/**/*.go, including versioning conventions, required godoc, and regeneration steps for CRDs/deepcopy code.

.claude/rules/api.md

controller.mdAdd path-scoped Claude rules for controller changes +12/-0

Add path-scoped Claude rules for controller changes

• Adds conventions for reconcile implementation and resource idempotency under internal/controller/**/*.go, plus recommended make targets to run after changes.

.claude/rules/controller.md

integration-tests.mdAdd path-scoped Claude rules for integration/E2E tests +12/-0

Add path-scoped Claude rules for integration/E2E tests

• Documents how to run integration tests against an existing cluster, how PROFILE affects suites, and provides a focused test invocation example.

.claude/rules/integration-tests.md

settings.jsonConfigure Claude post-edit hook to gofmt Go files +15/-0

Configure Claude post-edit hook to gofmt Go files

• Adds a PostToolUse hook that runs gofmt on edited/written *.go files, best-effort (errors ignored) to keep formatting consistent.

.claude/settings.json

MakefileRun go vet as part of 'make lint' +1/-1

Run go vet as part of 'make lint'

• Updates the lint target to depend on the vet target so 'make lint' covers golangci-lint plus go vet.

Makefile

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[johnmcollier]

@gazarenkov Thanks for the review! I've addressed your review comments