dotnet-vertical-slice

name	dotnet-vertical-slice
audience	team
description	Scaffold vertical slice architecture with CQRS + FreeMediator, including optional Telerik Blazor UI generation. Use when creating feature-based .NET projects with command/query separation and pipeline behaviors. Do NOT use when the project uses layer-based (N-tier) architecture — this skill enforces feature folder structure and will conflict with existing layer conventions.

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

#	Principle	Description	Priority
1	Feature Isolation	Feature folder is self-contained. No imports between feature folders. Shared code lives in Common/ or Infrastructure/.	Critical
2	Handler Autonomy	Each handler owns its dependencies and logic. Duplication between handlers is acceptable and preferred over coupling.	Critical
3	Minimal Abstractions	Introduce abstractions only when three or more features demonstrate an identical, stable pattern.	High
4	Pipeline Composition	Cross-cutting concerns are composed via FreeMediator pipeline behaviors, not handler inheritance.	Critical
5	CQRS Boundary	Commands return at most an identifier or status. Queries return data and must not mutate state.	Critical
6	Request/Response Immutability	Request and response types are C# records — immutable value objects.	High
7	Explicit Dependencies	Handlers declare dependencies via constructor injection. No service locator or static helpers.	High
8	Validator Co-Location	FluentValidation validator lives in the same feature folder as its request and handler.	High
9	Endpoint Thinness	Endpoints only deserialize, mediate, and serialize. No business logic.	High
10	Test Proximity	Tests mirror the feature folder structure and test handler, validator, and endpoint as a unit.	Medium

Knowledge Base Lookups

Query	When to Call
search_knowledge("vertical slice architecture CQRS feature folder .NET")	At session start
search_knowledge("FreeMediator IRequest handler pipeline behavior .NET")	When scaffolding handlers or pipeline behaviors
search_knowledge("FluentValidation IValidator async rule .NET")	When scaffolding validators
search_knowledge("ASP.NET Core Minimal API TypedResults endpoint group")	When scaffolding endpoints
search_knowledge("EF Core DbContext dependency injection scoped lifetime")	When scaffolding DbContext
search_knowledge("C# record immutable request response DTO")	When defining request/response types

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

Anti-Pattern	Why It's Wrong	Correct Approach
Generic CRUD handler	Couples all features; base class changes ripple everywhere.	Each handler is standalone. Accept duplication.
Shared response types	Forces features to conform to one shape; blocks independent evolution.	Each feature defines its own response record.
Fat endpoint with business logic	Logic in HTTP layer can't be unit-tested without HTTP infrastructure.	Endpoints only deserialize, mediate, serialize.
Handler calling another handler	Hidden runtime coupling; breaks feature isolation.	Use INotification events or shared infrastructure services.
Organizing by technical layer	Developers touch multiple folders for one feature.	Organize by feature; each folder contains all layers for that slice.
Validation in the handler	Mixes cross-cutting logic with business logic; not reusable.	FluentValidation validator + pipeline validation behavior.
Pipeline behaviors in feature folders	Behaviors are shared infrastructure, not feature-specific.	Behaviors live in Infrastructure/Behaviors/.

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