@ngxtm/devkit 3.11.0 → 3.12.0

package/merged-commands/skill/sync.md

@@ -0,0 +1,108 @@
+---
+description: Sync new skills from upstream repos with AI evaluation
+argument-hint: [options]
+---
+
+# Sync Skills from Upstream
+
+> AI-assisted upstream skill sync: fetch, evaluate, select, build.
+
+## Workflow
+
+### Step 1: Pre-flight Check
+
+Verify clean working directory:
+```bash
+git status --porcelain
+```
+If not clean → ask user to commit or stash first.
+
+### Step 2: Fetch Upstream
+
+Run the sync script to clone upstream repos and get a report:
+```bash
+npm run sync:upstream
+```
+
+This creates a sync branch and clones repos to temp directory.
+
+### Step 3: Evaluate New Skills
+
+After the script runs, it shows which skills are new. For each **new** skill:
+
+1. Read its `SKILL.md` from the temp directory
+2. Evaluate:
+   - **Useful**: Skill covers a distinct domain not already well-covered
+   - **Duplicate**: Similar skill already exists in the local collection
+   - **Irrelevant**: Too niche or low quality
+
+3. Present summary to user:
+```
+Upstream sync found N new skills:
+
+✅ Useful (X):
+  - skill-name: short reason
+  - skill-name: short reason
+
+⚠️ Possibly duplicate (Y):
+  - skill-name: overlaps with existing-skill
+
+❌ Skip (Z):
+  - skill-name: reason
+
+Sync options:
+  1. Sync all useful (X skills)
+  2. Sync all useful + duplicates (X+Y skills)
+  3. Let me choose manually
+```
+
+### Step 4: Copy Selected Skills
+
+Use `AskUserQuestion` to get user's choice. Then for selected skills:
+
+```bash
+cp -r /tmp/devkit-sync/{source}/{skill-name} ./skills/{skill-name}
+```
+
+### Step 5: Rebuild Indexes
+
+```bash
+npm run build
+```
+
+This regenerates all indexes (merged-commands, rules-index, skills-index, skills-compact).
+
+### Step 6: Review & Commit
+
+Show summary of changes:
+```bash
+git diff --stat
+```
+
+Ask user if they want to commit:
+```bash
+git add skills/ merged-commands/ SKILLS_INDEX.md skills-index.json skills-compact.json rules-index.json
+git commit -m "feat(skills): sync N new skills from upstream"
+```
+
+## Options
+
+- `$ARGUMENTS` can specify:
+  - `--auto`: Skip evaluation, sync all new skills automatically
+  - `--dry-run`: Only show report, don't copy anything
+  - A specific upstream name to sync from (e.g., `antigravity` or `agent-assistant`)
+
+## Evaluation Criteria
+
+When evaluating skills, consider:
+- Does it cover a technology the project uses or might use?
+- Is there already a similar skill? (check by name and description)
+- Is the SKILL.md well-structured with actionable content?
+- Is it too generic (just says "be a senior X engineer")?
+
+## Important
+
+- **NEVER** auto-sync without user confirmation (unless `--auto` flag)
+- **ALWAYS** run `npm run build` after copying skills
+- Keep the sync branch for PR review if needed
+- The temp directory is at the path shown by the sync script output

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@ngxtm/devkit",
-  "version": "3.11.0",
+  "version": "3.12.0",
   "description": "Per-project AI skills with smart tech detection - lightweight and context-optimized",
   "main": "cli/index.js",
   "bin": {
     "devkit": "cli/index.js"
   },
   "scripts": {
-    "build": "npm run merge-commands && npm run organize-rules && npm run generate-index",
+    "build": "npm run merge-commands && npm run organize-rules && npm run generate-index && npm run build-compact-index",
+    "build-compact-index": "node scripts/build-compact-index.js",
     "merge-commands": "node scripts/merge-commands.js",
     "organize-rules": "node scripts/organize-rules.js",
     "generate-index": "node scripts/generate-index.js",

package/rules-index.json

@@ -1,6 +1,6 @@
 {
   "version": "1.0.0",
-  "generatedAt": "2026-01-28T15:40:42.094Z",
+  "generatedAt": "2026-02-18T04:28:45.416Z",
   "templates": {
     "dart": {
       "path": "templates/dart/rules",
@@ -9,6 +9,13 @@
       ],
       "sizeKB": 4
     },
+    "dotnet": {
+      "path": "templates/dotnet/rules",
+      "rules": [
+        "dotnet"
+      ],
+      "sizeKB": 92
+    },
     "flutter": {
       "path": "templates/flutter/rules",
       "rules": [

package/scripts/merge-commands.js

@@ -38,7 +38,6 @@ const MERGE_STRATEGY = {
   'journal.md': 'claudekit',
   'kanban.md': 'claudekit',
   'preview.md': 'claudekit',
-  'scout.md': 'claudekit',
   'use-mcp.md': 'claudekit',
   'watzup.md': 'claudekit',
   'worktree.md': 'claudekit',

package/skills-index.json

@@ -1977,7 +1977,7 @@
   {
     "name": "learn",
     "path": "skills/learn",
-    "description": "Interactive step-by-step learning mode. Teaches concepts from basics to advanced while solving real problems. Auto-detects language, verifies code at each step, creates markdown tutorials. Triggers on"
+    "description": "Interactive learning mode. Teaches by doing with verified code, adaptive difficulty, and Socratic questioning."
   },
   {
     "name": "legacy-modernizer",

package/templates/base/rules/auto-skill.md

@@ -48,11 +48,12 @@ User Request → Extract keywords (react, auth, test, etc.)
 ### Step 1: Read Compact Index
 ```
 Read: .claude/skills-compact.json
-Format: { "_categories": {...}, "skills": { "skill-name": "category-code" } }
+Format: { "_categories": {...}, "skills": { "skill-name": { "c": "category", "d": "short description" } } }
+Note: Some skills may be just a category string if no description available.
 ```
 
 ### Step 2: Match by Name/Keyword
-Look for skills whose name contains user's keywords:
+Look for skills whose name OR description contains user's keywords:
 - User says "react" → find skills with "react" in name
 - User says "authentication" → find "auth" skills
 - User says "docker" → find "docker" skills

package/templates/base/rules/command-routing.md

@@ -0,0 +1,71 @@
+# Command Routing Guide
+
+> Help Claude choose the right command and execution mode for each task.
+
+## Decision Tree
+
+```
+Is this a learning/educational request?
+  → /learn
+
+Is this brainstorming/ideation only (no code)?
+  → /brainstorm
+
+Is this just planning (no implementation)?
+  → /plan
+
+Is this a bug fix?
+  → /fix (simple) or /fix:hard (complex)
+
+Is this a small, well-defined task?
+  → /cook:fast
+
+Is this a medium task with clear requirements?
+  → /cook:auto (auto: plan → code → commit)
+  → OR /plan → /code (manual control)
+
+Is this a complex, full-lifecycle feature?
+  → /cook:hard (includes brainstorm+research+plan+code+test+review)
+  → OR /brainstorm → /plan → /code (manual, more control)
+```
+
+## Anti-Patterns
+
+- **NEVER** chain `/brainstorm` → `/plan` before `/cook:hard` — it already includes both internally, causing duplicate work
+- **NEVER** use `/cook:hard` for trivial fixes — overkill, wastes context
+- **NEVER** use `/cook:fast` for complex features — skips research/design, leads to rework
+
+## Command Reference
+
+| Command | Complexity | Multi-Agent | Best For |
+|---------|-----------|-------------|----------|
+| `/cook:fast` | Low | Light (scouter, engineer) | Well-defined small tasks |
+| `/cook` | Medium | Yes (full team) | Standard feature work |
+| `/cook:auto` | Medium | Yes (plan → code → git) | Autonomous implementation |
+| `/cook:hard` | High | Full (8 phases, all agents) | Complex features from scratch |
+| `/brainstorm` | N/A | No | Ideation, design exploration |
+| `/plan` | N/A | Optional (researcher) | Creating implementation plans |
+| `/code` | Medium | Yes (tester, reviewer) | Executing an existing plan |
+| `/learn` | N/A | No | Interactive tutorials |
+| `/fix` | Low | No | Quick bug fixes |
+| `/fix:hard` | Medium | Yes (debugger, tester) | Complex debugging |
+
+## Multi-Agent Phases in /cook:hard
+
+```
+Phase 1: brainstormer  → Requirements discovery
+Phase 2: researcher    → Best practices research
+Phase 3: scouter       → Codebase analysis
+Phase 4: designer      → UI/UX design (if needed)
+Phase 5: planner       → Implementation plan
+Phase 6: tech-lead     → Routes to specialist engineers
+Phase 7: tester        → Testing
+Phase 8: reviewer      → Code review
+```
+
+## When to Suggest Skills
+
+After choosing the right command, check if a domain-specific skill would help:
+- User says "react" → suggest `/react-expert` skill alongside chosen command
+- User says "auth" → suggest `/auth-implementation-patterns` skill
+- See `auto-skill.md` for full detection flow

package/templates/dotnet/rules/dotnet/aspnet-core/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: ASP.NET Core Web API
+description: Modern ASP.NET Core patterns for building RESTful APIs.
+metadata:
+  labels: [aspnet, webapi, rest, minimal-api]
+  triggers:
+    files: ['**/*.cs', 'Program.cs']
+    keywords: [WebApplication, MapGet, MapPost, Controller, ApiController]
+---
+
+# ASP.NET Core Web API
+
+## **Priority: P1 (OPERATIONAL)**
+
+Modern ASP.NET Core patterns for building RESTful APIs.
+
+## Implementation Guidelines
+
+- **Minimal APIs**: Use for simple endpoints. `app.MapGet()`, route groups, endpoint filters.
+- **Controllers**: Use `[ApiController]` for automatic model validation and binding.
+- **Middleware**: Order matters. Custom middleware with `app.Use()`.
+- **Filters**: Action filters for cross-cutting concerns. Exception filters for error handling.
+- **Validation**: FluentValidation or DataAnnotations. Return `ProblemDetails` on errors.
+- **Versioning**: URL-based (`/api/v1/`) or header-based versioning.
+- **OpenAPI**: Always configure Swagger for API documentation.
+- **Response Types**: Use `TypedResults` for compile-time safety.
+
+## Anti-Patterns
+
+- **No `HttpClient` without `IHttpClientFactory`**: Socket exhaustion risk.
+- **No blocking async**: Never `.Result` or `.Wait()` in controllers.
+- **No business logic in controllers**: Controllers should only orchestrate.
+- **No returning `Task` without `async`**: Use `async` keyword or return directly.
+
+## Code
+
+```csharp
+// Minimal API with route groups
+var app = WebApplication.CreateBuilder(args).Build();
+
+var users = app.MapGroup("/api/users")
+    .WithTags("Users")
+    .RequireAuthorization();
+
+users.MapGet("/", async (IUserService service) =>
+    TypedResults.Ok(await service.GetAllAsync()));
+
+users.MapGet("/{id:int}", async (int id, IUserService service) =>
+    await service.GetByIdAsync(id) is { } user
+        ? TypedResults.Ok(user)
+        : TypedResults.NotFound());
+
+users.MapPost("/", async (CreateUserDto dto, IUserService service) =>
+{
+    var user = await service.CreateAsync(dto);
+    return TypedResults.Created($"/api/users/{user.Id}", user);
+}).AddEndpointFilter<ValidationFilter<CreateUserDto>>();
+
+// Controller with proper patterns
+[ApiController]
+[Route("api/[controller]")]
+[Produces("application/json")]
+public class OrdersController(IOrderService orderService) : ControllerBase
+{
+    [HttpGet("{id:int}")]
+    [ProducesResponseType<OrderDto>(StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status404NotFound)]
+    public async Task<IActionResult> GetOrder(int id, CancellationToken ct)
+    {
+        var order = await orderService.GetByIdAsync(id, ct);
+        return order is null ? NotFound() : Ok(order);
+    }
+
+    [HttpPost]
+    [ProducesResponseType<OrderDto>(StatusCodes.Status201Created)]
+    [ProducesResponseType<ValidationProblemDetails>(StatusCodes.Status400BadRequest)]
+    public async Task<IActionResult> CreateOrder(CreateOrderDto dto, CancellationToken ct)
+    {
+        var order = await orderService.CreateAsync(dto, ct);
+        return CreatedAtAction(nameof(GetOrder), new { id = order.Id }, order);
+    }
+}
+```
+
+## Reference & Examples
+
+For middleware, exception handling, and HttpClientFactory:
+See [references/REFERENCE.md](references/REFERENCE.md).
+
+## Related Topics
+
+security | razor-pages | blazor

package/templates/dotnet/rules/dotnet/aspnet-core/references/REFERENCE.md

@@ -0,0 +1,335 @@
+# ASP.NET Core Web API Reference
+
+Middleware, exception handling, and advanced patterns.
+
+## References
+
+- [**Middleware**](middleware.md) - Custom middleware patterns.
+- [**Exception Handling**](exception-handling.md) - Global error handling.
+- [**HttpClientFactory**](httpclient-factory.md) - Typed HTTP clients.
+
+## Global Exception Handling Middleware
+
+```csharp
+public class ExceptionMiddleware(
+    RequestDelegate next,
+    ILogger<ExceptionMiddleware> logger,
+    IHostEnvironment env)
+{
+    public async Task InvokeAsync(HttpContext context)
+    {
+        try
+        {
+            await next(context);
+        }
+        catch (Exception ex)
+        {
+            logger.LogError(ex, "Unhandled exception: {Message}", ex.Message);
+            await HandleExceptionAsync(context, ex);
+        }
+    }
+
+    private async Task HandleExceptionAsync(HttpContext context, Exception exception)
+    {
+        context.Response.ContentType = "application/problem+json";
+
+        var (statusCode, title) = exception switch
+        {
+            NotFoundException => (StatusCodes.Status404NotFound, "Not Found"),
+            ValidationException => (StatusCodes.Status400BadRequest, "Validation Error"),
+            UnauthorizedAccessException => (StatusCodes.Status401Unauthorized, "Unauthorized"),
+            ForbiddenException => (StatusCodes.Status403Forbidden, "Forbidden"),
+            _ => (StatusCodes.Status500InternalServerError, "Internal Server Error")
+        };
+
+        context.Response.StatusCode = statusCode;
+
+        var problem = new ProblemDetails
+        {
+            Status = statusCode,
+            Title = title,
+            Detail = env.IsDevelopment() ? exception.Message : null,
+            Instance = context.Request.Path
+        };
+
+        if (exception is ValidationException validationEx)
+        {
+            problem.Extensions["errors"] = validationEx.Errors;
+        }
+
+        await context.Response.WriteAsJsonAsync(problem);
+    }
+}
+
+// Registration
+app.UseMiddleware<ExceptionMiddleware>();
+```
+
+## Minimal API Endpoint Filters
+
+```csharp
+// Validation filter
+public class ValidationFilter<T> : IEndpointFilter where T : class
+{
+    public async ValueTask<object?> InvokeAsync(
+        EndpointFilterInvocationContext context,
+        EndpointFilterDelegate next)
+    {
+        var model = context.Arguments.OfType<T>().FirstOrDefault();
+
+        if (model is null)
+            return TypedResults.BadRequest("Request body is required");
+
+        var validator = context.HttpContext.RequestServices.GetService<IValidator<T>>();
+
+        if (validator is not null)
+        {
+            var result = await validator.ValidateAsync(model);
+            if (!result.IsValid)
+            {
+                return TypedResults.ValidationProblem(
+                    result.ToDictionary());
+            }
+        }
+
+        return await next(context);
+    }
+}
+
+// Logging filter
+public class LoggingFilter(ILogger<LoggingFilter> logger) : IEndpointFilter
+{
+    public async ValueTask<object?> InvokeAsync(
+        EndpointFilterInvocationContext context,
+        EndpointFilterDelegate next)
+    {
+        var path = context.HttpContext.Request.Path;
+        logger.LogInformation("Request started: {Path}", path);
+
+        var sw = Stopwatch.StartNew();
+        var result = await next(context);
+        sw.Stop();
+
+        logger.LogInformation("Request completed: {Path} in {ElapsedMs}ms",
+            path, sw.ElapsedMilliseconds);
+
+        return result;
+    }
+}
+
+// Usage
+app.MapPost("/api/users", handler)
+   .AddEndpointFilter<ValidationFilter<CreateUserDto>>()
+   .AddEndpointFilter<LoggingFilter>();
+```
+
+## IHttpClientFactory Typed Clients
+
+```csharp
+// Typed client
+public class PaymentClient(HttpClient httpClient)
+{
+    public async Task<PaymentResult?> ProcessPaymentAsync(PaymentRequest request)
+    {
+        var response = await httpClient.PostAsJsonAsync("/payments", request);
+        response.EnsureSuccessStatusCode();
+        return await response.Content.ReadFromJsonAsync<PaymentResult>();
+    }
+
+    public async Task<PaymentStatus?> GetStatusAsync(string paymentId)
+    {
+        return await httpClient.GetFromJsonAsync<PaymentStatus>($"/payments/{paymentId}");
+    }
+}
+
+// Registration with resilience
+builder.Services.AddHttpClient<PaymentClient>(client =>
+{
+    client.BaseAddress = new Uri(builder.Configuration["Payment:BaseUrl"]!);
+    client.DefaultRequestHeaders.Add("X-Api-Key",
+        builder.Configuration["Payment:ApiKey"]);
+    client.Timeout = TimeSpan.FromSeconds(30);
+})
+.AddStandardResilienceHandler(); // Polly retry, circuit breaker
+
+// Manual resilience configuration
+builder.Services.AddHttpClient<PaymentClient>()
+    .AddResilienceHandler("payment-pipeline", builder =>
+    {
+        builder
+            .AddRetry(new HttpRetryStrategyOptions
+            {
+                MaxRetryAttempts = 3,
+                Delay = TimeSpan.FromSeconds(1),
+                BackoffType = DelayBackoffType.Exponential
+            })
+            .AddCircuitBreaker(new HttpCircuitBreakerStrategyOptions
+            {
+                SamplingDuration = TimeSpan.FromSeconds(30),
+                FailureRatio = 0.5,
+                MinimumThroughput = 10,
+                BreakDuration = TimeSpan.FromSeconds(30)
+            })
+            .AddTimeout(TimeSpan.FromSeconds(10));
+    });
+```
+
+## Background Services
+
+```csharp
+public class OrderProcessingService(
+    IServiceScopeFactory scopeFactory,
+    ILogger<OrderProcessingService> logger) : BackgroundService
+{
+    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
+    {
+        logger.LogInformation("Order processing service started");
+
+        while (!stoppingToken.IsCancellationRequested)
+        {
+            try
+            {
+                await ProcessPendingOrdersAsync(stoppingToken);
+            }
+            catch (Exception ex)
+            {
+                logger.LogError(ex, "Error processing orders");
+            }
+
+            await Task.Delay(TimeSpan.FromMinutes(1), stoppingToken);
+        }
+    }
+
+    private async Task ProcessPendingOrdersAsync(CancellationToken ct)
+    {
+        using var scope = scopeFactory.CreateScope();
+        var orderService = scope.ServiceProvider.GetRequiredService<IOrderService>();
+
+        var pendingOrders = await orderService.GetPendingOrdersAsync(ct);
+
+        foreach (var order in pendingOrders)
+        {
+            await orderService.ProcessAsync(order.Id, ct);
+            logger.LogInformation("Processed order {OrderId}", order.Id);
+        }
+    }
+}
+
+// Registration
+builder.Services.AddHostedService<OrderProcessingService>();
+```
+
+## Health Checks
+
+```csharp
+// Registration
+builder.Services.AddHealthChecks()
+    .AddDbContextCheck<AppDbContext>("database")
+    .AddRedis(builder.Configuration.GetConnectionString("Redis")!, "redis")
+    .AddUrlGroup(new Uri("https://api.external.com/health"), "external-api")
+    .AddCheck<CustomHealthCheck>("custom");
+
+// Custom health check
+public class CustomHealthCheck(IOrderService orderService) : IHealthCheck
+{
+    public async Task<HealthCheckResult> CheckHealthAsync(
+        HealthCheckContext context,
+        CancellationToken ct = default)
+    {
+        try
+        {
+            var count = await orderService.GetPendingCountAsync(ct);
+
+            if (count > 1000)
+            {
+                return HealthCheckResult.Degraded(
+                    $"High pending orders: {count}");
+            }
+
+            return HealthCheckResult.Healthy();
+        }
+        catch (Exception ex)
+        {
+            return HealthCheckResult.Unhealthy("Order service unavailable", ex);
+        }
+    }
+}
+
+// Endpoints
+app.MapHealthChecks("/health", new HealthCheckOptions
+{
+    ResponseWriter = UIResponseWriter.WriteHealthCheckUIResponse
+});
+
+app.MapHealthChecks("/health/ready", new HealthCheckOptions
+{
+    Predicate = check => check.Tags.Contains("ready")
+});
+
+app.MapHealthChecks("/health/live", new HealthCheckOptions
+{
+    Predicate = _ => false // Just checks if app is running
+});
+```
+
+## Model Binding and Validation
+
+```csharp
+// FluentValidation
+public class CreateOrderDtoValidator : AbstractValidator<CreateOrderDto>
+{
+    public CreateOrderDtoValidator()
+    {
+        RuleFor(x => x.CustomerId)
+            .NotEmpty()
+            .WithMessage("Customer ID is required");
+
+        RuleFor(x => x.Items)
+            .NotEmpty()
+            .WithMessage("Order must have at least one item");
+
+        RuleForEach(x => x.Items).ChildRules(item =>
+        {
+            item.RuleFor(x => x.ProductId).NotEmpty();
+            item.RuleFor(x => x.Quantity).GreaterThan(0);
+        });
+
+        RuleFor(x => x.ShippingAddress)
+            .NotNull()
+            .SetValidator(new AddressValidator());
+    }
+}
+
+// Registration
+builder.Services.AddValidatorsFromAssemblyContaining<CreateOrderDtoValidator>();
+
+// Pipeline behavior for MediatR
+public class ValidationBehavior<TRequest, TResponse>(
+    IEnumerable<IValidator<TRequest>> validators)
+    : IPipelineBehavior<TRequest, TResponse>
+    where TRequest : notnull
+{
+    public async Task<TResponse> Handle(
+        TRequest request,
+        RequestHandlerDelegate<TResponse> next,
+        CancellationToken ct)
+    {
+        if (!validators.Any())
+            return await next();
+
+        var context = new ValidationContext<TRequest>(request);
+        var results = await Task.WhenAll(
+            validators.Select(v => v.ValidateAsync(context, ct)));
+
+        var failures = results
+            .SelectMany(r => r.Errors)
+            .Where(f => f != null)
+            .ToList();
+
+        if (failures.Count != 0)
+            throw new ValidationException(failures);
+
+        return await next();
+    }
+}
+```