TheRock/rocm-libraries/projects/hipdnn/docs/ai-rules.md

---
alwaysApply: true
---

# AI Rules for hipDNN Project

## Project AI Skills

Reusable AI skills for hipDNN live under `tools/ai/skills/`. The skills below describe what each one does and when to suggest it.

**To use a skill, follow this sequence — do not read `SKILL.md` and execute its steps directly.** That bypasses the install path the skill is meant to be invoked through, and misses the entire point of having skills.

1. **Check whether the skill is loaded in this session.** Look at the available-skills list in the session's system reminder. The skill being present under `tools/ai/skills/` is *not* enough — it's invocable only after it is installed into the active host's skills directory and surfaced in the session's skill list.
2. **If not loaded, ask the user which skill(s) to install and which host/scope.** Use `--codex` for Codex user-global skills (`$CODEX_HOME/skills` when set, otherwise `~/.codex/skills`), `--claude` for Claude user-global skills (`~/.claude/skills`), or `--target <dir>` for an explicit workspace or user scope. Then run one of:
   ```
   python3 tools/ai/install-skills.py --codex <skill-name> [<skill-name> ...]
   python3 tools/ai/install-skills.py --claude <skill-name> [<skill-name> ...]
   python3 tools/ai/install-skills.py --target <target-skills-dir> <skill-name> [<skill-name> ...]
   ```
   Use `python3 tools/ai/install-skills.py --list` to see what's available. If the user names skills, pass them explicitly; if they ask for a full refresh, omit names to install all available skills. The installer copies skills as snapshots, updates stale copies by comparing content hashes, and skips existing symlinks rather than replacing them. After changing committed skill packages, run `python3 tools/ai/validate-skills.py` before offering or installing them.
3. **Invoke via the active host's skill syntax.** In Codex, use `$hipdnn-superbuild`, `$hipdnn-review`, or the other `$skill-name` form. In Claude, use the slash-command adapters such as `/hipdnn-superbuild` or `/hipdnn-review`. The new skill may not appear in the session's skill list until the next message — once it does, invoke it normally.

When a user asks for a workflow covered by a project skill, tell them the project has a matching skill and offer to install and invoke it.

- `tools/ai/skills/pr-summary/SKILL.md`
  - Drafts or revises new or existing pull request titles and bodies with hipDNN's preferred summary, risk, testing, and technical-change format.
  - Suggest this skill when the user asks for PR creation, PR body updates, PR summaries, risk summaries, testing sections, or review-ready PR descriptions.
- `tools/ai/skills/hipdnn-review/SKILL.md`
  - Reviews hipDNN pull requests or local diffs for correctness, public API compatibility, provider behavior, resource ownership, code reuse, and testing coverage/quality.
  - Suggest this skill when the user asks for a hipDNN code review, PR review, merge-readiness assessment, or a focused review of testing quality and coverage.
- `tools/ai/skills/hipdnn-superbuild/SKILL.md`
  - Builds hipDNN together with one or more providers via the repository-root superbuild presets (`hipdnn-providers`, `miopen-provider`, `hipblaslt-provider`, `hip-kernel-provider`, `hipdnn-samples`, etc.), in a single CMake invocation. On Windows it auto-runs the wheel-based ROCm setup when no SDK path is supplied.
  - Suggest this skill when the user asks to build hipDNN with providers, run a superbuild preset, rebuild after a rebase or merge, or set up a fresh build from the repo root. Prefer it over the standalone build whenever providers are involved.
- `tools/ai/skills/hipdnn-superbuild-test/SKILL.md`
  - Runs tests against an existing superbuild with per-component selection (`hipdnn`, `miopen`, `hipblaslt`, `hip-kernel`, `integration-tests`, or `all`), unit/integration scope, optional `--filter=<gtest_pattern>`, `--verbose`, and `--keep-going`. Handles Windows DLL PATH and the `hip-kernel-provider` target naming quirk automatically.
  - Suggest this skill when the user asks to run, filter, or triage tests against a superbuild they have already configured. It does not configure or build — pair it with `$hipdnn-superbuild` in Codex or `/hipdnn-superbuild` in Claude first.

## Commit & PR Conventions

Commit messages and PR titles must follow [Conventional Commits](https://www.conventionalcommits.org/): `type(optional-scope): short description`, where `type` is one of `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, or `revert`. Keep PR titles between 10 and 80 characters, and never include `WIP` or `do not merge`. The Libraries PR Bot gates any PR whose title does not match.

Tracking references (a `JIRA ID :` / `ISSUE ID :` line, a closing keyword such as `Closes #123`, or a plain `#123`) belong in the PR body, not the title; the bot requires one. Use the `pr-summary` skill to draft conforming PR titles and bodies.

## Project Overview & Architecture

hipDNN is a graph-based deep learning library for AMD GPUs with a plugin-based architecture.

### Component Architecture (Do Not Modify Boundaries (linkage))
| Component | Type | Links To | Purpose |
|-----------|------|----------|---------|
| **Backend** (`backend/`) | Shared library (C API) | Data SDK | Core engine, plugin loading, graph execution |
| **Frontend** (`frontend/`) | Header-only C++ | Backend, Data SDK | User-friendly wrapper around backend C API (uses Data SDK for types/logging, not FlatBuffers) |
| **Data SDK** (`data_sdk/`) | Header-only | (none) | Shared data types, logging |
| **FlatBuffers SDK** (`flatbuffers_sdk/`) | Header-only | FlatBuffers, nlohmann_json | FlatBuffer schemas, generated headers, JSON helpers |
| **Plugin SDK** (`plugin_sdk/`) | Header-only | Data SDK | Interfaces for plugin development |
| **Test SDK** (`test_sdk/`) | Header-only | Data SDK | Shared test utilities |

---

## Building & Testing

### Windows Build Environment

On Windows, run `scripts/windows/wheel_build_setup.ps1` to fetch the latest ROCm SDK wheels and set up the build environment:

```powershell
.\scripts\windows\wheel_build_setup.ps1                         # Latest nightlies
.\scripts\windows\wheel_build_setup.ps1 -SHA "<commit-sha>"     # Specific S3 staging build
```

The script creates a Python venv, installs ROCm wheels, initializes the SDK, and prints the CMake variables (`CMAKE_PREFIX_PATH`, `CMAKE_PROGRAM_PATH`) needed for the build.

### Build Approaches

Choose the build approach based on what is being changed:

### 1. hipDNN Only (changes only within `projects/hipdnn/`)

```bash
cd <workspace>/projects/hipdnn
mkdir -p build && cd build
cmake -GNinja ..

ninja              # Build everything
ninja check        # Build and run ALL tests
ninja quick-check  # Build and run the YAML-defined quick category
ninja unit-check   # YAML-defined unit category
ninja integration-check  # YAML-defined integration category
ninja doxygen      # Generate Doxygen docs (output: build/docs/html/)
```

### 2. hipDNN + Providers via Superbuild (recommended when building providers)

Use the superbuild when building hipDNN together with one or more providers. See `docs/Superbuild.md` for full details.

```bash
cd <workspace>
cmake --preset <preset-name>
cmake --build build
```

Available presets (from the repository root `CMakePresets.json`):

| Preset | Components Built |
|--------|-----------------|
| `hipdnn` | hipDNN only |
| `miopen-provider` | hipDNN + miopen-provider |
| `hipblaslt-provider` | hipDNN + hipblaslt-provider |

Or manually specifying components:
```bash
cmake -B build -GNinja -DROCM_LIBS_ENABLE_COMPONENTS="hipdnn;miopen-provider;hipblaslt-provider" .
cmake --build build
```

In the superbuild, targets are prefixed with the project name (e.g., `hipdnn-check`, `hipdnn-quick-check`, `miopen-provider-quick-check`).

### 3. Standalone Provider Build (fallback — provider not in superbuild)

If a provider is not part of the superbuild, build and install hipDNN first, then build the provider with `CMAKE_PREFIX_PATH` pointing to the hipDNN install:

```bash
# Step 1: Build and install hipDNN
cd <workspace>/projects/hipdnn
mkdir -p build && cd build
cmake -GNinja -DCMAKE_INSTALL_PREFIX=<hipdnn-install-path> ..
ninja && ninja install

# Step 2: Build the provider against the hipDNN install
cd <workspace>/dnn-providers/<provider-name>
mkdir -p build && cd build
cmake -GNinja -DCMAKE_PREFIX_PATH=<hipdnn-install-path> ..
ninja
```

### Test Binaries in `build/bin/`
| Binary | Tests | Typical Use |
|--------|-------|-------------|
| `hipdnn_backend_tests` | Backend unit tests | Core backend logic |
| `hipdnn_frontend_tests` | Frontend unit tests | Frontend wrapper logic |
| `hipdnn_data_sdk_tests` | Data SDK unit tests | Flatbuffer objects, utilities |
| `hipdnn_plugin_sdk_tests` | Plugin SDK unit tests | Plugin interface utilities |
| `hipdnn_test_sdk_tests` | Test SDK unit tests | Test utility functions |
| `hipdnn_public_backend_tests` | Backend API tests | Public C API black-box tests |
| `hipdnn_public_frontend_tests` | Frontend integration tests | E2E frontend tests |

### Running Specific Tests
Use `--gtest_filter` for fast iteration:
```bash
./build/bin/hipdnn_backend_tests --gtest_filter="TestBackendDescriptor.*"
```

### When Modifying Code
**Only build or run tests if explicitly requested in the user's prompt.** Do not proactively run `ninja`, `ninja check`, or test binaries unless asked.

When requested to build/test:
1. Rebuild with `ninja` (from build directory)
2. Run relevant tests using `--gtest_filter` for fast iteration

---

## C++ Code Style

### Naming Conventions
- CamelCase for class/struct names (e.g., `BatchNormTestCase`, `SimpleTensorBundle`)
- camelCase for functions, variables, and private members (e.g., `setupEnvironment()`, `tensorData`)
- Underscore prefix for private members (e.g., `_handle`, `_testData`)

### File Headers
- Copyright header on all source files: `// Copyright © Advanced Micro Devices, Inc., or its affiliates.` / `// SPDX-License-Identifier:  MIT`
- `#pragma once` immediately after copyright in header files (.h, .hpp)

### Code Practices
- Use `auto` with casts to avoid type duplication: `auto tensor = static_cast<float*>(data)`
- Use `auto` when initializing variables, unless the type is not obvious
- **Avoid implicit casts** — use explicit `static_cast<>`. The codebase compiles with `-Wconversion` and `-Wsign-conversion`
- Always use braces for if/for/while bodies, even single-line
- Use CMake for managing C/C++ dependencies
- Use Flatbuffers for serialization needs (backend/data_sdk only; frontend uses the backend C API)

### RAII & Resource Management

**All owning raw pointers must be wrapped in RAII (smart pointers) immediately after acquisition.** Never rely on manual `delete` — if an assertion, exception, or early return occurs between allocation and `delete`, the resource leaks. This project runs under AddressSanitizer (ASAN) in CI, and any leak fails the build.

**Common patterns and pitfalls:**

| Pattern | Wrong | Right |
|---------|-------|-------|
| FlatBuffers Graph unpacking (backend/data_sdk) | `auto obj = graph->UnPack();` (raw `GraphT*`) | `auto obj = UnPackGraph(serialized.ptr);` (returns `unique_ptr<GraphT>`) |
| FlatBuffers `UnPack()` (backend/data_sdk) | `auto obj = table->UnPack();` (raw `T*`) | `auto obj = std::unique_ptr<T>(table->UnPack());` |
| `getAttribute()` for tensor arrays | Use raw pointer, forget cleanup | Wrap immediately: `auto owned = std::unique_ptr<HipdnnBackendDescriptor>(rawPtr);` |
| `createDescriptorPtr<T>()` | Store raw pointer | Use `createDescriptor<T>()` which returns `unique_ptr` |

**FlatBuffers `UnPack()` returns owning raw pointers (backend/data_sdk only).** The generated `Graph::UnPack()`, `Node::UnPack()`, etc. all return `T*` allocated with `new`. Prefer the generated helpers like `UnPackGraph()` which return `std::unique_ptr<T>` directly. For types without helpers, wrap manually: `std::unique_ptr<T>(table->UnPack())`.

**`getAttribute()` with `HIPDNN_TYPE_BACKEND_DESCRIPTOR` allocates new descriptors.** The C API packs shared descriptors into fresh `HipdnnBackendDescriptor*` via `packDescriptor()`. Ownership transfers to the caller — wrap in `std::unique_ptr<HipdnnBackendDescriptor>` immediately after retrieval.

### Testing
- Use Google Test (gtest) framework for all C/C++ tests
- Never generate a `main()` function in test files — gtest provides its own
- Use TEST(), TEST_F(), TEST_P(), or TYPED_TEST() macros as appropriate
- **Prefer TYPED_TEST for multi-datatype tests** — when testing across float, half, bfloat16, use TYPED_TEST instead of duplicating test code

#### Test Suite Naming

Rules apply to the TestSuite name (first param of `TEST` / `TEST_F` / `TEST_P`). TestCase (second param) should be PascalCase.

**Composition (left → right):**

1. Required `Test` (unit tests) or `Integration` (integration tests) prefix, always first
2. Optional `Gpu` immediately after `Test`/`Integration` if the test needs GPU support
3. Core Feature / Subject under test (PascalCase, no underscores)
4. Optional Datatype token: `Bfp16`, `Fp16`, `Fp32`

Omit any optional position that does not apply.

**Unit tests**: Mirror the class under test — `TestMyClass` or `TestGpuMyClass` if GPU is required.

**Valid examples:**
```
IntegrationGpuConvolutionPlannerNchwFp32   TestGpuActivationKernelNchwFp32
TestGpuExecutionPlanBuilderFp32            IntegrationGraphFusion
TestConvolutionHeuristicsFp32              TestConvolutionHeuristics
```

#### Choosing Between TYPED_TEST and TEST_P

| Scenario | Approach |
|----------|----------|
| Single type, no params | `TEST()` / `TEST_F()` |
| Single type, with params | `TEST_P()` |
| Multi-type, no params | `TYPED_TEST` |
| Multi-type, with params | `TEST_P` + multi-declarations |

**Key Principle:** Prefer `TEST_P` over `TYPED_TEST` when both type variation and parameterized cases are needed. `TYPED_TEST` and `TEST_P` don't mix well together.

**Multi-declarations**: Use explicit type aliases (`using ConvTestFp32 = ConvTest<float>`) with separate `TEST_P` and `INSTANTIATE_TEST_SUITE_P` per type. Prefer this over macros for debuggability.

**TypePair pattern**: For testing type combinations (e.g., input + compute type), define a `TypePair<T1, T2>` struct with `InputType`/`ComputeType` aliases and use with `TYPED_TEST_SUITE`.

---

## Conditional Guidelines

When modifying public API headers (under `backend/include/`, `frontend/include/hipdnn_frontend/`, `plugin_sdk/include/`), add Doxygen comments (`/** @brief ... */` for classes/functions/files, `///<` for enum values) to any new or changed public API. Exclude `detail/` subdirectories and generated files. For full style details, see `docs/doxygen-guidelines.md`.