ma-agents 2.19.2 → 2.20.0

package/.cline/skills/js-ts-security-skill/scripts/verify-security.sh

@@ -0,0 +1,136 @@
+#!/bin/bash
+
+# JS/TS Security Verification Script (OWASP Top 10 2025)
+# This script performs a series of security checks on a JavaScript/TypeScript project.
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+CYAN='\033[0;36m'
+NC='\033[0m' # No Color
+
+echo -e "${CYAN}====================================================${NC}"
+echo -e "${CYAN}   JS/TS Security Audit - OWASP Top 10 2025         ${NC}"
+echo -e "${CYAN}====================================================${NC}\n"
+
+# A03:2025 - Software Supply Chain Failures
+echo -e "${YELLOW}[1/5] A03:2025 - Software Supply Chain Failures${NC}"
+SUPPLY_CHAIN_ISSUES=0
+if [ ! -f "package-lock.json" ] && [ ! -f "yarn.lock" ] && [ ! -f "pnpm-lock.yaml" ]; then
+    echo -e "${RED}✗ CRITICAL: No lockfile found (package-lock.json, yarn.lock, or pnpm-lock.yaml).${NC}"
+    echo "  Impact: Non-deterministic builds increase supply chain vulnerability."
+    SUPPLY_CHAIN_ISSUES=$((SUPPLY_CHAIN_ISSUES + 1))
+fi
+
+HTTP_REGISTRY=$(grep -r "http://" package.json 2>/dev/null)
+if [ ! -z "$HTTP_REGISTRY" ]; then
+    echo -e "${RED}✗ WARNING: Insecure registry found in package.json (using HTTP instead of HTTPS).${NC}"
+    echo "$HTTP_REGISTRY"
+    SUPPLY_CHAIN_ISSUES=$((SUPPLY_CHAIN_ISSUES + 1))
+fi
+
+if [ $SUPPLY_CHAIN_ISSUES -eq 0 ]; then
+    echo -e "${GREEN}✓ No immediate supply chain issues found.${NC}\n"
+else
+    echo -e "${RED}✗ Total supply chain issues: $SUPPLY_CHAIN_ISSUES${NC}\n"
+fi
+
+# A03:2025 / A06:2021 - Dependency Audit
+echo -e "${YELLOW}[2/5] A03:2025 - Vulnerable Components (Audit)${NC}"
+if [ -f "package-lock.json" ]; then
+    npm audit --audit-level=high
+    AUDIT_EXIT=$?
+elif [ -f "yarn.lock" ]; then
+    yarn audit --level high
+    AUDIT_EXIT=$?
+else
+    echo -e "${YELLOW}  Skipping dependency audit: No lockfile found.${NC}"
+    AUDIT_EXIT=0
+fi
+
+if [ $AUDIT_EXIT -eq 0 ]; then
+    echo -e "${GREEN}✓ No high-severity vulnerabilities in dependencies.${NC}\n"
+else
+    echo -e "${RED}✗ Vulnerabilities found. Run 'npm audit fix'.${NC}\n"
+fi
+
+# A01/A04/A05/A08 - Static Analysis (SAST)
+echo -e "${YELLOW}[3/5] Static Analysis (OWASP A01, A04, A05, A08)${NC}"
+declare -A DANGEROUS_PATTERNS
+DANGEROUS_PATTERNS["A01: SSRF/Access Control"]="fetch\(\`|axios\.get\(\`|http\.get\(\`"
+DANGEROUS_PATTERNS["A05: Injection"]="eval\(|new Function\(|child_process\.exec\(|require\('child_process'\)\.exec"
+DANGEROUS_PATTERNS["A04: Cryptographic Failures"]="crypto\.createHash\('md5'\)|crypto\.createHash\('sha1'\)|Math\.random\(\)"
+DANGEROUS_PATTERNS["A08: Software/Data Integrity"]="unserialize\(|JSON\.parse\("
+DANGEROUS_PATTERNS["A07: Authentication Failures"]="res\.cookie\(.*httpOnly: false|res\.cookie\(.*secure: false"
+
+FOUND_ISSUES=0
+for cat in "A01: SSRF/Access Control" "A05: Injection" "A04: Cryptographic Failures" "A08: Software/Data Integrity" "A07: Authentication Failures"; do
+    pattern=${DANGEROUS_PATTERNS[$cat]}
+    MATCHES=$(grep -rnE "$pattern" --include="*.js" --include="*.ts" --exclude-dir=node_modules . 2>/dev/null)
+    if [ ! -z "$MATCHES" ]; then
+        echo -e "${RED}✗ Found Risk: [$cat]${NC}"
+        echo "$MATCHES" | sed 's/^/  /'
+        FOUND_ISSUES=$((FOUND_ISSUES + 1))
+    fi
+done
+
+if [ $FOUND_ISSUES -eq 0 ]; then
+    echo -e "${GREEN}✓ No dangerous patterns detected via SAST.${NC}\n"
+else
+    echo -e "${RED}✗ Total dangerous patterns: $FOUND_ISSUES${NC}\n"
+fi
+
+# A10:2025 - Mishandling of Exceptional Conditions
+echo -e "${YELLOW}[4/5] A10:2025 - Mishandling of Exceptional Conditions${NC}"
+EMPTY_CATCH=$(grep -rnE "catch\s*\(\w*\)\s*\{\s*\}" --include="*.js" --include="*.ts" --exclude-dir=node_modules . 2>/dev/null)
+FOUND_EXCEPTION_ISSUES=0
+if [ ! -z "$EMPTY_CATCH" ]; then
+    echo -e "${RED}✗ Found Risk: Empty catch blocks (Swallowing exceptions)${NC}"
+    echo "$EMPTY_CATCH" | sed 's/^/  /'
+    FOUND_EXCEPTION_ISSUES=$((FOUND_EXCEPTION_ISSUES + 1))
+fi
+
+if [ $FOUND_EXCEPTION_ISSUES -eq 0 ]; then
+    echo -e "${GREEN}✓ Exception handling patterns appear secure.${NC}\n"
+else
+    echo -e "${RED}✗ Total exception handling issues: $FOUND_EXCEPTION_ISSUES${NC}\n"
+fi
+
+# Secret Detection (A01/A07)
+echo -e "${YELLOW}[5/5] A01/A07 - Hardcoded Secrets Scanning${NC}"
+SECRET_PATTERNS=("AIza[0-9A-Za-z-_]{35}" "sk_live_[0-9a-zA-Z]{24}" "xox[pb]-[0-9]{12}-[0-9]{12}-[0-9]{12}-[a-z0-9]{32}" "-----BEGIN RSA PRIVATE KEY-----")
+
+FOUND_SECRETS=0
+for pattern in "${SECRET_PATTERNS[@]}"; do
+    MATCHES=$(grep -rnE "$pattern" --include="*.js" --include="*.ts" --include="*.env" --exclude-dir=node_modules . 2>/dev/null)
+    if [ ! -z "$MATCHES" ]; then
+        echo -e "${RED}✗ Found Risk: Potential secret leakage ($pattern)${NC}"
+        echo "$MATCHES" | sed 's/^/  /'
+        FOUND_SECRETS=$((FOUND_SECRETS + 1))
+    fi
+done
+
+if [ $FOUND_SECRETS -eq 0 ]; then
+    echo -e "${GREEN}✓ No hardcoded secrets detected.${NC}\n"
+else
+    echo -e "${RED}✗ Total secrets found: $FOUND_SECRETS${NC}\n"
+fi
+
+# Summary
+echo -e "${CYAN}----------------------------------------------------${NC}"
+echo -e "${CYAN}   OWASP 2025 Audit Summary                         ${NC}"
+echo -e "${CYAN}----------------------------------------------------${NC}"
+[ $SUPPLY_CHAIN_ISSUES -eq 0 ] && echo -e "A03: Supply Chain        - ${GREEN}PASS${NC}" || echo -e "A03: Supply Chain        - ${RED}FAIL${NC}"
+[ $AUDIT_EXIT -eq 0 ]           && echo -e "A03: Vulnerabilities     - ${GREEN}PASS${NC}" || echo -e "A03: Vulnerabilities     - ${RED}FAIL${NC}"
+[ $FOUND_ISSUES -eq 0 ]        && echo -e "A01/04/05/08: Code Patterns - ${GREEN}PASS${NC}" || echo -e "A01/04/05/08: Code Patterns - ${RED}FAIL${NC}"
+[ $FOUND_EXCEPTION_ISSUES -eq 0 ] && echo -e "A10: Exception Handling  - ${GREEN}PASS${NC}" || echo -e "A10: Exception Handling  - ${RED}FAIL${NC}"
+[ $FOUND_SECRETS -eq 0 ]       && echo -e "A01/A07: Secrets         - ${GREEN}PASS${NC}" || echo -e "A01/A07: Secrets         - ${RED}FAIL${NC}"
+echo -e "${CYAN}----------------------------------------------------${NC}"
+
+if [ $AUDIT_EXIT -eq 0 ] && [ $FOUND_ISSUES -eq 0 ] && [ $FOUND_SECRETS -eq 0 ] && [ $SUPPLY_CHAIN_ISSUES -eq 0 ] && [ $FOUND_EXCEPTION_ISSUES -eq 0 ]; then
+    echo -e "${GREEN}Final Result: SECURE${NC}"
+    exit 0
+else
+    echo -e "${RED}Final Result: VULNERABLE${NC}"
+    exit 1
+fi

package/.cline/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/.cline/skills/logging-best-practices/docs/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/.cline/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/.cline/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/.cline/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/.cline/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/.cline/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/.cline/skills/opentelemetry-best-practices/docs/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/)

package/.cline/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/.cline/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/.cline/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
+```