Add Gpu Backend

---
name: add-gpu-backend
description: Scaffold a complete new GPU backend (hip, rocm, metal, opencl, etc.) with runtime, feature kernel stubs, public header, Meson options, CI workflow, doc stub, and smoke test. Flagship scaffolding skill. Established precedents on the fork — CUDA (legacy), SYCL (legacy), Vulkan (T5-1, ADR-0175 scaffold + ADR-0186 image-import).
---

<!-- markdownlint-disable MD013 MD033 MD060 -->

# /add-gpu-backend

Creates fully-wired new GPU backend directory tree + build integration.
Generated code compiles as stub (empty kernels, zero scores) — keeps
CI/build pipeline green while implementation fills in incrementally.

Vulkan (T5-1) scaffold = canonical recent precedent — copy its structure
for new backends. See
[ADR-0175](../../../docs/adr/0175-vulkan-backend-scaffold.md) for scaffold
shape; [ADR-0186](../../../docs/adr/0186-vulkan-image-import-impl.md) for
ffmpeg-patches contract any new backend with image-import support inherits.

## Invocation

```text
/add-gpu-backend <name>
```

`<name>` is lowercase, e.g. `vulkan`, `hip`, `metal`, `opencl`, `rocm`.

## Files created

| Path                                                         | Purpose                              |
|--------------------------------------------------------------|--------------------------------------|
| `core/src/<name>/common.{c,h}`                            | Context/device selection             |
| `core/src/<name>/picture_<name>.{c,h}`                    | Picture allocation/lifecycle         |
| `core/src/<name>/<name>_types.h`                          | Backend-local types                  |
| `core/src/feature/<name>/integer_adm_<name>.{c,h}`        | ADM kernel stub                      |
| `core/src/feature/<name>/integer_vif_<name>.{c,h}`        | VIF kernel stub                      |
| `core/src/feature/<name>/integer_motion_<name>.{c,h}`     | Motion kernel stub                   |
| `core/include/libvmaf/libvmaf_<name>.h`                   | Public header (fetch pic, device sel)|
| `core/test/test_<name>_smoke.c`                           | Build + init + single-frame test     |
| `docs/<name>/README.md`                                      | Backend doc stub (build, caveats)    |
| `.github/workflows/<name>.yml` (or libvmaf-build-matrix.yml row) | CI job                           |

## Files patched

- `core/meson_options.txt` — new `enable_<name>` feature flag.
- `core/meson.build` — conditional subdir + dependency declaration.
- `core/src/meson.build` — feature sources + link.
- `core/src/libvmaf.c` — backend dispatch entry.
- `core/src/feature/feature_extractor.c` — registry add.
- `CLAUDE.md` + `AGENTS.md` — mention new backend in §1 "what this repo is".
- `docs/principles.md` — if backend requires rule relaxation, PR-specific
  note (otherwise untouched).

## Templates

Located under `.claude/skills/add-gpu-backend/templates/` (not created by
skill — authored by hand once per candidate backend). Expected templates:

- `templates/vulkan/` — VkInstance, VkDevice, compute queue, SPIR-V shader skeleton
  (live; backs T5-1 scaffold in `core/src/vulkan/`).
- `templates/hip/`    — hipInit, HIP kernel skeleton.
- `templates/metal/`  — MTLDevice, MTLCommandQueue, metal shader skeleton.
- `templates/opencl/` — clGetPlatformIDs, kernel skeleton.
- `templates/generic/` — fallback when no template exists: creates minimal no-op
  stubs + CI job.

## Workflow

1. Validate `<name>` = known backend (has template) or fall back to generic.
2. Check no `core/src/<name>/` exists yet; if it does, refuse.
3. Copy template files, substituting `@NAME@`, `@NAME_UPPER@`, and `@COPYRIGHT@`
   (= `Copyright 2026 Lusoris`) placeholders.
4. Apply patches to shared files (search-and-replace-based).
5. Run `/build-vmaf --backend=<name>` to confirm stub compiles.
6. Run `build/test/test_<name>_smoke` to confirm init path works.
7. Open PR checklist comment with:
   - Backend implementation checklist (picture_<name>.c, feature kernels, sanitizer
     clean, ncu/vtune/rocprof profile).
   - CODEOWNERS review required.
   - Required CI checks listed.

## Guardrails

- Never overwrites existing files.
- Never activates backend by default (`enable_<name>` starts `disabled`).
- Never claims bit-exactness until `/cross-backend-diff` confirms ULP ≤ 2.