Add AI agent documentation and architecture reference - #4066
Closed
yboaron wants to merge 1 commit into
Closed
Conversation
yboaron
requested review from
Oats87,
dfarrell07,
skitt,
sridhargaddam,
tpantelis and
vthapar
as code owners
June 15, 2026 08:45
Contributor
|
🤖 Created branch: z_pr4066/yboaron/add-ai-agent-support |
WalkthroughAdds ChangesRepository Documentation for AI Agents and Developers
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes Caution Pre-merge checks failedPlease resolve all errors before merging. Addressing warnings is optional.
❌ Failed checks (1 error)
✅ Passed checks (4 passed)
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. Comment |
yboaron
force-pushed
the
add-ai-agent-support
branch
from
June 15, 2026 08:46
14c7a31 to
d1a6399
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 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 `@AGENTS.md`:
- Around line 46-51: The three documentation links in AGENTS.md for Datapath
Architecture, Tunnel Analysis, and RouteAgent Analysis reference a non-existent
submariner-diagnostics repository on GitHub. Either replace these links with the
correct documentation URLs from https://submariner.io if the referenced analysis
documents are available there, or remove these links entirely if the analysis
documents are no longer maintained. Ensure that any replacement links point to
valid and accessible documentation sources.
In `@CLAUDE.md`:
- Line 3: Replace the non-standard `@AGENTS.md` syntax with proper Markdown link
syntax by converting it to `[AGENTS.md](URL)` format, where URL should be the
appropriate link destination. This change ensures compliance with Markdown
standards and consistency with the proper link format already used elsewhere in
the CLAUDE.md file.
- Around line 5-6: In CLAUDE.md at lines 5-6, replace the broken URL
`[AGENTS.md](https://agents.md/)` with `[AGENTS.md](./AGENTS.md)` to use a
relative link to the actual AGENTS.md file. In AGENTS.md around line 32, add
documentation explaining that the `@filename.md` syntax (used throughout files
like `@AGENTS.md`, `@ARCHITECTURE.md`, `@.agents/commit-templates.md`) is a
custom cross-reference convention for AI agents to navigate the documentation.
In ARCHITECTURE.md at lines 12-14, no direct change is required as the external
GitHub links for Datapath Architecture, Tunnel Analysis, and RouteAgent Analysis
are valid.
🪄 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: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 9f98cfb2-ea33-4308-8703-f48d41ff369e
📒 Files selected for processing (3)
AGENTS.mdARCHITECTURE.mdCLAUDE.md
Comment on lines
+5
to
+6
| This project uses [AGENTS.md](https://agents.md/) as the standard for | ||
| providing context to AI coding agents. |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Comprehensive verification across all three modified markdown files
cd "$(git rev-parse --show-toplevel)"
echo "=== 1. Checking Markdownlint Configuration ==="
if [ -f ".markdownlintrc" ] || [ -f ".markdownlint.json" ] || [ -f ".markdownlint.yaml" ]; then
echo "Found markdown linting config:"
find . -maxdepth 1 -name ".markdownlint*" -type f -exec cat {} \;
else
echo "No markdown linting config found at root"
fi
echo -e "\n=== 2. Verifying Referenced Workflow Files Exist ==="
workflow_files=(
".agents/commit-templates.md"
".agents/workflows/cve-fix.md"
".agents/workflows/konflux-component-setup.md"
"ARCHITECTURE.md"
"AGENTS.md"
)
for f in "${workflow_files[@]}"; do
if [ -f "$f" ]; then
echo "✓ $f"
else
echo "✗ MISSING: $f"
fi
done
echo -e "\n=== 3. Checking for Custom @ Reference Patterns in Codebase ==="
echo "Files using @ references:"
rg -l '@[A-Z_]' --type md
echo -e "\nContext of @ usage:"
rg -n '@[A-Z_]' --type md -B1 -A1Repository: submariner-io/submariner
Length of output: 736
🏁 Script executed:
#!/bin/bash
cd "$(git rev-parse --show-toplevel)"
echo "=== 1. Checking for Makefile markdownlint target ==="
if [ -f "Makefile" ]; then
grep -n "markdownlint" Makefile || echo "No markdownlint target found"
else
echo "No Makefile found"
fi
echo -e "\n=== 2. Exact content of CLAUDE.md lines 1-10 ==="
head -10 CLAUDE.md | cat -n
echo -e "\n=== 3. Exact content of AGENTS.md around lines 30-35 ==="
sed -n '30,35p' AGENTS.md | cat -n
echo -e "\n=== 4. Exact content of AGENTS.md around lines 115-120 ==="
sed -n '115,120p' AGENTS.md | cat -n
echo -e "\n=== 5. Exact content of ARCHITECTURE.md lines 12-14 ==="
sed -n '12,14p' ARCHITECTURE.md | cat -n
echo -e "\n=== 6. Searching for @ reference documentation ==="
rg "@" --type md --glob "*.md" | head -20Repository: submariner-io/submariner
Length of output: 1591
🏁 Script executed:
#!/bin/bash
cd "$(git rev-parse --show-toplevel)"
echo "=== 1. Search for @ reference documentation in README/docs ==="
rg "@ reference|@.*\.md|document reference" --type md -i | head -20
echo -e "\n=== 2. Check for markdownlint config in subdirectories ==="
find . -name ".markdownlint*" -type f 2>/dev/null
echo -e "\n=== 3. Check if makefile or other build config mentions markdownlint ==="
find . -name "Makefile*" -o -name "*.mk" -o -name "Taskfile*" 2>/dev/null | xargs grep -l "markdownlint" 2>/dev/null || echo "No markdownlint in build configs"
echo -e "\n=== 4. Check .github workflows for markdownlint ==="
find .github -name "*.yaml" -o -name "*.yml" 2>/dev/null | xargs grep -l "markdownlint" 2>/dev/null || echo "No markdownlint in GitHub workflows"
echo -e "\n=== 5. Count all @ prefix usages in markdown files ==="
rg "@[A-Za-z_./\-]+" --type md -o | sort | uniq -c | sort -rnRepository: submariner-io/submariner
Length of output: 955
🏁 Script executed:
#!/bin/bash
cd "$(git rev-parse --show-toplevel)"
echo "=== 1. Content of .markdownlint.yml ==="
cat .markdownlint.yml
echo -e "\n=== 2. Content of .markdownlintignore ==="
cat .markdownlintignore
echo -e "\n=== 3. Content of .github/workflows/linting.yml ==="
cat .github/workflows/linting.yml
echo -e "\n=== 4. Search for @ reference explanation in AGENTS.md and related docs ==="
rg -B5 -A5 "@.*\.md" AGENTS.md CLAUDE.md | head -50
echo -e "\n=== 5. Check if README documents the @ prefix convention ==="
cat README.md | grep -A10 -B10 "@" || echo "No @ documentation in README"Repository: submariner-io/submariner
Length of output: 8272
🏁 Script executed:
#!/bin/bash
cd "$(git rev-parse --show-toplevel)"
echo "=== 1. Search for markdownlint target in Makefile (verbose) ==="
grep -n "^markdownlint" Makefile || echo "Pattern: ^markdownlint not found"
grep -n "markdownlint" Makefile | head -20 || echo "No markdownlint references"
echo -e "\n=== 2. Check Makefile for includes or sourced files ==="
head -50 Makefile | cat -n
echo -e "\n=== 3. Verify GitHub links are accessible (check response codes) ==="
urls=(
"https://github.com/submariner-io/submariner-diagnostics/blob/devel/docs/analysis/datapath-architecture.md"
"https://github.com/submariner-io/submariner-diagnostics/blob/devel/docs/analysis/tunnel-analysis.md"
"https://github.com/submariner-io/submariner-diagnostics/blob/devel/docs/analysis/routeagent-analysis.md"
)
for url in "${urls[@]}"; do
echo "Testing: $url"
curl -s -o /dev/null -w "HTTP Status: %{http_code}\n" "$url" || echo "Could not test (curl may be unavailable)"
doneRepository: submariner-io/submariner
Length of output: 2976
🏁 Script executed:
#!/bin/bash
cd "$(git rev-parse --show-toplevel)"
echo "=== 1. Check if markdownlint is a script in scripts/ directory ==="
ls -la scripts/ | grep -i markdown
echo -e "\n=== 2. Search entire Makefile for markdownlint (not just start of line) ==="
cat Makefile | grep -i markdownlint
echo -e "\n=== 3. Check SHIPYARD_DIR and Makefile.inc for markdownlint ==="
echo "SHIPYARD_DIR value:"
grep "SHIPYARD_DIR" Makefile | head -5
echo -e "\nSearching for markdownlint in common locations:"
find . -name "Makefile.inc" -o -name "*makefile*" | xargs grep -l "markdownlint" 2>/dev/null || echo "Not found in local makefiles"
echo -e "\n=== 4. Verify the exact broken URL in CLAUDE.md ==="
sed -n '5,6p' CLAUDE.md
echo -e "\n=== 5. Check if @ prefix is a dockyard/markdown-it plugin convention ==="
rg "markdown-it|dockyard|@" .markdownlint.yml || echo "No special plugins configured"
echo -e "\n=== 6. Full AGENTS.md to understand @ context ==="
wc -l AGENTS.mdRepository: submariner-io/submariner
Length of output: 743
🏁 Script executed:
#!/bin/bash
cd "$(git rev-parse --show-toplevel)"
echo "=== Final verification: Check complete AGENTS.md for @ usage context ==="
cat AGENTS.mdRepository: submariner-io/submariner
Length of output: 4927
Fix broken URL and document @ reference syntax convention.
-
Broken URL in CLAUDE.md line 5: Change
[AGENTS.md](https://agents.md/)to[AGENTS.md](./AGENTS.md). The domainhttps://agents.md/is not a valid reference. -
Undocumented @ reference syntax: The
@prefix is used throughout the AI agent context files (@AGENTS.md,@ARCHITECTURE.md,@.agents/commit-templates.md, etc.) but is never documented as a custom convention. Add clarification to AGENTS.md explaining that@filename.mdis a custom cross-reference syntax for AI agents to navigate the documentation—or implement actual markdown link conversion if this syntax is meant to be processed. -
External GitHub links verified: The three submariner-diagnostics links in ARCHITECTURE.md (Datapath Architecture, Tunnel Analysis, RouteAgent Analysis) are valid and accessible.
-
Markdownlint is required: The coding guideline is correct—
make markdownlintis enforced by the CI pipeline (.github/workflows/linting.yml). Ensure it was run before commit.
📍 Affects 3 files
CLAUDE.md#L5-L6(this comment)AGENTS.md#L32-L32ARCHITECTURE.md#L12-L14
🤖 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 `@CLAUDE.md` around lines 5 - 6, In CLAUDE.md at lines 5-6, replace the broken
URL `[AGENTS.md](https://agents.md/)` with `[AGENTS.md](./AGENTS.md)` to use a
relative link to the actual AGENTS.md file. In AGENTS.md around line 32, add
documentation explaining that the `@filename.md` syntax (used throughout files
like `@AGENTS.md`, `@ARCHITECTURE.md`, `@.agents/commit-templates.md`) is a
custom cross-reference convention for AI agents to navigate the documentation.
In ARCHITECTURE.md at lines 12-14, no direct change is required as the external
GitHub links for Datapath Architecture, Tunnel Analysis, and RouteAgent Analysis
are valid.
Source: Coding guidelines
Consolidates project documentation to support AI coding assistants and improve developer onboarding: - AGENTS.md: Tool-agnostic entry point for AI assistants (Claude Code, Cursor, Copilot, etc.) following the AGENTS.md standard - ARCHITECTURE.md: Complete architectural overview from PR submariner-io#3956 by aswinsuryan, relocated to root per maintainer feedback - CLAUDE.md: Simplified to reference AGENTS.md following industry best practices (Langflow pattern) Enables AI assistants to answer questions about codebase structure. References submariner-diagnostics for runtime datapath details. Signed-off-by: Yossi Boaron <yboaron@redhat.com>
yboaron
force-pushed
the
add-ai-agent-support
branch
from
June 15, 2026 12:19
d1a6399 to
0911e7f
Compare
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 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 `@AGENTS.md`:
- Around line 152-158: Update the submariner-diagnostics link in the
Troubleshooting section of AGENTS.md (lines 152-158). Verify if the referenced
submariner-diagnostics repository at
github.com/submariner-io/submariner-diagnostics is now available and accessible.
If the repository does not exist or is not available, replace the link with a
reference to subctl's diagnostic capabilities as documented on the Submariner
website. Note that this same non-existent repository link also appears elsewhere
in the file (lines 46-51) and should be updated consistently across both
locations.
- Around line 46-51: The documentation links for Datapath Architecture, Tunnel
Analysis, and RouteAgent Analysis in AGENTS.md reference a non-existent
submariner-diagnostics repository. Verify whether these analysis documents are
available at https://submariner.io or elsewhere, then either replace the GitHub
links with the correct URLs if the documents exist, or remove these three
documentation references entirely if they are no longer maintained. Ensure any
retained links are functional and properly documented.
🪄 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: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 9085cf72-1c9b-4fe8-a2f9-d18ffd04b73c
📒 Files selected for processing (3)
AGENTS.mdARCHITECTURE.mdCLAUDE.md
✅ Files skipped from review due to trivial changes (2)
- CLAUDE.md
- ARCHITECTURE.md
Contributor
|
This pull request has been automatically marked as stale because it has not had recent activity. It will be closed if no further |
Contributor
|
🤖 Closed branches: [z_pr4066/yboaron/add-ai-agent-support] |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Consolidates project documentation to support AI coding assistants and improve developer onboarding:
Enables AI assistants to answer questions about codebase structure. References submariner-diagnostics for runtime datapath details.
Summary by CodeRabbit
AGENTS.md, including architecture context, patterns, build/test guidance, and troubleshooting references.ARCHITECTURE.mdwith a fuller overview of Submariner components, roles, APIs, metrics, and build/CI notes.CLAUDE.mdto direct agents toAGENTS.mdas the primary source of repository guidance.