@dennisrongo/skills 0.1.0

package/skills/dotnet-onion-api/SKILL.md

@@ -0,0 +1,267 @@
+---
+name: dotnet-onion-api
+description: Scaffold a new .NET solution (Web API + Worker microservices) using ONION architecture and EF Core, codifying battle-tested layered patterns and explicitly avoiding the common pitfalls of legacy stored-procedure-centric codebases. Use this skill whenever the user asks to "create a new dotnet project", "scaffold a .NET API", "new C# solution", "add a worker microservice", "add a feature end-to-end", or mentions "ONION", "Clean Architecture", "Onion Architecture", or "the layered .NET patterns I like". Three modes — (1) full solution scaffold, (2) add a feature slice through all layers, (3) add a BackgroundService worker microservice.
+---
+
+# .NET ONION API Scaffolder
+
+Generate a production-grade .NET solution that keeps the **good** layered patterns (Api → Application → Infrastructure → Domain separation, base classes for cross-cutting concerns, extension-method wiring in `Program.cs`, JWT, AutoMapper, auto-DI, unified error responses) and eliminates the **bad** ones often seen in legacy .NET codebases (stored-procedure-centric reflection repositories, EF6 on netstandard2.1, polling console-app workers, swallowed exceptions, mutable per-request state on base service classes, mixed ADO/Dapper/EF6 data access, missing `CancellationToken` plumbing).
+
+## When to use this skill
+
+Trigger on any of:
+
+- "create a new dotnet project / .NET solution / C# project"
+- "scaffold a .NET Web API"
+- "new microservice in .NET" / "add a worker service"
+- "use the patterns I like" / "use my layered .NET conventions" (in a .NET context)
+- "ONION architecture" / "Clean Architecture" / "layered .NET project"
+- "add a feature end-to-end" / "add a slice" (API + service + repository + EF entity + tests)
+- The user pastes a feature spec and asks you to wire it through the layers of a .NET solution
+
+If unsure whether the user wants a brand-new solution vs. an addition to an existing one, ask once — don't guess.
+
+## Three operating modes
+
+Pick the mode from the user's request. If ambiguous, ask.
+
+| Mode | Trigger | Output |
+|------|---------|--------|
+| **`scaffold-solution`** | "new project", "scaffold solution", empty directory | Full ONION solution: Domain, Application, Infrastructure, Api, Workers (optional), Tests. |
+| **`add-feature`** | "add `<Entity>` end-to-end", "wire up `<feature>` through all layers" | Entity + EF config + repository (port + adapter) + use-case service + DTO + controller + AutoMapper profile + unit test. |
+| **`add-worker`** | "new worker", "add microservice for queue X" | New `Workers.<Name>` project (BackgroundService) referencing Application + Infrastructure, with queue/service-bus consumer and graceful shutdown. |
+
+## Workflow
+
+### Step 1 — Determine the target framework (don't hard-code)
+
+The user explicitly does **not** want a hard-coded `<TargetFramework>` baked into the skill. Before generating `.csproj` files:
+
+1. Check the user's environment first: run `dotnet --list-sdks` to see installed SDKs.
+2. If a current LTS SDK is installed, prefer the highest installed LTS (`net8.0`, `net10.0`, etc.).
+3. If unsure which is the current LTS, fetch the latest .NET support policy via context7 (`mcp__plugin_context7_context7__resolve-library-id` → `query-docs` for ".NET release schedule" / "dotnet support policy") or WebFetch `https://dotnet.microsoft.com/en-us/platform/support/policy/dotnet-core`. Quote the version you picked back to the user before generating.
+4. Pin EF Core, ASP.NET Core, and `Microsoft.Extensions.*` package versions to the **latest stable for that TFM** — look them up via context7 (`Microsoft.EntityFrameworkCore`, `Microsoft.AspNetCore.Authentication.JwtBearer`, etc.) rather than guessing. Never hand-paste a version you don't have a source for.
+5. State the chosen TFM and package versions in your reply before writing files, so the user can object before scaffolding.
+
+### Step 2 — Gather inputs (ask once, in one batch)
+
+For `scaffold-solution`, use `AskUserQuestion` to collect:
+
+- **Solution name** (e.g. `Acme.Billing`). Used for namespace root and `.sln`.
+- **First feature/entity** (optional, e.g. `Customer`) — if provided, also run `add-feature` for it after scaffold.
+- **Auth**: JWT bearer with HS256 (symmetric) **or** JWT with asymmetric (RS256/JWKS) **or** none-yet.
+- **Include any Workers now?** If yes, ask for their names (comma-separated, e.g. `EmailSender, PdfPrinter`).
+- **Optional extras**: Serilog + OpenTelemetry? Dockerfile? GitHub Actions CI? Testcontainers integration tests? (Default: skip — only add if asked.)
+
+For `add-feature`: entity name, properties (name + C# type + nullability), whether it needs CRUD controller or only specific endpoints.
+
+For `add-worker`: worker name, trigger source (Azure Storage Queue / Service Bus / Timer), message DTO type (if known).
+
+### Step 3 — Generate files
+
+Use the **templates in `references/templates/`** as the source of truth for file contents. Apply these rules:
+
+- Use `Write` for new files. Never use `Edit` on files you're creating fresh.
+- Replace all `{{Solution}}`, `{{Feature}}`, `{{Worker}}` placeholders consistently.
+- Create directories before files. On Windows shell use PowerShell `New-Item -ItemType Directory -Force`.
+- After scaffolding, run `dotnet sln add` for every project and `dotnet build` to verify the solution compiles. Report build output to the user.
+- Do **not** run `dotnet new` to create the projects — write the `.csproj` and `.cs` files directly from templates so the layout matches exactly.
+
+### Step 4 — Verify and report
+
+- Run `dotnet build` from the solution root. If it fails, fix and rebuild — never leave a broken scaffold.
+- Run `dotnet test` if any test project exists.
+- Reply with a short summary: solution path, projects created, TFM chosen, package versions, next steps (e.g. "run `dotnet ef migrations add Initial -p src/{{Solution}}.Infrastructure -s src/{{Solution}}.Api`").
+
+## Solution layout (canonical)
+
+See [`references/solution-layout.md`](references/solution-layout.md) for the full tree and dependency rules.
+
+```
+{{Solution}}/
+  {{Solution}}.sln
+  src/
+    {{Solution}}.Domain          # entities, value objects, domain events. NO project refs.
+    {{Solution}}.Application     # use-case services + ports (interfaces) + DTOs + validators. refs Domain.
+    {{Solution}}.Infrastructure  # EF Core DbContext, repository adapters, external clients (Azure, email, auth). refs Application+Domain.
+    {{Solution}}.Api             # Controllers, Middleware, Filters, Program.cs. refs Application+Infrastructure.
+    {{Solution}}.Workers.<Name>  # BackgroundService microservices. refs Application+Infrastructure.
+    {{Solution}}.Contracts       # (optional) public DTOs / API contracts shared with clients.
+  tests/
+    {{Solution}}.UnitTests       # xUnit + NSubstitute. Tests Application use-cases with mocked ports.
+    {{Solution}}.IntegrationTests# WebApplicationFactory + Testcontainers (SQL Server). Real DB + real pipeline.
+```
+
+**Dependency rule (enforced):** outer → inner only. Domain has zero project references. Application references Domain only. Infrastructure may reference both. Api/Workers reference Application + Infrastructure but never each other.
+
+## Required code patterns
+
+Use these exact patterns when generating files. Full templates are in `references/templates/`.
+
+### Keep
+
+- **`BaseController`** with `[ApiController]`, `[Route("api/[controller]")]`, `[Authorize]`, injected `IUserContext` — see [`references/templates/base-controller.cs.md`](references/templates/base-controller.cs.md).
+- **Base use-case service** with constructor-injected `IUserContext` (no public mutable user property — a common bug in legacy bases).
+- **Thin `Program.cs`** that calls only extension methods (`AddApplication`, `AddInfrastructure`, `AddApiServices`, `AddJwtAuth`, `AddSwaggerDocs`, `AddCorsPolicies`). See [`references/templates/program-cs.md`](references/templates/program-cs.md).
+- **Auto-registration** via `Scrutor` for ports → adapters (replaces `NetCore.AutoRegisterDi`, modern + maintained). Singletons/options registered explicitly.
+- **Strongly-typed `AppSettings` + `ConnectionStrings`** bound via `IOptions<T>` (don't register the raw POCO as singleton — use `services.Configure<T>(...)` and inject `IOptions<T>`).
+- **AutoMapper** with assembly scan: `services.AddAutoMapper(typeof(ApplicationAssemblyMarker).Assembly)`.
+- **Centralized exception middleware** with env-aware response — see [`references/templates/exception-middleware.cs.md`](references/templates/exception-middleware.cs.md).
+- **Unified validation error response** via `InvalidModelStateResponseFactory`.
+- **JWT auth wiring** in a `RegisterAuth` extension method.
+
+### Eliminate (anti-patterns)
+
+Every one of these is forbidden in generated code. See [`references/anti-patterns.md`](references/anti-patterns.md) for the rationale of each.
+
+- ❌ Stored-procedure-first data access. **Use EF Core with LINQ**; only drop to raw SQL via `FromSqlInterpolated`/`ExecuteSqlInterpolated` for legitimate perf/legacy reasons, and never with reflection-based parameter mapping.
+- ❌ `dynamic` / `ExpandoObject` for query parameters.
+- ❌ Reflection-based `DataRow → object` mappers. EF Core handles this.
+- ❌ EF6 + `netstandard2.1`. Use **EF Core (latest)** on the chosen TFM.
+- ❌ Empty `catch {}` blocks. Either handle the exception meaningfully or let it propagate to the middleware.
+- ❌ Mutable `public User { get; set; }` on a service base class — request-scoped state belongs in the scoped `IUserContext` only.
+- ❌ Polling `while (true) { Task.Delay(5s) }` console-app workers. Use `BackgroundService` with `CancellationToken stoppingToken` and SDK-native receive loops — see [`references/templates/worker-program.cs.md`](references/templates/worker-program.cs.md).
+- ❌ Booting hosted services with `serviceProvider.GetService<T>()` in `Program.cs`. Register them via `services.AddHostedService<T>()`.
+- ❌ Auto-registering everything as `Scoped` indiscriminately. Use Scrutor's lifetime selectors, and register Azure SDK clients / `IHttpClientFactory` clients / options as singletons explicitly.
+- ❌ Newtonsoft.Json + `DefaultContractResolver` (PascalCase). Use **System.Text.Json** with `JsonNamingPolicy.CamelCase` by default. Add Newtonsoft only if a specific dependency demands it.
+- ❌ Missing `CancellationToken` parameters. Every async public method takes `CancellationToken ct` as the **last** parameter and forwards it.
+- ❌ Per-tenant repositories under `Repositories/{TenantName}/`. Multi-tenant behavior goes through a strategy injected via DI, not folder forks.
+- ❌ Hard-coded multi-tenant magic fallbacks (e.g. defaulting `ClientId` to a literal string when claims are missing). Multi-tenancy comes from `IUserContext` or fails fast.
+- ❌ Commented-out dead code in generated files.
+- ❌ Controllers that bypass `BaseController` (consistency is mandatory; if a public endpoint needs `[AllowAnonymous]`, declare it on the action).
+
+## Operating-mode playbooks
+
+### Mode 1 — `scaffold-solution`
+
+1. Pick TFM and package versions per **Step 1**. Quote them.
+2. Ask the inputs per **Step 2**. Wait for answers.
+3. Generate, in this order:
+   1. `.sln` file (use `dotnet new sln -n {{Solution}}` *only* to produce the sln; everything else is hand-written from templates).
+   2. `src/{{Solution}}.Domain/` (csproj + `DomainAssemblyMarker.cs` + sample `Entity` base if relevant).
+   3. `src/{{Solution}}.Application/` (csproj + assembly marker + `Common/` with `IUserContext`, `Result<T>` if requested, `IUnitOfWork` port, `IRepository<T>` port).
+   4. `src/{{Solution}}.Infrastructure/` (csproj + `Persistence/AppDbContext.cs` + `Persistence/EntityConfigurations/` folder + `Persistence/UnitOfWork.cs` + `Auth/UserContext.cs` + `DependencyInjection.cs` with `AddInfrastructure`).
+   5. `src/{{Solution}}.Api/` (csproj + `Program.cs` + `Extensions/` folder + `Middlewares/ExceptionHandlerMiddleware.cs` + `Controllers/BaseController.cs` + `appsettings.json`/`appsettings.Development.json`).
+   6. `src/{{Solution}}.Workers.<Name>/` per worker requested.
+   7. `tests/{{Solution}}.UnitTests/` (csproj + xUnit + NSubstitute + AutoFixture).
+   8. `tests/{{Solution}}.IntegrationTests/` (csproj + `Microsoft.AspNetCore.Mvc.Testing` + `Testcontainers.MsSql`) — only if user asked for it.
+4. `dotnet sln {{Solution}}.sln add` every project (one command, all projects).
+5. `dotnet build` — must succeed.
+6. If a first feature was requested, immediately run **Mode 2** for that entity.
+7. Report.
+
+### Mode 2 — `add-feature`
+
+For entity `{{Feature}}` (e.g. `Customer`):
+
+1. **Domain**: `src/{{Solution}}.Domain/{{Feature}}s/{{Feature}}.cs` — POCO entity with a private parameterless ctor for EF, a public ctor for invariants, and behavior methods (avoid anemic models). Add domain events only if asked.
+2. **Application**:
+   - Port: `src/{{Solution}}.Application/{{Feature}}s/I{{Feature}}Repository.cs` (interface with CRUD methods that take `CancellationToken`).
+   - DTOs: `Application/{{Feature}}s/Dtos/{{Feature}}Dto.cs`, `Create{{Feature}}Request.cs`, `Update{{Feature}}Request.cs`.
+   - Use-case service: `Application/{{Feature}}s/{{Feature}}Service.cs` + interface `I{{Feature}}Service.cs`. Service depends on `I{{Feature}}Repository`, `IUnitOfWork`, `IMapper`. Pure orchestration — no EF references.
+   - AutoMapper profile: `Application/{{Feature}}s/Mapping/{{Feature}}Profile.cs`.
+   - FluentValidation validator (only if user asked for FluentValidation; otherwise rely on DataAnnotations + the validation factory).
+3. **Infrastructure**:
+   - EF configuration: `Infrastructure/Persistence/EntityConfigurations/{{Feature}}Configuration.cs` (implements `IEntityTypeConfiguration<{{Feature}}>`).
+   - Repository adapter: `Infrastructure/Persistence/Repositories/{{Feature}}Repository.cs` (implements `I{{Feature}}Repository` using `AppDbContext`).
+   - Register the DbSet on `AppDbContext`.
+4. **Api**:
+   - Controller: `Api/Controllers/{{Feature}}sController.cs` inheriting `BaseController`, injecting `I{{Feature}}Service`. Standard REST endpoints, returning DTOs only.
+5. **Tests**:
+   - `tests/{{Solution}}.UnitTests/{{Feature}}s/{{Feature}}ServiceTests.cs` — xUnit + NSubstitute, covers the service's happy path + one validation/edge case.
+
+Template for the full slice is in [`references/templates/feature-slice.md`](references/templates/feature-slice.md).
+
+After generating: `dotnet build` then `dotnet test`. Both must pass.
+
+### Mode 3 — `add-worker`
+
+For worker `{{Worker}}` (e.g. `EmailSender`):
+
+1. Create `src/{{Solution}}.Workers.{{Worker}}/`:
+   - `csproj` per [`references/templates/worker-csproj.md`](references/templates/worker-csproj.md).
+   - `Program.cs` using `Host.CreateApplicationBuilder` per [`references/templates/worker-program.cs.md`](references/templates/worker-program.cs.md).
+   - `Worker.cs` — `BackgroundService` subclass; loop driven by `stoppingToken`; respects graceful shutdown.
+   - `appsettings.json` + `appsettings.Development.json`.
+2. Reference `Application` + `Infrastructure` (never `Api`).
+3. Add to `.sln`. `dotnet build`.
+4. **No `while (true) { ... await Task.Delay(5s) }`** — use the SDK's receive loop (e.g. `await foreach (var msg in receiver.ReceiveMessagesAsync(stoppingToken))` for Service Bus, or `await queueClient.ReceiveMessagesAsync(maxMessages, ct: stoppingToken)` inside a `while (!stoppingToken.IsCancellationRequested)` loop).
+
+## NuGet packages (resolve latest stable at scaffold time)
+
+Look these up via context7 — do not hand-paste versions:
+
+**Api project**
+- `Microsoft.AspNetCore.Authentication.JwtBearer`
+- `Microsoft.AspNetCore.OpenApi`
+- `Swashbuckle.AspNetCore`
+- `AutoMapper.Extensions.Microsoft.DependencyInjection` (or `AutoMapper` 13+ which self-registers)
+- `Scrutor` (assembly-scanning DI)
+- `Serilog.AspNetCore` + `Serilog.Sinks.Console` (only if user opted into Serilog)
+
+**Application project**
+- `MediatR` only if user explicitly asks for CQRS; default is plain service classes
+- `FluentValidation` only if requested
+
+**Infrastructure project**
+- `Microsoft.EntityFrameworkCore.SqlServer`
+- `Microsoft.EntityFrameworkCore.Design` (PrivateAssets="all")
+- `Microsoft.EntityFrameworkCore.Tools` (PrivateAssets="all")
+- `Microsoft.Data.SqlClient`
+- `Azure.Storage.Blobs`, `Azure.Storage.Queues`, `Azure.Messaging.ServiceBus` (only if used)
+
+**Worker projects**
+- `Microsoft.Extensions.Hosting`
+- Same Azure SDK packages as Infrastructure (only what the worker actually uses)
+
+**Test projects**
+- `Microsoft.NET.Test.Sdk`
+- `xunit`, `xunit.runner.visualstudio`
+- `NSubstitute` (preferred over Moq — cleaner API, actively maintained)
+- `FluentAssertions`
+- `Testcontainers.MsSql` (integration tests only)
+- `Microsoft.AspNetCore.Mvc.Testing` (integration tests only)
+
+## Verification checklist before reporting "done"
+
+- [ ] `dotnet build` exits 0.
+- [ ] `dotnet test` exits 0 (if tests were generated).
+- [ ] No `.csproj` references violate the ONION rule (verify with `grep`/`Select-String` for cross-layer `ProjectReference`).
+- [ ] No file contains any pattern from the **Eliminate** list.
+- [ ] `Program.cs` is under ~50 lines (everything else is in extension methods).
+- [ ] Domain project's `.csproj` has zero `<ProjectReference>` entries.
+
+If any check fails, fix before reporting. Don't claim success with a known-broken scaffold.
+
+## Examples
+
+### Example 1: Fresh solution
+
+**User:** "Scaffold a new dotnet API project called `Acme.Billing` using my ONION patterns. Add a `Customer` feature too."
+
+**Claude:**
+1. Runs `dotnet --list-sdks`, checks context7 for current LTS, picks (e.g.) `net8.0`.
+2. Reports chosen TFM + package versions; waits for confirmation if anything looks off.
+3. Asks the Step-2 questions (auth flavor, workers, extras).
+4. Generates the full solution + the `Customer` feature slice.
+5. Runs `dotnet build` and `dotnet test`.
+6. Reports the tree and the EF migration command.
+
+### Example 2: Add a feature
+
+**User:** "Add an `Invoice` feature end-to-end to the existing solution."
+
+**Claude:** Runs Mode 2 only — generates Domain entity, Application port + service + DTOs, Infrastructure config + repository, Api controller, unit test. Builds and tests.
+
+### Example 3: Add a worker
+
+**User:** "Add a worker that processes the `print-jobs` Azure Storage queue."
+
+**Claude:** Runs Mode 3 — generates `Workers.PrintJobs` project with a `BackgroundService` that receives messages with `stoppingToken`, calls into an Application service, deletes on success. Wires it into the .sln. Builds.
+
+## Notes
+
+- **Don't over-engineer**: don't add MediatR, CQRS, MassTransit, Polly, MinimalAPI conversions, Result<T> patterns, or domain events unless the user asks. Pragmatic > pure.
+- **Don't rewrite the user's existing codebase** as part of this skill. This skill is for *new* scaffolds, not migrations. If the user wants a migration plan, that's a different conversation.
+- **Multi-tenancy**: if the new project needs it, generate a `TenantContext` mirroring `IUserContext` and use EF Core query filters (`HasQueryFilter`) rather than per-tenant repositories.
+- **Always quote the TFM and package versions you chose before writing files** — the user explicitly asked not to hard-code them.

package/skills/dotnet-onion-api/references/anti-patterns.md

@@ -0,0 +1,155 @@
+# Anti-patterns — what NOT to generate
+
+Each item lists a common legacy pattern, why it's wrong, and what to do instead. The skill must never emit any of these in generated code.
+
+## 1. Stored procedures as the dominant data path
+
+**Anti-pattern:** Every repository calls a custom `Database`/`BaseData` wrapper around ADO.NET, executing `usp_Foo`-style stored procedures; business logic lives in SQL.
+
+**Why bad:** Untyped, no refactoring tooling, untestable, no LINQ, no compile-time safety, hides domain logic in the DB.
+
+**Do instead:** EF Core + LINQ for all reads/writes. Drop to `FromSqlInterpolated`/`ExecuteSqlInterpolated` *only* for legitimate perf hotspots or legacy sproc reuse, and use the interpolation form (parameters are bound automatically). Never use reflection-based parameter mapping.
+
+## 2. `dynamic` / `ExpandoObject` parameter mapping
+
+**Anti-pattern:** A `GetParameters(dynamic item)` helper that walks properties or ExpandoObject keys and switch-maps types to `SqlDbType`.
+
+**Why bad:** Runtime errors, no IntelliSense, silent truncation (`SqlDbType.VarChar` defaults to 8000), terrible for code review.
+
+**Do instead:** Strongly-typed request/DTO records. EF Core binds them.
+
+## 3. Reflection-based `DataRow → object` mappers
+
+**Anti-pattern:** A `MakeObjectFromDataRow` helper with a giant switch on `PropertyType.Name`, custom date parsing, swallowed exceptions on `SetValue`.
+
+**Why bad:** Slow, ignores nullability, eats errors, can't be debugged.
+
+**Do instead:** EF Core materializes entities. For ad-hoc projections, use `Select(x => new MyDto { ... })` in LINQ — fully typed.
+
+## 4. EF6 on `netstandard2.1`
+
+**Anti-pattern:** `EntityFramework 6.4.4` referenced from `netstandard2.1` libraries, EF Core nowhere.
+
+**Why bad:** EF6 is maintenance-mode; no async-streaming, no compiled queries, no `IAsyncEnumerable`, no migrations bundles.
+
+**Do instead:** **EF Core (latest stable for the chosen TFM)**, modern provider (`Microsoft.EntityFrameworkCore.SqlServer`).
+
+## 5. Empty `catch {}`
+
+**Anti-pattern:** Wrapping a SQL call (or any operation) in `try { ... } catch (Exception) { }` and returning a sentinel like `-1`.
+
+**Why bad:** Bugs become silent. Failures masquerade as success.
+
+**Do instead:** Let exceptions propagate to the centralized exception middleware. If a specific exception is genuinely recoverable, catch *that* type and log/handle explicitly.
+
+## 6. Mutable public state on a service base class
+
+**Anti-pattern:** `public class BaseService { public User User { get; set; } }` — a public setter on a scoped service.
+
+**Why bad:** Anyone can stomp it. Risks cross-request leaks if lifetime gets botched.
+
+**Do instead:** Inject `IUserContext` (scoped). No setters. The service reads `UserContext.UserId` etc. on demand.
+
+## 7. Polling-loop workers as console apps
+
+**Anti-pattern:**
+```csharp
+while (true)
+{
+    var msgs = await queueClient.ReceiveMessagesAsync(maxMessages: 1);
+    if (msgs.Value.Length == 0) { await Task.Delay(5000); continue; }
+    ...
+}
+```
+
+**Why bad:** No graceful shutdown, no DI lifetime management, no health checks, can't be hosted alongside other services, no `IConfiguration` change tokens, no structured logging out of the box.
+
+**Do instead:** `BackgroundService` with `protected override async Task ExecuteAsync(CancellationToken stoppingToken)`. Use `stoppingToken` in every `await`. Use `Host.CreateApplicationBuilder` + `services.AddHostedService<Worker>()`.
+
+## 8. Booting hosted services with `serviceProvider.GetService<T>()`
+
+**Anti-pattern:** Resolving a "listener" type from the service provider in `Program.cs` solely for its constructor side effects (starting a background loop).
+
+**Why bad:** Brittle (forgets to resolve = silently dead). No lifetime hook. Can't unit test the hosted lifecycle.
+
+**Do instead:** Implement `IHostedService` (or inherit `BackgroundService`) and register with `services.AddHostedService<MyListener>()`. The host owns start/stop.
+
+## 9. Indiscriminate `Scoped` auto-registration
+
+**Anti-pattern:** `RegisterAssemblyPublicNonGenericClasses(...).AsPublicImplementedInterfaces(ServiceLifetime.Scoped)` for every assembly, including ones that contain singletons.
+
+**Why bad:** Singletons (Azure SDK clients, third-party notification clients, options) accidentally become scoped or vice versa. Memory leaks, perf issues, race conditions.
+
+**Do instead:** Use Scrutor with lifetime selectors and exclude marker interfaces for non-scoped types:
+
+```csharp
+services.Scan(s => s
+    .FromAssemblyOf<ApplicationAssemblyMarker>()
+    .AddClasses(c => c.Where(t => t.Name.EndsWith("Service")))
+        .AsImplementedInterfaces()
+        .WithScopedLifetime());
+```
+
+Register singletons (Azure SDK clients, HttpClient factories, options) explicitly.
+
+## 10. Newtonsoft.Json + PascalCase by default
+
+**Anti-pattern:** `AddNewtonsoftJson(... new DefaultContractResolver())` with a TODO comment "use camel case later".
+
+**Why bad:** PascalCase breaks JS/TS clients by convention; Newtonsoft is slower, larger, and not the framework default any more.
+
+**Do instead:** Stick with System.Text.Json (default). Configure `JsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase` if you want to be explicit (it's the default anyway in ASP.NET Core). Only add Newtonsoft for specific compatibility needs.
+
+## 11. Missing `CancellationToken`
+
+**Anti-pattern:** Async methods with no `CancellationToken` parameter, so client disconnects don't cancel server-side work.
+
+**Do instead:** Every public async method takes `CancellationToken ct = default` as the **last** parameter and forwards it to every awaited call (`ToListAsync(ct)`, `SaveChangesAsync(ct)`, etc.). Controllers accept the framework-provided `HttpContext.RequestAborted` implicitly when you add `CancellationToken ct` to the action signature.
+
+## 12. Per-tenant repository folders
+
+**Anti-pattern:** `FormRepositories/TenantA/`, `FormRepositories/TenantB/` — branching tenant logic at the repository layer with parallel folders per customer.
+
+**Why bad:** Doesn't scale, duplicates code, hides shared behavior, requires registering different implementations per tenant.
+
+**Do instead:** One repository. Multi-tenant variations live behind a `ITenantStrategy` (or similar) port resolved at runtime, or via EF Core query filters tied to the current tenant ID.
+
+## 13. Hard-coded multi-tenant fallback
+
+**Anti-pattern:** A base data class constructor that assigns a literal default to the tenant/client identifier before reading claims (e.g. `DataContext.ClientId = "default";`).
+
+**Why bad:** Silently routes anonymous/broken requests to a default tenant — security hole.
+
+**Do instead:** `IUserContext.ClientId` either has a value or you reject the request. No magic defaults. If you legitimately have a public path, branch explicitly.
+
+## 14. Commented-out dead code
+
+**Anti-pattern:** Large `// var existingFactor = await ...` blocks left in repository code "in case we need it later".
+
+**Why bad:** Confuses readers, rots, never accurate again.
+
+**Do instead:** Delete it. If you might need it later, that's what git is for.
+
+## 15. Controllers that bypass the base class
+
+**Anti-pattern:** A controller (often `AuthController`) inheriting `ControllerBase` directly to escape the `[Authorize]` default — losing every other cross-cutting filter in the process.
+
+**Why bad:** Inconsistent cross-cutting concerns; easy to forget a filter.
+
+**Do instead:** All controllers inherit `BaseController`. For public endpoints, decorate the *action* with `[AllowAnonymous]`.
+
+## 16. Mixed data access (EF6 + Dapper + ADO.NET sprocs)
+
+**Anti-pattern:** All three coexist in the same codebase, often in the same project.
+
+**Why bad:** Three sets of conventions, three ways to fail, three connection-management stories.
+
+**Do instead:** EF Core is the default. Dapper is acceptable as a perf escape hatch for read-heavy queries — register it side-by-side but don't sprinkle it everywhere.
+
+## 17. Registering POCO config as a singleton
+
+**Anti-pattern:** `services.AddSingleton(_ => builder.Configuration.GetSection("AppSettings").Get<AppSettings>())`.
+
+**Why bad:** Doesn't react to `IOptionsMonitor` changes; couples consumers to the POCO; bypasses the options validation pipeline.
+
+**Do instead:** `services.AddOptions<AppSettings>().Bind(config.GetSection("AppSettings")).ValidateDataAnnotations().ValidateOnStart();` — inject `IOptions<AppSettings>` (or `IOptionsSnapshot<T>` if you need reload).

package/skills/dotnet-onion-api/references/solution-layout.md

@@ -0,0 +1,113 @@
+# Solution layout
+
+Canonical folder + project structure for every solution this skill generates.
+
+```
+{{Solution}}/
+├── {{Solution}}.sln
+├── .editorconfig
+├── .gitignore
+├── Directory.Build.props          # optional: shared <LangVersion>, <Nullable>, analyzers
+├── global.json                    # pins the SDK band (major.minor.x), not the exact patch
+├── src/
+│   ├── {{Solution}}.Domain/
+│   │   ├── {{Solution}}.Domain.csproj
+│   │   ├── DomainAssemblyMarker.cs
+│   │   └── <Entity>/Entity.cs ...
+│   ├── {{Solution}}.Application/
+│   │   ├── {{Solution}}.Application.csproj
+│   │   ├── ApplicationAssemblyMarker.cs
+│   │   ├── DependencyInjection.cs            # AddApplication(services)
+│   │   ├── Common/
+│   │   │   ├── IUserContext.cs
+│   │   │   ├── IUnitOfWork.cs
+│   │   │   └── Exceptions/                   # NotFoundException, ValidationException, ConflictException
+│   │   └── <Feature>/
+│   │       ├── I{{Feature}}Repository.cs     # port
+│   │       ├── I{{Feature}}Service.cs
+│   │       ├── {{Feature}}Service.cs
+│   │       ├── Dtos/...
+│   │       └── Mapping/{{Feature}}Profile.cs
+│   ├── {{Solution}}.Infrastructure/
+│   │   ├── {{Solution}}.Infrastructure.csproj
+│   │   ├── DependencyInjection.cs            # AddInfrastructure(services, config)
+│   │   ├── Auth/
+│   │   │   └── UserContext.cs                # IUserContext implementation (reads claims via IHttpContextAccessor)
+│   │   └── Persistence/
+│   │       ├── AppDbContext.cs
+│   │       ├── UnitOfWork.cs                 # IUnitOfWork adapter wrapping AppDbContext.SaveChangesAsync
+│   │       ├── Migrations/                   # generated by `dotnet ef migrations add`
+│   │       ├── EntityConfigurations/
+│   │       │   └── {{Feature}}Configuration.cs
+│   │       └── Repositories/
+│   │           └── {{Feature}}Repository.cs
+│   ├── {{Solution}}.Api/
+│   │   ├── {{Solution}}.Api.csproj
+│   │   ├── Program.cs
+│   │   ├── appsettings.json
+│   │   ├── appsettings.Development.json
+│   │   ├── Extensions/
+│   │   │   ├── ApiBehaviorExtensions.cs      # ConfigureControllers, ConfigureApiBehavior
+│   │   │   ├── AuthExtensions.cs             # AddJwtAuth
+│   │   │   ├── CorsExtensions.cs
+│   │   │   └── SwaggerExtensions.cs
+│   │   ├── Middlewares/
+│   │   │   └── ExceptionHandlerMiddleware.cs
+│   │   ├── Filters/                          # action filters if needed
+│   │   ├── Models/
+│   │   │   ├── ApiException.cs
+│   │   │   └── ApiValidationErrorResponse.cs
+│   │   └── Controllers/
+│   │       ├── BaseController.cs
+│   │       └── {{Feature}}sController.cs
+│   └── {{Solution}}.Workers.{{Worker}}/
+│       ├── {{Solution}}.Workers.{{Worker}}.csproj
+│       ├── Program.cs
+│       ├── Worker.cs                         # BackgroundService
+│       ├── appsettings.json
+│       └── appsettings.Development.json
+└── tests/
+    ├── {{Solution}}.UnitTests/
+    │   ├── {{Solution}}.UnitTests.csproj
+    │   └── <Feature>/{{Feature}}ServiceTests.cs
+    └── {{Solution}}.IntegrationTests/        # optional
+        ├── {{Solution}}.IntegrationTests.csproj
+        ├── ApiFactory.cs                     # WebApplicationFactory<Program> + Testcontainers MsSql
+        └── <Feature>/{{Feature}}EndpointTests.cs
+```
+
+## Dependency rules (enforced)
+
+| From → To           | Domain | Application | Infrastructure | Api | Workers | Contracts |
+|---------------------|--------|-------------|----------------|-----|---------|-----------|
+| **Domain**          | —      | ❌          | ❌             | ❌  | ❌      | ❌        |
+| **Application**     | ✅     | —           | ❌             | ❌  | ❌      | ✅ (opt)  |
+| **Infrastructure**  | ✅     | ✅          | —              | ❌  | ❌      | ❌        |
+| **Api**             | ✅     | ✅          | ✅             | —   | ❌      | ✅ (opt)  |
+| **Workers.<Name>**  | ✅     | ✅          | ✅             | ❌  | —       | ✅ (opt)  |
+| **Tests**           | ✅     | ✅          | ✅             | ✅  | ✅      | ✅        |
+
+- Domain has **zero** `<ProjectReference>` entries. Verify after scaffold.
+- Api and Workers never reference each other.
+- `Contracts` (if generated) only contains DTOs and has no project refs.
+
+## Namespace convention
+
+- Root namespace = solution name, e.g. `Acme.Billing`.
+- Project namespaces match folders: `Acme.Billing.Application.Customers`, `Acme.Billing.Infrastructure.Persistence.Repositories`, etc.
+- Assembly markers live at the project root for `typeof(...).Assembly` lookups (AutoMapper, Scrutor scans).
+
+## `global.json`
+
+Pin the SDK *band*, not the exact patch — so the solution builds on whichever patch the developer has installed:
+
+```json
+{
+  "sdk": {
+    "version": "8.0.0",
+    "rollForward": "latestFeature"
+  }
+}
+```
+
+Set `version` to the major.minor.0 of the TFM chosen in Step 1.

package/skills/dotnet-onion-api/references/templates/appsettings.md

@@ -0,0 +1,75 @@
+# `appsettings.json` templates
+
+## `src/{{Solution}}.Api/appsettings.json`
+
+```json
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  },
+  "ConnectionStrings": {
+    "Default": "Server=(localdb)\\MSSQLLocalDB;Database={{Solution}};Trusted_Connection=True;TrustServerCertificate=True"
+  },
+  "AppSettings": {
+    "SecretToken": "REPLACE_ME_WITH_A_LONG_RANDOM_STRING_AT_LEAST_32_CHARS",
+    "AllowedOrigins": [ "https://localhost:5173" ]
+  }
+}
+```
+
+## `src/{{Solution}}.Api/appsettings.Development.json`
+
+```json
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Debug",
+      "Microsoft.EntityFrameworkCore.Database.Command": "Information"
+    }
+  }
+}
+```
+
+## Strongly-typed binding (in `AddApiServices`)
+
+```csharp
+services.AddOptions<AppSettings>()
+    .Bind(config.GetSection("AppSettings"))
+    .ValidateDataAnnotations()
+    .ValidateOnStart();
+```
+
+## `AppSettings.cs` POCO (lives in Api project — Api is the only consumer of API-specific settings)
+
+```csharp
+using System.ComponentModel.DataAnnotations;
+
+namespace {{Solution}}.Api.Configuration;
+
+public sealed class AppSettings
+{
+    [Required, MinLength(32)]
+    public string SecretToken { get; set; } = string.Empty;
+
+    public string[] AllowedOrigins { get; set; } = Array.Empty<string>();
+}
+```
+
+## Secrets
+
+In `Development`, the `SecretToken` must come from User Secrets, not `appsettings.Development.json` (don't commit secrets):
+
+```bash
+dotnet user-secrets init --project src/{{Solution}}.Api
+dotnet user-secrets set "AppSettings:SecretToken" "<long-random-string>" --project src/{{Solution}}.Api
+```
+
+In `Production`, set via environment variables or your secret store (Key Vault, etc.). The double-underscore form binds to nested keys:
+
+```
+AppSettings__SecretToken=...
+ConnectionStrings__Default=...
+```