[no-ci] Support organization-owned forks in AGENTS.md

[rwgk]

Description

This updates the repository-wide agent guidance to support approved forks owned by either personal accounts or organizations.

The existing guidance assumes that every contributor uses a personal fork and can always open a pull request with gh pr create. That command currently cannot identify some renamed organization-owned forks (cli/cli#10093), even though GitHub's GraphQL API supports selecting the head repository explicitly through headRepositoryId.

The update:

• requires agents to distinguish the canonical repository and fork by complete OWNER/REPOSITORY names;
• keeps the canonical repository read-only by default, with a narrowly scoped exception when the user explicitly requests a specific upstream test branch;
• uses gh pr create when it can identify the fork unambiguously;
• documents the GraphQL headRepositoryId fallback for organization-owned forks; and
• preserves pull-request template, assignee, label, and milestone requirements regardless of how a pull request is created.

The wording is intentionally repository-neutral so the guidance remains applicable across supported development setups.

Review focus:

• Is the upstream-push exception narrow enough while still supporting workflow testing?
• Is the API fallback clear enough for agents to use reliably?
• Are the fork and repository identity checks sufficiently explicit?

This PR does not have an associated GitHub issue.

Validation:

• pre-commit run --files AGENTS.md
• git diff --check

Checklist

• New or existing tests cover these changes. (Not applicable: this is an agent-guidance-only change.)
• The documentation is up to date with these changes.

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[mdboom]

I've had enough run-ins with my agent pushing branches and creating pull requests before they were ready that I've worked really hard to get my agent to /never/ write anything in a remote location without my consent (and I prefer to be in the driver's seat even now for those steps).

I'm worried that a lot of the language here will encourage my agent to act too autonomously again. We should instead frame it in terms of things we want it /not/ to do (don't push to a fork that can't be the source of the PR you are trying to create), rather than things /to do/ (use gh pr to create PRs). To put it another way -- this is shared context we want everyone to agree on to collaborate well together. It's not intended to prescribe /how/ to accomplish that. A pre-AI analogy would be: we all agree to write standard text files and share them with git. We don't have to agree on what editor we are using or what git tool we use.

Therefore, I think the only required change here should be:

All branch creation and pushes must go to the contributor's
personal fork.

changes to:

Branch creation and pushes must not go directly to the canonical upstream fork. Use the user's personal fork, or if that is not supported as an official fork of upstream, use a intra-repo fork "owned" by the user.  Confirm that the push target is a fork of the base repository and is not the base repository itself.

[rwgk]

@mdboom Could you please take another look?

The section now separates remote-write policy from technical procedure. It explicitly requires direct user authorization, states that a push request does not authorize PR creation, and clarifies that the technical instructions grant no permission by themselves.

[mdboom]

@mdboom Could you please take another look?

The section now separates remote-write policy from technical procedure. It explicitly requires direct user authorization, states that a push request does not authorize PR creation, and clarifies that the technical instructions grant no permission by themselves.

I'm still in favor of just fixing the bug (that it mentions personal forks and intra-org forks are also ok). The rest of this feels like unnecessary prescription. Any of us can put it in our local instructions if we want this, but I don't think we all will.

Can we move the PR creation stuff to a skill such that I could easily tell my agent to ignore it?