claude-code-arcane 1.1.1 → 1.3.0

package/skills/dotnet-best-practices/references/dependency-injection.md

@@ -0,0 +1,73 @@
+# 2. Dependency Injection (CRITICAL)
+
+## 2.1 Prefer Constructor Injection (Primary Constructors) — CRITICAL
+
+Dependencias explícitas, type-safe y testeables. Con primary constructors (C# 12+) el boilerplate desaparece.
+
+**Correcto:**
+```csharp
+public sealed class CreateOrderHandler(IOrderRepository repo, ILogger<CreateOrderHandler> logger)
+{
+    public async Task HandleAsync(CreateOrderRequest req, CancellationToken ct)
+    {
+        logger.LogInformation("Creating order for {Customer}", req.CustomerId);
+        await repo.AddAsync(req.ToOrder(), ct);
+    }
+}
+```
+
+## 2.2 Use Correct Lifetimes — CRITICAL
+
+`Scoped` para `DbContext` y handlers (una instancia por request). `Singleton` solo para servicios stateless y thread-safe. `Transient` para servicios livianos sin estado.
+
+```csharp
+builder.Services.AddDbContext<AppDbContext>(o => o.UseNpgsql(cs)); // Scoped por defecto
+builder.Services.AddScoped<CreateOrderHandler>();
+builder.Services.AddSingleton<IClock, SystemClock>(); // stateless
+```
+
+## 2.3 Never Inject Scoped into Singleton — CRITICAL
+
+Es la "captured dependency": el Singleton retiene una instancia Scoped muerta tras el primer request → datos corruptos o `ObjectDisposedException`. Resolverlo bajo demanda con un scope.
+
+**Incorrecto:**
+```csharp
+public sealed class CacheWarmer(AppDbContext db) : IHostedService { } // Singleton captura DbContext Scoped
+```
+**Correcto:**
+```csharp
+public sealed class CacheWarmer(IServiceScopeFactory scopeFactory) : IHostedService
+{
+    public async Task StartAsync(CancellationToken ct)
+    {
+        await using var scope = scopeFactory.CreateAsyncScope();
+        var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();
+    }
+}
+```
+
+## 2.4 No Service Locator / No Manual BuildServiceProvider() — HIGH
+
+`provider.GetService<T>()` dentro de la lógica oculta dependencias y rompe los tests. `BuildServiceProvider()` en `Program.cs` crea un container paralelo (singletons duplicados, fugas). Inyectar por constructor (2.1).
+
+## 2.5 Register by Interface — HIGH
+
+Registrar contra la abstracción permite sustituir implementaciones (tests, features) sin tocar consumidores.
+
+```csharp
+builder.Services.AddScoped<IOrderRepository, EfOrderRepository>();
+```
+
+## 2.6 IOptions<T> Pattern for Config — MEDIUM-HIGH
+
+Bind tipado y validado de configuración, en vez de leer `IConfiguration` con strings por todo el código.
+
+```csharp
+builder.Services.AddOptions<JwtOptions>()
+    .Bind(builder.Configuration.GetSection("Jwt"))
+    .ValidateDataAnnotations()
+    .ValidateOnStart();
+// constructor(IOptions<JwtOptions> options) => _opts = options.Value;
+```
+
+_Ref: https://learn.microsoft.com/en-us/dotnet/core/extensions/dependency-injection · https://learn.microsoft.com/en-us/dotnet/core/extensions/options_

package/skills/dotnet-best-practices/references/devops.md

@@ -0,0 +1,76 @@
+# 10. DevOps & Deployment (LOW-MEDIUM)
+
+## 10.1 Multi-Stage Dockerfile, Non-Root User — MEDIUM
+
+Compilar con la imagen SDK y correr sobre la imagen `aspnet` runtime reduce el tamaño y la superficie de ataque. Usar un usuario no-root limita el blast radius.
+
+**Correcto:**
+```dockerfile
+FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
+WORKDIR /src
+COPY . .
+RUN dotnet publish -c Release -o /app
+
+FROM mcr.microsoft.com/dotnet/aspnet:10.0
+WORKDIR /app
+COPY --from=build /app .
+USER $APP_UID
+ENTRYPOINT ["dotnet", "Api.dll"]
+```
+
+## 10.2 Health Checks (Liveness/Readiness) — MEDIUM
+
+Los orquestadores (Kubernetes) necesitan endpoints separados: liveness (¿está vivo?) y readiness (¿puede recibir tráfico?, p. ej. DB conectada).
+
+**Correcto:**
+```csharp
+builder.Services.AddHealthChecks().AddNpgSql(conn, tags: ["ready"]);
+app.MapHealthChecks("/health/live", new() { Predicate = _ => false });
+app.MapHealthChecks("/health/ready", new() { Predicate = c => c.Tags.Contains("ready") });
+```
+
+## 10.3 Structured Logging (Serilog JSON) — MEDIUM
+
+Logs en JSON son parseables por agregadores (Loki, ELK). Serilog con sink de consola en formato compacto facilita la observabilidad.
+
+**Correcto:**
+```csharp
+builder.Host.UseSerilog((ctx, cfg) =>
+    cfg.WriteTo.Console(new Serilog.Formatting.Compact.CompactJsonFormatter()));
+```
+
+## 10.4 OpenTelemetry for Traces & Metrics — MEDIUM
+
+OpenTelemetry instrumenta traces y métricas de forma estándar y exportable a cualquier backend OTLP.
+
+**Correcto:**
+```csharp
+builder.Services.AddOpenTelemetry()
+    .WithTracing(t => t.AddAspNetCoreInstrumentation().AddOtlpExporter())
+    .WithMetrics(m => m.AddAspNetCoreInstrumentation().AddOtlpExporter());
+```
+
+## 10.5 Config per Environment & Graceful Shutdown — LOW-MEDIUM
+
+Nunca hardcodear secrets ni connection strings: usar `appsettings.{Environment}.json` y variables de entorno. Registrar limpieza ante el shutdown con `IHostApplicationLifetime`.
+
+**Correcto:**
+```csharp
+var conn = builder.Configuration.GetConnectionString("Default"); // env / appsettings, no hardcoded
+app.Lifetime.ApplicationStopping.Register(() => Log.Information("Draining connections..."));
+```
+
+## 10.6 CI: build, test, format — LOW
+
+El pipeline debe fallar ante código que no compila, tests rojos o formato inconsistente.
+
+**Correcto:**
+```yaml
+steps:
+  - run: dotnet restore
+  - run: dotnet build --no-restore -c Release
+  - run: dotnet test --no-build -c Release
+  - run: dotnet format --verify-no-changes
+```
+
+_Ref: https://learn.microsoft.com/en-us/dotnet/core/docker/build-container · https://learn.microsoft.com/en-us/aspnet/core/host-and-deploy/health-checks · https://learn.microsoft.com/en-us/dotnet/core/diagnostics/observability-with-otel · https://learn.microsoft.com/en-us/aspnet/core/fundamentals/host/generic-host_

package/skills/dotnet-best-practices/references/error-handling.md

@@ -0,0 +1,72 @@
+# 4. Error Handling (HIGH)
+
+## 4.1 Global IExceptionHandler + ProblemDetails — CRITICAL
+
+Respuestas de error consistentes y estandarizadas (RFC 7807) sin try/catch repetido en cada endpoint. Registrar `AddProblemDetails()` y un `IExceptionHandler`.
+
+**Correcto:**
+```csharp
+public sealed class GlobalExceptionHandler(ILogger<GlobalExceptionHandler> logger) : IExceptionHandler
+{
+    public async ValueTask<bool> TryHandleAsync(HttpContext ctx, Exception ex, CancellationToken ct)
+    {
+        logger.LogError(ex, "Unhandled exception on {Path}", ctx.Request.Path);
+        await Results.Problem(statusCode: StatusCodes.Status500InternalServerError, title: "An error occurred")
+            .ExecuteAsync(ctx);
+        return true;
+    }
+}
+// Program.cs
+builder.Services.AddProblemDetails();
+builder.Services.AddExceptionHandler<GlobalExceptionHandler>();
+app.UseExceptionHandler();
+```
+
+## 4.2 Don't Leak Stack Traces — CRITICAL
+
+En producción no exponer `ex.Message`, stack traces ni detalles internos: filtran rutas, versiones y vectores de ataque. Loggear el detalle, devolver un mensaje genérico (ver 4.1).
+
+## 4.3 Result Pattern for Expected Failures — HIGH
+
+Fallos esperados (validación, "not found", reglas de negocio) no son excepciones: las excepciones son caras y para lo excepcional. Devolver un `Result`.
+
+**Incorrecto:**
+```csharp
+if (order is null) throw new NotFoundException(); // control de flujo con excepciones
+```
+**Correcto:**
+```csharp
+public readonly record struct Result<T>(bool IsSuccess, T? Value, string? Error)
+{
+    public static Result<T> Ok(T value) => new(true, value, null);
+    public static Result<T> Fail(string error) => new(false, default, error);
+}
+return order is null ? Result<Order>.Fail("Order not found") : Result<Order>.Ok(order);
+```
+
+## 4.4 Validation → ValidationProblemDetails — HIGH
+
+Los errores de validación se devuelven como `ValidationProblemDetails` (400) con el mapa campo→errores, no como 500.
+
+```csharp
+return Results.ValidationProblem(new Dictionary<string, string[]>
+{
+    ["email"] = ["Email is required"]
+});
+```
+
+## 4.5 No Empty Catch; Log With Context — MEDIUM-HIGH
+
+`catch {}` oculta fallos y vuelve la app indebuggeable. Capturar tipos específicos, loggear con structured logging y re-lanzar o devolver un `Result`.
+
+**Incorrecto:**
+```csharp
+try { await Pay(ct); } catch { } // se traga el error
+```
+**Correcto:**
+```csharp
+try { await Pay(ct); }
+catch (PaymentException ex) { logger.LogError(ex, "Payment failed for {OrderId}", orderId); throw; }
+```
+
+_Ref: https://learn.microsoft.com/en-us/aspnet/core/fundamentals/error-handling · https://learn.microsoft.com/en-us/aspnet/core/web-api/handle-errors_

package/skills/dotnet-best-practices/references/performance.md

@@ -0,0 +1,63 @@
+# 6. Performance (HIGH)
+
+## 6.1 Output Caching & HybridCache — HIGH
+
+Cachear respuestas caras evita recomputar en cada request. `HybridCache` combina cache en memoria (L1) y distribuida (L2) con stampede protection.
+
+**Incorrecto:**
+```csharp
+app.MapGet("/stats", async (StatsService s) => await s.ComputeAsync()); // recomputa siempre
+```
+**Correcto:**
+```csharp
+builder.Services.AddHybridCache();
+
+app.MapGet("/stats", async (HybridCache cache, StatsService s, CancellationToken ct) =>
+    await cache.GetOrCreateAsync("stats", async token => await s.ComputeAsync(token), cancellationToken: ct));
+```
+
+## 6.2 Response Compression — HIGH
+
+Comprimir respuestas reduce el ancho de banda y la latencia percibida en payloads JSON grandes.
+
+**Correcto:**
+```csharp
+builder.Services.AddResponseCompression(o => o.EnableForHttps = true);
+var app = builder.Build();
+app.UseResponseCompression();
+```
+
+## 6.3 Never Block on Async (sync-over-async) — HIGH
+
+`.Result` o `.Wait()` bloquean un hilo del thread pool y pueden causar deadlocks y thread starvation bajo carga.
+
+**Incorrecto:**
+```csharp
+var user = _repo.GetUserAsync(id).Result; // bloquea el hilo
+```
+**Correcto:**
+```csharp
+var user = await _repo.GetUserAsync(id);
+```
+
+## 6.4 DbContext Pooling — MEDIUM-HIGH
+
+Reusar instancias de `DbContext` desde un pool reduce las allocations y el costo de setup por request.
+
+**Correcto:**
+```csharp
+builder.Services.AddDbContextPool<AppDbContext>(o =>
+    o.UseNpgsql(builder.Configuration.GetConnectionString("Default")));
+```
+
+## 6.5 Stream Large Results with IAsyncEnumerable — MEDIUM
+
+Devolver `IAsyncEnumerable<T>` transmite filas a medida que llegan en vez de materializar toda la colección en memoria.
+
+**Correcto:**
+```csharp
+app.MapGet("/orders", (AppDbContext db) =>
+    db.Orders.AsNoTracking().AsAsyncEnumerable()); // streaming, server GC ayuda en cargas altas
+```
+
+_Ref: https://learn.microsoft.com/en-us/aspnet/core/performance/caching/hybrid · https://learn.microsoft.com/en-us/aspnet/core/performance/response-compression · https://learn.microsoft.com/en-us/ef/core/performance/advanced-performance-topics_

package/skills/dotnet-best-practices/references/security.md

@@ -0,0 +1,73 @@
+# 5. Security (HIGH)
+
+## 5.1 Short-Lived JWT + Refresh Tokens — CRITICAL
+
+Access tokens cortos (5-15 min) limitan la ventana si se filtra uno; el refresh token (revocable, server-side) renueva sin re-login. Tokens de larga vida no se pueden invalidar.
+
+```csharp
+builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
+    .AddJwtBearer(o => o.TokenValidationParameters = new()
+    {
+        ValidateIssuer = true, ValidateAudience = true, ValidateLifetime = true,
+        ValidateIssuerSigningKey = true, ClockSkew = TimeSpan.FromSeconds(30)
+    });
+```
+
+## 5.2 Secrets in User-Secrets / Key Vault — CRITICAL
+
+Nunca claves ni connection strings en `appsettings.json` (van al repo). En dev `dotnet user-secrets`; en prod Azure Key Vault o variables de entorno.
+
+**Incorrecto:**
+```json
+{ "Jwt": { "Key": "super-secret-signing-key" } } // en el repo
+```
+**Correcto:**
+```csharp
+// dotnet user-secrets set "Jwt:Key" "..." (dev)
+builder.Configuration.AddAzureKeyVault(vaultUri, new DefaultAzureCredential()); // prod
+```
+
+## 5.3 Authorize by Policies, Not Manual Role Checks — HIGH
+
+Las policies centralizan la regla de autorización; los `if (user.Role == "Admin")` dispersos se desincronizan y se olvidan.
+
+**Incorrecto:**
+```csharp
+if (!ctx.User.IsInRole("Admin")) return Results.Forbid(); // lógica esparcida
+```
+**Correcto:**
+```csharp
+builder.Services.AddAuthorizationBuilder()
+    .AddPolicy("CanManageOrders", p => p.RequireRole("Admin").RequireClaim("scope", "orders:write"));
+app.MapPost("/orders", Handler).RequireAuthorization("CanManageOrders");
+```
+
+## 5.4 HTTPS, HSTS and Rate Limiting — HIGH
+
+Forzar HTTPS + HSTS evita downgrade/MITM. El middleware `RateLimiter` integrado protege de abuso y brute-force.
+
+```csharp
+builder.Services.AddRateLimiter(o => o.AddFixedWindowLimiter("api", w =>
+    { w.PermitLimit = 100; w.Window = TimeSpan.FromMinutes(1); }));
+app.UseHsts();
+app.UseHttpsRedirection();
+app.UseRateLimiter();
+```
+
+## 5.5 Don't Log Sensitive Data; Validate Input — HIGH
+
+Nunca loggear passwords, tokens ni PII. Validar todo input con FluentValidation. Las queries de EF Core son parametrizadas por defecto (no concatenar SQL crudo) y `[ValidateAntiForgeryToken]` donde haya cookies/formularios.
+
+```csharp
+public sealed class CreateOrderValidator : AbstractValidator<CreateOrderRequest>
+{
+    public CreateOrderValidator()
+    {
+        RuleFor(x => x.CustomerId).NotEmpty();
+        RuleFor(x => x.Items).NotEmpty();
+    }
+}
+// EF Core parametriza: db.Users.Where(u => u.Email == input) — nunca string-interpolated FromSqlRaw
+```
+
+_Ref: https://learn.microsoft.com/en-us/aspnet/core/security/authentication/configure-jwt-bearer-authentication · https://learn.microsoft.com/en-us/aspnet/core/performance/rate-limit_

package/skills/dotnet-best-practices/references/testing.md

@@ -0,0 +1,76 @@
+# 8. Testing (MEDIUM-HIGH)
+
+## 8.1 Integration Tests with WebApplicationFactory — HIGH
+
+`WebApplicationFactory<T>` levanta la app en memoria con el pipeline real (DI, middleware, routing), probando el comportamiento de verdad y no mocks.
+
+**Correcto:**
+```csharp
+public class OrdersApiTests(WebApplicationFactory<Program> factory)
+    : IClassFixture<WebApplicationFactory<Program>>
+{
+    [Fact]
+    public async Task GetOrders_ReturnsOk()
+    {
+        var client = factory.CreateClient();
+        var response = await client.GetAsync("/api/v1/orders");
+        response.StatusCode.Should().Be(HttpStatusCode.OK);
+    }
+}
+```
+
+## 8.2 Real Postgres via Testcontainers — HIGH
+
+El provider in-memory miente sobre el comportamiento relacional (transacciones, constraints, SQL). Testcontainers levanta un Postgres real y desechable.
+
+**Incorrecto:**
+```csharp
+options.UseInMemoryDatabase("test"); // no valida FKs, constraints ni SQL real
+```
+**Correcto:**
+```csharp
+var pg = new PostgreSqlBuilder().WithImage("postgres:17").Build();
+await pg.StartAsync();
+options.UseNpgsql(pg.GetConnectionString());
+```
+
+## 8.3 Don't Mock DbContext — MEDIUM-HIGH
+
+Mockear `DbContext` o `IQueryable` reimplementa LINQ-to-SQL en LINQ-to-Objects y da falsos verdes. Probar handlers/slices contra una base real.
+
+**Incorrecto:**
+```csharp
+var mock = new Mock<AppDbContext>(); // no traduce queries como el provider real
+```
+**Correcto:**
+```csharp
+var handler = new CreateOrderHandler(realDbContext);
+var result = await handler.Handle(command, CancellationToken.None);
+```
+
+## 8.4 Arrange-Act-Assert with FluentAssertions — MEDIUM
+
+Estructurar cada test en AAA y usar `FluentAssertions` para aserciones legibles y mensajes de error claros.
+
+**Correcto:**
+```csharp
+[Fact]
+public void Discount_AppliesPercentage()
+{
+    var order = new Order(100m);              // Arrange
+    order.ApplyDiscount(0.10m);               // Act
+    order.Total.Should().Be(90m);             // Assert
+}
+```
+
+## 8.5 Deterministic Tests — MEDIUM
+
+Evitar `DateTime.Now`, GUIDs aleatorios o dependencias de orden: inyectar `TimeProvider` para que los tests sean reproducibles.
+
+**Correcto:**
+```csharp
+var time = new FakeTimeProvider(new DateTimeOffset(2026, 1, 1, 0, 0, 0, TimeSpan.Zero));
+var service = new SubscriptionService(time); // sin reloj real, resultado estable
+```
+
+_Ref: https://learn.microsoft.com/en-us/aspnet/core/test/integration-tests · https://learn.microsoft.com/en-us/dotnet/core/testing/ · https://learn.microsoft.com/en-us/dotnet/architecture/microservices/multi-container-microservice-net-applications/test-aspnet-core-services-web-apps_

package/skills/dotnet-scaffold/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: dotnet-scaffold
+description: "Scaffold de API ASP.NET Core (.NET 10) production-ready: Vertical Slice o Clean Architecture, Minimal APIs, EF Core + PostgreSQL, JWT + Identity, ProblemDetails, health checks y testing. Usar para iniciar un backend .NET nuevo."
+category: "backend"
+argument-hint: "[project-name]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit, Task
+---
+# dotnet-scaffold — ASP.NET Core API Scaffolder
+
+## MANDATORY WORKFLOW
+
+**Antes de generar cualquier código, completar estos pasos en orden.** Confirmar las decisiones del Step 0 con el usuario antes de escribir archivos (Question → Decision → Approval).
+
+### Step 0: Gather Requirements
+1. **Nombre del servicio** (PascalCase para la solución, ej. `OrdersApi`)
+2. **Arquitectura:** Vertical Slice (default) / Clean Architecture — ver skill `dotnet-architecture` para elegir
+3. **Transport:** Web API REST con Minimal APIs (default) / Controllers / gRPC
+4. **ORM:** EF Core (default) / Dapper
+5. **DB:** PostgreSQL (default) / SQL Server
+6. **Auth:** JWT + ASP.NET Identity (default) / OAuth / ninguna
+7. **Deploy:** Docker (default) / Azure App Service
+
+> Si el dominio es CRUD/simple → **Vertical Slice**. Si es complejo y long-lived con varios devs → **Clean Architecture**.
+
+### Step 1: Crear base
+```bash
+dotnet new sln -n <Name>
+dotnet new webapi -n <Name>.Api                       # Minimal APIs (default en .NET 8+); para Controllers: --use-controllers
+dotnet sln add <Name>.Api
+dotnet new xunit -n <Name>.Tests && dotnet sln add <Name>.Tests
+cd <Name>.Api
+dotnet add package Npgsql.EntityFrameworkCore.PostgreSQL
+dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer
+dotnet add package Microsoft.AspNetCore.Identity.EntityFrameworkCore
+dotnet add package FluentValidation.DependencyInjectionExtensions    # core + DI; FluentValidation.AspNetCore (auto-validation) está deprecado
+dotnet add package Serilog.AspNetCore
+```
+
+### Step 2: Estructura
+
+**Vertical Slice (default)** — un folder por feature/use-case:
+```
+src/
+  Features/
+    Orders/   { CreateOrder.cs, GetOrder.cs, OrderEndpoints.cs }  # request+handler+validator+endpoint por slice
+    Users/    { ... }
+  Infrastructure/  { AppDbContext.cs, Migrations/ }
+  Common/    { Behaviors/, Results/, ProblemDetails/ }
+  Program.cs
+```
+
+**Clean Architecture** — proyectos por capa (deps apuntan hacia adentro):
+```
+<Name>.Domain/          # entities, value objects — cero deps externas
+<Name>.Application/      # use cases, interfaces (IAppDbContext), DTOs
+<Name>.Infrastructure/   # EF Core, Identity, implementaciones
+<Name>.Api/             # endpoints/controllers, DI, Program.cs
+```
+
+### Step 3: Defaults no negociables (`Program.cs` / `.csproj`)
+- `<Nullable>enable</Nullable>` + `<TreatWarningsAsErrors>true</TreatWarningsAsErrors>` en el `.csproj`
+- **Async end-to-end**: handlers `async Task<>`, `CancellationToken` propagado a EF Core y HTTP; nunca `.Result`/`.Wait()`
+- **DI por constructor** (primary constructors); registrar servicios con scope correcto (`AddScoped` para DbContext/handlers)
+- **Validación**: FluentValidation por slice, invocada manualmente (pipeline behavior MediatR o endpoint filter — no auto-validation) → responder `ValidationProblemDetails` (RFC 7807)
+- **Errores**: `AddProblemDetails()` + exception handler global → `ProblemDetails` consistente, sin filtrar stack traces
+- **EF Core**: migraciones versionadas (`dotnet ef migrations add`), **nunca** `EnsureCreated()` en prod; `DbContext` como Unit of Work (sin repos genéricos salvo necesidad)
+- **Auth**: JWT de vida corta + refresh, secretos en `user-secrets`/secret manager, authorization por policies declarativas
+- **Observabilidad**: Serilog structured logging (JSON) + health checks (`AddHealthChecks`) + OpenTelemetry opcional
+- **Graceful shutdown**: respetar `IHostApplicationLifetime` / `CancellationToken` del host
+
+### Step 4: Agregar piezas (invocar skills relacionadas)
+- `dotnet-architecture` — estructura de slices/capas en detalle
+- `database` / `data-migrations` — modelado EF Core + migraciones
+- `jwt-strategy` / `auth-strategy` / `rbac-abac` — auth y authorization
+- `api-design` / `api-versioning` / `api-docs` — contrato REST + OpenAPI
+- `testing` / `contract-testing` — xUnit + Testcontainers (Postgres real en tests)
+
+### Step 5: Verificar
+`dotnet build` + `dotnet test`. Revisar contra la rule `dotnet-code` y el skill `dotnet-best-practices`. Build + tests verdes → scaffold **READY**.
+
+## Stack Defaults
+
+| Componente | Default |
+|------------|---------|
+| Runtime | .NET 10 LTS (C# 14) |
+| Framework | ASP.NET Core — Minimal APIs |
+| Arquitectura | Vertical Slice (Clean opcional) |
+| ORM | EF Core 10 |
+| DB | PostgreSQL (Npgsql) |
+| Auth | JWT + ASP.NET Identity |
+| Validación | FluentValidation → ProblemDetails |
+| Logging | Serilog (JSON) |
+| Testing | xUnit + Testcontainers |
+| Deploy | Docker |
+
+---
+
+_Inspirado en [dotnet/skills](https://github.com/dotnet/skills) (oficial Microsoft), [github/awesome-copilot](https://github.com/github/awesome-copilot) (dotnet-best-practices) y los templates [ardalis/CleanArchitecture](https://github.com/ardalis/CleanArchitecture) y [nadirbad/VerticalSliceArchitecture](https://github.com/nadirbad/VerticalSliceArchitecture). Adaptado al formato Arcane._

package/skills/install-mcp/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: install-mcp
+description: "Instala y registra el MCP de Unity (CoplayDev MCP for Unity) en un proyecto Unity + Claude Code: agrega el package UPM, registra el server MCP y verifica la conexion. Usar para: instalar mcp unity, conectar Claude con Unity, setup MCP Unity."
+category: "gamedev"
+argument-hint: "[--secondary] [project-path]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit
+---
+# install-mcp — Unity MCP Setup
+
+Instala el package MCP del lado Unity y registra el server MCP en Claude Code, replicando el setup usado en los proyectos de tesis (TesisUade).
+
+- **Package primario:** `com.coplaydev.unity-mcp` (CoplayDev "MCP for Unity"). Server Python vía `uv`/`uvx`, transport HTTP en `127.0.0.1:8080`. El server se levanta y auto-configura desde Unity en `Window → MCP for Unity`.
+- **Package secundario (opcional, flag `--secondary`):** `com.gamelovers.mcp-unity` (CoderGamester). Server Node.
+
+> El flujo de Unity (`Window → MCP for Unity`) requiere la GUI del Editor — Claude no puede manejarla. La skill automatiza lo que sí puede (editar `manifest.json`, registrar el cliente MCP, verificar) y **guía** el paso del Editor.
+
+## Input
+
+- `project-path` (opcional): raíz del proyecto Unity. Default: directorio actual.
+- `--secondary` (opcional): además del primario, instala el package CoderGamester.
+
+---
+
+## Workflow
+
+### 1. Detectar proyecto Unity
+
+Desde `project-path` (o cwd), confirmar que existen:
+- `Packages/manifest.json`
+- `ProjectSettings/ProjectVersion.txt`
+
+Si falta alguno, **abortar** con: "No parece un proyecto Unity (falta Packages/manifest.json o ProjectSettings/ProjectVersion.txt). Pasá la ruta del proyecto con `/install-mcp <project-path>`."
+
+### 2. Verificar prerrequisitos
+
+- `uv --version` y `uvx --version` (server del primario). Si falta `uv`, **no abortar**: avisar y dar el comando de install y seguir editando el manifest:
+  - Windows: `winget install astral-sh.uv`
+  - alternativa: `pipx install uv`
+- Solo con `--secondary`: `node --version`. Si falta, avisar (el server CoderGamester no podrá correr).
+
+### 3. Agregar el package UPM (lado Unity)
+
+Leer `Packages/manifest.json`. Dentro de `"dependencies"`, agregar **solo si la key no existe** (idempotente — nunca duplicar):
+
+```json
+"com.coplaydev.unity-mcp": "https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main"
+```
+
+Con `--secondary`, agregar también:
+
+```json
+"com.gamelovers.mcp-unity": "https://github.com/CoderGamester/mcp-unity.git"
+```
+
+Usar `Edit` puntual sobre el bloque `dependencies` preservando el JSON válido (indentación, comas). Si la key ya estaba, reportar "ya presente, sin cambios".
+
+> **Antes de escribir**, mostrar el diff propuesto sobre `manifest.json` (y el `.mcp.json` del paso 4B si aplica) y pedir aprobación al usuario. No editar sin confirmación.
+
+### 4. Registrar el server MCP en Claude Code
+
+Dos caminos, en orden de preferencia:
+
+**A. Recomendado (auto-config desde Unity).** Instruir al usuario:
+1. Abrir el proyecto en Unity (Unity importará el package nuevo).
+2. `Window → MCP for Unity`.
+3. En esa ventana, usar el botón de auto-configuración para **Claude Code** — instala el server `uv` y registra el cliente MCP automáticamente.
+
+**B. Fallback manual.** Si el usuario no puede usar el Editor ahora, registrar el transport HTTP que usa CoplayDev:
+
+```bash
+claude mcp add --transport http unity-mcp http://127.0.0.1:8080
+```
+
+(equivalente: escribir un `.mcp.json` de proyecto con
+`{"mcpServers":{"unity-mcp":{"type":"http","url":"http://127.0.0.1:8080"}}}`).
+
+> El server solo responde cuando Unity está abierto con `MCP for Unity` activo. Registrar el cliente no levanta el server.
+
+### 5. Verificar
+
+Correr:
+
+```bash
+claude mcp list
+```
+
+Reportar si `unity-mcp` aparece **conectado**. Seguir la guía de TesisUade: **si NO está conectado, avisar explícitamente** y aclarar que las operaciones de engine (scenes, SOs, prefabs, UI wiring) NO se aplicaron — no asumir éxito.
+
+### 6. Resumen
+
+Reportar:
+- Qué keys se agregaron a `manifest.json` (o si ya estaban).
+- Estado del registro MCP (auto-config pendiente en Unity vs. fallback aplicado).
+- Resultado de `claude mcp list`.
+- Próximo paso manual: abrir Unity → `Window → MCP for Unity`.
+
+**Verdict:**
+- **READY** — package en `manifest.json` + cliente registrado + `unity-mcp` conectado en `claude mcp list`.
+- **PENDING** — package y cliente listos, pero falta abrir Unity (`Window → MCP for Unity`) para que el server conecte. Avisar que las operaciones de engine aún NO están disponibles.
+- **BLOCKED** — falta un prerrequisito (`uv` ausente) o no es un proyecto Unity válido. Indicar el fix.
+
+Tras conectar, seguir con `/unity-game-architecture` o `/scaffold-unity` para trabajar el proyecto.
+
+---
+
+> → Read references/manual-setup.md for [pasos detallados del flujo Window → MCP for Unity, troubleshooting (uv no encontrado, puerto 8080 ocupado, MCP no conecta) y la variante secundaria CoderGamester]