ma-agents 3.4.6 → 3.4.8

package/.opencode/skills/cpp-best-practices/examples/modern-idioms.md

@@ -1,189 +0,0 @@
-# Modern C++ Idioms Examples
-
-## C++17: Structured Bindings and std::optional
-
-```cpp
-#include <map>
-#include <optional>
-#include <string>
-
-// Structured bindings — prefer over .first/.second
-std::map<std::string, int> scores = {{"Alice", 95}, {"Bob", 87}};
-for (const auto& [name, score] : scores) {
-    // name and score are directly named — no .first/.second
-}
-
-// std::optional — no more nullptr sentinels or bool out-parameters
-std::optional<std::string> findUser(int id) {
-    if (id == 42) return "Alice";
-    return std::nullopt; // Not found — explicit, type-safe
-}
-
-void example() {
-    if (const auto user = findUser(42); user.has_value()) {
-        // C++17 if-with-initializer keeps 'user' scoped tightly
-        doSomethingWith(*user);
-    }
-}
-```
-
-## C++17: std::variant for Sum Types
-
-```cpp
-#include <variant>
-#include <string>
-
-struct Success { std::string message; };
-struct NotFound { int id; };
-struct PermissionDenied { std::string reason; };
-
-using LookupResult = std::variant<Success, NotFound, PermissionDenied>;
-
-LookupResult lookup(int id) {
-    if (id == 0) return NotFound{id};
-    if (id < 0) return PermissionDenied{"negative ids reserved"};
-    return Success{"found item " + std::to_string(id)};
-}
-
-void handle(const LookupResult& result) {
-    std::visit([](const auto& v) {
-        using T = std::decay_t<decltype(v)>;
-        if constexpr (std::is_same_v<T, Success>) {
-            log(v.message);
-        } else if constexpr (std::is_same_v<T, NotFound>) {
-            log("not found: " + std::to_string(v.id));
-        } else {
-            log("denied: " + v.reason);
-        }
-    }, result);
-}
-```
-
-## C++20: Concepts
-
-```cpp
-#include <concepts>
-#include <iostream>
-#include <vector>
-
-// Before concepts: SFINAE was required — hard to read and debug
-// After concepts: clear, readable constraints
-
-template<std::integral T>
-T clamp(T value, T lo, T hi) {
-    return std::max(lo, std::min(value, hi));
-}
-
-// Custom concept
-template<typename T>
-concept Printable = requires(T t) {
-    { t.toString() } -> std::convertible_to<std::string>;
-};
-
-template<Printable T>
-void printAll(const std::vector<T>& items) {
-    for (const auto& item : items) {
-        std::cout << item.toString() << '\n';
-    }
-}
-```
-
-## C++20: Ranges
-
-```cpp
-#include <algorithm>
-#include <iostream>
-#include <ranges>
-#include <vector>
-#include <string>
-
-void modernRanges() {
-    std::vector<int> numbers = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};
-
-    // Chain range adaptors — lazy, composable, readable
-    auto evenSquares = numbers
-        | std::views::filter([](int n) { return n % 2 == 0; })
-        | std::views::transform([](int n) { return n * n; });
-
-    // Iterate result without materializing an intermediate container
-    for (int v : evenSquares) {
-        std::cout << v << '\n'; // 4 16 36 64 100
-    }
-
-    // Sorting with ranges — no begin/end iterator boilerplate
-    std::vector<std::string> names = {"Charlie", "Alice", "Bob"};
-    std::ranges::sort(names);
-}
-```
-
-## C++23: std::expected for Error Handling
-
-```cpp
-#include <expected>
-#include <string>
-#include <fstream>
-
-enum class ParseError { InvalidFormat, EmptyInput, Overflow };
-
-// Return expected<T, E> instead of throwing for anticipated failures
-std::expected<int, ParseError> parsePositiveInt(std::string_view input) {
-    if (input.empty()) return std::unexpected(ParseError::EmptyInput);
-    int result = 0;
-    for (char c : input) {
-        if (c < '0' || c > '9') return std::unexpected(ParseError::InvalidFormat);
-        result = result * 10 + (c - '0');
-        if (result < 0) return std::unexpected(ParseError::Overflow);
-    }
-    return result;
-}
-
-void usage() {
-    const auto result = parsePositiveInt("123");
-    if (result) {
-        std::println("Parsed: {}", *result);
-    } else {
-        // Handle error without try/catch — expected path, not exceptional
-        switch (result.error()) {
-            case ParseError::InvalidFormat: std::println("invalid format"); break;
-            case ParseError::EmptyInput:    std::println("empty input");    break;
-            case ParseError::Overflow:      std::println("overflow");       break;
-        }
-    }
-}
-```
-
-## Class Design: Rule of Zero
-
-```cpp
-#include <memory>
-#include <string>
-#include <vector>
-
-// Good: Rule of Zero — all members manage themselves
-class Document {
-public:
-    explicit Document(std::string title) : title_(std::move(title)) {}
-
-    void addSection(std::string content) {
-        sections_.emplace_back(std::move(content));
-    }
-
-private:
-    std::string title_;                    // manages its own lifetime
-    std::vector<std::string> sections_;    // manages its own lifetime
-    // No destructor, no copy/move definitions needed — compiler generates correct ones
-};
-
-// Bad: unnecessary manual resource management
-class BadDocument {
-public:
-    BadDocument(const char* title) {
-        title_ = new char[strlen(title) + 1]; // raw new — avoid this
-        strcpy(title_, title);
-    }
-    ~BadDocument() { delete[] title_; }       // manual cleanup — fragile
-    // Must also define copy ctor, copy assign, move ctor, move assign correctly...
-private:
-    char* title_;
-};
-```

package/.opencode/skills/cpp-best-practices/examples/naming-and-organization.md

@@ -1,102 +0,0 @@
-# Naming and Organization Examples
-
-## Naming Conventions
-
-```cpp
-// File: user_account.h
-#pragma once
-
-#include <string>
-#include <string_view>
-#include <optional>
-
-namespace myapp::domain {
-
-// Types use PascalCase
-class UserAccount {
-public:
-    // Constants use UPPER_SNAKE_CASE
-    static constexpr int MAX_NAME_LENGTH = 128;
-
-    // Constructors and methods use camelCase
-    explicit UserAccount(std::string_view userName, int accountId);
-
-    // Const member function — does not modify the object
-    [[nodiscard]] std::string_view getUserName() const;
-    [[nodiscard]] int getAccountId() const;
-
-    // Mutating method
-    void setUserName(std::string_view newName);
-
-private:
-    // Private members use camelCase with trailing underscore
-    std::string userName_;
-    int accountId_;
-};
-
-} // namespace myapp::domain
-```
-
-## Header Organization
-
-```cpp
-// File: connection_pool.cpp
-
-// 1. Project headers first
-#include "connection_pool.h"
-#include "network/socket.h"
-
-// 2. Third-party headers
-#include <boost/asio.hpp>
-
-// 3. Standard library
-#include <algorithm>
-#include <chrono>
-#include <memory>
-#include <vector>
-
-namespace myapp::network {
-// ...
-} // namespace myapp::network
-```
-
-## Forward Declarations to Reduce Coupling
-
-```cpp
-// File: request_handler.h
-#pragma once
-
-// Forward declare instead of including the full header
-namespace myapp::domain {
-class UserAccount;
-}
-
-namespace myapp::network {
-
-class RequestHandler {
-public:
-    // Only a reference/pointer is needed here — forward declaration is sufficient
-    void handle(const myapp::domain::UserAccount& user);
-};
-
-} // namespace myapp::network
-```
-
-## Namespace Usage
-
-```cpp
-// Good: deeply nested namespace matching directory structure
-namespace myapp::network::http {
-
-class Client {
-    // ...
-};
-
-} // namespace myapp::network::http
-
-// Avoid in headers — pollutes every translation unit that includes this header:
-// using namespace std; // BAD in headers
-
-// OK in .cpp files, restricted to file scope:
-// using namespace myapp::network::http;
-```

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

@@ -1,60 +0,0 @@
----
-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/.opencode/skills/cpp-concurrency-safety/examples/concurrency.md

@@ -1,73 +0,0 @@
-# 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/.opencode/skills/cpp-const-correctness/SKILL.md

@@ -1,63 +0,0 @@
----
-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/.opencode/skills/cpp-const-correctness/examples/const_correctness.md

@@ -1,54 +0,0 @@
-# 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/.opencode/skills/cpp-memory-handling/SKILL.md

@@ -1,42 +0,0 @@
----
-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/.opencode/skills/cpp-memory-handling/examples/modern-cpp.md

@@ -1,49 +0,0 @@
-# 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/.opencode/skills/cpp-memory-handling/examples/smart-pointers.md

@@ -1,46 +0,0 @@
-# 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();
-    }
-}
-```