mcj-coder · martincjarvis · Jan 17, 2026 · Jan 17, 2026
@@ -20,6 +20,25 @@ all times. If you cannot prove context or tooling, stop and fix that first.
 If an issue-driven workflow is required (work item comments, approvals, evidence tracking),
 use `issue-driven-delivery`.
 
+## When to Use
+
+- Agent is asked to autonomously manage a work item (GitHub, Azure DevOps, or Jira)
+- Comment mentions the agent with a task verb (e.g., "manage", "handle", "take", "own")
+- Need to resolve task board source, platform CLI, or step updates
+- Automating delivery flow across ticketing systems
+- Setting up CI/CD workflows triggered by ticket events
+
+## Core Workflow
+
+1. **Discovery**: Read README.md, locate Work Items section, infer platform from URL
+2. **Setup**: Verify CLI is installed and authenticated for the platform
+3. **Load ticket**: Fetch issue details, comments, acceptance criteria, and related PRs
+4. **Execute step**: Determine and execute only the next required step
+5. **Post update**: Comment with Summary, Evidence, Next Step, and Hand-off status
+6. **Update checklist**: Mark completed items in the issue body
+7. **Verify completion**: Use verification-before-completion for all acceptance criteria
+8. **Close or hand-off**: Close when complete with evidence, or hand off to human if blocked
+
 ## End-to-End Autonomous Delivery Flow
 
 Autonomous delivery follows four explicit phases:

@@ -18,6 +18,14 @@ must understand how to work in the repository by reading only AGENTS.md.
 **REQUIRED SUB-SKILL:** `superpowers:brainstorming`
 **REQUIRED SUB-SKILL:** `superpowers:verification-before-completion`
 
+## When to Use
+
+- User integrates AI agents into repository for first time
+- User asks to set up agent guidance, rules, or onboarding documentation
+- Repository is missing agent-specific onboarding docs (no AGENTS.md)
+- Fresh agent context needs to understand repository standards without conversation history
+- Existing AGENTS.md is incomplete or outdated and needs enhancement
+
 ## Core Workflow
 
 1. **Announce** skill and why it applies.

@@ -24,6 +24,16 @@ objective and measurable—there is no "spirit vs letter" escape.
 - Standards violations detected during code review
 - Skills-first repos: Before starting work (validate prerequisites)
 
+## Core Workflow
+
+1. Detect warning, error, or standards violation
+2. Investigate root cause and document finding
+3. Estimate fix time and remaining work time
+4. Apply 2x rule: if fix time < 2x remaining work, fix immediately
+5. If fix time >= 2x remaining work, create tech-debt issue with steps to replicate
+6. Verify warning/error is resolved or issue is created
+7. Continue with original task
+
 ## The 2x Rule
 
 ```dot

@@ -17,6 +17,15 @@ components) to scoped-colocation.
 
 **REQUIRED:** superpowers:brainstorming, superpowers:verification-before-completion
 
+## When to Use
+
+- User decides repository organization or restructures codebase
+- User asks where functionality should live (component placement decisions)
+- User reviews or questions existing component boundaries
+- New functionality spans multiple existing components
+- Team ownership changes require boundary realignment
+- Deployment independence needs evaluation for splitting/merging components
+
 ## Core Workflow
 
 1. **Identify candidate boundaries** based on deployment independence, team ownership, coupling analysis, and reuse patterns

@@ -16,6 +16,25 @@ detects the language/runtime configuration, prefers the newest supported feature
 consults version-specific references progressively from C# 10 upward while respecting
 repository conventions.
 
+## When to Use
+
+- Implementing or refactoring C# code in any .NET project
+- Reviewing C# code for best practice alignment
+- Upgrading code to use newer C# language features
+- Resolving analyzer warnings or style issues
+- Onboarding to an existing C# codebase to understand effective patterns
+
+## Core Workflow
+
+1. **Detect language version**: Check LangVersion in csproj, Directory.Build.props, or infer from TFM
+2. **Record determination**: Document effective C# version and how it was determined
+3. **Load references progressively**: Load reference docs from C# 10 up to the effective version
+4. **Apply highest-priority guidance**: When conflicts exist, newest version guidance wins
+5. **Handle optional analyzers**: Pause and request clarification for optional/contentious rules
+6. **Apply to touched code only**: Avoid unrelated formatting changes unless broader refactor requested
+7. **Validate build and tests**: Ensure changes compile and pass tests
+8. **Emit summary**: Document applied practices and any pending analyzer decisions
+
 ## Intent
 
 Apply C# best practices appropriate to the project's **effective language version**.

@@ -9,13 +9,26 @@ Bias against bespoke internal implementations by preferring mature open-source t
 composable libraries. When custom code is unavoidable, enforce justification rubrics that
 require explicit rationale, ownership, versioning, testing, and security considerations.
 
-## Core
+## When to Use
+
+- Proposals to write internal mappers, code generators, custom build scripts, or DI containers
+- Reviews where new internal tooling or bespoke framework layers are introduced
+- Evaluating whether to build vs buy/adopt for any infrastructure component
+- Reviewing PRs that add custom implementations for common concerns (validation, retries, caching)
+- Architectural decisions involving custom scaffolding or automation scripts
 
-### When to use
+## Core Workflow
 
-- Proposals to write internal mappers, code generators, custom build scripts, custom DI containers,
-  or bespoke framework layers.
-- Reviews where new internal tooling is introduced.
+1. **Identify the concern**: Determine what functionality is being proposed (mapping, validation, CLI, etc.)
+2. **Search for OSS alternatives**: Evaluate mature open-source libraries that solve the same problem
+3. **Compare trade-offs**: Assess maintenance burden, test effort, performance, and community support
+4. **Apply decision framework**: Choose OSS unless clear justification exists for bespoke code
+5. **Require justification rubric**: If bespoke code is proposed, demand explicit rationale,
+   ownership, versioning, tests, and security considerations
+6. **Document decision**: Record OSS evaluation, selection rationale, and maintenance plan
+7. **Verify in PR**: Check that PR includes evidence of OSS evaluation and rubric satisfaction
+
+## Core
 
 ### Defaults
 

@@ -50,6 +50,16 @@ Use this skill when you are:
 
 For cross-language or organization-wide security processes, use the `security-processes` skill alongside this one.
 
+## Core Workflow
+
+1. Identify target .NET version and load corresponding version reference
+2. For upgrades, load upgrade-cumulative.md and lts-upgrade-playbook.md
+3. Apply baseline engineering standards (security, reliability, performance, maintainability)
+4. Review code against version-specific recommended patterns
+5. Validate configuration centralisation and analyzer enforcement
+6. Produce target framework recommendation and adoption checklist
+7. Document risks, breaking changes, and required test gates
+
 ## Progressive loading model
 
 1. Read this file (baseline standards + operating procedure).

@@ -10,12 +10,25 @@ domain models. Conversions to/from primitives are permitted only at explicit bou
 (persistence, transport, serialization), ensuring type safety and validation throughout
 the domain layer.
 
-## Core
+## When to Use
+
+- Designing or reviewing domain models (entities, aggregates, commands/events)
+- Introducing new entity identifiers (CustomerId, OrderId, TenantId, etc.)
+- Working with meaningful primitives that carry validation (EmailAddress, Money, Percentage)
+- Reviewing code where primitive types (Guid, string, int) are used for domain concepts
+- Implementing API boundaries, persistence layers, or serialization
 
-### When to use
+## Core Workflow
 
-- Designing or reviewing domain models (entities, aggregates, commands/events).
-- Any non-trivial service where identifiers and "meaningful primitives" recur across layers.
+1. **Identify primitive obsession**: Locate places where Guid, string, int, or long represent domain concepts
+2. **Define strongly typed IDs**: Create typed ID types using source-generation libraries for entity identifiers
+3. **Define value objects**: Create value objects for meaningful primitives with validation (EmailAddress, Money)
+4. **Establish boundary conversions**: Map to/from primitives only at explicit boundaries (API, persistence, transport)
+5. **Configure serialization**: Add JSON converters, EF Core value converters, and type handlers as needed
+6. **Update service signatures**: Change service methods to accept domain primitives, not raw types
+7. **Add boundary tests**: Test that boundary conversion works and invalid primitives are rejected
+
+## Core
 
 ### Defaults (non-negotiable)
 

@@ -9,12 +9,26 @@ Standardise Entity Framework Core usage with dedicated migrations projects exclu
 coverage, attribute-linked configuration types for entities, and deterministic configuration
 discovery. This ensures clean separation between business logic and infrastructure scaffolding.
 
-## Core
+## When to Use
+
+- Any solution using EF Core for persistence
+- Adding or modifying DbContext, entity types, or configurations
+- Creating or updating EF Core migrations
+- Setting up code coverage exclusions for infrastructure projects
+- Reviewing PRs that change persistence layer structure
 
-### When to use
+## Core Workflow
 
-- Any solution using EF Core for persistence.
-- Any PR introducing or changing DbContext, entity types, configurations, or migrations.
+1. **Verify project structure**: Ensure migrations are in a dedicated `*.Persistence.Migrations` project
+2. **Configure coverage exclusion**: Add `<ExcludeFromCodeCoverage>true</ExcludeFromCodeCoverage>` to migrations project
+3. **Create configuration types**: Implement dedicated `IEntityTypeConfiguration<T>` for each entity
+4. **Link via attributes**: Use attribute-based discovery to connect entities to their configurations
+5. **Keep DbContext clean**: DbContext applies configurations, not define them inline
+6. **Ensure deterministic ordering**: Configuration scanning uses stable ordering (e.g., by full name)
+7. **Verify coverage gate**: Run tests to confirm migrations project excluded from coverage reports
+8. **Add repository tests**: Use xUnit with `IAsyncLifetime` for async repository testing
+
+## Core
 
 ### Defaults (non-negotiable)
 

@@ -9,12 +9,25 @@ Standardise health check implementation using the AspNetCore.Diagnostics.HealthC
 open-source ecosystem. Prefer battle-tested packages over bespoke probes for liveness, readiness,
 and dependency health endpoints across databases, caches, message brokers, and external services.
 
-## Core
+## When to Use
+
+- Building or modifying ASP.NET Core services that need health endpoints
+- Adding health checks for infrastructure dependencies (databases, caches, brokers)
+- Implementing Kubernetes liveness and readiness probes
+- Reviewing PRs that introduce custom health check implementations
+- Configuring orchestration health semantics for containerised services
 
-### When to use
+## Core Workflow
 
-- Any ASP.NET Core service exposing liveness, readiness, or dependency health endpoints.
-- Any PR introducing health checks for infrastructure dependencies.
+1. **Evaluate Xabaril packages**: Check if AspNetCore.Diagnostics.HealthChecks has a package for the dependency
+2. **Register health checks**: Add checks via `AddHealthChecks()` with appropriate packages
+3. **Separate liveness from readiness**: Tag liveness checks with "live", readiness with "ready"
+4. **Map endpoints**: Configure `/health/live` and `/health/ready` with tag-based predicates
+5. **Configure orchestration**: Set Kubernetes probes to use appropriate endpoints
+6. **Test health checks**: Unit test custom IHealthCheck implementations, integration test endpoints
+7. **Verify with curl**: Use `curl -i` to confirm endpoints return expected status codes
+
+## Core
 
 ### Defaults (strong preference)
 

@@ -6,6 +6,28 @@ metadata:
   superseded-by: observability-logging-baseline
 ---
 
+## Overview
+
+This skill standardizes structured logging in .NET applications using `ILogger`/`ILogger<T>`
+abstractions with Serilog as the underlying provider. It ensures startup exceptions are logged at
+Critical severity for immediate visibility in operational tooling, and provides patterns for
+Application Insights and OpenTelemetry integration.
+
+## When to Use
+
+- Building or modifying ASP.NET Core or worker service applications that need structured logging
+- Reviewing PRs that touch host startup, logging configuration, or exception handling
+- Integrating logging with Azure Application Insights or OpenTelemetry
+- Ensuring startup failures are properly captured and visible in monitoring systems
+
+## Core Workflow
+
+1. Configure Serilog as the logging provider during host building with a bootstrap logger for early startup capture
+2. Use `ILogger<T>` abstractions in application code (never reference Serilog types directly)
+3. Wrap host build/run in try/catch and log startup exceptions at Critical severity
+4. Configure appropriate sinks (console for dev, Application Insights or centralized sink for production)
+5. Verify structured properties are used instead of string concatenation for operational fields
+
 > **DEPRECATED**: This skill has been consolidated into `observability-logging-baseline`.
 >
 > - For comprehensive observability guidance (logs, metrics, traces), use

@@ -9,11 +9,25 @@ Standardise mapping between DTOs, domain models, and persistence models using so
 mappers. Mappings live at explicit boundaries (API, infrastructure) with deterministic,
 testable conversion paths and no runtime reflection magic.
 
-## Core
+## When to Use
+
+- Mapping between API request/response DTOs and domain models
+- Converting domain entities to/from persistence models
+- Handling integration event contracts at service boundaries
+- Reviewing PRs that introduce new mapping logic
+- Refactoring existing reflection-based mappers to source-generated alternatives
 
-### When to use
+## Core Workflow
 
-- Any service that maps between API contracts, domain models, persistence models, or integration events.
+1. **Identify mapping boundaries**: Locate where DTOs cross into domain or persistence layers
+2. **Choose source-generated mapper**: Select Mapperly or similar compile-time mapper
+3. **Create explicit mappers**: Implement mapper classes at boundary projects (API, Infrastructure)
+4. **Handle typed IDs explicitly**: Map strongly typed IDs and value objects with explicit conversions
+5. **Apply DI gating rules**: Use static mappers unless mapper has injected dependencies
+6. **Add mapping tests**: Include round-trip tests for critical boundary conversions
+7. **Verify side-effect free**: Ensure mappings have no side effects or external calls
+
+## Core
 
 ### Defaults
 

@@ -9,13 +9,26 @@ Enforce open-source-first dependency selection with mandatory live license reval
 review time. Historical OSS status is insufficient; verify current licensing via web search
 for every dependency selection, upgrade, or review to catch recent licensing changes.
 
-## Core
+## When to Use
+
+- Selecting a new library or tool dependency
+- Upgrading any dependency (minor or major version)
+- Performing PR, architecture, security, or dependency reviews
+- Evaluating alternatives for an existing proprietary or source-available component
+- Auditing existing dependencies for license compliance
 
-### When to use
+## Core Workflow
 
-- Selecting a new dependency.
-- Upgrading any dependency (minor or major).
-- Performing PR, architecture, security, or dependency reviews.
+1. **Prefer open-source**: Default to OSS libraries over proprietary or source-available alternatives
+2. **Perform live web search**: Search for current licensing status (not cached/historical data)
+3. **Verify authoritative sources**: Check project homepage, LICENSE file, release notes, issue tracker
+4. **Confirm exact version license**: Verify licensing for the specific version being adopted
+5. **Check transitive dependencies**: Spot-check critical transitives for license changes
+6. **Document verification**: Record license name, verification source(s), and verification date (UTC)
+7. **Gate on missing verification**: Reject or defer proposals without complete license documentation
+8. **Flag ambiguity**: Mark dependency unapproved if licensing cannot be verified confidently
+
+## Core
 
 ### Policy (non-negotiable)
 

@@ -10,6 +10,23 @@ concerns like mapping, serialization, regex, and logging. Source generation prov
 determinism, compile-time verification, reduced runtime overhead, and better AOT/trimming
 compatibility.
 
+## When to Use
+
+- Introducing or reviewing repetitive cross-cutting mechanisms (mappers, serializers, regex, logging templates)
+- Building performance-sensitive systems or services with startup-time concerns
+- Targeting AOT compilation or assembly trimming scenarios
+- Evaluating mapping or serialization libraries for a new project
+- Reviewing PRs that propose reflection-based or runtime codegen approaches
+
+## Core Workflow
+
+1. Identify the cross-cutting concern (mapping, serialization, regex, logging)
+2. Check if a source-generation library exists for the use case (e.g., Mapperly, System.Text.Json source generators, GeneratedRegex)
+3. Evaluate the source-gen library against requirements (API compatibility, feature set, maintainability)
+4. Implement using the source-generation approach
+5. Verify compile-time generation is working (check generated files, no runtime reflection warnings)
+6. Benchmark if performance is critical (use the minimal benchmark template in Load: advanced)
+
 ## Core
 
 ### When to use

@@ -9,6 +9,23 @@ Prefer the Specification Pattern over generic Repository Pattern for query compo
 domain selection logic. Specifications define what to fetch while infrastructure decides how
 to execute, enabling composable, testable selection logic without exposing ORM details.
 
+## When to Use
+
+- Implementing query logic beyond trivial CRUD (filtering, paging, sorting, includes)
+- Building systems with multiple query shapes or evolving selection logic
+- Reviewing code that introduces generic repository patterns with GetAll/Find methods
+- Refactoring scattered LINQ queries in handlers or controllers
+- Adding tenancy, authorization, or other cross-cutting query constraints
+
+## Core Workflow
+
+1. Identify selection logic that is reused or non-trivial
+2. Create a named specification class implementing ISpecification<T>
+3. Define criteria, includes, ordering, and paging in the specification
+4. Update repository to accept specifications (ListAsync, CountAsync)
+5. Replace inline LINQ chains with the named specification
+6. Compose specifications using And/Or combinators where needed
+
 ## Core
 
 ### When to use