shmakk 1.1.0 → 1.2.0

package/skills/dev-create-architectural-decision-record.md

@@ -0,0 +1,98 @@
+---
+name: create-architectural-decision-record
+description: 'Create an Architectural Decision Record (ADR) document for AI-optimized decision documentation.'
+category: dev
+---
+
+# Create Architectural Decision Record
+
+Create an ADR document for `${input:DecisionTitle}` using structured formatting optimized for AI consumption and human readability.
+
+## Inputs
+
+- **Context**: `${input:Context}`
+- **Decision**: `${input:Decision}`
+- **Alternatives**: `${input:Alternatives}`
+- **Stakeholders**: `${input:Stakeholders}`
+
+## Input Validation
+If any of the required inputs are not provided or cannot be determined from the conversation history, ask the user to provide the missing information before proceeding with ADR generation.
+
+## Requirements
+
+- Use precise, unambiguous language
+- Follow standardized ADR format with front matter
+- Include both positive and negative consequences
+- Document alternatives with rejection rationale
+- Structure for machine parsing and human reference
+- Use coded bullet points (3-4 letter codes + 3-digit numbers) for multi-item sections
+
+The ADR must be saved in the `/docs/adr/` directory using the naming convention: `adr-NNNN-[title-slug].md`, where NNNN is the next sequential 4-digit number (e.g., `adr-0001-database-selection.md`).
+
+## Required Documentation Structure
+
+The documentation file must follow the template below, ensuring that all sections are filled out appropriately. The front matter for the markdown should be structured correctly as per the example following:
+
+```md
+---
+title: "ADR-NNNN: [Decision Title]"
+status: "Proposed"
+date: "YYYY-MM-DD"
+authors: "[Stakeholder Names/Roles]"
+tags: ["architecture", "decision"]
+supersedes: ""
+superseded_by: ""
+---
+
+# ADR-NNNN: [Decision Title]
+
+## Status
+
+**Proposed** | Accepted | Rejected | Superseded | Deprecated
+
+## Context
+
+[Problem statement, technical constraints, business requirements, and environmental factors requiring this decision.]
+
+## Decision
+
+[Chosen solution with clear rationale for selection.]
+
+## Consequences
+
+### Positive
+
+- **POS-001**: [Beneficial outcomes and advantages]
+- **POS-002**: [Performance, maintainability, scalability improvements]
+- **POS-003**: [Alignment with architectural principles]
+
+### Negative
+
+- **NEG-001**: [Trade-offs, limitations, drawbacks]
+- **NEG-002**: [Technical debt or complexity introduced]
+- **NEG-003**: [Risks and future challenges]
+
+## Alternatives Considered
+
+### [Alternative 1 Name]
+
+- **ALT-001**: **Description**: [Brief technical description]
+- **ALT-002**: **Rejection Reason**: [Why this option was not selected]
+
+### [Alternative 2 Name]
+
+- **ALT-003**: **Description**: [Brief technical description]
+- **ALT-004**: **Rejection Reason**: [Why this option was not selected]
+
+## Implementation Notes
+
+- **IMP-001**: [Key implementation considerations]
+- **IMP-002**: [Migration or rollout strategy if applicable]
+- **IMP-003**: [Monitoring and success criteria]
+
+## References
+
+- **REF-001**: [Related ADRs]
+- **REF-002**: [External documentation]
+- **REF-003**: [Standards or frameworks referenced]
+```

package/skills/dev-create-draft-pr.md

@@ -0,0 +1,17 @@
+---
+name: create-draft-pr
+description: Create a draft pull request for the current session. Use when the user wants to open a draft PR with the session's changes.
+category: dev
+---
+<!-- Customize this skill and select save to override its behavior. Delete that copy to restore the built-in behavior. -->
+
+# Create Draft Pull Request
+
+Use the GitHub MCP server to create a draft pull request — do NOT use the `gh` CLI.
+
+1. Run the compile and hygiene tasks (fixing any errors)
+2. If there are any uncommitted changes, use the `/commit` skill to commit them
+3. Review all changes in the current session
+4. Write a clear, concise PR title with a short area prefix (e.g. "sessions: …", "editor: …")
+5. Write a description covering what changed, why, and anything reviewers should know
+6. Create the draft pull request

package/skills/dev-create-pr.md

@@ -0,0 +1,17 @@
+---
+name: create-pr
+description: Create a pull request for the current session. Use when the user wants to open a PR with the session's changes.
+category: dev
+---
+<!-- Customize this skill and select save to override its behavior. Delete that copy to restore the built-in behavior. -->
+
+# Create Pull Request
+
+Use the GitHub MCP server to create a pull request — do NOT use the `gh` CLI.
+
+1. Run the compile and hygiene tasks (fixing any errors)
+2. If there are any uncommitted changes, use the `/commit` skill to commit them
+3. Review all changes in the current session
+4. Write a clear, concise PR title with a short area prefix (e.g. "sessions: …", "editor: …")
+5. Write a description covering what changed, why, and anything reviewers should know
+6. Create the pull request

package/skills/dev-create-readme.md

@@ -0,0 +1,22 @@
+---
+name: create-readme
+description: 'Create a README.md file for the project'
+category: dev
+---
+
+## Role
+
+You're a senior expert software engineer with extensive experience in open source projects. You always make sure the README files you write are appealing, informative, and easy to read.
+
+## Task
+
+1. Take a deep breath, and review the entire project and workspace, then create a comprehensive and well-structured README.md file for the project.
+2. Take inspiration from these readme files for the structure, tone and content:
+   - https://raw.githubusercontent.com/Azure-Samples/serverless-chat-langchainjs/refs/heads/main/README.md
+   - https://raw.githubusercontent.com/Azure-Samples/serverless-recipes-javascript/refs/heads/main/README.md
+   - https://raw.githubusercontent.com/sinedied/run-on-output/refs/heads/main/README.md
+   - https://raw.githubusercontent.com/sinedied/smoke/refs/heads/main/README.md
+3. Do not overuse emojis, and keep the readme concise and to the point.
+4. Do not include sections like "LICENSE", "CONTRIBUTING", "CHANGELOG", etc. There are dedicated files for those sections.
+5. Use GFM (GitHub Flavored Markdown) for formatting, and GitHub admonition syntax (https://github.com/orgs/community/discussions/16925) where appropriate.
+6. If you find a logo or icon for the project, use it in the readme's header.

package/skills/dev-csharp-mstest.md

@@ -0,0 +1,479 @@
+---
+name: csharp-mstest
+description: 'Get best practices for MSTest 3.x/4.x unit testing, including modern assertion APIs and data-driven tests'
+category: dev
+---
+
+# MSTest Best Practices (MSTest 3.x/4.x)
+
+Your goal is to help me write effective unit tests with modern MSTest, using current APIs and best practices.
+
+## Project Setup
+
+- Use a separate test project with naming convention `[ProjectName].Tests`
+- Reference MSTest 3.x+ NuGet packages (includes analyzers)
+- Consider using MSTest.Sdk for simplified project setup
+- Run tests with `dotnet test`
+
+## Test Class Structure
+
+- Use `[TestClass]` attribute for test classes
+- **Seal test classes by default** for performance and design clarity
+- Use `[TestMethod]` for test methods (prefer over `[DataTestMethod]`)
+- Follow Arrange-Act-Assert (AAA) pattern
+- Name tests using pattern `MethodName_Scenario_ExpectedBehavior`
+
+```csharp
+[TestClass]
+public sealed class CalculatorTests
+{
+    [TestMethod]
+    public void Add_TwoPositiveNumbers_ReturnsSum()
+    {
+        // Arrange
+        var calculator = new Calculator();
+
+        // Act
+        var result = calculator.Add(2, 3);
+
+        // Assert
+        Assert.AreEqual(5, result);
+    }
+}
+```
+
+## Test Lifecycle
+
+- **Prefer constructors over `[TestInitialize]`** - enables `readonly` fields and follows standard C# patterns
+- Use `[TestCleanup]` for cleanup that must run even if test fails
+- Combine constructor with async `[TestInitialize]` when async setup is needed
+
+```csharp
+[TestClass]
+public sealed class ServiceTests
+{
+    private readonly MyService _service;  // readonly enabled by constructor
+
+    public ServiceTests()
+    {
+        _service = new MyService();
+    }
+
+    [TestInitialize]
+    public async Task InitAsync()
+    {
+        // Use for async initialization only
+        await _service.WarmupAsync();
+    }
+
+    [TestCleanup]
+    public void Cleanup() => _service.Reset();
+}
+```
+
+### Execution Order
+
+1. **Assembly Initialization** - `[AssemblyInitialize]` (once per test assembly)
+2. **Class Initialization** - `[ClassInitialize]` (once per test class)
+3. **Test Initialization** (for every test method):
+   1. Constructor
+   2. Set `TestContext` property
+   3. `[TestInitialize]`
+4. **Test Execution** - test method runs
+5. **Test Cleanup** (for every test method):
+   1. `[TestCleanup]`
+   2. `DisposeAsync` (if implemented)
+   3. `Dispose` (if implemented)
+6. **Class Cleanup** - `[ClassCleanup]` (once per test class)
+7. **Assembly Cleanup** - `[AssemblyCleanup]` (once per test assembly)
+
+## Modern Assertion APIs
+
+MSTest provides three assertion classes: `Assert`, `StringAssert`, and `CollectionAssert`.
+
+### Assert Class - Core Assertions
+
+```csharp
+// Equality
+Assert.AreEqual(expected, actual);
+Assert.AreNotEqual(notExpected, actual);
+Assert.AreSame(expectedObject, actualObject);      // Reference equality
+Assert.AreNotSame(notExpectedObject, actualObject);
+
+// Null checks
+Assert.IsNull(value);
+Assert.IsNotNull(value);
+
+// Boolean
+Assert.IsTrue(condition);
+Assert.IsFalse(condition);
+
+// Fail/Inconclusive
+Assert.Fail("Test failed due to...");
+Assert.Inconclusive("Test cannot be completed because...");
+```
+
+### Exception Testing (Prefer over `[ExpectedException]`)
+
+```csharp
+// Assert.Throws - matches TException or derived types
+var ex = Assert.Throws<ArgumentException>(() => Method(null));
+Assert.AreEqual("Value cannot be null.", ex.Message);
+
+// Assert.ThrowsExactly - matches exact type only
+var ex = Assert.ThrowsExactly<InvalidOperationException>(() => Method());
+
+// Async versions
+var ex = await Assert.ThrowsAsync<HttpRequestException>(async () => await client.GetAsync(url));
+var ex = await Assert.ThrowsExactlyAsync<InvalidOperationException>(async () => await Method());
+```
+
+### Collection Assertions (Assert class)
+
+```csharp
+Assert.Contains(expectedItem, collection);
+Assert.DoesNotContain(unexpectedItem, collection);
+Assert.ContainsSingle(collection);  // exactly one element
+Assert.HasCount(5, collection);
+Assert.IsEmpty(collection);
+Assert.IsNotEmpty(collection);
+```
+
+### String Assertions (Assert class)
+
+```csharp
+Assert.Contains("expected", actualString);
+Assert.StartsWith("prefix", actualString);
+Assert.EndsWith("suffix", actualString);
+Assert.DoesNotStartWith("prefix", actualString);
+Assert.DoesNotEndWith("suffix", actualString);
+Assert.MatchesRegex(@"\d{3}-\d{4}", phoneNumber);
+Assert.DoesNotMatchRegex(@"\d+", textOnly);
+```
+
+### Comparison Assertions
+
+```csharp
+Assert.IsGreaterThan(lowerBound, actual);
+Assert.IsGreaterThanOrEqualTo(lowerBound, actual);
+Assert.IsLessThan(upperBound, actual);
+Assert.IsLessThanOrEqualTo(upperBound, actual);
+Assert.IsInRange(actual, low, high);
+Assert.IsPositive(number);
+Assert.IsNegative(number);
+```
+
+### Type Assertions
+
+```csharp
+// MSTest 3.x - uses out parameter
+Assert.IsInstanceOfType<MyClass>(obj, out var typed);
+typed.DoSomething();
+
+// MSTest 4.x - returns typed result directly
+var typed = Assert.IsInstanceOfType<MyClass>(obj);
+typed.DoSomething();
+
+Assert.IsNotInstanceOfType<WrongType>(obj);
+```
+
+### Assert.That (MSTest 4.0+)
+
+```csharp
+Assert.That(result.Count > 0);  // Auto-captures expression in failure message
+```
+
+### StringAssert Class
+
+> **Note:** Prefer `Assert` class equivalents when available (e.g., `Assert.Contains("expected", actual)` over `StringAssert.Contains(actual, "expected")`).
+
+```csharp
+StringAssert.Contains(actualString, "expected");
+StringAssert.StartsWith(actualString, "prefix");
+StringAssert.EndsWith(actualString, "suffix");
+StringAssert.Matches(actualString, new Regex(@"\d{3}-\d{4}"));
+StringAssert.DoesNotMatch(actualString, new Regex(@"\d+"));
+```
+
+### CollectionAssert Class
+
+> **Note:** Prefer `Assert` class equivalents when available (e.g., `Assert.Contains`).
+
+```csharp
+// Containment
+CollectionAssert.Contains(collection, expectedItem);
+CollectionAssert.DoesNotContain(collection, unexpectedItem);
+
+// Equality (same elements, same order)
+CollectionAssert.AreEqual(expectedCollection, actualCollection);
+CollectionAssert.AreNotEqual(unexpectedCollection, actualCollection);
+
+// Equivalence (same elements, any order)
+CollectionAssert.AreEquivalent(expectedCollection, actualCollection);
+CollectionAssert.AreNotEquivalent(unexpectedCollection, actualCollection);
+
+// Subset checks
+CollectionAssert.IsSubsetOf(subset, superset);
+CollectionAssert.IsNotSubsetOf(notSubset, collection);
+
+// Element validation
+CollectionAssert.AllItemsAreInstancesOfType(collection, typeof(MyClass));
+CollectionAssert.AllItemsAreNotNull(collection);
+CollectionAssert.AllItemsAreUnique(collection);
+```
+
+## Data-Driven Tests
+
+### DataRow
+
+```csharp
+[TestMethod]
+[DataRow(1, 2, 3)]
+[DataRow(0, 0, 0, DisplayName = "Zeros")]
+[DataRow(-1, 1, 0, IgnoreMessage = "Known issue #123")]  // MSTest 3.8+
+public void Add_ReturnsSum(int a, int b, int expected)
+{
+    Assert.AreEqual(expected, Calculator.Add(a, b));
+}
+```
+
+### DynamicData
+
+The data source can return any of the following types:
+
+- `IEnumerable<(T1, T2, ...)>` (ValueTuple) - **preferred**, provides type safety (MSTest 3.7+)
+- `IEnumerable<Tuple<T1, T2, ...>>` - provides type safety
+- `IEnumerable<TestDataRow>` - provides type safety plus control over test metadata (display name, categories)
+- `IEnumerable<object[]>` - **least preferred**, no type safety
+
+> **Note:** When creating new test data methods, prefer `ValueTuple` or `TestDataRow` over `IEnumerable<object[]>`. The `object[]` approach provides no compile-time type checking and can lead to runtime errors from type mismatches.
+
+```csharp
+[TestMethod]
+[DynamicData(nameof(TestData))]
+public void DynamicTest(int a, int b, int expected)
+{
+    Assert.AreEqual(expected, Calculator.Add(a, b));
+}
+
+// ValueTuple - preferred (MSTest 3.7+)
+public static IEnumerable<(int a, int b, int expected)> TestData =>
+[
+    (1, 2, 3),
+    (0, 0, 0),
+];
+
+// TestDataRow - when you need custom display names or metadata
+public static IEnumerable<TestDataRow<(int a, int b, int expected)>> TestDataWithMetadata =>
+[
+    new((1, 2, 3)) { DisplayName = "Positive numbers" },
+    new((0, 0, 0)) { DisplayName = "Zeros" },
+    new((-1, 1, 0)) { DisplayName = "Mixed signs", IgnoreMessage = "Known issue #123" },
+];
+
+// IEnumerable<object[]> - avoid for new code (no type safety)
+public static IEnumerable<object[]> LegacyTestData =>
+[
+    [1, 2, 3],
+    [0, 0, 0],
+];
+```
+
+## TestContext
+
+The `TestContext` class provides test run information, cancellation support, and output methods.
+See [TestContext documentation](https://learn.microsoft.com/dotnet/core/testing/unit-testing-mstest-writing-tests-testcontext) for complete reference.
+
+### Accessing TestContext
+
+```csharp
+// Property (MSTest suppresses CS8618 - don't use nullable or = null!)
+public TestContext TestContext { get; set; }
+
+// Constructor injection (MSTest 3.6+) - preferred for immutability
+[TestClass]
+public sealed class MyTests
+{
+    private readonly TestContext _testContext;
+
+    public MyTests(TestContext testContext)
+    {
+        _testContext = testContext;
+    }
+}
+
+// Static methods receive it as parameter
+[ClassInitialize]
+public static void ClassInit(TestContext context) { }
+
+// Optional for cleanup methods (MSTest 3.6+)
+[ClassCleanup]
+public static void ClassCleanup(TestContext context) { }
+
+[AssemblyCleanup]
+public static void AssemblyCleanup(TestContext context) { }
+```
+
+### Cancellation Token
+
+Always use `TestContext.CancellationToken` for cooperative cancellation with `[Timeout]`:
+
+```csharp
+[TestMethod]
+[Timeout(5000)]
+public async Task LongRunningTest()
+{
+    await _httpClient.GetAsync(url, TestContext.CancellationToken);
+}
+```
+
+### Test Run Properties
+
+```csharp
+TestContext.TestName              // Current test method name
+TestContext.TestDisplayName       // Display name (3.7+)
+TestContext.CurrentTestOutcome    // Pass/Fail/InProgress
+TestContext.TestData              // Parameterized test data (3.7+, in TestInitialize/Cleanup)
+TestContext.TestException         // Exception if test failed (3.7+, in TestCleanup)
+TestContext.DeploymentDirectory   // Directory with deployment items
+```
+
+### Output and Result Files
+
+```csharp
+// Write to test output (useful for debugging)
+TestContext.WriteLine("Processing item {0}", itemId);
+
+// Attach files to test results (logs, screenshots)
+TestContext.AddResultFile(screenshotPath);
+
+// Store/retrieve data across test methods
+TestContext.Properties["SharedKey"] = computedValue;
+```
+
+## Advanced Features
+
+### Retry for Flaky Tests (MSTest 3.9+)
+
+```csharp
+[TestMethod]
+[Retry(3)]
+public void FlakyTest() { }
+```
+
+### Conditional Execution (MSTest 3.10+)
+
+Skip or run tests based on OS or CI environment:
+
+```csharp
+// OS-specific tests
+[TestMethod]
+[OSCondition(OperatingSystems.Windows)]
+public void WindowsOnlyTest() { }
+
+[TestMethod]
+[OSCondition(OperatingSystems.Linux | OperatingSystems.MacOS)]
+public void UnixOnlyTest() { }
+
+[TestMethod]
+[OSCondition(ConditionMode.Exclude, OperatingSystems.Windows)]
+public void SkipOnWindowsTest() { }
+
+// CI environment tests
+[TestMethod]
+[CICondition]  // Runs only in CI (default: ConditionMode.Include)
+public void CIOnlyTest() { }
+
+[TestMethod]
+[CICondition(ConditionMode.Exclude)]  // Skips in CI, runs locally
+public void LocalOnlyTest() { }
+```
+
+### Parallelization
+
+```csharp
+// Assembly level
+[assembly: Parallelize(Workers = 4, Scope = ExecutionScope.MethodLevel)]
+
+// Disable for specific class
+[TestClass]
+[DoNotParallelize]
+public sealed class SequentialTests { }
+```
+
+### Work Item Traceability (MSTest 3.8+)
+
+Link tests to work items for traceability in test reports:
+
+```csharp
+// Azure DevOps work items
+[TestMethod]
+[WorkItem(12345)]  // Links to work item #12345
+public void Feature_Scenario_ExpectedBehavior() { }
+
+// Multiple work items
+[TestMethod]
+[WorkItem(12345)]
+[WorkItem(67890)]
+public void Feature_CoversMultipleRequirements() { }
+
+// GitHub issues (MSTest 3.8+)
+[TestMethod]
+[GitHubWorkItem("https://github.com/owner/repo/issues/42")]
+public void BugFix_Issue42_IsResolved() { }
+```
+
+Work item associations appear in test results and can be used for:
+- Tracing test coverage to requirements
+- Linking bug fixes to regression tests
+- Generating traceability reports in CI/CD pipelines
+
+## Common Mistakes to Avoid
+
+```csharp
+// ❌ Wrong argument order
+Assert.AreEqual(actual, expected);
+// ✅ Correct
+Assert.AreEqual(expected, actual);
+
+// ❌ Using ExpectedException (obsolete)
+[ExpectedException(typeof(ArgumentException))]
+// ✅ Use Assert.Throws
+Assert.Throws<ArgumentException>(() => Method());
+
+// ❌ Using LINQ Single() - unclear exception
+var item = items.Single();
+// ✅ Use ContainsSingle - better failure message
+var item = Assert.ContainsSingle(items);
+
+// ❌ Hard cast - unclear exception
+var handler = (MyHandler)result;
+// ✅ Type assertion - shows actual type on failure
+var handler = Assert.IsInstanceOfType<MyHandler>(result);
+
+// ❌ Ignoring cancellation token
+await client.GetAsync(url, CancellationToken.None);
+// ✅ Flow test cancellation
+await client.GetAsync(url, TestContext.CancellationToken);
+
+// ❌ Making TestContext nullable - leads to unnecessary null checks
+public TestContext? TestContext { get; set; }
+// ❌ Using null! - MSTest already suppresses CS8618 for this property
+public TestContext TestContext { get; set; } = null!;
+// ✅ Declare without nullable or initializer - MSTest handles the warning
+public TestContext TestContext { get; set; }
+```
+
+## Test Organization
+
+- Group tests by feature or component
+- Use `[TestCategory("Category")]` for filtering
+- Use `[TestProperty("Name", "Value")]` for custom metadata (e.g., `[TestProperty("Bug", "12345")]`)
+- Use `[Priority(1)]` for critical tests
+- Enable relevant MSTest analyzers (MSTEST0020 for constructor preference)
+
+## Mocking and Isolation
+
+- Use Moq or NSubstitute for mocking dependencies
+- Use interfaces to facilitate mocking
+- Mock dependencies to isolate units under test