ma-agents 3.2.0 → 3.3.0

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

@@ -0,0 +1,278 @@
+---
+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

@@ -0,0 +1,28 @@
+---
+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

@@ -0,0 +1,39 @@
+#!/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

@@ -0,0 +1,28 @@
+---
+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

@@ -0,0 +1,33 @@
+#!/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

@@ -0,0 +1,104 @@
+---
+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 |
+```