Add AI policy

[jonatack]

Opened for discussion. Adapted from (rewritten by hand based on) Bitcoin Core's AI Policy.

[Hero-Gamer]

I think #2265 is a good draft direction. I researched this with ChatGPT, MetaAI, and Gemini, had them review and challenge each other's research, and then made my own edits based on that process.

I came away with 3 small wording improvements for the Editors' consideration, based on current policies from Debian, Kubernetes, and Home Assistant (among others, but after several rounds of review, I decided to leave the others out).

1. Make clear that AI does not lower the contribution standard

Current:

A high bar is held for all contributions to this project.

Suggested:

A high bar is held for all contributions to this project. AI assistance does not lower the normal contribution standard.

Debian's 2026 policy explicitly says AI-assisted contributions remain subject to the same standards as other contributions, and AI use does not diminish contributor responsibility. [Debian 2026 AI policy]

2. Make pre-submission verification explicit

Current:

This project requires a human author in the loop who fully understands the proposal or change.

Suggested:

This project requires a human author in the loop who reviews, verifies, and fully understands the proposal or change before submission.

Kubernetes explicitly says:

"Do not leave the first review of AI generated changes to the reviewers."

[Kubernetes PR guidance]

Home Assistant similarly requires contributions to be reviewed and understood by the contributor before submission. [Home Assistant AI policy]

3. Optional clarification for communication

The current wording says comments are expected to be written by humans. It may be worth clarifying that AI-assisted grammar or clarity does not replace human authorship of the substance.

For example:

AI may be used to improve grammar or clarity, but the substance of comments and responses must be the contributor's own.

Home Assistant makes this distinction explicitly. [Home Assistant AI policy]

---

I would consider #1 and #2 the more substantive improvements, with #3 as an optional clarification.

I particularly like #2 because it makes it explicit that the human contributor must step in, review, and verify the work before submission.

Disclosure: This comment itself was AI-assisted. I used multiple AI models to research and challenge the suggestions, then reviewed, edited, and understood the resulting recommendations rather than simply copying an AI response.

---

One open question regarding suggestion #2: the current text, and my suggested wording, do not explicitly define whether the pre-submission review/verification requirement applies to issues/proposals, pull requests, or both. Other projects take slightly different approaches here. Is the intention to deliberately keep this broad, or would it be better to clarify the scope?

[Hero-Gamer]

Also super minor comment, there is already an AI Policy, so the title of "Add AI Policy" made me think there wasn't an AI Policy and now we wanna add one. Maybe slightly more accurate if there title is named "AI Policy revision/update"

[Hero-Gamer]

Thirdly, one additional consideration for the Editors: should Bitcoin Core provide repository-level, agent-facing guidance for AI coding tools alongside the human-facing AI_POLICY.md - such as AGENTS.md?

A human contributor can read and understand the policy, but an AI tool used during the contribution does not necessarily know that the policy exists or that it should follow it. This creates a potential gap between the rules understood by the human and the behavior of the tool.

Other mature open-source projects are beginning to address this directly. Rust uses an AGENTS.md to operationalize its LLM policy and repository workflow for coding agents, while keeping the human-facing documentation authoritative. Linux has dedicated AI Coding Assistants documentation that explicitly directs AI-assisted development to follow the normal kernel development process and requires the assistant to read the relevant process documentation before starting. Kubernetes projects are also using AGENTS.md to provide concrete agent instructions around testing, minimal changes, and contribution policy.

For Bitcoin Core, this could potentially be a concise AGENTS.md that does not duplicate or replace AI_POLICY.md, but directs AI agents to treat AI_POLICY.md, CONTRIBUTING.md, and relevant developer/testing documentation as authoritative and follow them before making or proposing changes.

I think this is worth considering (or maybe you guys are already considering) as part of the broader AI contribution workflow.

---

I've noticed many repos now all have AGENTS.md - therefore would like to raise this point.
If the contributor such as myself read the AI policy.md but forgot to tell the clanker to follow it, it could create a gap. If we did have an agents.md file which all agents must read before work begins, could help prevent contributors' AI agents not following the AI policy more surely - hopefully removing the needs for BIP Editors having to check if people have been following guideline, this could be a more scalable approach to save you guys' valuable time.
Many people don't read docs... they should, but they don't... that's the reality.. So hopefully their AI will definitely read the doc!

[jonatack]

@Hero-Gamer Thank you for reviewing! I pushed an update taking some of your suggestions. I appreciated looking at the other AI policies that you linked to.

A high bar is held for all contributions to this project. AI assistance does not lower the normal contribution standard.

I don't think the second sentence is needed, as it is covered by "all" in the first sentence.

there is already an AI Policy

Are you referring to this one? If yes, the BIPs are a separate project from that one.

applies to issues/proposals, pull requests, or both

This repo doesn't have issues, only pulls, so we're already good there.

provide repository-level, agent-facing guidance for AI coding tools

Please feel free to propose your idea for an AGENTS.md, while keeping in mind that we don't (for now, I think) want changes opened or driven by autonomous agents.

[kanzure]

I don't see the value of adding policies. Just reject bad or low quality work. Adding policies to moderate that work is only going to slow things down or cause problems. If you don't like the work that someone is doing, then don't collaborate with them.

[Hero-Gamer]

Are you referring to this one? If yes, the BIPs are a separate project from that one.

Yes! (yeah I am clearer these are 2 separate repos/projects that the AI_POLICY.md are treated differently. Thanks!)

Please feel free to propose your idea for an AGENTS.md, while keeping in mind that we don't (for now, I think) want changes opened or driven by autonomous agents.

# Agent Instructions

This repository contains the Bitcoin Improvement Proposals (BIPs) and related process documentation. BIP process and review requirements are authoritative.

These instructions are for AI agents and automated tools working in this repository. Human contributors should follow the normal repository contribution process.

## Sources of Truth

Before making changes, read the documentation relevant to the task:

* `AI_POLICY.md` for AI-assisted contribution requirements.
* `CONTRIBUTING.md` for repository contribution guidance.
* The applicable BIP and BIP process documentation.
* Relevant discussion and implementation references when needed.

The repository's documented BIP process and contribution requirements are authoritative. This file provides navigation and stable agent-specific guardrails; it does not replace them.

## Contribution Principles

* Keep changes focused and minimal. Do not reformat unchanged text or modify unrelated BIPs or files.
* Do not invent or assume BIP process rules. If the documentation is ambiguous, identify the ambiguity rather than guessing.
* Verify factual and technical claims against relevant primary sources.
* Preserve the meaning and status of existing BIPs unless the applicable process permits the change.
* Do not autonomously publish issues, pull requests, reviews, comments, or other public communications.

## When Uncertain

If a change could affect the meaning, status, compatibility, or interpretation of a BIP, stop and seek human clarification.

Prefer identifying uncertainty over guessing.

---

A little context on how I arrived at this proposal.

• This is actually my first contribution touching Bitcoin documentation directly. Historically I've mostly been a reader, observer, and learner of the Bitcoin repositories, so I'm very much open to correction here.

• I spent some time (with different AIs) looking at how other mature open-source projects (and looking at how Bitcoin current structure and culture is) handle AI-assisted development.

• A pattern that stood out was using a root AGENTS.md as a predictable entry point for AI agents, while keeping the actual human-facing policies and contribution documentation authoritative. Rust is a good example of this approach: https://github.com/rust-lang/rust/blob/main/AGENTS.md

That led me to think the BIPs repository could benefit from a deliberately small AGENTS.md. The goal isn't to create another policy or duplicate the BIP process. It's simply to tell an agent:

• what repository it is working in
• which documents are authoritative
• which mistakes to avoid
• when it should stop and ask rather than guess

I think this is particularly useful for BIPs because this is a specification and process repository rather than a conventional codebase.

The principle I'm working from is:

Don't make the AI smarter. Make the repository harder to misunderstand.

I've proposed a first draft above, but I'd genuinely welcome feedback and changes from people more familiar with the BIPs process. I'm treating this as a starting point, not a finished design.

---

Location of AI_POLICY.md file in /bitcoin/bitcoin

• One related thought from looking at Bitcoin Core: its AI_POLICY.md currently lives under doc/, while CONTRIBUTING.md is at the repository root.
• I wonder whether, from an AI discoverability perspective, the policy would be better placed at the root as well?
• Core's CONTRIBUTING.md already directs AI-assisted contributors to the AI policy, so this wouldn't change the policy itself.
• It would simply make the policy easier for an agent entering the repository to discover alongside the other top-level contribution documents.

I'd consider that a separate discussion from this BIPs proposal.

Similarly, IF this pattern proves useful here, I could see a small root AGENTS.md being useful in the Bitcoin Core repository too, with Core-specific build, testing, and security guidance.