Add cross-agent repo guidance

[titusfortner]

Description

Docs repo never did the equivalent of: SeleniumHQ/selenium#16735
This PR includes updates from: SeleniumHQ/selenium#17756

• Adds AGENTS.md as the canonical repo instruction file for agents.
• Adds a minimal CLAUDE.md compatibility pointer to AGENTS.md.
• Documents .local/ as a private, ignored workspace for contributor-specific notes and scratch work.
• Adds .github/pr_review.md as the canonical PR review rubric for documentation-focused reviews.
• Wires GitHub Copilot PR review and Qodo to the shared PR review guidance.
• Adds Qodo automation for PR description and review on PR events, and review on pushes.

Motivation and Context

This gives contributors and automated review tools one concise source of repo-specific guidance.
The PR review guidance is focused on the main risks for this documentation repository: broken Hugo
rendering, malformed shortcodes/tabs/code blocks, stale gh-codeblock references, and translation
structure drift.

[netlify]

❌ Deploy Preview for selenium-dev failed.

Name	Link
🔨 Latest commit	eb96ed5
🔍 Latest deploy log	https://app.netlify.com/projects/selenium-dev/deploys/6a4d5c9a7e367c000801eb72

[qodo-code-review]

PR Summary by Qodo

Add canonical agent and PR review guidance with automation wiring

📝 Documentation ⚙️ Configuration changes ✨ Enhancement 🕐 10-20 Minutes

AI Description

• Add AGENTS.md as canonical repository guidance for human and automated agents.
• Introduce a documentation-focused PR review rubric and link automation tools to it.
• Document a private .local/ workspace and enable Qodo PR review/description automations.

Diagram

graph TD
  A["Contributors & agents"] --> B["AGENTS.md"] --> C[".github/pr_review.md"]
  E["CLAUDE.md"] --> B
  B --> D[".local/README.md"]
  I[".github/copilot-instructions.md"] --> C
  F([".pr_agent.toml"]) --> J{{"Automated PR review bots"}} --> C

  subgraph Legend
    direction LR
    _doc["Doc / guidance file"] ~~~ _cfg(["Automation config"]) ~~~ _ext{{"External tool"}}
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Put all guidance in README.md / CONTRIBUTING.md

• ➕ Reduces the number of top-level guidance files
• ➕ Uses a familiar convention for contributors
• ➖ Mixes human contribution workflow with agent/tool-specific instructions
• ➖ Harder to keep a concise, agent-consumable canonical source

2. Use GitHub-only guidance (CODEOWNERS + PR template + review checklist)

• ➕ Keeps review standards close to the PR experience
• ➕ Can standardize reviewer prompts in one place
• ➖ Less useful for local/offline agent workflows
• ➖ Doesn’t provide a single canonical cross-tool instruction source

Recommendation: The PR’s approach (AGENTS.md as canonical guidance + a single PR review rubric consumed by both humans and automation) is the best fit for “cross-agent” consistency. The main alternatives either dilute agent-focused instructions into general contributor docs or over-index on GitHub UI features that don’t help local agent workflows.

Files changed (6) +144 / -0

Documentation (4) +131 / -0

pr_review.mdAdd documentation-focused PR review guidelines +48/-0

Add documentation-focused PR review guidelines

• Introduces a canonical rubric emphasizing Hugo/Markdown rendering hazards, shortcode/tab correctness, and gh-codeblock path/line-range integrity. Also defines reviewer style expectations and what not to comment on.

.github/pr_review.md

README.mdDocument a private, git-ignored .local workspace +17/-0

Document a private, git-ignored .local workspace

• Defines .local/ as a contributor-only scratch and customization area (ignored by Git except this README). Explicitly prohibits production dependencies on .local content.

.local/README.md

AGENTS.mdAdd canonical repository instructions for agents +65/-0

Add canonical repository instructions for agents

• Creates AGENTS.md with project overview, repo map, standard commands, and working guidance specific to Hugo/Docsy docs and gh-codeblock usage. Also documents the .local overlay mechanism for contributor-specific agent instructions and skills.

AGENTS.md

CLAUDE.mdAdd CLAUDE.md compatibility pointer to AGENTS.md +1/-0

Add CLAUDE.md compatibility pointer to AGENTS.md

• Adds a minimal CLAUDE.md that redirects to AGENTS.md as the canonical instruction source. This preserves compatibility with tools expecting CLAUDE.md without duplicating guidance.

CLAUDE.md

Other (2) +13 / -0

copilot-instructions.mdPoint Copilot PR reviews at the shared review rubric +1/-0

Point Copilot PR reviews at the shared review rubric

• Adds a Copilot instruction that directs PR reviewers to follow .github/pr_review.md. This keeps automated review behavior aligned with the repo’s documentation-specific risks.

.github/copilot-instructions.md

.pr_agent.tomlConfigure Qodo/PR Agent commands and push-triggered reviews +12/-0

Configure Qodo/PR Agent commands and push-triggered reviews

• Adds PR Agent configuration to run /agentic_describe and /agentic_review on PR events, and to run review commands on pushes. Also injects extra reviewer instructions pointing to the shared PR review rubric.

.pr_agent.toml

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Broken AGENTS.md reference ✗ Dismissed 🐞 Bug ⚙ Maintainability

Description

CLAUDE.md points to @AGENTS.md, but the canonical instruction file added by this PR is
AGENTS.md (no leading @), which can mislead readers and tooling that treats the reference as a
literal path.

Code

CLAUDE.md[1]

+This repository uses @AGENTS.md as the canonical repo instruction file.

Evidence

CLAUDE.md names @AGENTS.md, but the actual canonical file present in the repo is AGENTS.md, so
the reference does not match an existing filename.

CLAUDE.md[1-1]
AGENTS.md[1-2]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`CLAUDE.md` references `@AGENTS.md`, but the repository file is `AGENTS.md`. This is likely a typo and can confuse humans and any automation that expects a literal filename.

## Issue Context
The PR’s goal is to make `AGENTS.md` the canonical instruction source; `CLAUDE.md` is intended as a compatibility pointer.

## Fix Focus Areas
- CLAUDE.md[1-1]

## Suggested change
Update the line to reference `AGENTS.md` (optionally as a markdown link), e.g.:
- `This repository uses AGENTS.md as the canonical repo instruction file.`
- or `See [AGENTS.md](AGENTS.md) for repo instructions.`

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---