CNTRLPLANE-3734: Add docs for Agentic SDLC, architecture and contributing

[tchap]

Add AGENTS.md, ARCHITECTURE.md, CLAUDE.md, and CONTRIBUTING.md with verified codebase documentation. Move OTE test instructions from README.md into CONTRIBUTING.md to avoid duplication.

Created as a draft to prevent unnecessary CI runs until accepted.

Summary by CodeRabbit

• Documentation
  • Added new project docs describing the operator’s purpose, architecture, end-to-end configuration flow, startup/reconciliation behavior, and key conventions.
  • Introduced centralized contribution guidance, including testing expectations (unit/integration/E2E) and OpenShift Tests Extension (OTE) commands.
  • Updated the main README contributing section to point to the new centralized guidance.
  • Updated CLAUDE documentation to reference the new agent/project documentation.

[openshift-ci-robot]

@tchap: This pull request references CNTRLPLANE-3734 which is a valid jira issue.

Warning: The referenced jira issue has an invalid target version for the target branch this PR targets: expected the story to target the "5.0.0" version, but no target version was set.

Details

In response to this:

Add AGENTS.md, ARCHITECTURE.md, CLAUDE.md, and CONTRIBUTING.md with verified codebase documentation. Move OTE test instructions from README.md into CONTRIBUTING.md to avoid duplication.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository.

[openshift-ci]

Skipping CI for Draft Pull Request.
If you want CI signal for your change, please convert it to an actual PR.
You can still manually trigger a test run with /test all

[openshift-ci]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign flavianmissi for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[coderabbitai]

Walkthrough

Adds new documentation for operator architecture, contributor workflow, and agent guidance, and updates the README contributing section to point to the new contributor guide.

Changes

Repository documentation

Layer / File(s)	Summary
Agent guidance AGENTS.md, CLAUDE.md	AGENTS.md adds operator guidance, and CLAUDE.md now references it.
Architecture overview ARCHITECTURE.md	ARCHITECTURE.md adds the operator architecture, startup flow, controller responsibilities, configuration handling, certificate rotation, recovery, and supporting components.
Contributor guide and README link CONTRIBUTING.md, README.md	CONTRIBUTING.md adds contribution, testing, PR, review, and OTE sections, and README.md links to the new contributor guide.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

🚥 Pre-merge checks | ✅ 14 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Ipv6 And Disconnected Network Test Compatibility	⚠️ Warning	FAIL: test/e2e-preferred-host/kcm_preferred_host_kas.go builds scheme://%s:1234 with fmt.Sprintf, so IPv6 hosts won't be bracketed.	Use net.JoinHostPort (or url.URL{Host: ...}) for the master URL, and verify it in the IPv6 e2e job or gate it to IPv4 clusters.

✅ Passed checks (14 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Stable And Deterministic Test Names	✅ Passed	No Ginkgo tests are present; searches of all *_test.go files found no It/Describe/Context/When calls or ginkgo imports.
Test Structure And Quality	✅ Passed	No Ginkgo test code changed; the only test file uses standard Go testing, so the Ginkgo-specific checklist doesn’t apply.
Microshift Test Compatibility	✅ Passed	Diff vs main only touches docs/README; no new Ginkgo e2e tests were added, so MicroShift compatibility is not implicated.
Single Node Openshift (Sno) Test Compatibility	✅ Passed	PR is docs-only per summary; no new Ginkgo e2e tests or SNO-sensitive test logic were introduced.
Topology-Aware Scheduling Compatibility	✅ Passed	Only documentation/README changes were added; no deployment manifests, operator code, or controllers introducing scheduling constraints were modified.
Ote Binary Stdout Contract	✅ Passed	PR only changes markdown docs (AGENTS/ARCHITECTURE/CLAUDE/CONTRIBUTING/README); no process-level code or stdout writes were added.
No-Weak-Crypto	✅ Passed	The PR only changes docs/README wording; no MD5/SHA1/DES/RC4/3DES/Blowfish/ECB, custom crypto, or secret/token comparison logic appears in touched files.
Container-Privileges	✅ Passed	PR changes are documentation-only; no modified manifest files contain privileged/root settings or allowPrivilegeEscalation.
No-Sensitive-Data-In-Logs	✅ Passed	Docs-only PR; I found no new log statements or sensitive data exposed in logs.
Title check	✅ Passed	The title accurately summarizes the main documentation additions and the contributing doc update.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

ARCHITECTURE.md (1)

1-155: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Rename this file to lowercase.

ARCHITECTURE.md violates the repo rule that all filenames must be lowercase. As per coding guidelines, All filenames should be lowercase.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@ARCHITECTURE.md` around lines 1 - 155, Rename the ARCHITECTURE.md document to
use a lowercase filename to match the repository naming rule. Update the
documentation file itself and any references that point to it so the lowercase
name is used consistently, ensuring the architecture content remains unchanged
while the identifier complies with the repo-wide lowercase filename convention.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@CONTRIBUTING.md`:
- Around line 69-71: The new documentation filenames violate the lowercase
filename rule in CONTRIBUTING.md, so update the docs naming to comply or
explicitly document an exception for instruction files. Make the fix in the
places that introduce AGENTS.md, CLAUDE.md, and CONTRIBUTING.md, and ensure the
guidance in the repository’s docs policy clearly states whether standard
instruction docs are exempt from the lowercase requirement.

---

Outside diff comments:
In `@ARCHITECTURE.md`:
- Around line 1-155: Rename the ARCHITECTURE.md document to use a lowercase
filename to match the repository naming rule. Update the documentation file
itself and any references that point to it so the lowercase name is used
consistently, ensuring the architecture content remains unchanged while the
identifier complies with the repo-wide lowercase filename convention.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository: openshift/coderabbit/.coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: ddf468f3-cc1e-4427-bb71-667c75d375c8

📥 Commits

Reviewing files that changed from the base of the PR and between c35307f and bd48be8.

📒 Files selected for processing (5)

• AGENTS.md
• ARCHITECTURE.md
• CLAUDE.md
• CONTRIBUTING.md
• README.md

[coderabbitai]

♻️ Duplicate comments (1)

CONTRIBUTING.md (1)

69-71: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Keep the docs filename policy consistent.

CONTRIBUTING.md still conflicts with the repo rule that all filenames should be lowercase. If standard instruction docs are meant to be exempt, state that explicitly here; otherwise rename them to match the policy.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@CONTRIBUTING.md` around lines 69 - 71, The filename policy in CONTRIBUTING.md
conflicts with the stated lowercase-only rule, so update the docs guidance to be
consistent. Either explicitly add an exception for standard documentation
filenames like CONTRIBUTING.md in the filename policy, or change the policy text
so it applies uniformly and no longer contradicts existing docs file names; use
the CONTRIBUTING.md section that lists filename conventions as the place to make
this clarification.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Duplicate comments:
In `@CONTRIBUTING.md`:
- Around line 69-71: The filename policy in CONTRIBUTING.md conflicts with the
stated lowercase-only rule, so update the docs guidance to be consistent. Either
explicitly add an exception for standard documentation filenames like
CONTRIBUTING.md in the filename policy, or change the policy text so it applies
uniformly and no longer contradicts existing docs file names; use the
CONTRIBUTING.md section that lists filename conventions as the place to make
this clarification.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository: openshift/coderabbit/.coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 2f3b604c-442e-40f2-a452-a87f21a5c8ff

📥 Commits

Reviewing files that changed from the base of the PR and between bd48be8 and cc89d7a.

📒 Files selected for processing (5)

• AGENTS.md
• ARCHITECTURE.md
• CLAUDE.md
• CONTRIBUTING.md
• README.md

✅ Files skipped from review due to trivial changes (3)

• CLAUDE.md
• AGENTS.md
• ARCHITECTURE.md

🚧 Files skipped from review as they are similar to previous changes (1)

• README.md

[tchap]

/retitle CNTRLPLANE-3734: Add docs for Agentic SDLC, architecture and contributing

[coderabbitai]

Caution

Failed to replace (edit) comment. This is likely due to insufficient permissions or the comment being deleted.

Error details

putComment timed out