ma-agents 1.4.0 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ma-agents",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "NPX tool to install skills for AI coding agents (Claude Code, Gemini, Copilot, Kilocode, Cline, Cursor)",
   "main": "index.js",
   "bin": {
@@ -32,4 +32,4 @@
   "engines": {
     "node": ">=14.0.0"
   }
-}
+}

package/skills/README.md

@@ -191,6 +191,31 @@ Creates production-ready hardened Docker configurations following security best
 
 ---
 
+### 5. Test-Accompanied Development (TAD)
+**Directory:** `test-accompanied-development/`
+
+Enforces a "Test-Alongside" policy where every public method is accompanied by a corresponding unit test. It ensures high code quality by mandating that all public interfaces are verified by automated tests at the moment of creation.
+
+**Key Features:**
+- ✅ **Automatic Enforcement**: Mandates tests for every new public method.
+- ✅ **Integration**: References `test-generator` for implementation standards.
+- ✅ **Workflow Guardrail**: Prevents "test debt" by requiring tests alongside code.
+
+---
+
+### 6. Logging Best Practices
+**Directory:** `logging-best-practices/`
+
+Standardizes structured logging (JSON) across Backend, Frontend, Realtime, and Algorithmic domains. Enforces mandatory exception logging and OpenTelemetry-aligned context fields.
+
+**Key Features:**
+- ✅ **Structured Logging**: Mandates JSON format for machine-readability.
+- ✅ **Domain-Specific**: Tailored guidance for Web, Server, and High-Performance Algorithm domains.
+- ✅ **Mandatory Exceptions**: Every catch block must log full stack traces.
+- ✅ **Context-Rich**: Standardizes fields like `trace_id`, `placement`, and `process_name`.
+
+---
+
 ## Requirements
 
 ### All Skills

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

@@ -0,0 +1,46 @@
+# Logging Best Practices
+
+Enforce structured, context-rich logging according to market standards (OpenTelemetry) across all application domains.
+
+## Policy
+
+**All logs must be structured (preferably JSON) and include mandatory context. Every exception MUST be logged with its full stack trace.**
+
+## Core Mandatory Fields
+
+Every log entry must contain:
+- `datetime`: ISO 8601 timestamp with timezone.
+- `severity`: Standard level (DEBUG, INFO, WARN, ERROR, CRITICAL).
+- `message`: Clear, concise description of the event.
+- `placement`: File name and line number where the log was triggered.
+- `process_name`: Name of the service or application.
+- `container_id`: (If applicable) Docker/K8s container identifier.
+- `trace_id` / `span_id`: For distributed tracing and request correlation.
+
+## Domain-Specific Requirements
+
+### 1. Backend Systems
+- **Log**: Incoming/outgoing requests (method, status, duration).
+- **Log**: Database query latencies and connection states.
+- **Mandatory**: Full exception details in catch blocks.
+
+### 2. Frontend Applications
+- **Log**: Client-side errors (JS runtime, UI crashes).
+- **Log**: User interaction context (last clicked component, breadcrumbs).
+- **Context**: Browser version, OS, Resolution.
+
+### 3. Realtime & Algorithmic Work
+- **Log**: Iteration throughput and step-by-step latency.
+- **Log**: Mathematical anomalies or convergence failures.
+- **Mandatory**: Timeout exceptions and resource exhaustion warnings.
+
+## Rules
+
+- **No PII/Secrets**: Never log passwords, keys, or private user data.
+- **Asynchronous**: Prefer non-blocking logging to maintain performance.
+- **Traceability**: Always include `trace_id` in logs that are part of a request flow.
+- **Exception Policy**: Use the `ERROR` level for caught exceptions that affect flow, and `CRITICAL` for system-wide failures.
+
+## Reference
+
+See [logging-standards.md](./references/logging-standards.md) for detailed field definitions and level guidance.

package/skills/logging-best-practices/examples/cpp.md

@@ -0,0 +1,36 @@
+# C++ Logging Examples
+
+## Structured Logging with `spdlog`
+
+```cpp
+#include "spdlog/spdlog.h"
+#include "spdlog/sinks/stdout_color_sinks.h"
+#include <exception>
+
+void run_realtime_loop() {
+    auto logger = spdlog::get("realtime_logger");
+    
+    try {
+        // Realtime/Algorithmic domain logging
+        logger->info("Computation step started. Input size: {}. Placement: {}:{}", 
+                     1024, __FILE__, __LINE__);
+        
+        if (check_anomaly()) {
+            logger->warn("Numerical anomaly detected! Severity: WARN");
+        }
+        
+    } catch (const std::exception& e) {
+        // Mandatory Exception Logging
+        logger->critical("Critical failure in realtime loop! Error: {}. File: {}. Line: {}", 
+                        e.what(), __FILE__, __LINE__);
+        throw;
+    }
+}
+
+// Global setup for JSON output
+void setup_logging() {
+    // Note: spdlog requires a custom formatter or sink for pure JSON output 
+    // to match OTel standards perfectly.
+    spdlog::set_pattern("{\"datetime\":\"%Y-%m-%dT%H:%M:%SZ\",\"severity\":\"%l\",\"message\":\"%v\",\"process_name\":\"engine_v1\"}");
+}
+```

package/skills/logging-best-practices/examples/csharp.md

@@ -0,0 +1,49 @@
+# C# Logging Examples
+
+## Structured Logging with Serilog
+
+```csharp
+using Serilog;
+using System;
+
+public class DataService
+{
+    private readonly ILogger _logger = Log.ForContext<DataService>();
+
+    public void ProcessAlgorithm(double[] data)
+    {
+        try
+        {
+            _logger.Information("Algorithm iteration started. Data points: {Count}. Placement: {Placement}", 
+                data.Length, "DataService.cs:45");
+
+            // Realtime/Algorithmic specific logging
+            var startTime = DateTime.UtcNow;
+            RunComplexMath(data);
+            var duration = (DateTime.UtcNow - startTime).TotalMilliseconds;
+
+            _logger.Information("Iteration complete. Latency: {Latency}ms", duration);
+        }
+        catch (Exception ex)
+        {
+            // Mandatory Exception Logging
+            _logger.Error(ex, "Algorithm execution failed at {Placement}. Container: {ContainerId}", 
+                "DataService.cs:55", Environment.GetEnvironmentVariable("HOSTNAME"));
+        }
+    }
+}
+```
+
+## Microsoft.Extensions.Logging (JSON Console)
+
+```csharp
+// In Program.cs
+builder.Logging.AddJsonConsole(options => {
+    options.TimestampFormat = "yyyy-MM-ddTHH:mm:ssZ ";
+    options.JsonWriterOptions = new JsonWriterOptions { Indented = true };
+});
+
+// Usage
+_logger.LogError(exception, "Request failed at {Placement}. TraceId: {TraceId}", 
+    "OrderController.cs:120", HttpContext.TraceIdentifier);
+```

package/skills/logging-best-practices/examples/javascript.md

@@ -0,0 +1,77 @@
+# JavaScript/TypeScript Logging Examples
+
+## Backend (Node.js with `pino` or `winston`)
+
+```typescript
+import pino from 'pino';
+
+const logger = pino({
+  level: process.env.LOG_LEVEL || 'info',
+  formatters: {
+    level: (label) => {
+      return { severity: label.toUpperCase() };
+    },
+  },
+  base: {
+    process_name: 'api-gateway',
+    container_id: process.env.HOSTNAME || 'unknown'
+  }
+});
+
+async function handleRequest(req, res) {
+  const traceId = req.headers['x-trace-id'];
+  try {
+    logger.info({ 
+      msg: 'Handling incoming request', 
+      trace_id: traceId,
+      path: req.path,
+      placement: 'router.ts:12'
+    });
+    
+    // ... logic
+  } catch (error) {
+    // Mandatory Exception Logging
+    logger.error({
+      msg: 'Request handler failed',
+      trace_id: traceId,
+      err: error, // Pino automatically formats the stack trace
+      severity: 'ERROR',
+      placement: 'router.ts:25'
+    });
+    res.status(500).send('Internal Server Error');
+  }
+}
+```
+
+## Frontend (Browser)
+
+```javascript
+const logToServer = async (logEntry) => {
+  try {
+    await fetch('/api/logs', {
+      method: 'POST',
+      body: JSON.stringify({
+        ...logEntry,
+        datetime: new Date().toISOString(),
+        browser: navigator.userAgent,
+        process_name: 'frontend-spa'
+      })
+    });
+  } catch (e) {
+    console.error('Failed to ship logs', e);
+  }
+};
+
+// Global error handler
+window.onerror = function(msg, url, lineNo, columnNo, error) {
+  logToServer({
+    severity: 'ERROR',
+    message: msg,
+    placement: `${url}:${lineNo}`,
+    exception: {
+      message: error?.message,
+      stack: error?.stack
+    }
+  });
+};
+```

package/skills/logging-best-practices/examples/python.md

@@ -0,0 +1,57 @@
+# Python Logging Examples
+
+## Structured Logging with `structlog`
+
+```python
+import structlog
+import os
+
+logger = structlog.get_logger()
+
+def process_data(data):
+    try:
+        # Algorithmic step logging
+        logger.info("calculation_step_started",
+                    step="matrix_multiplication",
+                    data_size=len(data),
+                    placement="processor.py:45")
+        
+        result = perform_complex_math(data)
+        return result
+    except Exception as e:
+        # Mandatory Exception Logging
+        logger.error("calculation_failed",
+                     exception_type=type(e).__name__,
+                     exception_msg=str(e),
+                     stack_trace=True, # structlog captures this
+                     severity="ERROR",
+                     placement="processor.py:52",
+                     container_id=os.getenv("HOSTNAME"))
+        raise
+```
+
+## Standard Library with JSON Formatter
+
+```python
+import logging
+import json
+from datetime import datetime
+
+class JsonFormatter(logging.Formatter):
+    def format(self, record):
+        log_entry = {
+            "datetime": datetime.utcnow().isoformat(),
+            "severity": record.levelname,
+            "message": record.getMessage(),
+            "placement": f"{record.filename}:{record.lineno}",
+            "process_name": record.processName,
+            "trace_id": getattr(record, 'trace_id', 'none')
+        }
+        if record.exc_info:
+            log_entry["exception"] = self.formatException(record.exc_info)
+        return json.dumps(log_entry)
+
+# usage
+logger = logging.getLogger("backend_service")
+logger.error("Database connection failed", exc_info=True)
+```

package/skills/logging-best-practices/references/logging-standards.md

@@ -0,0 +1,29 @@
+# Logging Standards Reference
+
+This document defines the semantic conventions and levels used in the Logging Best Practices skill.
+
+## Log Levels
+
+| Level | Usage |
+| :--- | :--- |
+| **TRACE** | Fine-grained informational events (mostly for debugging logic flows). |
+| **DEBUG** | Detailed information for developer troubleshooting. |
+| **INFO** | Regular operational events (startup, shutdown, successful requests). |
+| **WARN** | Potential issues or degraded states that don't stop the service. |
+| **ERROR** | Operational failures that affect a specific request or operation. |
+| **CRITICAL** | System-wide failures requiring immediate attention. |
+
+## OpenTelemetry Semantic Conventions
+
+To ensure interoperability, use the following field names where possible:
+
+- `timestamp`: The time when the event occurred.
+- `severity_text`: The string representation of the log level.
+- `body`: The primary log message.
+- `attributes.service.name`: The value of `process_name`.
+- `attributes.container.id`: The value of `container_id`.
+- `attributes.code.filepath`: Path to the source file.
+- `attributes.code.lineno`: Line number in the source file.
+- `attributes.exception.type`: Class name of the exception.
+- `attributes.exception.message`: Message from the exception.
+- `attributes.exception.stacktrace`: Full stack trace.

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

@@ -0,0 +1,13 @@
+{
+    "name": "Logging Best Practices",
+    "description": "Standardizes structured logging across Backend, Frontend, Realtime, and Algorithmic domains with mandatory exception handling.",
+    "version": "1.0.0",
+    "author": "Antigravity",
+    "tags": [
+        "logging",
+        "observability",
+        "json",
+        "opentelemetry",
+        "quality"
+    ]
+}

package/skills/test-accompanied-development/SKILL.md

@@ -0,0 +1,39 @@
+# Test-Accompanied Development (TAD)
+
+Enforce a "Test-Alongside" policy where every public method is accompanied by a corresponding unit test.
+
+## Purpose
+
+To ensure high code quality and maintainability by mandating that all public interfaces are verified by automated tests at the moment of creation.
+
+## Policy
+
+**Every new public method/function you write MUST be accompanied by at least one unit test.**
+
+## When to Use
+
+- Use this skill **every time** you are about to write a new public method or function.
+- This skill should be active during the coding phase of any feature or bug fix.
+
+## Instructions
+
+1.  **Identify Public Exports**: When preparing to write a new class, module, or function, identify which methods will be public/exported.
+2.  **Plan the Test**: Before or immediately after writing the method signature, plan the corresponding test cases (Happy Path, Edge Cases, Error Cases).
+3.  **Write the Method**: Implement the public method.
+4.  **Write the Tests**: Immediately write the unit tests for the method. 
+    - Refer to the `test-generator` skill for best practices on how to structure these tests (AAA pattern, Mocking, etc.).
+    - Ensure tests are placed in the appropriate test directory of the project.
+5.  **Verify**: Run the tests to ensure they pass before considering the method "done".
+
+## Rules
+
+- **No Public Method without Tests**: Do not consider a public method complete until its corresponding test file exists and passes.
+- **Refer to Test Generator**: Use the `test-generator` skill as the standard for test quality and structure.
+- **Traceability**: Mention the test file location when adding the public method.
+
+## Example Workflow
+
+1.  **Agent**: "I am adding a `calculateTotal` method to the `InvoiceService`. I will also create `InvoiceService.test.ts` to verify it."
+2.  **Agent**: [Writes `calculateTotal` in `InvoiceService.ts`]
+3.  **Agent**: [Writes tests in `InvoiceService.test.ts` using `test-generator` patterns]
+4.  **Agent**: "Method and tests are complete. Running tests now..."

package/skills/test-accompanied-development/skill.json

@@ -0,0 +1,12 @@
+{
+    "name": "Test-Accompanied Development",
+    "description": "Enforces writing unit tests for every new public method created by the agent.",
+    "version": "1.0.0",
+    "author": "Antigravity",
+    "tags": [
+        "testing",
+        "quality",
+        "policy",
+        "tdd"
+    ]
+}