
Use when adding database persistence to a Truenorth.Components.* library, migrating legacy persistence code to the standard pattern, or adding new entities to an existing component following the stored-procedure-only architecture with EXECUTE-only permissions. Covers the 8-artifact pattern: embedded settings, language constants, static repository, component factory, DbMappings, Insert/Update/Delete commands, SelectAll/SelectById/Exists queries, and a CrudPersistenceHelper-based persistence service with IList/IListCollectable/ITableCollectable output variants. Domain: Data Access / Persistence. Level: Advanced. Tags: persistence, stored-procedure, CRUD, ADO.NET, provider-agnostic.
Use when building a .NET library distributed via NuGet that needs default configuration values shipped with the assembly, when you want zero-configuration defaults that just work without file deployment, or when consumers need to override library settings via standard appsettings.json patterns. Covers three-tier configuration precedence: embedded JSON defaults compiled into the assembly via EmbeddedResource, consumer appsettings.json overrides, and hardcoded fallback values, plus the EmbeddedConfigLoader and LogicalName conventions. Domain: .NET Library Design, Configuration. Level: Intermediate. Tags: configuration, embedded-resource, nuget, library-defaults, appsettings.
Use when raising and handling domain events within a bounded context, decoupling domain logic from side-effect infrastructure (notifications, audit, read-model projections), or when multiple independent reactions to the same domain change are directly calling services from the entity or use case handler. Covers in-process dispatch via MediatR INotification, a manual IDomainEventDispatcher with IServiceProvider, and EF Core SaveChanges integration to dispatch events after the transaction commits. Domain: Domain-Driven Design, Architecture. Level: Intermediate. Tags: domain-events, ddd, mediatr, event-dispatch, decoupling.
Use when performing batch inserts, updates, or deletes on large datasets, running scheduled cleanup or archive jobs, or when EF Core's default SaveChangesAsync is generating thousands of individual SQL statements causing timeouts or lock contention. Covers EF Core 7+ ExecuteUpdate/ExecuteDelete for single-statement bulk ops, chunked SaveChanges with ChangeTracker.Clear to prevent memory growth, and BulkExtensions for high-volume import/upsert scenarios. Domain: Data Access, Performance. Level: Intermediate. Tags: bulk, batch, ef-core, performance, execute-update, execute-delete.
Use when adding versioning to HTTP APIs, introducing a breaking change to an existing API contract, or when you need to deprecate an old API version with a sunset protocol. Covers URL segment, query string, header, and media type strategies, Asp.Versioning setup, deprecation headers with Sunset dates, and breaking vs. additive change classification rules. Domain: API Design, REST. Level: Intermediate. Tags: api-versioning, rest, breaking-changes, deprecation, minimal-api.
Use when implementing background work, queued processing, or recurring tasks, or when replacing fire-and-forget Task.Run calls that lose exceptions silently. Covers BackgroundService with PeriodicTimer, Channel<T> for high-performance producer-consumer pipelines, IServiceScopeFactory for per-iteration DI scopes, and graceful shutdown with CancellationToken propagation. Domain: Infrastructure, Concurrency, Worker Patterns. Level: Intermediate. Tags: background-service, hosted-service, channels, worker, periodic-timer.
Use when deciding between IMemoryCache, IDistributedCache, Response Caching, or Output Caching, or when caching is applied inconsistently across a codebase and a decision framework is needed. Covers a decision matrix by data volatility and deployment topology, cache key design conventions, invalidation strategies (TTL, event-based, versioned, tag-based), and stampede prevention with GetOrCreateAsync. Domain: Performance, Architecture. Level: Intermediate. Tags: caching, IMemoryCache, IDistributedCache, Redis, performance, output-caching.
Use when onboarding to the workspace structure for a coding assistant context. Explains the layered context model: root instruction file as baseline, skills for task prompts and reference knowledge, agents for multi-step workflows.
Use when a search, filter, or query method has more than 2–3 optional parameters and the parameter list keeps growing, or when adding a new filter requires changing method signatures across multiple call sites. Covers the typed criteria object pattern (e.g., ProductCriteria), conditional LINQ filtering, paged variants with IPagedRequest, and naming conventions for ByCriteria, ById, and Paged overloads. Domain: Architecture, Query Design. Level: Foundational. Tags: criteria, query, filtering, search, specification.
Use when diagnosing slow EF Core queries, N+1 problems, or unexpected SQL generation. Covers query logging, AsNoTracking, Include chains, projection fixes, and compiled queries. Invoke when a LINQ query generates more SQL than expected, a page loads slowly due to database calls, Include chains produce Cartesian explosion, or tracking is unnecessary on read-only queries. Also trigger when the user asks: why is my EF query slow, N+1 problem, fix EF query, EF SQL logging, AsNoTracking, Include performance, compiled query, EF Core optimization. Domain: EF Core / Data Access. Level: Intermediate.
Use when implementing or reviewing GoF design patterns (Factory, Strategy, Decorator, Observer, etc.) in .NET — provides canonical C# implementations, when-to-use, and when-NOT-to-use guidance.
Use when designing EF Core entities, relationships, value objects, owned types, inheritance strategies, Fluent API configuration, migrations, schema changes, DbContext design, data access patterns, repository implementations, or querying strategies. Provides domain-specific rules layered on top of base architectural standards.
Use when implementing feature flags for trunk-based development with incomplete features behind toggles, progressive rollouts (canary, percentage, time-window), per-tenant feature sets, optional AI or premium features, or kill switches that disable production features without redeployment. Covers Microsoft.FeatureManagement, IFeatureManager, built-in and custom feature filters, endpoint and middleware gating, feature flag constants, and flag lifecycle management from creation through removal. Domain: Release Management, Configuration, Progressive Delivery. Level: Intermediate. Tags: feature-flags, feature-management, feature-toggles, progressive-delivery, canary.
Use when managing which features are scaffolded into the coding assistant workspace. Covers ai-context new --features, manifest tracking, and ai-context update to reconcile feature changes across targets.
Use when generating a new agent markdown file for the Truenorth KB — either a filter agent (executes a single concern) or an orchestrator (coordinates other agents). Invoked by the Apex Orchestrator in Create mode, or directly when the user asks to create a new agent, add a reviewer, scaffold an orchestrator, or register a new agent role. Produces a fully compliant agent markdown with all required sections, dispatching protocol, gate protocol, quality checklist, and STATUS line. Domain: KB Evolution, AI Architecture. Level: Advanced. Tags: meta, kb-evolution, agent-generation, apex.
Scaffold a complete Blazor Server documentation and demo site for a .NET library or tool. Produces a content-driven app with typed data models, in-memory content service, lazy-indexed search, dark-theme layout, and multiple page types (home, list+detail, search, knowledge map). Use for library showcases, learning tools, and interactive documentation. Invoke when the user says: create a demo site, scaffold a Blazor docs site, build a library showcase, interactive documentation site, generate a Blazor demo app. Domain: UI, Documentation. Level: Intermediate.
Use when onboarding developers to an unfamiliar codebase, documenting a complex architectural flow across multiple files, or creating guided walkthroughs for code reviews. Generates VSCode CodeTour JSON files with progressive disclosure — starting from high-level architecture and drilling into implementation details. Domain: Documentation, Onboarding. Level: Intermediate. Tags: code-tour, onboarding, walkthrough, documentation, progressive-disclosure, vscode.
Use when scaffolding a new CQRS command or query handler. Generates a request record, response DTO, FluentValidation validator, MediatR handler class, and xUnit test shell. Also invoke when the user mentions: add a command, create a query, new handler, new use-case handler, MediatR handler. Domain: Code Generation, CQRS. Level: Intermediate.
Use when wiring a new application module into the DI container. Generates an IServiceCollection extension method composition root with options validation, safe-copy overload, and convenience helpers. Do NOT use for static black-box libraries — use gen-factory-class instead. Also invoke when the user mentions: DI registration, AddMyModule, composition root, service registration extension. Domain: Code Generation, Dependency Injection. Level: Intermediate.
Use when creating a static factory for a strategy or provider pattern in a black-box library (no DI container). Generates a thread-safe cached static factory dispatching by enum key with typed convenience methods. Also invoke when the user mentions: static factory, provider factory, enum-keyed factory, library factory pattern. Domain: Code Generation, Design Patterns. Level: Intermediate.
Use when setting up or cleaning up global using directives for a project. Generates a categorized GlobalUsings.cs based on the project's NuGet dependencies and internal namespaces, with section comments. Also invoke when the user mentions: global usings, add GlobalUsings.cs, organize usings, implicit usings. Domain: Code Generation. Level: Beginner.
Use when adding a new background service or worker to a .NET application. Generates a BackgroundService subclass, options class, DI registration, and health check — for periodic timers or Channel<T> queue-based work. Also invoke when the user mentions: background service, hosted service, IHostedService, background worker, timer-based service. Domain: Code Generation, Infrastructure. Level: Intermediate.
Use when you need a fake or stub implementation of a service for demos, local development, or testing without a real backend. Generates an in-memory class that implements the real service interface, with seed data, realistic delays, and DI registration that can be swapped. Also invoke when the user mentions: fake service, in-memory stub, demo service, mock service for dev, test double. Domain: Code Generation, Testing. Level: Intermediate.
Use when designing indexes for new tables, diagnosing slow queries that are not using indexes efficiently, reviewing index fragmentation and maintenance, or when the current indexing strategy results in key lookups, table scans, or missing index warnings. Covers clustered index key selection (narrow, unique, ever-increasing), non-clustered index design for query patterns, covering indexes with INCLUDE columns, filtered indexes for subset queries, composite index column ordering, DMV-based monitoring for missing and unused indexes, and rebuild vs reorganize maintenance thresholds. Domain: Database, Performance. Level: Intermediate. Tags: index, sql-server, covering-index, filtered-index, performance, dmv, maintenance.
Use when scaffolding a new Minimal API endpoint or route group. Generates request/response records, FluentValidation validators, and handler wiring following the one-concern-per-group rule. Also invoke when the user mentions: new endpoint, new route, minimal API, MapGroup, add HTTP endpoint. Domain: Code Generation, API. Level: Intermediate.
Use when adding strongly-typed configuration to a .NET service or library. Generates an options interface, concrete class with sensible defaults, EnsureValid() startup validation, and the matching appsettings.json section. Also invoke when the user mentions: options class, IOptions, configuration class, appsettings section, settings class. Domain: Code Generation, Configuration. Level: Beginner.
Use when adding a new repository to a feature. Generates an IRepository interface and EF Core implementation with AsNoTracking read methods, write methods, and unit/integration test stubs. Also invoke when the user mentions: new repository, add data access, EF repository, create repository class. Domain: Code Generation, Data Access. Level: Intermediate.
Use when adding retry or resilience handling to an HTTP client or external dependency call. Generates a Polly v8 policy with exponential backoff, transient error detection, jitter, and an observability callback. Also invoke when the user mentions: add retry, resilience policy, Polly policy, transient fault handling. Domain: Code Generation, Resilience. Level: Intermediate.
Use when defining the public contract for a new domain service or application service. Generates a CQS-categorized interface with Commands, Queries, Validators, a Criteria class, and XML doc comments. Also invoke when the user mentions: service interface, IMyService, define service contract, add service interface, application service interface. Domain: Code Generation, Architecture. Level: Intermediate.
Use when adding real-time push communication to an ASP.NET Core application. Generates a strongly-typed SignalR hub with a client interface, group management, DI registration, and authorization attributes. Also invoke when the user mentions: SignalR hub, real-time hub, WebSocket hub, push notifications, Hub class. Domain: Code Generation, Real-Time. Level: Intermediate.
Use when creating a test class for a source file or when no tests exist yet for a class. Generates a convention-compliant xUnit test class covering all six coverage categories (happy path, validation, not-found, cancellation, invariants, round-trip). Pairs with gen-gherkin-feature (upstream criteria) and gen-use-case (upstream model). Also invoke when the user mentions: write tests, add unit tests, test class, xUnit tests for, test coverage. Domain: Testing, Code Generation. Level: Intermediate.
Use when capturing a feature requirement as a user story before writing use cases or tests. Generates a story card with role, capability, benefit, acceptance criteria, and MoSCoW priority. Pairs with gen-use-case (downstream). Also invoke when the user mentions: user story, As a user, feature card, story card, acceptance criteria. Domain: Requirements, Agile. Level: Beginner.
Generate a comprehensive root instruction file for any repository by discovering the project structure, validating every command, and embedding universal architectural principles. Verbose variant with full output template. Invoke when the user says: generate verbose instructions, create comprehensive copilot instructions, bootstrap root instruction file, full instructions template, generate CLAUDE.md. Domain: DevOps, AI Context. Level: Intermediate.
Use when working with gRPC services, protobuf definitions, Protocol Buffers, streaming RPCs, interceptors, or gRPC client configuration in .NET. Provides domain-specific rules layered on top of base architectural standards.
Use when deploying an ASP.NET Core application to Azure App Service, Kubernetes, or any cloud platform that requires health probes, or when load balancers need to route around unhealthy instances and deployment slots must verify readiness before traffic swap. Covers AddHealthChecks registration, liveness vs readiness probe separation with tag-based filtering, custom IHealthCheck implementations, structured JSON response format, and platform-specific configuration for Azure App Service, Kubernetes, and Docker Compose. Domain: Cloud Readiness, Observability. Level: Foundational. Tags: health-check, cloud-native, monitoring, azure, kubernetes, observability.
Use when collecting real-time telemetry or analytics with concurrent access, tracking in-process events without external infrastructure, or building lightweight admin dashboards showing usage statistics. Implements thread-safe counters and bounded event streams using ConcurrentDictionary and ConcurrentQueue to prevent memory growth under concurrent writes. Domain: Telemetry, In-Process Analytics. Level: Intermediate. Tags: analytics, concurrent-collections, telemetry, in-memory, event-tracking.
Use when adding an AI assistant that answers domain-specific questions, building a documentation chatbot, or when you need contextual AI without vector database infrastructure. Implements RAG-lite: inject the relevant knowledge subset into the system prompt based on the user's question using an in-memory registry — no embeddings API required. Domain: AI Integration, LLM, RAG-lite. Level: Advanced. Tags: ai, chatbot, rag, microsoft-extensions-ai, system-prompt, knowledge-injection, streaming, temperature.
Use when designing or choosing a multi-step AI workflow, deciding between an autonomous agent and a structured workflow, or when a task requires more than one LLM call and you need a pattern to orchestrate them reliably. Covers the five agentic workflow patterns — prompt chaining, routing, parallelization (sectioning and voting), orchestrator-workers, and evaluator-optimizer — when to use each, and how they map to the Truenorth agent and skill hierarchy. Domain: AI Architecture, Orchestration. Level: Advanced. Tags: agentic, workflows, orchestration, prompt-chaining, routing, parallelization, evaluator-optimizer.
Use when designing or reviewing RESTful HTTP APIs, endpoint routing, status codes, pagination, error responses, or OpenAPI specs in .NET projects.
Use when designing, reviewing, or enforcing interface-first API contracts, public API surfaces, or cross-library type signatures in .NET projects.
Use when protecting a service from repeatedly calling a failing dependency, when retry logic alone keeps hammering an already-down service, or when you need to fail fast after sustained failures and probe cautiously for recovery. Covers the three-state circuit breaker (Closed → Open → Half-Open), Polly v8 ResiliencePipeline configuration with FailureRatio and MinimumThroughput tuning, and correct retry + circuit breaker composition order. Domain: Resilience, Fault Tolerance. Level: Intermediate. Tags: circuit-breaker, resilience, polly, fault-tolerance, state-machine.
Use when implementing or reviewing CQRS with MediatR — command handlers, query handlers, pipeline behaviors, or request/response patterns in .NET projects.
Use when choosing DI lifetimes, diagnosing a 'Cannot consume scoped service from singleton' error, or when a singleton is holding stale data from a captured DbContext. Covers Singleton vs Scoped vs Transient decision matrix, the captive dependency trap and how to detect it with ValidateScopes, IServiceScopeFactory for singletons that need scoped services, keyed services (.NET 8+), and common DI registration anti-patterns. Domain: Dependency Injection, Architecture. Level: Intermediate. Tags: dependency-injection, di, lifetime, scoped, singleton, captive-dependency.
Use when designing new database schemas, reviewing existing schemas for normalization issues, choosing data types for SQL Server columns, adding temporal tables or partitioning to large datasets, or when schema decisions impact query performance and data integrity. Covers normalization through BCNF with denormalization decision criteria, SQL Server data type selection (narrowest type principle, VARCHAR vs NVARCHAR, DATETIME2 vs DATETIME), constraint design at the database level (PK, FK, UNIQUE, CHECK, DEFAULT), schema organization for security boundaries, temporal tables with retention policies, table partitioning for lifecycle-managed data, row-level security for multi-tenant systems, and schema anti-patterns (EAV misuse, God tables, polymorphic associations). Domain: Database, Architecture. Level: Intermediate. Tags: schema-design, normalization, data-types, temporal-tables, partitioning, row-level-security, constraints.
Use when implementing structured logging with correlation IDs across service boundaries, diagnosing requests that cannot be traced end-to-end across services, or when log messages use string interpolation causing allocations on every call. Covers LoggerMessage source generator for zero-allocation logging, correlation ID middleware, W3C trace context propagation via Activity, OpenTelemetry integration, log scope context, and PII scrubbing rules. Domain: Observability, Logging, Tracing. Level: Intermediate. Tags: logging, correlation-id, opentelemetry, structured-logging, tracing.
Use when diagnosing or improving slow EF Core queries, fixing N+1 problems, eliminating cartesian explosions from multi-level Includes, or when API endpoints are loading full entities when only a few columns are needed. Covers DTO projections with Select, AsNoTracking and AsNoTrackingWithIdentityResolution, AsSplitQuery to prevent cartesian explosions, compiled queries for hot paths, query tags for SQL profiler identification, filtered Includes, and slow-query interceptors. Domain: Data Access, Performance. Level: Advanced. Tags: ef-core, performance, query, sql, optimization.
Use when a Blazor or web application needs intentional visual design beyond default Bootstrap styling, when scaffolding a greenfield app that should look polished rather than generic, or when the design brief requires aesthetic direction (typography, color, motion, spatial composition). Covers the design thinking process, aesthetic vocabulary, font pairing, color palette composition, animation patterns for Blazor, and anti-generic design principles. Domain: UI, Visual Design, Blazor. Level: Intermediate. Tags: design, typography, color, animation, aesthetics, layout, blazor, visual-quality.
Bootstrap a copilot-instructions.md for any repository by discovering the project structure, validating every command, and embedding universal architectural principles. Use this for foreign repos or non-.NET projects. For your own .NET solutions, use New-CopilotContext.ps1 instead. Invoke when the user says: create copilot instructions, bootstrap instructions file, add copilot-instructions.md, generate agent instructions for this repo, set up AI coding guidelines. Domain: DevOps, AI Context. Level: Intermediate.
Scaffold a complete new component in one pass: settings class, interface, concrete implementation, DI registration (or static factory for libraries), and a test shell. Use this for new components from scratch; use gen-service-interface, gen-options-class, or gen-di-composition-root for targeted retrofits. Invoke when the user says: create a new service, scaffold a component, generate a class, new provider, new handler, add a component to the project. Domain: Code Generation, Architecture. Level: Intermediate.
Use when a .NET library needs to ship sensible default configuration that consumers can override without editing source. Generates a 3-tier config system: embedded JSON defaults, appsettings.json overrides, and environment variable overrides via a static accessor. Also invoke when the user mentions: embedded config, library defaults, appsettings override, embedded resource settings. Domain: Code Generation, Configuration. Level: Intermediate.
Use when formalizing acceptance criteria from a use case into executable Gherkin scenarios. Generates a .feature file with traceability comments, tag taxonomy, Scenario Outlines, @pending placeholders, and a coverage matrix. Pairs with gen-use-case (upstream) and gen-test-class (downstream). Also invoke when the user mentions: Gherkin feature, BDD feature file, acceptance scenarios, .feature file, Cucumber/SpecFlow feature. Domain: Testing, BDD. Level: Intermediate.
Use when adding custom middleware to an ASP.NET Core pipeline. Generates a middleware class for a single cross-cutting concern (e.g., request logging, correlation ID, tenant resolution) and an IApplicationBuilder extension method. Also invoke when the user mentions: custom middleware, pipeline middleware, request middleware, ASP.NET middleware class. Domain: Code Generation, Infrastructure. Level: Intermediate.
Use when a sub-project, module, or layer needs its own scoped AI coding instructions layered on top of the root instructions. Generates a .instructions.md with the correct applyTo glob, architecture decisions, conventions, and anti-patterns. Also invoke when the user mentions: scoped instructions, sub-project instructions, module instructions, feature instructions file. Domain: DevOps, AI Context. Level: Intermediate.
Use when generating a new skill document for the Truenorth KB — knowledge artifacts that provide domain-specific guidance, templates, patterns, or procedures. Invoked by the Apex Orchestrator in Create mode, or directly when the user asks to create a skill, add a how-to guide, scaffold a best-practices document, or register a new knowledge artifact. Produces a fully compliant SKILL.md with problem statement, context, procedure, examples, and checklist. Domain: KB Evolution, AI Architecture. Level: Advanced. Tags: meta, kb-evolution, skill-generation, apex.
Use when documenting a feature's business behavior before implementation. Generates a use case document (Manage X template) with Main Scenario, Extensions, Data Structures, Business Rules, and Pending Issues. Pairs with gen-user-story (upstream) and gen-gherkin-feature (downstream). Also invoke when the user mentions: use case document, UC document, business scenario, feature specification, requirements doc. Domain: Requirements, Analysis. Level: Intermediate.
Use when creating a new .NET Worker Service project for background processing, scheduled tasks, or long-running daemons. Generates a full project scaffold: BackgroundService, options class, health check, and DI registration. Also invoke when the user mentions: worker service, new worker project, dotnet worker, background processor project. Domain: Code Generation, Infrastructure. Level: Intermediate.
Use when writing any public method that receives parameters, adding guard clauses to existing code, or when a NullReferenceException or ArgumentException is bubbling from deep in the call stack and you need to standardize validation at the entry boundary. Covers ArgumentNullException.ThrowIfNull, ArgumentException.ThrowIfNullOrWhiteSpace, ArgumentOutOfRangeException range guards, a custom Guard static helper with CallerArgumentExpression, and Design by Contract precondition patterns. Domain: Defensive Programming, API Design. Level: Foundational. Tags: validation, guard-clauses, defensive-programming, fail-fast, argument-validation.
Use when writing integration tests for Razor Pages, MVC, or Minimal API applications to validate routing, middleware, page rendering, and HTTP behavior without a browser or live server, or when adding fast smoke tests to a CI pipeline. Covers WebApplicationFactory<Program> setup with public partial class Program, in-memory test server, AngleSharp HTML parsing, CSS selector assertions, redirect and status code testing, and a shared static fixture pattern for minimal per-test startup overhead. Domain: Testing, ASP.NET Core. Level: Intermediate. Tags: integration-testing, webapplicationfactory, razor-pages, anglesharp, http-testing.
Use when building a searchable in-memory catalog or registry for documentation sites, admin panels, or type/API browsers where you need keyword matching, fuzzy search, and ranked results without an external search engine or database. Covers RegistryService with weighted scoring across name, description, keywords, and method names; Levenshtein fuzzy matching; synonym expansion; category and subcategory filtering; and singleton DI registration for datasets of hundreds to low thousands of items. Domain: Search, Data Access Patterns. Level: Intermediate. Tags: search, registry, fuzzy-matching, in-memory, catalog, filtering.
Use when working with authentication, authorization, OAuth, JWT, identity, RBAC, claims, or secrets management in .NET projects. Provides domain-specific rules layered on top of base architectural standards.
Use when working with Blazor Server or WebAssembly components, Razor markup, SignalR, render modes, or interactive server patterns. Provides domain-specific rules layered on top of base architectural standards.
Use when cross-cutting concerns (logging, metrics, validation, authorization) are tangled into command handlers or service methods, when building database command pipelines with reorderable concerns, or when HTTP client pipelines or message handlers need composable, independently-replaceable processing stages. Covers ICommandInterceptor interface, InterceptorPipeline with reverse-chain construction, zero-cost Empty sentinel to skip overhead when no interceptors are registered, and ConfigureAwait(false) discipline for library code. Domain: Architecture, Cross-Cutting Concerns. Level: Intermediate. Tags: interceptor, pipeline, middleware, decorator, cross-cutting-concerns.