Add the fvtk Claude Code plugin (#139)

Author: banesullivan

.claude/CLAUDE.md

@@ -0,0 +1,107 @@
+# fvtk: Claude Code guide
+
+fvtk is a trimmed, fast fork of VTK 9.6.2, maintained by the PyVista community as a
+drop-in graphics layer for [PyVista](https://github.com/pyvista/pyvista). It is public,
+BSD-3 licensed, and developed in the open at `pyvista/fvtk`. Read `README.md` for the
+public story and `CONTRIBUTING.md` for the rules of engagement.
+
+This file is the always-on context for working in this repo. The skills and commands under
+`.claude/` encode the recurring maintenance jobs.
+
+## The prime directive: parity
+
+fvtk is a **bit-exact drop-in for stock VTK 9.6.2 by default** (`maxULP = 0`). Every change
+falls into one of two buckets:
+
+1. **Byte-identical → ships on by default.** Must pass `tests/bitexact/` at `maxULP = 0`,
+   including thread-count determinism for anything threaded.
+2. **Correct but reorders output → opt-in behind `fvtk.EnableFast()`.** Relaxed-order parity
+   gate plus an engagement check proving the fast path ran.
+
+Positions and values are sacred. Only emission order is ever negotiable. Backported upstream
+bug fixes are the one deliberate exception: they intentionally diverge from stock 9.6.2 to fix
+a real defect, and must be recorded as such. See the `parity-contract` skill before touching
+any filter, kernel, or render path.
+
+## Repo map
+
+- `fvtk-config/`: the build profiles and the trim lists (`_modules_minimal.cmake`,
+  `_nowrap_classes.cmake`, `_nocompile_classes.cmake`). See the `module-trimming` skill.
+- `ci/`: build and validation scripts (`build-fvtk.sh` entry, `run-bitexact.sh`,
+  `run-renderexact.sh`, `run-regression.sh`, `run-pyvista.sh`, `build-sdk.sh`) and the
+  cibuildwheel backend under `ci/cibw/`.
+- `tests/bitexact/`: the byte-exact gate. `tests/renderexact/`: pixel-exact render gate.
+  `tests/regression/`: fvtk's own regression scenes. `tests/pyvista/`: the PyVista parity
+  suite and its pinned ref (lands with PR #112).
+- `docs/`: `build-internals.md` (the lever set and parity gates, read this first for build
+  work), `versioning.md`, `abi3-feasibility.md`, `threading-bitexact.md`, `ci-closers.md`,
+  `ci-runners.md`.
+- `tools/`: `pgo-train.py`, `fvtk_shim.py` (the `vtkmodules` → `fvtk` import redirect used by
+  every parity harness).
+- The module trees (`Common/`, `Filters/`, `Rendering/`, `IO/`, …) are the forked VTK source.
+
+## Build and validate
+
+The build runs inside `nix-shell` (pinned cmake 4.1.2, Python 3.13, GL/EGL/OSMesa). Entry:
+
+```bash
+./build-fvtk.sh                 # default profile (minimal), LTO on
+PROFILE=fast ./build-fvtk.sh    # fast iteration, LTO off
+```
+
+Validation gates (also run in CI):
+
+```bash
+ci/run-bitexact.sh      # byte-exact vs stock vtk==9.6.2 (maxULP=0)
+ci/run-renderexact.sh   # pixel-exact offscreen render (EGL/Mesa)
+ci/run-regression.sh    # fvtk's regression scenes
+ci/run-pyvista.sh       # PyVista's own suite against the built wheel (PR #112)
+```
+
+The parity harnesses install stock `vtk==9.6.2` and the fvtk wheel on separate venvs and
+redirect `vtkmodules` → `fvtk` via `tools/fvtk_shim.py`. Never install stock `vtk` into the
+fvtk venv. Details and env vars are in `tests/bitexact/README.md` and the `parity-contract`
+skill.
+
+## Contribution workflow
+
+- Branch from `main`; **never push to `main`**. Every change lands through a pull request.
+- One logical change per PR. Backports are one MR per PR (see the `backport-vtk` skill).
+- State which parity bucket the change is in, with its evidence, in the PR body.
+- CI on `main` is always green. A red branch is the branch's fault; do not wave it off as
+  flaky. Run the relevant gate locally before pushing. If main's CI is genuinely failing
+  that is an issue that needs to be rectified immediately.
+
+## Commits and PRs
+
+- **Single-line commit messages**, matching the conventional-commit style already in the
+  history: `fix(opengl): …`, `perf(SMP): …`, `test(bitexact): …`, `ci: …`, `docs: …`,
+  `chore: …`, `build: …`. Pick the scope from the touched area.
+- Never `git add -A` or `git add .`; stage explicit paths by name.
+- Never `--amend` a pushed commit, never use a HEREDOC commit body.
+- **No additional attribution anywhere**: no `Co-Authored-By: Claude`,
+  `🤖 Generated with…`, `noreply@anthropic.com`, or `[Claude Code]` in commits, PR bodies,
+  PR/issue comments, or release notes.
+
+## Scope discipline
+
+fvtk is a community fork for PyVista, and every public artifact stays framed that way: it
+exists to give PyVista a graphics layer that is tested, fast, and released on a community
+cadence. Keep rationale in commits, PRs, issues, and docs anchored to PyVista and scientific
+visualization. Do not reference, name, or speculate about specific downstream commercial users
+or private infrastructure in anything that lands in this repo or on GitHub. When a motivation
+would only make sense by pointing at a particular downstream consumer, frame it generically
+("for large-scale visualization workloads") instead. When unsure, ask.
+
+## Skills and commands
+
+- `/backport-vtk`: sweep recently merged upstream VTK merge requests, triage the ones that
+  matter to fvtk's shipped modules, and land each as its own PR linked back to the MR.
+- `/pyvista-bump`: advance the pinned PyVista ref and triage the parity suite (real
+  regression vs image-cache drift).
+- `/fvtk-release`: cut an fvtk release (tag-driven publish to PyPI for the wheel and SDK).
+- `/triage-ci`: diagnose a failing CI run or PR check and propose the fix.
+- `parity-contract` (skill): the bit-exact contract, the gates, and the fast-filter checklist.
+- `module-trimming` (skill): the three trim levers and how to add, remove, or restore classes.
+- `vtk-backport-engineer` (agent): lands a single backport end to end; driven by
+  `/backport-vtk`.

.claude/agents/vtk-backport-engineer.md

@@ -0,0 +1,54 @@
+---
+name: vtk-backport-engineer
+description: Lands a single upstream VTK merge request as one fvtk PR, linked back to the MR. Spawned by the backport-vtk skill (usually several in parallel, one per MR). Given an MR iid, title, web_url, and changed-file list, it branches, ports the diff to the 9.6.2 tree, handles the parity story, validates, and opens the PR.
+tools: Glob, Grep, Read, Edit, Write, Bash
+model: sonnet
+color: blue
+---
+
+You land exactly one upstream VTK merge request as one fvtk pull request. You are given the MR
+iid, title, web_url, and changed-file list. Read `.claude/skills/backport-vtk/SKILL.md`,
+`.claude/skills/backport-vtk/references/upstream-api.md`, `.claude/skills/parity-contract/SKILL.md`,
+and `.claude/CLAUDE.md` first. Stay within this one MR; do not sweep or triage others.
+
+## Context you must hold
+
+- fvtk is frozen on VTK 9.6.2 and has **no shared git history** with upstream, so `git
+  cherry-pick` is impossible. You apply the MR's diff and adapt it to the 9.6.2 tree by hand
+  where context has drifted.
+- fvtk's default build is a bit-exact drop-in for stock 9.6.2. A behavioral fix is a deliberate
+  divergence and must be recorded; a degenerate-input guard usually leaves valid output
+  unchanged.
+- This is a public, community-facing repo. Keep all prose framed around PyVista and VTK. No
+  AI attribution. No reference to downstream commercial users or private infrastructure.
+
+## Procedure
+
+1. Branch `backport/vtk-mr-<iid>-<short-slug>` from `main`.
+2. Fetch the MR diff (`https://gitlab.kitware.com/vtk/vtk/-/merge_requests/<iid>.diff`). Try
+   `git apply --3way --whitespace=nowarn`. For rejected hunks, open the file and port the change
+   by hand, reading the diff and the MR description for intent. Keep the change minimal and
+   matched to surrounding VTK style. Do not pull in unrelated upstream churn.
+3. Parity story:
+   - Behavioral fix (changes valid-input output): update the affected `tests/bitexact/` op to
+     the corrected expectation and note the divergence in the divergence ledger /
+     `tests/precision_audit.md`.
+   - Degenerate-input guard (crash/nullptr on bad input): add a regression test for the
+     degenerate case; valid-input output stays byte-exact.
+4. Build with `PROFILE=fast ./build-fvtk.sh` and run the relevant gate
+   (`ci/run-bitexact.sh` / `ci/run-renderexact.sh` / `ci/run-regression.sh`) to prove the fix
+   and the parity outcome. If you cannot build in this environment, say so plainly and leave the
+   PR as a draft with the gate steps listed; do not claim a gate passed that you did not run.
+5. Stage explicit paths, single-line conventional commit (`fix(<scope>): …`), no `git add -A`,
+   no AI attribution.
+6. Open the PR. The body must:
+   - link the MR: `Backports https://gitlab.kitware.com/vtk/vtk/-/merge_requests/<iid>`
+   - describe the upstream defect in fvtk's own words
+   - state the parity bucket and attach the gate evidence
+   - pass the prose-hygiene rules in `.claude/CLAUDE.md` (no em dashes, no triads, no promo
+     vocab, straight quotes, absolute dates)
+7. Report the PR number, the parity outcome, and whether any gate could not be run here.
+
+If the diff turns out to touch only trimmed modules, or the change does not actually apply to
+the 9.6.2 tree in a meaningful way, stop and report that the MR should be skipped rather than
+forcing a PR.

.claude/commands/fvtk-release.md

@@ -0,0 +1,60 @@
+---
+description: Cut an fvtk release — pick the next 9.6.2.N segment, draft release notes from merged PRs, create the GitHub Release that tag-fires trusted publishing for the fvtk wheel and fvtk-sdk.
+argument-hint: "[next | 9.6.2.N | rc]"
+allowed-tools: Read, Bash, Grep, Glob
+---
+
+Cut an fvtk release. The full scheme is `docs/versioning.md`; this is the operational runbook.
+fvtk publishes two PyPI projects in lockstep: `fvtk` (runtime wheel, via `ci.yml`, environment
+`pypi`) and `fvtk-sdk` (headers + CMake config, via `sdk.yml`, environment `pypi-sdk`). Both use
+OIDC trusted publishing — no stored tokens.
+
+Argument: `next` (default, increment the last segment), an explicit `9.6.2.N`, or `rc` for a
+pre-release (`9.6.2.Nrc1`).
+
+## The scheme
+
+Version is `9.6.2.N`: the frozen VTK base `9.6.2` plus the fvtk iteration `N`. The version is
+**tag-driven** through `setuptools_scm` — there is no version file to edit. A bare `9.6.2` tag is
+reserved for an unmodified byte-exact build; fork releases always carry `.N`. Publishing is gated
+on a **published GitHub Release**, not a bare `git push --tags`.
+
+## Steps
+
+1. **Confirm `main` is green.** `gh run list --branch main --limit 5`. Do not release off a red
+   `main`. Confirm you are releasing the intended commit.
+2. **Pick `N`.** List existing tags (`git tag`), find the last published `9.6.2.K`, and take
+   `9.6.2.{K+1}` (or the explicit argument). For a pre-release, `9.6.2.{K+1}rc1`.
+3. **Draft release notes** from the merged PRs since the last release tag:
+   `gh pr list --state merged --base main --search "merged:>=<last-release-date>"`. Group by
+   conventional-commit scope (perf, fix, build, ci, test, docs). Lead with parity-relevant
+   changes (new default-on optimizations, new opt-in fast filters, backported upstream fixes —
+   link their MRs). Run the notes through the prose-hygiene rules in `.claude/CLAUDE.md`: no em
+   dashes, no triads, no promo vocab, straight quotes, absolute dates, no AI attribution.
+4. **Create the GitHub Release** with the tag `9.6.2.N` targeting the chosen commit. Mark `rc`
+   tags as pre-release. This is the single action that triggers publishing; only run it once the
+   notes are reviewed.
+
+   ```bash
+   gh release create 9.6.2.N --target <sha> --title "fvtk 9.6.2.N" --notes-file <notes> [--prerelease]
+   ```
+5. **Watch the release workflows.** Publishing the Release fires `ci.yml` (builds the shipped
+   LTO abi3 Linux + macOS + Windows wheels, runs the bit-exact and pixel-exact gates, then the
+   `publish` job to PyPI `pypi`) and `sdk.yml` (`publish-sdk` to `pypi-sdk`). Watch both:
+   `gh run watch`. If a gate fails, the publish does not run — fix forward and re-release; do not
+   hand-upload.
+6. **Verify** both projects landed at the same version: `pip index versions fvtk` and
+   `pip index versions fvtk-sdk` (or check the PyPI project pages). Pin `fvtk` and `fvtk-sdk`
+   together.
+
+## First-release note
+
+The first time either project publishes (before it exists on PyPI), a **pending** trusted
+publisher must be registered on PyPI first: `fvtk` → workflow `ci.yml`, environment `pypi`;
+`fvtk-sdk` → workflow `sdk.yml`, environment `pypi-sdk`. Without it the publish job fails auth.
+
+## Rebasing onto a new VTK
+
+Out of scope for a normal release. When fvtk moves to a new upstream VTK, bump
+`VTK_BASE_VERSION` in `ci/cibw/fvtk_backend.py` and the base in `pyproject.toml`, then restart at
+`9.7.0.0`. See `docs/versioning.md`.

.claude/commands/pyvista-bump.md

@@ -0,0 +1,58 @@
+---
+description: Advance the pinned PyVista ref and triage the parity suite — separate real fvtk regressions (fix them) from image-cache drift (deselect them).
+argument-hint: "[pyvista-sha-or-tag | latest]"
+allowed-tools: Read, Edit, Bash, Grep, Glob
+---
+
+Bump the PyVista pin fvtk tests against, run the parity suite, and triage the result. The suite
+and its machinery land with PR #112 (`tests/pyvista/`, `ci/run-pyvista.sh`,
+`.github/workflows/pyvista-bump.yml`). If `tests/pyvista/` is absent, #112 has not merged yet —
+say so and stop.
+
+Argument: a PyVista SHA or tag to pin, or `latest` (default) to take the current tip of
+PyVista `main`.
+
+## What the suite is
+
+- `tests/pyvista/PYVISTA_REF` — the pinned PyVista commit. The only thing a bump edits.
+- `ci/run-pyvista.sh` — clones PyVista at the pin, installs it `--no-deps` over the built fvtk
+  wheel with the `vtkmodules` → `fvtk` redirect, runs core + plotting offscreen under Xvfb +
+  Mesa llvmpipe (software GLX, matching PyVista's own CI). Stock `vtk` is never installed, so an
+  un-redirected import fails loud.
+- `tests/pyvista/deselect.txt` — the triage surface for image-cache drift. `needs_download`
+  (network) and snake_case opt-out tests are handled automatically and stay out of it.
+- The CI job runs on the merge queue, `workflow_dispatch`, and the `pyvista-full` PR label.
+  `pyvista-bump.yml` opens the weekly bump PR automatically; this command is the manual path and
+  the triage helper.
+
+## Steps
+
+1. Confirm `tests/pyvista/` exists. Read the current `tests/pyvista/PYVISTA_REF` and
+   `tests/pyvista/README.md`.
+2. Resolve the target ref. For `latest`, get the current `main` tip:
+   `gh api repos/pyvista/pyvista/commits/main --jq .sha`. Show the old → new ref and the
+   compare URL.
+3. Edit `tests/pyvista/PYVISTA_REF` to the new ref.
+4. Run the suite against a built fvtk wheel: `ci/run-pyvista.sh <wheel-dir>` locally if a wheel
+   and the Xvfb + Mesa stack are available, otherwise dispatch CI on the branch with
+   `gh workflow run ci.yml --ref <branch>` (or push the branch and apply the `pyvista-full`
+   label, or just change `PYVISTA_REF`/`deselect.txt` — the `changes` detector triggers the
+   gate) and watch it with `gh run watch`.
+5. **Triage every failure. This is the real work — distinguish two kinds:**
+   - **Image-cache drift** — a plotting test whose rendered image differs from PyVista's
+     committed baseline because of a benign rendering difference, not a parity break. These go in
+     `tests/pyvista/deselect.txt` with a one-line reason. Only deselect drift; never use it to
+     hide a real regression.
+   - **Real fvtk regression** — a parity break, a crash, a wrong numerical result, an import
+     that should have redirected but did not. **Do not deselect these.** Reproduce against the
+     bitexact / renderexact gate, find the fvtk cause, and fix it (or file it and leave the pin
+     unbumped). A real regression means fvtk diverged from the contract, which is the whole point
+     of the gate.
+6. Re-run until green (real fixes applied, drift deselected with reasons).
+7. Open the bump PR: title `test(pyvista): bump pin to <short-sha>`, body stating the old → new
+   ref, the compare link, what was deselected and why, and any fvtk fix that rode along. Follow
+   the commit and prose rules in `.claude/CLAUDE.md`. Do not push to `main`.
+
+If a failure is ambiguous (could be drift or a subtle regression), reproduce it through the
+bitexact or renderexact gate before deciding. When still unsure, leave it failing and surface it
+rather than deselecting.

.claude/commands/triage-ci.md

@@ -0,0 +1,72 @@
+---
+description: Diagnose a failing fvtk CI run or PR check — fetch the failing job logs, classify the failure against the known gates, and propose or apply the fix.
+argument-hint: "[PR# | run-id | branch]"
+allowed-tools: Read, Bash, Grep, Glob, Edit
+---
+
+Diagnose a failing CI run and get to the fix. The gate layout is in `docs/ci-closers.md` and
+`docs/ci-runners.md`; this command maps a red check to its cause.
+
+Argument: a PR number, a run id, or a branch. Default to the current branch's latest run.
+
+## Pull the failure
+
+```bash
+gh pr checks <PR#>                       # which checks are red
+gh run list --branch <branch> --limit 5
+gh run view <run-id> --log-failed        # the failing job's log tail
+```
+
+Read the failing job's log, not just its name. Identify which gate failed and the first real
+error (not the cascade after it).
+
+## Classify against the gates
+
+`ci.yml` runs these job groups. Match the red one:
+
+- **build (Linux / macOS / Windows cibuildwheel)** — compile, link, codegen, wheel-repair, or
+  smoke failure. Common causes: a missing class a kept path references (a trim closure broke —
+  see the `module-trimming` skill), a configure-time module cascade, a platform-specific compile
+  error (MSVC vcvars, AppleClang), an `abi3` / `python3.lib` link issue on Windows. The smoke
+  step (`ci/smoke_test.py` / `smoke_min.py`) failing means the wheel imports or renders wrong.
+
+- **bitexact** — output diverged from stock VTK 9.6.2 (`maxULP > 0`). This is a **parity
+  break**. A change that was meant to be byte-identical is not. Either make it byte-identical
+  again, move it behind `fvtk.EnableFast()` as a Bucket-2 opt-in, or — if it is an intentional
+  backport divergence — update the affected op and record it in the divergence ledger. See the
+  `parity-contract` skill. Never relax the comparison to make it pass.
+
+- **renderexact** — offscreen RGBA+Z framebuffer diverged. A render-path change broke pixel
+  exactness. Reproduce with `ci/run-renderexact.sh` under software EGL; treat like a bitexact
+  break.
+
+- **regression** — an fvtk regression scene failed. Read the specific test; it usually points at
+  a concrete filter or render behavior.
+
+- **pyvista** (PR #112, merge-queue / `pyvista-full` label) — PyVista's own suite failed against
+  the built wheel. Split image-cache drift from a real fvtk regression exactly as the
+  `/pyvista-bump` command describes. Real regression → fix in fvtk; drift → `deselect.txt` with a
+  reason. Never deselect a real regression.
+
+- **\*-lto legs** (main only) — the shipped LTO+ICF config failed to build or validate. The
+  fast-O2 PR build passed but the LTO build did not. Usually an LTO/ICF-sensitive construct or a
+  link-time issue; check the LTO build log specifically.
+
+- **sdk / sdk-gate** — the `fvtk-sdk` build or its external-project consumer test failed (the SDK
+  ships headers + CMake config + import libs). Check `ci/build-sdk.sh` / `ci/test-sdk.sh` and the
+  per-platform link setup (Windows `python3.lib`, macOS).
+
+- **publish** (release only) — runs only on a published GitHub Release; a failure here is
+  trusted-publisher / environment config, not code. See `/fvtk-release`.
+
+## Reproduce, then fix
+
+Reproduce locally before changing anything: `PROFILE=fast ./build-fvtk.sh` plus the matching
+gate script (`ci/run-bitexact.sh`, `ci/run-renderexact.sh`, `ci/run-regression.sh`,
+`ci/run-pyvista.sh`). A gate that fails in CI but not locally is usually environment (runner
+arch, Mesa version, contention), not flakiness — `docs/ci-runners.md` covers the runner matrix.
+CI on `main` is always green; a red branch is the branch's fault.
+
+Propose the fix with its root cause and the gate evidence. Apply it only on a branch, follow the
+commit and prose rules in `.claude/CLAUDE.md`, and re-run the failed gate to confirm before
+handing back.