robertcoltheart · Oct 5, 2026 · Sep 21, 2026 · Sep 23, 2026 · Sep 23, 2026 · Sep 23, 2026
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -9,12 +9,9 @@ on:
 permissions:
   contents: read
 
-env:
-  DOTNET_NOLOGO: true
-
 jobs:
   build:
-    name: Build
+    name: Build, test and package
     runs-on: ubuntu-latest
 
     steps:
@@ -26,15 +23,15 @@ jobs:
       - name: Setup .NET
         uses: actions/setup-dotnet@v5
         with:
-          dotnet-version: 3.1.x
+          dotnet-version: 10.x
 
       - name: Install GitVersion
         uses: gittools/actions/gitversion/setup@v4
-        with:
-          versionSpec: 6.x
 
       - name: Calculate version
         uses: gittools/actions/gitversion/execute@v4
 
       - name: Build
-        run: ./build.sh
+        env:
+          VERSION: ${{ env.GitVersion_SemVer }}
+        run: ./build.sh build
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
@@ -9,12 +9,9 @@ permissions:
   contents: read
   id-token: write
 
-env:
-  DOTNET_NOLOGO: true
-
 jobs:
   build:
-    name: Publish
+    name: Build and publish
     runs-on: ubuntu-latest
 
     steps:
@@ -32,7 +29,7 @@ jobs:
       - name: Setup .NET
         uses: actions/setup-dotnet@v5
         with:
-          dotnet-version: 3.1.x
+          dotnet-version: 10.x
 
       - name: Install GitVersion
         uses: gittools/actions/gitversion/setup@v4
@@ -44,5 +41,6 @@ jobs:
 
       - name: Deploy
         env:
+          VERSION: ${{ env.GitVersion_SemVer }}
           NUGET_API_KEY: ${{ steps.login.outputs.NUGET_API_KEY }}
         run: ./build.sh publish
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,37 @@
+# Machine.Specificaitons Agent Guide
+**Machine.Specifications** is also known as **MSpec**.
+
+## Project architecture
+All code for MSpec lives in `src` or `tests`. Documentation is in `docs`, and logos for NuGet are in `assets`.
+
+The below source projects are in use by this project, along with test projects. You should **ignore** any other project that is not referenced in the `.slnx` file in the repo root.
+
+- `Machine.Specifications` - Meta NuGet package that references the default set of dependencies
+- `Machine.Specifications.Analyzers` - Code hints and fixes for writing tests "the MSpec way"
+- `Machine.Specifications.Core` - Core testing engine and framwork
+- `Machine.Specifications.Core.SourceGenerator` - Source generators to aid in test discovery and speed up execution
+- `Machine.Specifications.Fakes` - Interface mocking library used by MSpec
+- `Machine.Specifications.Fakes.Analyzers` - Code warnings and fixes for writing mocks using MSpec
+- `Machine.Specifications.Fakes.SourceGenerator` - Source generator that creates code for mocks in MSpec
+- `Machine.Specifications.Should` - Assertion library for MSpec
+- `Machine.Specifications.Templates` - Dotnet 'new' templates for creating test projects using MSpec
+
+All test projects end in `.Specs`, and match the libraries above.
+
+**Important:** Any projects named with the words `Fixtures` or `Runner` should be ignored as these are legacy and will be removed.
+Only use the projects referenced by the `.slnx` file in the repo root.
+
+## Dev environment tips
+- Use `dotnet build` to build the solution
+- Use `dotnet test` to build and run all the tests in the solution
+
+## Making changes
+- Make the smallest, most surgical change you can make for the feature you are writing
+- Tests should be focused and not verbose
+- Follow the naming and styling conventions of this repository
+- All changes, in general, should have accompanying tests
+- Any API surface changes should have documentation added to `docs`
+
+## PR instructions
+- Title format: Use <Title> with a brief description
+- Always run `dotnet test` before committing.
diff --git a/Directory.Build.props b/Directory.Build.props
@@ -1,7 +1,6 @@
 <Project>
 
   <PropertyGroup>
-    <TargetFramework>netstandard2.0</TargetFramework>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
     <LangVersion>latest</LangVersion>
@@ -11,7 +10,7 @@
     <Authors>Machine Specifications</Authors>
     <PackageTags>test;unit;testing;context;specification;bdd;tdd;mspec</PackageTags>
     <PackageReleaseNotes>https://github.com/machine/machine.specifications/releases</PackageReleaseNotes>
-    <PackageIcon>icon.png</PackageIcon>
+    <PackageIcon>mspec_logo.png</PackageIcon>
     <PackageProjectUrl>http://github.com/machine/machine.specifications</PackageProjectUrl>
     <RepositoryUrl>http://github.com/machine/machine.specifications</RepositoryUrl>
     <RepositoryType>git</RepositoryType>
@@ -20,8 +19,8 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <None Include="../../images/icon.png" Pack="true" PackagePath="" Visible="false" />
-    <None Include="../../README.md" Pack="true" PackagePath="/" />
+    <None Include="$(MSBuildThisFileDirectory)assets/mspec_logo.png" Pack="true" PackagePath="/" Visible="false" />
+    <None Include="$(MSBuildThisFileDirectory)README.md" Pack="true" PackagePath="/" />
   </ItemGroup>
 
 </Project>
diff --git a/Machine.Specifications.slnx b/Machine.Specifications.slnx
@@ -1,15 +1,26 @@
 <Solution>
-  <Project Path="src/Machine.Specifications.Analyzers.Tests/Machine.Specifications.Analyzers.Tests.csproj" />
-  <Project Path="src/Machine.Specifications.Analyzers/Machine.Specifications.Analyzers.csproj" />
-  <Project Path="src/Machine.Specifications.Core.Specs/Machine.Specifications.Core.Specs.csproj" />
-  <Project Path="src/Machine.Specifications.Core/Machine.Specifications.Core.csproj" />
-  <Project Path="src/Machine.Specifications.Fakes.Specs/Machine.Specifications.Fakes.Specs.csproj" />
-  <Project Path="src/Machine.Specifications.Fakes/Machine.Specifications.Fakes.csproj" />
-  <Project Path="src/Machine.Specifications.Fixtures/Machine.Specifications.Fixtures.csproj" />
-  <Project Path="src/Machine.Specifications.Runner.Utility.Specs/Machine.Specifications.Runner.Utility.Specs.csproj" />
-  <Project Path="src/Machine.Specifications.Runner.Utility/Machine.Specifications.Runner.Utility.csproj" />
-  <Project Path="src/Machine.Specifications.Runner.VisualStudio/Machine.Specifications.Runner.VisualStudio.csproj" />
-  <Project Path="src/Machine.Specifications.Should.Specs/Machine.Specifications.Should.Specs.csproj" />
-  <Project Path="src/Machine.Specifications.Should/Machine.Specifications.Should.csproj" />
-  <Project Path="src/Machine.Specifications/Machine.Specifications.csproj" />
+  <Folder Name="/Analyzers/">
+    <Project Path="src/Machine.Specifications.Analyzers/Machine.Specifications.Analyzers.csproj" />
+    <Project Path="src/Machine.Specifications.Core.SourceGenerator/Machine.Specifications.Core.SourceGenerator.csproj" Id="be1e82ac-fadb-462e-b941-de93bf7a4a41" />
+    <Project Path="src/Machine.Specifications.Fakes.Analyzers/Machine.Specifications.Fakes.Analyzers.csproj" Id="55618fdf-264c-426c-95d9-179826526efc" />
+    <Project Path="src/Machine.Specifications.Fakes.SourceGenerator/Machine.Specifications.Fakes.SourceGenerator.csproj" Id="d39b087e-b815-4431-bf51-a786ab3a740e" />
+  </Folder>
+  <Folder Name="/Core/">
+    <Project Path="src/Machine.Specifications.Core/Machine.Specifications.Core.csproj" />
+    <Project Path="src/Machine.Specifications.Fakes/Machine.Specifications.Fakes.csproj" />
+    <Project Path="src/Machine.Specifications.Should/Machine.Specifications.Should.csproj" />
+    <Project Path="src/Machine.Specifications/Machine.Specifications.csproj" />
+  </Folder>
+  <Folder Name="/Templates/">
+    <Project Path="src/Machine.Specifications.Templates/Machine.Specifications.Templates.csproj" Id="f8740762-8ccb-4b72-9ae2-2b84dcf04d0e" />
+  </Folder>
+  <Folder Name="/Tests/">
+    <Project Path="tests/Machine.Specifications.Analyzers.Specs/Machine.Specifications.Analyzers.Specs.csproj" />
+    <Project Path="tests/Machine.Specifications.Core.SourceGenerator.Specs/Machine.Specifications.Core.SourceGenerator.Specs.csproj" />
+    <Project Path="tests/Machine.Specifications.Core.Specs/Machine.Specifications.Core.Specs.csproj" />
+    <Project Path="tests/Machine.Specifications.Fakes.Analzyers.Specs/Machine.Specifications.Fakes.Analzyers.Specs.csproj" />
+    <Project Path="tests/Machine.Specifications.Fakes.SourceGenerator.Specs/Machine.Specifications.Fakes.SourceGenerator.Specs.csproj" />
+    <Project Path="tests/Machine.Specifications.Fakes.Specs/Machine.Specifications.Fakes.Specs.csproj" />
+    <Project Path="tests/Machine.Specifications.Should.Specs/Machine.Specifications.Should.Specs.csproj" />
+  </Folder>
 </Solution>
diff --git a/assets/mspec_logo.png b/assets/mspec_logo.png
diff --git a/assets/mspec_logo.svg b/assets/mspec_logo.svg
diff --git a/build.ps1 b/build.ps1
@@ -10,7 +10,7 @@ if ($null -eq (Get-Command "dotnet" -ErrorAction Ignore)) {
 Push-Location (Split-Path $MyInvocation.MyCommand.Definition)
 
 try {
-    & dotnet run ./build/build.cs -- $args
+    & dotnet ./build/build.cs -- $args
 }
 finally {
     Pop-Location

diff --git a/build.sh b/build.sh
@@ -3,7 +3,7 @@
 set -euo pipefail
 
 if which dotnet > /dev/null; then
-    dotnet run ./build/build.cs -- "$@"
+    dotnet ./build/build.cs -- "$@"
 else
     echo "error(1): Could not find 'dotnet', please install .NET SDK"
     exit 1

diff --git a/build/build.cs b/build/build.cs
@@ -4,7 +4,7 @@
 using static Bullseye.Targets;
 using static SimpleExec.Command;
 
-var version = new GitVersion();
+var version = default(string);
 
 Target("clean", () =>
 {
@@ -16,50 +16,38 @@
     }
 });
 
+Target("version", () =>
+{
+    version = Environment.GetEnvironmentVariable("VERSION");
+});
+
 Target("restore", dependsOn: ["clean"], () =>
 {
     Run("dotnet", "restore");
 });
 
-Target("build", dependsOn: ["restore"], () =>
+Target("build", dependsOn: ["restore", "version"], () =>
 {
-    Run("dotnet", "build " +
-                  "--no-restore " +
-                  "--configuration Release " +
-                  $"--property Version={version.SemVer} " +
-                  $"--property AssemblyVersion={version.AssemblySemVer} " +
-                  $"--property FileVersion={version.AssemblySemFileVer} " +
-                  $"--property InformationalVersion={version.InformationalVersion}");
+    Run("dotnet", $"build --configuration Release --no-restore --property Version={version}");
 });
 
 Target("test", dependsOn: ["build"], () =>
 {
     Run("dotnet", "test --configuration Release --no-restore --no-build");
 });
 
-Target("package", dependsOn: ["build", "test"], () =>
+Target("package", dependsOn: ["build", "test", "version"], () =>
 {
-    Run("dotnet", $"pack --configuration Release --no-restore --no-build --output artifacts --property Version={version.SemVer}");
+    Run("dotnet", $"pack --configuration Release --no-restore --no-build --output artifacts --property Version={version}");
 });
 
 Target("publish", dependsOn: ["package"], () =>
 {
     var apiKey = Environment.GetEnvironmentVariable("NUGET_API_KEY");
 
-    Run("dotnet", $"nuget push {Path.Combine("artifacts", "*.nupkg")} --api-key {apiKey} --source https://api.nuget.org/v3/index.json");
+    Run("dotnet", $"nuget push artifacts/*.nupkg --api-key {apiKey} --source https://api.nuget.org/v3/index.json");
 });
 
 Target("default", dependsOn: ["package"]);
 
 await RunTargetsAndExitAsync(args);
-
-public class GitVersion
-{
-    public string SemVer { get; } = Environment.GetEnvironmentVariable("GitVersion_SemVer") ?? "0.1.0";
-
-    public string AssemblySemVer { get; } = Environment.GetEnvironmentVariable("GitVersion_AssemblySemVer") ?? "0.1.0";
-
-    public string AssemblySemFileVer { get; } = Environment.GetEnvironmentVariable("GitVersion_AssemblySemFileVer") ?? "0.1.0";
-
-    public string InformationalVersion { get; } = Environment.GetEnvironmentVariable("GitVersion_InformationalVersion") ?? "0.1.0";
-}
diff --git a/docs/.gitkeep b/docs/.gitkeep
diff --git a/global.json b/global.json
@@ -0,0 +1,5 @@
+{
+  "test": {
+    "runner": "Microsoft.Testing.Platform"
+  }
+}
diff --git a/src/Directory.Build.props b/src/Directory.Build.props
@@ -0,0 +1,9 @@
+<Project>
+
+  <Import Project="../Directory.Build.props" />
+
+  <PropertyGroup>
+    <TargetFramework>netstandard2.0</TargetFramework>
+  </PropertyGroup>
+
+</Project>
diff --git a/src/Machine.Specifications.Analyzers.Tests/Machine.Specifications.Analyzers.Tests.csproj b/src/Machine.Specifications.Analyzers.Tests/Machine.Specifications.Analyzers.Tests.csproj
diff --git a/src/Machine.Specifications.Analyzers/Machine.Specifications.Analyzers.csproj b/src/Machine.Specifications.Analyzers/Machine.Specifications.Analyzers.csproj
@@ -4,25 +4,18 @@
     <IncludeBuildOutput>false</IncludeBuildOutput>
     <DevelopmentDependency>true</DevelopmentDependency>
     <EnforceExtendedAnalyzerRules>true</EnforceExtendedAnalyzerRules>
-    <TargetsForTfmSpecificContentInPackage>$(TargetsForTfmSpecificContentInPackage);PackageItems</TargetsForTfmSpecificContentInPackage>
   </PropertyGroup>
 
   <PropertyGroup>
     <Description>Roslyn analyzers and code fixes for Machine.Specifications</Description>
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="Microsoft.CodeAnalysis.CSharp.Workspaces" Version="4.12.0" PrivateAssets="all" />
+    <PackageReference Include="Microsoft.CodeAnalysis.CSharp.Workspaces" Version="5.0.0" PrivateAssets="all" />
   </ItemGroup>
 
   <ItemGroup>
-    <None Update="*.ps1" CopyToOutputDirectory="Always" Pack="true" PackagePath="tools" Visible="false" />
+    <TfmSpecificPackageFile Include="$(TargetPath)" Pack="true" PackagePath="analyzers/dotnet/cs" />
   </ItemGroup>
 
-  <Target Name="PackageItems">
-    <ItemGroup>
-      <TfmSpecificPackageFile Include="$(OutputPath)\$(AssemblyName).dll" PackagePath="analyzers/dotnet/cs" />
-    </ItemGroup>
-  </Target>
-
 </Project>
diff --git a/src/Machine.Specifications.Analyzers/MachineSpecStubs.cs b/src/Machine.Specifications.Analyzers/MachineSpecStubs.cs
@@ -1,4 +1,4 @@
-namespace Machine.Specifications;
+namespace Machine.Specifications;
 
 public class SetupDelegateAttribute : Attribute
 {