new-bt-node
Scaffold a Behavior Tree leaf node — plain BehaviorTree.CPP (sync/stateful/condition) or a BehaviorTree.ROS2 wrapper (action/service/topic) — with ports, registration, and an XML usage snippet.
mkdir -p ~/.claude/commands && curl -fsSL https://raw.githubusercontent.com/harunkurtdev/ros2-claude-code-template/HEAD/.claude/commands/new-bt-node.md -o ~/.claude/commands/new-bt-node.mdnew-bt-node.md
Scaffold a behavior-tree node inside an existing package.
Argument handling (`$ARGUMENTS`):
1. `<package>` — existing package under `src/` (required).
2. `<ClassName>` — CamelCase node class (required).
3. `<kind>` — one of:
* `sync` → `BT::SyncActionNode` (finishes in one tick)
* `stateful` → `BT::StatefulActionNode` (async; onStart/onRunning/onHalted)
* `condition` → `BT::ConditionNode`
* `ros-action` → `BT::RosActionNode<ActionT>`
* `ros-service` → `BT::RosServiceNode<ServiceT>`
* `ros-topic-pub` → `BT::RosTopicPubNode<MsgT>`
* `ros-topic-sub` → `BT::RosTopicSubNode<MsgT>`
For the `ros-*` kinds, also ask for the interface type (e.g.
`btcpp_ros2_interfaces/action/Sleep`). For Nav 2-specific BT nodes, use
`/new-nav2-plugin bt_node` instead.
If anything is missing, ask before scaffolding.
Process:
1. Read the skill `behaviortree_node_creation` and the rules
`behaviortree_cpp.md` (plain) / `behaviortree_ros2.md` (ros-*). Mirror
the closest sample (`~/nav2_ws/src/BehaviorTree.CPP/sample_nodes/` or
`~/nav2_ws/src/BehaviorTree.ROS2/btcpp_ros2_samples/src/`).
2. Create:
* `include/<package>/<snake_class>.hpp` — the class deriving from the
chosen base, with `static providedPorts()` (use `providedBasicPorts`
for ros-* wrappers) and the required overrides:
- sync/condition: `tick()`
- stateful: `onStart()`, `onRunning()`, `onHalted()`
- ros-action: `setGoal()`, `onResultReceived()`, `onFeedback()`,
`onFailure()`, `onHalt()`
- ros-service: `setRequest()`, `onResponseReceived()`, `onFailure()`
- ros-topic-pub/sub: `setMessage()` / message handler
* `src/<snake_class>.cpp` — implementation (non-blocking ticks!).
3. Registration:
* plain → `BT_REGISTER_NODES(factory){ factory.registerNodeType<Class>("Name"); }`
* ros-* → `CreateRosNodePlugin(Class, "Name")` (uses `RosNodeParams`).
* Or register directly in the executor with `registerNodeType<Class>(...)`.
4. `CMakeLists.txt` / `package.xml`: dep `behaviortree_cpp` (+
`behaviortree_ros2` and the message package for ros-*); build the
plugin as a shared lib if registering via plugin.
5. Add an XML usage snippet (`BTCPP_format="4"`) and, where useful, a
gtest that ticks the node.
6. `pre-commit run --files <touched files>`.
7. Print: files created and the XML tag + how to register it.
Never block inside `tick()`/`onRunning()`; return `RUNNING` and resume on
the next tick. `onFeedback()` must not return `IDLE`.Use proactively before opening a PR that adds or changes BehaviorTree.CPP nodes or BehaviorTree.ROS2 wrappers (RosActionNode/RosServiceNode/RosTopicPub/SubNode, TreeExecutionServer). Reviews a diff against BT.CPP v4 conventions — node base-class choice, non-blocking ticks, ports/blackboard typing, factory/plugin registration, XML v4, and the ROS 2 wrapper contract. Returns a punch list with file:line anchors, not a rewrite.
Use when a design decision touches Clean Architecture boundaries in a ROS 2 project — which layer a new behaviour belongs to, whether a port belongs in domain or application, whether a new node should be lifecycle-managed, whether to compose nodes or split packages. Returns an architectural recommendation with trade-offs, not implementation.
Use when a design decision touches the gz-sim ECS — where new state should live, which system phase should write it, how to avoid coupling, whether to add a component vs. a member variable, whether a new system should be split or merged with an existing one. Returns an architectural recommendation with trade-offs, not implementation.
Use proactively before opening any gz-sim PR. Reviews a diff against the project's C++17 style, ECS conventions, plugin registration patterns, CMake structure, test placement, Migration.md / Changelog.md expectations, and pre-commit configuration. Returns a punch list, not a rewrite.
Use proactively before opening a PR that adds or changes a ros2_control controller, broadcaster, or hardware component (incl. URDF <ros2_control> bringup). Reviews a diff against ros2_controllers / ros2_control_demos conventions — controller & hardware lifecycle, command/state interface configuration, real-time safety of update()/read()/write(), generate_parameter_library usage, pluginlib registration, chainable-controller correctness, URDF wiring, and tests. Returns a punch list with file:line anchors, not a rewrite.
Use proactively before opening any ROS 2 / Nav 2 PR. Reviews a diff against this template's Clean Architecture, ROS 2 communication, lifecycle, testing, and Nav 2 plugin conventions. Returns a punch list with file:line anchors, not a rewrite.
Use proactively before opening a PR that touches a VDA 5050 connector / fleet bridge. Reviews a diff against VDA 5050 v3.0.0 protocol compliance (topics, QoS, header rules, base/horizon, action state machine, schema validation) and the template's Clean Architecture for the MQTT↔Nav 2 bridge. Returns a punch list with file:line anchors, not a rewrite.
Build the colcon workspace (optionally a single package) and report the outcome.