CNTRLPLANE-3726: Add Agentic SDLC context files

[sanchezl]

Summary

• Add ARCHITECTURE.md — design decisions, controllers, capabilities integration, pull secret architecture, tech debt
• Add CONTRIBUTING.md — dev workflow, build/test commands, PR guidelines, OWNERS structure
• Add AGENTS.md — AI agent instructions, repo layout, critical rules, key patterns
• Add CLAUDE.md symlink → AGENTS.md
• Update README.md — add Quick Start, fix stale content, add companion doc links

Test plan

• Verify all relative links resolve (ARCHITECTURE.md, CONTRIBUTING.md, AGENTS.md, docs/metrics.md)
• Verify CLAUDE.md symlink resolves to AGENTS.md
• Verify make targets listed in docs match actual Makefile
• Review ARCHITECTURE.md design decisions for accuracy

Summary by CodeRabbit

• Documentation
  • Expanded and reorganized onboarding materials with repository-specific guidance for controller-manager scope and development practices.
  • Added a comprehensive architecture overview covering what the controller manager manages (and excludes), controller organization, and testing approach.
  • Updated contribution guidelines with clearer build/verify, testing expectations, and pull request process.
  • Refreshed the README with a streamlined quick start, revised rebase checklist, consolidated OTE instructions, and updated related links; aligned CLAUDE guidance via a symbolic link to AGENTS.

[openshift-ci-robot]

@sanchezl: This pull request references CNTRLPLANE-3726 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:

Summary

• Add ARCHITECTURE.md — design decisions, controllers, capabilities integration, pull secret architecture, tech debt
• Add CONTRIBUTING.md — dev workflow, build/test commands, PR guidelines, OWNERS structure
• Add AGENTS.md — AI agent instructions, repo layout, critical rules, key patterns
• Add CLAUDE.md symlink → AGENTS.md
• Update README.md — add Quick Start, fix stale content, add companion doc links

Test plan

• Verify all relative links resolve (ARCHITECTURE.md, CONTRIBUTING.md, AGENTS.md, docs/metrics.md)
• Verify CLAUDE.md symlink resolves to AGENTS.md
• Verify make targets listed in docs match actual Makefile
• Review ARCHITECTURE.md design decisions for accuracy

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]

[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 benluddy 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]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Enterprise

Run ID: f155f845-fd49-4ece-8d50-3b1f8c0b7f79

📥 Commits

Reviewing files that changed from the base of the PR and between 3309d14 and 4abe330.

📒 Files selected for processing (1)

• ARCHITECTURE.md

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

• ARCHITECTURE.md

---

Walkthrough

Adds repository documentation for OCM architecture, contributor workflow, and agent instructions. CLAUDE.md now points to AGENTS.md. README.md is reorganized with updated onboarding, rebase, metrics, and repository-link sections.

Changes

Repository Documentation

Layer / File(s)	Summary
Agent and contributor guidance AGENTS.md, CONTRIBUTING.md, CLAUDE.md	Adds repository-specific agent instructions, contributor workflow guidance, and a CLAUDE.md link to AGENTS.md.
Architecture scope and controller layout ARCHITECTURE.md	Documents OCM scope, startup lifecycle, controller table, pull-secrets sub-controller behavior, and capabilities-based controller registration.
Ownership, dependencies, and design decisions ARCHITECTURE.md	Describes deployment ownership, dependencies, testing strategy, and recorded design decisions.
README onboarding updates README.md	Reworks the introduction, quick start, rebase checklist, metrics link, and related documentation links.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

🚥 Pre-merge checks | ✅ 15

✅ Passed checks (15 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: adding agentic SDLC context files and related docs.
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	PR is docs-only (AGENTS/ARCHITECTURE/CONTRIBUTING/README/CLAUDE); no Ginkgo test titles were added or modified.
Test Structure And Quality	✅ Passed	PR only adds/edits docs and a symlink; no Ginkgo test files or test code were changed, so the test-quality review is not applicable.
Microshift Test Compatibility	✅ Passed	No new Ginkgo e2e specs were added; changed test files are unit tests with no It/Describe/Context/When or MicroShift-unsafe API refs.
Single Node Openshift (Sno) Test Compatibility	✅ Passed	PASS: This PR only updates docs/symlink per the summary; no new Ginkgo e2e test code or SNO-sensitive test assumptions were added.
Topology-Aware Scheduling Compatibility	✅ Passed	Only ARCHITECTURE.md changed, and the patch is documentation-only; no manifests, operator code, or controllers were modified.
Ote Binary Stdout Contract	✅ Passed	This PR only changes docs/symlink files; no process-level OTE code was added or edited, so no new stdout contract violation exists.
Ipv6 And Disconnected Network Test Compatibility	✅ Passed	Repo scan found no ginkgo/gomega imports or Ginkgo DSL; only non-test Describe methods, so the IPv6/disconnected check is not applicable.
No-Weak-Crypto	✅ Passed	PASS: The PR only adds/updates docs and a symlink; the changed files contain no MD5/SHA1/DES/RC4/3DES/Blowfish/ECB usage or custom secret/token comparisons.
Container-Privileges	✅ Passed	PR only changes docs and a symlink; no container/K8s manifests or privilege settings were introduced.
No-Sensitive-Data-In-Logs	✅ Passed	Reviewed the modified files; this PR only updates docs/symlink and adds no logging code or sensitive-data log messages.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[openshift-ci]

@sanchezl: all tests passed!

Full PR test history. Your PR dashboard.

Details

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 kubernetes-sigs/prow repository. I understand the commands that are listed here.