♻️ Refactor specifications for better discovery (#607)

📄 Refactor specifications: consolidate into aggregate classes with factory methods for improved discoverability and reduced file count

Author: danielmackay

docs/adr/20260221-use-aggregate-specification-classes-with-factory-methods.md

@@ -0,0 +1,70 @@
+# Use Aggregate Specification Classes with Factory Methods
+
+- Status: accepted
+- Deciders: Daniel Mackay, Anton Polkanov
+- Date: 2026-02-21
+- Tags: domain, specifications
+
+## Context and Problem Statement
+
+The previous approach created a separate class file per specification (e.g., `TeamByIdSpec`, `HeroByIdSpec`). As the number of specifications grows, this leads to file proliferation and poor discoverability — developers must know the exact class name to find a specification, and there is no single place to browse all available specifications for a given aggregate.
+
+## Decision Drivers
+
+- Improve discoverability of specifications per aggregate
+- Reduce the number of files in the Domain layer
+- Keep specifications co-located with their aggregate
+
+## Considered Options
+
+1. One class per specification (previous approach)
+2. Single class per aggregate with static factory methods
+
+## Decision Outcome
+
+Chosen option: **Option 2 - Single class per aggregate with static factory methods**, because it groups all specifications for an aggregate in one discoverable location and reduces file count without sacrificing clarity.
+
+The class itself extends `SingleResultSpecification<T>` and static factory methods configure instances via `spec.Query`, following a consistent naming convention (`{Aggregate}Spec`).
+
+```csharp
+public sealed class HeroSpec : SingleResultSpecification<Hero>
+{
+    public static HeroSpec ById(HeroId heroId)
+    {
+        var spec = new HeroSpec();
+        spec.Query.Where(h => h.Id == heroId);
+        return spec;
+    }
+}
+```
+
+Usage:
+
+```csharp
+dbContext.Heroes.WithSpecification(HeroSpec.ById(heroId)).FirstOrDefault();
+```
+
+### Consequences
+
+- ✅ All specifications for an aggregate live in one file (`HeroSpec.cs`, `TeamSpec.cs`)
+- ✅ Intention-revealing factory method names (`HeroSpec.ById(...)`)
+- ✅ IntelliSense on `HeroSpec.` surfaces all available specifications immediately
+- ✅ No inner classes or extra indirection needed
+- ❌ Slightly more boilerplate per specification (factory method vs constructor-only class)
+
+## Pros and Cons of the Options
+
+### Option 1 - One class per specification
+
+- ✅ Minimal boilerplate for a single specification
+- ❌ File proliferation as aggregate queries grow
+- ❌ No single place to discover all specifications for an aggregate
+- ❌ Class names must be memorised to find the right specification
+
+### Option 2 - Single class per aggregate with static factory methods
+
+- ✅ All specifications browsable via IntelliSense on the aggregate's spec class
+- ✅ Fewer files in the Domain layer
+- ✅ Consistent naming convention (`{Aggregate}Spec`)
+- ✅ No inner class boilerplate
+- ❌ Slightly more verbose per specification entry

src/AGENTS.md

@@ -7,7 +7,7 @@ This file covers conventions, migrations, and all coding patterns for the Domain
 - **No AutoMapper** - Use manual mapping with `Select()` projections
 - **Strongly-typed IDs** - All entities use Vogen `[ValueObject<Guid>]`
 - **Factory methods** - Create aggregates via static `Create()` methods, not constructors
-- **Specifications** - Query logic in Domain layer (e.g., `TeamByIdSpec`)
+- **Specifications** - One class per aggregate in Domain layer (`{Aggregate}Spec`), with static factory methods per query
 - **FluentValidation** - Validators in same folder as Command/Query
 - **Awesome Assertions** - Use `Should()` syntax in tests
 - **Code generation** - Reference existing code in `src/Application/UseCases/Heroes/` as patterns
@@ -136,3 +136,30 @@ Use `ErrorOr<T>` for commands, not exceptions. Handle with `.Match()` at the HTT
 ```csharp
 result.Match(success => TypedResults.Ok(success), CustomResult.Problem);
 ```
+
+## Specifications
+
+Location: `src/Domain/{Feature}/{Aggregate}Spec.cs`
+
+Each aggregate has a single specification class that extends `SingleResultSpecification<T>`. Static factory methods build and configure instances. This groups all queries for an aggregate in one place for discoverability.
+
+```csharp
+// src/Domain/Heroes/HeroSpec.cs
+public sealed class HeroSpec : SingleResultSpecification<Hero>
+{
+    public static HeroSpec ById(HeroId heroId)
+    {
+        var spec = new HeroSpec();
+        spec.Query.Where(h => h.Id == heroId);
+        return spec;
+    }
+
+    // Add further factory methods here as new queries are needed
+}
+```
+
+Usage in commands:
+
+```csharp
+dbContext.Heroes.WithSpecification(HeroSpec.ById(heroId)).FirstOrDefault();
+```

src/Application/UseCases/Teams/Commands/AddHeroToTeam/AddHeroToTeamCommand.cs

@@ -15,14 +15,14 @@ public async Task<ErrorOr<Success>> Handle(AddHeroToTeamCommand request, Cancell
         var heroId = HeroId.From(request.HeroId);
 
         var team = dbContext.Teams
-            .WithSpecification(new TeamByIdSpec(teamId))
+            .WithSpecification(TeamSpec.ById(teamId))
             .FirstOrDefault();
 
         if (team is null)
             return TeamErrors.NotFound;
 
         var hero = dbContext.Heroes
-            .WithSpecification(new HeroByIdSpec(heroId))
+            .WithSpecification(HeroSpec.ById(heroId))
             .FirstOrDefault();
 
         if (hero is null)

src/Application/UseCases/Teams/Commands/CompleteMission/CompleteMissionCommand.cs

@@ -12,7 +12,7 @@ public async Task<ErrorOr<Success>> Handle(CompleteMissionCommand request, Cance
     {
         var teamId = TeamId.From(request.TeamId);
         var team = dbContext.Teams
-            .WithSpecification(new TeamByIdSpec(teamId))
+            .WithSpecification(TeamSpec.ById(teamId))
             .FirstOrDefault();
 
         if (team is null)

src/Application/UseCases/Teams/Commands/ExecuteMission/ExecuteMissionCommand.cs

@@ -16,7 +16,7 @@ public async Task<ErrorOr<Success>> Handle(ExecuteMissionCommand request, Cancel
     {
         var teamId = TeamId.From(request.TeamId);
         var team = dbContext.Teams
-            .WithSpecification(new TeamByIdSpec(teamId))
+            .WithSpecification(TeamSpec.ById(teamId))
             .FirstOrDefault();
 
         if (team is null)

src/Application/UseCases/Teams/Events/PowerLevelUpdatedEventHandler.cs

@@ -26,7 +26,7 @@ public async Task Handle(PowerLevelUpdatedEvent notification, CancellationToken
         }
 
         var team = dbContext.Teams
-            .WithSpecification(new TeamByIdSpec(hero.TeamId.Value))
+            .WithSpecification(TeamSpec.ById(hero.TeamId.Value))
             .FirstOrDefault();
 
         if (team is null)

src/Domain/Heroes/HeroSpec.cs

@@ -0,0 +1,12 @@
+namespace SSW.CleanArchitecture.Domain.Heroes;
+
+// For more on the Specification Pattern see: https://www.ssw.com.au/rules/use-specification-pattern/
+public sealed class HeroSpec : SingleResultSpecification<Hero>
+{
+    public static HeroSpec ById(HeroId heroId)
+    {
+        var spec = new HeroSpec();
+        spec.Query.Where(h => h.Id == heroId);
+        return spec;
+    }
+}

src/Domain/Heroes/TeamByIdSpec.cs

@@ -0,0 +1,15 @@
+namespace SSW.CleanArchitecture.Domain.Teams;
+
+// For more on the Specification Pattern see: https://www.ssw.com.au/rules/use-specification-pattern/
+public sealed class TeamSpec : SingleResultSpecification<Team>
+{
+    public static TeamSpec ById(TeamId teamId)
+    {
+        var spec = new TeamSpec();
+        spec.Query
+            .Where(t => t.Id == teamId)
+            .Include(t => t.Missions)
+            .Include(t => t.Heroes);
+        return spec;
+    }
+}