ma-agents 2.20.2 → 2.21.0

package/.opencode/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;
+});
+```

package/.opencode/skills/cpp-modern-composition/examples/composition.md

@@ -0,0 +1,51 @@
+# Modern Composition Examples (C++14+)
+
+### 1. Data Transformation (Transform)
+**Legacy:**
+```cpp
+std::vector<int> inputs = {1, 2, 3};
+std::vector<int> outputs;
+for (size_t i = 0; i < inputs.size(); ++i) {
+    outputs.push_back(inputs[i] * 2);
+}
+```
+
+**Modern (C++14):**
+```cpp
+std::vector<int> inputs = {1, 2, 3};
+std::vector<int> outputs;
+outputs.reserve(inputs.size());
+std::transform(inputs.begin(), inputs.end(), std::back_inserter(outputs), 
+               [](int n) { return n * 2; });
+```
+
+### 2. Summation and Reduction (Accumulate)
+**Modern (C++14):**
+```cpp
+#include <numeric>
+
+std::vector<double> prices = {10.5, 20.0, 5.25};
+double total = std::accumulate(prices.begin(), prices.end(), 0.0);
+```
+
+### 3. Safe Narrowing Protection
+**Logic:**
+```cpp
+double d = 7.9;
+// int i{d}; // Error: narrowing conversion from 'double' to 'int'
+int i = static_cast<int>(d); // Explicit and safe
+```
+
+### 4. Replacing Function Macros
+**Legacy:**
+```cpp
+#define SQUARE(x) ((x)*(x))
+```
+
+**Modern (C++14):**
+```cpp
+template<typename T>
+constexpr T square(T t) {
+    return t * t;
+}
+```

package/.opencode/skills/cpp-robust-interfaces/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: C++ Robust Interfaces
+description: Enforce contract-based design and strong typing in C++ interfaces (C++14+).
+---
+# C++ Robust Interfaces (Core Guidelines Section I & E)
+
+This skill ensures that C++ interfaces follow contract-based design principles to improve safety, clarity, and maintainability.
+
+## Policies
+
+### 1. Make Interfaces Explicit
+*   **Rule**: Functions must explicitly state their requirements (pre-conditions) and guarantees (post-conditions).
+*   **Action**: Use `Expects()` and `Ensures()` (from GSL) or standardized comments if GSL is unavailable.
+*   **Rationale**: Detects integration bugs at the call site rather than deep in the implementation.
+
+### 2. Strong Typing over Primitive Types
+*   **Rule**: Avoid "Boolean Blindness" and `void*`.
+*   **Action**: 
+    - Use `enum class` for options instead of `bool`.
+    - Use `std::chrono` for time instead of `int`.
+    - Use specific types/structs instead of a long list of primitive arguments.
+
+### 3. Clear Ownership and Lifetime
+*   **Rule**: A raw pointer (`T*`) in an interface **must never** represent ownership.
+*   **Action**: 
+    - Use `gsl::not_null<T*>` for pointers that cannot be null.
+    - Use `std::unique_ptr` or `std::shared_ptr` ONLY if the function is participating in ownership/lifetime management.
+    - Prefer `T&` for arguments that must exist and aren't owned by the callee.
+
+### 4. Sequence Safety
+*   **Rule**: Never pass an array as a raw pointer + size.
+*   **Action**:
+    - Use `gsl::span<T>` (C++14/17 via GSL) or `std::span<T>` (C++20).
+    - Use `std::string_view` for read-only strings.
+
+## Examples
+
+### Before (Fragile Interface)
+```cpp
+// What does 'flag' mean? Is data allowed to be null? Is it an array?
+void processData(char* data, int size, bool flag);
+```
+
+### After (Robust Interface)
+```cpp
+#include <gsl/gsl>
+
+enum class ProcessingMode { Fast, Thorough };
+
+// Explicit contract: data must not be null, size is handled by span
+void processData(gsl::span<const char> data, ProcessingMode mode) {
+    Expects(!data.empty());
+    // ...
+}
+```

package/.opencode/skills/cpp-robust-interfaces/examples/interfaces.md

@@ -0,0 +1,56 @@
+# Robust Interface Examples (C++14+)
+
+### 1. Avoiding Boolean Blindness
+**Incorrect:**
+```cpp
+void setWindowVisible(bool visible, bool animate);
+// Call site: setWindowVisible(true, false); // What is false?
+```
+
+**Correct (C++14):**
+```cpp
+enum class Visibility { Visible, Hidden };
+enum class Animation { Enabled, Disabled };
+
+void setWindowVisible(Visibility v, Animation a);
+// Call site: setWindowVisible(Visibility::Visible, Animation::Disabled);
+```
+
+### 2. Contract-Based Validation
+Using GSL (Guidelines Support Library) style:
+
+```cpp
+#include <gsl/gsl>
+
+class User {
+public:
+    // Ensure name is never null or empty
+    void setName(gsl::not_null<const char*> name) {
+        Expects(std::strlen(name) > 0);
+        this->name = name;
+    }
+private:
+    std::string name;
+};
+```
+
+### 3. Safe Sequences with Span
+Replaces pointer + length pairs which are prone to buffer overflows.
+
+```cpp
+#include <gsl/gsl> // Use gsl::span in C++14
+
+float calculateAverage(gsl::span<const float> values) {
+    Expects(!values.empty());
+    
+    float sum = 0.0f;
+    for (float v : values) {
+        sum += v;
+    }
+    return sum / values.size();
+}
+
+// Usage:
+// float arr[] = {1, 2, 3};
+// calculateAverage(arr); // Automatic conversion to span
+```