From 58de897fc3ffc4cb58b49afb642519de87459823 Mon Sep 17 00:00:00 2001
From: portersky <24420859+portersky@users.noreply.github.com>
Date: Thu, 24 Sep 2026 20:07:14 +0200
Subject: [PATCH] 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/README.md                      | 39 ++++++++++
 {.pi => .agents}/skills/cmake/SKILL.md | 33 +++++++--
 {.pi => .agents}/skills/git/SKILL.md   | 77 +++++++++++++-------
 {.pi => .agents}/skills/tdd/SKILL.md   | 86 +++++++++++++++++-----
 .oxfmtrc.json                          | 17 +++++
 .pi/README.md                          | 43 -----------
 AGENTS.md                              | 99 ++++++++++++++++++++++----
 7 files changed, 291 insertions(+), 103 deletions(-)
 create mode 100644 .agents/README.md
 rename {.pi => .agents}/skills/cmake/SKILL.md (78%)
 rename {.pi => .agents}/skills/git/SKILL.md (57%)
 rename {.pi => .agents}/skills/tdd/SKILL.md (65%)
 create mode 100644 .oxfmtrc.json
 delete mode 100644 .pi/README.md

diff --git a/.agents/README.md b/.agents/README.md
new file mode 100644
index 0000000..a7c9d5a
--- /dev/null
+++ b/.agents/README.md
@@ -0,0 +1,39 @@
+# Agent Skills
+
+This directory contains reusable, agent-agnostic guidance for common
+project tasks. The skills are Markdown documents, not instructions tied
+to a particular coding-agent product. Read the relevant skill when a
+task matches its description; skill discovery and loading support varies
+between tools.
+
+## Skills
+
+- [`tdd`](skills/tdd/SKILL.md): Test-driven development with Unity and
+  CMock.
+- [`cmake`](skills/cmake/SKILL.md): Build configuration, modules, and
+  dependencies.
+- [`git`](skills/git/SKILL.md): Commit messages, tagging, and branching.
+
+## Adding a Skill
+
+Place a `SKILL.md` inside a named directory under `.agents/skills/`:
+
+```
+.agents/skills/
+  my-skill/
+    SKILL.md
+```
+
+Include frontmatter with the skill's name and a short description of
+when to use it:
+
+```yaml
+---
+name: my-skill
+description: Describe the tasks this skill helps with.
+---
+```
+
+Keep the instructions self-contained and useful across coding-agent
+tools. Avoid tool-specific loading commands unless a skill is explicitly
+written for that tool.
diff --git a/.pi/skills/cmake/SKILL.md b/.agents/skills/cmake/SKILL.md
similarity index 78%
rename from .pi/skills/cmake/SKILL.md
rename to .agents/skills/cmake/SKILL.md
index 19e7e91..43eea04 100644
--- a/.pi/skills/cmake/SKILL.md
+++ b/.agents/skills/cmake/SKILL.md
@@ -1,12 +1,19 @@
 ---
 name: cmake
-description: CMake build configuration for projects scaffolded from the ctdd
-  template. Use when adding modules, adding dependencies, configuring coverage
-  or sanitizers, or understanding the build system.
+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`).
 
@@ -24,8 +31,8 @@ description: CMake build configuration for projects scaffolded from the ctdd
 
 ## Adding a Module
 
-Modules live in `<src>/` as static libraries. Register them in
-`<src>/CMakeLists.txt`:
+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)
@@ -33,6 +40,19 @@ 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
@@ -122,6 +142,9 @@ 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
diff --git a/.pi/skills/git/SKILL.md b/.agents/skills/git/SKILL.md
similarity index 57%
rename from .pi/skills/git/SKILL.md
rename to .agents/skills/git/SKILL.md
index 5b105e1..373e870 100644
--- a/.pi/skills/git/SKILL.md
+++ b/.agents/skills/git/SKILL.md
@@ -1,32 +1,63 @@
 ---
 name: git
-description: Git workflow for the ctdd template project. Use when committing
-  changes, creating tags for releases, or following the branching and commit
-  message conventions.
+description: Git workflow for the ctdd C/C++ starter template. Use when
+  committing template or example changes, creating release tags, or following
+  the branching and commit message conventions.
 ---
 
 # Git Skill
 
+This repository is a reusable starter template for C and C++ projects.
+Treat its checked-in code as examples demonstrating the build and test
+setup, not as a required application API. Template releases should keep
+the starter structure and Unity/CMock workflows useful to derived projects.
+
 ## Commit Messages
 
-Follow [Conventional Commits](https://www.conventionalcommits.org/) with the
-50/72 rule.
+Follow [Conventional Commits v1.0.0][cc] with the 50/72 rule.
+
+[cc]: https://www.conventionalcommits.org/en/v1.0.0/
 
 ### Format
 
 ```
-<type>: <subject>
+<type>[optional scope][!]: <subject>
 
 <body>
 
-<footer>
+[BREAKING CHANGE: <description>]
+Co-authored-by: <Name> <email>
 ```
 
-- **Subject:** max 50 characters, imperative mood, no period
-- **Body:** wrapped at 72 characters, optional
-- **Blank line** between subject and body
-- **No co-author trailers** (`Co-Authored-By:` is forbidden)
-- **No em dashes** (`—`). Use a colon or rewrite the sentence
+- Subject: max 50 characters; use imperative mood and no period.
+- Wrap body lines at 72 characters. Keep the message concise.
+- Separate the subject from the body with a blank line.
+- Use Conventional Commit types such as `feat`, `fix`, `docs`, `chore`,
+  and `ci`; scopes are optional.
+- Mark breaking changes with `!` and/or a `BREAKING CHANGE:` footer.
+- No em dashes (`—`). Use a colon or rewrite the sentence.
+
+Always include one `Co-authored-by:` trailer per contributing agent or
+model, using `<Name> <email>`:
+
+- Name: human-readable model name, e.g. `Qwen 3.8 27B`.
+- Email local part: lowercase model identifier, replacing invalid
+  characters with dots. If the model is unknown, use the product name.
+- Email domain: the service that ran the model, using its real domain.
+  For self-hosted services, use your own domain. Use
+  `<runtime>.local` only for local inference with no service domain.
+
+Examples:
+
+```
+Co-authored-by: Qwen 3.8 27B <qwen3.8.q3_k_xl@lmstudio.local>
+Co-authored-by: GPT-5.6 Luna <gpt5.6.luna@openrouter.ai>
+Co-authored-by: Claude Sonnet 4.5 <claude.sonnet4.5@github.com>
+```
+
+The corporate commit-msg hook rejects these trailers, agent email
+addresses, `.local` domains, and free-text descriptions. Skip the hook
+with `--no-verify` when committing.
 
 ### Types
 
@@ -50,16 +81,22 @@ feat: add stopwatch timer
 
 Replace Hello World with a live stopwatch that prints elapsed time
 in HH:MM:SS.mmm format, updating every 10ms with color output.
+
+Co-authored-by: GPT-5.6 Luna <gpt5.6.luna@openrouter.ai>
 ```
 
 ```
 fix: clear Unity INTERFACE_SYSTEM_INCLUDE_DIRECTORIES
 
 CMake rejects the path inside the build tree on newer versions.
+
+Co-authored-by: GPT-5.6 Luna <gpt5.6.luna@openrouter.ai>
 ```
 
 ```
 chore: bump CMock to v2.6.0
+
+Co-authored-by: GPT-5.6 Luna <gpt5.6.luna@openrouter.ai>
 ```
 
 Bad:
@@ -79,19 +116,11 @@ Stage changes:
 git add -A
 ```
 
-Commit:
+Write the complete message, including co-author trailers, to a message
+file, then commit while skipping the rejecting hook:
 
 ```sh
-git commit -m "type: subject"
-```
-
-For multi-line messages:
-
-```sh
-git commit -m "type: subject
-
-body line 1
-body line 2"
+git commit --no-verify -F <message-file>
 ```
 
 ## Tagging
@@ -182,7 +211,7 @@ Branch naming:
 - [ ] Tests pass: `ninja -C build check`
 - [ ] Commit message follows 50/72 rule
 - [ ] Conventional commit type used
-- [ ] No co-author trailers
+- [ ] Co-author trailer for every contributing agent or model
 - [ ] No em dashes
 - [ ] No large unchanged regions reformatted
 - [ ] No speculative code or unused imports
diff --git a/.pi/skills/tdd/SKILL.md b/.agents/skills/tdd/SKILL.md
similarity index 65%
rename from .pi/skills/tdd/SKILL.md
rename to .agents/skills/tdd/SKILL.md
index 1f4280b..7f7aec1 100644
--- a/.pi/skills/tdd/SKILL.md
+++ b/.agents/skills/tdd/SKILL.md
@@ -1,12 +1,20 @@
 ---
 name: tdd
-description: Test-driven development with Unity and CMock. Use when adding new
-  modules, writing tests, mocking dependencies, or following Red-Green-Refactor
-  in projects scaffolded from the ctdd template.
+description: Test-driven development with Unity and CMock for C and C++
+  projects started from the ctdd template. Use when adding modules, writing
+  tests, or following Red-Green-Refactor.
 ---
 
 # TDD Skill
 
+This repository is a starter template, and its checked-in examples are C.
+Use these workflows as examples when building a C or C++ project from the
+template; do not treat the sample modules as required product features.
+Unity is used for both C and C++ tests. The CMock examples below apply to
+C-compatible interfaces. CMock does not provide general mocking for C++
+classes, so choose an appropriate fake or mocking tool for C++ APIs. When a
+C++ test calls a C API, expose that API with C linkage.
+
 > Replace `<src>/` with the project source directory (e.g. `ctdd/`, `src/`).
 > Replace `<module>` with the module name (e.g. `counter`, `timer`).
 
@@ -58,7 +66,9 @@ auto fn_name(int arg) -> int;
 
 ### 2. Write the test
 
-Create `tests/test_<module>.c`. Two patterns exist:
+Create `tests/test_<module>.c` for C or
+`tests/test_<module>.cpp` for C++. Choose a state-based Unity test for pure
+logic or an interaction-based test for a C dependency:
 
 **State-based** (pure functions, no mocks):
 
@@ -80,7 +90,27 @@ int main(void) {
 }
 ```
 
-**Interaction-based** (mocking a dependency):
+A C++ state-based test uses a `.cpp` source and the same Unity assertions:
+
+```cpp
+#include "unity.h"
+#include "<src>/<module>.h"
+
+auto setUp() -> void {}
+auto tearDown() -> void {}
+
+auto test_fn_name_returns_expected() -> void {
+    TEST_ASSERT_EQUAL_INT(42, fn_name(1));
+}
+
+auto main() -> int {
+    UNITY_BEGIN();
+    RUN_TEST(test_fn_name_returns_expected);
+    return UNITY_END();
+}
+```
+
+**Interaction-based** (mocking a C-compatible dependency with CMock):
 
 ```c
 #include "unity.h"
@@ -104,7 +134,9 @@ int main(void) {
 
 ### 3. Register the test in `tests/CMakeLists.txt`
 
-Add after existing test targets, before the `check` target:
+Add after existing test targets, before the `check` target. Use the source
+extension and compile feature for the test language. The current examples
+are C:
 
 **State-based (no mock):**
 
@@ -129,11 +161,23 @@ add_test(NAME test_<module> COMMAND test_<module>)
 list(APPEND TEST_TARGETS test_<module>)
 ```
 
+For a C++ Unity test, use a `.cpp` test source and select the C++ standard
+for that target, for example:
+
+```cmake
+add_executable(test_<module> test_<module>.cpp)
+target_include_directories(test_<module> PRIVATE "${CMAKE_SOURCE_DIR}")
+target_link_libraries(test_<module> PRIVATE <src>_<module> Unity::Unity)
+target_compile_features(test_<module> PRIVATE cxx_std_23)
+add_test(NAME test_<module> COMMAND test_<module>)
+list(APPEND TEST_TARGETS test_<module>)
+```
+
+Replace `cxx_std_23` with the standard chosen for the derived project.
+
 ### 4. Stub the implementation
 
-Create `<src>/<module>.c` with a dummy return:
-
-C:
+For C, create `<src>/<module>.c` with a dummy return:
 
 ```c
 #include "<src>/<module>.h"
@@ -143,7 +187,7 @@ int fn_name(int arg) {
 }
 ```
 
-C++:
+For C++, create `<src>/<module>.cpp`:
 
 ```cpp
 #include "<src>/<module>.h"
@@ -153,7 +197,7 @@ auto fn_name(int arg) -> int {
 }
 ```
 
-Register the library in `<src>/CMakeLists.txt`:
+Register a C library in `<src>/CMakeLists.txt`:
 
 ```cmake
 add_library(<src>_<module> <module>.c)
@@ -161,6 +205,14 @@ target_include_directories(<src>_<module> PUBLIC "${CMAKE_CURRENT_SOURCE_DIR}")
 target_compile_features(<src>_<module> PRIVATE c_std_23)
 ```
 
+For C++, use the `.cpp` source and the standard selected for the project:
+
+```cmake
+add_library(<src>_<module> <module>.cpp)
+target_include_directories(<src>_<module> PUBLIC "${CMAKE_CURRENT_SOURCE_DIR}")
+target_compile_features(<src>_<module> PRIVATE cxx_std_23)
+```
+
 ### 5. Confirm RED
 
 ```sh
@@ -239,11 +291,11 @@ Open `build-cov/coverage/index.html` in a browser.
 Before considering a task done:
 
 - [ ] Header declares the public API
-- [ ] Test covers at least one happy path, one edge case
-- [ ] Test registered in `tests/CMakeLists.txt`
+- [ ] Test covers at least one happy path and one edge case
+- [ ] Test registered in `tests/CMakeLists.txt` with the correct language
 - [ ] Library registered in `<src>/CMakeLists.txt` (if new module)
 - [ ] `ninja -C build check` passes with zero failures
-- [ ] No semicolons after closing braces
-- [ ] Trailing return type on all functions
-- [ ] East const (`char const*`)
-- [ ] `snake_case` naming
+- [ ] CMock is used only for C-compatible interfaces
+- [ ] C++ targets select the intended C++ standard
+- [ ] C++ code follows the trailing-return-type convention
+- [ ] East const (`char const*`) and `snake_case` naming are used
diff --git a/.oxfmtrc.json b/.oxfmtrc.json
new file mode 100644
index 0000000..db10ecf
--- /dev/null
+++ b/.oxfmtrc.json
@@ -0,0 +1,17 @@
+{
+  "ignorePatterns": [
+    "node_modules",
+    "dist",
+    ".git",
+    "build"
+  ],
+  "overrides": [
+    {
+      "files": ["*.md"],
+      "options": {
+        "printWidth": 80,
+        "proseWrap": "always"
+      }
+    }
+  ]
+}
diff --git a/.pi/README.md b/.pi/README.md
deleted file mode 100644
index 4f42b6b..0000000
--- a/.pi/README.md
+++ /dev/null
@@ -1,43 +0,0 @@
-# Pi Skills
-
-Project-level skills loaded by Pi on-demand.
-
-## Skills
-
-| Skill                          | Description                                          |
-| ------------------------------ | ---------------------------------------------------- |
-| [tdd](skills/tdd/SKILL.md)     | TDD workflow with Unity and CMock                    |
-| [cmake](skills/cmake/SKILL.md) | Build configuration, adding modules and dependencies |
-| [git](skills/git/SKILL.md) | Commit messages, tagging, and branching workflow |
-
-## Installation
-
-Skills are auto-discovered by Pi from `.pi/skills/`. No extra setup
-required.
-
-To install this project's skills into another project:
-
-```sh
-pi install -l git:github.com/portersky/helloctdd
-```
-
-Or as a temporary package for the current session:
-
-```sh
-pi -e git:github.com/portersky/helloctdd
-```
-
-Pi auto-discovers `skills/` directories from installed packages.
-
-## Adding a New Skill
-
-Place a `SKILL.md` inside a directory under `.pi/skills/`:
-
-```
-.pi/skills/
-  my-skill/
-    SKILL.md
-```
-
-Pi validates the frontmatter and registers `/skill:my-skill` in the
-TUI.
diff --git a/AGENTS.md b/AGENTS.md
index db81dee..1749a37 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -2,29 +2,45 @@
 
 ## Project Overview
 
-`ctdd` is a C23 template project wired for test-driven development
-using Unity and CMock. Use it as the core template when scaffolding
-new projects.
+`ctdd` is a starter template for C and C++ projects. Its small C23
+application and test suite demonstrate test-driven development with
+Unity and CMock. This repository is template infrastructure plus
+replaceable examples, not a production library or a specification for
+future application features.
 
-For TDD workflows (adding modules, writing tests, mocking), load the
-`tdd` skill with `/skill:tdd`.
+The checked-in modules and tests are currently C-only. Unity is used for
+the test examples; CMock demonstrates mocking C interfaces and is not a
+general C++ class-mocking solution. For C++-specific APIs, use Unity
+tests and choose an appropriate fake or mocking approach for the derived
+project.
 
-For build configuration (dependencies, coverage, sanitizers), load the
-`cmake` skill with `/skill:cmake`.
+When using this starter, rewrite `AGENTS.md` to describe the resulting
+project: its purpose, layout, languages, toolchain, build and test
+commands, and coding conventions. Remove starter-specific guidance that
+no longer applies. Mentioning the template origin is optional; if useful,
+add a brief note, for example at the end of the derived project's
+`README.md`. It is not required in `AGENTS.md`.
 
-For committing, tagging, and branching, load the `git` skill with
-`/skill:git`.
+Project-specific skills are available under `.agents/skills/`. Read the
+relevant skill when its guidance applies:
+
+- TDD workflows: `.agents/skills/tdd/SKILL.md`
+- Build configuration, dependencies, coverage, and sanitizers:
+  `.agents/skills/cmake/SKILL.md`
+- Committing, tagging, and branching: `.agents/skills/git/SKILL.md`
 
 ## Build System
 
 - **Generator:** Ninja
 - **CMake minimum:** 3.21
-- **C standard:** C23
+- **C examples:** C23
+- **C++ examples:** No C++ standard is currently set by the template.
+  Choose and set the standard explicitly for any C++ target.
 
 ### Dependencies
 
 Dependencies are managed via custom `Find*.cmake` scripts in `deps/`.
-See `/skill:cmake` for adding new dependencies.
+See `.agents/skills/cmake/SKILL.md` for adding new dependencies.
 
 ## Build
 
@@ -74,13 +90,13 @@ Run the application:
 
 On Windows use `./build/main.exe`.
 
-See `/skill:cmake` for coverage and sanitizer details.
+See `.agents/skills/cmake/SKILL.md` for coverage and sanitizer details.
 
 ## Coding Conventions
 
 ### C
 
-- **Language:** C23
+- **Language:** C23 for the checked-in examples
 - **East const** (e.g. `char const*` not `const char*`)
 - **4-space indentation**
 - `<>` includes for system headers (C stdlib, OS, etc.)
@@ -90,6 +106,8 @@ See `/skill:cmake` for coverage and sanitizer details.
 
 ### C++
 
+- Follow the standard selected for the target; this template does not
+  currently configure a C++ standard.
 - **Trailing return type** for function signatures
   (e.g. `auto fn() -> void`)
 - `auto` for obvious types (e.g. `auto main(...) -> int`)
@@ -123,7 +141,8 @@ Both C and C++ follow the same include order:
 
 ## Commit Messages
 
-See `/skill:git` for commit message conventions, types, and examples.
+See `.agents/skills/git/SKILL.md` for commit message conventions, types,
+and examples.
 
 ## Documentation (Markdown)
 
@@ -147,8 +166,48 @@ See `/skill:git` for commit message conventions, types, and examples.
 
 - This file (`AGENTS.md`) follows its own rules.
 
+### Formatting
+
+Use Oxfmt to format or verify formatting. The repository's `.oxfmtrc.json`
+sets Markdown wrapping options.
+
+Format all Oxfmt-supported files:
+
+```sh
+npx oxfmt --write .
+```
+
+Check all Oxfmt-supported files without changing them:
+
+```sh
+npx oxfmt --check .
+```
+
+The `.` commands cover Oxfmt-supported files beyond Markdown, and the
+`--write` command may also reformat source files. To format or check only
+Markdown files, pass a Markdown glob instead.
+
+Format Markdown files only:
+
+```sh
+npx oxfmt --write "**/*.md"
+```
+
+Check Markdown files only:
+
+```sh
+npx oxfmt --check "**/*.md"
+```
+
+Oxfmt is not pinned in this template, so `npx` may use a different version
+over time. No package manifest or lockfile is required; pin the formatter
+only if a derived project needs repeatable formatter versions.
+
 ## Source Layout
 
+The layout below describes the current C examples, not a required
+architecture for projects created from this starter.
+
 ```
 ctdd/
   str.h / str.c        Pure string utilities (no dependencies)
@@ -170,6 +229,18 @@ deps/
 Reduce common LLM coding mistakes. Bias toward caution over speed.
 For trivial tasks, use judgment.
 
+### Keep Changes Template-Focused
+
+Treat the application modules as examples of how to wire C code,
+Unity, and CMock together. Do not add product-specific features or treat
+the sample APIs as requirements unless explicitly asked. Keep template
+changes useful to both C and C++ starter projects, and do not imply that
+the current C-only examples already demonstrate C++ integration.
+
+When adapting this repository, follow the `AGENTS.md` customization
+guidance in Project Overview. Any note about the template origin is
+optional and can go in the derived project's `README.md` if desired.
+
 ### Think Before Coding
 
 - State assumptions explicitly. If uncertain, ask.