cppcourse/AGENTS.md

# AGENTS.md

## Project Overview

This repository holds the content for a C++ course: lecture material, exercises,
and runnable code examples. The language target is modern C++ (C++23).

The repository is in a startup phase: no course content exists yet. As material
is added, document its layout under "Source Layout".

## Build System

CMake (3.21+) with Ninja.

```sh
cmake -B build -G Ninja
cmake --build build
```

Course exercises in `cmat/` are excluded from the default build; build one by
target name, e.g.:

```sh
cmake --build build --target Ex11
```

Tests (optional): configure with `-DBUILD_TESTING=ON`, then run `ninja check` in
the build directory.

## Coding Conventions

- **Language:** C++23
- **Primitive types:** use fixed-width type aliases (`u32`, `i64`, ...) instead
  of `std::uint32_t` etc.
- **Trailing return type** for function signatures (e.g. `auto fn() -> void`)
- **4-space indentation**
- **No semicolons after closing braces** for namespaces/classes
- `auto` for obvious types (e.g. `auto main(...) -> int`)
- **East const** (e.g. `char const*` not `const char*`)
- **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
- **Private data members** start with `m_` (e.g. `m_state`)
- `<>` includes only for system headers (std, OS, etc.)
- `""` includes for third-party dependencies (e.g. `fmt`, `nlohmann/json`)
- **Naming:** `snake_case` for variables, functions, and classes
- **Naming:** `SCREAMING_SNAKE_CASE` only for macros and constants
- **Header extensions:** C++ headers use `.hpp`, C headers use `.h`
- 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

Follow the git skill (`.agents/skills/git/SKILL.md`) for commit message format,
conventional types, co-author trailers, and the committing workflow.

## Versioning

This project follows [Semantic Versioning](https://semver.org) for tagged
releases of the course material.

- **Patch** (`x.y.Z`): corrections and small updates to existing material. No
  change is too small.
- **Minor** (`x.Y.z`): new lectures, exercises, or other significant additions.
- **Major** (`X.y.z`): restructuring that breaks how the material is organized
  or used.

## 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.
- This file (`AGENTS.md`) follows its own rules.
- Do not use em dashes (`—`). Use a colon or rewrite the sentence.

### Auto-Formatting with oxfmt

- All markdown files are formatted with **oxfmt**
- **Always run `npx oxfmt --write .` after editing any markdown file**
  - This is mandatory. Do not skip it. Run it before finishing your response
- Use `npx oxfmt --check .` to verify formatting before committing
- Config is in `.oxfmtrc.json` at the project root
- Do not manually fight the formatter. Let oxfmt handle spacing, line breaks,
  and list alignment

## Source Layout

```text
cppcourse/
  AGENTS.md         # This file
  README.md         # Project docs
  .oxfmtrc.json     # oxfmt config
  .agents/          # Agent skills (git workflow)
  CMakeLists.txt    # Build system entry point
  deps/             # CMake helper modules (platform, flags, Find* deps)
  cmat/             # Course material: exercises and solutions
  397/              # Original copy of the course material (reference only)
```

`cmat/` layout:

- `Ex*/`: exercise starting points. Some intentionally contain bugs that
  students fix during the course; their targets fail to compile (or misbehave at
  runtime) until fixed.
- `SolutionEx*/`: working solutions of the exercises.
- `DOS_Unix/`: platform Keyboard/Screen implementations shared by the GUI
  exercises. The DOS variants are Windows-specific; on Unix-like systems the
  curses variants are built instead (linked as the `dos_unix` library).
- Each exercise directory holds a `CMakeLists.txt` that defines its target via
  `cmat_add_exercise()` (see `cmat/CMakeLists.txt`). Exercises that need a
  missing dependency (e.g. Boost) are reported as not available at configure
  time and skipped.

## Behavioral Guidelines

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

### 1. Think Before Coding

Don't assume. Don't hide confusion. Surface tradeoffs.

Before implementing:

- State your assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them, don't pick silently.
- If a simpler approach exists, say so. Push back when warranted.
- If something is unclear, stop. Name what's confusing. Ask.

### 2. Simplicity First

Minimum code that solves the problem. Nothing speculative.

- No features beyond what was asked.
- No abstractions for single-use code.
- No "flexibility" or "configurability" that wasn't requested.
- No error handling for impossible scenarios.
- If you write 200 lines and it could be 50, rewrite it.

Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes,
simplify.

### 3. Surgical Changes

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

When editing existing code:

- 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.
- If you notice unrelated dead code, mention it, don't delete it.

When your changes create orphans:

- Remove imports/variables/functions that YOUR changes made unused.
- Don't remove pre-existing dead code unless asked.

Every changed line should trace directly to the user's request.

### 4. Goal-Driven Execution

Define success criteria. Loop until verified.

Transform tasks into verifiable goals:

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

For multi-step tasks, state a brief plan:

```
1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]
```

Strong success criteria let you loop independently. Weak criteria ("make it
work") require constant clarification.

## Target Platforms

The primary platform for building and running course examples is Linux. Keep
examples portable within that constraint unless a lesson specifically targets
another platform.