From a13105a591b87fcb94c6c214d3878264dc0872f0 Mon Sep 17 00:00:00 2001
From: portersky <24420859+portersky@users.noreply.github.com>
Date: Tue, 5 May 2026 21:30:57 +0200
Subject: [PATCH] docs: add coding and shell conventions to AGENTS.md

- Add include ordering rules: C++ std, C std, OS-specific,
  third-party, local headers (separated by blank lines)
- Clarify <> for system headers, "" for third-party deps
- Remove .exe from run command
- Mark shell code blocks as sh (POSIX compliant)
- Add shell script conventions section
---
 AGENTS.md | 24 ++++++++++++++++++++++--
 1 file changed, 22 insertions(+), 2 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 62fef8e..7ad740b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -12,10 +12,10 @@
 
 ### Commands
 
-  ```bash
+  ```sh
   cmake -S . -B build -GNinja
   ninja -C build
-  ./build/cuber.exe
+  ./build/cuber
   ```
 
 ### Dependencies
@@ -42,6 +42,26 @@ to the custom scripts instead of system-installed packages.
 - **4-space indentation**
 - **No semicolons after closing braces** for namespaces/classes
 - `auto` for obvious types (e.g. `auto main(...) -> int`)
+- `<>` includes only for system headers (std, OS, etc.)
+- `""` includes for third-party dependencies (e.g. `fmt`, `nlohmann/json`)
+- 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
 
 ## Source Layout