agentic-team-templates 0.13.2 → 0.14.0

package/templates/cpp-expert/.cursorrules/memory-and-ownership.md

@@ -0,0 +1,220 @@
+# Memory and Ownership
+
+RAII is the foundation. Smart pointers express ownership. Raw pointers mean "non-owning."
+
+## RAII (Resource Acquisition Is Initialization)
+
+```cpp
+// The single most important C++ idiom
+// Resource lifetime = object lifetime
+class DatabaseConnection {
+    sqlite3* db_ = nullptr;
+
+public:
+    explicit DatabaseConnection(const std::string& path) {
+        if (sqlite3_open(path.c_str(), &db_) != SQLITE_OK) {
+            throw std::runtime_error("Failed to open database");
+        }
+    }
+
+    ~DatabaseConnection() {
+        if (db_) sqlite3_close(db_);
+    }
+
+    // Non-copyable, movable
+    DatabaseConnection(const DatabaseConnection&) = delete;
+    DatabaseConnection& operator=(const DatabaseConnection&) = delete;
+    DatabaseConnection(DatabaseConnection&& other) noexcept
+        : db_{std::exchange(other.db_, nullptr)} {}
+    DatabaseConnection& operator=(DatabaseConnection&& other) noexcept {
+        if (this != &other) {
+            if (db_) sqlite3_close(db_);
+            db_ = std::exchange(other.db_, nullptr);
+        }
+        return *this;
+    }
+};
+// No cleanup code needed at call sites — ever
+```
+
+## Smart Pointers
+
+### std::unique_ptr — Single Ownership
+
+```cpp
+// The default smart pointer. Zero overhead over raw pointer.
+auto widget = std::make_unique<Widget>(42);
+
+// Transfer ownership explicitly
+auto new_owner = std::move(widget);
+// widget is now nullptr — ownership transferred
+
+// Custom deleters for C APIs
+auto file = std::unique_ptr<FILE, decltype(&fclose)>(
+    fopen("data.txt", "r"), &fclose);
+
+// Factory functions return unique_ptr
+auto create_engine(const Config& cfg) -> std::unique_ptr<Engine> {
+    return std::make_unique<ConcreteEngine>(cfg);
+}
+```
+
+### std::shared_ptr — Shared Ownership
+
+```cpp
+// Use only when ownership is genuinely shared (rare)
+auto shared = std::make_shared<Resource>();
+auto also_owns = shared; // Reference count incremented
+
+// Weak references to break cycles
+class Node {
+    std::vector<std::shared_ptr<Node>> children_;
+    std::weak_ptr<Node> parent_; // Doesn't prevent destruction
+
+public:
+    auto parent() const -> std::shared_ptr<Node> {
+        return parent_.lock(); // Returns nullptr if parent destroyed
+    }
+};
+
+// Rules:
+// - Prefer unique_ptr. Only use shared_ptr when multiple owners exist.
+// - Use make_shared (single allocation for control block + object)
+// - Never create shared_ptr from raw pointer if one already exists
+// - Use weak_ptr to observe without owning
+```
+
+### Raw Pointers — Non-Owning References
+
+```cpp
+// Raw pointer = "I'm borrowing this, I don't own it"
+void process(const Widget* widget) {
+    if (!widget) return;
+    widget->do_work();
+    // Do NOT delete widget — you don't own it
+}
+
+// Prefer references over pointers when null is not valid
+void process(const Widget& widget) {
+    widget.do_work();
+}
+```
+
+## std::span — Non-Owning View (C++20)
+
+```cpp
+// View into contiguous memory — no ownership, no copies
+void process(std::span<const int> data) {
+    for (auto val : data) {
+        // Works with vector, array, C array, etc.
+    }
+}
+
+std::vector<int> vec = {1, 2, 3, 4, 5};
+process(vec);                    // Implicit conversion
+process({vec.data() + 1, 3});  // Subspan
+int arr[] = {1, 2, 3};
+process(arr);                    // C arrays too
+```
+
+## Move Semantics
+
+```cpp
+class Buffer {
+    std::unique_ptr<uint8_t[]> data_;
+    size_t size_ = 0;
+
+public:
+    // Move constructor — steal resources
+    Buffer(Buffer&& other) noexcept
+        : data_{std::move(other.data_)}
+        , size_{std::exchange(other.size_, 0)} {}
+
+    // Move assignment
+    Buffer& operator=(Buffer&& other) noexcept {
+        data_ = std::move(other.data_);
+        size_ = std::exchange(other.size_, 0);
+        return *this;
+    }
+
+    // Rule of Five: if you define one, define all five
+    Buffer(const Buffer& other);              // Copy constructor
+    Buffer& operator=(const Buffer& other);   // Copy assignment
+    ~Buffer() = default;                      // Destructor
+};
+
+// Move from function return — no cost
+auto create_buffer(size_t size) -> Buffer {
+    Buffer buf(size);
+    // ... fill buffer ...
+    return buf; // NRVO or move — never copies
+}
+```
+
+## The Rule of Zero/Five
+
+```cpp
+// Rule of Zero: prefer classes that need no custom special members
+class UserService {
+    std::unique_ptr<UserRepository> repo_;  // Handles its own cleanup
+    std::string name_;                       // Handles its own cleanup
+
+    // No destructor, no copy/move constructors needed — compiler generates correct ones
+};
+
+// Rule of Five: if you need one, you need all five
+// (destructor, copy ctor, copy assignment, move ctor, move assignment)
+
+// Rule of Three (legacy): if you need destructor, you need copy ctor + copy assignment
+```
+
+## Memory Safety Checklist
+
+```cpp
+// 1. No owning raw pointers
+Widget* w = new Widget(); // BUG: who deletes this?
+
+// 2. No manual memory management
+auto w = std::make_unique<Widget>(); // Correct
+
+// 3. No dangling references
+const std::string& get_name() {
+    std::string name = "Alice";
+    return name; // BUG: dangling reference to local
+}
+
+// 4. No use-after-move
+auto buf = create_buffer(1024);
+consume(std::move(buf));
+buf.size(); // BUG: use after move
+
+// 5. No out-of-bounds access
+vec[vec.size()]; // BUG: one past the end
+vec.at(i);       // Bounds-checked alternative
+```
+
+## Anti-Patterns
+
+```cpp
+// Never: new without corresponding smart pointer
+auto* p = new Widget(42);
+// Use: auto p = std::make_unique<Widget>(42);
+
+// Never: manual delete
+delete p;
+delete[] arr;
+// Use: RAII, smart pointers, containers
+
+// Never: owning raw pointers in classes
+class Bad {
+    Widget* widget_; // Who owns this? When is it freed?
+};
+
+// Never: returning raw owning pointers
+Widget* create_widget(); // Caller must remember to delete
+// Use: std::unique_ptr<Widget> create_widget();
+
+// Never: C-style memory management
+malloc/free/realloc
+// Use: containers, smart pointers, std::vector
+```

package/templates/cpp-expert/.cursorrules/modern-cpp.md

@@ -0,0 +1,211 @@
+# Modern C++ Language Features
+
+C++17/20/23 features used deliberately. Every feature exists for safety, clarity, or performance.
+
+## Core Type System
+
+### auto and Type Deduction
+
+```cpp
+// Good: auto when the type is obvious from context
+auto name = std::string{"Alice"};
+auto count = static_cast<size_t>(items.size());
+auto it = container.find(key);
+auto ptr = std::make_unique<Widget>(42);
+
+// Good: trailing return types for complex deductions
+template <typename T, typename U>
+auto add(T a, U b) -> decltype(a + b) {
+    return a + b;
+}
+
+// Bad: auto when it obscures the type
+auto result = process(data); // What is result? Reader must look up process()
+// Prefer explicit type when clarity matters
+ProcessResult result = process(data);
+```
+
+### std::optional
+
+```cpp
+// Return type for "might not exist"
+std::optional<User> find_user(std::string_view email) {
+    auto it = users_.find(std::string{email});
+    if (it == users_.end()) return std::nullopt;
+    return it->second;
+}
+
+// Usage
+if (auto user = find_user(email); user.has_value()) {
+    process(*user);
+}
+
+// Or with value_or
+auto name = find_user(email)
+    .transform([](const User& u) { return u.name(); })
+    .value_or("Unknown");
+```
+
+### std::variant
+
+```cpp
+// Type-safe union — the C++ discriminated union
+using JsonValue = std::variant<
+    std::nullptr_t,
+    bool,
+    double,
+    std::string,
+    std::vector<JsonValue>,
+    std::map<std::string, JsonValue>>;
+
+// Visit with overloaded lambdas
+auto to_string(const JsonValue& value) -> std::string {
+    return std::visit(overloaded{
+        [](std::nullptr_t) { return std::string{"null"}; },
+        [](bool b) { return b ? std::string{"true"} : std::string{"false"}; },
+        [](double d) { return std::to_string(d); },
+        [](const std::string& s) { return "\"" + s + "\""; },
+        [](const auto&) { return std::string{"[complex]"}; }
+    }, value);
+}
+
+// The overloaded helper
+template<class... Ts>
+struct overloaded : Ts... { using Ts::operator()...; };
+template<class... Ts>
+overloaded(Ts...) -> overloaded<Ts...>;
+```
+
+### std::expected (C++23)
+
+```cpp
+// Result type — like Rust's Result
+enum class ParseError { empty_input, invalid_format, out_of_range };
+
+auto parse_port(std::string_view input) -> std::expected<uint16_t, ParseError> {
+    if (input.empty()) return std::unexpected{ParseError::empty_input};
+
+    int value = 0;
+    auto [ptr, ec] = std::from_chars(input.data(), input.data() + input.size(), value);
+
+    if (ec != std::errc{}) return std::unexpected{ParseError::invalid_format};
+    if (value < 1 || value > 65535) return std::unexpected{ParseError::out_of_range};
+
+    return static_cast<uint16_t>(value);
+}
+
+// Monadic operations
+auto result = parse_port(input)
+    .transform([](uint16_t port) { return Endpoint{"localhost", port}; })
+    .or_else([](ParseError e) -> std::expected<Endpoint, ParseError> {
+        return Endpoint{"localhost", 8080}; // Default
+    });
+```
+
+## Concepts (C++20)
+
+```cpp
+// Constrain templates at the interface, not in error messages
+template <typename T>
+concept Numeric = std::integral<T> || std::floating_point<T>;
+
+template <typename T>
+concept Serializable = requires(T t, std::ostream& os) {
+    { os << t } -> std::same_as<std::ostream&>;
+    { t.serialize() } -> std::convertible_to<std::string>;
+};
+
+// Clean constrained templates
+template <Numeric T>
+auto clamp(T value, T low, T high) -> T {
+    return std::max(low, std::min(value, high));
+}
+
+// Requires clause for complex constraints
+template <typename Container>
+    requires std::ranges::range<Container> &&
+             std::totally_ordered<std::ranges::range_value_t<Container>>
+auto find_median(Container& c) {
+    std::ranges::sort(c);
+    return c[c.size() / 2];
+}
+```
+
+## Ranges (C++20/23)
+
+```cpp
+#include <ranges>
+
+// Composable, lazy transformations
+auto active_user_emails = users
+    | std::views::filter([](const User& u) { return u.is_active(); })
+    | std::views::transform([](const User& u) { return u.email(); })
+    | std::views::take(100);
+
+// Collect into a container
+auto result = active_user_emails | std::ranges::to<std::vector>();
+
+// Algorithm with projection
+std::ranges::sort(users, {}, &User::name); // Sort by name
+auto it = std::ranges::find(users, target_id, &User::id); // Find by id
+```
+
+## Structured Bindings
+
+```cpp
+// Decompose aggregates
+auto [key, value] = *map.find(target);
+auto [x, y, z] = get_position();
+
+// With if-init
+if (auto [it, inserted] = map.try_emplace(key, value); !inserted) {
+    log::warn("Key {} already exists", key);
+}
+
+// Iterate maps cleanly
+for (const auto& [name, score] : scores) {
+    fmt::print("{}: {}\n", name, score);
+}
+```
+
+## String Handling
+
+```cpp
+// std::string_view for non-owning references (C++17)
+void process(std::string_view input) {
+    // Zero-copy substring
+    auto prefix = input.substr(0, 5);
+}
+
+// std::format (C++20)
+auto msg = std::format("User {} logged in from {}", user.name(), ip_address);
+
+// fmt library (pre-C++20 or for extra features)
+fmt::print("Processing {} items\n", count);
+
+// Never: manual snprintf or string concatenation in loops
+```
+
+## Anti-Patterns
+
+```cpp
+// Never: raw new/delete
+auto* widget = new Widget(42);
+delete widget;
+// Use: auto widget = std::make_unique<Widget>(42);
+
+// Never: C-style casts
+int x = (int)some_double;
+// Use: static_cast<int>(some_double)
+
+// Never: NULL or 0 for null pointers
+if (ptr == NULL)
+// Use: if (ptr == nullptr)
+
+// Never: C arrays in interfaces
+void process(int* data, size_t len);
+// Use: void process(std::span<const int> data);
+
+// Never: using namespace std; in headers
+// Pollutes every translation unit that includes the header
+```

package/templates/cpp-expert/.cursorrules/overview.md

@@ -0,0 +1,87 @@
+# C++ Expert Overview
+
+Principal-level C++ engineering. Deep language mastery, zero-cost abstractions, and systems-level thinking.
+
+## Scope
+
+This guide applies to:
+- Systems programming (OS, drivers, embedded)
+- High-performance computing and real-time systems
+- Game engines and graphics programming
+- Networking and server infrastructure
+- Libraries and frameworks
+- Scientific computing and simulation
+
+## Core Philosophy
+
+C++ gives you control. That control comes with responsibility. Write code that is correct, clear, and fast — in that order.
+
+- **Resource management is automatic.** RAII is not optional — every resource has an owner, every owner has a destructor.
+- **Zero-cost abstractions are the goal.** If an abstraction adds runtime overhead you don't need, you're using the wrong abstraction.
+- **The type system is your strongest tool.** Use it to make invalid states unrepresentable at compile time.
+- **Undefined behavior is a bug, period.** No shortcuts. No "it works on my machine." UB is the enemy.
+- **Modern C++ is the baseline.** C++17 minimum, C++20/23 features where they improve clarity.
+- **If you don't know, say so.** Admitting uncertainty about compiler behavior, ABI details, or standard wording is professional.
+
+## Key Principles
+
+1. **RAII Everywhere** — Every resource acquisition is an initialization, every release is a destruction
+2. **Value Semantics by Default** — Copy, move, compare. References and pointers are the exception
+3. **const Correctness** — If it doesn't mutate, it's `const`. No exceptions
+4. **Prefer the Standard Library** — `std::vector`, `std::string`, `std::optional`, `std::variant` before rolling your own
+5. **Compile-Time Over Runtime** — `constexpr`, `static_assert`, `concepts` — catch bugs before the program runs
+
+## Project Structure
+
+```
+project/
+├── include/mylib/            # Public headers
+│   ├── mylib.hpp             # Main include
+│   ├── types.hpp
+│   └── utils.hpp
+├── src/                      # Implementation files
+│   ├── main.cpp
+│   ├── types.cpp
+│   └── utils.cpp
+├── tests/                    # Test files
+│   ├── test_types.cpp
+│   └── test_utils.cpp
+├── benchmarks/               # Performance benchmarks
+├── third_party/              # Vendored dependencies
+├── cmake/                    # CMake modules
+│   └── CompilerWarnings.cmake
+├── CMakeLists.txt
+├── CMakePresets.json
+├── .clang-format
+├── .clang-tidy
+└── conanfile.txt or vcpkg.json
+```
+
+## Compiler Warnings
+
+```cmake
+# Treat warnings as errors — non-negotiable
+target_compile_options(${PROJECT_NAME} PRIVATE
+    $<$<CXX_COMPILER_ID:MSVC>:/W4 /WX /permissive->
+    $<$<NOT:$<CXX_COMPILER_ID:MSVC>>:-Wall -Wextra -Wpedantic -Werror
+        -Wshadow -Wconversion -Wsign-conversion -Wnon-virtual-dtor
+        -Wold-style-cast -Wcast-align -Wunused -Woverloaded-virtual
+        -Wnull-dereference -Wdouble-promotion -Wformat=2>
+)
+```
+
+## Definition of Done
+
+A C++ feature is complete when:
+
+- [ ] Compiles with zero warnings under `-Wall -Wextra -Wpedantic -Werror`
+- [ ] All tests pass (unit, integration)
+- [ ] Sanitizers pass (ASan, UBSan, TSan)
+- [ ] `clang-tidy` reports zero findings
+- [ ] No undefined behavior (verified with sanitizers)
+- [ ] No memory leaks (verified with ASan or Valgrind)
+- [ ] `const` correctness enforced
+- [ ] RAII used for all resource management
+- [ ] No raw `new`/`delete` in application code
+- [ ] Exception safety guarantees documented
+- [ ] Code reviewed and approved