ma-agents 2.20.3 → 2.22.0

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

@@ -0,0 +1,50 @@
+---
+name: Logging Best Practices
+description: Standardizes structured logging across Backend, Frontend, Realtime, and Algorithmic domains with mandatory exception handling.
+---
+# 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/.opencode/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/.opencode/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/.opencode/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/.opencode/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/.opencode/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/.opencode/skills/open-presentation/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: Open Presentation
+description: Opens the BMAD-METHOD AI Development Training presentation from _bmad-output/methodology/
+---
+# 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/.opencode/skills/opentelemetry-best-practices/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: OpenTelemetry Best Practices
+description: Standardizes distributed tracing, metrics, and semantic conventions for high-quality system observability.
+---
+# OpenTelemetry Best Practices
+
+Guidelines for implementing standardized distributed tracing and metrics using OpenTelemetry to ensure high-quality observability.
+
+## Mandatory Policies
+
+### 1. Semantic Conventions
+You MUST use OpenTelemetry Semantic Conventions for all attribute names. Never invent custom names for standard concepts (e.g., use `http.method` instead of `method` or `http_method`).
+
+### 2. Context Propagation
+You MUST ensure trace context is propagated across asynchronous boundaries. When starting a background task or making a network call, ensure the active span is correctly parented or the context is injected into headers.
+
+### 3. Span Granularity
+- **Database**: Every query MUST have its own span with attributes for the statement (sanitized) and database name.
+- **External API**: Every outgoing request MUST have a span.
+- **Complex Logic**: Large internal computation blocks SHOULD have spans if they represent a distinct logical step.
+
+### 4. Meaningful Metrics
+- **Counters**: Use for discrete events (e.g., `api.requests.total`).
+- **Histograms**: Use for durations and sizes (e.g., `api.latency`).
+- **Attributes**: Common attributes (e.g., `status_code`, `service.name`) SHOULD be applied to both spans and metrics.
+
+## Critical Rules
+- **No Sensitive Data**: Never include PII, passwords, or tokens in span attributes or logs associated with spans.
+- **Fail Gracefully**: Instrumentation should never crash the application. Use `tracer.startActiveSpan` carefully with `try...finally` to ensure spans are always ended.
+- **Status Codes**: Always set the span status to `Error` when an exception is caught that isn't handled.
+
+## Resources
+- [Semantic Conventions Reference](file:///skills/opentelemetry-best-practices/references/otel-standards.md)
+- [Example Implementations](file:///skills/opentelemetry-best-practices/examples/javascript.md)

package/.opencode/skills/opentelemetry-best-practices/examples/go.md

@@ -0,0 +1,32 @@
+# OpenTelemetry Go Examples
+
+Idiomatic usage of the OpenTelemetry Go SDK.
+
+## Context-Aware Tracing
+
+```go
+import (
+	"context"
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/attribute"
+	"go.opentelemetry.io/otel/codes"
+)
+
+var tracer = otel.Tracer("my-service")
+
+func (s *Server) GetUser(ctx context.Context, id string) (*User, error) {
+	ctx, span := tracer.Start(ctx, "GetUser")
+	defer span.End()
+
+	span.SetAttributes(attribute.String("user.id", id))
+
+	user, err := s.db.FetchUser(ctx, id)
+	if err != nil {
+		span.RecordError(err)
+		span.SetStatus(codes.Error, err.Error())
+		return nil, err
+	}
+
+	return user, nil
+}
+```

package/.opencode/skills/opentelemetry-best-practices/examples/javascript.md

@@ -0,0 +1,58 @@
+# OpenTelemetry JavaScript (Node.js) Examples
+
+Idiomatic usage of the OpenTelemetry SDK in Node.js applications.
+
+## Tracing a Function
+
+```javascript
+const { trace } = require('@opentelemetry/api');
+
+const tracer = trace.getTracer('my-service');
+
+async function processOrder(orderId) {
+  // Use startActiveSpan to automatically handle context propagation
+  return tracer.startActiveSpan('process.order', async (span) => {
+    try {
+      // Set semantic attributes
+      span.setAttribute('order.id', orderId);
+      
+      const result = await someDatabaseCall(orderId);
+      
+      span.setStatus({ code: SpanStatusCode.OK });
+      return result;
+    } catch (error) {
+      span.recordException(error);
+      span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
+      throw error;
+    } finally {
+      span.end();
+    }
+  });
+}
+```
+
+## Creating Metrics
+
+```javascript
+const { metrics } = require('@opentelemetry/api');
+
+const meter = metrics.getMeter('my-service');
+
+const requestCounter = meter.createCounter('api.requests.total', {
+  description: 'Total number of API requests',
+});
+
+const latencyHistogram = meter.createHistogram('api.latency', {
+  description: 'API request latency',
+  unit: 'ms',
+});
+
+function handleRequest(req) {
+  const startTime = Date.now();
+  
+  // Logic...
+  
+  requestCounter.add(1, { 'http.method': req.method, 'status_code': 200 });
+  latencyHistogram.record(Date.now() - startTime, { 'http.method': req.method });
+}
+```

package/.opencode/skills/opentelemetry-best-practices/examples/python.md

@@ -0,0 +1,37 @@
+# OpenTelemetry Python Examples
+
+Idiomatic usage of the OpenTelemetry Python SDK.
+
+## Tracing with Decorators
+
+```python
+from opentelemetry import trace
+
+tracer = trace.get_tracer(__name__)
+
+@tracer.start_as_current_span("process_data")
+def process_data(data):
+    span = trace.get_current_span()
+    span.set_attribute("data.size", len(data))
+    
+    # Process...
+    return True
+```
+
+## Manual Span Management
+
+```python
+def fetch_external_resource(url):
+    with tracer.start_as_current_span("http_request") as span:
+        span.set_attribute("http.url", url)
+        span.set_attribute("http.method", "GET")
+        
+        try:
+            response = requests.get(url)
+            span.set_attribute("http.status_code", response.status_code)
+            return response.json()
+        except Exception as e:
+            span.record_exception(e)
+            span.set_status(trace.Status(trace.StatusCode.ERROR))
+            raise
+```

package/.opencode/skills/opentelemetry-best-practices/references/otel-standards.md

@@ -0,0 +1,37 @@
+# OpenTelemetry Standards & Semantic Conventions
+
+This document outlines the specific attributes and naming conventions to follow when instrumenting services.
+
+## Common Attributes
+
+| Attribute | Description | Example |
+|-----------|-------------|---------|
+| `service.name` | Logical name of the service | `user-auth-service` |
+| `service.version` | Version of the service | `1.2.3` |
+| `deployment.environment` | Target environment | `production` |
+
+## HTTP Semantic Conventions
+
+| Attribute | Description | Example |
+|-----------|-------------|---------|
+| `http.method` | HTTP request method | `GET` |
+| `http.status_code` | response status | `200` |
+| `http.url` | Full request URL | `https://api.example.com/v1/users` |
+| `http.user_agent` | User agent header | `Mozilla/5.0...` |
+
+## Database Semantic Conventions
+
+| Attribute | Description | Example |
+|-----------|-------------|---------|
+| `db.system` | Database vendor | `postgresql` |
+| `db.statement` | Sanitized SQL/query | `SELECT * FROM users WHERE id = ?` |
+| `db.name` | Database name | `prod_db` |
+| `db.operation` | Operation name | `SELECT` |
+
+## Span Status Values
+- **Unset**: Default status.
+- **Ok**: Explicitly marked as successful.
+- **Error**: Encountered a failure. Describe the error in the `exception` event or attributes.
+
+## Useful links
+- [Official OTel Semantic Conventions](https://opentelemetry.io/docs/specs/otel/common/semantic-conventions/)