Fuse
AGENTS.md37 starsChanged 18 days agoApache-2.0View on GitHub
Fuse is one .NET tool (fuse) that keeps a warm Roslyn compilation of a repository and gives coding agents the errors their edits introduced, affected-test runs, and compact build output, through agent hooks and a three-tool MCP server. README.md describes the product, site/docs/index.html indexes the documentation, and site/docs/how-it-works.html describes how it works. Tests generate real git repositories and restore them, so the first run needs NuGet access.
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository2 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- site/llms.txtllms.txt
The file
We split this AGENTS.md into the rules it gives an agent
1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 44
No configuration knobs. A behavior that needs a setting is a behavior to decide, not to expose.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Fuse: contributor and agent guide
Fuse is one .NET tool (fuse) that keeps a warm Roslyn compilation of a repository and gives coding agents the errors their edits introduced, affected-test runs, and compact build output, through agent hooks and a three-tool MCP server. README.md describes the product, site/docs/index.html indexes the documentation, and site/docs/how-it-works.html describes how it works.
Layout
src/Fuse: the only product project, packed as theFusedotnet tool. Its namespaces are layers; site/docs/architecture.html says which may use which, in what order to read them, and what its words mean. From the top:Program.cs: parses the command line and picks a surface or the engine.Hooks/,Mcp/,Harnesses/:fuse hook,fuse mcp, andfuse initwith one class per harness.Operations/: the check, test and build operations shared by every surface, and their output.Engine/Client/: finds, starts and calls the engine.Protocol/: the pipe's request and response records.Engine/: the engine process: pipe server, request routing, preload, mapping results toProtocol.Check/,Testing/: the check algorithm and test selection, each with aModel/folder read first.Changes/: which declarations differ between HEAD and the working tree.Workspace/: the current and baseline Roslyn solutions.Repo/,Graph/,Dotnet/: git and the working tree, MSBuild evaluation, child processes and their output parsers.Paths/,Failures/,Telemetry/:RepoRootandRepoPath,FuseExceptionandErrorCode,PhaseTimesandEngineLog.
tests/Fuse.Tests: unit, engine and process tests over generated fixture repositories, andArchitecture/NamespaceDependencyTests, which fails the build when a namespace uses one it may not.evals/Fuse.Evals: the correctness, selection and latency evals, and the chart renderer; results inevals/results.site/: the website at fuse.codes, static HTML deployed frommainwith no build step. Cloudflare Workers serves it as static assets, configured bywrangler.jsoncat the repository root.index.htmland404.html: the home page and the not-found page.docs/: all documentation, one page per file, withindex.htmlas the overview.assets/:style.css, the icons andog.png(copies of files in the rootassets/), andbenefits.svg, whichdotnet run --project evals/Fuse.Evals -c Release -- chartrenders fromevals/results.
assets/: the logo and social images, in the Litenova Solutions family: the square frame on a 240 grid around four lines of build output, 14 thick, each shorter than the last, the last one saffron; a 20 cut for icons of 48 pixels and below.logo/holds the SVG sources (mark, lockups, icons, avatar) andfavicon.ico,logo/png/their renders at the sizes in their names, andsocial/the Open Graph image and the GitHub social preview, both in the site's style. The site serveslogo/icon-rounded-small.svgassite/assets/fuse-icon.svg, and the package iconsrc/Fuse/icon.pngislogo/png/icon-128.png. Nothing in it is deployed._headersand_redirects: response headers, and redirects from addresses that moved.robots.txt,sitemap.xmlandllms.txt: for crawlers and agents.
- Documents outside
site/docs/: only the files GitHub and the release workflow read, the README,CONTRIBUTING.md,SECURITY.mdandCHANGELOG.mdin the root, andCODE_OF_CONDUCT.mdandSUPPORT.mdin.github/.
Build, test, format
dotnet build Fuse.slnx -c Release
dotnet test --solution Fuse.slnx -c Release --no-build
dotnet format Fuse.slnx --verify-no-changesTests generate real git repositories and restore them, so the first run needs NuGet access.
Rules
- The product answers from the working tree as it is on disk, compared with HEAD. Never report an error that already existed at HEAD as introduced.
- A hook must never break the agent's session:
fuse hookreports only introduced errors and missing restores, and every internal failure exits 0 with no output and logs tohook.login the state directory. - No configuration knobs. A behavior that needs a setting is a behavior to decide, not to expose.
- The engine never writes the working tree and never runs
dotnet restoreon its own. Its state (logs, shadow test output) lives in the user's local application data, never in the repository. - The pipe protocol needs no versioning by hand: every request carries
EngineVersion.Build, and an engine from another build restarts. - Child processes take argument lists, never shell strings. Variable-length lists (paths, filters) are bounded or chunked.
- Evals run on GitHub Actions, never on a developer's machine: add the
evalslabel to the pull request (latency and analyzers), or start the Evals workflow from the Actions tab with the repositories and suites to run. Commit the result files from the run's artifacts. A local machine runs other work and differs from the runners, so its numbers are not comparable and are never quoted. - Iterate with targeted runs, through the GitHub CLI. While a change is in progress, rerun only what it can affect:
gh workflow run ci.yml --ref <branch> -f filter="--filter-class <class> ..." -f os='["ubuntu-latest"]'for the test classes it touches, andgh workflow run evals.yml --ref <branch> -f repos='["<repo>"]' -f suites='["<suite>"]'(with-f latency_parts='["main"]'for one latency part) for the eval that measures it. The full CI run and the full eval set run once the targeted runs pass. A failing job's engine logs are in its artifact (engine-logs/), so read them before running it again. When a run is slow, split it: rebalance the CI shards in.github/workflows/ci.ymland the truth shards inevals.ymlso no job waits on one long tail, within the 20 concurrent jobs the repository gets. - Numbers quoted in docs come from files in
evals/results. Counts are quoted exactly. Times, sizes and percentages are rounded half up for display: seconds to two decimals below 10 s and one decimal from 10 s, milliseconds and megabytes to whole numbers, percentages to at most one decimal. Each benchmark table names the result files it comes from. - A file holds one type plus its private helpers.
- Layers follow site/docs/architecture.html. A new namespace gets a row in its dependency table and in
NamespaceDependencyTestsin the same change. - One word per concept, in code, output, comments and docs: the vocabulary in site/docs/architecture.html decides. That means no synonyms, not repeating the full phrase every time: once a thing is named, "it" or a short name is fine. Text says what is true now, in plain sentences, with keyboard punctuation only. Docs address the reader as "you" and explain a mechanism on one page, which other pages link to rather than repeat.
- New tests must run: confirm the test count went up.
- A commit an agent helped write carries an
Assisted-by:trailer, and itsSigned-off-by:line is the person's, as site/docs/ai-policy.html says. - Every documentation page carries the same header, sidebar and footer. A new page adds its link to the sidebar of every page, its URL to
site/sitemap.xmlandsite/llms.txt, and its pager links to its neighbors. Pages link each other by their canonical address, without.html(commands#fuse-check,../), which fuse.codes serves directly; a.htmllink costs a redirect. A page's title, description, Open Graph and Twitter tags and structured data say the same thing, and itsdateModifiedand sitemaplastmodchange with its content. A page opens with who it is for and what they do after it, and explains each term where it first appears.
Releases
The version lives in Directory.Build.props. A release is a vX.Y.Z tag matching it; the publish workflow checks the match. A release description is scoped to one baseline, named in the text: a major and its first preview carry the full changelog for that major, and every later release compares against the immediately previous version only. CHANGELOG.md keeps the cumulative history, and the release workflow reads its section as the release notes. Each release also gets a section with its upgrade steps in site/docs/changelog.html, and its row in that page's supported versions table, in the same change.
A changelog is read by a user deciding whether to upgrade and by one checking what changed afterward. Follow the changelog guidance in ~/.config/agent-rules/writing/technical.md. For Fuse, name the immediately previous version at the top, put required upgrade actions near the top, list only the groups that have entries, and end an entry with its issue link and a link to the page that explains the details when one exists. Keep CHANGELOG.md and site/docs/changelog.html synchronized in substance; the site section adds the upgrade steps. Implementation detail belongs in an entry only when it explains observable behavior, a limit or an action the reader must take.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

