ma-agents 3.4.8 → 3.5.0

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

@@ -1,50 +0,0 @@
----
-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/.roo/skills/logging-best-practices/examples/cpp.md

@@ -1,36 +0,0 @@
-# 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/.roo/skills/logging-best-practices/examples/csharp.md

@@ -1,49 +0,0 @@
-# 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/.roo/skills/logging-best-practices/examples/javascript.md

@@ -1,77 +0,0 @@
-# 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/.roo/skills/logging-best-practices/examples/python.md

@@ -1,57 +0,0 @@
-# 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/.roo/skills/logging-best-practices/references/logging-standards.md

@@ -1,29 +0,0 @@
-# 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/.roo/skills/open-presentation/SKILL.md

@@ -1,35 +0,0 @@
----
-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/.roo/skills/opentelemetry-best-practices/SKILL.md

@@ -1,34 +0,0 @@
----
-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/.roo/skills/opentelemetry-best-practices/examples/go.md

@@ -1,32 +0,0 @@
-# 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/.roo/skills/opentelemetry-best-practices/examples/javascript.md

@@ -1,58 +0,0 @@
-# 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/.roo/skills/opentelemetry-best-practices/examples/python.md

@@ -1,37 +0,0 @@
-# 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/.roo/skills/opentelemetry-best-practices/references/otel-standards.md

@@ -1,37 +0,0 @@
-# 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/)