[docs] Add AGENTS.md contribution policy; route .claude/CLAUDE.md to it

[eicherseiji]

Why

Ray is a high-traffic repo, and AI-assisted contributions have made low-value and duplicate PRs more common. Each one notifies CODEOWNERS, triggers CI, and consumes maintainer attention. This adds a contribution policy aimed at AI-assisted PRs to reduce that load, and makes AGENTS.md the single source of truth for agent instructions.

What

Adds a top-level AGENTS.md, modeled on vLLM's AGENTS.md. It establishes a mandatory contribution policy for AI-assisted work:

• Duplicate-work checks before opening a PR (gh searches against ray-project/ray).
• No low-value busywork PRs (single typo, lone style tweak, one mutable default, etc.) unless bundled with substantive work or coordinated with maintainers.
• Accountability: pure code-agent PRs disallowed; a human must understand, test, and defend the change; the PR description must disclose that AI assistance was used, list tests run, and explain why the change is not a duplicate.
• Fail-closed: if the work is duplicate, trivial, or cannot be defended by a human, do not open a PR.

It also folds the repo overview (layout, default test timeout) into AGENTS.md and routes Claude Code to the same file: .claude/CLAUDE.md is now a one-line @../AGENTS.md import, mirroring vLLM's CLAUDE.md -> AGENTS.md pattern. Claude Code does not read AGENTS.md natively, so the import is what bridges both tool families to one file. The previous inline skill hints are dropped because the /rebuild, /lint, and /fetch-buildkite-logs skills auto-load by relevance; the .claude/ directory (settings, skills, subagents, path-scoped rules, per-library CLAUDE.md) is otherwise unchanged.

The contributing guide surfaces the policy without duplicating it: doc/source/ray-contribute/getting-involved.md gains an "AI-assisted contributions" section that literalincludes the repo-root AGENTS.md. This keeps AGENTS.md the single source of truth while making the policy discoverable on docs.ray.io. literalinclude embeds the file verbatim, so AGENTS.md's repo-relative links are not parsed and cannot trip the fail_on_warning docs build.

Build/test/lint details remain deferred to Ray's existing contribute docs to avoid duplication.

AI-assisted contribution disclosure

This PR is itself AI-assisted, so it follows the policy it introduces:

• AI assistance used. Drafted with Claude Code. The submitter reviewed every line and is accountable for the change end-to-end.
• Not a duplicate. Ran the policy's duplicate-work check; no other open PR adds an AGENTS.md or an AI-contribution policy:

  gh pr list --repo ray-project/ray --state open --search "AGENTS.md in:title"
  gh pr list --repo ray-project/ray --state open --search "contribution policy AI"
  

  Only this PR matches.
• Verification.
  • Every in-repo path referenced by AGENTS.md was confirmed to exist. The pre-commit command matches getting-involved.md (pre-commit==3.5.0, pre-commit run). pre-commit ran at commit time; the docs markdown matches no code hooks, so all were skipped with no failures.
  • Docs build. A warnings-as-errors (-W) Sphinx + MyST build (myst-parser 5.1.0, matching CI) of the new literalinclude against the real AGENTS.md passed clean and embedded the file verbatim. Because literalinclude embeds rather than parses, AGENTS.md's repo-relative links do not resolve on the docs site and so cannot trip fail_on_warning.
  • Context load. A fresh Claude Code session in the repo resolves .claude/CLAUDE.md -> @../AGENTS.md and loads the policy: it recites the accountability rules verbatim, while the same probe in an empty directory returns nothing, confirming the import is the source. The import path follows the Claude Code memory docs.

Related

vLLM contribution policy: https://github.com/vllm-project/vllm/blob/main/AGENTS.md

[gemini-code-assist]

Code Review

This pull request introduces a new policy document AGENTS.md and updates .claude/CLAUDE.md to establish mandatory guidelines for AI-assisted contributions to the Ray repository. The feedback suggests pinning the pre-commit version to 3.5.0 for consistency and removing the --all-files flag from the manual pre-commit run command to prevent extremely slow execution times on this large codebase.

[abrarsheikh]

wdyt about amending this info to https://docs.ray.io/en/latest/ray-contribute/getting-involved.html and pointing AGENTS.md ot that? seems like a good idea, but the question it will that work?

[eicherseiji]

Good call on discoverability. I did it, but pointed the other way: AGENTS.md stays the source of truth and the contributing guide pulls it in.

Direction matters here because AGENTS.md only works when its text is loaded into the agent's context. Native tools like Codex and Cursor read the file directly, and Claude Code loads it through .claude/CLAUDE.md -> @../AGENTS.md. A link to the docs page is not loaded content, so pointing AGENTS.md at the docs would strip the policy from the context of the tools it targets.

So in 7779e74 I added an "AI-assisted contributions" section to getting-involved.md that literalincludes the repo-root AGENTS.md. One source of truth, and the policy now renders on docs.ray.io.

On "will that work?", yes, verified both paths:

1. Docs build. literalinclude embeds the file verbatim, so AGENTS.md's repo-relative links are not parsed and cannot trip fail_on_warning. A warnings-as-errors build passed clean with the content embedded.
2. Context load. A fresh Claude Code session in the repo resolves the @../AGENTS.md import and loads the policy. It recites the accountability rules verbatim, while an empty directory returns nothing, confirming the import is the source.