[build] document .local customization and add PR review guidance

[titusfortner]

🔗 Related Issues

💥 What does this PR do?

• Clarifies usage for .local/ as the documented directory for user-specific/local agent customization including skills
• Clarifies that one of the reasons to point --output_base to .local is for worktrees so it gets cleaned up with the worktree
• Removes git tracking for anything ".local"
• Adds a concise repo-specific rubric for automated PR reviewers

🔧 Implementation Notes

• PR review guidance is stored in one place (.github/pr_review.md) and referenced by .pr_agent.toml (Qodo), .github/copilot-instructions.md (Copilot), and AGENTS.md.
• Removed @ references in AGENTS files since only Claude always properly responds to it
• CLAUDE.local.md (previously tracked, containing the dangling import) is untracked and added to .gitignore alongside AGENTS.local.md/GEMINI.local.md.
• Don't check in anything .local

🤖 AI assistance

• AI assisted (complete below)
  • Tool(s): Claude Code
  • What was generated: the AGENTS.md/.gitignore edits, .local/README.md, and .github/pr_review.md plus the Qodo/Copilot wiring
  • I reviewed all AI output and can explain the change

💡 Additional Considerations

We are moving to a new Qodo plan, which may change how the review integration behaves; the .pr_agent.toml wiring and referenced guidance may need adjustment after that switch.

🔄 Types of changes

• Cleanup (formatting, renaming)

[qodo-code-review]

PR Summary by Qodo

Document .local workspace customization and centralize agentic PR review guidance

📝 Documentation ⚙️ Configuration changes 🕐 10-20 Minutes

AI Description

• Add centralized PR review rubric for automated reviewers in .github/pr_review.md.
• Document .local/ as the gitignored location for per-contributor customization and skills.
• Wire the review rubric into Copilot instructions and Qodo /agentic_review configuration.

Diagram

graph TD
  E{{"AI review tools"}} --> B[".github/pr_review.md"] --> A[".github/copilot-instructions.md"] --> D[".pr_agent.toml"]
  B --> C["AGENTS.md"] --> F[(".local/ workspace")]
  F --> G[".local/README.md"]

  subgraph Legend
    direction LR
    _ext{{"External"}} ~~~ _doc["Doc/Guide"] ~~~ _dir[("Directory")]
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. GitHub PR template checklist

• ➕ Shows the rubric directly in every PR without relying on tool integrations
• ➕ Benefits human reviewers equally (not just agentic reviewers)
• ➖ Harder to keep concise; can add noise to PR creation
• ➖ Doesn't automatically steer agentic reviewers unless they are configured to read it

2. Embed guidance directly in each tool config (Copilot/Qodo)

• ➕ No indirection; each tool gets tailored, tool-specific guidance
• ➖ Duplicated content drifts over time
• ➖ Harder for contributors to discover and update in one place

Recommendation: Keeping a single rubric in .github/pr_review.md and referencing it from AGENTS/Copilot/Qodo is the best tradeoff: one source of truth, easy to evolve, and it avoids duplicated guidance across multiple tool configs. If human-reviewer visibility becomes a goal, consider additionally adding a short PR template that links to the same rubric (not a full copy).

Files changed (5) +61 / -5

Documentation (3) +57 / -5

pr_review.mdAdd repo-specific rubric for agentic PR reviews +32/-0

Add repo-specific rubric for agentic PR reviews

• Introduces a concise, Selenium-specific PR review guide focusing on correctness, compatibility, security, and cross-binding parity. Also defines what to avoid commenting on to reduce review noise and provides guidance on actionable comments and test suggestions.

.github/pr_review.md

README.mdDocument intended usage of the '.local/' workspace directory +14/-0

Document intended usage of the '.local/' workspace directory

• Adds a README describing '.local/' as the place for private customizations, scratch work, generated artifacts, and local agent instructions/skills. Lists common optional subpaths to standardize local layout without committing local files.

.local/README.md

AGENTS.mdClarify '.local/' customization overlay and link PR review guidance +11/-5

Clarify '.local/' customization overlay and link PR review guidance

• Adds a dedicated section documenting '.local/' as the per-contributor overlay (including optional '.local/AGENTS.md' and skill definitions). Also adds guidance to use '--output_base=.local/bazel-out' for restricted environments/worktrees and links reviewers to '.github/pr_review.md'. Removes older, duplicated '.local/' workspace text in favor of the new structured section.

AGENTS.md

Other (2) +4 / -0

copilot-instructions.mdReference centralized PR review rubric for Copilot reviews +1/-0

Reference centralized PR review rubric for Copilot reviews

• Adds an explicit instruction for Copilot-driven PR reviews to follow '.github/pr_review.md' in addition to 'AGENTS.md'. This aligns Copilot review behavior with the repo-specific rubric.

.github/copilot-instructions.md

.pr_agent.tomlWire Qodo '/agentic_review' to follow '.github/pr_review.md' +3/-0

Wire Qodo '/agentic_review' to follow '.github/pr_review.md'

• Adds an '[agentic_review]' section to provide extra instructions pointing reviewers to the centralized PR review guidance. This keeps the Qodo review command aligned with the repo rubric.

.pr_agent.toml

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📜 Skill insights (0)

Context used

✅ Compliance rules (platform): 11 rules

1. Relative output_base footgun ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

AGENTS.md recommends --output_base=.local/bazel-out, but because it’s a relative path it can
resolve under whatever directory Bazel is invoked from, potentially creating build output outside
the repo-root .local/ tree. This can lead to unignored generated directories (e.g.,
java/.local/...) since the repo .gitignore only ignores the top-level /.local/*.

Code

AGENTS.md[28]

+- When the default output directory is restricted or when working in a git worktree, isolate build output with `--output_base=.local/bazel-out`. It is a startup flag, so it goes *before* the command: `bazel --output_base=.local/bazel-out build //...` (not after `build`/`test`/`query`).

Evidence

The new guidance uses a relative --output_base value. The repo ignores only root /.local/*, so
if the relative path is resolved under a subdirectory, the resulting .local directory would not be
ignored and would pollute the working tree.

AGENTS.md[25-30]
.gitignore[151-152]
rust/README.md[12-13]

Agent prompt

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

### Issue description
`AGENTS.md` documents `--output_base=.local/bazel-out` as a workaround, but this is a relative path and may land outside the repo-root `.local/` (and therefore outside the only `.local` ignore rule) if Bazel is run from a subdirectory.

### Issue Context
The repo `.gitignore` ignores only the top-level `/.local/*`, not nested `.local` directories elsewhere. Some repo docs also explicitly instruct running Bazel from the repo top-level directory.

### Fix Focus Areas
- AGENTS.md[25-30]

### Suggested change
Adjust the guidance to ensure the output base is anchored to the repo root, e.g.:
- Explicitly instruct running Bazel from the repo root before using `--output_base=.local/bazel-out`, **or**
- Use an absolute/anchored path example (e.g., repo-root path) so the output always ends up under the ignored `/.local/` directory.

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

---

[qodo-code-review]

Code review by qodo was updated up to the latest commit 61ae9a8

[qodo-code-review]

Code review by qodo was updated up to the latest commit 5047256