ma-agents 2.20.3 → 2.22.0

package/skills/cpp-best-practices/examples/modern-idioms.md

@@ -0,0 +1,189 @@
+# Modern C++ Idioms Examples
+
+## C++17: Structured Bindings and std::optional
+
+```cpp
+#include <map>
+#include <optional>
+#include <string>
+
+// Structured bindings — prefer over .first/.second
+std::map<std::string, int> scores = {{"Alice", 95}, {"Bob", 87}};
+for (const auto& [name, score] : scores) {
+    // name and score are directly named — no .first/.second
+}
+
+// std::optional — no more nullptr sentinels or bool out-parameters
+std::optional<std::string> findUser(int id) {
+    if (id == 42) return "Alice";
+    return std::nullopt; // Not found — explicit, type-safe
+}
+
+void example() {
+    if (const auto user = findUser(42); user.has_value()) {
+        // C++17 if-with-initializer keeps 'user' scoped tightly
+        doSomethingWith(*user);
+    }
+}
+```
+
+## C++17: std::variant for Sum Types
+
+```cpp
+#include <variant>
+#include <string>
+
+struct Success { std::string message; };
+struct NotFound { int id; };
+struct PermissionDenied { std::string reason; };
+
+using LookupResult = std::variant<Success, NotFound, PermissionDenied>;
+
+LookupResult lookup(int id) {
+    if (id == 0) return NotFound{id};
+    if (id < 0) return PermissionDenied{"negative ids reserved"};
+    return Success{"found item " + std::to_string(id)};
+}
+
+void handle(const LookupResult& result) {
+    std::visit([](const auto& v) {
+        using T = std::decay_t<decltype(v)>;
+        if constexpr (std::is_same_v<T, Success>) {
+            log(v.message);
+        } else if constexpr (std::is_same_v<T, NotFound>) {
+            log("not found: " + std::to_string(v.id));
+        } else {
+            log("denied: " + v.reason);
+        }
+    }, result);
+}
+```
+
+## C++20: Concepts
+
+```cpp
+#include <concepts>
+#include <iostream>
+#include <vector>
+
+// Before concepts: SFINAE was required — hard to read and debug
+// After concepts: clear, readable constraints
+
+template<std::integral T>
+T clamp(T value, T lo, T hi) {
+    return std::max(lo, std::min(value, hi));
+}
+
+// Custom concept
+template<typename T>
+concept Printable = requires(T t) {
+    { t.toString() } -> std::convertible_to<std::string>;
+};
+
+template<Printable T>
+void printAll(const std::vector<T>& items) {
+    for (const auto& item : items) {
+        std::cout << item.toString() << '\n';
+    }
+}
+```
+
+## C++20: Ranges
+
+```cpp
+#include <algorithm>
+#include <iostream>
+#include <ranges>
+#include <vector>
+#include <string>
+
+void modernRanges() {
+    std::vector<int> numbers = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};
+
+    // Chain range adaptors — lazy, composable, readable
+    auto evenSquares = numbers
+        | std::views::filter([](int n) { return n % 2 == 0; })
+        | std::views::transform([](int n) { return n * n; });
+
+    // Iterate result without materializing an intermediate container
+    for (int v : evenSquares) {
+        std::cout << v << '\n'; // 4 16 36 64 100
+    }
+
+    // Sorting with ranges — no begin/end iterator boilerplate
+    std::vector<std::string> names = {"Charlie", "Alice", "Bob"};
+    std::ranges::sort(names);
+}
+```
+
+## C++23: std::expected for Error Handling
+
+```cpp
+#include <expected>
+#include <string>
+#include <fstream>
+
+enum class ParseError { InvalidFormat, EmptyInput, Overflow };
+
+// Return expected<T, E> instead of throwing for anticipated failures
+std::expected<int, ParseError> parsePositiveInt(std::string_view input) {
+    if (input.empty()) return std::unexpected(ParseError::EmptyInput);
+    int result = 0;
+    for (char c : input) {
+        if (c < '0' || c > '9') return std::unexpected(ParseError::InvalidFormat);
+        result = result * 10 + (c - '0');
+        if (result < 0) return std::unexpected(ParseError::Overflow);
+    }
+    return result;
+}
+
+void usage() {
+    const auto result = parsePositiveInt("123");
+    if (result) {
+        std::println("Parsed: {}", *result);
+    } else {
+        // Handle error without try/catch — expected path, not exceptional
+        switch (result.error()) {
+            case ParseError::InvalidFormat: std::println("invalid format"); break;
+            case ParseError::EmptyInput:    std::println("empty input");    break;
+            case ParseError::Overflow:      std::println("overflow");       break;
+        }
+    }
+}
+```
+
+## Class Design: Rule of Zero
+
+```cpp
+#include <memory>
+#include <string>
+#include <vector>
+
+// Good: Rule of Zero — all members manage themselves
+class Document {
+public:
+    explicit Document(std::string title) : title_(std::move(title)) {}
+
+    void addSection(std::string content) {
+        sections_.emplace_back(std::move(content));
+    }
+
+private:
+    std::string title_;                    // manages its own lifetime
+    std::vector<std::string> sections_;    // manages its own lifetime
+    // No destructor, no copy/move definitions needed — compiler generates correct ones
+};
+
+// Bad: unnecessary manual resource management
+class BadDocument {
+public:
+    BadDocument(const char* title) {
+        title_ = new char[strlen(title) + 1]; // raw new — avoid this
+        strcpy(title_, title);
+    }
+    ~BadDocument() { delete[] title_; }       // manual cleanup — fragile
+    // Must also define copy ctor, copy assign, move ctor, move assign correctly...
+private:
+    char* title_;
+};
+```

package/skills/cpp-best-practices/examples/naming-and-organization.md

@@ -0,0 +1,102 @@
+# Naming and Organization Examples
+
+## Naming Conventions
+
+```cpp
+// File: user_account.h
+#pragma once
+
+#include <string>
+#include <string_view>
+#include <optional>
+
+namespace myapp::domain {
+
+// Types use PascalCase
+class UserAccount {
+public:
+    // Constants use UPPER_SNAKE_CASE
+    static constexpr int MAX_NAME_LENGTH = 128;
+
+    // Constructors and methods use camelCase
+    explicit UserAccount(std::string_view userName, int accountId);
+
+    // Const member function — does not modify the object
+    [[nodiscard]] std::string_view getUserName() const;
+    [[nodiscard]] int getAccountId() const;
+
+    // Mutating method
+    void setUserName(std::string_view newName);
+
+private:
+    // Private members use camelCase with trailing underscore
+    std::string userName_;
+    int accountId_;
+};
+
+} // namespace myapp::domain
+```
+
+## Header Organization
+
+```cpp
+// File: connection_pool.cpp
+
+// 1. Project headers first
+#include "connection_pool.h"
+#include "network/socket.h"
+
+// 2. Third-party headers
+#include <boost/asio.hpp>
+
+// 3. Standard library
+#include <algorithm>
+#include <chrono>
+#include <memory>
+#include <vector>
+
+namespace myapp::network {
+// ...
+} // namespace myapp::network
+```
+
+## Forward Declarations to Reduce Coupling
+
+```cpp
+// File: request_handler.h
+#pragma once
+
+// Forward declare instead of including the full header
+namespace myapp::domain {
+class UserAccount;
+}
+
+namespace myapp::network {
+
+class RequestHandler {
+public:
+    // Only a reference/pointer is needed here — forward declaration is sufficient
+    void handle(const myapp::domain::UserAccount& user);
+};
+
+} // namespace myapp::network
+```
+
+## Namespace Usage
+
+```cpp
+// Good: deeply nested namespace matching directory structure
+namespace myapp::network::http {
+
+class Client {
+    // ...
+};
+
+} // namespace myapp::network::http
+
+// Avoid in headers — pollutes every translation unit that includes this header:
+// using namespace std; // BAD in headers
+
+// OK in .cpp files, restricted to file scope:
+// using namespace myapp::network::http;
+```

package/skills/cpp-best-practices/skill.json

@@ -0,0 +1,25 @@
+{
+    "name": "C++ Best Practices",
+    "description": "Comprehensive C++ coding standards covering naming conventions, modern C++ idioms (C++17/20/23), error handling, and build guidelines. Cross-references domain-specific C++ skills for deep-dives.",
+    "version": "1.0.0",
+    "author": "Antigravity",
+    "tags": [
+        "c++",
+        "cpp",
+        "coding-standards",
+        "best-practices",
+        "modern-cpp",
+        "c++17",
+        "c++20",
+        "c++23"
+    ],
+    "applies_when": [
+        "writing c++ code",
+        "modifying c++ code",
+        "creating new c++ files or classes",
+        "reviewing c++ code style or conventions",
+        "refactoring c++ code",
+        "setting up a c++ project"
+    ],
+    "always_load": true
+}

package/skills/csharp-best-practices/SKILL.md

@@ -0,0 +1,274 @@
+# C# Best Practices
+
+Coding standards for modern C# (C# 10+) across .NET 6 through .NET 8+. This skill covers language-level patterns. Framework-specific patterns (ASP.NET Core middleware, EF Core, Blazor) belong in future skills.
+
+## 1. Naming Conventions
+
+**Rule:** Use consistent naming to maximize code readability and tooling support.
+
+| Element | Convention | Example |
+|---------|-----------|---------|
+| Namespace | PascalCase, match folder | `MyApp.Services` |
+| Class / Struct / Record | PascalCase | `CustomerService` |
+| Interface | `I` + PascalCase | `ICustomerService` |
+| Method | PascalCase | `GetCustomerAsync` |
+| Property | PascalCase | `FirstName` |
+| Local variable | camelCase | `customerCount` |
+| Parameter | camelCase | `customerId` |
+| Private field | `_` + camelCase | `_logger` |
+| Constant | PascalCase | `MaxRetryCount` |
+| Enum type | PascalCase singular | `OrderStatus` |
+| Enum member | PascalCase | `OrderStatus.Pending` |
+| Async method | suffix `Async` | `SaveAsync` |
+
+## 2. Code Organization
+
+**Rule:** One type per file; namespace matches folder path.
+
+- File-scoped namespace declaration (C# 10+): `namespace MyApp.Services;` — no extra indentation level.
+- Organize types in the order: constants, fields, constructors, properties, methods (public first, then private).
+- Use `global using` directives in a dedicated `GlobalUsings.cs` file to eliminate repetitive `using` statements project-wide.
+- Prefer `record` types for immutable data containers; use `record struct` for small value-type data.
+
+## 3. Nullable Reference Types
+
+**Rule:** Enable NRT project-wide and treat warnings as errors.
+
+```xml
+<Nullable>enable</Nullable>
+<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+```
+
+- Never use `!` (null-forgiving) to silence warnings without a documented reason.
+- Use `string?` for intentionally nullable references; non-nullable types must be initialized before use.
+- Initialize fields in the constructor or use `required` members (C# 11+) to enforce initialization at the call site.
+
+```csharp
+public class Order
+{
+    public required string CustomerId { get; init; }
+    public string? Notes { get; init; }
+}
+```
+
+## 4. Modern C# Language Features
+
+### 4.1 Primary Constructors (C# 12)
+
+Use primary constructors for classes and structs that primarily capture injected dependencies.
+
+```csharp
+public class OrderService(IOrderRepository repository, ILogger<OrderService> logger)
+{
+    public async Task<Order?> GetAsync(int id, CancellationToken ct)
+    {
+        logger.LogInformation("Getting order {Id}", id);
+        return await repository.FindAsync(id, ct);
+    }
+}
+```
+
+### 4.2 Collection Expressions (C# 12)
+
+Prefer collection expressions over explicit constructors for collection initialization.
+
+```csharp
+// Preferred
+int[] ids = [1, 2, 3];
+List<string> names = ["Alice", "Bob"];
+
+// Also valid for spread
+int[] combined = [..ids, 4, 5];
+```
+
+### 4.3 Raw String Literals (C# 11)
+
+Use raw string literals for JSON, SQL, or multi-line strings to avoid escaping.
+
+```csharp
+var json = """
+    {
+        "name": "Alice",
+        "age": 30
+    }
+    """;
+```
+
+### 4.4 Pattern Matching
+
+Use pattern matching to simplify type checks and conditional logic.
+
+```csharp
+// Type patterns
+string Describe(object obj) => obj switch
+{
+    int n when n > 0 => "positive integer",
+    int n            => "non-positive integer",
+    string s         => $"string: {s}",
+    null             => "null",
+    _                => "other"
+};
+
+// List patterns (C# 11)
+bool IsFirstTwo(int[] arr) => arr is [var first, var second, ..];
+```
+
+### 4.5 Records and Record Structs
+
+Use `record` for immutable reference-type DTOs and value objects. Use `readonly record struct` for small immutable value types that benefit from stack allocation.
+
+```csharp
+// Reference-type record (class semantics, heap allocated)
+public record Address(string Street, string City, string PostalCode);
+
+// with-expressions for non-destructive mutation
+var updated = original with { City = "New York" };
+
+// Value-type record (struct semantics, stack allocated)
+public readonly record struct Point(double X, double Y);
+
+// Mutable record struct — only when mutation is explicitly needed
+public record struct Range(int Start, int End);
+```
+
+Choose `readonly record struct` over `record` when: the data is small (2-4 fields), frequently allocated in hot paths, and value semantics (equality by value, copied on assignment) are correct.
+
+### 4.6 File-Scoped Types (C# 11)
+
+Use the `file` access modifier to restrict a type's visibility to the single file where it is declared. This is useful for implementation detail types that should not leak into other files.
+
+```csharp
+// Only visible within this .cs file — cannot be used from any other file
+file class OrderValidator
+{
+    public bool IsValid(Order order) => order.CustomerId is not null;
+}
+
+// Also applies to records, structs, interfaces, delegates
+file record struct ValidationResult(bool IsValid, string? Error);
+```
+
+Use `file`-scoped types for: helper classes private to a single implementation file, source generators' internal scaffolding, and avoiding name collisions across files without polluting `internal` scope.
+
+## 5. Async/Await
+
+**Rule:** Use async all the way up the call stack; never block on async code.
+
+- Prefer `async Task` / `async Task<T>` over returning naked `Task`.
+- Never use `async void` except for event handlers; use `async Task` instead.
+- Always propagate `CancellationToken` from public API boundaries down to I/O calls.
+- Prefer `ConfigureAwait(false)` in library code where the calling context does not matter.
+- Use `ValueTask<T>` when a method frequently returns a synchronous result (hot-path optimization); default to `Task<T>` for simplicity.
+
+```csharp
+// Correct — async all the way, CancellationToken propagated, ConfigureAwait in library code
+public async Task<Order?> FindOrderAsync(int id, CancellationToken ct = default)
+{
+    return await _repository.GetByIdAsync(id, ct).ConfigureAwait(false);
+}
+
+// Correct — multiple I/O operations with cancellation
+public async Task<IReadOnlyList<Order>> GetActiveOrdersAsync(CancellationToken ct = default)
+{
+    var orders = await _repository.ListAsync(ct).ConfigureAwait(false);
+    return orders.Where(o => o.IsActive).ToList();
+}
+
+// Wrong — blocks the thread pool, risks deadlock
+public Order? FindOrder(int id) => FindOrderAsync(id).Result;
+```
+
+## 6. LINQ
+
+**Rule:** Prefer method syntax; be aware of deferred execution.
+
+- Use method syntax (`Where`, `Select`, `FirstOrDefault`) over query syntax for consistency with the rest of the codebase.
+- LINQ queries execute lazily — materialize with `.ToList()`, `.ToArray()`, or `.ToDictionary()` when the result will be enumerated more than once or when you need a stable snapshot.
+- Avoid LINQ inside tight loops on large collections; profile before assuming LINQ is a bottleneck.
+- For in-memory filtering on large datasets, consider `AsSpan()` or `ArrayPool<T>` instead of repeated LINQ queries.
+
+```csharp
+// Materialize when enumerating multiple times
+var activeOrders = orders.Where(o => o.IsActive).ToList();
+
+// Avoid multiple enumeration of IEnumerable
+foreach (var order in activeOrders) { /* ... */ }
+int count = activeOrders.Count;
+```
+
+## 7. Error Handling
+
+**Rule:** Use structured exception handling; reserve exceptions for truly exceptional conditions.
+
+- Define a domain exception hierarchy derived from a base exception: `AppException : Exception`.
+- Use the Result pattern for expected failure cases (validation, not-found) where exceptions are expensive overhead.
+- For HTTP APIs, structure error responses using ProblemDetails (RFC 9457) — the language-level concern is ensuring your exceptions carry enough data to produce one; the middleware that converts them belongs in a future `csharp-aspnet-patterns` skill.
+- Never swallow exceptions silently; always log or rethrow.
+
+```csharp
+// Result pattern for expected failures
+public record Result<T>(T? Value, string? Error)
+{
+    public bool IsSuccess => Error is null;
+    public static Result<T> Ok(T value) => new(value, null);
+    public static Result<T> Fail(string error) => new(default, error);
+}
+
+// Exception hierarchy
+public class AppException(string message) : Exception(message);
+public class NotFoundException(string entity, object id)
+    : AppException($"{entity} with id '{id}' was not found.");
+```
+
+## 8. Dependency Injection
+
+**Rule:** Favor constructor injection; choose service lifetimes deliberately.
+
+- Constructor injection is the standard pattern — inject only what the type needs.
+- **Singleton:** One instance for the application lifetime. Use for stateless services and configuration.
+- **Scoped:** One instance per request (web) or operation scope. Use for database contexts and unit-of-work patterns.
+- **Transient:** New instance per resolution. Use for lightweight, stateless utilities.
+- Never inject a Scoped or Transient service into a Singleton — this causes captive dependency bugs.
+
+```csharp
+// Registration via IServiceCollection (Microsoft.Extensions.DependencyInjection)
+// Works in console apps, workers, ASP.NET Core, and any .NET host
+IServiceCollection services = new ServiceCollection();
+services.AddSingleton<IConfigService, ConfigService>();
+services.AddScoped<IOrderService, OrderService>();
+services.AddTransient<IEmailFormatter, EmailFormatter>();
+```
+
+## 9. Testing
+
+**Rule:** Follow Arrange-Act-Assert; use framework-agnostic patterns.
+
+- Name tests: `MethodName_StateUnderTest_ExpectedBehavior`.
+- Arrange all preconditions, act on the system under test, assert the single observable outcome.
+- Major test frameworks: xUnit (most popular for .NET), NUnit, MSTest — choose based on team preference.
+- Popular assertion libraries: FluentAssertions, Shouldly. Popular mock libraries: NSubstitute, Moq.
+- Avoid test logic that depends on execution order; each test must be independent.
+
+```csharp
+// xUnit example (patterns apply to NUnit/MSTest)
+public class OrderServiceTests
+{
+    [Fact]
+    public async Task GetAsync_ExistingId_ReturnsOrder()
+    {
+        // Arrange
+        var repository = Substitute.For<IOrderRepository>();
+        var logger = Substitute.For<ILogger<OrderService>>();
+        repository.FindAsync(1, Arg.Any<CancellationToken>())
+            .Returns(new Order { Id = 1 });
+        var sut = new OrderService(repository, logger);
+
+        // Act
+        var result = await sut.GetAsync(1, CancellationToken.None);
+
+        // Assert
+        result.Should().NotBeNull();
+        result!.Id.Should().Be(1);
+    }
+}
+```

package/skills/csharp-best-practices/skill.json

@@ -0,0 +1,23 @@
+{
+    "name": "C# Best Practices",
+    "description": "Comprehensive C# coding standards covering modern C# (C# 10-12), async/await, LINQ, dependency injection basics, nullable reference types, and testing conventions.",
+    "version": "1.0.0",
+    "author": "ma-agents",
+    "tags": [
+        "csharp",
+        "c#",
+        "dotnet",
+        ".net",
+        "coding-standards",
+        "best-practices",
+        "net8"
+    ],
+    "applies_when": [
+        "writing c# code",
+        "creating new c# files or classes",
+        "reviewing c# code style or conventions",
+        "working with .net projects",
+        "setting up a c# project"
+    ],
+    "always_load": true
+}

package/skills/git-workflow-skill/skill.json

@@ -18,4 +18,4 @@
     "any code writing or modification task"
   ],
   "always_load": true
-}
+}

package/skills/open-presentation/SKILL.md

@@ -0,0 +1,31 @@
+# Open Presentation Skill
+
+## Description
+Opens the BMAD-METHOD AI Development Training presentation installed at `_bmad-output/methodology/`.
+
+## Usage
+Invoke this skill by typing `/open-presentation`.
+
+## Instructions
+
+When the user invokes `/open-presentation`:
+
+1. **Locate the presentation** at `_bmad-output/methodology/BMAD_AI_Development_Training.pptx` relative to the project root.
+
+2. **Open it** using the OS default viewer via the Bash tool:
+   - **Windows**: `start "" "_bmad-output/methodology/BMAD_AI_Development_Training.pptx"`
+   - **macOS**: `open "_bmad-output/methodology/BMAD_AI_Development_Training.pptx"`
+   - **Linux**: `xdg-open "_bmad-output/methodology/BMAD_AI_Development_Training.pptx"`
+
+3. **If the file does not exist**, inform the user:
+   > "The methodology presentation has not been installed yet. Run `npx ma-agents install` with BMAD to deploy it to `_bmad-output/methodology/`."
+
+4. **Detect the OS** using the Node.js `process.platform` convention or by checking which command is available, then run the appropriate open command.
+
+## Examples
+
+**User**: `/open-presentation`
+**Assistant**: Opens `_bmad-output/methodology/BMAD_AI_Development_Training.pptx` in the system default PowerPoint viewer.
+
+**User**: "open the methodology slides"
+**Assistant**: [Treats this as /open-presentation and follows the instructions above]

package/skills/open-presentation/skill.json

@@ -0,0 +1,11 @@
+{
+  "name": "Open Presentation",
+  "description": "Opens the BMAD-METHOD AI Development Training presentation from _bmad-output/methodology/",
+  "version": "1.0.0",
+  "author": "AI Agent Skills",
+  "tags": ["methodology", "presentation", "bmad", "training"],
+  "applies_when": [
+    "user types /open-presentation",
+    "user asks to open the methodology presentation or training slides"
+  ]
+}