Add AGENTS.md and remove maintenance-mode notice#1993
Merged
Conversation
tyrielv
force-pushed
the
tyrielv/agents-md
branch
2 times, most recently
from
06a3a14 to
5c83d6a
Compare
This commit does four related things:
1. Add an AGENTS.md at the repo root, following the 2025-2026 cross-tool
convention (Linux Foundation Agentic AI Foundation). It is natively read
by GitHub Copilot, Claude Code, OpenAI Codex, Cursor, Gemini CLI,
Windsurf, Aider, Devin, Zed, and others; agents that have their own
native file (e.g. CLAUDE.md) fall back to AGENTS.md when no native file
is present.
The file captures project-specific knowledge that isn't obvious from a
fresh `git clone` and which routinely trips up AI coding assistants:
- The wrapped-output layout (build outputs land one level up from the
working tree -- catches agents reaching for ./out or similar). Notes
the documented `src\` convention and that all commands assume CWD at
the enlistment root.
- Three explicit build paths scoped to scenario, so agents stop reaching
for the full installer build (~5 min, NativeAOT publish + Inno Setup,
no incremental support) when they just want to rerun a unit test:
Path A -- unit-test inner loop: ~10-15 s (dotnet build .csproj)
Path B -- functional-test loop: ~30-60 s (dotnet publish w/
PublishAot=false +
SkipCreateInstaller=true)
Path C -- installer build: ~5 min (Build.bat, only when you
actually need an installer)
Path B explicitly calls out the native C++ vcxproj prerequisite, since
dotnet publish won't build those.
- The NUnit filter footgun: this codebase uses NUnitLite, which supports
only --test (not --where). --where is silently ignored and runs every
test. For unit tests that's just slow; for functional tests it's hours
of wasted runtime against fresh enlistments.
- Fully-qualified-name requirement for --test (short names silently match
nothing).
- The vcpkg caching behavior in Build.bat (don't manually re-run vcpkg
unless overlay ports changed).
Coding standards are NOT duplicated here -- agents are pointed at
CONTRIBUTING.md, which already covers StyleCop, error handling,
TryXxx patterns, logging conventions, etc.
No new precompiled binaries, no helper scripts, no opinionated workflow
recommendations (worktree model etc.) -- just the minimum project-specific
knowledge needed to keep an agent productive in this repo.
2. Remove the "maintenance mode" notice from Readme.md. VFS for Git has
resumed active development; the line about "only required updates as a
reaction to critical security vulnerabilities will prompt a release" is
no longer accurate. The Scalar recommendation paragraph (for new
deployments) is unchanged.
3. Remove the build-badge table from Readme.md. The four pipelines it
referenced are a mix of still-running (gvfs/ci CI - Windows and
CI - Windows - Full Functional Tests, both currently green) and
never-configured for master (mseng/AzureDevOps GVFS/GitHub VFSForGit
Large Repo Perf Tests and Large Repo Build both render the "set up
now" placeholder). Active CI signal lives in the GitHub Actions
checks on each commit/PR; keeping a separately-maintained badge
table just creates a "is this still accurate?" question that no one
answers.
4. Update the "Building VFS for Git" section of Readme.md to reflect the
current build system:
- The .NET 10 SDK has replaced the .NET Core 8 SDK requirement.
- The "Install nuget.exe" prerequisite is gone (modern dotnet SDK
handles restore).
- vcpkg is now required (for native libgit2 et al.); call it out and
point at the official getting-started doc.
- The .NET Core cross-platform development workload and runtime
bullets are obsolete; dropped.
- The build script is `Build.bat`, not the historical
`BuildGVFSForWindows.bat`.
- The installer output path is `out\GVFS.Installers\bin\<Config>\win-x64\`,
not the historical `BuildOutput\GVFS.Installer.Windows\bin\x64\<Config>\`.
- Added a pointer at the end of the section to AGENTS.md for AI
coding assistants.
Assisted-by: Claude Opus 4.7
Signed-off-by: Tyrie Vella <tyrielv@gmail.com>
tyrielv
force-pushed
the
tyrielv/agents-md
branch
from
5c83d6a to
a3f95d4
Compare
derrickstolee
approved these changes
Jun 1, 2026
Contributor
derrickstolee
left a comment
derrickstolee
left a comment
There was a problem hiding this comment.
This is a great foundation. We should consider updating this or adding repo-specific skills as you continue to work agentically in this codebase.
This was referenced Jun 3, 2026
Merged
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.
Summary
Three related changes to make the repo more approachable for AI coding assistants and to correct outdated content in the Readme:
Add AGENTS.md at the repo root, following the 2025-2026 cross-tool convention (Linux Foundation Agentic AI Foundation). It's natively read by GitHub Copilot, Claude Code, OpenAI Codex, Cursor, Gemini CLI, Windsurf, Aider, Devin, and Zed; agents with their own native file (e.g. CLAUDE.md) fall back to AGENTS.md.
Remove the
maintenance modenotice fromReadme.md-- VFS for Git has resumed active development; the line aboutonly required updates as a reaction to critical security vulnerabilities will prompt a releaseis no longer accurate. The Scalar recommendation paragraph (for new deployments) is intentionally unchanged.Refresh the
Building VFS for Gitsection ofReadme.mdto match the current build system: .NET 10 SDK (not .NET Core 8), vcpkg requirement,Build.bat(notBuildGVFSForWindows.bat), corrected installer output path. Added a pointer to AGENTS.md at the end for AI coding assistants.What's in AGENTS.md
Just the project-specific knowledge that isn't obvious from a fresh
git cloneand which routinely trips up agents:src\convention documented for clones. All commands assume CWD at the enlistment root.dotnet buildofGVFS.UnitTests.csprojdotnet publishofFunctionalTests+PayloadwithPublishAot=falseandSkipCreateInstaller=true, thenRunFunctionalTests-Dev.ps1. Explicitly notes the native C++ vcxproj prerequisite.Build.bat, only when you actually need an installer--where. Use--test. For unit tests--whereis just slow; for functional tests it's hours of wasted runtime against fresh enlistments.--test(short names silently match nothing).Build.bat-- don't manually re-run unless overlay ports changed.Coding standards are not duplicated -- agents are pointed at
CONTRIBUTING.md, which already covers StyleCop, error handling,TryXxxpatterns, logging conventions, and themock:\\/mock://test URL convention.What's intentionally NOT in this PR
.github/copilot-instructions.mdorCLAUDE.mdstubs -- Copilot, Claude Code, and the other major agents all fall back to AGENTS.md, so stubs add maintenance for no real benefitThe goal is the minimum project-specific knowledge needed to keep an agent productive, in a single ~175-line file that's reviewable in one screen.
Validation
Content was derived from extensive empirical use of the build/test workflows over the past several months. The build-path timings were measured directly: a 6-fork comparison (three scenarios x two brain-arms) showed the Path A guidance produces a 51x speedup over the default
Build.bat-based instructions (1833 s -> 36 s for a unit-test inner loop), and 9x speedup for the functional-test loop (362 s -> 40 s). The installer path is unchanged.The
--test/--wheredistinction comes from repeated real-world bites of accidentally kicking off the full functional suite while iterating on a single test.The Readme updates were verified against the current
Build.bat(vcpkg is required,BuildGVFSForWindows.batno longer exists),Directory.Build.props(.NET 10 TFM), and an actual produced installer on disk (out\GVFS.Installers\bin\Debug\win-x64\SetupGVFS.0.2.173.2.exe).