ma-agents 2.19.2 → 2.20.0

package/.cline/skills/code-documentation/examples/javascript_typescript.md

@@ -0,0 +1,28 @@
+# JavaScript & TypeScript Documentation (JSDoc Style)
+
+### File Header
+```typescript
+/**
+ * @file api-client.ts
+ * @description Centralized HTTP client with automatic retry and error handling.
+ * @author Antigravity / ma-agents
+ * @version 1.2.0
+ */
+```
+
+### Method Documentation
+```typescript
+/**
+ * Fetches data from a specific endpoint with optional caching.
+ * 
+ * @template T The expected type of the response data.
+ * @param {string} url The target URL (must be absolute).
+ * @param {RequestOptions} [options] Optional configuration for headers and timeouts.
+ * @returns {Promise<T>} A promise that resolves to the parsed JSON response.
+ * @throws {NetworkError} If the server is unreachable.
+ * @throws {ValidationError} If the response schema does not match T.
+ */
+async function fetchData<T>(url: string, options?: RequestOptions): Promise<T> {
+  // ...
+}
+```

package/.cline/skills/code-documentation/examples/python.md

@@ -0,0 +1,57 @@
+# Python Documentation (Google/NumPy Style)
+
+### File Header
+Every module should start with a docstring that provides a high-level overview.
+
+```python
+"""
+data_processor.py
+~~~~~~~~~~~~~~~~~
+Handles high-performance transformation of raw sensor data using NumPy.
+
+:copyright: (c) 2026 by Antigravity.
+:license: MIT, see LICENSE for more details.
+"""
+```
+
+### Method Documentation
+Preferred style is Google or NumPy style for readability and integration with tools like Sphinx.
+
+```python
+def calculate_moving_average(data, window_size):
+    """Calculates the moving average of a dataset.
+
+    This method uses a sliding window algorithm to smooth out volatility 
+    in sensor inputs.
+
+    Args:
+        data (list[float]): A list or array of float values to process.
+        window_size (int): The size of the averaging window (must be > 0).
+
+    Returns:
+        float: The calculated moving average.
+
+    Raises:
+        ValueError: If data is empty or window_size is invalid.
+
+    Note:
+        This implementation assumes data is already cleaned.
+    """
+    if not data or window_size <= 0:
+        raise ValueError("Invalid data or window_size")
+    # ... implementation
+```
+
+### Class Documentation
+```python
+class SignalFilter:
+    """A collection of signal processing utilities.
+    
+    Attributes:
+        sampling_rate (int): The frequency at which signals are sampled.
+    """
+    
+    def __init__(self, sampling_rate):
+        """Initializes the SignalFilter with a specific sampling rate."""
+        self.sampling_rate = sampling_rate
+```

package/.cline/skills/code-review/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: Code Review
+description: Performs comprehensive code reviews with best practices
+---
+# Code Review Skill for Cline
+
+## Overview
+Comprehensive code review capability for analyzing code quality, security, and best practices.
+
+## When to Use
+- User requests code review
+- Before merging code changes
+- During development for quality checks
+
+## Review Checklist
+
+### Code Quality
+- [ ] Clear and readable code
+- [ ] Proper naming conventions
+- [ ] Well-organized structure
+- [ ] No obvious bugs
+
+### Best Practices
+- [ ] Follows language conventions
+- [ ] Proper error handling
+- [ ] Performance optimized
+- [ ] No code duplication
+
+### Security
+- [ ] No SQL injection vulnerabilities
+- [ ] No XSS vulnerabilities
+- [ ] Proper input validation
+- [ ] Secure authentication/authorization
+
+### Testing & Docs
+- [ ] Adequate test coverage
+- [ ] Edge cases handled
+- [ ] Well-documented code
+- [ ] Clear comments
+
+## Response Template
+
+```markdown
+## 🔍 Code Review Results
+
+### ✅ Strengths
+[List what's done well]
+
+### ⚠️ Issues
+**[Severity]** [Issue]
+- File: [path:line]
+- Fix: [solution]
+
+### 💡 Recommendations
+[Suggestions for improvement]
+
+### 📈 Score
+[Overall quality rating]
+```

package/.cline/skills/commit-message/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: Commit Message Generator
+description: Generates conventional commit messages from code changes
+---
+# Commit Message Generator
+
+Generate meaningful commit messages following Conventional Commits specification.
+
+## Format
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+## Types
+
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation changes
+- `style`: Code style/formatting
+- `refactor`: Code refactoring
+- `test`: Adding/updating tests
+- `chore`: Maintenance tasks
+- `perf`: Performance improvements
+- `ci`: CI/CD changes
+- `build`: Build system changes
+- `revert`: Revert previous commit
+
+## Guidelines
+
+1. **Subject line** (max 50 chars):
+   - Use imperative mood ("Add" not "Added")
+   - Don't capitalize first letter
+   - No period at the end
+
+2. **Body** (optional):
+   - Explain what and why, not how
+   - Wrap at 72 characters
+
+3. **Footer** (optional):
+   - Breaking changes: `BREAKING CHANGE: description`
+   - Issue references: `Fixes #123`
+
+## Examples
+
+```
+feat(auth): add JWT token refresh mechanism
+
+Implement automatic token refresh to improve user experience
+and reduce re-authentication prompts.
+
+Fixes #456
+```
+
+```
+fix(api): resolve memory leak in user service
+
+The user cache was not being cleared properly, causing
+memory to grow over time.
+```
+
+```
+docs: update installation instructions
+
+Add steps for Windows users and clarify dependency requirements.
+```
+
+## Process
+
+1. Analyze the code changes
+2. Determine the type of change
+3. Identify the scope (component/module affected)
+4. Write clear, concise subject
+5. Add body if changes need explanation
+6. Add footer for breaking changes or issue refs

package/.cline/skills/cpp-concurrency-safety/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: C++ Safety-First Concurrency
+description: Enforce safe multi-threading patterns using RAII locking and task-based parallelism (C++14+).
+---
+# C++ Safety-First Concurrency (Core Guidelines Section CP)
+
+This skill prevents common multi-threading defects like data races, deadlocks, and shared-state corruption.
+
+## Policies
+
+### 1. RAII Locking Only
+*   **Rule**: Never call `mutex.lock()` or `mutex.unlock()` manually.
+*   **Action**: 
+    - Use `std::lock_guard` for single mutexes.
+    - Use `std::unique_lock` if you need deferred locking or condition variables.
+    - Use `std::scoped_lock` (C++17) for multiple mutexes to avoid deadlocks.
+*   **Rationale**: Ensures locks are released even if an exception is thrown.
+
+### 2. Task-Based Parallelism
+*   **Rule**: Prefer tasks (`std::async`, `std::packaged_task`, `std::future`) over raw threads (`std::thread`).
+*   **Action**: Use `auto result = std::async(std::launch::async, func, args...);`
+*   **Rationale**: Automates thread management and handles value return/exception propagation naturally.
+
+### 3. Minimize Shared Mutable State
+*   **Rule**: Data should ideally be either "Thread-Local" or "Read-Only".
+*   **Action**:
+    - Pass data to threads by value where possible.
+    - Use `const` for data shared between threads.
+    - Group mutexes with the data they protect (e.g., in a struct).
+*   **Rationale**: If data isn't shared or isn't mutable, it cannot have a race condition.
+
+### 4. Never Sleep/Wait without a Condition
+*   **Rule**: Avoid `std::this_thread::sleep_for` for synchronization.
+*   **Action**: Use `std::condition_variable` with a predicate to wait for work.
+*   **Rationale**: Sleeping is inefficient and bug-prone; condition variables are precise and responsive.
+
+## Examples
+
+### Before (Dangerous Concurrency)
+```cpp
+std::mutex mtx;
+int sharedData = 0;
+
+void worker() {
+    mtx.lock();
+    sharedData++;
+    mtx.unlock(); // What if an exception happened above?
+}
+```
+
+### After (Safe Concurrency)
+```cpp
+std::mutex mtx;
+int sharedData = 0;
+
+void worker() {
+    std::lock_guard<std::mutex> lock(mtx);
+    sharedData++;
+} // Lock automatically released here
+```

package/.cline/skills/cpp-concurrency-safety/examples/concurrency.md

@@ -0,0 +1,73 @@
+# Concurrency Safety Examples (C++14+)
+
+### 1. Task-Based Parallelism (Async)
+Avoids manual thread joining and handles return values safely.
+
+```cpp
+#include <future>
+#include <vector>
+#include <numeric>
+
+int computeLargeSum(const std::vector<int>& data) {
+    auto part1 = std::async(std::launch::async, [&data]() {
+        return std::accumulate(data.begin(), data.begin() + data.size()/2, 0);
+    });
+    
+    auto part2 = std::accumulate(data.begin() + data.size()/2, data.end(), 0);
+    
+    return part1.get() + part2;
+}
+```
+
+### 2. Multi-Lock Safety (C++17 scoped_lock)
+Prevents deadlocks when acquiring multiple resources.
+
+```cpp
+#include <mutex>
+
+struct Account {
+    std::mutex mtx;
+    double balance;
+};
+
+void transfer(Account& from, Account& to, double amount) {
+    // Acquire both locks simultaneously in a deadlock-free manner
+    std::scoped_lock lock(from.mtx, to.mtx);
+    
+    if (from.balance >= amount) {
+        from.balance -= amount;
+        to.balance += amount;
+    }
+}
+```
+
+### 3. Condition Variables with Predicates
+Always use a predicate to protect against "spurious wakeups."
+
+```cpp
+#include <mutex>
+#include <condition_variable>
+#include <queue>
+
+std::queue<int> workQueue;
+std::mutex workMtx;
+std::condition_variable workCv;
+bool finished = false;
+
+void consumer() {
+    while (true) {
+        std::unique_lock<std::mutex> lock(workMtx);
+        
+        // Wait until there is work OR we are finished
+        workCv.wait(lock, []{ return !workQueue.empty() || finished; });
+        
+        if (workQueue.empty() && finished) break;
+        
+        int task = workQueue.front();
+        workQueue.pop();
+        lock.unlock(); // Release lock before processing
+        
+        process(task);
+    }
+}
+```

package/.cline/skills/cpp-const-correctness/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: C++ Const-Correctness & Logic
+description: Enforce immutability-by-default and push logic to compile-time using constexpr (C++14+).
+---
+# C++ Const-Correctness & Logic (Core Guidelines Section Con & ES)
+
+This skill ensures that C++ code is "immutable by default," reducing side effects and enabling better compiler optimizations.
+
+## Policies
+
+### 1. By Default, Make Objects Immutable
+*   **Rule**: Declare all variables `const` unless they *must* be modified.
+*   **Action**: 
+    - Use `const auto x = ...;` instead of `auto x = ...;`.
+    - Use `const` for function results that won't be modified.
+*   **Rationale**: Prevents accidental state mutation and improves code reasoning.
+
+### 2. Const Member Functions
+*   **Rule**: Any member function that does not modify the object's observable state must be `const`.
+*   **Action**: Append `const` to the function signature: `T getValue() const { ... }`.
+*   **Rationale**: Necessary for calling functions on `const` objects and `const&` parameters.
+
+### 3. Compute at Compile-Time (`constexpr`)
+*   **Rule**: Prefer `constexpr` for any value or simple logic that *can* be computed at compile-time.
+*   **Action**:
+    - Use `constexpr` for constants.
+    - Declare mathematical or configuration functions as `constexpr` (C++14 allows complex logic in `constexpr`).
+*   **Rationale**: Moves work from runtime to compile-time, reducing binary size and execution time.
+
+### 4. Consistent Parameter Logic
+*   **Rule**: Avoid passing by value for large types; avoid passing by non-const reference unless it's an "out" or "in-out" parameter.
+*   **Action**:
+    - **In parameters**: Pass cheap types (int, double, pointers, `string_view`) by value. Pass large types by `const&`.
+    - **Out/In-out parameters**: Pass by `T&`.
+    - **Sinks**: Pass by `T&&` (rvalue reference).
+
+## Examples
+
+### Before (Mutable/Runtime Logic)
+```cpp
+int getMultiplier(int x) {
+    return x * 10;
+}
+
+void process() {
+    auto data = loadData();
+    auto mult = getMultiplier(5); // mutable by accident
+    data.apply(mult);
+}
+```
+
+### After (Const/Compile-time Logic)
+```cpp
+constexpr int getMultiplier(int x) {
+    return x * 10;
+}
+
+void process() {
+    const auto data = loadData(); // data won't change
+    constexpr auto mult = getMultiplier(5); // computed at compile time
+    data.apply(mult);
+}
+```

package/.cline/skills/cpp-const-correctness/examples/const_correctness.md

@@ -0,0 +1,54 @@
+# Const-Correctness Examples (C++14+)
+
+### 1. Complex Const Initialization (Lambda)
+Sometimes you need to conditionally initialize a variable, but you want it to be `const` afterward.
+
+**Modern (C++14):**
+```cpp
+const auto path = []() {
+    if (auto env = std::getenv("APP_PATH")) {
+        return std::string(env);
+    }
+    return std::string("/default/path");
+}(); // Immediately invoked lambda
+```
+
+### 2. Const-Correct Member Functions
+Ensure getters and inspectors are `const`.
+
+```cpp
+class Config {
+    int timeout = 30;
+public:
+    // This is an inspector, must be const
+    int getTimeout() const { return timeout; }
+    
+    // This is a mutator, cannot be const
+    void setTimeout(int t) { timeout = t; }
+};
+```
+
+### 3. C++14 constexpr Logic
+C++14 expanded `constexpr` significantly (loops, branches allowed).
+
+```cpp
+constexpr int fibonacci(int n) {
+    if (n <= 1) return n;
+    int a = 0, b = 1;
+    for (int i = 2; i <= n; ++i) {
+        int next = a + b;
+        a = b;
+        b = next;
+    }
+    return b;
+}
+
+// Result is computed by the compiler
+constexpr int fib10 = fibonacci(10);
+```
+
+### 4. Parameter Passing Guide
+- `void f(int)` : Fast to copy (Value)
+- `void f(const LargeObject&)` : Expensive to copy (Const Ref)
+- `void f(LargeObject&)` : I will modify this (Ref)
+- `void f(LargeObject&&)` : I will MOVE/OWN this (Rvalue Ref)

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

@@ -0,0 +1,42 @@
+---
+name: C++ Safe Memory Handling
+description: Enforces Modern C++ practices (RAII, Smart Pointers) to prevent memory leaks, dangling pointers, and buffer overflows.
+---
+# 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/.cline/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/.cline/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/.cline/skills/cpp-modern-composition/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: C++ Modern Composition
+description: Replace legacy C patterns with STL, Ranges, and modern C++ abstractions (C++14+).
+---
+# C++ Modern Composition (Core Guidelines Section STL, CPL, ES)
+
+This skill forces the transition from legacy "C-style" C++ to modern, declarative, and safer C++ idioms.
+
+## Policies
+
+### 1. STL Algorithms over Manual Loops
+*   **Rule**: Never write a raw `for` or `while` loop for operations supported by `<algorithm>` or `<numeric>`.
+*   **Action**: 
+    - Use `std::any_of`, `std::all_of`, `std::find_if`, `std::transform`, `std::accumulate`.
+    - In C++20 projects, prefer `std::ranges` versions.
+*   **Rationale**: Reduces "off-by-one" errors and improves intent readability.
+
+### 2. Eradicate C-style Casts and Macros
+*   **Rule**: Ban `(type)value` and `#define` for logic/constants.
+*   **Action**:
+    - Use `static_cast`, `reinterpret_cast`, or `const_cast`.
+    - Replace macros with `constexpr` variables or `inline` functions/templates.
+*   **Rationale**: Named casts are searchable and safer; `constexpr` respects namespaces and scopes.
+
+### 3. Universal Initialization
+*   **Rule**: Prefer `{}` initialization to avoid the "Most Vexing Parse".
+*   **Action**: Use `auto x = Type{args...};` or `Type x{args...};`.
+*   **Rationale**: Prevents narrowing conversions (e.g., `int x{3.5}` is a compiler error, while `int x = 3.5` is not).
+
+### 4. Zero Raw Memory Manipulation
+*   **Rule**: Ban `memset`, `memcpy`, and `malloc`.
+*   **Action**:
+    - Use `std::fill`, `std::copy`, or `container.assign()`.
+    - Use `std::vector` or `std::array` instead of raw arrays.
+*   **Rationale**: Standard containers are bounds-checked (via `.at()`) and manage their own memory.
+
+## Examples
+
+### Before (C-style C++)
+```cpp
+#define MAX_BUFFER 1024
+int arr[MAX_BUFFER];
+memset(arr, 0, sizeof(arr));
+
+bool found = false;
+for (int i = 0; i < MAX_BUFFER; ++i) {
+    if (arr[i] == (int)someFloat) {
+        found = true;
+        break;
+    }
+}
+```
+
+### After (Modern C++)
+```cpp
+constexpr size_t MaxBuffer = 1024;
+std::array<int, MaxBuffer> arr;
+arr.fill(0);
+
+auto target = static_cast<int>(someFloat);
+bool found = std::any_of(arr.begin(), arr.end(), [target](int v) {
+    return v == target;
+});
+```