Add AGENTS.md to guide AI agents and developers#170
Merged
Conversation
This repository's role in the Git for Windows ecosystem is not immediately apparent from examining the code alone. It works in tandem with the GitForWindowsHelper GitHub App, which receives slash commands and triggers workflows here to perform the heavy lifting. Understanding this relationship, along with patterns like check-run mirroring and the various workflow triggers, requires cross-referencing multiple repositories and piecing together context from workflow definitions, JavaScript modules, and shell scripts. To reduce this onboarding burden for both human contributors and AI agents assisting with maintenance, this document consolidates the essential architectural knowledge: how workflows are triggered, what each module does, which secrets are required, and how the pieces connect to other Git for Windows repositories. Assisted-by: Claude Opus 4.6 Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
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 <johannes.schindelin@gmx.de>
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 <johannes.schindelin@gmx.de>
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 <johannes.schindelin@gmx.de>
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 <johannes.schindelin@gmx.de>
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 <johannes.schindelin@gmx.de>
dscho
force-pushed
the
add-an-AGENTS.md-file
branch
from
71df4d7 to
b23cc23
Compare
mjcheetham
approved these changes
Apr 29, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
AI-assisted contributions are a reality of open source, and that includes the maintainers themselves. Over recent
months, AI has proven increasingly useful for the kind of menial, tedious work that does not require much creativity
but is highly boring when done by hand: chasing down CI failures, tracing cross-repository automation flows, and
adapting workflows to upstream changes.
This AGENTS.md provides enough context about the repository's architecture, conventions, and contracts that AI tools
can produce reasonable results even when a human contributor fails to steer carefully. Similar files have been added
to other repositories in the Git for Windows project:
gitandMINGW-packages.So let's add an
AGENTS.mdfile to provide guidance for AI agents (and developers) working with this repository. It documents:gfw-helper-github-app(workflow filenames, check-run names, artifact names)git describein merging-rebase topologies, version update script environments)