Sliderule

SlideRule

SlideRule is a .NET architecture checker that enforces one C# spec and renders the same rules for coding agents.

A long-lived codebase has layers, boundaries and rules. They live in a few heads, no build step checks them, and the diagrams drift. A change can cross a boundary and the build still passes. A coding agent makes that change quickly and plausibly, and it cannot see which walls are structural. SlideRule's answer is architecture-as-code. The rules become one C# spec, and the spec produces every surface this page names.

1. Enforcement. One checker passes or fails the rules at the command line, in CI, in the build and as named xUnit tests. A Claude Code hook runs the same check when an agent's turn ends.
2. Agent context. The rules render to a managed AGENTS.md block, per-directory rule cards and MCP query tools for coding agents.

SlideRule is pre-alpha. Minor versions can still change the spec API before 1.0. Status describes what exists today and the versioning rules.

Install the tool, build your solution, and check it:

dotnet tool install -g SlideRule.Cli
dotnet build MyApp.sln
sliderule check MyApp.sln

check reads the rules from a spec project, a C# class library in your solution. On a solution with no spec project yet, check stops and reports that it found none. The Getting started page makes one with the SlideRule package, and sliderule graph surveys a solution before it has any rules.

A rule is one statement:

arch.Rule("layering/domain-independent")
    .Enforce(domain.MustNotReference(application, infrastructure, api))
    .Because("The Domain holds the quote and rate model the rest of the subsystem is built on; it stays free of the layers that depend on it so it can be reasoned about and tested on its own.")
    .Fix("Move the dependency out of Domain: define an interface here and implement it in the outer layer that needs it.");

That is the whole rule. It has an ID, a posture, a constraint, a reason and a fix. Here the posture is Enforce, and domain and the three layers it must not reference are declared earlier in the spec by namespace pattern. The rule is committed in the clean-architecture example, and CI keeps check green against the codebase it governs. A rule can also cite the page its reason rests on and name a type to copy, as Writing specs shows.

When an agent breaks a rule

Rules like the one above govern this repository too. One of them keeps the CLI off stdout, because the MCP server speaks JSON-RPC over that channel. Suppose an agent adds a progress printer to the CLI and reaches for Console.WriteLine. When it tries to end its turn, the Claude Code Stop hook in hooks/ runs check over the working tree. The rule goes red, and the hook blocks the stop with this report on the agent's stderr:

FAIL cli/no-stdout — The Host layer must not use `Console.Out`, `Console.Write()` or `Console.WriteLine()`.
  because: Stdout is a protocol channel here — the MCP server speaks JSON-RPC over it and CLI output flows through System.CommandLine's console — so a direct Console write corrupts the wire and is invisible to the in-process tests.
  citation: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#stdio
  fix: Write CLI output through the command's InvocationConfiguration console; route server diagnostics to the logger or Console.Error.
  subject: 194 types, 1 generated
  src/SlideRule.Cli/Rendering/ProgressPrinter.cs:10 — SlideRule.Cli.Rendering.ProgressPrinter uses System.Console.WriteLine()
  src/SlideRule.Cli/Rendering/ProgressPrinter.cs:15 — SlideRule.Cli.Rendering.ProgressPrinter uses System.Console.WriteLine()

The report gives the rule, its reason, its citation, the fix and each offending line. The subject: line appears only when a rule's subject includes generated code, here 1 of its 193 types. The agent routes the output through the command's console instead, and the next stop is clean.

The SlideRule on itself page shows this repository's own spec on the other surfaces too, from the prose it renders to code scanning and the graph. It also explains how every excerpt on both pages is held to its source.

The four postures

Every rule has one of the first two, and every scope one of the last two.

Migrate is for a rule the code does not keep yet. sliderule baseline init records the rule's current violations, and any new violation fails from then on. As sites are fixed, sliderule baseline accept-reductions shrinks the baseline, and once it is empty, status suggests promoting the rule to Enforce.

A scope marks code that needs care. Its dragons are notes on why the code is fragile and how to call into it. render puts them on a card in the scope's directory. Quarantine also records the references into the scope on a baseline, and fails any new one except through the surface BoundaryOnlyVia names. Both kinds of scope warn when a change touches them, given check --diff-base <ref>. The Writing specs page shows each posture in code, and Operating SlideRule follows a ratchet from capture to promotion.

The three postures after Enforce each answer a way a coding agent goes wrong on an established codebase. Enforce is the law the code already keeps, and a change that crosses it fails wherever the check runs. The Meridian example walks three of those ways on real output.

• An agent copies the majority pattern, the statistical prior. Six of Meridian's eight controllers open a SqlConnection, so inline SQL reads as house style and an agent writes its next controller the same way. Migrate answers it. The rendered context calls that pattern debt, in words the agent reads before it writes.
• An agent tidies away a gateway, the helpful refactor. A public type inside a module invites a direct call that skips the gateway in front of it. A Quarantine scope makes the gateway the only sanctioned way in.
• An agent corrects structural weirdness. A check-digit table that skips values looks like a bug, and making it contiguous breaks every real container number. The dragons on a Quarantine or Caution scope answer it. The card on that scope's directory explains what the code does, which part is structural, and how to call in.

What one spec produces

Each target below reads the same model. Every violation report gives the rule ID, the generated rule sentence, the reason and the exact file:line. A rule's fix, citation and exemplar appear there too when it has them.

The adapter's failure text is byte-identical to the CLI's. The two share one renderer, and a product test pins them equal. The managed block plus sliderule explain are also the generated architecture documentation, written for agents first and readable by people. The SlideRule on itself page shows the gate that keeps it current.

The Coding agents page explains which agents read the AGENTS.md files and use each surface. It also gives the line a repository with its own CLAUDE.md adds for Claude Code.

Compared with ArchUnitNET and NetArchTest

NetArchTest and ArchUnitNET run architecture rules inside your unit tests, and they are good at it. SlideRule moves the rules out of test code into one spec and renders every surface above from it.

The grammar comes from surveying that prior art, and GRAMMAR.md records each divergence. Constraints negate in the verb (MustNotReference), following ArchUnitNET. ArchUnit's FreezingArchRule accepts a rule's current violations as a baseline, and here that is Migrate with its counted baseline. Quarantine applies the same ratchet to a region of code, counting the references into it today and failing any new one that bypasses its sanctioned surface.

Because is mandatory. A rule without one is an invalid spec, and check stops before it evaluates anything, reporting every spec error in one pass. Even the predicate escape hatch, Must(condition, description:), does not compile without its description. Every reason ships to your agents in the rendered context. In the Interchange example, each of the 12 rules has a Citation naming the learn.microsoft.com page its reason rests on. Of those 12, 9 come from a shared rule pack, an ordinary class library of static methods. The pack owns the citation, and the spec picks the posture. That pack is a worked example in this repository rather than a published package. A pack of your own is a class library in your repository, with no registry to depend on.

Starting on a codebase that already exists

SlideRule is built for long-lived, business-critical .NET codebases, where the architecture is real but lives in a few people's heads. You can write the first rules yourself or have an agent draft them through the derive_spec prompt, as Getting started shows. You review every rule the agent proposes, and accept, edit or drop it before anything is committed.

What it handles

Real solutions are rarely one shape. Each row is one case and what the checker does with it. The changelog records the release each landed in.

A project in a language the checker does not read makes the model smaller. The check, status and graph documents list it with the reason, and the run still answers. The survey, sliderule graph, names the framework a multi-targeting project's shared types follow. It also lists every type name that two projects, or a project and a package, both declare. .Authored() on a rule's subject keeps the rule off generated code.

After an edit, a check loads only the projects it re-extracts and the projects they reference. That is the check hook runs when an agent's turn ends, and its output is byte for byte what a cold run prints. The command-line reference lists the cases where such a check loads the whole solution instead.

.NET Framework

The tool runs on .NET 10. The codebase it checks does not have to, and neither does the spec that governs it.

A spec project can target net48 and compile at that framework's default language level, C# 7.3. It references the same netstandard2.0 SlideRule package every other spec does, and the CLI loads the built DLL in an isolated load context. A typeof() reference to a product type works while that type and everything it depends on stay inside netstandard2.0. Anything past that, such as a .NET Framework type with no .NET counterpart, is named by a namespace pattern. A filter such as DerivedFrom also takes the type's full name as a string. Neither needs an assembly load.

Old project files load too. A non-SDK-style Framework project is the kind in the 2003 MSBuild XML namespace, with explicit <Reference> items and a hand-maintained AssemblyInfo.cs. It loads through the .NET Framework build host Roslyn ships and reports at file:line like anything else:

FAIL data-access/no-inline-sql — Types in `Classic.*` must not reference types in `System.Data.*`.
  Classic.Billing/BillingCalculator.cs:10 — Classic.Billing.BillingCalculator references System.Data.SqlClient.SqlConnection

check --binlog replays a binary log from a real build of the solution on the same machine, in place of its own design-time build. The log can come from .NET Framework MSBuild.exe. Replaying the log and opening the workspace directly produce byte-identical output.

Loading a non-SDK-style project and replaying a log from .NET Framework MSBuild.exe both need Windows, because that is where the Framework build host and MSBuild.exe come from. The command-line reference explains which Visual Studio or Build Tools install the tool takes, and how to choose one. A net48 spec project has no such requirement and builds anywhere.

Examples

Six worked examples in examples/ share one fictional freight-forwarding company. Four are solutions. CI builds each one, keeps check green against the committed tree, and runs render --check to prove every file a render writes under examples/ current:

• Enforce-only clean architecture: the greenfield quoting subsystem. Nine rules govern a four-layer clean architecture, and every rule runs as a named xUnit test.

• Three of the four postures on one codebase: a mid-migration monolith. It has the law, three ratchets and their burndown, and one quarantined scope.

• Module isolation as law: a modular monolith. Every module directory has its own rendered rule card, and one module is quarantined behind its facade.

• Microsoft guidance, enforced and cited: the cookbook page. It shows the canon sentence, spec excerpt, and real violation, rule by rule.

The other two walk a flow on the Meridian monolith, with captured output:

• Day-one adoption on an existing codebase: the full derive flow, every step a real command with real output.

• The agent loop, closed by a hook: the storyboard for the loop above, walked beat by beat. It also has the paste-in hook config.

Installing

The CLI is a .NET global tool, and the machine that runs it needs a .NET 10 SDK. The requirements in Getting started cover the rest, including an install inside a repository whose global.json pins an SDK below 10.

The command-line reference covers each command's options and exit codes, and what a run does when a project fails to load or a solution filter narrows it.

The command is sliderule. Four lockstep-versioned packages make up a release, and a spec project references SlideRule at the version sliderule --version prints:

Operating SlideRule explains how to keep the tool and the packages on one version as releases come out.

Connecting an MCP client

An MCP client launches the same tool with the mcp command; the server speaks stdio. The .mcp.json shape:

{
  "mcpServers": {
    "sliderule": {
      "command": "sliderule",
      "args": ["mcp", "MyApp.sln"]
    }
  }
}

A config generated from the MCP registry passes no solution. The server then finds one as every command does, from a committed sliderule.json or by walking up from its working directory. Where it cannot, bind one at install time. The Coding agents page covers binding, the tools and the derive_spec prompt.

Documentation

• Getting started: the first run, from no spec to a green check.

• Writing specs: the parts of a rule, the postures and scopes, and what a rule covers.

• Coding agents: the context files, the MCP server and the hook.

• Operating SlideRule: CI, ratchets, the build analyzer, upgrades and failed runs.

• Command-line reference: every command, option, exit code and document.

• GRAMMAR.md: the language reference.

• SlideRule on itself: this repository's own spec, checked and rendered over its own code.

Status

SlideRule 0.1.0 is the first release. Every surface on this page exists today, and all four postures evaluate. SlideRule on itself shows these surfaces running over this repository's own code, and CI uploads that check --sarif run to code scanning. The build analyzer is the exception, proven on the four example solutions instead. The fluent surface can still move; GRAMMAR.md is its spec, and its vocabulary table is generated from the shipped API.

The packages version in lockstep under 0.x semver. Every spec-API change is listed under Breaking in the changelog and ships without a shim, and a patch version makes none. The JSON documents have a schemaVersion that moves when their shape does, and the human-readable reports can gain lines in any release. Tests pin the public surface of SlideRule and SlideRule.Xunit, the two packages a consumer compiles against. That surface is the spec language and the adapter's test base class, and the engine behind them is internal. The surface is also compared with the previous release at pack time, so a change there cannot slip in by accident.

Building

dotnet build SlideRule.slnx
dotnet test SlideRule.slnx

CONTRIBUTING.md covers the rest of working on SlideRule itself.

License

MIT