Request for Comments: Modular AirStack — module repos, slot contracts, marketplace, and distributed CI/docs

[andrewjong]

RFC: Modular AirStack — module repos, slot contracts, a module marketplace, and distributed CI/docs

This RFC is the output of a design session on making AirStack modular rather than monolithic. It is written to be self-contained: a reader (human or AI agent) should be able to understand the full design and implement it from this document alone. Repo facts referenced below are accurate as of develop @ 55d9b887 (VERSION 0.19.0-alpha.9).

1. Problem statement

Projects branched from AirStack develop features we want to offer to trunk users as optional capabilities, but today the only integration path is merging into the monolith or living forever in a fork. Concrete motivating cases:

• Don't Fool Me Twice (DFM2) built a library of Isaac Sim disturbances (lens flares, strobe lights, ice planes, …). It lives in a whole-repo fork of AirStack, so the reusable work is buried inside a copy of everything else.
• An OptiTrack motion-capture integration for state estimation, with its own tests.
• A custom global planner.

The specific pain points this design addresses:

1. Distribution — modules should live in their own git repos, pulled into a developer's local stack on demand, with their own CI running their own tests so they don't bog down trunk's test suite.
2. Version compatibility — modules must (at minimum) report which AirStack versions they're compatible with, and ideally have that claim verified automatically.
3. Launch integration — today, enabling/disabling a module means hand-editing bringup launch XML in the right place and rewiring topics. The result is a variant explosion: robot/ros_ws/src/local/local_bringup/launch/ contains local.launch.xml, local_droan_cpu.launch.xml, and local_macvo_obstacle_avoidance.launch.xml — near-copies differing by which module fills a role, with alternate wirings living as commented-out lines.
4. Cross-module compatibility — modules may expect certain inputs/topics or depend on each other.
5. Discoverability — ideally a "marketplace" of modules compatible with AirStack that developers can browse and sync.
6. Docker images — all deps for all modules are currently merged into one Dockerfile per host type (Dockerfile.robot, GCS, Isaac). This breaks when deps are cross-repo, and the permutation space of module combinations is too large to prebuild.
7. Tests — a module author (e.g., the custom global planner) needs to run trunk's full system-test suite (image builds, container liveliness, takeoff/hover/land, trajectory following, waypoint navigation) from a repo that contains only their module.
8. Docs — trunk uses MkDocs (+ mike versioning); module docs will be distributed across repos but should still be served coherently on the public site.

Design principles (decided)

• Steal the rosdistro model, don't invent one. Index repo + version-pinned manifests + CI-verified compatibility is a proven pattern (ROS buildfarm/rosdistro, vcstool).
• Modules are thin repos, never forks. A module repo contains only its packages plus a manifest.
• Standardize the waists, not the topology. Contracts live at a small number of interchange points ("rungs"), so the architecture absorbs module shapes we haven't imagined yet (see §4, end-to-end VLA example).
• Containers stay machines. One container per robot + one for GCS + one for sim models real deployments (DDS domain isolation, multi-robot replicas, onboard/offboard split). We do NOT split into per-module containers; the dependency problem is solved at the image composition layer (§6).
• Compatibility claims must be CI-verified or they rot. Declared ranges without automated verification are worthless; the CI loop (§5) is the foundation everything else depends on.

2. Module anatomy: a thin repo with a manifest

A module repo contains its ROS packages / Isaac extension / assets plus a module.yaml at the root:

name: dfm2_disturbances
description: Isaac Sim disturbance library (lens flare, strobes, ice planes)
maintainer: someone@andrew.cmu.edu         # required; see governance §8
license: BSD-3-Clause                      # checked at registration
type: isaac_extension                      # isaac_extension | ros_package | stack_module
airstack_compat: ">=0.19.0 <0.21.0"        # semver range vs trunk .env VERSION
container_targets: [isaac-sim]             # which host containers it touches: robot | gcs | isaac-sim

# Interface contract (see §3–4)
slot: null                                 # e.g. "global_planner" if it fills a standard slot
provides: [disturbance_injection]          # capability names
requires: []                               # capability names it needs from the stack
replaces: []                               # slots it vacates (stack_module type, §4)

launch: launch/dfm2.launch.xml             # standard entry point honoring contract args
compose: docker-compose.module.yaml        # optional compose fragment (mounts, env)

deps:                                      # dependency tier 1 (§6); tiers 2–3 also declared here
  apt: []
  pip: []
dockerfile: null                           # tier 2: Dockerfile.module using ARG BASE_IMAGE
overlay_image: null                        # tier 3: prebuilt overlay image ref

assets: []                                 # large files: [{url, sha256, dest}] fetched to a cache by `module sync` — no Git LFS in module repos

docs:
  readme: README.md                        # or dir: docs/ + nav: nav.yml

foxglove: null                             # optional Foxglove layout/panel fragment

tests:
  packages: [dfm2_disturbances]            # unit-test packages (colcon convention, co-located test/)
  conformance_marks: []                    # system-test marks this module must pass (per-slot defaults, §5)

The three motivating examples map as: OptiTrack → ros_package, slot: state_estimator, provides: [odometry]; custom planner → slot: global_planner; DFM2 → isaac_extension (Isaac supports extension search paths, so it's the lowest-coupling pilot).

3. Sync mechanism and launch integration

Sync: vcstool + a modules/ overlay (not submodules)

• Developers keep a modules.repos file (vcstool format). airstack module add <name-or-url> clones into a gitignored modules/ directory at repo root and updates modules.repos.
• The overlay plumbing places each module where its type/targets say: ROS packages symlinked into robot/ros_ws/src/modules/ (colcon picks them up automatically), Isaac extensions onto the extension search path, compose fragments merged via COMPOSE_FILE.
• Trunk never carries module code — only the optional manifest. Nothing about a developer's module selection is committed to trunk.
• New CLI surface: airstack module add|remove|list|sync|doctor|create|search|extract, plus airstack init --release <X>, module create --in-tree, and module doctor --drift (see §11, researcher workflow).

Slots + one stack config: kill the variant launch files

The layers already implicitly define roles. Make them explicit slots (state_estimator, local_planner, local_world_model, global_planner, global_world_model, controller, behavior, …). Each slot has a contract: the standard topics (already documented in docs/robot/autonomy/integration_checklist.md) become required launch args. Every module — including trunk's own — ships its own launch file honoring that arg interface.

Replace hand-edited bringup XML with a per-deployment stack.yaml:

slots:
  state_estimator: optitrack             # a module; provides /odometry
  local_planner: droan                   # trunk default; swap to droan_cpu / macvo_avoidance here
  global_planner: my_custom_planner      # a module
extras: [dfm2_disturbances]
overrides:
  droan.disparity_in: /$ROBOT_NAME/perception/stereo_image_proc/disparity

A generic Python bringup reads stack.yaml, includes each selected module's launch file, and passes the contract topics. Enabling/disabling a module = one line. The three local_*.launch.xml variants collapse into three preset stack.yaml files. (Precedent for YAML-driven collection already exists in trunk: tests/colcon_unit_test_packages.yaml.)

Contracts are more than topic names. The slot contract spec must also capture QoS profiles (a best-effort subscriber against a reliable-only publisher silently receives nothing) and frame/units conventions (TF tree shape, ENU vs NED, frame naming). Cheap to declare, miserable to debug in the field. airstack module doctor checks these.

4. Modules that don't fit a slot (e.g., an end-to-end VLA planner)

A rigid slot taxonomy breaks on modules that swallow several slots — e.g., an end-to-end vision-language-action planner spanning perception → global planning → local planning. Three refinements:

(a) Slots are contracts at narrow waists, not boxes. The stack's real invariants are a handful of interchange points — rungs on a ladder: sensor bus → state estimate (/odometry) → global plan → trajectory interface (trajectory_segment_to_add / trajectory_override) → task action servers (tasks/navigate) → low-level interface commands. A conventional module taps in at one rung and out at the next; an end-to-end module taps in high and out low.

(b) A module can declare what it replaces:

name: vla_pilot
type: stack_module
consumes: [front_stereo, odometry, tasks/navigate]
produces: [trajectory_override]
replaces: [global_planner, local_planner, local_world_model]

The resolver vacates replaced slots (no double-publishing), verifies everything consumed is still provided by something, and warns about orphaned downstream consumers (e.g., a GCS map view fed by the vacated world model).

(c) Three module tiers of decreasing verifiability, all first-class:

1. Slot filler — drop-in planner/estimator; doctor verifies everything.
2. Ladder-spanning stack_module — declares consumes/produces/replaces; doctor verifies wiring and conflicts, not internals.
3. Freeform — gets a namespace and the sensor bus, declares only conflicts; doctor checks collisions only.

Non-negotiable safety floor across all tiers: command authority flows through the trajectory controller / interface layer, where arming, safety monitoring, and takeover live. A module emitting trajectory_override inherits the whole safety apparatus for free (timeout behavior, land-on-state-estimate-loss, GCS override) — a selling point for authors, not a constraint. A module that genuinely must bypass it (direct attitude/rate commands) must declare produces: [attitude_setpoint] and the doctor flags it loudly as safety-critical.

Cross-module compatibility uses the same machinery: provides/requires capability names + slot uniqueness gets ~90% of the value cheaply. doctor reports: two modules claiming one slot, a requires nobody provides, message-type mismatches vs airstack_msgs. Do not build a full ontology — names + message types, validated at sync time and optionally at launch.

Future work — cross-embodiment generalization. The rung model's second stress test (after the VLA case above) is generalizing AirStack across form factors: quadrupeds, wheeled robots, humanoids, reusing autonomy modules across embodiments via a platform module type and trait-based compatibility. That design is deliberately split into its own RFC to keep this one focused on modularity: see RFC: Cross-embodiment AirStack (#380). Nothing in it changes the plan here — it's what this plan enables later.

5. Version compatibility and test separation

The substrate already exists

Trunk's docker-build.yml pushes cosign-signed images tagged by .env VERSION on merge to main/develop. Published images are the compatibility contract.

Module CI: a reusable workflow trunk owns

Trunk publishes a workflow_call-able workflow (.github/workflows/module-system-tests.yml). A module repo's entire CI:

jobs:
  system-tests:
    uses: castacks/AirStack/.github/workflows/module-system-tests.yml@v0.19.0
    with:
      airstack_ref: v0.19.0        # pin and checkout ref move together
      marks: "build_packages or liveliness or takeoff_hover_land or autonomy or waypoint_flight"
      sim: isaacsim

The reusable workflow: (1) checks out trunk at airstack_ref; (2) checks out the module and runs airstack module add ./ — the same overlay path a developer uses, so the module's slot: declaration wires it into the test bring-up's stack.yaml (their planner runs instead of the default); (3) runs the existing suite unchanged via airstack test -m "<marks>". test_build_packages builds their package because it's in the workspace; waypoint_flight exercises their planner because it fills the slot. The module repo never copies a single test.

System tests double as slot conformance tests. tests/waypoint_checker.py judging the odometry track (in-order corridor arrival, goal tolerance, per-waypoint timeout) doesn't care which planner produced the motion — passing it is the behavioral definition of "a working global planner." Formalize: each slot contract names the marks a filler must pass (global_planner → waypoint_flight, autonomy; state_estimator → liveliness, sensors, takeoff_hover_land). The registry compat badge for (module version × AirStack version) is granted only when that mark set passes.

GPU runner access (system tests need GPU + sim license)

Trunk's GPU jobs run on OpenStack ephemeral runners via .github/orchestrator/ (per-job VM, JIT token, destroyed on completion). Two paths, both used:

• First-party (org) modules: move runner registration to an org-level runner group; orchestrator polls queued jobs across registered repos. Admission to the runner group = listing in the module registry (mirrors trunk's existing fork-PR block on self-hosted runners).
• External/community modules: never get org GPUs directly. Trunk hosts a dispatch-triggered test bench workflow — repository_dispatch with {module_repo, module_ref, airstack_ref}; trunk runs the suite on its own runners and posts a check-run/status back to the module's commit via a GitHub App. Secrets, licenses, runner control never leave trunk; bench time can be gated/rate-limited.

Cost ladder (encode in the reusable workflow defaults)

• Every push: unit + build_packages inside the published image — minutes, no GPU, no orchestrator.
• PR / nightly: liveliness (+ sensors for perception-adjacent modules); msairsim is the cheaper bring-up.
• Release / compat claim: full slot-conformance mark set on GPU. This run stamps the registry badge.
• Trunk-side nightly ecosystem canary: trunk runs registered modules' conformance sets against develop, so breakage is discovered by trunk the day it lands — not by module authors months later.

Metrics: let module runs' metrics.json diff against trunk's baseline for the same AirStack version via the existing tests/parse_metrics.py. Badges can then carry e.g. "cross-track RMSE vs default planner," making the marketplace informative rather than a link list.

6. Docker images: base + composed module layers

Never publish permutations. Trunk keeps publishing exactly one signed base image per host type per version. Composed images are built where they're used, from cached layers.

Three dependency tiers (declared in module.yaml)

1. rosdep/apt/pip lists (default). Deps in package.xml (rosdep) + deps: {apt, pip} in the manifest. No Dockerfile in the module repo.

2. Dockerfile fragment for real install steps — written against a build arg, never a fixed base:

   ARG BASE_IMAGE
   FROM ${BASE_IMAGE}
   RUN ./install_optitrack_sdk.sh

3. Prebuilt overlay image for monster deps (e.g., a VLA's 20 GB CUDA/PyTorch). The module's own CI publishes ghcr.io/<org>/<module>-overlay:<airstack_version> built FROM ${BASE_IMAGE}; the manifest points at it so developers pull instead of build.

Composition chain

airstack module sync sorts enabled modules deterministically (by name), groups by target host, and builds:

ghcr.io/castacks/airstack-robot:0.19.0          ← pulled, never rebuilt
  → +layer: rosdep/apt/pip for tier-1 modules    (one RUN per module → per-module cache)
  → +layer: optitrack Dockerfile.module           (BASE_IMAGE = previous)
  → +layer: vla overlay                           (pulled if published for 0.19, else built)
  = airstack-robot:0.19.0-local

• Changing module code rebuilds nothing — source stays volume-mounted (dev loop = bws inside the container, unchanged).
• Changing one module's dep list rebuilds only that layer and those above it.
• The CLI hashes each module's dep declaration into modules.lock (resolved chain + image digests). airstack up knows precisely when a rebuild is needed and says so ("optitrack deps changed, rebuilding 2/4 layers"). The lockfile also gives reproducibility: compat badges record the digest chain they were earned with; a bug report of "modules A+B+C on 0.19.2" is one file.
• CI test bench uses the identical path; a registry-backed buildx cache keeps module layers warm across ephemeral runner VMs.

Two failure modes to design for

• Dep conflicts (one module pins numpy<2, another needs >=2): doctor runs pip check / apt dry-run against the composed layer set at compose time and names the two modules fighting — not a colcon failure forty minutes in.
• Prebuilt overlays don't merge. Rule: a published overlay is used as-is only when it's the sole tier-3 module in the chain; otherwise the CLI builds each from its Dockerfile.module in chain order. Modules keep their fragment buildable and treat the published overlay as a cache, not the source of truth.

Side effect: trunk's Dockerfiles thin out over time — deps merged into Dockerfile.robot because some configuration needs them (MACVO networks, mocap SDKs) migrate into the modules that own them. The monolith unwinds itself module by module.

7. Marketplace / registry

An airstack-modules-index repo (rosdistro's distribution.yaml pattern): one YAML entry per module — name, repo URL, description, maintainer, CI-generated compat matrix. airstack module search|list|add reads it; MkDocs renders it into a browsable catalog with compat badges. Getting listed = PR to the index, which doubles as the quality gate (manifest valid, CI green, README template sections present, license checked).

Release sets: the answer to N×N module compatibility

You can't test every module pairing. Periodically publish a curated release set — "AirStack 0.20 + these module versions, tested together" — one lockfile in the registry, blessed by a single CI run with all of them enabled. Individual badges mean "works with trunk"; release sets mean "works together." Most users pull a release set; à-la-carte is for developers. Release sets also drive versioned docs (§9).

8. Governance (the part most likely to decide success)

• Maintainer lifecycle. Module authors are grad students; grad students graduate. Every registry entry has a named maintainer. Nightly canary failing for N weeks with no response auto-moves the module to an "unmaintained" shelf — still listed, clearly labeled — rather than staying green-badged. This keeps marketplace credibility.
• License checks at registration. One GPL module in an overlay chain has implications the manifest must surface, not bury.
• Contract deprecation policy. The rungs are now public API. A rung change requires: semver-major bump on the contract, a deprecation window where old + new coexist, and a short RFC in the registry repo so module authors see it coming. Without this, the first breaking trunk change teaches everyone the badges are meaningless.
• Semver airstack_msgs ruthlessly, as its own versioned package. ROS 2 type hashes mean a module built against a different msg definition doesn't degrade gracefully — it silently fails to connect. doctor compares msg-package versions across the composed workspace.

9. Docs

Hybrid, with embedding automated. Pure link-outs to repo READMEs fail users: no unified search, no consistent theme, and no versioning (a GitHub README always shows main — wrong for someone on 0.19). Trunk already versions docs with mike; module docs ride that machinery.

• Main site owns natively: the auto-generated marketplace catalog (one page per module from the registry: description, maintainer, compat matrix, conformance results, install snippet, source link); the contract/rung specs, QoS + frame conventions, module-authoring guide, deprecation RFCs; everything that exists today.
• Module repos own their deep docs (README minimum, optionally docs/), declared via docs: in the manifest and validated against the README template at registration. The trunk docs deploy workflow gains a pre-build step: for each registered module, shallow-clone at a pinned ref, drop content under modules/<name>/, splice a nav entry. (Plugins exist — mkdocs-multirepo-plugin — but a fetch loop driven by the registry index is simpler and easier to debug. This extends trunk's existing same-dir pattern of including package READMEs from outside docs/.)
• Release sets drive doc versions: the docs build for version X fetches each module at the ref pinned in X's release set — versioned docs and the tested distribution stay in lockstep automatically. The develop/latest site fetches module default branches.
• Failure isolation: an unreachable module repo or broken module markdown must NOT fail trunk's docs deploy — skip, emit a stub page + warning.
• Freshness: rebuild on registry-index changes (repository_dispatch) + existing push triggers + nightly backstop. "Within a day, exact at releases" is the right target.
• Unregistered/external modules: catalog links out, no embedding — embedding is a perk of registration.

10. Smaller items (one line each, all decided)

• Large assets: manifest declares assets: [{url, sha256, dest}]; module sync fetches to a cache. No Git LFS blobs in module repos.
• GCS/Foxglove fragments: a module is only field-usable if operators can see it — manifest may ship a Foxglove layout/panel fragment like it ships a compose fragment.
• Scaffolding + agent skills: airstack module create generates the template repo (manifest, CI stub, launch, README); update .agents/skills/ so AI-agent contributions build modules the new way instead of reintroducing the monolith pattern.
• Dogfood the module mechanism (i.e., "eat your own dog food" — use it ourselves the way external authors would): migrate 1–2 trunk modules (e.g., MACVO, which drags heavy deps) onto the mechanism early. Maintainers hit the friction firsthand and fix it, the machinery can't silently rot, and the base images shrink.
• DFM2 as test infrastructure: a disturbance-injection module is a test fixture — the system-test harness can take an optional disturbance module to run robustness variants of existing flight marks. The first extracted module becomes a multiplier for the test story.

11. The researcher workflow: research in a fork, graduate to a module

A principle worth stating explicitly: research happens in a fork; modularity is a graduation step, not an entry fee. Nobody exploring an algorithm wants to maintain a manifest, CI, and contract compliance while their idea changes daily — if the process demands that, researchers will ignore it and we get whole-repo forks again (the DFM2 story). The design's job is to make the fork cheap to extract from later, which means the critical moment isn't extraction — it's day one.

Stage 0 — start from a release set. airstack init --release 0.20 clones trunk at the blessed tag with the release-set lockfile; airstack module add <name> pulls any modules the experiments need. The researcher pins here and stays pinned through the research — stability through the paper deadline, no chasing trunk.

Stage 1 — research in-tree, but inside a boundary. The expensive part of extraction later is never moving files — it's the archaeology: edits sprinkled across trunk launch files, hardcoded topics, deps snuck into Dockerfile.robot. So impose exactly one cheap discipline at the start: airstack module create --in-tree my_planner scaffolds a directory under robot/ros_ws/src/modules/my_planner/ — a normal colcon package with a stub module.yaml and its own launch file — living in the researcher's fork, committed to their repo, with zero CI or registry obligations. They hack freely inside it. All ceremony is deferred; only the directory boundary exists from day one, and that boundary is what makes extraction mechanical instead of archaeological.

To keep the boundary honest without policing: airstack module doctor --drift diffs the fork against the pinned release and classifies changes — contained in the module dir (fine) vs. trunk file edits (extraction debt, each listed). Researchers can run it never, occasionally, or in their fork's CI; either way, at extraction time the drift report is a precise, machine-readable work list rather than a surprise.

The boundary is a default, not a cage. Some feature work genuinely is repo-wide, and the drift report informs — it never blocks: no CI failure, no refusal to sync, no gate anywhere. A trunk edit in the drift report has three healthy destinies rather than being forbidden: (1) upstream it — bug fixes and genuine improvements belong to everyone; PR to trunk and it leaves the report entirely; (2) carry it as extraction debt — perfectly fine to defer; at graduation it becomes a stack.yaml override, launch arg, or Dockerfile fragment; (3) recognize it as a missing rung — sometimes a trunk edit is evidence the contracts lack a tap point the researcher needed, which is exactly what the contract RFC process (§8) is for; drift reports are how those gaps get discovered.

Stage 2 — graduate. Once the algorithm is ironed out: airstack module extract my_planner moves the directory into a fresh repo from the template (manifest completed, CI stub pinned to their release version, README skeleton) and emits the drift report as the remaining task list — convert this hardcoded topic to a contract arg, move these three Dockerfile.robot lines into deps:/Dockerfile.module, turn that trunk config edit into a stack.yaml override. Then the standard loop: conformance marks against the pinned version (should pass immediately — same code), then against current trunk (the deferred compat work happens once, at the end — matching researcher incentives), then register in the index.

Agent-assisted extraction. Extraction is an ideal coding-agent task for a specific reason: it has an objective success criterion. Package it as an .agents/skills/extract-module skill whose context is the module.yaml schema, the contract/rung specs, the template repo, and the drift report as input. The agent does the mechanical conversion and uses doctor + the slot's conformance marks (e.g., waypoint_flight passing with the researcher's planner in the slot) as its verification loop — it isn't hoping the refactor worked; it flies the drone until it does. A second, smaller skill matters just as much: guidance for agents helping during Stage-1 research, so an agent asked to "add a parameter to my planner" keeps changes inside the module directory instead of reintroducing trunk edits. Cheap prevention that makes Stage 2 nearly free.

Stage 3 — maintain or park. Nightly canary + compat bumps while the author is around; the unmaintained shelf when they graduate. The graduating-student story now has a good ending: an afternoon of agent-assisted extraction turns a thesis fork into a registered module, instead of the work dying with the fork.

12. Phased implementation plan

1. Phase 1 — CI loop + pilot (do first; everything depends on it): module.yaml schema (+ JSON Schema validation); reusable module-system-tests.yml workflow; extract DFM2 disturbances as pilot (sim-side, lowest coupling: Isaac extension path, no slot). Proves "own repo, own CI, own tests."
2. Phase 2 — overlay + CLI: modules/ overlay dir + modules.repos; airstack module add|remove|sync|doctor subcommands in the CLI; Docker composition chain + modules.lock; extract OptiTrack and the custom planner. Researcher-workflow tooling (§11): module create --in-tree, doctor --drift, module extract, and the extract-module agent skill.
3. Phase 3 — slot bringup: contract specs for existing layers (topics + QoS + frames); generic stack.yaml-driven bringup; collapse the local_*.launch.xml variants into presets. (Big refactor — fixes launch clutter for trunk modules too.)
4. Phase 4 — ecosystem: airstack-modules-index registry repo; docs catalog + module-docs embedding; nightly canary; org runner group + dispatch test bench; release sets; governance policies (maintainer lifecycle, deprecation RFCs).
   Beyond these phases, cross-embodiment generalization (platform modules, trait-based compatibility) is future work tracked in RFC #380 — sequenced only after phases 1–4 are proven.

Ranked success factors: (1) the CI-against-published-images loop, (2) contract governance/deprecation policy, (3) maintainer lifecycle policy. Everything else is buildable later; those three determine whether the ecosystem stays trustworthy.

Appendix: trunk facts an implementer needs

• .env VERSION="0.19.0-alpha.9" tags docker images; check-version-increment.yml gates PRs on semver bump.
• .github/workflows/docker-build.yml builds, pushes, cosign-signs all compose images on merge to main/develop when VERSION changes.
• System tests: tests/system/ (pytest marks in tests/pytest.ini: unit, build_docker, build_packages, integration, liveliness, sensors, takeoff_hover_land, autonomy, waypoint_flight); harness in tests/harness/ + tests/conftest.py; unit-test package list in tests/colcon_unit_test_packages.yaml (precedent for YAML-driven collection); metrics via tests/parse_metrics.py (diff-vs-baseline, exits 1 on regression); waypoint pass/fail via standalone tests/waypoint_checker.py.
• GPU CI: runs-on: [self-hosted, airstack-ephemeral] → OpenStack ephemeral VMs via .github/orchestrator/ (spawn loop, JIT tokens, cloud-init, reap loop). Fork PRs blocked from runners.
• Bringup: single entry robot/ros_ws/src/autonomy_bringup/launch/robot.launch.xml, role-dispatched by AUTONOMY_ROLE (full|onboard|offboard); per-layer bringups like robot/ros_ws/src/local/local_bringup/launch/ (where the variant explosion lives).
• Multi-robot: compose deploy.replicas: ${NUM_ROBOTS}; ROBOT_NAME/ROS_DOMAIN_ID resolved at container start by robot/docker/.bashrc + robot/docker/robot_name_map/resolve_robot_name.py.
• Standard topics (the rungs, today): /{robot}/odometry, /{robot}/global_plan, /{robot}/trajectory_controller/{trajectory_override,trajectory_segment_to_add,look_ahead,tracking_point,set_trajectory_mode}, /{robot}/tasks/{navigate,takeoff,land,fixed_trajectory}, /{robot}/interface/* — see docs/robot/autonomy/integration_checklist.md.
• Docs: MkDocs Material + mike versioning, same-dir plugin for out-of-tree READMEs, deploy workflows per branch (deploy_docs_from_{main,develop,release}.yaml).
• Candidate module sources: DFM2 fork at castacks org (disturbances under its simulation/), OptiTrack integration (natnet_ros2 exists in trunk today), custom global planner.

---

This RFC came out of a design brainstorm session (2026-08-04). Comments and pushback welcome — especially from anyone who'd author a module or maintain the registry.