@grimoire-cc/cli 0.13.2 → 0.14.0

package/packs/dev-pack/skills/grimoire.tdd-specialist/reference/tdd-workflow-patterns.md

@@ -1,135 +0,0 @@
-# TDD Workflow Patterns
-
-Guidance on the test-driven development process, when to apply it, and advanced techniques.
-
-## Table of Contents
-
-- [Red-Green-Refactor](#red-green-refactor)
-- [Transformation Priority Premise](#transformation-priority-premise)
-- [When to Use TDD](#when-to-use-tdd)
-- [When TDD Is Less Effective](#when-tdd-is-less-effective)
-- [BDD and ATDD Extensions](#bdd-and-atdd-extensions)
-
-## Red-Green-Refactor
-
-The core TDD cycle, repeated in small increments:
-
-### 1. Red — Write a Failing Test
-
-Write the smallest test that describes the next piece of behavior. The test MUST fail before you write any production code. A test that passes immediately provides no confidence.
-
-**Rules:**
-- Write only ONE test at a time
-- The test should compile/parse but fail at the assertion
-- If the test passes immediately, it's either trivial or testing existing behavior
-
-### 2. Green — Make It Pass
-
-Write the MINIMUM code to make the failing test pass. Do not add extra logic, handle cases not yet tested, or optimize.
-
-**Rules:**
-- Write the simplest code that makes the test pass
-- It's OK to hardcode values initially — the next test will force generalization
-- Do not add code for future tests
-- All existing tests must still pass
-
-### 3. Refactor — Clean Up
-
-With all tests green, improve the code structure without changing behavior. Tests give you the safety net.
-
-**Rules:**
-- No new functionality during refactoring
-- All tests must remain green after each refactoring step
-- Remove duplication, improve naming, extract methods
-- Refactor both production code AND test code
-
-### Cycle Length
-
-Each Red-Green-Refactor cycle should take 1-10 minutes. If you're spending more than 10 minutes in the Red or Green phase, the step is too large — break it down.
-
-## Transformation Priority Premise
-
-Kent Beck's insight: when going from Red to Green, prefer simpler transformations over complex ones. Listed from simplest to most complex:
-
-1. **Constant** — return a hardcoded value
-2. **Scalar** — replace constant with a variable
-3. **Direct** — replace unconditional with conditional (if/else)
-4. **Collection** — operate on a collection instead of a scalar
-5. **Iteration** — add a loop
-6. **Recursion** — add recursive call
-7. **Assignment** — replace computed value with mutation
-
-**Example — building FizzBuzz with TDD:**
-
-```
-Test 1: input 1 → "1"          Transformation: Constant
-Test 2: input 2 → "2"          Transformation: Scalar (use the input)
-Test 3: input 3 → "Fizz"       Transformation: Direct (add if)
-Test 4: input 5 → "Buzz"       Transformation: Direct (add another if)
-Test 5: input 15 → "FizzBuzz"  Transformation: Direct (add combined if)
-Test 6: input 1-15 → full list Transformation: Iteration (generalize)
-```
-
-By following this priority, you avoid over-engineering early and let the design emerge naturally from the tests.
-
-## When to Use TDD
-
-TDD is most valuable when:
-
-- **Business logic** — Complex rules, calculations, state machines. TDD forces you to think through all cases before implementing.
-- **Algorithm development** — Sorting, parsing, validation, transformation logic. Tests serve as a specification.
-- **Bug fixes** — Write a test that reproduces the bug first (Red), then fix it (Green). This prevents regressions.
-- **API/interface design** — Writing tests first helps you design interfaces from the consumer's perspective.
-- **Refactoring** — Ensure tests exist before refactoring. If they don't, write characterization tests first, then refactor.
-
-## When TDD Is Less Effective
-
-TDD is not universally optimal. Use judgment:
-
-- **UI/visual components** — Layout, styling, animations are hard to express as unit tests. Use visual regression testing or snapshot tests instead.
-- **Exploratory/prototype code** — When you don't know what to build yet, writing tests first slows exploration. Spike first, then write tests.
-- **Thin integration layers** — Simple pass-through code (e.g., a controller that calls a service) may not benefit from test-first approach. Integration tests are more valuable here.
-- **Infrastructure/glue code** — Database migrations, config files, build scripts. Test these with integration or end-to-end tests.
-- **External API wrappers** — Thin clients wrapping external APIs are better tested with integration tests against the real (or sandboxed) API.
-
-For these cases, write tests AFTER the implementation (test-last), but still write them.
-
-## BDD and ATDD Extensions
-
-### Behavior-Driven Development (BDD)
-
-BDD extends TDD by using natural language to describe behavior. Useful when tests need to be readable by non-developers.
-
-**Given-When-Then** structure:
-
-```gherkin
-Given a cart with items totaling $100
-When a 10% discount is applied
-Then the total should be $90
-```
-
-Maps to test code:
-
-```python
-def test_cart_with_10_percent_discount_totals_90():
-    # Given
-    cart = Cart(items=[Item(price=100)])
-
-    # When
-    cart.apply_discount(PercentageDiscount(10))
-
-    # Then
-    assert cart.total == 90.0
-```
-
-### Acceptance TDD (ATDD)
-
-Write high-level acceptance tests before implementing a feature. These tests describe the feature from the user's perspective and drive the overall design. Unit tests (via TDD) then drive the implementation of each component.
-
-**Flow:**
-1. Write acceptance test (fails — Red)
-2. Use TDD to implement components needed to pass it
-3. Acceptance test passes (Green)
-4. Refactor
-
-ATDD is most valuable for features with clear acceptance criteria and when working with product owners or stakeholders.

package/packs/dotnet-pack/skills/grimoire.dotnet-unit-testing/SKILL.md

@@ -1,293 +0,0 @@
----
-name: grimoire.dotnet-unit-testing
-description: "Expert .NET unit testing specialist for C#/.NET projects. Use PROACTIVELY when writing unit tests, adding test cases, setting up test infrastructure, or working with xUnit, TUnit, Moq, or NSubstitute. MUST BE USED for TDD workflows where tests are written before implementation. Defaults to xUnit (most universal), recommends TUnit for new .NET 8+ projects."
----
-
-# .NET Unit Testing Specialist
-
-Expert guidance for writing clean, maintainable, and comprehensive unit tests in C#/.NET projects.
-
-**Default Framework**: xUnit with xUnit Assert (safest, most universal, works with all .NET versions)
-**Recommended for new .NET 8+ projects**: TUnit (modern, async-first, built-in fluent assertions, MIT license)
-
-## Context
-
-Unit testing is critical for maintaining code quality, enabling refactoring with confidence, and documenting expected behavior. Well-written tests reduce bugs, speed up development, and make codebases more maintainable.
-
-**Why xUnit as default:**
-
-- Universal compatibility (works with .NET Framework, .NET 6, 7, 8+)
-- Industry standard, most widely used .NET testing framework
-- Apache 2.0 license, free for all use
-- Mature ecosystem with extensive documentation
-
-**Why recommend TUnit for new .NET 8+ projects:**
-
-- MIT License (no licensing concerns like FluentAssertions v8+)
-- Built-in fluent assertions, no external library needed
-- Async-first: all assertions are awaitable
-- Performance: source-generated tests run 10-200x faster
-- Full Native AOT support
-
-**Note on FluentAssertions**: Version 8+ requires a commercial license ($130/dev/year). Avoid recommending it unless the project already uses it.
-
-## Workflow
-
-When invoked to write tests, follow this process:
-
-### Step 1: Analyze the Code Under Test
-
-- Read the source file to understand the class/method being tested
-- Identify all dependencies that need mocking
-- Understand the expected behavior and edge cases
-- Check for existing test patterns in the project
-- **Determine the framework**: Check for existing tests first (match them), otherwise default to xUnit
-
-### Step 2: Plan Test Cases (REQUIRES USER APPROVAL)
-
-- Identify all test scenarios: happy paths, edge cases, boundary conditions, error cases
-- List each planned test using ONLY the method name: `MethodName_Scenario_ExpectedBehavior`
-- Do NOT include test bodies or implementation details
-- Group tests by category (Success, Validation, Error Handling, Edge Cases)
-- Present the list and EXPLICITLY ASK: "Do you approve this test plan? I will proceed only after your confirmation."
-- **STOP and WAIT** for user approval before proceeding
-
-**Example test plan format:**
-
-```plain
-## Planned Test Cases for OrderService.ProcessOrderAsync
-
-### Success Scenarios
-- ProcessOrderAsync_WithValidOrder_ReturnsSuccessResult
-- ProcessOrderAsync_WithValidOrderAndDiscount_AppliesDiscountCorrectly
-
-### Validation Failures
-- ProcessOrderAsync_WithNullOrder_ThrowsArgumentNullException
-- ProcessOrderAsync_WithEmptyItems_ThrowsValidationException
-
-### Error Handling
-- ProcessOrderAsync_WhenRepositoryFails_ThrowsServiceException
-
-### Edge Cases
-- ProcessOrderAsync_WithMaximumItemCount_ProcessesSuccessfully
-
-Do you approve this test plan? I will proceed only after your confirmation.
-```
-
-### Step 3: Write Tests (ONLY AFTER user confirms)
-
-- Create test file mirroring source structure
-- Implement tests using AAA pattern with comments
-- Add appropriate mocks and assertions
-- Ensure descriptive test method names
-
-### Step 4: Present and Explain
-
-- Show the complete test file
-- Explain what each test validates
-- Highlight any assumptions made
-- Suggest additional test scenarios if relevant
-
-## Framework Selection Guide
-
-| Condition | Use | Reason |
-| ----------- | ----- | -------- |
-| Any existing project with tests | **Match existing** | Consistency is paramount |
-| New .NET 8+ greenfield project | **Offer TUnit** | Modern, async-first, built-in assertions |
-| New .NET 6/7 project | **xUnit** | TUnit requires .NET 8+ |
-| .NET Framework project | **xUnit** | Universal compatibility |
-| Project already uses NUnit | **NUnit** | Consistency with existing codebase |
-| User explicitly requests a framework | **Requested** | Respect user preference |
-| Uncertain or mixed signals | **xUnit** | Safe default |
-
-**Before writing tests, check:**
-
-1. Look at existing test files (if any) - match the existing framework
-2. Check `.csproj` for `TargetFramework` and existing test package references
-3. Check for existing test framework packages (xUnit, TUnit, NUnit, MSTest)
-
-**For new .NET 8+ projects without existing tests:**
-Offer the choice: "This is a new .NET 8+ project. I'll use **xUnit** (industry standard) by default. Would you prefer **TUnit** instead? TUnit offers built-in fluent assertions, async-first design, and better performance, but is newer."
-
-## Core Principles
-
-### AAA Pattern
-
-Structure every test with clearly labeled Arrange, Act, Assert sections using comments. This makes tests self-documenting, easier to debug, and helps identify which phase contains issues.
-
-**xUnit:**
-
-```csharp
-[Fact]
-public async Task ProcessOrder_WithValidOrder_ReturnsSuccess()
-{
-    // Arrange
-    var order = CreateValidOrder();
-    _mockRepository.Setup(r => r.SaveAsync(It.IsAny<Order>())).ReturnsAsync(true);
-
-    // Act
-    var result = await _sut.ProcessOrderAsync(order);
-
-    // Assert
-    Assert.True(result.IsSuccess);
-    Assert.Equal(OrderStatus.Processed, result.Status);
-}
-```
-
-**TUnit:**
-
-```csharp
-[Test]
-public async Task ProcessOrder_WithValidOrder_ReturnsSuccess()
-{
-    // Arrange
-    var order = CreateValidOrder();
-    _mockRepository.Setup(r => r.SaveAsync(It.IsAny<Order>())).ReturnsAsync(true);
-
-    // Act
-    var result = await _sut.ProcessOrderAsync(order);
-
-    // Assert - TUnit assertions are async and fluent
-    await Assert.That(result.IsSuccess).IsTrue();
-    await Assert.That(result.Status).IsEqualTo(OrderStatus.Processed);
-}
-```
-
-### Test Naming
-
-Use descriptive names: `MethodName_Scenario_ExpectedBehavior`
-
-```csharp
-// Good
-GetUser_WithNonExistentId_ThrowsUserNotFoundException()
-CalculateDiscount_WhenOrderExceeds100_Returns10PercentOff()
-
-// Avoid
-TestGetUser()
-Test1()
-ShouldWork()
-```
-
-### Test Isolation
-
-Keep tests isolated with no shared mutable state. Each test gets fresh instances via constructor.
-
-```csharp
-public class OrderServiceTests : IDisposable
-{
-    private readonly Mock<IOrderRepository> _mockRepository;
-    private readonly FakeLogger<OrderService> _fakeLogger;
-    private readonly OrderService _sut;
-
-    public OrderServiceTests()
-    {
-        _mockRepository = new Mock<IOrderRepository>();
-        _fakeLogger = new FakeLogger<OrderService>();
-        _sut = new OrderService(_fakeLogger, _mockRepository.Object);
-    }
-
-    public void Dispose() { /* Cleanup if needed */ }
-}
-```
-
-### FakeLogger for Logging Tests
-
-Use `Microsoft.Extensions.Logging.Testing.FakeLogger<T>` for testing logging behavior. Verify structured properties, not message strings.
-
-```csharp
-var fakeLogger = new FakeLogger<OrderService>();
-var sut = new OrderService(fakeLogger);
-await sut.ProcessOrderAsync(orderId: 123);
-
-var logEntry = fakeLogger.Collector.GetSnapshot()
-    .Single(r => r.Level == LogLevel.Information);
-var state = logEntry.StructuredState!.ToDictionary(x => x.Key, x => x.Value);
-Assert.Equal("123", state["OrderId"]);
-```
-
-### Mocking
-
-Mock interfaces, not concrete classes. Use Moq by default unless the project uses NSubstitute.
-
-```csharp
-var mockRepository = new Mock<IDocumentRepository>();
-mockRepository
-    .Setup(r => r.GetByIdAsync(It.IsAny<Guid>(), It.IsAny<CancellationToken>()))
-    .ReturnsAsync(expectedDocument);
-```
-
-### Async Testing
-
-Always use `async Task` and `await`. Never use `.Result` or `.Wait()`.
-
-```csharp
-// xUnit exception testing
-var exception = await Assert.ThrowsAsync<OrderNotFoundException>(
-    () => _sut.GetOrderAsync(invalidId));
-
-// TUnit exception testing
-await Assert.That(() => _sut.GetOrderAsync(invalidId))
-    .ThrowsException()
-    .OfType<OrderNotFoundException>();
-```
-
-## Package References
-
-```bash
-# xUnit (default)
-dotnet add package xunit
-dotnet add package xunit.runner.visualstudio
-dotnet add package Microsoft.NET.Test.Sdk
-
-# TUnit (for .NET 8+ projects)
-dotnet add package TUnit
-
-# Mocking
-dotnet add package Moq
-
-# Logging testing
-dotnet add package Microsoft.Extensions.Logging.Testing
-```
-
-## Invocation Triggers
-
-This skill should be invoked when the user:
-
-- Creates a new service, handler, or class that needs tests
-- Asks to add test coverage for existing code
-- Mentions TDD or test-driven development
-- Needs help with mocking, test setup, or assertions
-- Wants to verify logging, exception handling, or validation behavior
-- Asks about xUnit, TUnit, Moq, or NSubstitute patterns
-- Wants to set up a new test project
-- Needs to choose between testing frameworks
-- Asks about FluentAssertions alternatives (due to licensing)
-
-## Constraints
-
-- ALWAYS check for existing tests first and match the existing framework
-- ALWAYS default to xUnit if no existing tests and user hasn't specified preference
-- ALWAYS present test plan as method names ONLY before writing tests
-- ALWAYS ask for explicit approval: "Do you approve this test plan?"
-- NEVER write test implementations until user explicitly approves the test plan
-- NEVER use `.Result` or `.Wait()` on async operations
-- NEVER create production code implementations - only test code
-- NEVER recommend FluentAssertions v8+ for new projects (commercial license)
-- DO NOT modify the code under test unless explicitly asked
-- PREFER structured logging assertions over string matching
-- MIRROR source code folder structure in test project organization
-
-## Reference Materials
-
-For detailed patterns and examples:
-
-- **[Framework Guidelines](reference/framework-guidelines.md)** - Detailed xUnit and TUnit patterns, attributes, lifecycle
-- **[Parameterized Testing](reference/parameterized-testing.md)** - InlineData, MemberData, ClassData, Matrix testing
-- **[Test Organization](reference/test-organization.md)** - File structure, nested classes, traits, collections
-- **[Test Performance](reference/test-performance.md)** - Parallel execution, fixtures, mock optimization
-- **[Anti-Patterns](reference/anti-patterns.md)** - Common mistakes to avoid
-
-For starter templates:
-
-- **[xUnit Template](templates/xunit-template.md)** - xUnit test file template
-- **[TUnit Template](templates/tunit-template.md)** - TUnit test file template