[MINOR][INFRA] Instruct agents to use --no-track when creating worktrees or branches

[nchammas]

What changes were proposed in this pull request?

Specify that when creating a new worktree or branch, agents should use --no-track so they don't accidentally target upstream/master.

Why are the changes needed?

I just pushed 3731453 directly to master from a new worktree. It was a mistake and I was surprised by it. The worktree was configured to push directly to upstream/master. I believe this happened because I let an agent (for the first time) create the worktree for me and it followed the instructions in our AGENTS file:

create a new git worktree from <upstream>/master and work from there

More background here: #58136 (comment)

To be clear, I made the commit and push myself, not the agent. What the agent did is create the worktree.

Does this PR introduce any user-facing change?

No.

How was this patch tested?

TODO:

• I will try using an agent to create a new worktree (without committing or pushing anywhere, of course) and inspect the setup. I will report back here.

Was this patch authored or co-authored using generative AI tooling?

No.

[pan3793]

I think the existing behavior is correct, cutting from <upstream>/master so you won't start from a stale state, but usually, your main repo stays with the master branch and the newly created worktree with a different branch (worktrees can not use the same branch at the same time by design)

[nchammas]

I use VS Code with Copilot and a mix of models. When I made this mistake, I was using Grok 4.5.

This is what Grok 4.5 does when I ask it to create a new worktree so I can develop some doc fixes (formatted for clarity):

git fetch upstream master
git worktree add -b docs-spelling-grammar ../spark.worktrees/docs-spelling-grammar upstream/master
git -C ../spark.worktrees/docs-spelling-grammar status -sb
git -C ../spark.worktrees/docs-spelling-grammar log -1 --oneline
git worktree list

If I then cd to the new worktree folder and inspect the push target, I see this:

$ git status -sb
## docs-spelling-grammar...upstream/master

I believe this is the problem. Normally, if you git push with this setup it will fail:

fatal: The upstream branch of your current branch does not match
the name of your current branch.

However, I sometimes use VS Code's command palette to push. And this unfortunately has different behavior.

Git: Push from the VS Code command palette constructs the equivalent of this command:

git push upstream docs-spelling-grammar:master

And this is exactly how I ended up pushing 3731453 directly to master.

I believe this is a footgun that will eventually bite someone else, especially if they use VS Code and Git: Push.

[nchammas]

I think instead of having freeform instructions on how to create a worktree, we should perhaps have a small shell script to do it and instruct agents to use the script. It's too easy for something to be misconfigured otherwise.

If we like that idea, I can work on it. If not, I think we should try at least tweaking the wording of the AGENT instructions.

In any case, for the time being I will not let agents create worktrees anymore. I've used them before without issue; the first time I let an agent do it for me it created this situation!

cc @dongjoon-hyun

[nchammas]

@pan3793 - I've refactored the pre-flight checks section. What do you think? Does my post mortem make sense?

[pan3793]

@nchammas, I understand what happened, but I would only touch this

... create a new git worktree from `<upstream>/master` and work from there (recommended) ...
                                                     /|\
                                           add words "with `--no-track`"

I usually perform git push by either:

1. ask the agent to push with the words "push to my forked repo", or
2. type and run the git push ... command manually, or
3. push via a GUI tool but set the target remote branch clearly

[nchammas]

OK, I've cut things back to just add the --no-track instruction.

I'm honestly not happy with the current set of agent instructions and think we need a major refactor. There are too many things in there that a) touch personal workflows or b) belong in the user docs. But I will raise this separately.