Vertical Slice Architecture with CQRS + FreeMediator

"The whole idea is that the abstraction we use to reason about the system should be the feature, not the layer." -- Jimmy Bogard

Core Philosophy

This skill scaffolds and maintains vertical slice architecture in .NET projects using FreeMediator for CQRS and pipeline behaviors. Every feature is a self-contained unit. Layers are an implementation detail inside the slice, not a project-level organizing principle.

Non-Negotiable Constraints:

1. Feature Isolation — Each feature lives in its own folder. No feature may reach into another feature's folder for types or logic.
2. No Shared Base Handlers — Abstract base handlers and handler inheritance defeat the purpose of vertical slices. Each handler is independent.
3. Handler-Per-Feature — Every command, query, or notification gets its own handler class. A single handler must never process multiple unrelated operations.
4. Cross-Cutting via Pipeline — Validation, logging, transactions, and caching are pipeline behaviors, not base class methods.
5. CQRS Separation Is Structural — Commands mutate state; queries return data. A single handler must never both read and write.

Domain Principles Table

Knowledge Base Lookups

Search before scaffolding each new component type. Cite the source path in generated code comments.

Workflow

Scaffold proceeds in phases: SCAFFOLD (create folder and stub files) → COMMAND or QUERY (implement handler) → PIPELINE (wire behaviors) → VALIDATE (run tests, verify isolation). Use a notification (INotification) when an event must fan out to multiple handlers. When a feature both reads and writes, split it: extract the write as a command and the read as a separate query. Pipeline behaviors (validation, logging, transactions, caching) belong in Infrastructure/Behaviors/ and are registered once in DI — they must never contain feature-specific conditional logic.

Pre-Flight Checklist

• Feature has a clear, single responsibility
• Feature name describes the action, not the layer (e.g., CreateOrder, not OrderService)
• FreeMediator is registered in Program.cs
• FluentValidation is registered
• Pipeline behaviors registered in correct order
• Features/ directory exists in the project

State Block Format

<vslice-state>
step: [SCAFFOLD | COMMAND | QUERY | NOTIFICATION | PIPELINE | VALIDATE]
feature: [description]
pattern: [command | query | notification]
folder_path: [path to feature folder]
last_action: [what was just done]
next_action: [what should happen next]
blockers: [any issues]
</vslice-state>

Example:

<vslice-state>
step: SCAFFOLD
feature: CreateOrder - creates a new order from a cart
pattern: command
folder_path: src/MyApp/Features/Orders/CreateOrder/
last_action: Created feature folder structure
next_action: Define CreateOrderCommand record and CreateOrderResponse record
blockers: none
</vslice-state>

Output Templates

## Vertical Slice Session: [Feature Name]
**Pattern**: [Command | Query | Notification] | **Folder**: `Features/[Domain]/[FeatureName]/`
**Files created**: Request, Response, Handler, Validator, Endpoint
**State**: [current vslice-state block]
**Next**: [action]

AI Discipline Rules

Never create shared base handlers. Each handler is a standalone class implementing IRequestHandler<TRequest, TResponse>. If two handlers look similar, that duplication is intentional — shared abstractions between handlers re-introduce the horizontal layering that vertical slices eliminate.

One feature per folder. A feature folder contains exactly one request type, one handler, one validator (if applicable), one endpoint, and one response type. Two handlers in one folder means split it.

No cross-feature imports. Handlers must not import types from another feature folder or dispatch to another feature's handler. Use domain events (INotification) or shared infrastructure services for inter-feature communication.

Pipeline behaviors are infrastructure. A behavior with conditional logic per feature type is a design error. Use marker interfaces on the request type (e.g., ICachedQuery) to vary behavior without adding feature knowledge to the behavior class. Behaviors live in Infrastructure/Behaviors/, never inside a feature folder.

Telerik Blazor UI Generation (Conditional)

When the project uses Telerik UI for Blazor, generate Blazor pages alongside the backend slice. Pages live in the feature folder under Pages/ and dispatch commands/queries via FreeMediator. Only generate when the project has Telerik Blazor dependencies.

Extended feature folder structure:

Features/{FeatureName}/
├── Commands/Create{Entity}/, Update{Entity}/, Delete{Entity}/
├── Queries/Get{Entity}ById/, Get{Entity}List/
├── DTOs/{Entity}Dto.cs, {Entity}ListDto.cs
├── Pages/{Entity}List.razor, {Entity}Edit.razor
├── Mapping/{Entity}MappingConfig.cs (Mapster)
└── Tests/

Anti-Patterns Table

Error Recovery

Handler Not Found at Runtime

InvalidOperationException — No handler registered for [RequestType]

1. Verify the handler implements IRequestHandler<TRequest, TResponse>
2. Verify FreeMediator registration scans the correct assembly
3. Verify the handler is public, non-abstract, non-static
4. Check that the request type matches what is being sent

Validator Not Running Before Handler

Handler executes with invalid data, no ValidationException thrown

1. Verify ValidationBehavior<,> is registered as a pipeline behavior
2. Verify the validator implements AbstractValidator<TRequest>
3. Verify services.AddValidatorsFromAssemblyContaining<Program>()
4. Verify behavior order: validation must run before the handler

Feature Folder Growing Too Large

A feature folder has more than 6–8 files; handler has 200+ lines

1. Split into smaller features — separate command and query
2. If handler coordinates multiple steps, consider domain events
3. Move non-feature-specific domain logic to Common/

Circular Dependency Between Features

Feature A imports from Feature B, Feature B imports from Feature A

1. Extract shared types to Common/Models/ or the domain layer
2. Use domain events for communication
3. If truly interdependent, they are likely one feature incorrectly split

Pipeline Behavior Order Causing Side Effects

Transaction commits before validation; logging misses exceptions

1. Correct order: Logging → Validation → Transaction → (Handler)
2. Behaviors execute in registration order (outermost first)
3. Verify each behavior calls next() and does not swallow exceptions

Integration with Other Skills

• ef-migration-manager — When a slice requires schema changes, plan the migration alongside the feature. Define the entity first, then create the migration.
• tdd — Each slice is an ideal TDD unit. Write a failing handler test (RED), implement minimally (GREEN), refactor. Handler isolation makes testing straightforward without mocking half the application.
• tdd-agent — For autonomous vertical slice development: scaffold the folder, write handler tests RED, implement GREEN, refactor.

Reference Files

• Feature Folder Patterns — Folder layouts, request/response records, handler classes, validators, FreeMediator registration
• Pipeline Behaviors — Behavior implementations for validation, logging, transactions, caching
• Vertical Slice Testing — Testing patterns for handlers, validators, endpoints using xUnit and FluentAssertions