ma-agents 3.4.9 → 3.5.0

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

@@ -1,278 +0,0 @@
----
-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.
----
-# 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/.roo/skills/docker-hardening-verification/SKILL.md

@@ -1,28 +0,0 @@
----
-name: Docker Hardening Verification
-description: Audits Docker images for security best practices, least privilege, and OpenShift compliance.
----
-# Docker Hardening Verification
-
-## Purpose
-Audit Docker images to ensure they follow security best practices, specifically focusing on non-root execution and least privilege principles required for hardened clusters like OpenShift.
-
-## Instructions
-1.  **Inspect Image**: Use `docker inspect` or `podman inspect` to check metadata.
-2.  **Verify User**: 
-    - Ensure `USER` is defined and is NOT `root` or `0`.
-    - Recommended: Use a high-numbered UID (e.g., `1001`).
-3.  **Check Permissions**:
-    - Ensure sensitive directories are not world-writable.
-    - Check for `setuid`/`setgid` bits on binaries.
-4.  **OpenShift Compliance**:
-    - Verify that the image doesn't require specific UIDs if it's meant to run with an arbitrary assigned UID (OpenShift's default).
-    - Check if the `/etc/passwd` entry handles arbitrary UIDs (e.g., by using `nss_wrapper` or similar).
-
-## Rules
-- Fail the audit if `USER root` is detected.
-- Flag a warning if many unnecessary packages/tools are present.
-- Ensure only necessary ports are exposed.
-
-## Usage
-Run `scripts/verify-hardening.sh <image_name>`

package/.roo/skills/docker-hardening-verification/scripts/verify-hardening.sh

@@ -1,39 +0,0 @@
-#!/bin/bash
-# verify-hardening.sh - Part of ma-agents docker-hardening-verification skill
-
-IMAGE=$1
-
-if [ -z "$IMAGE" ]; then
-    echo "Usage: $0 <image_name>"
-    exit 1
-fi
-
-echo "Auditing image: $IMAGE"
-
-# 1. Check User
-USER_VAL=$(docker inspect --format='{{.Config.User}}' "$IMAGE")
-
-if [ -z "$USER_VAL" ] || [ "$USER_VAL" == "root" ] || [ "$USER_VAL" == "0" ]; then
-    echo "[FAIL] Image runs as root! Definining a non-root USER is mandatory for hardened clusters."
-else
-    echo "[PASS] Image runs as user: $USER_VAL"
-fi
-
-# 2. Check for sensitive capabilities (simplified check)
-CAPS=$(docker inspect --format='{{.Config.CapAdd}}' "$IMAGE")
-if [ "$CAPS" != "<nil>" ] && [ -n "$CAPS" ]; then
-    echo "[WARNING] Image has explicitly added capabilities: $CAPS"
-fi
-
-# 3. Check for exposed ports
-PORTS=$(docker inspect --format='{{range $p, $conf := .Config.ExposedPorts}}{{$p}} {{end}}' "$IMAGE")
-echo "[INFO] Exposed ports: ${PORTS:-none}"
-
-# 4. OpenShift specific check (arbitrary UID support)
-# This is a heuristic check looking for common entrypoint patterns
-ENTRYPOINT=$(docker inspect --format='{{.Config.Entrypoint}}' "$IMAGE")
-if [[ "$ENTRYPOINT" == *"bash"* ]]; then
-    echo "[INFO] Entrypoint uses bash, manual check for UID mapping recommended."
-fi
-
-echo "Summary: Audit complete for $IMAGE"

package/.roo/skills/docker-image-signing/SKILL.md

@@ -1,28 +0,0 @@
----
-name: Docker Image Signing
-description: Automates the signing of Docker images using certificates and Cosign/Notary.
----
-# Docker Image Signing
-
-## Purpose
-Ensure the integrity and authenticity of Docker images by signing them with a cryptographic key/certificate. This prevents unauthorized image substitution and ensures only trusted images are deployed.
-
-## Instructions
-1.  **Tool Selection**: Use `cosign` (recommended) or `notary`.
-2.  **Environment Check**: Verify that the signing tool and Docker/Podman are installed.
-3.  **Signing Process**:
-    - Load the provided certificate/key.
-    - Run the signing command against the target image (using its SHA256 digest for immutability).
-4.  **Verification**: Always run a verification check immediately after signing.
-
-## Rules
-- NEVER sign images by tag alone; use the immutable digest (e.g., `image@sha256:...`).
-- Private keys must be handled as secrets and never stored in the clear.
-- Ensure the certificate provided is valid and not expired.
-
-## Usage
-Run the provided script in `scripts/sign-image.sh` with:
-- `IMAGE`: The image reference with digest.
-- `CERT`: Path to the certificate file.
-- `KEY`: Path to the private key file.
-- `PASSPHRASE`: (Optional) Key passphrase.

package/.roo/skills/docker-image-signing/scripts/sign-image.sh

@@ -1,33 +0,0 @@
-#!/bin/bash
-# sign-image.sh - Part of ma-agents docker-image-signing skill
-
-IMAGE=$1
-CERT=$2
-KEY=$3
-PASSPHRASE=$4
-
-if [ -z "$IMAGE" ] || [ -z "$CERT" ] || [ -z "$KEY" ]; then
-    echo "Usage: $0 <image_digest> <cert_file> <key_file> [passphrase]"
-    exit 1
-fi
-
-echo "Signing image: $IMAGE"
-
-# Check for cosign
-if command -v cosign &> /dev/null; then
-    echo "Using Cosign for signing..."
-    if [ -n "$PASSPHRASE" ]; then
-        export COSIGN_PASSWORD=$PASSPHRASE
-    fi
-    cosign sign --key "$KEY" --cert "$CERT" "$IMAGE"
-else
-    echo "Error: cosign not found. Please install cosign to use this skill."
-    exit 1
-fi
-
-if [ $? -eq 0 ]; then
-    echo "Successfully signed $IMAGE"
-else
-    echo "Failed to sign $IMAGE"
-    exit 1
-fi

package/.roo/skills/document-revision-history/SKILL.md

@@ -1,104 +0,0 @@
----
-name: Document Revision History
-description: Manages a revision history table at the beginning of generated documents, tracking changes per version.
----
-# Document Revision History
-
-Manage a revision history table at the beginning of every generated or updated document. This ensures traceability of changes across document versions.
-
-## Policy
-
-### 1. Revision History Table Required
-
-Every document generated or updated by the agent MUST include a **Revision History** table immediately after the document title (before the Table of Contents or Section 1).
-
-### 2. Table Format
-
-Use the following markdown table format:
-
-```markdown
-| Version | Date | Author | Changes |
-|---------|------|--------|---------|
-| 1.0 | 2026-03-02 | Agent (Claude) | Initial document generation |
-```
-
-### 3. Column Definitions
-
-| Column | Description |
-|--------|-------------|
-| **Version** | Document version number (e.g., 1.0, 1.1, 2.0). Use semantic versioning: major version for structural changes, minor for content updates |
-| **Date** | Date of the change in `YYYY-MM-DD` format |
-| **Author** | Who made the change — use `Agent (<model>)` for AI-generated content, or the user's name for user-directed changes |
-| **Changes** | Brief summary of ALL changes made in this version. One line per version — consolidate multiple changes into a single descriptive entry |
-
-### 4. Rules for New Documents
-
-When **generating a new document** for the first time:
-- Add the revision history table immediately after the document title
-- Set version to `1.0`
-- Set date to today's date
-- Set author to `Agent (<model>)` where `<model>` is the AI model name
-- Set changes to `Initial document generation`
-
-### 5. Rules for Updated Documents
-
-When **updating an existing document**:
-- Read the existing revision history table
-- Determine the new version number:
-  - **Minor increment** (e.g., 1.0 → 1.1): Content updates, corrections, additions to existing sections
-  - **Major increment** (e.g., 1.1 → 2.0): Structural changes, section reorganization, significant rewrites
-- Add a **single new row** summarizing ALL changes made in this update session
-- Do NOT create multiple rows for changes made in the same session — consolidate them into one line
-- Preserve all previous revision history entries
-
-### 6. Changes Column Guidelines
-
-Write concise but descriptive change summaries:
-
-**Good examples:**
-- `Added Sections 7-8 (impacts, analysis), expanded interface requirements to cover categories a-g`
-- `Updated capability requirements based on user feedback, added 3 new interfaces`
-- `Fixed traceability matrix, corrected section numbering`
-
-**Bad examples:**
-- `Updated document` (too vague)
-- `Changed section 3.2.1 requirement SRS-CAP-001 description from X to Y, then changed 3.2.2...` (too granular — summarize)
-
-### 7. Placement
-
-The revision history table MUST appear in this order within the document:
-
-```markdown
-# Document Title
-
-| Version | Date | Author | Changes |
-|---------|------|--------|---------|
-| 1.0 | 2026-03-02 | Agent (Claude) | Initial document generation |
-
-> MIL-STD-498 or other document metadata...
-
-## Table of Contents (if applicable)
-
-## 1. Scope
-...
-```
-
-### 8. Multi-Author Sessions
-
-If the user provides their name or the changes are user-directed corrections:
-- Use the user's name as author
-- If both the agent and user contribute in the same session, use `{user_name} / Agent (<model>)`
-
-## Example
-
-A document updated twice would have:
-
-```markdown
-# Software Requirements Specification (SRS)
-
-| Version | Date | Author | Changes |
-|---------|------|--------|---------|
-| 1.0 | 2026-03-01 | Agent (Claude) | Initial document generation from SSDD and PRD artifacts |
-| 1.1 | 2026-03-02 | Joseph / Agent (Claude) | Added 4 interface requirements per user feedback, corrected capability traceability to SSDD |
-| 2.0 | 2026-03-15 | Agent (Claude) | Major rewrite: restructured CSCI decomposition after SSDD v2.0, updated all requirement IDs |
-```