@@ -0,0 +1,94 @@
+---
+name: robostack-debug-build
+description: Debug and fix a RoboStack package that fails to build (compile, link, configure, patch or test failures) for one ROS distribution. Use when a build-one / CI build of a ros2-<pkg> recipe fails.
+---
+
+# Debug a failed package build
+
+Work from the repository root; `<d>` is the distribution, `<pkg>` the conda name
+(`ros2-<ros-name-with-dashes>`).
+
+## 1. Reproduce with one package
+
+```bash
+pixi run rs <d> generate-recipes          # if distros/<d>/work/recipes is missing or stale
+pixi run rs <d> build-one ros2-<pkg>
+```
+
+`build-one` copies the package's patches into the recipe and builds without
+`--skip-existing`. For a CI failure, first read the failing job's log
+(`gh run view <run> --job <job> --log-failed`) and search for `× error`,
+`CMake Error`, `error:` and `undefined reference`.
+
+## 2. Find the work directory
+
+```bash
+ls -td distros/<d>/work/output/bld/rattler-build_ros2-<pkg>_*/work | head -1
+```
+
+In it:
+- `conda_build.log`: the full log. Look for compile, link and configure errors,
+  patch failures, missing files.
+- `build_env.sh`: `PREFIX` (host env), `BUILD_PREFIX`, `SRC_DIR`, `RECIPE_DIR`.
+- `.source_info.json` (`jq .`): the fetched source revision.
+
+## 3. Investigate by failure class
+
+| symptom | look at |
+|---|---|
+| missing header | `requirements.host` of the recipe; is it under `$PREFIX/include`? |
+| `Could not find a package configuration file provided by "X"` | is X in host? Does a conda-forge package provide that CMake config? A mapping in `shared/robostack.yaml` may be wrong, or vinca may have built a ROS package under the conda-forge name (see below) |
+| undefined symbols | host deps, `$PREFIX/lib`, link flags |
+| configure failure | flags in `conda_build.sh`; rerun with verbosity |
+| patch does not apply | refresh it, see the `robostack-patch` skill |
+| hard-coded prefixes / rpaths | relocatability; inspect with `otool -L` (macOS) / `patchelf --print-rpath` |
+
+Reproduce interactively:
+
+```bash
+cd <work-directory>
+source build_env.sh
+bash -x conda_build.sh 2>&1 | less
+```
+
+## 4. Common fixes
+
+- **Boost 1.88+**: needs C++14 or newer; replace `-std=c++11` / `CMAKE_CXX_STANDARD 11`.
+- **Python modules on macOS**: don't link `Python::Python`:
+  ```cmake
+  if(APPLE)
+    set_target_properties(${_name} PROPERTIES LINK_FLAGS "-undefined dynamic_lookup")
+  else()
+    target_link_libraries(${_name} ${PYTHON_LIBRARIES})
+  endif()
+  ```
+- **Windows `min`/`max` macro clashes**: `target_compile_definitions(<target> PRIVATE NOMINMAX WIN32_LEAN_AND_MEAN)` under `if(WIN32)`.
+- **gtest / test failures**: add the missing dependency in `dependencies.yaml`, or
+  disable the tests when safe; no custom shims.
+- **Qt plugins (rviz, rtabmap)**: make sure CMake finds the intended Qt major version.
+- **Missing dependency**: `shared/dependencies.yaml` (all distributions) or
+  `distros/<d>/patch/dependencies.yaml` (one), keyed by ROS package name:
+  ```yaml
+  <ros_pkg>:
+    add_host: [<conda-pkg>]
+    add_run: [<conda-pkg>]
+  ```
+- **A conda-forge package is shadowed**: when a rosdep key that is also a ROS package
+  maps to a conda-forge package (e.g. `tl_expected` -> `cpp-expected`), vinca may build
+  the ROS package under the conda-forge name. Add it to `packages_skip_by_deps`
+  (`shared/vinca.yaml`), and evict the stale build from the PR cache
+  (`evict_cache` in `distros/<d>/ci.yaml`, plain names work).
+- **CMake args for one package**: `additional_cmake_args` in `pkg_additional_info.yaml`.
+
+## 5. Make it stick
+
+1. Turn source edits into a patch (`robostack-patch` skill).
+2. Rebuild: `pixi run rs <d> build-one ros2-<pkg>`.
+3. If the fixed package was already built in the PR, add it to `evict_cache` in
+   `distros/<d>/ci.yaml`. A package that is already published needs a new build
+   number: `<ros_pkg>: {build_number: <global + 1>}` in `distros/<d>/pkg_additional_info.yaml`.
+4. Check whether the same fix applies to other distributions; port it only where the
+   source is compatible.
+
+Triage order with many failures: fix the easy ones first, move on once something gets
+complex, and come back after the queue is shorter.
@@ -0,0 +1,69 @@
+---
+name: robostack-package-selection
+description: Add, exclude or restrict ROS packages in RoboStack vinca.yaml files (shared/ and distros/<d>/), including platform-only packages, dependency skips and the build gap report. Use when a package should be added, removed, made Linux-only, or when recipes/artifacts don't line up.
+---
+
+# Package selection (vinca.yaml)
+
+`distros/<d>/work/vinca.yaml` is assembled from `shared/vinca.yaml` plus
+`distros/<d>/vinca.yaml`. The three package lists are concatenated; for other keys
+the distribution wins. A package selected for every distribution goes into
+`shared/vinca.yaml`.
+
+## Add packages
+
+```bash
+pixi run rs add-package foxglove_bridge rqt_gauges            # every distribution that has them
+pixi run rs add-package foxglove_bridge humble jazzy --preview
+```
+
+This is the bot's `add-package`. It inserts in sorted position, chooses `shared/` when
+every distribution gets the same packages, and lists what will be built on linux-64.
+Names are ROS package names; dashes and underscores both work.
+
+## The three ways to exclude a package
+
+vinca's revision is pinned in `pixi.toml`. If that pin moves, re-check
+`vinca/main.py` and `vinca/resolve.py`.
+
+1. **`packages_select_by_deps` under a platform condition**: the primary way to keep a
+   package's own recipe off a platform. Every listed name is selected
+   unconditionally, so not listing it for a platform is what excludes it:
+   ```yaml
+   packages_select_by_deps:
+     - if: linux
+       then:
+         - some_linux_only_pkg
+   ```
+2. **`packages_skip_by_deps`**: only stops transitive pull-in (`ignore_pkgs` for
+   `distro.get_depends()`). It doesn't stop a package listed directly in (1). It's
+   also the tool for ROS packages that map to conda-forge in `shared/robostack.yaml`
+   (`tl_expected`, `sophus`), so that vinca doesn't build them under the conda-forge
+   name.
+3. **`packages_remove_from_deps`**: removes the package's own recipe *and* strips it
+   from every other package's host/run dependencies, together and inseparably. Use
+   it only if nothing selected legitimately needs it; otherwise use (1) + (2).
+
+Keep (2) and (3) coherent with the platform conditions in (1). A truly platform-only
+package goes behind a condition, not into a comment.
+
+## Recipes vs. artifacts
+
+```bash
+pixi run rs <d> generate-recipes --platform <platform>
+pixi run rs <d> gap-report
+```
+
+- **Built artifacts without a recipe directory**: packages in
+  `distros/<d>/work/output/<platform>` that aren't selected any more. Add their seeds,
+  or accept that they are gone.
+- **Recipe directories without an artifact**: generated recipes still to build on this
+  platform.
+
+Regenerate recipes after editing `vinca.yaml` before expecting the report to change.
+
+## rosdep mappings
+
+`shared/robostack.yaml` maps rosdep keys to conda packages (per platform);
+`shared/packages-ignore.yaml` lists keys to drop. Changes there affect every
+distribution: check them with `generate-recipes` for at least two distributions.
@@ -0,0 +1,66 @@
+---
+name: robostack-patch
+description: Create, refresh, place, port and validate source patches for RoboStack ROS packages (distros/<d>/patch/). Use after editing sources in a rattler-build work directory, when a patch no longer applies, or when porting a fix to another distribution.
+---
+
+# Patches
+
+## Where they live
+
+- `distros/<d>/patch/ros-<d>-<pkg>.patch` (all platforms), or with a platform suffix
+  `.osx.patch`, `.linux.patch`, `.win.patch`, `.unix.patch`. `<pkg>` uses dashes.
+- One patch per package and platform. Merge new hunks into the existing file instead
+  of adding variants.
+- vinca picks them up by name when generating recipes; nothing else needs wiring.
+  `pixi run rs check` rejects names of other distributions.
+- `distros/<d>/patch/dependencies.yaml` is for dependency fixes, not source patches
+  (`shared/dependencies.yaml` for all distributions).
+
+## Create a patch from work-directory edits
+
+```bash
+WORK=$(ls -td distros/<d>/work/output/bld/rattler-build_ros2-<pkg>_*/work | head -1)
+cd "$WORK"
+# edit the sources, rebuild with `bash conda_build.sh` (after `source build_env.sh`)
+rattler-build create-patch --directory . --name ros-<d>-<pkg> \
+  --exclude "*.o,*.so,*.dylib,*.a,*.pyc,__pycache__,build/" --dry-run
+rattler-build create-patch --directory . --name ros-<d>-<pkg> \
+  --exclude "*.o,*.so,*.dylib,*.a,*.pyc,__pycache__,build/"
+```
+
+Move the result to `distros/<d>/patch/ros-<d>-<pkg>.patch`, merging it with an
+existing patch for that package if there is one. Then:
+
+```bash
+pixi run rs <d> build-one ros2-<pkg>
+```
+
+Without a work directory, a `git diff` against the source checkout from
+`.source_info.json` works too (paths relative to the source root, `a/` and `b/` prefixes).
+
+## Check that patches apply
+
+```bash
+pixi run rs <d> check-patches                          # every recipe with patches
+pixi run rs <d> check-patches --recipe ros2-<pkg>      # one (repeat --recipe for more)
+pixi run rs <d> check-patches --dry --recipe ros2-<pkg>  # prepare only
+pixi run rs <d> check-orphaned-patches                 # platform patches without a recipe
+```
+
+## Refresh a patch that no longer applies
+
+A new upstream version moved the code: build the package without the patch (rename it
+temporarily), re-apply the change by hand in the work directory, regenerate with
+`create-patch`, and check that the old intent is still needed. Upstream may have fixed
+it, in which case delete the patch.
+
+## Port a fix to another distribution
+
+- Port only to an existing package with a compatible source. Compare the versions in
+  `distros/<d>/rosdistro_snapshot.yaml` and check with `check-patches`. Never copy a
+  patch only because a file of that name exists elsewhere.
+- Rename to the target distribution (`ros-<other>-<pkg>.patch`).
+- After the PR's first build, add the package to `evict_cache` in the target's
+  `ci.yaml` if CI already cached it.
+- Fixes that belong upstream: open a PR on the package's repository and note it in the
+  patch header.
@@ -0,0 +1,113 @@
+---
+name: robostack-versions
+description: Update ROS package versions (rosdistro snapshot) and conda-forge pins for RoboStack distributions, bump build numbers and the distro mutex, plan full rebuilds, and find or rebuild packages built against outdated pins. Use for version updates, pinning/migration changes, pin conflicts, or full rebuilds.
+---
+
+# Versions, pins and rebuilds
+
+robostack-bot does the routine part: `update-rosdistro-snapshot` (daily, when a new
+rosdistro sync is tagged) and
+`update-conda-forge-pinning` (weekly, or on request) open PRs that already contain the
+bumps below. Do it by hand when the bot fails or something extra is needed.
+
+## What is pinned where
+
+- **ROS package versions**: `distros/<d>/rosdistro_snapshot.yaml`, plus
+  `rosdistro_additional_recipes.yaml` for packages outside rosdistro.
+- **conda-forge pins**:
+  - `shared/pinning/conda_forge.yaml` holds the pinning version and migrations for
+    every distribution that doesn't set its own.
+  - `shared/pinning/overrides.yaml` holds local pins.
+  - `distros/<d>/distro.yaml` can set `conda_forge_pinning_version` together with
+    `conda_forge_migrations` (its own pinning, e.g. until its next full rebuild), and
+    `pinning_overrides` (replace shared pins by name).
+  - `pixi run rs <d> render-pinning` writes the committed
+    `distros/<d>/conda_build_config.yaml`.
+- **The mutex** (`mutex_package` in `distros/<d>/vinca.yaml`): `ros2-distro-mutex`
+  with `upper_bound: x.x`. Packages built with mutex 0.11 can't be installed with
+  0.10 builds. Its `run_constraints` pin the ABI-relevant libraries for users'
+  environments and must agree with the rendered pins.
+
+## Update the snapshot
+
+```bash
+pixi run rs rosdistro-syncs         # which distributions have a new sync (what the bot checks daily)
+pixi run rs <d> update-snapshot     # = bot command: latest sync, version bumps, rebuild bump
+# or only the file, for a given sync tag (any ros/rosdistro ref) or rosdistro master:
+pixi run rs <d> create-snapshot --rosdistro-ref <d>/2026-10-05
+pixi run rs <d> create-snapshot
+```
+
+- The ROS release team tags every sync from ros-testing to the main repositories in
+  ros/rosdistro (`<distro>/<YYYY-MM-DD>`, announced on Discourse as "New Packages for
+  ..."). Snapshotting the tag ships what users get from the official repositories;
+  rosdistro master also contains releases that are still only in ros-testing.
+- `distros/<d>/distro.yaml` records the sync as `rosdistro_sync`. `rosdistro_sync:
+  manual` (rolling, which isn't tagged regularly) uses rosdistro master instead and
+  isn't checked daily.
+- `update-snapshot` also performs the rebuild bump (next section).
+
+## Update the conda-forge pinning
+
+```bash
+pixi run rs update-pinning          # = bot command, for all distributions that follow shared/
+pixi run rs <d> render-pinning      # after editing shared/pinning or distro.yaml
+pixi run rs <d> check-deps          # solve all non-ROS deps + mutex constraints, nothing built
+```
+
+`check-deps` reports:
+- `PIN MISMATCH`: a mutex `run_constraints` entry contradicts the rendered pin. Fix
+  `vinca.yaml` or the pinning; never `conda_build_config.yaml`.
+- Per conflicting package: the recipes that need it, the clashing pin, the solver
+  explanation and the conda-forge migration status. "no migration" means the feedstock
+  only needs a rebuild upstream.
+
+Exit code 1 means something conflicts. Status of migrations:
+https://conda-forge.org/status/.
+
+## Rebuild bump (full rebuild)
+
+When the snapshot or the pins change, everything is rebuilt:
+
+1. `build_number` in `distros/<d>/vinca.yaml` = the highest build number of the
+   distribution's released packages + 1, so every package gets a new build.
+2. Mutex minor version + 1, e.g. `0.10.0` -> `0.11.0`. Nothing else hard-codes the
+   mutex version.
+3. Remove all per-package `build_number` entries in `distros/<d>/pkg_additional_info.yaml`.
+4. Update mutex `run_constraints` to the new pins, then run `check-deps`.
+5. `pixi run rs check`.
+
+The bot does 1–4. It only moves constraints of the form `<pkg> <version>.*`; ranges
+and other constraints are left for you to check.
+
+In the PR, CI uses its cache unless told otherwise. A full rebuild PR sets
+`full_rebuild: true` in `distros/<d>/ci.yaml` (reset after merging).
+
+## Rebuild a few packages
+
+- Published already: `<ros_pkg>: {build_number: <global + 1>}` in
+  `distros/<d>/pkg_additional_info.yaml`. Shared settings stay in
+  `shared/pkg_additional_info.yaml`; the distribution's keys win.
+- Only in the current PR: `evict_cache` in `distros/<d>/ci.yaml`.
+
+## Packages built against outdated pins
+
+```bash
+pixi run rs <d> find-stale                                     # = bot find-stale-packages
+pixi run rs <d> check-deps --stale                             # local artifacts
+pixi run rs <d> check-deps --stale --mutex-only                # only mutex violations
+pixi run rs <d> check-deps --stale --repodata https://conda.anaconda.org/<channel>
+pixi run rs <d> check-deps --stale --delete                    # delete stale local artifacts
+```
+
+For published stale builds, the report prints the `pkg_additional_info.yaml`
+build-number snippet, a `mutex_package: build_number:` bump (re-publishes the mutex
+with new constraints without changing its version), and the `anaconda remove`
+commands for the old files.
+
+## Bump vinca or rattler-build
+
+Both are pinned once for all distributions in `pixi.toml` (vinca as a git revision).
+After a bump, run `pixi install`, `pixi run rs check`, and
+`pixi run rs <d> generate-recipes` for a distribution or two, and compare the recipe
+sets before and after.