docs: establish ADR framework with template and agent guidelines

[akurinnoy]

What does this PR do?

Introduces Architecture Decision Records (ADRs) to the project: adds adr/ directory with a README, template, maintenance guide for AI agents, and the first ADR documenting the backup auth secret lifecycle decision. Updates root AGENTS.md and .claude/CLAUDE.md with criteria for when to create an ADR.

What issues does this PR fix or reference?

Is it tested? How?

PR Checklist

• E2E tests pass (when PR is ready, comment /test v8-devworkspace-operator-e2e, v8-che-happy-path to trigger)
  • v8-devworkspace-operator-e2e: DevWorkspace e2e test
  • v8-che-happy-path: Happy path for verification integration with Che

Summary by CodeRabbit

• Documentation

  • Established Architecture Decision Records (ADR) framework with standardized templates, naming conventions, and governance guidelines for documenting key architectural decisions.

• Bug Fixes

  • Backup registry authentication secrets now persist across workspace deletions, preventing data loss and eliminating cross-workspace interference.

[openshift-ci]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: akurinnoy
Once this PR has been reviewed and has the lgtm label, please assign dkwon17 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]

Warning

Rate limit exceeded

@akurinnoy has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 17 minutes and 28 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 8203a5d9-c829-44be-a79f-6f4ecb829116

📥 Commits

Reviewing files that changed from the base of the PR and between e6e2c2d and 9b8072d.

📒 Files selected for processing (1)

• AGENTS.md

📝 Walkthrough

Walkthrough

This PR establishes an Architecture Decision Records (ADRs) process for the project. It creates the ADR directory infrastructure with README, template, and agent maintenance guide; integrates ADR guidance into project documentation; and records the first ADR documenting backup registry auth secret lifecycle changes.

Changes

ADR Framework and First Decision

Layer / File(s)	Summary
ADR framework and template adr/README.md, adr/TEMPLATE.md, adr/AGENTS.md	Establishes the ADR directory with documentation explaining ADR purpose, write conditions, status lifecycle, and naming conventions; provides a template for new ADRs with sections for metadata, context, decision, alternatives, and consequences; and includes maintenance guidance for AI agents.
ADR guidance in project documentation .claude/CLAUDE.md, AGENTS.md	Updates AI guidance and project documentation to direct contributors to consult existing ADRs, consider trade-offs and alternative rejections, create ADRs when warranted, and reference the new adr/ directory in documentation links.
First ADR: Backup auth secret lifecycle adr/2026-05-11-backup-auth-secret-lifecycle.md	Records decision to remove ownerReference from the shared namespace singleton backup registry auth secret, converting it to a namespace-scoped resource with no workspace ownership, preventing unintended garbage collection and cross-workspace interference.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• devfile/devworkspace-operator#1618: Refactors backup cronjob tests and CopySecret semantics around registry auth secret copying, directly implementing the behavior documented in this PR's backup auth secret lifecycle ADR.

Suggested labels

lgtm, approved

Suggested reviewers

• ibuziuk
• rohanKanojia
• btjd

Poem

🐰 A framework born, so clear and bright,
For decisions recorded, all fair and right,
From secrets shared to process shown,
The garden of choices, now widely known!
First ADR planted, may many more grow,
In the code we build, let wisdom flow! 🌱

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the main change: establishing an ADR framework with template and agent guidelines, which is the primary focus of all file additions.
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.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[tolusha]

Hi! I'm che-ai-assistant — I help with your pull requests.

Available commands:

• /che-ai-assistant generate-che-doc — Generate a documentation PR based on this PR's changes
• /che-ai-assistant ok-pr-review — Run a comprehensive PR review (summary, code review, deep review, impact analysis)
• /che-ai-assistant help — Show this help message

[coderabbitai]

Caution

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

⚠️ Outside diff range comments (1)

AGENTS.md (1)

785-785: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Update stale "Last Updated" metadata.

AGENTS.md was modified in this PR, but Line 785 still says 2025-12-24. Please bump it to the actual update date to keep document metadata trustworthy.

🤖 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 `@AGENTS.md` at line 785, Update the stale "Last Updated" metadata by replacing
the existing date string "2025-12-24" in the AGENTS.md header with the actual
update date for this PR (use the current repo update date, e.g., "2026-05-15"),
so the document's Last Updated field accurately reflects this modification.

🤖 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.

Outside diff comments:
In `@AGENTS.md`:
- Line 785: Update the stale "Last Updated" metadata by replacing the existing
date string "2025-12-24" in the AGENTS.md header with the actual update date for
this PR (use the current repo update date, e.g., "2026-05-15"), so the
document's Last Updated field accurately reflects this modification.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e50f32ea-19f8-40af-9518-5449c4282909

📥 Commits

Reviewing files that changed from the base of the PR and between 1e949fc and e6e2c2d.

📒 Files selected for processing (6)

• .claude/CLAUDE.md
• AGENTS.md
• adr/2026-05-11-backup-auth-secret-lifecycle.md
• adr/AGENTS.md
• adr/README.md
• adr/TEMPLATE.md

[akurinnoy]

Follow-up to #1631. This PR depends on #1631 being merged first (the ADR file references code changes from that PR).