Skip to content

general: T8595: add AGENTS.md #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
andamasov wants to merge 1 commit into
base: production
Choose a base branch
from
Open

general: T8595: add AGENTS.md #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/copilot-instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
../AGENTS.md
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot May 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical | ⚡ Quick win

File must be a symlink, not text content.

PR description states this should be "a .github/copilot-instructions.md symlink" but the file appears to be regular text containing ../AGENTS.md rather than an actual symlink. Git and GitHub support symlinks natively.

Create as actual symlink:

ln -s ../AGENTS.md .github/copilot-instructions.md
git add .github/copilot-instructions.md

Tools reading .github/copilot-instructions.md expect either the target content (via symlink resolution) or standalone instructions, not a path string.

🤖 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 @.github/copilot-instructions.md at line 1, The file
.github/copilot-instructions.md is a plain text file containing "../AGENTS.md"
but should be a symlink to the actual AGENTS.md; remove the plain file and
replace it with a symbolic link named .github/copilot-instructions.md that
points to ../AGENTS.md (ensure ../AGENTS.md exists in the repo), then git add
the symlink so the repository stores a symlink rather than literal text.

50 changes: 50 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
# AGENTS.md — `vyos/coderabbit`

## Project purpose

Org-wide central CodeRabbit baseline for `vyos/*`. CodeRabbit's [central-configuration](https://docs.coderabbit.ai/configuration/central-configuration) feature looks up a repo named exactly `coderabbit` in each org and auto-applies its `.coderabbit.yaml` to every other repo in that org which does not carry its own. This repo is configuration-only — no build artifacts, no Actions, no code.

Public so anyone can audit how AI code review is configured for the public org.

## Tech stack

- Single YAML file: `.coderabbit.yaml` (CodeRabbit schema v2).
- `README.md` (purpose + override instructions).
- `CODEOWNERS` (`@vyos/maintainers`).

## Build / test / run

No build, no tests, no runtime. Edits to `.coderabbit.yaml` take effect on the next PR webhook in any inheriting repo (ten-second propagation in practice; CodeRabbit's org-level cache may take up to ~15 min to refresh on first config publish).

## Repository layout

- `.coderabbit.yaml` — central baseline. Pins `inheritance: true` so per-repo overrides deep-merge instead of fully replacing.
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot May 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Incorrect: central baseline should NOT pin inheritance: true.

Line 21 states the central baseline pins inheritance: true, but the central config has no parent to inherit from—it IS the baseline. Only per-repo override files need inheritance: true to deep-merge with this central baseline (correctly stated at line 27).

Remove or rephrase line 21 to avoid contradiction:

-- `.coderabbit.yaml` — central baseline. Pins `inheritance: true` so per-repo overrides deep-merge instead of fully replacing.
+- `.coderabbit.yaml` — central baseline. Per-repo overrides must pin `inheritance: true` to deep-merge instead of fully replacing.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
- `.coderabbit.yaml` — central baseline. Pins `inheritance: true` so per-repo overrides deep-merge instead of fully replacing.
- `.coderabbit.yaml` — central baseline. Per-repo overrides must pin `inheritance: true` to deep-merge instead of fully replacing.
🤖 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 21, The doc incorrectly states the central baseline
`.coderabbit.yaml` pins `inheritance: true`; update AGENTS.md to remove or
rephrase that claim so it no longer implies the baseline has a parent — clarify
that only per-repo override files should set `inheritance: true` to deep-merge
with the central baseline and that the central `.coderabbit.yaml` should not set
`inheritance: true`.

- `README.md` — purpose, inheritance model, override pattern, rollback.
- `CODEOWNERS` — Maintainers.

## Inheritance model (load-bearing)

Every per-repo override file MUST also pin `inheritance: true`. Without it, the override fully replaces this baseline. With it, CodeRabbit deep-merges per the [configuration-inheritance docs](https://docs.coderabbit.ai/configuration/configuration-inheritance):
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot May 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Remove "also" to fix inheritance documentation.

The word "also" incorrectly implies the central baseline has inheritance: true (echoing line 21's error). Only per-repo overrides need this flag.

-Every per-repo override file MUST also pin `inheritance: true`. Without it, the override fully replaces this baseline. With it, CodeRabbit deep-merges per the [configuration-inheritance docs](https://docs.coderabbit.ai/configuration/configuration-inheritance):
+Every per-repo override file MUST pin `inheritance: true`. Without it, the override fully replaces this baseline. With it, CodeRabbit deep-merges per the [configuration-inheritance docs](https://docs.coderabbit.ai/configuration/configuration-inheritance):
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
Every per-repo override file MUST also pin `inheritance: true`. Without it, the override fully replaces this baseline. With it, CodeRabbit deep-merges per the [configuration-inheritance docs](https://docs.coderabbit.ai/configuration/configuration-inheritance):
Every per-repo override file MUST pin `inheritance: true`. Without it, the override fully replaces this baseline. With it, CodeRabbit deep-merges per the [configuration-inheritance docs](https://docs.coderabbit.ai/configuration/configuration-inheritance):
🤖 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 27, The sentence currently reads "Every per-repo override
file MUST also pin `inheritance: true`" which wrongly implies the central
baseline has that flag; edit the sentence to remove the word "also" so it reads
"Every per-repo override file MUST pin `inheritance: true`", ensuring the
documentation clearly states that only per-repo overrides must set `inheritance:
true`.


- objects: deep-merged
- arrays: unioned
- scalars: child wins

Override files restate only the keys that should deviate; everything else inherits.

## Conventions

- Commit / PR title format: `component: T12345: description`. Phorge task ID at https://vyos.dev mandatory.
- Default branch: `production`.
- Schema: pin `# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json` at the top of every config file in the fleet (central + per-repo overrides).
- Tone: `tone_instructions` is generic on this public baseline. Internal-product-specific tone goes in `VyOS-Networks/coderabbit` (private).

## Cross-repo context

- Sibling: `VyOS-Networks/coderabbit` (private, same baseline + `git-actions` added to `base_branches`).
- Authority: [T8764](https://vyos.dev/T8764) (parent rollout), [T8765](https://vyos.dev/T8765) (this repo's provisioning).
- Per-repo overlays/overrides are deployed as the consuming repo's own `.coderabbit.yaml` — see spec doc referenced from T8764 for the overlay catalogue (Python, OCaml, C/C++, Perl, shell, TypeScript, Ansible, Go, PHP, Terraform, docs, workflow).

## Rollback

`git revert` the offending commit, or set `.coderabbit.yaml` body to `{}`. Either makes every inheriting repo fall back to CodeRabbit's hardcoded defaults on the next PR webhook.