---
name: google-cpp-header-inclusion
description: "Enforce the strict topological header inclusion layering and reordering rules in Filament. Use this skill when adding or modifying `#include` directives in C++ source or header files."
license: "Apache-2.0"
metadata:
  decimalai-skill-id: "ab939e01-d662-47b3-b90d-a0f5824e4a3b"
  decimalai-version-id: "f31a33c9-2a65-41f9-ab85-ea80b890bb54"
  decimalai-version: "1"
  decimalai-body-sha256: "6f9100ff59b0ff3e04ab1292cd3c23a5a60402fa98c10462c9214e553c6a11df"
  decimalai-name: "google/cpp-header-inclusion"
  decimalai-format: "1"
  decimalai-invocation: "model"
  decimalai-category: "coding"
  decimalai-source: "https://app.decimal.ai/s/google-cpp-header-inclusion@1/SKILL.md"
---
# Dynamic C++ Header Inclusion & Reordering

Filament enforces a strict, acyclic include layering hierarchy to optimize compile times, prevent header pollution, and identify missing dependencies.

## 1. Logical Layer Hierarchy

Includes must be grouped and separated by **exactly one blank line** in the following order (top to bottom):

1.  **Layer 0 (Corresponding Header):** `#include "details/Foo.h"` (isolated at the very top).
2.  **Layer 0.5 (Windows Cleanup):** `#include <utils/unwindows.h>` (always second, only if needed).
3.  **Layer 1 (Private/Local Headers):** `#include "PrivateStuff.h"` (using double quotes `" "` strictly for private local headers located under the local target's `src/` folder).
4.  **Layer 2 (Internal Proprietary Libraries):** Public and private includes for other internal libraries (e.g. `<filaflat/...>`, `<backend/...>`, `<utils/...>`, `<math/...>`). All proprietary library includes **must** use `< >` syntax (including `private/` sub-folders). The layering priority order of these libraries is dynamically computed based on `CMakeLists.txt` target linkages.
5.  **Layer 3 (Third-Party Libraries):** `<tsl/...>`, `<absl/...>`, `<jni.h>`.
6.  **Layer 4 (C++ Standard Library):** `<algorithm>`, `<vector>`, `<cstddef>` (including standard `<c...>` wrappers).
7.  **Layer 5 (POSIX System Headers):** `<unistd.h>`, `<sys/stat.h>` (C system headers below C++ std, but above C std).
8.  **Layer 6 (C Standard Library):** Legacy C system headers ending in `.h` (e.g., `<stdint.h>`, `<stddef.h>`).

---

## 2. Sorting & Spacing Rules for Private Includes (Layer 1)

*   **Flat-First:** Flat/top-level includes (without a subdirectory prefix, e.g., `"Allocators.h"`) are sorted **above** nested subdirectory includes (e.g., `"components/Foo.h"`).
*   **Visual Grouping:** Private includes must be grouped by their first subdirectory path prefix, separated by **exactly one blank line**.

---

## 3. Running the Automated Include Formatter

AI agents **must never manually sort includes** or guess target dependencies. Always run the repository's dynamic topological include formatter after modifying C++ files:

```bash
./tools/reorganize-headers/run.py <file_or_directory>
```

*Note: The tool dynamically parses `CMakeLists.txt` files to topologically sort proprietary libraries and includes preprocessor safety checks to avoid breaking platform-conditional include guards.*