The initial version focused on describing what exists, but contributors also
need to know what must not change without coordination. Workflow filenames,
check-run names, artifact naming patterns, and summary text formats are parsed
by the GitForWindowsHelper GitHub App to drive cascading behavior. Changing
these without updating the helper app will silently break the automation
pipeline.

This revision reframes the guidance to be more prescriptive: preserve these
contracts, validate changes against the helper app's expectations, and treat
cross-repository updates as API boundaries. The expanded list of affected
repositories and the new validation checklist should help contributors avoid
accidentally breaking downstream consumers.

Assisted-by: Claude Opus 4.6
Signed-off-by: Johannes Schindelin <[email protected]>

While reviewing the MSYS2 sync automation in PR #152, we discovered
that multi-line content inside `run: |` and `script: |` blocks
silently gets truncated when any line falls below the block's base
indentation level. This is particularly treacherous for heredoc bodies
and JS template literals whose content naturally starts at column 0.

Document the pitfall and the two mitigations that worked: indenting
heredoc bodies to match the YAML block's base indentation, and using
`[...].join('\n')` for multi-line JS strings.

See #152 (comment)
for the context that prompted this.

Assisted-by: Claude Opus 4.6
Signed-off-by: Johannes Schindelin <[email protected]>

After rebasing onto current main, several files that were added since
the original AGENTS.md commit are now missing from the documentation:
the rebase-shears.yml and remove-packages-from-pacman-repository.yml
workflows, the gently.js and get-workflow-run-artifact.js modules, and
five root shell scripts (rebase-branch.sh, stash-with-conflicts.sh,
apply-stash-with-conflicts.sh, gh-cli-auth-as-app.sh, and
prepare-embargoed-branches.sh). This commit adds them all, together
with the .github/agents/ directory in the tree overview.

Assisted-by: Claude Opus 4.6
Signed-off-by: Johannes Schindelin <[email protected]>

The previous version documented specific bugs (the v2.54.0 MSYS2 sync
deletion, the msys2-runtime version mis-detection) as if they were
open issues. They are fixed. What matters for AGENTS.md is the
generalizable learning that prevents the same class of mistake in
future, unrelated code:

Sparse checkout with --no-checkout leaves the index empty, so a bare
`git commit` sees deletions for every path outside the cone. This
applies anywhere worktrees are created this way, not just the MSYS2
sync branch.

`git describe` is unreliable for finding the nearest ancestor tag in
merging-rebase topologies. The `for-each-ref %(ahead-behind)`
approach generalizes to any repository with a similarly complex DAG.

Version update scripts are hard to debug because they operate on a
specific layout of bare clones, worktrees, and alternates files. The
key principle is object visibility: objects fetched into one clone are
invisible to another unless they share an object store or alternates
are configured.

Assisted-by: Claude Opus 4.6
Signed-off-by: Johannes Schindelin <[email protected]>

Document the Cygwin -> MSYS2 -> Git for Windows fork chain for the
POSIX emulation runtime, and how it relates to what users call "Git
Bash" (which is actually mintty launching Bash on top of the
msys2-runtime). Note that the most common class of user-reported
bugs traces back to the pseudo-console emulation in the
msys2-runtime, not to Bash or mintty.

Document the maintainer development environment: the Git for Windows
SDK is typically installed on a Dev Drive (D:\) for I/O performance,
and repositories live under /usr/src/ inside the SDK. Beyond the
obvious core repos (git, MINGW-packages, MSYS2-packages,
build-extra, git-for-windows-automation), maintainers also commonly
have 7-Zip, setup-git-for-windows-sdk, rss-to-issues,
track-website-changes, and msys2-runtime checked out there.

Assisted-by: Claude Opus 4.6
Signed-off-by: Johannes Schindelin <[email protected]>