agentic-team-templates 0.13.2 → 0.14.0

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

@@ -0,0 +1,312 @@
+# C++ Tooling and Build System
+
+CMake is the standard. Sanitizers are mandatory. Static analysis catches bugs before they ship.
+
+## CMake
+
+### Modern CMake (Target-Based)
+
+```cmake
+cmake_minimum_required(VERSION 3.25)
+project(myapp VERSION 1.0.0 LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+
+# Main library
+add_library(mylib
+    src/types.cpp
+    src/utils.cpp
+)
+target_include_directories(mylib PUBLIC
+    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+    $<INSTALL_INTERFACE:include>
+)
+
+# Executable
+add_executable(myapp src/main.cpp)
+target_link_libraries(myapp PRIVATE mylib)
+
+# Tests
+option(BUILD_TESTING "Build tests" ON)
+if(BUILD_TESTING)
+    enable_testing()
+    add_subdirectory(tests)
+endif()
+```
+
+### CMake Presets
+
+```json
+{
+    "version": 6,
+    "configurePresets": [
+        {
+            "name": "dev",
+            "generator": "Ninja",
+            "binaryDir": "${sourceDir}/build/dev",
+            "cacheVariables": {
+                "CMAKE_BUILD_TYPE": "Debug",
+                "CMAKE_EXPORT_COMPILE_COMMANDS": "ON",
+                "ENABLE_SANITIZERS": "ON"
+            }
+        },
+        {
+            "name": "release",
+            "generator": "Ninja",
+            "binaryDir": "${sourceDir}/build/release",
+            "cacheVariables": {
+                "CMAKE_BUILD_TYPE": "Release",
+                "CMAKE_INTERPROCEDURAL_OPTIMIZATION": "ON"
+            }
+        }
+    ],
+    "buildPresets": [
+        { "name": "dev", "configurePreset": "dev" },
+        { "name": "release", "configurePreset": "release" }
+    ],
+    "testPresets": [
+        { "name": "dev", "configurePreset": "dev", "output": { "outputOnFailure": true } }
+    ]
+}
+```
+
+### Essential Commands
+
+```bash
+# Configure and build
+cmake --preset dev
+cmake --build --preset dev
+
+# Run tests
+ctest --preset dev
+
+# Clean build
+cmake --build --preset dev --target clean
+
+# Install
+cmake --install build/release --prefix /usr/local
+```
+
+## Package Management
+
+### vcpkg
+
+```json
+{
+    "dependencies": [
+        "fmt",
+        "spdlog",
+        "catch2",
+        "benchmark",
+        "nlohmann-json"
+    ]
+}
+```
+
+```cmake
+# CMakeLists.txt
+find_package(fmt CONFIG REQUIRED)
+find_package(spdlog CONFIG REQUIRED)
+target_link_libraries(myapp PRIVATE fmt::fmt spdlog::spdlog)
+```
+
+### Conan
+
+```ini
+# conanfile.txt
+[requires]
+fmt/10.2.1
+spdlog/1.13.0
+catch2/3.5.2
+
+[generators]
+CMakeDeps
+CMakeToolchain
+```
+
+## .clang-format
+
+```yaml
+BasedOnStyle: Google
+IndentWidth: 4
+ColumnLimit: 100
+PointerAlignment: Left
+AllowShortFunctionsOnASingleLine: Inline
+AllowShortIfStatementsOnASingleLine: Never
+AllowShortLoopsOnASingleLine: false
+BreakBeforeBraces: Attach
+IncludeBlocks: Regroup
+SortIncludes: CaseSensitive
+SpaceAfterCStyleCast: false
+```
+
+```bash
+# Format all files
+find src include tests -name '*.cpp' -o -name '*.hpp' | xargs clang-format -i
+
+# CI check
+find src include tests -name '*.cpp' -o -name '*.hpp' | xargs clang-format --dry-run --Werror
+```
+
+## .clang-tidy
+
+```yaml
+Checks: >
+    -*,
+    bugprone-*,
+    clang-analyzer-*,
+    cppcoreguidelines-*,
+    misc-*,
+    modernize-*,
+    performance-*,
+    readability-*,
+    -modernize-use-trailing-return-type,
+    -readability-identifier-length
+
+WarningsAsErrors: '*'
+
+CheckOptions:
+    - key: readability-identifier-naming.ClassCase
+      value: CamelCase
+    - key: readability-identifier-naming.FunctionCase
+      value: lower_case
+    - key: readability-identifier-naming.VariableCase
+      value: lower_case
+    - key: readability-identifier-naming.PrivateMemberSuffix
+      value: '_'
+```
+
+```bash
+# Run clang-tidy
+clang-tidy -p build/dev src/*.cpp -- -std=c++20
+
+# With CMake integration
+set(CMAKE_CXX_CLANG_TIDY "clang-tidy")
+```
+
+## Docker
+
+```dockerfile
+FROM ubuntu:24.04 AS build
+RUN apt-get update && apt-get install -y \
+    cmake ninja-build g++-14 \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+COPY CMakeLists.txt CMakePresets.json vcpkg.json ./
+COPY include/ include/
+COPY src/ src/
+
+RUN cmake --preset release && cmake --build --preset release
+
+FROM ubuntu:24.04 AS runtime
+RUN useradd -m appuser
+USER appuser
+COPY --from=build /app/build/release/myapp /usr/local/bin/
+ENTRYPOINT ["myapp"]
+```
+
+## CI/CD (GitHub Actions)
+
+```yaml
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build-and-test:
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+        compiler: [gcc-14, clang-18]
+
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y ninja-build ${{ matrix.compiler }}
+
+      - name: Configure
+        run: cmake --preset dev
+        env:
+          CXX: ${{ matrix.compiler == 'gcc-14' && 'g++-14' || 'clang++-18' }}
+
+      - name: Build
+        run: cmake --build --preset dev
+
+      - name: Test
+        run: ctest --preset dev
+
+      - name: clang-format check
+        run: |
+          find src include tests -name '*.cpp' -o -name '*.hpp' | \
+            xargs clang-format --dry-run --Werror
+
+      - name: clang-tidy
+        run: |
+          clang-tidy -p build/dev src/*.cpp -- -std=c++20
+
+  sanitizers:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        sanitizer: [address, thread]
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build with sanitizer
+        run: |
+          cmake -B build -DCMAKE_BUILD_TYPE=Debug \
+            -DCMAKE_CXX_FLAGS="-fsanitize=${{ matrix.sanitizer }} -fno-omit-frame-pointer"
+          cmake --build build
+      - name: Test with sanitizer
+        run: ctest --test-dir build --output-on-failure
+```
+
+## Logging (spdlog)
+
+```cpp
+#include <spdlog/spdlog.h>
+#include <spdlog/sinks/stdout_color_sinks.h>
+#include <spdlog/sinks/rotating_file_sink.h>
+
+auto logger = spdlog::stdout_color_mt("app");
+logger->set_level(spdlog::level::info);
+
+logger->info("Server starting on port {}", port);
+logger->warn("Connection pool at {}% capacity", utilization);
+logger->error("Failed to process order {}: {}", order_id, ec.message());
+
+// Structured logging with fmt
+spdlog::info("request method={} path={} status={} duration_ms={}",
+    method, path, status, duration.count());
+```
+
+## Anti-Patterns
+
+```cpp
+// Never: hand-written Makefiles for complex projects
+// Use CMake with presets
+
+// Never: header-only for everything (compile time explosion)
+// Use compilation units, forward declarations, and pimpl
+
+// Never: skipping sanitizers in CI
+// ASan + UBSan + TSan catch real bugs that tests miss
+
+// Never: -Wno-* to suppress warnings without fixing
+// Fix the code, don't silence the compiler
+
+// Never: system-installed dependencies without version pinning
+// Use vcpkg, Conan, or FetchContent with pinned versions
+```

package/templates/cpp-expert/CLAUDE.md

@@ -0,0 +1,242 @@
+# C++ Expert Development Guide
+
+Principal-level guidelines for C++ engineering. Deep language mastery, zero-cost abstractions, and systems-level thinking.
+
+---
+
+## Overview
+
+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."
+- **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`
+5. **Compile-Time Over Runtime** — `constexpr`, `static_assert`, `concepts`
+
+### Project Structure
+
+```
+project/
+├── include/mylib/            # Public headers
+├── src/                      # Implementation files
+├── tests/                    # Test files
+├── benchmarks/               # Performance benchmarks
+├── cmake/                    # CMake modules
+├── CMakeLists.txt
+├── CMakePresets.json
+├── .clang-format
+├── .clang-tidy
+└── vcpkg.json or conanfile.txt
+```
+
+---
+
+## Modern C++
+
+### std::optional, std::variant, std::expected
+
+```cpp
+std::optional<User> find_user(std::string_view email);
+
+using JsonValue = std::variant<std::nullptr_t, bool, double, std::string>;
+
+auto parse_port(std::string_view input) -> std::expected<uint16_t, ParseError>;
+```
+
+### Concepts (C++20)
+
+```cpp
+template <typename T>
+concept Numeric = std::integral<T> || std::floating_point<T>;
+
+template <Numeric T>
+auto clamp(T value, T low, T high) -> T;
+```
+
+### Ranges (C++20)
+
+```cpp
+auto result = users
+    | std::views::filter(&User::is_active)
+    | std::views::transform(&User::email)
+    | std::ranges::to<std::vector>();
+```
+
+---
+
+## Memory and Ownership
+
+### Smart Pointers
+
+- `std::unique_ptr` — Single ownership (default choice, zero overhead)
+- `std::shared_ptr` — Shared ownership (rare, atomic ref count overhead)
+- Raw pointer — Non-owning reference only
+
+### Rules
+
+- No raw `new`/`delete` in application code
+- RAII for every resource (files, sockets, mutexes, memory)
+- Rule of Zero: prefer classes that need no custom special members
+- Rule of Five: if you need one custom special member, define all five
+- Move semantics for efficient transfers
+
+```cpp
+auto widget = std::make_unique<Widget>(42);
+auto shared = std::make_shared<Resource>();
+```
+
+---
+
+## Concurrency
+
+### Core Rules
+
+- Immutable data is thread-safe — share via `const` references
+- Every mutable shared state needs synchronization
+- `std::jthread` (C++20) — automatically joins on destruction
+- `std::scoped_lock` — deadlock-free multi-mutex locking
+- `std::atomic` for single variables, `std::mutex` for compound operations
+
+```cpp
+auto worker = std::jthread([](std::stop_token stop) {
+    while (!stop.stop_requested()) { /* work */ }
+});
+```
+
+### Parallel Algorithms
+
+```cpp
+std::sort(std::execution::par, data.begin(), data.end());
+```
+
+---
+
+## Error Handling
+
+### Exception Safety Guarantees
+
+1. **No-throw** — Function never throws. Mark `noexcept`.
+2. **Strong** — If exception thrown, state rolls back.
+3. **Basic** — Invariants preserved, no leaks.
+
+### std::expected (C++23)
+
+```cpp
+auto result = validate(input)
+    .and_then([&](auto v) { return save(db, v); })
+    .transform([](auto s) { return Response::from(s); });
+```
+
+### Rules
+
+- Throw by value, catch by const reference
+- `noexcept` on destructors, move operations, swap
+- `static_assert` for compile-time invariants
+- Never throw in destructors
+
+---
+
+## Testing
+
+### Framework Stack
+
+| Tool | Purpose |
+|------|---------|
+| Google Test / Catch2 | Test framework |
+| Google Mock | Mocking |
+| Google Benchmark | Micro-benchmarks |
+| ASan | Address sanitizer |
+| UBSan | Undefined behavior sanitizer |
+| TSan | Thread sanitizer |
+| Valgrind | Memory leak detection |
+
+### Sanitizers Are Mandatory
+
+```bash
+cmake -B build -DENABLE_SANITIZERS=ON
+cmake --build build && ctest --test-dir build
+```
+
+Every sanitizer finding is a real bug. No exceptions.
+
+---
+
+## Performance
+
+### Profile First
+
+```bash
+perf record -g ./myapp && perf report
+```
+
+### Key Patterns
+
+- Cache-friendly data structures (SoA vs AoS for hot loops)
+- Pre-allocate containers with `reserve()`
+- Move semantics to avoid copies
+- `constexpr` computation at compile time
+- Help auto-vectorization with simple loops and `__restrict`
+- `std::string_view` for zero-copy string operations
+
+---
+
+## Tooling
+
+### Essential Stack
+
+| Tool | Purpose |
+|------|---------|
+| CMake + Ninja | Build system |
+| vcpkg / Conan | Package management |
+| clang-format | Code formatting |
+| clang-tidy | Static analysis |
+| Sanitizers | Runtime bug detection |
+| perf / Valgrind | Profiling |
+| spdlog | Structured logging |
+
+### CI Essentials
+
+```bash
+cmake --preset dev && cmake --build --preset dev
+ctest --preset dev
+clang-format --dry-run --Werror src/*.cpp
+clang-tidy -p build/dev src/*.cpp
+```
+
+---
+
+## 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
+- [ ] No memory leaks
+- [ ] `const` correctness enforced
+- [ ] RAII used for all resource management
+- [ ] No raw `new`/`delete` in application code
+- [ ] Exception safety guarantees documented
+- [ ] Code reviewed and approved