Initial commit

Agent instructions (AGENTS.md), oxfmt config, git workflow skill, and .gitignore for the C++ course repository. Co-authored-by: Qwen 3.8 27B <qwen3.8_27b-q3_k_xl@jelly.nrv.nu>
2026-10-03 15:01:32 +02:00
commit 2bb43ddbf9
5 changed files with 673 additions and 0 deletions
@@ -0,0 +1,220 @@
 ---
 name: git
 description: >-
  Git workflow: commit message format, co-author trailers, tagging, and
  branching conventions. Use when committing changes, creating release tags, or
  following branch naming rules.
 ---
 # Git Skill
 This skill defines the git workflow for the repository: commit message format,
 co-author trailers, tagging, and branching conventions.
 ## Commit Messages
 Follow [Conventional Commits v1.0.0][cc] with the 50/72 rule. The full
 specification is vendored in `spec.md` next to this file; read it for edge cases
 such as scopes, footers, and breaking changes.
 [cc]: https://www.conventionalcommits.org/en/v1.0.0/
 ### Format
 ```
 <type>[optional scope][!]: <subject>
 <body>
 [BREAKING CHANGE: <description>]
 Co-authored-by: <Name> <email>
 ```
 - 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 including size, followed by `-`
  and the quantization (the dash marks where the quant starts), e.g.
  `qwen3.8_27b-q3_k_xl`. Replace other 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_27b-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
 | Type       | Use                                |
 | ---------- | ---------------------------------- |
 | `feat`     | New feature or module              |
 | `fix`      | Bug fix                            |
 | `docs`     | Documentation only                 |
 | `chore`    | Build, deps, config, housekeeping  |
 | `ci`       | CI/CD changes                      |
 | `refactor` | Code change without feature or fix |
 | `test`     | Adding or changing tests           |
 | `style`    | Formatting, whitespace, semicolons |
 ### Examples
 Good:
 ```
 feat: add pointer arithmetic exercise
 Add the pointer arithmetic exercise with a reference solution and
 compilation checks for the expected output.
 Co-authored-by: GPT-5.6 Luna <gpt5.6.luna@openrouter.ai>
 ```
 ```
 docs: outline lecture 03 on memory layout
 Document the stack, heap, and static storage regions so the exercise
 solutions reference the same terminology.
 Co-authored-by: GPT-5.6 Luna <gpt5.6.luna@openrouter.ai>
 ```
 ```
 chore: add oxfmt config
 Co-authored-by: GPT-5.6 Luna <gpt5.6.luna@openrouter.ai>
 ```
 Bad:
 ```
 added a new thing               # no type, lowercase, vague
 feat: add input trim            # no body for a significant change
 feat: add input trim control.   # trailing period
 feat: add trim — it's fast      # em dash not allowed
 ```
 ## Committing
 Stage changes:
 ```sh
 git add -A
 ```
 Write the complete message, including co-author trailers, to a message file,
 then commit while skipping the rejecting hook:
 ```sh
 git commit --no-verify -F <message-file>
 ```
 ## Tagging
 This project uses semantic versioning for releases.
 ### Creating a tag
 Create the tag:
 ```sh
 git tag -a v0.1.0 -m "Release v0.1.0"
 ```
 Push the tag:
 ```sh
 git push origin v0.1.0
 ```
 Tag messages follow the same rules as commit messages: no em dashes, wrapped at
 72 characters.
 ### Tag naming
 | Version  | Meaning                            |
 | -------- | ---------------------------------- |
 | `v0.x.0` | Minor changes, breaking API        |
 | `v0.x.y` | Patch changes, backward-compatible |
 | `v1.x.0` | Major release                      |
 ### When to tag
 - After merging a feature branch with significant changes
 - Before sharing course material with students
 - After build system or project structure changes
 ### Listing tags
 ```sh
 git tag -l
 ```
 ### Deleting a tag
 Delete the local tag:
 ```sh
 git tag -d v0.1.0
 ```
 Remove the remote tag:
 ```sh
 git push origin --delete v0.1.0
 ```
 ## Branching
 For local development:
 ```sh
 git checkout -b feat/add-counter
 ```
 Branch naming:
 | Prefix   | Use           |
 | -------- | ------------- |
 | `feat/`  | New feature   |
 | `fix/`   | Bug fix       |
 | `chore/` | Housekeeping  |
 | `docs/`  | Documentation |
 ## Common Commands
 | Command                 | Use                               |
 | ----------------------- | --------------------------------- |
 | `git log --oneline -10` | Recent history                    |
 | `git diff --staged`     | Check staged changes              |
 | `git status`            | Current state                     |
 | `git reset HEAD~1`      | Undo last commit (keep changes)   |
 | `git rebase -i HEAD~3`  | Interactive rebase last 3 commits |
 ## Checklist Before Committing
 - [ ] Markdown changes pass: `npx oxfmt --check .`
 - [ ] Commit message follows 50/72 rule
 - [ ] Conventional commit type used
 - [ ] Co-author trailer for every contributing agent or model
 - [ ] No em dashes
 - [ ] No large unchanged regions reformatted
 - [ ] No speculative code or unused imports
@@ -0,0 +1,254 @@
 # Conventional Commits 1.0.0
 A specification for adding human and machine readable meaning to commit
 messages.
 - Source: <https://www.conventionalcommits.org/en/v1.0.0/>
 - License: Creative Commons - CC BY 3.0
 ## Summary
 The Conventional Commits specification is a lightweight convention on top of
 commit messages. It provides an easy set of rules for creating an explicit
 commit history; which makes it easier to write automated tools on top of. This
 convention dovetails with SemVer, by describing the features, fixes, and
 breaking changes made in commit messages.
 The commit message should be structured as follows:
 ```text
 <type>[optional scope]: <description>
 [optional body]
 [optional footer(s)]
 ```
 The commit contains the following structural elements, to communicate intent to
 the consumers of your library:
 - `fix`: a commit of the type fix patches a bug in your codebase (this
  correlates with PATCH in Semantic Versioning).
 - `feat`: a commit of the type feat introduces a new feature to the codebase
  (this correlates with MINOR in Semantic Versioning).
 - `BREAKING CHANGE`: a commit that has a footer `BREAKING CHANGE:`, or appends a
  `!` after the type/scope, introduces a breaking API change (correlating with
  MAJOR in Semantic Versioning). A BREAKING CHANGE can be part of commits of any
  type.
 - Types other than `fix:` and `feat:` are allowed. For example,
  @commitlint/config-conventional (based on the Angular convention) recommends
  `build:`, `chore:`, `ci:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`,
  and others.
 - Footers other than `BREAKING CHANGE: <description>` may be provided and follow
  a convention similar to git trailer format.
 Additional types are not mandated by the Conventional Commits specification, and
 have no implicit effect in Semantic Versioning (unless they include a BREAKING
 CHANGE). A scope may be provided to a commit’s type, to provide additional
 contextual information and is contained within parenthesis, e.g.,
 `feat(parser): add ability to parse arrays`.
 ## Examples
 ### Commit message with description and breaking change footer
 ```text
 feat: allow provided config object to extend other configs
 BREAKING CHANGE: `extends` key in config file is now used for extending other config files
 ```
 ### Commit message with ! to draw attention to breaking change
 ```text
 feat!: send an email to the customer when a product is shipped
 ```
 ### Commit message with scope and ! to draw attention to breaking change
 ```text
 feat(api)!: send an email to the customer when a product is shipped
 ```
 ### Commit message with both ! and BREAKING CHANGE footer
 ```text
 feat!: drop support for Node 6
 BREAKING CHANGE: use JavaScript features not available in Node 6.
 ```
 ### Commit message with no body
 ```text
 docs: correct spelling of CHANGELOG
 ```
 ### Commit message with scope
 ```text
 feat(lang): add Polish language
 ```
 ### Commit message with multi-paragraph body and multiple footers
 ```text
 fix: prevent racing of requests
 Introduce a request id and a reference to latest request. Dismiss
 incoming responses other than from latest request.
 Remove timeouts which were used to mitigate the racing issue but are
 obsolete now.
 Reviewed-by: Z
 Refs: #123
 ```
 ## Specification
 The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”,
 “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be
 interpreted as described in RFC 2119.
 - Commits MUST be prefixed with a type, which consists of a noun, `feat`, `fix`,
  etc., followed by the OPTIONAL scope, OPTIONAL `!`, and REQUIRED terminal
  colon and space.
 - The type `feat` MUST be used when a commit adds a new feature to your
  application or library.
 - The type `fix` MUST be used when a commit represents a bug fix for your
  application.
 - A scope MAY be provided after a type. A scope MUST consist of a noun
  describing a section of the codebase surrounded by parenthesis, e.g.,
  `fix(parser):`.
 - A description MUST immediately follow the colon and space after the type/scope
  prefix. The description is a short summary of the code changes, e.g.,
  `fix: array parsing issue when multiple spaces were contained in string`.
 - A longer commit body MAY be provided after the short description, providing
  additional contextual information about the code changes. The body MUST begin
  one blank line after the description.
 - A commit body is free-form and MAY consist of any number of newline separated
  paragraphs.
 - One or more footers MAY be provided one blank line after the body. Each footer
  MUST consist of a word token, followed by either a `:<space>` or `<space>#`
  separator, followed by a string value (this is inspired by the git trailer
  convention).
 - A footer’s token MUST use `-` in place of whitespace characters, e.g.,
  `Acked-by` (this helps differentiate the footer section from a multi-paragraph
  body). An exception is made for BREAKING CHANGE, which MAY also be used as a
  token.
 - A footer’s value MAY contain spaces and newlines, and parsing MUST terminate
  when the next valid footer token/separator pair is observed.
 - Breaking changes MUST be indicated in the type/scope prefix of a commit, or as
  an entry in the footer.
 - If included as a footer, a breaking change MUST consist of the uppercase text
  BREAKING CHANGE, followed by a colon, space, and description, e.g.,
  `BREAKING CHANGE: environment variables now take precedence over config files`.
 - If included in the type/scope prefix, breaking changes MUST be indicated by a
  `!` immediately before the `:`. If `!` is used, BREAKING CHANGE MAY be omitted
  from the footer section, and the commit description SHALL be used to describe
  the breaking change.
 - Types other than feat and fix MAY be used in your commit messages, e.g.,
  `docs: update ref docs`.
 - The units of information that make up Conventional Commits MUST NOT be treated
  as case-sensitive by implementors, with the exception of BREAKING CHANGE which
  MUST be uppercase.
 - BREAKING-CHANGE MUST be synonymous with BREAKING CHANGE, when used as a token
  in a footer.
 ## Why Use Conventional Commits
 - Automatically generating CHANGELOGs.
 - Automatically determining a semantic version bump (based on the types of
  commits landed).
 - Communicating the nature of changes to teammates, the public, and other
  stakeholders.
 - Triggering build and publish processes.
 - Making it easier for people to contribute to your projects, by allowing them
  to explore a more structured commit history.
 ## FAQ
 ### How should I deal with commit messages in the initial development phase?
 We recommend that you proceed as if you’ve already released the product.
 Typically somebody, even if it’s your fellow software developers, is using your
 software. They’ll want to know what’s fixed, what breaks etc.
 ### Are the types in the commit title uppercase or lowercase?
 Any casing may be used, but it’s best to be consistent.
 ### What do I do if the commit conforms to more than one of the commit types?
 Go back and make multiple commits whenever possible. Part of the benefit of
 Conventional Commits is its ability to drive us to make more organized commits
 and PRs.
 ### Doesn’t this discourage rapid development and fast iteration?
 It discourages moving fast in a disorganized way. It helps you be able to move
 fast long term across multiple projects with varied contributors.
 ### Might Conventional Commits lead developers to limit the type of commits
 they make because they’ll be thinking in the types provided?
 Conventional Commits encourages us to make more of certain types of commits such
 as fixes. Other than that, the flexibility of Conventional Commits allows your
 team to come up with their own types and change those types over time.
 ### How does this relate to SemVer?
 fix type commits should be translated to PATCH releases. feat type commits
 should be translated to MINOR releases. Commits with BREAKING CHANGE in the
 commits, regardless of type, should be translated to MAJOR releases.
 ### How should I version my extensions to the Conventional Commits
 Specification, e.g., @jameswomack/conventional-commit-spec?
 We recommend using SemVer to release your own extensions to the specification
 (and encourage you to make these extensions!).
 ### What do I do if I accidentally use the wrong commit type?
 When you used a type that’s of the spec but not the correct type, e.g., `fix`
 instead of `feat`: prior to merging or releasing the mistake, we recommend using
 `git rebase -i` to edit the commit history. After release, the cleanup will be
 different according to what tools and processes you use.
 When you used a type not of the spec, e.g., `feet` instead of `feat`: in a worst
 case scenario, it’s not the end of the world if a commit lands that does not
 meet the Conventional Commits specification. It simply means that commit will be
 missed by tools that are based on the spec.
 ### Do all my contributors need to use the Conventional Commits specification?
 No! If you use a squash based workflow on Git, lead maintainers can clean up the
 commit messages as they’re merged, adding no workload to casual committers. A
 common workflow for this is to have your git system automatically squash commits
 from a pull request and present a form for the lead maintainer to enter the
 proper git commit message for the merge.
 ### How does Conventional Commits handle revert commits?
 Reverting code can be complicated: are you reverting multiple commits? if you
 revert a feature, should the next release instead be a patch?
 Conventional Commits does not make an explicit effort to define revert behavior.
 Instead we leave it to tooling authors to use the flexibility of types and
 footers to develop their logic for handling reverts.
 One recommendation is to use the `revert` type, and a footer that references the
 commit SHAs that are being reverted:
 ```text
 revert: let us never again speak of the noodle incident
 Refs: 676104e, a215868
 ```
 ## License
 Creative Commons - CC BY 3.0
@@ -0,0 +1,10 @@
 # Build
 build/
 out/
 *.o
 *.obj
 *.exe
 # OS / editor
 .DS_Store
 Thumbs.db
@@ -0,0 +1,12 @@
 {
  "ignorePatterns": ["node_modules", "dist", ".git"],
  "overrides": [
    {
      "files": ["*.md"],
      "options": {
        "printWidth": 80,
        "proseWrap": "always"
      }
    }
  ]
 }
@@ -0,0 +1,177 @@
 # 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
 No build system is set up yet. When one is added for the course examples,
 document its configure, build, and test commands here.
 ## 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
  .oxfmtrc.json     # oxfmt config
  .agents/          # Agent skills (git workflow)
 ```
 Course content (lectures, exercises, examples) will be added as the course is
 developed. Document the layout here when it takes shape.
 ## 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.