Proposal: AI usage guidelines

[ascorbic]

I've been looking into creating some broader guidelines on AI use in the project. We have info on use in creating PRs, but I think we need to cover other areas. These are my suggestions, written up with help from Codex based on my requirements.

AI usage guidelines

EmDash welcomes contributions created with AI tools. The human contributor remains responsible for the result, and conversations with community members should remain human unless a narrow exception is stated below.

This proposal extends the existing AI disclosure rules to cover agent actions and project communication. It distinguishes AI agents from ordinary CI automation such as test results, dependency updates, and deterministic status comments.

General principles

• Disclose material AI assistance. Name the model or tool used.
• Review all AI-generated work before submitting it. For code, inspect the complete diff, run the relevant tests, and exercise the changed behaviour yourself.
• Keep a human in control of every external action. An agent may open a particular pull request or issue only after a human explicitly authorises that item.
• Do not give an agent standing permission to choose work and open pull requests or issues autonomously. Autonomous contribution agents such as Claws are not permitted.
• Do not use an agent to reply to a human except in the implementation-PR review cases allowed below.
• Posting from an identifiable bot account removes the need for a signature, but it does not override a surface where AI participation is prohibited.

No drive-by pull requests

Open a pull request only when at least one of the following applies:

• You use EmDash yourself and the change addresses a concrete problem you encountered.
• You maintain or substantially contribute to a tool, dependency, or service that EmDash uses, and the change directly concerns that integration. For example, the maintainer of a localization tool may correct EmDash's configuration for that tool.
• An EmDash maintainer has approved that specific change before you open the pull request.

Do not ask an agent to scan the repository for contribution opportunities or manufacture plausible work. Speculative cleanups, generic refactors, bulk fixes, and changes selected only because an agent could generate them are not accepted. Technical correctness does not make a drive-by change useful to the project.

The pull request must explain the contributor's connection to the change and how they verified it. If none of the listed cases fits a legitimate contribution, obtain maintainer approval before opening the pull request. AI assistance does not replace first-hand context or relevant expertise.

Code and pull requests

AI-generated code is welcome and is held to the same quality standard as human-written code. The submitter must understand the change, review it, test it, and be able to maintain it.

An agent may create commits, draft a pull request description, and open a pull request under direct human control. The human must authorise that specific pull request and review the complete change before submission.

Every pull request must use the repository's pull request template and complete every applicable section. The AI disclosure must name all models and tools that materially generated code or pull request text. The template disclosure is sufficient for the pull request body; the body does not need a separate bot signature.

Issues

A human must reproduce a reported bug before an issue is opened. Screenshots, logs, and agent analysis do not replace human reproduction.

Issues should normally be written and posted by a human. An agent may help prepare or open a specific issue only after a human has verified the report, reviewed the complete issue, explicitly authorised that issue, and disclosed the AI assistance in its body.

Agents must not write or post comments or replies on issues after they are opened.

Discussions and Design PRs

AI may help prepare the initial text of a proposal for a Discussion. Before posting it, a human must review and edit it for correctness, coherence, and length, disclose the AI assistance, and post it manually.

Agents and bots must not write or post comments or replies in Discussions. There are no exceptions. Discussions are spaces for direct human deliberation, including comments on proposals.

AI may help prepare the initial proposal in a Design PR under the same human-review and disclosure rules. All reviews, comments, and replies on Design PRs must be written and posted by humans. Automated AI reviewers must skip Design PRs.

Implementation PR comments and reviews

AI participation in pull request conversation is limited to code review and replies to code review on implementation PRs.

Situation	Rule
Replying to review comments on your implementation PR	Allowed under human control. Sign every substantially agent-written reply posted from a human account.
Reviewing another person's implementation PR	Allowed only when a human explicitly requests a code review of that PR. Limit comments to the code review and sign every agent-written review or comment posted from a human account.
Posting any other comment on another person's PR	Not allowed. The human must write and post it.
Commenting on a Design PR	Not allowed, including reviews and replies.
Posting from an authorised project bot account	Allowed only for configured implementation-PR review tasks. The bot identity replaces the signature.

A code review examines the proposed code for correctness, security, compatibility, tests, and conformance with an accepted design. It does not include project-management discussion, persuasion, general conversation, or replying on a human's behalf.

Use the following signature for allowed agent-written comments posted from a human account:

~ 🤖 Agent name (model name)

The signature must identify the actual model used. Add it to every agent-written review, inline comment, and review reply rather than only the final comment in a thread.

Allowed communication at a glance

Surface	AI may help draft the initial content	AI may post it from a human account	AI may write or post later comments
Pull request	Yes, with disclosure	Yes, with explicit permission for that PR	Only the implementation-PR review cases above
Issue	Normally human-written; permitted after human verification and review	Yes, with explicit permission for that issue	No
Discussion proposal	Yes, with disclosure and human editing	No; a human posts it manually	No
Design PR	Yes, with disclosure and human review	Yes, with explicit permission for that PR	No

Project-operated bots

Project-operated AI bots may perform narrowly configured code-review tasks on implementation PRs. They must use identifiable bot accounts and must not open contribution PRs or issues autonomously, participate in Discussions, comment on issues, or comment on Design PRs.

Ordinary CI and repository automation are outside this policy when they report deterministic results or perform an action explicitly requested through the repository's documented commands.

Implementation

If accepted, this policy will be added to the contributor documentation. The pull request template's AI section will cover AI-generated code and text, and reviewer automation will be configured to skip issues, Discussions, and Design PRs.

Feedback requested

Feedback is particularly useful on:

• Whether the distinction between an initial proposal and later human discussion is clear.
• Whether the limited implementation-PR review exceptions cover legitimate agent use without allowing agents to speak generally on a human's behalf.
• Whether AI-assisted issue creation should remain available after human reproduction and explicit approval, or whether issues should always be written and posted manually.
• Whether the direct-user, upstream-maintainer, and prior-approval routes cover legitimate contributions without permitting drive-by work.

[MA2153]

LGTM!

[keybits]

Excellent proposal.

What happens if the guidelines are broken? For example:

Agents and bots must not write or post comments or replies in Discussions.

I already received a reply in a Discussion here which I'm 99% sure was mostly AI written. The account appears to belong to a human, but the speed with with the verbose reply was posted and the numerous LLM prose artifacts left me feeling a bit sad. What would be the recommended course of action in such cases?

[ascorbic]

In future when this is in place I would start with a reminder of the rules. Hopefully wouldn't need to escalate, as in most cases I'm sure it would jst be them not knowing the rules

[swissky]

Does it count as “Agent writes” if a tool only corrects spelling and grammar in a comment you wrote yourself?

[ascorbic]

I'd say it's usually fine, but at the same time if it's just a comment then I'd prefer you just leave it uncorrected!

[danielmlr]

I like the proposal overall!

One question about emdashbot. #3808 drops the issue bot from TRIAGE.md, and this policy limits project-operated AI bots to code review and bars them from commenting on issues. Is the plan to retire emdashbot's issue triage and fix PRs? Today it prepares low-risk fixes on its own, and a human, often the reporter, accepts each one before a draft PR goes up. That's 9 merged PRs since Saturday and 5 open right now. If it's being retired, it would help to say so here, along with what happens to the 99 open issues that currently sit in bot:* states. If not, the bot section needs an exception for its issue comments and for PRs opened after a human accepts.

+1 to @swissky's question. I'd say fixing grammar or translating your own text shouldn't count as agent-written and shouldn't need a signature. That matters a lot for non-native speakers.

One more gap, between this policy and the governance proposal: the human-approval check in #3808 counts any approving review from a maintainer, but it can't tell whether the maintainer wrote it or posted an agent-written review under the signature this policy allows. I'd add one sentence to AI_POLICY.md and MAINTAINING.md: a maintainer's approval means they've reviewed and verified the change themselves, and an agent-written review is evidence for that decision, not a substitute for it.

[ascorbic]

emdashbot is staying, and is exempt from the comment rules. I'll update the doc. I've actually changed it to not wait for the human accpetance before opening the PR (though it still tracks whether it was accepted). I have been trying to make the triage bot more reliable so it can recover the failed or otherwise in-progress issues

I'll update to say that translation and spelling/grammar checks are fine but don't make it do full rewrites.

[CacheMeOwside]

Solid proposal! I support keeping AI-assisted issue preparation available after human reproduction and review.

From a triage perspective, it helps organize reproduction steps, logs, and environment details into a clearer report. The requirement that the author verifies the claims and approves the specific issue feels like a reasonable boundary.