ctdd/AGENTS.md

AGENTS.md

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.

For TDD workflows (adding modules, writing tests, mocking), load the tdd skill with /skill:tdd.

For build configuration (dependencies, coverage, sanitizers), load the cmake skill with /skill:cmake.

For committing, tagging, and branching, load the git skill with /skill:git.

Build System

• Generator: Ninja
• CMake minimum: 3.21
• C standard: C23

Dependencies

Dependencies are managed via custom Find*.cmake scripts in deps/. See /skill:cmake for adding new dependencies.

Coding Conventions

C

• Language: C23
• East const (e.g. char const* not const char*)
• 4-space indentation
• <> includes for system headers (C stdlib, OS, etc.)
• "" includes for third-party and local headers
• Naming: snake_case for variables, functions, and structs
• Naming: SCREAMING_SNAKE_CASE only for macros and constants

C++

• Trailing return type for function signatures (e.g. auto fn() -> void)
• auto for obvious types (e.g. auto main(...) -> int)
• No semicolons after closing braces for namespaces/classes
• Trailing return type for all function definitions, including operators (e.g. auto operator=(T&&) noexcept -> T&)
• Public members first in class declarations, private members at the bottom

Include Order

Both C and C++ follow the same include order:

1. C++ standard library headers (<chrono>, <vector>, etc.)
2. (blank line)
3. C standard library headers (<stdlib.h>, <string.h>, etc.)
4. (blank line)
5. OS-specific headers (Windows API, POSIX, etc.)
6. (blank line)
7. Third-party dependencies ("fmt/core.h", etc.)
8. (blank line)
9. Local/project headers

Shell Scripts

• Always use #!/bin/sh shebang for shell scripts
• Scripts must be POSIX compliant (no bashisms)
• When providing commands to users:
  • Windows/PowerShell: use ` for line continuation
  • Unix/Linux/macOS: use \ for line continuation

Commit Messages

See /skill:git for commit message conventions, types, and examples.

Documentation (Markdown)

• Wrap normal text and lists at max 80 columns (for readability in terminals and editors).

• Exceptions: Tables and code blocks (```) can exceed 80 columns when formatting requires it (e.g. trees, alignment).

• Use standard Markdown: **bold**, `inline code`, ## headings, - or numbered lists, fenced code blocks with language hints (```cpp, ```sh).

• Keep examples concise, up-to-date, and self-documenting.

• Do not use em dashes (—). Use a colon or rewrite the sentence.

• Each shell command gets its own fenced code block; do not combine multiple commands into one block. Precede each block with a short plain-text label describing what the command does:

  Setup build:

  cmake -S . -B build -G Ninja
  

• This file (AGENTS.md) follows its own rules.

Source Layout

ctdd/
  str.h / str.c        Pure string utilities (no dependencies)
  report.h / report.c  Formats a value and calls log_info()
  logger.h / logger.c  Log levels, emits via log_write()
  log_write.h / log_write.c  Real log_write via printf to stdout
main.c                 Entry point (template placeholder)
tests/
  test_str.c           Unity state-based tests for ctdd/str
  test_report.c        Interaction-based tests using CMock
  test_logger.c        Interaction-based tests using CMock
deps/
  FindUnity.cmake      Fetches Unity v2.6.1 via ZIP
  FindCMock.cmake      Fetches CMock v2.6.0 via ZIP

Behavioral Guidelines

Reduce common LLM coding mistakes. Bias toward caution over speed. For trivial tasks, use judgment.

Think Before Coding

• State assumptions explicitly. If uncertain, ask.
• If multiple interpretations exist, present them, don't pick silently.
• If something is unclear, stop. Name what's confusing. Ask.

Simplicity First

Minimum code that solves the problem. Nothing speculative.

• No features beyond what was asked.
• No abstractions for single-use code.
• If you write 200 lines and it could be 50, rewrite it.

Surgical Changes

Touch only what you must. Clean up only your own mess.

• Don't "improve" adjacent code, comments, or formatting.
• Don't refactor things that aren't broken.
• Match existing style, even if you'd do it differently.
• Remove imports/variables/functions that YOUR changes made unused.
• Don't remove pre-existing dead code unless asked.

Goal-Driven Execution

Transform tasks into verifiable goals:

• "Add validation" means: write tests for invalid inputs, then pass.
• "Fix the bug" means: write a test that reproduces it, then pass.
• "Refactor X" means: ensure tests pass before and after.