ENH: Add Claude Code project scaffolding and developer tooling (#34)

* ENH: Add .claude configuration as part of the repo

* BUG: Address CoPilot and CodeRabbit reviews

**PR:** ENH: Add Claude Code project scaffolding and developer tooling
**Branch:** `claude_agents` -> `main`
**Reviewed:** 2026-03-28
**Comments processed:** 16 (2 PR-level, 14 inline)

| # | File | Line | Reviewer | Decision | Reasoning |
|---|------|------|----------|----------|-----------|
| 1 | *(PR overview)* | — | copilot | SKIPPED | Overview comment only; no actionable change |
| 2 | *(PR overview)* | — | coderabbitai | SKIPPED | Overview comment only; no actionable change |
| 3 | `.pre-commit-config.yaml` | 35 | copilot | APPLIED | Fixed `python` -> `py` per project convention (Windows launcher) |
| 4 | `CLAUDE.md` | 107 | copilot | REJECTED | Suggested `X \| None`; CLAUDE.md explicitly mandates `Optional[X]` (UP007 suppressed) |
| 5 | `AGENTS.md` | 15 | copilot | REJECTED | Same `Optional[X]` rule — project convention is unambiguous |
| 6 | `utils/setup_feature_worktree.py` | 241 | copilot | APPLIED | Fixed missing `f` prefix — `{branch_name}` was printing as a literal string |
| 7 | `utils/setup_feature_worktree.py` | 200 | copilot | REJECTED | Adding `git check-ref-format` validation is beyond stated scope of the script |
| 8 | `utils/setup_feature_worktree.py` | 389 | copilot | REJECTED | Lockfile detection is speculative; current editable-install fallback is intentional design |
| 9 | `.claude/agents/architecture.md` | 12 | coderabbitai | APPLIED | Added `text` language tag to unlabeled code fence (MD040) |
| 10 | `.claude/agents/testing.md` | 22 | coderabbitai | REVISED | `::test_extract_surface` does not exist; replaced with `::TestContourTools` (verified against test file) |
| 11 | `AGENTS.md` | 13 | coderabbitai | REJECTED | Narrowing the `Optional[X]` rule to specific contexts would diverge from CLAUDE.md, which states it universally |
| 12 | `CLAUDE.md` | 55 | coderabbitai | APPLIED | Fixed `python` -> `py` in API map regeneration command |
| 13 | `CLAUDE.md` | 69 | coderabbitai | APPLIED | Fixed stale class name `CompareImages` -> `TestTools` (confirmed by reading `test_tools.py`) |
| 14 | `README.md` | 701 | coderabbitai | APPLIED | Added `text` language tag to 7 unlabeled fenced code blocks (MD040) |
| 15 | `vtk_to_usd/CLAUDE.md` | 10 | coderabbitai | REJECTED | Strict wording is intentional; softening it risks agents bypassing `ConvertVTKToUSD` |
| 16 | `utils/setup_feature_worktree.py` | 242 | coderabbitai | SKIPPED | Duplicate of #6; f-string fix already applied |

- **`.pre-commit-config.yaml`** — `python` -> `py` (Windows launcher consistency)
- **`utils/setup_feature_worktree.py:242`** — added missing `f` prefix to f-string; `{branch_name}` was printing as a literal
- **`.claude/agents/architecture.md`** — added `text` to unlabeled code fence (MD040 lint)
- **`.claude/agents/testing.md`** — replaced nonexistent test node ID `::test_extract_surface` with `::TestContourTools`
- **`CLAUDE.md:55`** — `python` -> `py` in API map regeneration command
- **`CLAUDE.md:69`** — `CompareImages` -> `TestTools` (stale class name)
- **`README.md`** — `text` tag added to 7 unlabeled fenced code blocks

- **`X | None` syntax (×2, copilot + coderabbitai):** CLAUDE.md explicitly mandates `Optional[X]`; ruff UP007 is suppressed project-wide. No exceptions.
- **`git check-ref-format` validation (copilot):** Speculative complexity for a utility script with a clear, narrow scope.
- **Lockfile/pip-upgrade detection (copilot):** The editable-install fallback is a documented intentional design choice, not an oversight.
- **`vtk_to_usd/CLAUDE.md` wording (coderabbitai):** The strict "never call this from outside `ConvertVTKToUSD`" language is a deliberate guardrail; weakening it undermines the purpose of the file.
- **`AGENTS.md` `Optional[X]` scoping (coderabbitai):** The rule is universal by design; scoping it to specific contexts would create ambiguity.

1. **`python` vs `py`** appeared in 3 files; all fixed. This is a recurring slip — the Windows launcher convention should be enforced by pre-commit or linting if it keeps appearing.
2. **`Optional[X]` vs `X | None`** was the dominant reviewer conflict. Both bots flagged it repeatedly. The project rule is clear and was correctly rejected each time, but it may be worth adding a note to `CONTRIBUTING` so external reviewers understand it is intentional.
3. **The f-string bug** (`{branch_name}` missing `f` prefix) was independently caught by both reviewers — a genuine defect. Worth adding a pre-commit check or test for this pattern in utility scripts.
4. **CodeRabbit nitpicks** consistently trended toward adding speculative complexity (lockfile variants, pip upgrade paths, extended validation) that conflicts with CLAUDE.md's explicit instruction to avoid handling impossible or out-of-scope scenarios.

* ENH: tighten agent rules, simplify API map hook, add --since-last-push to review script

- claude_github_reviews: filter by remote reflog cutoff; document py vs venv
- pre-commit: run generate_api_map without bash/git add wrapper
- AGENTS / vtk_to_usd CLAUDE: narrow PhysioMotion4DBase and print() guidance
- Regenerate docs/API_MAP.md

Author: aylward

.claude/agents/architecture.md

@@ -0,0 +1,45 @@
+---
+name: PhysioMotion4D Architecture Agent
+description: Analyzes the PhysioMotion4D codebase and produces numbered design plans with trade-offs. Does not write implementation code. Flags coordinate-system and ITK/PyVista boundary risks.
+tools: Read, Bash, Glob, Grep
+---
+
+You are an architecture agent for PhysioMotion4D. Analyze the codebase and produce
+clear numbered design plans with explicit trade-offs. Do not write implementation code.
+
+## Codebase map
+
+```text
+src/physiomotion4d/
+  physiomotion4d_base.py      — base class with shared logger
+  segment_anatomy_base.py     — abstract segmentation interface
+  segment_chest_*.py          — TotalSegmentator, VISTA-3D, NIM, Ensemble
+  register_images_*.py        — ICON, ANTs, Greedy, time-series wrappers
+  register_models_*.py        — ICP, PCA, distance-map registerers
+  contour_tools.py            — surface extraction from ITK masks
+  convert_vtk_to_usd.py       — high-level VTK→USD (in-memory, PyVista)
+  vtk_to_usd/                 — file-based VTK→USD subpackage
+  usd_tools.py / usd_anatomy_tools.py — USD stage utilities
+  workflow_*.py               — top-level orchestration
+```
+
+Use `docs/API_MAP.md` to locate classes and signatures without manual searching.
+
+## Design invariants to preserve
+
+- `PhysioMotion4DBase` inheritance for all major classes.
+- Segmenters return anatomy group masks with consistent label IDs.
+- Image registerers follow: `set_fixed_image()` → `register(moving)` → dict with transforms.
+- ITK for images; PyVista for surfaces. Boundary is at contour extraction.
+- Coordinate system: RAS internally; Y-up only at USD export.
+
+## Output format — always produce all six sections
+
+1. **Current state** — what exists today, 3–5 bullet points.
+2. **Proposed change** — numbered steps with enough detail to implement.
+3. **Affected files** — every file that will change.
+4. **Trade-offs** — what improves, what gets harder, what breaks.
+5. **Open questions** — decisions that need user input before coding starts.
+6. **Recommended next action** — one sentence.
+
+Flag any change at the ITK↔PyVista boundary or the RAS→Y-up transform as **high-risk**.

.claude/agents/docs.md

@@ -0,0 +1,52 @@
+---
+name: PhysioMotion4D Docs Agent
+description: Updates docstrings, inline comments, and docs/API_MAP.md for PhysioMotion4D. Keeps claims factual, states image shapes explicitly, and does not create new .md files.
+tools: Read, Edit, Bash, Glob, Grep
+---
+
+You are a documentation agent for PhysioMotion4D. Keep docstrings, type annotations,
+and the API map accurate and concise.
+
+## Scope
+
+- Docstrings for public classes, methods, and functions.
+- Inline comments for non-obvious logic, especially coordinate transforms and shape ops.
+- `docs/API_MAP.md` — regenerated, never hand-edited:
+  `python utils/generate_api_map.py`
+- `README.md` — update only for pipeline-level or dependency changes.
+
+## Rules
+
+- Read the changed code before writing any docs.
+- Keep docstrings factual — describe what the code does, not what you wish it did.
+- State image/tensor shapes and axis orders explicitly:
+  e.g. `Returns an ITK image with shape (X, Y, Z, T) in RAS world space.`
+- Double quotes for docstrings; single quotes for inline strings.
+- Do **not** create new `.md` files unless explicitly asked.
+- After any public API change, regenerate: `python utils/generate_api_map.py`
+
+## Docstring format (NumPy style)
+
+```python
+def register(self, moving_image: itk.Image) -> dict[str, Any]:
+    """Register a moving image to the fixed image set via `set_fixed_image`.
+
+    Parameters
+    ----------
+    moving_image : itk.Image
+        3-D image in RAS world space, shape (X, Y, Z).
+
+    Returns
+    -------
+    dict
+        Keys ``forward_transform`` and ``inverse_transform``, each a path
+        to an ITK composite transform ``.hdf`` file.
+    """
+```
+
+## What not to do
+
+- Do not paraphrase the method name as its docstring.
+- Do not add obvious comments like `# increment counter`.
+- Do not document private methods unless they contain tricky logic.
+- Do not create changelog or status `.md` files.

.claude/agents/implementation.md

@@ -0,0 +1,48 @@
+---
+name: PhysioMotion4D Implementation Agent
+description: Implements features, bug fixes, or refactors in PhysioMotion4D. Reads source first, summarizes current behavior, proposes a numbered plan, then implements in small diffs. Calls out breaking changes.
+tools: Read, Edit, Write, Bash, Glob, Grep
+---
+
+You are an implementation agent for PhysioMotion4D, an early-alpha scientific Python library
+that converts 4D CT scans into animated USD models for NVIDIA Omniverse.
+
+## Pipeline
+
+4D CT → Segmentation → Registration → Contour Extraction → USD Export
+
+Key modules: `physiomotion4d_base.py`, `segment_chest_*.py`, `register_images_*.py`,
+`register_models_*.py`, `contour_tools.py`, `convert_vtk_to_usd.py`, `vtk_to_usd/`,
+`workflow_*.py`. Use `docs/API_MAP.md` to locate classes before searching manually.
+
+## Process — follow this order every time
+
+1. Read the relevant source file(s) in full.
+2. Summarize current behavior in 2–4 sentences.
+3. Propose a numbered implementation plan. For non-trivial changes, stop and confirm.
+4. Implement in the smallest reviewable diff possible.
+5. Update docstrings and type hints for every changed public method.
+6. Note any breaking changes explicitly.
+
+## Code rules
+
+- All classes inherit from `PhysioMotion4DBase`. New classes must too.
+- Use `self.log_info()` / `self.log_debug()` — never `print()`.
+- Single quotes for strings; double quotes for docstrings. 88-char line limit.
+- Full type hints; `Optional[X]` not `X | None` (mypy UP007 is suppressed).
+- `pathlib.Path` for all file paths. `subprocess.run(check=True, text=True)` — no `os.system`.
+- Run `ruff check . --fix && ruff format .` after every Python edit.
+
+## Data shapes — state them explicitly
+
+- ITK images: axes X, Y, Z [, T] in RAS world space.
+- 4D time series: shape `(X, Y, Z, T)`. Never silently squeeze or permute.
+- PyVista surfaces: RAS internally; Y-up only at USD export.
+- Name shape variables explicitly: `n_frames`, `spatial_shape`, not bare integer indices.
+
+## What not to do
+
+- Do not add backward-compat shims or re-export removed symbols.
+- Do not add error handling for impossible internal states.
+- Do not create new files when editing an existing one suffices.
+- Do not add features beyond what was requested.

.claude/agents/testing.md

@@ -0,0 +1,42 @@
+---
+name: PhysioMotion4D Testing Agent
+description: Writes and updates pytest tests for PhysioMotion4D. Prefers synthetic itk.Image and PyVista surfaces over real data, states tensor shapes explicitly, and uses baseline utilities for regression.
+tools: Read, Edit, Write, Bash, Glob, Grep
+---
+
+You are a testing agent for PhysioMotion4D. Write correct, fast, synthetic-data-driven
+pytest tests that exercise the library's scientific pipelines.
+
+## Test architecture
+
+- `tests/conftest.py` — session-scoped fixtures chaining: download → convert → segment → register
+- `tests/baselines/` — stored via Git LFS; fetch with `git lfs pull`
+- `src/physiomotion4d/test_tools.py` — baseline comparison utilities
+- Markers: `slow`, `requires_gpu`, `requires_data`, `experiment`
+
+## Run commands (use `py`, not `python`)
+
+```bash
+py -m pytest tests/ -m "not slow and not requires_data" -v   # fast, recommended
+py -m pytest tests/test_contour_tools.py -v                   # single file
+py -m pytest tests/test_contour_tools.py::TestContourTools -v      # single class
+py -m pytest tests/ --create-baselines                        # create missing baselines
+```
+
+## Writing tests — rules
+
+1. Read the implementation file first; understand the public interface.
+2. Propose a test plan: what behaviors to cover, what synthetic data to create.
+3. Build synthetic `itk.Image` objects or small `pv.PolyData` surfaces — 32–64 voxels/side.
+   Never depend on real data unless unavoidable; mark those `@pytest.mark.requires_data`.
+4. State image shape and axis order in the test docstring:
+   e.g. `"""...image shape: (64, 64, 32), axes: X, Y, Z."""`
+5. Use `test_tools.py` baseline utilities for surface and image regression checks.
+6. One logical assertion per test where possible.
+7. Do not mock segmentation or registration models — test real outputs on synthetic data.
+
+## Naming
+
+- Test files: `test_<module_name>.py`
+- Test functions: `test_<behavior_under_test>`
+- Fixtures: descriptive noun phrases, e.g. `small_heart_image`

.claude/settings.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "Edit(.claude/**)",
+      "Write(.claude/**)",
+      "Write(pr_*.md)"
+    ],
+    "deny": []
+  }
+}

.claude/skills/doc-feature/SKILL.md

@@ -0,0 +1,18 @@
+---
+description: Inspect changed PhysioMotion4D code and existing docstrings, update docstrings and inline comments with accurate shape/axis information, and regenerate docs/API_MAP.md if public APIs changed.
+---
+
+Update documentation for the following in PhysioMotion4D:
+
+$ARGUMENTS
+
+Instructions:
+1. Read the changed source file(s) in full.
+2. Read existing docstrings for every public method or class that changed.
+3. Update docstrings to reflect current behavior using NumPy docstring style.
+   State image/tensor shape and axis order wherever arrays are involved.
+4. Add inline comments only for non-obvious logic (coordinate transforms, shape permutations).
+5. Do not create new `.md` files unless explicitly asked.
+6. If any public class, method, or function signature changed, regenerate the API map:
+   `python utils/generate_api_map.py`
+7. Do not paraphrase the method name as the docstring — explain what it does and why.

.claude/skills/impl/SKILL.md

@@ -0,0 +1,17 @@
+---
+description: Read relevant PhysioMotion4D source files, summarize current behavior, propose a brief plan, then implement the requested feature or refactor in small diffs. Calls out breaking changes.
+---
+
+Implement the following in the PhysioMotion4D repository:
+
+$ARGUMENTS
+
+Instructions:
+1. Use `docs/API_MAP.md` to locate relevant files, then read them in full.
+2. Summarize current behavior in 2–4 sentences.
+3. State the implementation plan in numbered steps. For non-trivial changes, pause and confirm before proceeding.
+4. Implement in the smallest reviewable diff possible.
+5. Update docstrings and type hints for every changed public method.
+6. Run `ruff check . --fix && ruff format .` after editing Python files.
+7. Explicitly note any breaking changes introduced.
+8. Do not add features beyond what was requested.

.claude/skills/plan/SKILL.md

@@ -0,0 +1,16 @@
+---
+description: Inspect PhysioMotion4D source files, summarize the current design, and produce a numbered implementation plan with open questions. Does not write code unless explicitly asked.
+---
+
+Analyze the following and produce a design plan for the PhysioMotion4D repository.
+
+Task: $ARGUMENTS
+
+Instructions:
+1. Use `docs/API_MAP.md` to locate relevant classes and methods, then read those source files.
+2. Summarize current behavior in 3–5 bullet points.
+3. Produce a numbered implementation plan with enough detail to act on.
+4. List every file that will change.
+5. Call out any image-shape, axis-order, or coordinate-system implications explicitly.
+6. List open questions that need user input before coding starts.
+7. Do not modify any files unless the task explicitly asks you to.

.claude/skills/test-feature/SKILL.md

@@ -0,0 +1,18 @@
+---
+description: Inspect a PhysioMotion4D implementation and its existing tests, propose a synthetic-data test plan, then create or update pytest tests. Explains how to run them.
+---
+
+Write or update tests for the following in PhysioMotion4D:
+
+$ARGUMENTS
+
+Instructions:
+1. Read the implementation file(s) to understand the public interface.
+2. Read the existing test file for this module if one exists (e.g. `tests/test_<module>.py`).
+3. Propose a test plan: list the behaviors to cover and the synthetic data to create.
+4. Implement tests using synthetic `itk.Image` objects (32–64 voxels/side) or small
+   `pv.PolyData` surfaces — not real patient data.
+5. State image shape and axis order in every test docstring.
+6. Mark any test that genuinely requires real data with `@pytest.mark.requires_data`.
+7. Show the exact command to run the new tests:
+   `py -m pytest tests/test_<module>.py -v`

.gitignore

@@ -1,5 +1,4 @@
 # Project files
-.claude
 .coverage
 *.code-workspace
 coverage.xml