ma-agents 1.7.0 → 1.9.0

package/bin/cli.js

@@ -120,60 +120,113 @@ async function installWizard(preselectedSkill, preselectedAgents, customPath, fo
   const skills = listSkills();
   const agents = listAgents();
 
+  let selectedSkillIds = preselectedSkill ? [preselectedSkill] : [];
+  let selectedAgentIds = preselectedAgents || [];
+  let installScope = 'project';
+  let installPath = customPath || '';
+
+  const existingStatus = getStatus([], '', 'project');
+  let isUpdate = false;
+
+  // Step 0: Check for existing installation ONLY in interactive mode (no preselected skill)
+  if (!preselectedSkill && !customPath && existingStatus.length > 0) {
+    console.log(chalk.cyan('\n Existing installation detected in project.'));
+
+    const { action } = await prompts({
+      type: 'select',
+      name: 'action',
+      message: 'What would you like to do?',
+      choices: [
+        { title: 'Update (add/remove skills)', value: 'update' },
+        { title: 'Clean reinstall (remove all first)', value: 'reinstall' },
+        { title: 'Uninstall all skills', value: 'uninstall' },
+        { title: 'Cancel', value: 'cancel' }
+      ]
+    });
+
+    if (!action || action === 'cancel') process.exit(0);
+
+    if (action === 'uninstall') {
+      const { confirmed } = await prompts({
+        type: 'confirm',
+        name: 'confirmed',
+        message: 'This will remove all ma-agents skills from this project. Are you sure?',
+        initial: false
+      });
+      if (!confirmed) process.exit(0);
+
+      for (const entry of existingStatus) {
+        for (const skillId of Object.keys(entry.skills)) {
+          await uninstallSkill(skillId, [entry.agent.id], '', 'project');
+        }
+      }
+      console.log(chalk.bold.green('\n All skills successfully removed!\n'));
+      return;
+    }
+
+    if (action === 'reinstall') {
+      for (const entry of existingStatus) {
+        for (const skillId of Object.keys(entry.skills)) {
+          await uninstallSkill(skillId, [entry.agent.id], '', 'project');
+        }
+      }
+      console.log(chalk.gray(' Clean slate prepared.'));
+    }
+
+    if (action === 'update') {
+      isUpdate = true;
+      // Pre-populate selections from existing status
+      const existingSkillIds = new Set();
+      const existingAgentIds = new Set();
+      existingStatus.forEach(entry => {
+        existingAgentIds.add(entry.agent.id);
+        Object.keys(entry.skills).forEach(id => existingSkillIds.add(id));
+      });
+      selectedSkillIds = Array.from(existingSkillIds);
+      selectedAgentIds = Array.from(existingAgentIds);
+    }
+  }
+
   // Step 1: Select skills
-  let selectedSkillIds;
-  if (preselectedSkill) {
-    selectedSkillIds = [preselectedSkill];
-  } else {
+  if (selectedSkillIds.length === 0 || isUpdate) {
     const { skills: chosen } = await prompts({
       type: 'multiselect',
       name: 'skills',
-      message: 'Which skills do you want to install?',
+      message: 'Select the skills you want to have installed:',
       choices: skills.map(s => ({
         title: chalk.white(s.name) + chalk.gray(` v${s.version} - ${s.description}`),
         value: s.id,
-        selected: false
+        selected: selectedSkillIds.includes(s.id)
       })),
       instructions: chalk.gray('  Use space to select, enter to confirm'),
       min: 1
     });
 
-    if (!chosen || chosen.length === 0) {
-      console.log(chalk.yellow('No skills selected. Exiting.'));
-      process.exit(0);
-    }
+    if (!chosen) process.exit(0);
     selectedSkillIds = chosen;
   }
 
   // Step 2: Select agents
-  let selectedAgentIds;
-  if (preselectedAgents && preselectedAgents.length > 0) {
-    selectedAgentIds = preselectedAgents;
-  } else {
+  if (selectedAgentIds.length === 0 || isUpdate) {
     const { agents: chosen } = await prompts({
       type: 'multiselect',
       name: 'agents',
-      message: 'Which coding agents do you want to install to?',
+      message: 'Select which coding agents to include:',
       choices: agents.map(a => ({
         title: chalk.white(a.name) + chalk.gray(` v${a.version} - ${a.description}`),
         value: a.id,
-        selected: false
+        selected: selectedAgentIds.includes(a.id)
       })),
       instructions: chalk.gray('  Use space to select, enter to confirm'),
       min: 1
     });
 
-    if (!chosen || chosen.length === 0) {
-      console.log(chalk.yellow('No agents selected. Exiting.'));
-      process.exit(0);
-    }
+    if (!chosen) process.exit(0);
     selectedAgentIds = chosen;
   }
 
-  // Step 3: Installation scope
-  let installPath = customPath || '';
-  let installScope = 'project';
-  if (!installPath) {
+  // Step 3: Scope (Skip if update, we already know it's project)
+  if (!isUpdate && !installPath) {
     const { pathChoice } = await prompts({
       type: 'select',
       name: 'pathChoice',
@@ -209,16 +262,33 @@ async function installWizard(preselectedSkill, preselectedAgents, customPath, fo
   const { confirmed } = await prompts({
     type: 'confirm',
     name: 'confirmed',
-    message: 'Proceed with installation?',
+    message: isUpdate ? 'Apply changes?' : 'Proceed with installation?',
     initial: true
   });
 
   if (!confirmed) {
-    console.log(chalk.yellow('Installation cancelled.'));
+    console.log(chalk.yellow('Operation cancelled.'));
     process.exit(0);
   }
 
-  // Step 5: Install each skill (with upgrade detection)
+  // Step 5: Execution
+  if (isUpdate) {
+    // Identify removals
+    const currentlyInstalled = new Set();
+    existingStatus.forEach(entry => Object.keys(entry.skills).forEach(id => currentlyInstalled.add(id)));
+
+    const finalSkills = new Set(selectedSkillIds);
+    const toRemove = [...currentlyInstalled].filter(id => !finalSkills.has(id));
+
+    if (toRemove.length > 0) {
+      console.log(chalk.gray(`\n  Cleaning up ${toRemove.length} removed skills...`));
+      for (const skillId of toRemove) {
+        await uninstallSkill(skillId, selectedAgentIds, installPath, 'project');
+      }
+    }
+  }
+
+  // Install requested skills
   for (const skillId of selectedSkillIds) {
     try {
       await installSkill(skillId, selectedAgentIds, installPath, installScope, { force: !!forceFlag });
@@ -227,7 +297,7 @@ async function installWizard(preselectedSkill, preselectedAgents, customPath, fo
     }
   }
 
-  console.log(chalk.bold.green('\n Installation complete!\n'));
+  console.log(chalk.bold.green('\n Done!\n'));
 }
 
 // --- Command handlers ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ma-agents",
-  "version": "1.7.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"
+    ]
+}