@pratikpsl/agent-skills 0.1.0

package/src/templates/dotnet/AgentSkills/agents/README.md

@@ -0,0 +1,16 @@
+# Agents
+
+This folder is the canonical source of truth for agent definitions used by all AI tools and IDEs in this repository.
+
+Do not duplicate agent content under `.github/`, `.copilot/`, `.codex/`, or other tool-specific folders.
+Those tools should load agent definitions from this folder.
+Complete `AgentSkills/OPERATING.md` before loading a task-specific agent definition.
+
+## Agent Locations (canonical paths)
+
+| Agent | Canonical Path |
+|---|---|
+| architect | `AgentSkills/agents/architect.agent.md` |
+| developer | `AgentSkills/agents/developer.agent.md` |
+
+All agents and tools (Copilot, Codex, Claude, Cursor, Antigravity) load agents from `AgentSkills/agents/`.

package/src/templates/dotnet/AgentSkills/agents/architect.agent.md

@@ -0,0 +1,59 @@
+---
+name: architect
+description: >
+  Load when designing features, planning CQRS structure,
+  designing SQL schema, or planning MCP server contracts.
+  Do not write implementation code; output structure only.
+---
+
+# Architect Agent
+
+## Responsibilities
+
+- Design CQRS command/query split before any code is written.
+- Define SQL schema and relationships.
+- Define MCP tool contracts including name, input, and output.
+- Identify performance-sensitive read/write paths and expected data volume.
+- Reject designs that violate SOLID, KISS, or YAGNI.
+- Prefer simple, small designs that are easy to delete.
+
+## CQRS Rules
+
+- Commands mutate state and return nothing, an ID, or a small result.
+- Queries read state and never mutate.
+- Controllers dispatch only; no business logic belongs in controllers.
+- Use one handler per command or query.
+- Query designs returning collections must specify projection, pagination, and tracking behavior.
+
+## Output Format
+
+Before implementation, produce:
+
+1. Command/query split with input and output.
+2. SQL schema if new tables are needed.
+3. MCP tool contract if the MCP surface changes.
+4. Proposed folder structure.
+
+## Example Command / Query Split
+
+| Type | Name | Input | Output |
+|---|---|---|---|
+| Command | CreateOrderCommand | CreateOrderRequest | OrderId |
+| Query | GetOrderByIdQuery | OrderId | OrderDto |
+
+## Example Folder Structure
+
+```text
+Features/
+└── Orders/
+    ├── Commands/
+    │   └── CreateOrder/
+    │       ├── CreateOrderCommand.cs
+    │       ├── CreateOrderHandler.cs
+    │       └── CreateOrderValidator.cs
+    └── Queries/
+        └── GetOrderById/
+            ├── GetOrderByIdQuery.cs
+            ├── GetOrderByIdHandler.cs
+            └── OrderDto.cs
+```

package/src/templates/dotnet/AgentSkills/agents/developer.agent.md

@@ -0,0 +1,88 @@
+---
+name: developer
+description: >
+  Load when implementing features in .NET C# API.
+  Always load architect guidance first if structure is not defined.
+  Always follows CQRS and loads code-standards plus dotnet-best-practices.
+---
+
+# Developer Agent
+
+## Stack
+
+- .NET 10 and modern C#.
+- ASP.NET Core Minimal APIs or controllers.
+- MediatR for CQRS dispatch.
+- FluentValidation for input validation.
+- EF Core for persistence.
+- MCP Server SDK for AI tool surface.
+
+## Implementation Rules
+
+- Use records for commands, queries, and DTOs when immutability is appropriate.
+- Mark classes `sealed` unless inheritance is intentionally supported.
+- Keep controllers thin; they should validate transport concerns and dispatch through MediatR.
+- Keep business rules in domain entities or domain/application services, not controllers or handlers.
+- Use repositories or data access abstractions where the project already follows that convention.
+- Use async all the way; never block with `.Result`, `.Wait()`, or `.GetAwaiter().GetResult()`.
+- Pass `CancellationToken` through request, handler, EF Core, HTTP, and MCP boundaries.
+- Optimize read queries with `.AsNoTracking()`, DTO projection, pagination, and no N+1 queries.
+- Keep API payloads small and avoid excessive logging in hot paths.
+
+## CQRS Pattern
+
+```csharp
+public sealed record CreateOrderCommand(Guid CustomerId, IReadOnlyList<OrderItem> Items)
+    : IRequest<Guid>;
+
+public sealed class CreateOrderHandler(IOrderRepository repository)
+    : IRequestHandler<CreateOrderCommand, Guid>
+{
+    public async Task<Guid> Handle(
+        CreateOrderCommand command,
+        CancellationToken cancellationToken)
+    {
+        var order = Order.Create(command.CustomerId, command.Items);
+        await repository.AddAsync(order, cancellationToken);
+        return order.Id;
+    }
+}
+```
+
+## Controller Rule
+
+Controllers dispatch only.
+
+```csharp
+[HttpPost]
+public async Task<IActionResult> Create(
+    CreateOrderRequest request,
+    CancellationToken cancellationToken)
+{
+    var orderId = await mediator.Send(
+        new CreateOrderCommand(request.CustomerId, request.Items),
+        cancellationToken);
+
+    return CreatedAtAction(nameof(GetById), new { orderId }, null);
+}
+```
+
+## MCP Tool Rule
+
+MCP tools should reuse the same command/query handlers as REST endpoints.
+
+```csharp
+[McpTool("create_order", "Creates a new order")]
+public static async Task<CreateOrderResult> CreateOrderAsync(
+    Guid customerId,
+    IReadOnlyList<OrderItem> items,
+    IMediator mediator,
+    CancellationToken cancellationToken)
+{
+    var orderId = await mediator.Send(
+        new CreateOrderCommand(customerId, items),
+        cancellationToken);
+
+    return new CreateOrderResult(orderId);
+}
+```

package/src/templates/dotnet/AgentSkills/entry-points/AGENTS.md

@@ -0,0 +1,16 @@
+# Codex / OpenAI Entry Point
+
+This file is a lightweight entry point for Codex and OpenAI agents.
+
+`AgentSkills/` is the single source of truth for skills, agents, memory,
+prerequisites, checklists, and project rules used by all coding agents and
+AI-enabled IDEs in this repository.
+
+## Start Here
+
+1. Read `AgentSkills/OPERATING.md`.
+2. Follow skill routing in `AgentSkills/skills/INDEX.md`.
+3. Load role definitions from `AgentSkills/agents/` only when the task requires them.
+
+Do not duplicate canonical instructions in this file. Edit shared guidance in
+`AgentSkills/`.

package/src/templates/dotnet/AgentSkills/entry-points/CLAUDE.md

@@ -0,0 +1,16 @@
+# Claude Entry Point
+
+This file is a lightweight entry point for Claude (Anthropic).
+
+`AgentSkills/` is the single source of truth for skills, agents, memory,
+prerequisites, checklists, and project rules used by all coding agents and
+AI-enabled IDEs in this repository.
+
+## Start Here
+
+1. Read `AgentSkills/OPERATING.md`.
+2. Follow skill routing in `AgentSkills/skills/INDEX.md`.
+3. Load role definitions from `AgentSkills/agents/` only when the task requires them.
+
+Do not duplicate canonical instructions in this file. Edit shared guidance in
+`AgentSkills/`.

package/src/templates/dotnet/AgentSkills/entry-points/copilot-instructions.md

@@ -0,0 +1,16 @@
+# Copilot Entry Point
+
+This file is a lightweight entry point for GitHub Copilot.
+
+`AgentSkills/` is the single source of truth for skills, agents, memory,
+prerequisites, checklists, and project rules used by all coding agents and
+AI-enabled IDEs in this repository.
+
+## Start Here
+
+1. Read `AgentSkills/OPERATING.md`.
+2. Follow skill routing in `AgentSkills/skills/INDEX.md`.
+3. Load role definitions from `AgentSkills/agents/` only when the task requires them.
+
+Do not duplicate canonical instructions in this file. Edit shared guidance in
+`AgentSkills/`.

package/src/templates/dotnet/AgentSkills/entry-points/cursor-instructions.md

@@ -0,0 +1,16 @@
+# Cursor / Antigravity Entry Point
+
+This file is a lightweight entry point for Cursor and Antigravity IDEs.
+
+`AgentSkills/` is the single source of truth for skills, agents, memory,
+prerequisites, checklists, and project rules used by all coding agents and
+AI-enabled IDEs in this repository.
+
+## Start Here
+
+1. Read `AgentSkills/OPERATING.md`.
+2. Follow skill routing in `AgentSkills/skills/INDEX.md`.
+3. Load role definitions from `AgentSkills/agents/` only when the task requires them.
+
+Do not duplicate canonical instructions in this file. Edit shared guidance in
+`AgentSkills/`.

package/src/templates/dotnet/AgentSkills/memory/index.md

@@ -0,0 +1,22 @@
+# Memory Index
+
+Always load this file first. Then load **only** the domain file(s) that match your task.
+Do NOT load domain files you do not need. Never load all files at once.
+
+## Domain Map
+
+| Domain | Load when | File | Lessons |
+|--------|-----------|------|---------|
+| api | CQRS, MediatR, commands, queries, controllers, endpoints | [lessons/api.md](lessons/api.md) | 1 |
+| db | EF Core, migrations, schema, seeding, repositories | [lessons/db.md](lessons/db.md) | 0 |
+| infra | Build, paths, CI, tooling, portability, AgentSkills setup | [lessons/infra.md](lessons/infra.md) | 5 |
+| auth | Authentication, authorisation, JWT, policies, claims | [lessons/auth.md](lessons/auth.md) | 0 |
+| testing | xUnit, test data, mocking, coverage, assertions | [lessons/testing.md](lessons/testing.md) | 0 |
+| csharp | C# language features, async/await, naming, code style | [lessons/csharp.md](lessons/csharp.md) | 0 |
+| design | SOLID, CQRS, Repository, patterns, architecture decisions | [lessons/design.md](lessons/design.md) | 0 |
+| mcp | MCP server tools, transports, contracts, .NET MCP integration | [lessons/mcp.md](lessons/mcp.md) | 0 |
+
+## Writing a lesson?
+
+Load `memory/schema.md` for the one-line format. Do not inline logging instructions here.
+Update the lesson count in this table after appending to the domain file.

package/src/templates/dotnet/AgentSkills/memory/lessons/api.md

@@ -0,0 +1,3 @@
+# API Lessons
+
+RULE: Controllers dispatch only via MediatR; all business rules belong in Domain Entities or Domain Services, never in Handlers or Controllers. #cqrs-violation 2026-05-31

package/src/templates/dotnet/AgentSkills/memory/lessons/auth.md

@@ -0,0 +1,3 @@
+# Auth Lessons
+
+<!-- No lessons yet. Append using the format in memory/schema.md -->

package/src/templates/dotnet/AgentSkills/memory/lessons/csharp.md

@@ -0,0 +1,3 @@
+# C# Lessons
+
+<!-- No lessons yet. Append using the format in memory/schema.md -->

package/src/templates/dotnet/AgentSkills/memory/lessons/db.md

@@ -0,0 +1,3 @@
+# DB Lessons
+
+<!-- No lessons yet. Append using the format in memory/schema.md -->

package/src/templates/dotnet/AgentSkills/memory/lessons/design.md

@@ -0,0 +1,3 @@
+# Design Lessons
+
+<!-- No lessons yet. Append using the format in memory/schema.md -->

package/src/templates/dotnet/AgentSkills/memory/lessons/infra.md

@@ -0,0 +1,7 @@
+# Infra Lessons
+
+RULE: Never overwrite files in AgentSkills/ without verifying they are backed up; it is the single source of truth and tool-specific entry points must point to it, never duplicate it. #circular-redirect 2026-05-31
+RULE: Use repo-relative paths in all agent and IDE instruction files; never write absolute local drive paths in shared documentation. #wrong-path 2026-06-06
+RULE: When splitting a monolithic memory file into domain files, grep the whole repo for the old path and update every reference before deleting the original. #stale-reference 2026-06-07
+RULE: Always check native command exit codes explicitly in PowerShell harness scripts. #native-exit-code 2026-06-21
+RULE: Run dotnet format after patching C# files; this repo enforces CRLF and no final newline. #format-fail 2026-07-01

package/src/templates/dotnet/AgentSkills/memory/lessons/mcp.md

@@ -0,0 +1,3 @@
+# MCP Lessons
+
+<!-- No lessons yet. Append using the format in memory/schema.md -->

package/src/templates/dotnet/AgentSkills/memory/lessons/testing.md

@@ -0,0 +1,3 @@
+# Testing Lessons
+
+<!-- No lessons yet. Append using the format in memory/schema.md -->

package/src/templates/dotnet/AgentSkills/memory/schema.md

@@ -0,0 +1,26 @@
+# Lesson Logging Schema
+
+Load this file **only when writing a new lesson** at the end of a task.
+Never load at task start — it adds no value during execution.
+
+## Format
+
+Append one line per lesson to the correct domain file in `memory/lessons/`:
+
+```
+RULE: <imperative sentence — what to always do or never do> #tag YYYY-MM-DD
+```
+
+## Rules for a good entry
+
+- Start with **Always**, **Never**, or an action verb.
+- Keep it under 20 words. The rule only — no symptom narrative, no root cause prose.
+- Add one `#tag` describing the symptom class (e.g. `#build-fail`, `#wrong-path`, `#cqrs-violation`).
+- Pick the correct domain from `memory/index.md`. If unsure, use `infra.md`.
+- After appending, **increment the lesson count** for that domain in `memory/index.md`.
+
+## Example
+
+```
+RULE: Never place business logic in MediatR Handlers; delegate to domain entities or services. #cqrs-violation 2026-05-31
+```

package/src/templates/dotnet/AgentSkills/skills/INDEX.md

@@ -0,0 +1,21 @@
+# Skills Index
+
+Load the relevant skill from `AgentSkills/skills/` before starting any task.
+Start with `AgentSkills/OPERATING.md` for the shared prerequisite and completion workflow.
+
+`AgentSkills/` is the single source of truth for all skills and agents.
+Do not duplicate skill content under `.github/`, `.copilot/`, `.codex/`, or other tool-specific folders.
+All AI tools and IDEs should load skills from this folder.
+
+## Skills
+
+| Skill | Load when | Path |
+|---|---|---|
+| **core** | Every task | [SKILL.md](core/SKILL.md) |
+| **code-standards** | Writing, reviewing, or refactoring C# code | [SKILL.md](code-standards/SKILL.md) |
+| **design** | Designing, architecting, or implementing patterns | [SKILL.md](design/SKILL.md) |
+| **dotnet-best-practices** | Writing, reviewing, refactoring, or optimizing .NET/C# code | [SKILL.md](dotnet-best-practices/SKILL.md) |
+| **csharp-xunit** | Get best practices for XUnit unit testing, including data-driven tests | [SKILL.md](csharp-xunit/SKILL.md) |
+| **mcp_dotnet** | Building, reviewing, or extending .NET MCP server tools, transports, and integration points | [SKILL.md](mcp_dotnet/SKILL.md) |
+| **dotnet-api** | Creating, structuring, or reviewing .NET 10 Web API projects with Swagger/OpenAPI, CORS, compression, auth, versioning, and error handling | [SKILL.md](dotnet-api/SKILL.md) |
+| **harness** | Changing agent instructions, validation scripts, CI workflows, hooks, or operational guardrails | [SKILL.md](harness/SKILL.md) |

package/src/templates/dotnet/AgentSkills/skills/README.md

@@ -0,0 +1,14 @@
+# Skills
+
+This folder is the canonical source of truth for reusable skills used by all AI tools and IDEs in this repository.
+
+Do not duplicate skill content under `.github/`, `.copilot/`, `.codex/`, or other tool-specific folders.
+Those tools should load skill definitions from this folder.
+
+## Skill Index
+
+Start with `AgentSkills/skills/INDEX.md`, then load only the skills that match the task.
+
+## Harness Skill
+
+Use `AgentSkills/skills/harness/SKILL.md` when changing guides, sensors, hooks, CI, validation, or operational guardrails.

package/src/templates/dotnet/AgentSkills/skills/code-standards/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: code-standards
+description: >
+  Load when writing, reviewing, or refactoring C# code.
+  Covers naming, structure, comments, and commit hygiene.
+---
+
+# Code Standards
+
+Language: C#. Every example is production code, not pseudocode.
+
+## 1. No Magic Values
+
+```csharp
+// Bad
+if (role == 3) { }
+
+// Good
+private const int AdminRoleId = 3;
+if (role == AdminRoleId) { }
+```
+
+## 2. Meaningful Names
+
+Names explain what a value represents and why it matters. If a comment is needed to explain a variable, rename it.
+
+```csharp
+// Bad
+int d = 86400;
+bool flag = true;
+
+// Good
+const int SecondsPerDay = 86400;
+bool isUserVerified = true;
+```
+
+## 3. One Function, One Responsibility
+
+One function should do one thing. If you cannot summarize it in one sentence, split it.
+
+## 4. Descriptive Booleans
+
+```csharp
+// Bad
+bool check = true;
+
+// Good
+bool hasPermission = true;
+bool isSessionExpired = false;
+```
+
+## 5. DRY
+
+Keep one source of truth per piece of logic. Apply judgment: premature abstraction is also harmful.
+
+## 6. Early Returns Over Deep Nesting
+
+```csharp
+// Bad
+void Process(User user)
+{
+    if (user != null)
+    {
+        if (user.IsActive)
+        {
+            // Main logic
+        }
+    }
+}
+
+// Good
+void Process(User user)
+{
+    if (user is null) return;
+    if (!user.IsActive) return;
+
+    // Main logic
+}
+```
+
+## 7. Comment Why, Not What
+
+```csharp
+// Bad
+// Increment counter.
+count++;
+
+// Good
+// Back off before HTTP 429; this API caps requests at 100 per minute.
+if (requestCount >= RateLimitBackoffThreshold) { }
+```
+
+## 8. Limit Function Arguments
+
+More than 3 arguments should usually become a config object, command object, or record.
+
+```csharp
+// Bad
+CreateUser("Alice", "alice@example.com", true, "admin", "UTC");
+
+// Good
+CreateUser(new UserConfig
+{
+    Name = "Alice",
+    Email = "alice@example.com",
+    IsVerified = true,
+    Role = Role.Admin,
+    Timezone = "UTC"
+});
+```
+
+## 9. Meaningful Commits
+
+```text
+Bad:
+fix bug
+update stuff
+
+Good:
+fix: prevent double-submit on payment
+refactor: extract shared email validation
+```

package/src/templates/dotnet/AgentSkills/skills/core/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: core
+description: >
+  Load on every task. Non-negotiable principles that govern
+  all work: how to think, what to change, and how to verify.
+---
+
+# Core Principles
+
+> Simplification is the ultimate sophistication.
+> Write code that is simple, small, easy to delete, and adds nothing unnecessary.
+
+1. **Think Before Coding** – Understand the goal before writing a line. If requirements are ambiguous, **stop and ask** — assumptions compound. Surface tradeoffs to the caller, not just in comments.
+2. **Simplicity First** - Write the minimum code that correctly solves the problem. Avoid speculative features.
+3. **Surgical Changes** – Touch only what the task requires. Avoid "while I'm here" changes. Refactoring is a separate, explicit task — never bundled into a feature or fix.
+4. **Goal-Driven Testing** – Define success before writing code. Tests are the contract. Cover the failure path — a test suite that only passes on happy inputs is not a contract, it's a wish.
+5. **No Race Conditions** - Treat shared mutable state as dangerous. Prefer immutability.
+6. **Agent Memory**  – Every task is a learning loop. Read `AgentSkills/memory/index.md` at task start, then load only the domain file(s) matching your task. Before closing, check if a new lesson is warranted — if so, read `AgentSkills/memory/schema.md`, append one line to the correct domain file, and update the count in `index.md`.
+
+7. **Fail Loudly, Recover Gracefully** – Errors are a first-class output. When something goes wrong, fail loudly with context (what, where, relevant IDs). Never swallow exceptions silently. Recovery paths must be as deliberate as the happy path.
+
+8. **Prefer Reversible Moves** – When two approaches solve the problem equally well, choose the one that can be undone. Flag irreversible changes (schema drops, destructive migrations, hard deletes) explicitly before executing them.
+
+## Prerequisite Gate
+
+Every task starts with the shared operating contract in
+`AgentSkills/OPERATING.md`.
+
+Before editing, confirm that you have:
+
+- [ ] Read `AgentSkills/memory/index.md` and loaded only the relevant domain
+      lesson file(s).
+- [ ] Read `AgentSkills/skills/INDEX.md`.
+- [ ] Loaded this core skill.
+- [ ] Loaded task-specific skills and agent definitions only when they apply.
+- [ ] Identified the expected verification command(s).
+- [ ] Checked the worktree context so existing user changes are preserved.
+
+## Pre-submit Checklist
+
+### Scope
+
+- [ ] Only required files changed; no unrelated refactors or metadata churn.
+- [ ] Public documentation changed only when behavior, setup, commands, or usage changed.
+- [ ] Commit message states what changed and why, when a commit is made.
+- [ ] Memory was updated only if a mistake or durable project-specific rule was discovered.
+
+### Design and Maintainability
+
+- [ ] Code is as simple as possible, but no simpler.
+- [ ] No speculative generality or unused extension points.
+- [ ] Each function does one thing.
+- [ ] No argument list longer than 4; use an object, options type, or record.
+- [ ] No nesting deeper than 2 levels; prefer early returns.
+- [ ] No duplicated logic; shared behavior is extracted only when it is real reuse.
+- [ ] SOLID respected, especially Single Responsibility.
+- [ ] Important values are named; no magic literals.
+- [ ] Comments explain why, not what the code already says.
+
+### Reliability and Security
+
+- [ ] No race condition on shared mutable state.
+- [ ] All async operations have a cancellation path.
+- [ ] No sensitive data such as keys, PII, or tokens appears in logs, errors, commits, or responses.
+- [ ] External inputs are validated before use.
+- [ ] Rendered outputs are sanitized where applicable.
+- [ ] Errors include useful context: what failed, where, and relevant IDs.
+- [ ] Structured log entries are used; no raw string concatenation in logs.
+- [ ] Correlation or trace IDs are propagated on cross-service calls.
+
+### API and Contract Behavior
+
+- [ ] API responses use correct HTTP status codes; errors are not returned as `200`.
+- [ ] Collection endpoints include pagination and filtering where applicable.
+- [ ] Existing API contracts are preserved unless a versioned breaking change is intentional.
+- [ ] MCP, REST, and application contracts stay aligned when they expose the same behavior.
+
+### Tests and Verification
+
+- [ ] Tests cover failure paths, not just happy paths.
+- [ ] Test names describe behavior, not implementation.
+- [ ] Tests do not depend on external state or execution order.
+- [ ] Relevant build, test, format, and harness commands were run, or skipped with a clear reason.

package/src/templates/dotnet/AgentSkills/skills/csharp-xunit/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: csharp-xunit
+description: 'Get best practices for XUnit unit testing, including data-driven tests'
+---
+
+# XUnit Best Practices
+
+Your goal is to help me write effective unit tests with XUnit, covering both standard and data-driven testing approaches.
+
+## Project Setup
+
+- Use a separate test project with naming convention `[ProjectName].Tests`
+- Reference Microsoft.NET.Test.Sdk, xunit, and xunit.runner.visualstudio packages
+- Create test classes that match the classes being tested (e.g., `CalculatorTests` for `Calculator`)
+- Use .NET SDK test commands: `dotnet test` for running tests
+
+## Test Structure
+
+- No test class attributes required (unlike MSTest/NUnit)
+- Use fact-based tests with `[Fact]` attribute for simple tests
+- Follow the Arrange-Act-Assert (AAA) pattern
+- Name tests using the pattern `MethodName_Scenario_ExpectedBehavior`
+- Use constructor for setup and `IDisposable.Dispose()` for teardown
+- Use `IClassFixture<T>` for shared context between tests in a class
+- Use `ICollectionFixture<T>` for shared context between multiple test classes
+
+## Standard Tests
+
+- Keep tests focused on a single behavior
+- Avoid testing multiple behaviors in one test method
+- Use clear assertions that express intent
+- Include only the assertions needed to verify the test case
+- Make tests independent and idempotent (can run in any order)
+- Avoid test interdependencies
+
+## Data-Driven Tests
+
+- Use `[Theory]` combined with data source attributes
+- Use `[InlineData]` for inline test data
+- Use `[MemberData]` for method-based test data
+- Use `[ClassData]` for class-based test data
+- Create custom data attributes by implementing `DataAttribute`
+- Use meaningful parameter names in data-driven tests
+
+## Assertions
+
+- Use `Assert.Equal` for value equality
+- Use `Assert.Same` for reference equality
+- Use `Assert.True`/`Assert.False` for boolean conditions
+- Use `Assert.Contains`/`Assert.DoesNotContain` for collections
+- Use `Assert.Matches`/`Assert.DoesNotMatch` for regex pattern matching
+- Use `Assert.Throws<T>` or `await Assert.ThrowsAsync<T>` to test exceptions
+- Use fluent assertions library for more readable assertions
+
+## Mocking and Isolation
+
+- Consider using Moq or NSubstitute alongside XUnit
+- Mock dependencies to isolate units under test
+- Use interfaces to facilitate mocking
+- Consider using a DI container for complex test setups
+
+## Test Organization
+
+- Group tests by feature or component
+- Use `[Trait("Category", "CategoryName")]` for categorization
+- Use collection fixtures to group tests with shared dependencies
+- Consider output helpers (`ITestOutputHelper`) for test diagnostics
+- Skip tests conditionally with `Skip = "reason"` in fact/theory attributes