codewithmukesh/dotnet-claude-kit

# API Versioning

## Core Principles

1. **Version from day one** — Adding versioning later is painful. Start with a version in the URL even if you only have v1.
2. **URL segment versioning is the default** — `/api/v1/orders` is the most discoverable and cache-friendly strategy.
3. **Never break existing versions** — Add a new version for breaking changes. Deprecate the old version with a timeline.
4. **Version the API, not individual endpoints** — All endpoints in a version group share the same version number.

## Patterns

### Setup with Asp.Versioning

```csharp

# /arch-check

## What

Verifies that the code still matches the architecture it claims to have.
Architectures rot through small, individually-reasonable changes — a Domain
project that gains an EF Core reference, a module that reaches into a sibling's
internals, an endpoint defined outside the host. This workflow catches the rot
using project-graph and dependency analysis, not file-by-file reading.

Output: a violation report with severity, file:line evidence, and the concrete
fix — or a clean conformance pass.

## When

# Architecture Advisor

## Core Principles

1. **Ask before recommending** — Never prescribe an architecture without understanding the project. Run the questionnaire first to gather context about domain, team, lifetime, and constraints.
2. **Right-size the architecture** — The best architecture is the simplest one that handles the project's actual complexity. CRUD apps do not need DDD. Startups do not need Clean Architecture. Match complexity to real requirements, not aspirations.
3. **Architecture is not permanent** — Every architecture has an evolution path. Start simple and add structure when complexity demands it. Document the decision so the team knows when to evolve.
4. **Four supported architectures** — dotnet-claude-kit provides first-class patterns for Vertical Slice Architecture (VSA), Clean Architecture (CA), DDD + Clean Architecture, and Modular Monolith. Each has specific strengths and trade-offs.

## The Architecture Questionnaire

Before recommending an architecture, ask questions across these 6 categories. Not every question applies to every project — skip irrelevant ones.

### Category 1: Domain Complexity

# .NET Aspire

## Core Principles

1. **AppHost orchestrates; it is never deployed itself** — Aspire's core job is the local development experience: starting services, databases, and message brokers together. Modern Aspire also generates deployment assets (`aspire publish` for docker-compose/Kubernetes manifests, `aspire deploy` for Azure Container Apps) — but the AppHost process itself stays a dev/build-time tool, not a production runtime.
2. **Service defaults are your baseline** — The `ServiceDefaults` project configures OpenTelemetry, health checks, and resilience for all services in one place.
3. **Use Aspire integrations** — Aspire has built-in integrations for PostgreSQL, Redis, RabbitMQ, SQL Server, and more. They handle connection strings, health checks, and tracing automatically.
4. **The dashboard is your observability tool** — Use the Aspire dashboard for local development tracing, logging, and metrics instead of setting up Seq/Grafana locally.

## Patterns

### AppHost Configuration

```csharp

# Authentication & Authorization

## Core Principles

1. **Use ASP.NET Identity for user management** — Don't build your own user store. Identity handles password hashing, lockout, two-factor, email confirmation, and (since .NET 10) built-in passkey/WebAuthn support for passwordless login.
2. **JWT for APIs, cookies for web apps** — APIs use Bearer token authentication; Blazor/MVC apps use cookie authentication.
3. **Policy-based authorization over roles** — Policies are testable, composable, and more expressive than `[Authorize(Roles = "Admin")]`.
4. **Never store secrets in code** — Use user secrets in development, Azure Key Vault / environment variables in production.

## Patterns

### JWT Bearer Authentication

```csharp

# /build-fix

## What

The kit's autonomous iteration-loop skill. It drives a broken `dotnet build`
(or failing `dotnet test`) to green by looping: run, parse failures,
categorize by root cause, apply targeted fixes, re-run. It repeats until
green or a guard fires — the same way an experienced developer works through
a wall of red, but with hard limits that stop it from thrashing.

This is not a single-pass fix. It handles cascading errors where fixing one
issue reveals the next.

## When

# Caching

## Core Principles

1. **HybridCache is the default** — .NET 9+ introduced `HybridCache` as the unified caching abstraction. It combines in-memory (L1) and distributed (L2) caching with stampede protection. See ADR-004.
2. **Cache reads, not writes** — Cache GET operations. Invalidate on mutations. Never cache POST/PUT/DELETE responses.
3. **Output caching for entire responses** — When the full HTTP response can be cached (public APIs, static data), use output caching middleware.
4. **Set explicit TTLs** — Every cached item needs an expiration. No unbounded caches.

## Patterns

### HybridCache (Recommended Default)

```csharp

# /checkpoint

## What

A quick mid-session save that banks the known-good state in two moves:

1. **Descriptive git commit** — stage relevant changes and commit with a
   message that summarizes the work.
2. **Brief handoff note** — write `.claude/handoff.md` so a resumed session
   (or you, after a botched refactor) knows exactly where things stand.

Checkpoint is the mid-session save; `/wrap-up` is the end-of-session ritual.
Checkpoint commits and jots a note, then keeps working. Wrap-up does the full
handoff plus learning extraction into `MEMORY.md`.

# CI/CD

## Core Principles

1. **Pipeline as code** — YAML pipelines committed to the repo. No click-ops in the UI.
2. **Fast feedback** — Build and test on every push. Cache NuGet packages. Fail fast.
3. **Build once, deploy many** — Build the artifact once, promote it through environments (dev → staging → production).
4. **Never skip tests** — Tests gate the pipeline. No deployment without passing tests.

## Patterns

### GitHub Actions — Build + Test

```yaml

# Clean Architecture

## Core Principles

1. **Dependency inversion is the foundation** — All dependencies point inward. Domain has zero project references. Application references only Domain. Infrastructure references Application and Domain. Api references all but depends on abstractions. The compiler enforces this via project references.
2. **Domain owns the rules** — Business logic lives in the Domain layer as entity methods, domain services, or specifications. The Domain layer has no knowledge of databases, HTTP, or any framework — only pure C# and .NET primitives.
3. **Use cases are the unit of work** — Each use case (command or query) is a single class in the Application layer. It orchestrates domain objects, persists through abstractions, and returns a result. No "service" classes with 20 methods.
4. **Infrastructure is a plugin** — EF Core, external APIs, email senders, file storage — all live in Infrastructure and implement interfaces defined in Application or Domain. Swap implementations without touching business logic.
5. **The API layer is thin** — Endpoints map HTTP to use cases and use cases to HTTP responses. No business logic in endpoints.

## Patterns

### Project Layout

# /code-review — MCP-Powered Code Review

## What

Performs a multi-dimensional code review combining Roslyn MCP analysis with
structured manual review. Effort follows the 80/20 rule: the 20% of code that
causes 80% of incidents (data access, security, concurrency, integration
boundaries) gets thorough review; style and formatting are left to tooling.

Review dimensions: **Correctness** (logic, edge cases, null handling, async
pitfalls), **Security** (auth gaps, injection, secrets, CORS), **Performance**
(N+1, allocations, missing cancellation), **Architecture compliance** (layer
violations, boundary breaches), **Test coverage** (behavior tests for changed
types).

# Configuration

## Core Principles

1. **Options pattern always** — Never read `IConfiguration` directly in services. Bind configuration sections to strongly-typed classes with validation.
2. **Validate on startup** — Use `ValidateDataAnnotations()` and `ValidateOnStart()` to catch misconfiguration before the first request.
3. **Secrets never in source** — Use user secrets in development, Azure Key Vault or environment variables in production. Never commit secrets to git.
4. **Configuration layering** — `appsettings.json` → `appsettings.{Environment}.json` → environment variables → user secrets. Later sources override earlier ones.

## Patterns

### Options Pattern

```csharp

# Container Publishing (No Dockerfile)

## Core Principles

1. **No Dockerfile needed** — The .NET 10 SDK builds OCI-compliant container images directly from `dotnet publish /t:PublishContainer`. No Dockerfile to write or maintain.
2. **Chiseled images for production** — Use `noble-chiseled` base images: no shell, no package manager, 7 Linux components vs 100+. Smallest attack surface.
3. **Non-root by default** — .NET 10 container images run as the `app` user automatically. Never override to root in production.
4. **Configuration in the .csproj** — All container settings are MSBuild properties, versioned with your project. No separate files to drift.

## Patterns

### Minimal Container Publish

No project file changes needed. Just publish:

# Convention Learner

## Core Principles

1. **Observe before enforcing** — Never impose conventions without first analyzing the existing codebase. A project with 200 `internal sealed class` handlers should not get a new `public class` handler. Detect first, then match.
2. **Project conventions override generic rules** — If the project uses `*Service` instead of `*Handler`, follow the project's convention even if the kit default is different. Explicit `.editorconfig` and `Directory.Build.props` rules always win.
3. **Use MCP tools for analysis** — `get_public_api` reveals naming patterns, `get_project_graph` shows structure conventions, `detect_antipatterns` tracks quality trends. Tools provide objective data; file reads provide confirmation.
4. **Document findings** — After detecting conventions, suggest adding them to the project's CLAUDE.md. Undocumented conventions are lost when the original developers leave.
5. **Consistency over perfection** — A project with consistent `snake_case` database columns is better than a project with half `snake_case` and half `PascalCase`. Match the existing pattern, even if another convention is theoretically superior.

## Patterns

### Convention Detection Flow

# Domain-Driven Design (DDD)

## Core Principles

1. **Aggregates define consistency boundaries** — An aggregate is a cluster of entities and value objects treated as a single unit for data changes. All invariants within an aggregate are enforced in a single transaction. Cross-aggregate consistency is eventual.
2. **Value objects over primitives** — Replace primitive obsession with value objects. `Money`, `EmailAddress`, `OrderNumber` are not strings — they carry validation, equality, and behavior. Use C# records for immutable value objects.
3. **Domain events decouple side effects** — When something meaningful happens in the domain (OrderPlaced, PaymentReceived), raise a domain event. Side effects (send email, update read model, notify another aggregate) subscribe to these events. The aggregate stays focused on its own rules.
4. **Aggregate root is the sole entry point** — External code accesses an aggregate only through its root entity. Child entities are never loaded or modified independently. The root enforces all invariants for the entire aggregate.
5. **Repositories persist aggregates, not entities** — One repository per aggregate root. The repository loads and saves the entire aggregate as a unit. No repository for child entities. The Infrastructure implementation uses `DbContext` internally — this is a DDD tactical pattern for aggregate boundaries, not a generic CRUD wrapper.

## Patterns

### Aggregate Root

# /de-sloppify — 7-Step Cleanup Pipeline

## What

Runs an ordered, verified cleanup pipeline over a .NET codebase. Order matters:
formatting first (it touches every file — get the churn out of the way before
anything else), dead code late (earlier steps reveal it). Random cleanup misses
things and creates merge conflicts; the pipeline doesn't.

Three rules make it safe:

1. **Verify after each step** — `dotnet build` + `dotnet test` between steps. A
   cleanup that breaks something is worse than the mess it was fixing.
2. **Commit per step** — each step is its own commit, so a bad Step 4 reverts

# Dependency Injection

## Core Principles

1. **Constructor injection is the default** — Inject dependencies through the constructor (primary constructors make this clean). No service locator, no property injection.
2. **Match lifetimes carefully** — A singleton must never depend on a scoped or transient service. This is the most common DI bug.
3. **Register interfaces, resolve interfaces** — Register `services.AddScoped<IOrderService, OrderService>()`, not the concrete type.
4. **Keyed services for strategy pattern** — .NET 8+ keyed services replace manual factory patterns for selecting between implementations.

## Patterns

### Keyed Services (.NET 8+)

Use keyed services to register and resolve multiple implementations of the same interface.

# Docker

## Core Principles

1. **Multi-stage builds always** — Separate build and runtime stages. Build in the SDK image, run in the ASP.NET runtime image.
2. **Non-root by default** — .NET container images support `USER app` by default since .NET 8. Never run as root in production.
3. **Layer caching matters** — Copy `.csproj` files and restore before copying source code. This caches NuGet dependencies across builds.
4. **Health probes at the orchestrator level** — Expose a `/health/live` endpoint and let Kubernetes/Compose probe it. Chiseled and default aspnet images have no shell or curl, so in-image `HEALTHCHECK` commands have nothing to run with.

## Patterns

### Multi-Stage Dockerfile for Web API

```dockerfile

# /dotnet-init

## What

Interactively initializes a .NET project for use with dotnet-claude-kit. Detects the project type, asks targeted questions about architecture and tech stack, then generates a fully customized `CLAUDE.md` in the project root.

**No manual template copying required.**

## When

- Starting a new .NET project with Claude Code
- Adding dotnet-claude-kit to an existing project
- "init project", "setup project", "generate CLAUDE.md", "configure for dotnet-claude-kit"

# EF Core (.NET 10)

## Core Principles

1. **EF Core is the default ORM** — Use it unless you have a specific reason not to (extreme perf, legacy DB without FK constraints). See ADR-003.
2. **DbContext is a unit of work** — Don't wrap it in another UoW abstraction. EF Core already implements Unit of Work and Repository patterns internally.
3. **Queries should be projections** — Use `.Select()` to project into DTOs instead of loading full entities. This avoids over-fetching and N+1 issues.
4. **Migrations are code** — Treat them like any other source code. Review them, test them, never auto-apply in production.

## Patterns

### DbContext Configuration

Use `IEntityTypeConfiguration<T>` to keep entity configs separate and discoverable.

# Error Handling

## Core Principles

1. **Use the Result pattern for expected failures** — Don't throw exceptions for things like "order not found" or "validation failed". These are expected outcomes, not exceptional conditions. See ADR-002.
2. **Reserve exceptions for unexpected failures** — Database connection lost, null reference bugs, network timeouts — these are truly exceptional and should propagate to the global handler.
3. **Every API error returns ProblemDetails** — RFC 9457 is the standard. Every error response has `type`, `title`, `status`, `detail`, and optionally `errors`.
4. **Validate at the boundary** — Validate incoming requests at the API layer, not deep inside business logic.

## Patterns

### Result Pattern

A simple, generic result type that carries either a value or errors.

# /health-check — 8-Dimension Project Assessment

## What

Runs a data-driven health assessment across 8 dimensions, each graded A-F with
the specific data points that produced the grade, and rolls them into a GPA.
Gut feeling is not a grade: every dimension uses MCP tools or CLI commands, and
every grade below A comes with specific, prioritized, effort-estimated fixes —
"add test classes for OrderService, PaymentProcessor, ShippingCalculator" is
actionable; "improve test coverage" is not.

This skill owns the **canonical grading system** for the kit. The full rubrics,
GPA scale, and report template live in `references/grading-rubric.md` — load
that file when running an assessment.

# HttpClient Factory

## Core Principles

1. **Never `new HttpClient()` per request** — Raw `HttpClient` creation causes socket exhaustion under load and ignores DNS changes. Use `IHttpClientFactory` to manage handler lifetimes.
2. **Keyed clients over typed clients** — Keyed DI (`.AddAsKeyed()`) is the recommended pattern in .NET 10. Typed clients captured in singletons silently break handler rotation.
3. **Resilience is not optional** — Every external HTTP call needs retry, circuit breaker, and timeout. `AddStandardResilienceHandler()` provides sensible defaults in one line.
4. **DelegatingHandlers for cross-cutting concerns** — Auth tokens, correlation IDs, and logging belong in the handler pipeline, not scattered across service methods.

## Patterns

### Named Client with Resilience

```csharp

# Instinct System

One learning system, three tiers. Every signal Claude receives during work — an observed pattern, a user correction, a surprising discovery — routes to exactly one store.

## Core Principles

1. **Three tiers, one routing decision** — *Instincts* are unconfirmed hypotheses (`.claude/instincts.md`). *Corrections* are user-confirmed rules (`MEMORY.md`). *Discoveries* are insights that explain the world (`.claude/learning-log.md`). Rules prescribe behavior; insights describe it; instincts are rules-in-waiting. Never mix the tiers — a hypothesis in MEMORY.md pollutes permanent knowledge, and a confirmed rule left as an instinct gets forgotten.

2. **Instincts are hypotheses, not rules** — An instinct starts as a guess from a single observation and has no authority until confirmed. "One handler uses `sealed`" is an instinct at 0.3; "all 12 handlers use `sealed`" is a rule at 0.9. Confidence (0.3–0.9) drives behavior: note at 0.3, mention at 0.5, follow at 0.7, promote at 0.9.

3. **A user correction is a confirmed instinct at full confidence** — When the user corrects you, skip the confirmation cycle entirely. Generalize the lesson, capture it immediately in MEMORY.md with the "why", and confirm what was captured. A correction costs the user 30 seconds today and saves hours across all future sessions — losing one is the most expensive mistake this system can make.

4. **Project-scoped, never global** — What holds in one codebase may be wrong in another. Instincts live per-project; transfers between projects go through export/import with confidence decay, never at full confidence.

# Logging & Observability

## Core Principles

1. **Structured logging with Serilog** — Every log entry is a structured event with named properties, not a formatted string. This enables searching, filtering, and alerting. All setup (two-stage bootstrap, `AddSerilog()`, sinks, enrichers) lives in the **serilog** skill — that skill's `AddSerilog()`-over-`UseSerilog()` guidance is canonical.
2. **OpenTelemetry for distributed tracing** — Traces connect requests across services; metrics track system health over time. Full setup lives in the **opentelemetry** skill.
3. **Health checks for operational readiness** — Every service exposes `/health` endpoints for load balancers and orchestrators. Liveness and readiness are separate questions and separate endpoints.
4. **Correlation IDs for request tracing** — Every request gets a unique ID that flows through all log entries and downstream service calls, so one user complaint maps to one filtered log stream.

## Patterns

### How the Pieces Fit Together

| Concern | Owner | Skill |

# Messaging

## Core Principles

1. **Wolverine is the recommended default** — MIT licensed, combines mediator + messaging in one library with built-in outbox, saga support, and convention-based handlers. MassTransit is an alternative but requires a commercial license from v9.
2. **Outbox pattern for reliability** — Always use the transactional outbox to ensure messages are published only when the database transaction succeeds.
3. **Choreography for simple flows, saga for complex** — If a workflow has 2-3 steps, use event choreography. If it has compensating actions or complex state, use a saga.
4. **Messages are contracts** — Put message types in a shared contracts project. Keep them as simple records with primitive types.

## Patterns

### Wolverine Setup

```csharp

# /migrate

## What

The single migration workflow for three change types, with EF Core schema
migrations as the primary flow:

1. **EF Core schema** — review pending model changes, generate a descriptively
   named migration, review the SQL for data loss and locking risks, apply with
   a documented rollback path.
2. **.NET version upgrade** — phased TFM/SDK/package upgrade with verification
   at each phase.
3. **NuGet updates** — incremental, one-package-at-a-time updates so breakage
   is always attributable.

# Minimal APIs (.NET 10)

## Core Principles

1. **Minimal APIs are the default** — Use controllers only when migrating legacy code. Minimal APIs are lighter, faster, and compose well with any architecture style.
2. **Group endpoints with `MapGroup`** — Never scatter individual `MapGet`/`MapPost` calls in `Program.cs`. Group related endpoints together.
3. **Use `TypedResults` for OpenAPI** — `TypedResults.Ok(value)` gives you compile-time type safety AND correct OpenAPI documentation. `Results.Ok(value)` does not.
4. **Metadata over comments** — Use `.WithName()`, `.WithTags()`, `.WithSummary()` to document endpoints. The metadata feeds into OpenAPI specs.

## Patterns

### Endpoint Group Auto-Discovery (Required Pattern)

Every endpoint group lives in its own file and implements `IEndpointGroup`. A single `app.MapEndpoints()` call in `Program.cs` discovers and registers all groups automatically. **Program.cs never changes when you add new endpoint groups.**

# Modern C# (C# 14 / .NET 10)

## Core Principles

1. **Use the newest stable features** — C# 14 is the target. Prefer language-level constructs over library workarounds.
2. **Readability over cleverness** — Pattern matching and expression-bodied members improve readability when used appropriately; deeply nested patterns do not.
3. **Value types where possible** — Prefer `record struct`, `Span<T>`, and stack allocation to reduce GC pressure.
4. **Immutability by default** — Use `record`, `readonly`, `init`, and `required` to make illegal states unrepresentable.

## Patterns

### Well-Known Features Quick Reference

| Feature | Usage | Example |

# OpenAPI

## Core Principles

1. **Built-in, not Swashbuckle** — .NET 10 ships `Microsoft.AspNetCore.OpenApi` as the official, framework-maintained OpenAPI solution. Swashbuckle was removed from templates in .NET 9 and is no longer recommended.
2. **TypedResults drive the schema** — `TypedResults.Ok<T>()` automatically generates correct OpenAPI response schemas. `Results.Ok()` does not. Always use `TypedResults`.
3. **Transformers over workarounds** — Document, operation, and schema transformers compose cleanly. Use them for security schemes, global responses, and schema customization.
4. **Metadata on every endpoint** — Use `.WithName()`, `.WithSummary()`, `.WithTags()` on every endpoint. This metadata feeds directly into the OpenAPI spec and client generators.

## Patterns

### Basic Setup

```csharp

# OpenTelemetry

## Core Principles

1. **Three pillars, one setup** — Configure traces, metrics, and logs through a single `AddOpenTelemetry()` call. Use `UseOtlpExporter()` for cross-cutting export to any OTLP-compatible backend.
2. **Use `IMeterFactory` for metrics** — Never create `Meter` instances with `new`. The factory manages lifetime through DI and prevents leaks.
3. **Null-safe activities** — `StartActivity()` returns `null` when no listener is attached. Always use `?.` when setting tags or events.
4. **Environment variables over code** — Use `OTEL_EXPORTER_OTLP_ENDPOINT` and `OTEL_SERVICE_NAME` so deployments control telemetry routing without code changes.
5. **Low-cardinality metric tags** — Keep metric tag combinations under ~1000 per instrument. Use span attributes or logs for high-cardinality data like user IDs or request IDs.

## Patterns

### Full Setup with All Three Signals

# /outdated

## What

A three-layer dependency health report:

1. **Inventory** — every `PackageReference` per project, with TFMs and central
   package management awareness, via the `get_nuget_packages` MCP tool (no
   network, token-cheap).
2. **Staleness + vulnerabilities** — current vs latest stable, and known CVEs,
   via the `dotnet` CLI.
3. **License screen** — flags packages that moved to commercial licenses so an
   innocent `dotnet outdated --upgrade` doesn't silently change your legal
   position.

# /plan -- Architecture-Aware Planning

## What

Enters a structured planning mode that considers the project's architecture pattern
before producing an implementation plan. Instead of jumping straight to code, this
command forces a deliberate pause to:

- Identify the project's current architecture (or recommend one)
- Map the task to affected layers, modules, and boundaries
- Produce a numbered implementation plan with clear steps
- Iterate on the plan until it is solid before writing any code

Plans are living documents -- if something goes sideways during implementation,

# Project Setup — Tech-Stack Advisor

This skill owns one thing: the kit's recommended tech-stack defaults and why. The workflows that consume it live elsewhere:

- **Initializing a project / generating CLAUDE.md** → `dotnet-init` (interactive flow, architecture questionnaire, CLAUDE.md generation)
- **Assessing an existing codebase** → `health-check` (the canonical 8-dimension graded assessment)
- **EF Core schema, NuGet, or .NET version migrations** → `migrate`
- **Choosing an architecture** → `architecture-advisor` (always ask before recommending)

## Core Principles

1. **Recommend a default, explain the why, let the user choose** — Every dimension has a kit default, but defaults are starting points, not mandates. State the trade-off in one line so the choice is informed.
2. **Prefer built-in .NET over third-party** — `HybridCache` over Redis-client wrappers, built-in rate limiting over packages, built-in OpenAPI over Swashbuckle. Fewer dependencies means fewer licensing surprises and upgrade breaks.
3. **License-aware picks** — MediatR (v13+), MassTransit (v9+), and FluentAssertions (v8+) went commercial. The kit defaults to MIT alternatives: Mediator, Wolverine, plain xUnit asserts.

# Project Structure

## Core Principles

1. **Central package management** — Use `Directory.Packages.props` to manage NuGet package versions in one place. No version numbers in individual `.csproj` files.
2. **Shared build properties** — Use `Directory.Build.props` for common settings (target framework, nullable, implicit usings). Don't repeat in every project.
3. **.slnx for solutions** — The new XML-based solution format is cleaner and more merge-friendly than the legacy `.sln` format.
4. **src/tests separation** — Source projects in `src/`, test projects in `tests/`. Clear boundary.

## Patterns

### Solution Layout

```

# Resilience

## Core Principles

1. **Polly v8 resilience pipelines, not v7 policies** — Polly v8 replaced `Policy` with `ResiliencePipeline`. Never use `PolicyBuilder`, `Policy.Handle<>()`, or `ISyncPolicy`. The new API is composable, type-safe, and integrates natively with `IHttpClientFactory`.
2. **Configure via `AddResilienceHandler`, not manual wrapping** — For HTTP calls, use `Microsoft.Extensions.Http.Resilience` which adds pipelines directly to `HttpClient` via DI. No manual `ExecuteAsync` wrapping.
3. **Compose strategies, don't nest them** — A single `ResiliencePipeline` can chain retry + circuit breaker + timeout. Strategies execute outer-to-inner (first added = outermost). No need for nested try/catch or manual orchestration.
4. **Always set timeouts** — Every external call needs a timeout. Use Polly's `AddTimeout()` as the innermost strategy so it applies per-attempt, and optionally an outer timeout for total elapsed time.
5. **Instrument everything** — Polly v8 emits `Metering` events and supports `TelemetryOptions` for OpenTelemetry. Use them to monitor retry rates, circuit breaker state, and timeout frequency.

## Patterns

### HTTP Client Resilience (Recommended Default)

# /scaffold — Architecture-Aware Feature Scaffolding

## What

Generates a complete feature with all required files based on the project's
architecture. Never generates half a feature — every scaffold includes the
endpoint, handler, validation, DTOs, EF configuration, and at least one
integration test as a single unit, written in modern C# 14 (primary
constructors, collection expressions, records, sealed handlers, TypedResults).

Supported architectures (file placement maps and code shape templates live in
`references/architecture-patterns.md`):

- **Vertical Slice Architecture (VSA)** — single-file features in `Features/`

# Scalar

## Core Principles

1. **Scalar replaces Swagger UI** — Scalar is the recommended API documentation UI for .NET 10. Faster rendering, built-in dark mode, code generation for dozens of languages, and full OpenAPI 3.1 support.
2. **Development only by default** — Wrap `MapScalarApiReference()` in an `IsDevelopment()` check. API documentation exposes internal structure. If needed in production, add authorization.
3. **Disable the proxy for sensitive APIs** — Scalar's "Try It" feature routes through `proxy.scalar.com` by default. Disable it with `.WithProxy(null)` to keep auth headers local.
4. **Security schemes come from OpenAPI** — Scalar reads security schemes from the OpenAPI document. Configure them via document transformers, not in Scalar directly.

## Patterns

### Basic Setup

```csharp

# /security-scan — 6-Layer Security Pipeline

## What

Runs a defense-in-depth static scan across 6 layers. A project with zero CVEs
can still have hardcoded secrets, SQL injection, and missing auth — each layer
catches a different vulnerability class. Findings map to the **OWASP Top
10:2025** taxonomy and are rated Critical/High/Medium/Low by exploitability,
impact, and exposure — a Critical SQL injection on a public endpoint outranks a
Low info-disclosure on an admin page.

Detection patterns, OWASP mappings, remediation code, and the report template
live in `references/scan-layers.md` — read it before executing.

# Serilog

## Core Principles

1. **Two-stage initialization** — Create a bootstrap logger for startup, then replace it with the full logger after DI is ready. This captures startup errors that would otherwise be lost.
2. **`AddSerilog()` over `UseSerilog()`** — Use `builder.Services.AddSerilog()` (the modern API) instead of `builder.Host.UseSerilog()`. It integrates with DI services via `ReadFrom.Services(services)`.
3. **Message templates, not interpolation** — `{PropertyName}` syntax creates structured data that can be queried. String interpolation (`$"..."`) breaks structure and allocates even when the log level is disabled.
4. **Configure via appsettings.json** — Keep log levels, sinks, and overrides in configuration so they can change per environment without redeployment.

## Patterns

### Two-Stage Bootstrap Setup

```csharp

# /spec — Relentless Specification Workflow

## What

Converts an idea into a written, versioned specification that both the developer
and Claude explicitly agree on — before any planning or code. The contract:

- **Never assume.** Every gap in the idea becomes a question. If Claude catches
  itself thinking "probably", "presumably", or "the usual way" — that thought is
  a question to ask, not a decision to make.
- **Relentless, but structured.** Questions come in focused rounds (3–5 at a
  time) across nine dimensions — not one overwhelming dump, and not a single
  polite round that stops early.
- **Agreement is explicit.** Specs have a status lifecycle: Draft → In Review →

# /tdd -- Red-Green-Refactor for .NET

## What

Guides a strict test-driven development cycle for .NET features. Instead of
writing implementation first and bolting on tests after, this command flips the
order: write a failing test that defines the desired behavior, implement the
minimum code to make it pass, then refactor with confidence.

Every cycle uses the .NET testing stack:
- **xUnit v3** -- Test framework with `[Fact]` and `[Theory]`
- **WebApplicationFactory** -- Integration tests against the real HTTP pipeline
- **Testcontainers** -- Real databases (PostgreSQL, SQL Server) in tests
- **Verify** -- Snapshot testing for complex response structures

# Testing (.NET 10)

## Core Principles

1. **Integration tests are the highest-value tests** — A single `WebApplicationFactory` test covers routing, binding, validation, business logic, and persistence in one shot. Start here before writing unit tests.
2. **Real databases in tests** — Use Testcontainers to spin up real PostgreSQL/SQL Server instances. In-memory providers hide real bugs (transactions, constraints, SQL generation).
3. **AAA pattern is mandatory** — Every test has three clearly separated sections: Arrange, Act, Assert. No mixing.
4. **Test behavior, not implementation** — Tests should survive refactoring. Test what the system does, not how it does it.

## Patterns

### xUnit v3 Basics

```csharp

# /verify -- 7-Phase Verification Pipeline

## What

Runs a sequential, 7-phase verification pipeline that catches issues at every level --
from compiler errors to subtle antipatterns to formatting drift. Each phase produces
an explicit PASS, WARN, or FAIL with details. "It looks fine" is not a verification
result; a table of statuses is. Critical failures (Phase 1 build, Phase 4 tests)
short-circuit the pipeline because later phases cannot produce meaningful results
on broken code.

The pipeline answers one question: **"Is this code ready for review?"**

| Phase | Tool | What It Catches | Critical |

# Vertical Slice Architecture (VSA)

## Core Principles

1. **Organize by feature, not by layer** — Each feature is a self-contained vertical slice containing its endpoint, handler, request/response types, and validation. No more jumping between Controllers/, Services/, Repositories/ folders.
2. **Minimize cross-feature coupling** — Features should not reference each other directly. Shared concerns go in a `Common/` or `Shared/` directory.
3. **One file per feature is fine** — A simple CRUD endpoint doesn't need 5 files spread across layers. Start with everything in one file, extract only when complexity demands it.
4. **The handler is the unit of work** — Each handler does one thing. No god-services with 20 methods.

## Patterns

### Feature Folder Structure

```

# Workflow Mastery for .NET

## Core Principles

1. **Parallel over sequential** — Run 3-5 Claude sessions simultaneously using git worktrees. Build a feature in one, fix a bug in another, run tests in a third. The single biggest productivity unlock.
2. **Plan then execute** — For any non-trivial task, start in plan mode, iterate until the plan is bulletproof, then switch to auto-accept. A good plan means Claude 1-shots the implementation.
3. **Verification closes the loop** — Give Claude a way to prove its work: `dotnet build`, `dotnet test`, `get_diagnostics` via MCP. This single practice 2-3x the quality of the output.
4. **Context is a budget, not a dumping ground** — The context window fills fast: a typical .cs file is 500-2000 tokens, and 50 file reads can burn a large share of the budget. Spend tokens like sprint capacity — deliberately.
5. **Automate the repetitive** — If you do it more than once a day, make it a hook, a slash command, or a subagent. Pre-allow safe permissions. Eliminate friction.
6. **Compound your knowledge** — Every correction becomes a rule in `MEMORY.md` (see `instinct-system` skill). Every PR review adds a learning. Over time, Claude's mistake rate drops because your project's knowledge base grows.

## Patterns

### Parallel Sessions with Git Worktrees

# /wrap-up

## What

The session continuity ritual. Sessions are ephemeral; knowledge is permanent.
Wrap-up bridges sessions in both directions:

- **Session END** — capture exactly three things: what was DONE, what is
  PENDING, and what was LEARNED. Write them to `.claude/handoff.md` and flow
  durable learnings into `MEMORY.md`.
- **Session START** — load the handoff, memory, and instincts, then present a
  resume summary so no session starts blind.

## When