CNTRLPLANE-3723: Add Agentic SDLC context files

[sanchezl]

Summary

• Add ARCHITECTURE.md — design decisions, controllers, cert management, platform/topology behavior
• 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 master branch refs, add companion doc links, trim from 204 to 90 lines

Test plan

• Verify all relative links resolve (ARCHITECTURE.md, CONTRIBUTING.md, AGENTS.md, defaultconfig.yaml)
• 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
  • Added repository-wide AI agent guidance with operator purpose, safe operational constraints, and pointers to unit/E2E/OTE test locations.
  • Added/expanded architecture documentation for static pod management, revision rollouts, certificate and service account token key rotation, and recovery/rendering flows.
  • Added complete contributing documentation covering prerequisites, build/test/verify commands, OTE suite execution, and PR review conventions.
  • Substantially rewrote README with a streamlined Quick Start, clearer configuration/debugging guidance, and updated custom-image workflow.
  • Updated CLAUDE.md to reference the shared agent guidance.

[openshift-ci-robot]

@sanchezl: This pull request references CNTRLPLANE-3723 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, cert management, platform/topology behavior
• 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 master branch refs, add companion doc links, trim from 204 to 90 lines

Test plan

• Verify all relative links resolve (ARCHITECTURE.md, CONTRIBUTING.md, AGENTS.md, defaultconfig.yaml)
• 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.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

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: 6da40ff6-58a4-4c3b-80f9-e80d5df2ed73

📥 Commits

Reviewing files that changed from the base of the PR and between 70bb8ea and 24f31d5.

📒 Files selected for processing (1)

• ARCHITECTURE.md

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

• ARCHITECTURE.md

---

Walkthrough

Repository guidance, architecture documentation, contribution instructions, and README content were added or reorganized. CLAUDE.md now links to AGENTS.md.

Changes

Repository documentation refresh

Layer / File(s)	Summary
Agent and contributor guidance AGENTS.md, CONTRIBUTING.md, CLAUDE.md	Adds repository instructions, contribution workflows, test guidance, and the CLAUDE.md symlink to AGENTS.md.
Architecture scope and controller model ARCHITECTURE.md	Documents operator scope, namespaces, controller responsibilities, run-level ordering, and static pod lifecycle flow.
Architecture resources and platform behavior ARCHITECTURE.md	Documents resource ownership, platform behavior, certificate and signing-key handling, recovery and render commands, testing, and design decisions.
README workflows and references README.md	Reorganizes the README around setup, configuration, debugging, custom images, tests, metrics, documentation, and related repositories.

Estimated code review effort: 1 (Trivial) | ~2 minutes

Suggested reviewers: ingvagabund, kaleemsiddiqu

---

Important

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
No-Sensitive-Data-In-Logs	❓ Inconclusive	Need repository evidence; PR appears docs-only, but I must verify changed files for any logging of sensitive data.	Inspect the actual diff and search changed files for logging or secrets references before deciding.

✅ Passed checks (14 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.
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	The PR only changes docs/symlink files; no test files or Ginkgo titles were modified, so this check is not applicable.
Test Structure And Quality	✅ Passed	No Ginkgo specs were changed; the repo test edits are a deleted table-driven unit test and an empty placeholder test, so this check is not applicable.
Microshift Test Compatibility	✅ Passed	The commit changes only ARCHITECTURE.md; no Ginkgo e2e tests were added or modified, so MicroShift compatibility is not implicated.
Single Node Openshift (Sno) Test Compatibility	✅ Passed	PR changes only docs and a symlink; no *_test.go files or new Ginkgo e2e tests were added, so SNO compatibility is not applicable.
Topology-Aware Scheduling Compatibility	✅ Passed	PASS: The merge-base diff touches only documentation files; no manifests, operator code, or controllers changed, so no new scheduling constraints.
Ote Binary Stdout Contract	✅ Passed	Changed pkg files add no main/TestMain/BeforeSuite stdout writes; the only new fmt.Printf is in vendored Ginkgo CLI build_command.go, not an OTE binary path.
Ipv6 And Disconnected Network Test Compatibility	✅ Passed	Only ARCHITECTURE.md changed; no new Ginkgo e2e tests or network code were added, so this compatibility check is not applicable.
No-Weak-Crypto	✅ Passed	Touched files are docs/symlink only; scans of AGENTS/ARCHITECTURE/CONTRIBUTING/README found no MD5/SHA1/DES/RC4/3DES/Blowfish/ECB or secret comparisons.
Container-Privileges	✅ Passed	PR only changes docs/symlink; no K8s manifests or securityContext/privilege fields were modified.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[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 gangwgr 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

[openshift-ci]

@sanchezl: The following test failed, say /retest to rerun all failed tests or /retest-required to rerun all mandatory failed tests:

Test name	Commit	Details	Required	Rerun command
ci/prow/e2e-aws-ovn	24f31d5	link	true	/test e2e-aws-ovn

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.