Move AGENTS.md to the repository root, make its checks runnable, and link the AI policy

Problem/Motivation

There have been grumblings that AGENTS.md "wasn't doing anything", with slop issues and comments still coming through. So over in #3636154: Remove CLAUDE.md now that Claude (finally) supports AGENTS.md I thought it would be pretty funny to solve this with Claude Code, and decided to attempt to do this with my normal "vibe coding" flow (e.g. just ask the agent to fix it, not read anything in advance, lean on the agent's built-in knowledge + default skills) and then log what happened.

The log and the follow-up tests showed:

• core/AGENTS.md does not load when an agent starts at the repository root, which is where its own commands run from.
• It ships to every site through drupal/core, with rules meant for core contributors.
• The code checks and tests were never run, and nothing reported that.
• No rule required the operator to see a post before it went up.
• The agent first saw the AI policy at step 73 of 75.

How this scope was reached

The first version of this issue proposed a lot more, including replacing the "Discouraged uses" section and changing the disclosure line. Reading #3585894: LLM harm reduction in Drupal core contribution, AGENTS.md guidelines changed that. That file came after several earlier issues, and it is a harm reduction compromise that went in for a three-month trial.

• "Discouraged uses" is layered on purpose (#15), and it was part of what the release managers agreed to (#41). It stays.
• The disclosure line names no tool on purpose, because small local models hallucinate their names (#11). It stays.

What is left is what serves the file's own goal: rules that reach core contributors, checks that actually run, and a human seeing each post first. The trial started on 2026-06-27, and its evaluation in #3606814: [PP until 2026-09-30] Evaluate AGENTS.md effects has not happened yet.

Proposed resolution

• Move AGENTS.md and CLAUDE.md to the root. This keeps them out of drupal/core.
• Add check and test setup to §3 and §4.
• Add §6: approval before posting, no self-RTBC, no credit changes, no pushing to another contributor's MR without their agreement.
• Add §7: read issues through the API, not a summary, and the issue fork steps.
• Link the AI policy.

Tested with Claude Code and Codex against a fake posting command. Without §6, agents posted in 8 of 8 runs. With it, 0 of 8. Full steps and results are in the attached process log, and the raw output of every run is in the second attachment.

Remaining tasks

• Release and framework manager review, with #3606814.

What this does not fix

This will not end the original complaint. Anyone pasting from a chat window never loads this file, and it cannot prove that an operator understood the output.

• Started outside the checkout, Claude Code loads the rules only after opening a file there. Codex did not load them.
• Started in core/, headless Claude Code skips the import.
• Approval given in advance bypasses §6.
• drupal/drupal still includes root files.
• cspell does not cover the root file.

Release notes snippet

Rules for LLM tools used on Drupal core moved from core/ to the repository root, so they apply when a tool is started at the root of a clone and no longer ship to site projects. New rules require operator approval before posting to drupal.org, forbid pushing to another contributor's MR without agreement, and require reporting which tests did not run.

AI disclosure

Generated with the help of an LLM.