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.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.