chore: refresh project agent guidance

Clarify template guidance, move skills, and document formatter and
commit conventions.

Co-authored-by: GPT-6 Luna <gpt.6.luna@openrouter.ai>

.agents/skills/cmake/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: cmake
+description: CMake build configuration for C and C++ projects started from
+  the ctdd template. Use when adding modules or dependencies, or configuring
+  builds, coverage, and sanitizers.
+---
+
+# CMake Skill
+
+This repository is a starter template, not an application whose sample
+modules define required features. Its checked-in targets are C examples
+using C23. When adding C++ targets, use `.cpp` sources and select the
+project's C++ standard explicitly (for example, `cxx_std_23`). Unity can
+be used by C++ tests. CMock is for C-compatible interfaces, not C++ class
+mocking.
+
+> Replace `<src>/` with the project source directory (e.g. `ctdd/`, `src/`).
+> Replace `<module>` with the module name (e.g. `counter`, `timer`).
+
+## Build Commands
+
+| Action    | Command                                                                                    |
+| --------- | ------------------------------------------------------------------------------------------ |
+| Configure | `cmake -S . -B build -G Ninja`                                                             |
+| Build     | `ninja -C build`                                                                           |
+| Run tests | `ninja -C build check`                                                                     |
+| Coverage  | `cmake -S . -B build-cov -G Ninja -DENABLE_COVERAGE=ON` then `ninja -C build-cov coverage` |
+| ASan      | `cmake -S . -B build-asan -G Ninja -DENABLE_ASAN=ON` then `ninja -C build-asan`            |
+
+> ASan and coverage cannot be used together.
+
+## Adding a Module
+
+Modules live in `<src>/` as static libraries. The current example is C;
+register C modules in `<src>/CMakeLists.txt`:
+
+```cmake
+add_library(<src>_<module> <module>.c)
+target_include_directories(<src>_<module> PUBLIC "${CMAKE_SOURCE_DIR}")
+target_compile_features(<src>_<module> PRIVATE c_std_23)
+```
+
+For a C++ module, use a `.cpp` source and select the standard used by the
+derived project:
+
+```cmake
+add_library(<src>_<module> <module>.cpp)
+target_include_directories(<src>_<module> PUBLIC "${CMAKE_SOURCE_DIR}")
+target_compile_features(<src>_<module> PRIVATE cxx_std_23)
+```
+
+Replace `cxx_std_23` if the project uses a different C++ standard. Likewise,
+choose `.c`/`c_std_23` or `.cpp`/`cxx_std_23` for the application's entry
+point and test sources.
+
+Link into `main` in the root `CMakeLists.txt`:
+
+```cmake
+target_link_libraries(main PRIVATE ... <src>_<module>)
+```
+
+## Adding a Dependency
+
+Dependencies are fetched via custom `Find<name>.cmake` scripts in `deps/`.
+`deps/` is on `CMAKE_MODULE_PATH` so `find_package()` resolves to these
+scripts first.
+
+### 1. Create `deps/Find<name>.cmake`
+
+Pattern (follow `deps/FindUnity.cmake` or `deps/FindCMock.cmake`):
+
+```cmake
+if (DEFINED _FIND<NAME>_INCLUDED)
+    return()
+endif()
+set(_FIND<NAME>_INCLUDED TRUE)
+
+set(<NAME>_VERSION "x.y.z")
+message(STATUS "Fetching <name> ${<NAME>_VERSION}")
+
+include(FetchContent)
+
+FetchContent_Declare(
+    <name>
+    URL https://github.com/org/<name>/archive/refs/tags/v${<NAME>_VERSION}.zip
+    DOWNLOAD_EXTRACT_TIMESTAMP TRUE
+)
+
+FetchContent_MakeAvailable(<name>)
+
+if (NOT TARGET <Name>::<Name>)
+    add_library(<Name>::<Name> ALIAS <name>)
+endif()
+
+set(<Name>_FOUND TRUE)
+```
+
+For libraries without CMakeLists.txt (like CMock), use
+`FetchContent_Populate` and compile manually. See `FindCMock.cmake`
+for the pattern.
+
+### 2. Add `find_package(<Name> REQUIRED)` to `CMakeLists.txt`
+
+Place it after `include(Platform)` and `include(Flags)`.
+
+### 3. Link with `<Name>::<Name>`
+
+In `<src>/CMakeLists.txt` or `tests/CMakeLists.txt` as needed:
+
+```cmake
+target_link_libraries(<src>_<module> PRIVATE <Name>::<Name>)
+```
+
+## Platform Flags
+
+`deps/Platform.cmake` sets these variables for conditional logic:
+
+| Variable          | Meaning                                          |
+| ----------------- | ------------------------------------------------ |
+| `IS_CLANG_OR_GCC` | Clang or GCC compiler                            |
+| `IS_MSVC`         | MSVC compiler                                    |
+| `IS_WINDOWS`      | Windows target                                   |
+| `IS_LINUX`        | Linux target                                     |
+| `IS_MACOS`        | macOS target                                     |
+| `IS_IOS`          | iOS target                                       |
+| `IS_ANDROID`      | Android target                                   |
+| `IS_EMSCRIPTEN`   | Emscripten/WASM target                           |
+| `ARCH`            | Normalized arch (`amd64`, `arm64`, `wasm`, etc.) |
+| `IS_AMD64`        | x86_64                                           |
+| `IS_ARM64`        | arm64/aarch64                                    |
+
+## Compiler Flags
+
+`deps/Flags.cmake` defines `BASE_OPTIONS` (warning flags) and
+`BASE_DEFINITIONS`. Apply per-target to avoid polluting fetched
+dependencies:
+
+```cmake
+target_compile_options(<target> PRIVATE ${BASE_OPTIONS})
+target_compile_definitions(<target> PRIVATE ${BASE_DEFINITIONS})
+```
+
+## CMock Mock Generation
+
+CMock generates mocks for C-compatible interfaces. Do not pass C++ class
+headers to this helper; use a suitable fake or mocking tool for C++ APIs.
+
+`tests/CMakeLists.txt` provides a `cmock_generate_mock` helper function:
+
+```cmake
+cmock_generate_mock(<target> "<absolute-path-to-header>")
+```
+
+With optional config file:
+
+```cmake
+cmock_generate_mock(<target> "<header>" "cmock_config.yml")
+```
+
+Generated mocks go into `build/mocks/` as `Mock<name>.h/.c`.
+
+## Coverage
+
+Enabled via `-DENABLE_COVERAGE=ON`. Requires GCC or Clang + `gcovr`.
+Report at `build-cov/coverage/index.html`. Only `<src>/` sources are
+measured; Unity, CMock, and mocks are excluded.
+
+## Sanitizers
+
+`deps/Sanitizers.cmake` provides AddressSanitizer via `-DENABLE_ASAN=ON`.
+Incompatible with coverage.