T8595: add AGENTS.md + Copilot symlink for the vyos-org central Mergify baseline

[andamasov]

Summary

Adds AGENTS.md at repo root with a .github/copilot-instructions.md symlink to ../AGENTS.md, completing AGENTS.md fleet coverage for the vyos-org central Mergify baseline.

Content diverges from VyOS-Networks/mergify — see "Cross-repo context" for the rationale on the unified single-rule shape used here (vs the two-rule shape on the Networks side).

Authority: T8595, with T8782 / IS-432 context.

Local CodeRabbit (Phase 0 per WD-1334): 2 findings, both classified as symlink-deref false positives — CodeRabbit reviewed .github/copilot-instructions.md as if it were a standalone file rather than a symlink to ../AGENTS.md. Findings flagged "heading mismatch" and "Parent (this file) phrasing"; in AGENTS.md (the actual file) both are correct. Pushback rather than edit.

Test plan

• CodeRabbit auto-review (post-flip-to-ready) is clean
• Copilot review (manual @copilot review) is clean
• Maintainers approval before merge

🤖 Generated by robots

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Central YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: c2764d80-c9c3-4269-bc43-6a67121614f7

📥 Commits

Reviewing files that changed from the base of the PR and between 1c18ffc and 8642233.

📒 Files selected for processing (2)

• .github/copilot-instructions.md
• AGENTS.md

📜 Recent review details

🧰 Additional context used

🧠 Learnings (1)

📓 Common learnings

Learnt from: CR
Repo: vyos/mergify

Timestamp: 2026-05-17T08:48:17.173Z
Learning: Agents should be designed with clear responsibilities and single purposes

Learnt from: CR
Repo: vyos/mergify

Timestamp: 2026-05-17T08:48:17.173Z
Learning: Use type-safe communication patterns between agents

Learnt from: CR
Repo: vyos/mergify

Timestamp: 2026-05-17T08:48:17.173Z
Learning: Document agent interfaces and expected message contracts

Learnt from: CR
Repo: vyos/mergify

Timestamp: 2026-05-17T08:48:17.173Z
Learning: Implement error handling and recovery mechanisms in agents

Learnt from: CR
Repo: vyos/mergify

Timestamp: 2026-05-17T08:48:17.173Z
Learning: Use message queues for asynchronous agent communication

Learnt from: CR
Repo: vyos/mergify

Timestamp: 2026-05-17T08:48:25.597Z
Learning: Set commit/PR title format as `T<num>: <description>` (or optionally `scope: T<num>: <description>`)

Learnt from: CR
Repo: vyos/mergify

Timestamp: 2026-05-17T08:48:25.597Z
Learning: Use `production` as the default branch for this repository

Learnt from: CR
Repo: vyos/mergify

Timestamp: 2026-05-17T08:48:25.597Z
Learning: Keep repository visibility as public

Learnt from: CR
Repo: vyos/mergify

Timestamp: 2026-05-17T08:48:25.597Z
Learning: Understand that changes merged to `production` affect every consumer repo's next Mergify event immediately with no staging period

Learnt from: CR
Repo: vyos/mergify

Timestamp: 2026-05-17T08:48:25.597Z
Learning: Use `Mergifyio` slash commands only as a Maintainers-team member; commands from non-members are silently dropped

Learnt from: CR
Repo: vyos/mergify

Timestamp: 2026-05-17T08:48:25.597Z
Learning: Support multi-branch backports using space-separated commands in `Mergifyio` comments (e.g., `Mergifyio backport circinus sagitta`)

🪛 LanguageTool

AGENTS.md

[locale-violation] ~26-~26: In American English, ‘afterward’ is the preferred variant. ‘Afterwards’ is more commonly used in British English and other dialects.
Context: ...e) loads first; per-repo file is merged afterwards. Same-name rules in the child replace t...

(AFTERWARDS_US)

🔍 Remote MCP Context7

Summary of additional, review-relevant facts

• Mergify supports sharing configuration from another repository via the extends keyword; the extended config is loaded first and local rules add/override behavior. (Docs: "Extend Mergify Configuration" / "Combine Extended and Local Configuration")
• To extend a config from another repo, Mergify must be installed on the source repository so it can access the shared configuration. (Sharing/Extends doc)
• GitHub Copilot reads repository-wide custom instructions from .github/copilot-instructions.md and also accepts repository-root instruction files (e.g., AGENTS.md); repository instructions are used for Copilot code-review and other agent behaviors (Copilot reads the first ~4,000 characters). Creating a .github/copilot-instructions.md is the documented way to provide repo-wide guidance. (Copilot docs on repository instructions and generating copilot-instructions.md)

Relevant implications for this PR

• The chosen approach (extends-based central Mergify baseline + a symlink .github/copilot-instructions.md → ../AGENTS.md) is consistent with Mergify's extends behavior and with GitHub Copilot's documented sources of repository instructions; the symlink is an acceptable way to expose AGENTS.md content to Copilot without duplicating it.

Tools/sources used

• Context7 (Mergify docs: extends/sharing & changelog) via Context7_query-docs
• Context7 (GitHub Copilot docs: repository instructions / copilot-instructions.md guidance) via Context7_query-docs

🔀 Multi-repo context ansible/ansible

Linked repositories findings

ansible/ansible

• AGENTS.md exists at repo root; provides agent guidance and CI/dev commands. [::ansible/ansible::AGENTS.md]
• CLAUDE.md references AGENTS.md (list entry at top). [::ansible/ansible::CLAUDE.md:1]
• Packaging test excludes AGENTS.md from sdist via ignore_patterns in test/sanity/code-smell/package-data.py (entry 'AGENTS.md'). [::ansible/ansible::test/sanity/code-smell/package-data.py:36]

🔇 Additional comments (2)

AGENTS.md (1)

1-47: LGTM!

.github/copilot-instructions.md (1)

1-1: LGTM!

---

📝 Walkthrough

Summary by CodeRabbit

• Documentation
  • Added org-wide documentation describing the merge baseline, validation approach, merge/backport conventions, contributor workflows, and operational guidance for repository management.
  • Updated contributor assistance instructions to reference the new documentation for PR/commit formatting and contributor guidance.

Walkthrough

Adds AGENTS.md (lines 1-46) documenting the vyos org .mergify.yml baseline: inheritance semantics, repo divergences, contributor conventions, and operational notes. Updates .github/copilot-instructions.md (line 1) to reference ../AGENTS.md.

Changes

Organization Mergify baseline documentation

Layer / File(s)

Summary

Mergify baseline documentation and pointer AGENTS.md (lines 1-46), .github/copilot-instructions.md (line 1)

AGENTS.md (lines 1-46) introduces the org-wide .mergify.yml baseline: config intent, YAML schema validation/testing, extends: mergify inheritance, explicit divergences from VyOS-Networks/mergify (unified PR-message or: rule and org-specific header paths), contributor conventions (default branch, PR/commit title format, backport conflict handling and author assignment), and operational guidance (rollback, unqueue vs dequeue, maintainer-only @Mergifyio commands). .github/copilot-instructions.md (line 1) now contains a single-line pointer to ../AGENTS.md.

Possibly related PRs

• vyos/mergify#1: Adds AGENTS.md/Copilot documentation describing the same centralized Mergify baseline behavior and related .mergify.yml semantics.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	Title accurately summarizes the two main changes: adding AGENTS.md and a Copilot symlink for the vyos-org Mergify baseline.
Description check	✅ Passed	Description directly relates to the changeset, detailing AGENTS.md addition, the symlink purpose, content divergence rationale, and known CodeRabbit false positives.
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

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch agents-md-T8595

---

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

[andamasov]

@copilot review

[Copilot]

@copilot review

Review complete. One real finding fixed (8642233):

AGENTS.md — stale ignore_conflicts: false references (×2)
Both the project-purpose summary and the Conventions note incorrectly stated ignore_conflicts: false. .mergify.yml has had ignore_conflicts: true (with label_conflicts: backport-conflict + assignees: ["{{ author }}"] as compensating controls) since the incident post-mortem. Both lines updated to match the actual config.

Everything else looks correct:

• Symlink committed as gitlink (mode 120000), resolves cleanly to ../AGENTS.md ✓
• Cross-repo context rationale for the single-rule toggle shape is accurate ✓
• unqueue / requeue / multi-branch backport notes are correct ✓
• CodeRabbit's "heading mismatch" and "Parent (this file)" findings remain pushback — in the actual AGENTS.md source both are correct; those were symlink-deref false positives as described in the PR ✓

[andamasov]

@copilot review

[Copilot]

@copilot review

No new findings. Current state (HEAD 8642233) is clean:

• AGENTS.md is factually consistent with .mergify.yml (ignore_conflicts: true, label_conflicts: backport-conflict, assignees: ["{{ author }}"]) ✓
• Symlink committed as gitlink mode 120000 → ../AGENTS.md ✓
• Cross-repo context, single-rule toggle rationale, command restriction notes — all accurate ✓
• CodeRabbit's two prior findings remain valid pushback (symlink-deref false positives) ✓

[andamasov]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[andamasov]

@coderabbitai full review

[coderabbitai]

✅ Actions performed

Full review triggered.

[andamasov]

@coderabbitai full review

[coderabbitai]

✅ Actions performed

Full review triggered.