RFC: AI Documentation Directory Structure

[sg00dwin]

Purpose

This is a Request for Comments (RFC) on a proposed AI documentation architecture for the Console repository.

What This Is

• 📋 A proposal document for team review
• 🗳️ Requesting feedback and approval on the directory structure
• ⏸️ Not ready to merge - this is discussion only

What's Being Proposed

Summary:

• Create modular AI documentation (AGENTS.md + .ai/ guideline files)
• Establish Claude Code team configuration (.claude/settings.json)
• Clean separation of team vs personal configuration

Next Steps

• Collect team feedback
• Address concerns
• Get approval
• Close this PR (won't merge)
• Implement approved structure on separate branch

Questions?

Comment below or reach out directly. Thanks for reviewing! 🙏

[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

[coderabbitai]

Important

Review skipped

Auto reviews are limited based on label configuration.

🚫 Excluded labels (none allowed) (1)

• do-not-merge/work-in-progress

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Note

Reviews paused

Use the following commands to manage reviews:

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

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

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

[openshift-ci]

[APPROVALNOTIFIER] This PR is NOT APPROVED

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

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

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

[sg00dwin]

@coderabbitai ignore

[coderabbitai]

✅ Actions performed

Reviews paused.

[sg00dwin]

Asked Gemini, and Grok where the supporting docs, for coding agents, should reside in the console repo (ARCHITECTURE.md, CONVENTIONS.md, TESTING.md) Here's the short analysis summary.

The top choice it in the /console/ root for best scan discoverability by multiple agents and give some statistics to back it up. The next choice would be in a console/docs/ or console/ai/ and definitely not console/.ai/ because of the hidden folder implication. So I suggest we go with the root location.