ma-agents 1.8.0 → 1.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ma-agents",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "NPX tool to install skills for AI coding agents (Claude Code, Gemini, Copilot, Kilocode, Cline, Cursor)",
   "main": "index.js",
   "bin": {

package/skills/README.md

@@ -216,6 +216,30 @@ Standardizes structured logging (JSON) across Backend, Frontend, Realtime, and A
 
 ---
 
+### 7. OpenTelemetry Best Practices
+**Directory:** `opentelemetry-best-practices/`
+
+Standardizes distributed tracing, metrics, and semantic conventions for high-quality system observability. Enforces trace context propagation and OTel semantic naming.
+
+**Key Features:**
+- ✅ **Standardized Tracing**: Mandates spans for DB calls and external requests.
+- ✅ **Semantic Conventions**: Enforces OTel naming standards.
+- ✅ **Context Propagation**: Ensures trace IDs flow across async boundaries.
+
+---
+
+### 8. C++ Safe Memory Handling
+**Directory:** `cpp-memory-handling/`
+
+Enforces Modern C++ practices (RAII, Smart Pointers) to prevent memory leaks and dangling pointers.
+
+**Key Features:**
+- ✅ **Smart Pointers**: Mandates `std::unique_ptr` and `std::shared_ptr`.
+- ✅ **RAII**: Ensures every resource is bound to object lifetimes.
+- ✅ **Safe Containers**: Forbids raw buffers in favor of `std::vector` and `std::string`.
+
+---
+
 ## Requirements
 
 ### All Skills

package/skills/cpp-memory-handling/SKILL.md

@@ -0,0 +1,38 @@
+# C++ Safe Memory Handling
+
+Guidelines for writing robust, memory-safe C++ code by leveraging Modern C++ features and RAII principles.
+
+## Mandatory Policies
+
+### 1. Smart Pointers by Default
+You MUST use smart pointers for all heap allocations.
+- Use `std::unique_ptr` for exclusive ownership. This is the preferred default.
+- Use `std::shared_ptr` only when multiple objects share ownership of a resource.
+- Use `std::weak_ptr` to break circular dependencies or for non-owning references that must be checked for validity.
+
+### 2. Forbid raw new/delete
+You MUST NOT use raw `new` and `delete` operators.
+- Use `std::make_unique` (C++14+) or `std::make_shared` to allocate objects on the heap.
+- Exceptions are only allowed within low-level custom container implementations, which must be encapsulated.
+
+### 3. Prefer Value Semantics
+Always prefer stack-allocated objects and value semantics over pointer-based indirection unless heap allocation is strictly necessary (e.g., polymorphism, very large objects, or dynamic lifetimes).
+
+### 4. RAII for All Resources
+Every resource (file handles, sockets, mutexes, memory) MUST be managed by an object whose constructor acquires the resource and destructor releases it. Never rely on manual cleanup blocks.
+
+### 5. Standard Containers
+NEVER use raw buffers or manually managed arrays.
+- Use `std::vector` for dynamic arrays.
+- Use `std::string` for text.
+- Use `std::array` (C++11) for fixed-size stack arrays.
+- Access elements using `.at()` if bounds checking is required for security-critical logic.
+
+## Critical Rules
+- **No Dangling Pointers**: Never return a pointer or reference to a local stack-allocated variable.
+- **Rule of Zero/Five**: Follow the "Rule of Zero" (prefer components that handle their own resource management). If manual management is needed, correctly implement the "Rule of Five".
+- **Nullable Checks**: Always check pointers (even smart ones) for `nullptr` before dereferencing if there is any chance they could be empty.
+
+## Resources
+- [Modern C++ Examples](file:///skills/cpp-memory-handling/examples/modern-cpp.md)
+- [Smart Pointer Reference](file:///skills/cpp-memory-handling/examples/smart-pointers.md)

package/skills/cpp-memory-handling/examples/modern-cpp.md

@@ -0,0 +1,49 @@
+# Modern C++ Safe Memory Examples
+
+Demonstrating RAII and safe resource management in modern C++.
+
+## RAII Resource Management
+
+```cpp
+#include <iostream>
+#include <fstream>
+#include <vector>
+#include <memory>
+
+class FileHandler {
+public:
+    FileHandler(const std::string& filename) : file(filename) {
+        if (!file.is_open()) throw std::runtime_error("Could not open file");
+    }
+    // Destructor automatically closes the file
+    ~FileHandler() { if (file.is_open()) file.close(); }
+
+    void write(const std::string& data) { file << data; }
+
+private:
+    std::ofstream file;
+};
+
+void log_data(const std::string& message) {
+    // RAII handles lifetime. No manual close needed.
+    FileHandler handler("app.log");
+    handler.write(message);
+}
+```
+
+## Vector vs Raw Arrays
+
+```cpp
+// BAD: Manual memory management
+void bad_array() {
+    int* arr = new int[100];
+    // ... logic ...
+    delete[] arr; // Manual cleanup is error-prone
+}
+
+// GOOD: Automatic memory management
+void safe_vector() {
+    std::vector<int> arr(100);
+    // Vector manages its own heap memory. RAII cleans up at scope exit.
+}
+```

package/skills/cpp-memory-handling/examples/smart-pointers.md

@@ -0,0 +1,46 @@
+# C++ Smart Pointer Reference
+
+Guidelines for selecting and using smart pointers correctly.
+
+## unique_ptr (Preferred Default)
+- Represents **exclusive ownership**.
+- Zero runtime overhead compared to raw pointers.
+
+```cpp
+#include <memory>
+
+class Widget { /* ... */ };
+
+void exclusive_use() {
+    // Use make_unique for safety and efficiency
+    auto widget = std::make_unique<Widget>();
+    
+    // Ownership can be moved but not copied
+    std::unique_ptr<Widget> other = std::move(widget);
+}
+```
+
+## shared_ptr (For Shared Ownership)
+- Use only when **multiple** owners truly exist.
+- Reference counting has small overhead.
+
+```cpp
+void shared_use() {
+    auto shared_widget = std::make_shared<Widget>();
+    
+    auto owner1 = shared_widget; // Count = 2
+    auto owner2 = shared_widget; // Count = 3
+}
+```
+
+## weak_ptr (Breaking Cycles)
+- Non-owning reference. Must be locked before use.
+
+```cpp
+void weak_use(std::weak_ptr<Widget> weak_widget) {
+    if (auto shared = weak_widget.lock()) {
+        // Resource is still alive
+        shared->do_something();
+    }
+}
+```

package/skills/cpp-memory-handling/skill.json

@@ -0,0 +1,20 @@
+{
+    "name": "C++ Safe Memory Handling",
+    "description": "Enforces Modern C++ practices (RAII, Smart Pointers) to prevent memory leaks, dangling pointers, and buffer overflows.",
+    "version": "1.0.0",
+    "author": "Antigravity",
+    "tags": [
+        "cpp",
+        "memory-management",
+        "raii",
+        "smart-pointers",
+        "cplusplus",
+        "security"
+    ],
+    "applies_when": [
+        "writing c++ code",
+        "modifying memory-intensive C++ logic",
+        "debugging memory leaks in c++",
+        "implementing new c++ classes"
+    ]
+}

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

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

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

@@ -0,0 +1,19 @@
+{
+    "name": "OpenTelemetry Best Practices",
+    "description": "Standardizes distributed tracing, metrics, and semantic conventions for high-quality system observability.",
+    "version": "1.0.0",
+    "author": "Antigravity",
+    "tags": [
+        "opentelemetry",
+        "observability",
+        "tracing",
+        "metrics",
+        "distributed-systems"
+    ],
+    "applies_when": [
+        "implementing api endpoints",
+        "handling distributed requests",
+        "optimizing performance",
+        "adding monitoring"
+    ]
+}