name: ackermann-rover-stack description: Use when working in the ackermann_rover_humble repository or changing its Docker, Gazebo, RTAB-Map, Nav2, ros2_control, RealSense, PX4, rover monitoring, Control Center, tmux session, or verification flows. Provides the repo-specific subsystem map, launch/script entrypoints, architecture references, and mandatory validation workflow.

Ackermann Rover Stack

Use this skill for any task in this repository. Start by reading references/project_memory.md. Open the relevant ADR or architecture doc before changing public behavior, topic names, frames, or launch sequencing.

Workflow

1. On the host, run source ~/.bashrc before any Docker command. The compose stack depends on exported ARCH, USERNAME, USER_UID, and USER_GID. In non-interactive automation, .bashrc may return before exporting them; if Compose still shows blank variables, load .env and export ARCH, USERNAME, USER_UID, and USER_GID explicitly before invoking Compose.
2. First consider the repo's scripts/ entrypoints before using raw docker compose, ros2 launch, or ad hoc shell commands. In practice, many day-to-day workflows are wrapped by scripts/lib/dc.sh, scripts/start_*.sh, scripts/stop_all.sh, and scripts/verify_*, so inspect the matching script before reproducing a launch sequence manually.
3. Manage the environment with docker-compose -f docker/docker-compose.yml ... as described in AGENTS.md when a script does not already encode the desired workflow.
4. Run ROS build, test, launch, and debugging commands inside ackermann_slam. Treat the host-side control_center/ stack separately from the in-container rover stack.
5. Before declaring a task done, follow the repo validation contract in AGENTS.md, .agent/instructions.md, and scripts/verify_agent_work.sh. Always shut down launches and containers you started.

Mental Model

• robot_bringup is the top-level composition layer. It selects simulation vs hardware, depth camera choice, optional RTAB-Map, optional Nav2, optional PX4 SITL, RViz, and rover monitoring.
• description_robot owns the URDF, Gazebo world, ROS-Gazebo bridges, and ros2_control/PX4-SITL joint control plumbing.
• rtabmap_bringup owns RGB-D sync, IMU frame conditioning, VIO or ICP odometry, EKF fusion, RTAB-Map SLAM/localization, depth-to-scan, and obstacle point cloud generation.
• ackermann_nav2_bringup owns the Nav2 stack with MPPI + Smac Hybrid and remaps odom consumption to /odometry/filtered.
• px4_bringup owns the PX4 DDS/MAVLink bridges and the custom px4_ros2_interface_lib modes.
• realsense_camera_bringup owns D435i/L515/T265 startup and T265 odom relay behavior for hardware mode.
• rover_monitor is the health/telemetry monitoring subsystem.
• control_center is the host-side base-station subsystem. It consumes rover_monitor telemetry over MQTT/Protobuf, serves a FastAPI + React dashboard, stores history in InfluxDB, gates outbound commands, and tracks command ACKs.
• scripts/ is a first-class operational layer, not just miscellaneous helpers. scripts/lib/dc.sh normalizes Compose usage, and the start_*, stop_all.sh, verify_*, and test scripts encode the canonical launch, tmux-session, and smoke-test workflows.
• When deciding how to reproduce, launch, build, verify, or tear down the stack, prefer the existing script in scripts/ first and fall back to raw commands only when no script covers the workflow.
• ackermann_control and safety are small focused nodes with their own parameters and tests.

Read These First For Common Task Types

• Launch orchestration, topics, TF, startup ordering: docs/architecture/overview.md, docs/architecture/interfaces.md, docs/architecture/node_graph.md
• PX4 mode or odometry bridge work: docs/architecture/px4_overview.md, docs/decisions/ADR-004-rover-manual-mode.md, docs/decisions/ADR-005-rover-speed-steering-mode.md, docs/decisions/ADR-006-rover-speed-attitude-mode.md, docs/decisions/ADR-008-px4-odometry-frames.md
• Gazebo / ros2_control joint behavior: docs/decisions/ADR-007-steering-joint-control.md
• Nav2 behavior and tuning: docs/architecture/nav2_overview.md, docs/decisions/ADR-002-nav2.md
• Host-side monitoring and command flows: docs/architecture/control_center.md, docs/architecture/system_monitor.md
• Operational entrypoints and smoke tests: scripts/lib/dc.sh, scripts/start_ros2_nodes.sh, scripts/start_px4_sitl.sh, scripts/start_microxrce_agent.sh, scripts/start_px4_bringup_vo.sh, scripts/start_host_session.sh, scripts/start_system_monitor_session.sh, scripts/test_control_center.sh, scripts/verify_agent_work.sh
• Safety expectations: docs/requirements/safety.md, docs/decisions/ADR-003-safety.md

Debugging Defaults

• ROS graph: ros2 topic list, ros2 topic hz, ros2 node list, ros2 lifecycle get
• TF: ros2 run tf2_ros tf2_echo ..., ros2 run tf2_tools view_frames
• Gazebo transport: gz topic -l, gz topic -e -t <topic>
• Controller state: ros2 control list_controllers, ros2 control list_hardware_interfaces

Keep changes aligned with existing docs. If you intentionally change interfaces, launch semantics, frames, or requirements, update the architecture docs and ADRs in the same task.