new-agent
The new-agent command creates a structured sub-agent configuration file in the `.claude/agents/` directory with required frontmatter (name, description, tools, model) and role-specific body content (either a reviewer's checklist-based audit process or an architect's decision-framing approach). Use this when extending a ROS2 Claude Code workspace to add specialized code reviewers or design advisors that follow established conventions and are automatically indexed in CLAUDE.md and README.md for discoverability.
mkdir -p ~/.claude/commands && curl -fsSL https://raw.githubusercontent.com/harunkurtdev/ros2-claude-code-template/HEAD/.claude/commands/new-agent.md -o ~/.claude/commands/new-agent.mdnew-agent.md
Add a new sub-agent to this `.claude/` config.
Argument handling (`$ARGUMENTS`):
1. `<agent_name>` — `kebab-case` (required); becomes the file name and the
`subagent_type`.
2. `[role]` — `reviewer` (pre-PR diff auditor) or `architect` (design
advisor). Default `reviewer`.
3. `[domain]` — what it covers (e.g. "ros2_control controllers"). If
missing, ask.
If anything is unclear (which rules does it review against?), ask first.
Process:
1. Read the `extending_claude_config` skill (conventions + templates) and
skim a sibling agent of the same role
(`ros2-style-reviewer`/`vda5050-reviewer` for reviewers,
`clean-arch-architect`/`ecs-architect` for architects).
2. Verify `agents/<agent_name>.md` does not already exist.
3. Create `agents/<agent_name>.md` with:
* frontmatter: `name:`, `description:` (start with "Use proactively
before …"; end reviewers with "Returns a punch list with file:line
anchors, not a rewrite."), `tools:` (`["Bash","Read","Grep","Glob"]`
for read-only reviewers/architects), `model: sonnet`.
* body for a **reviewer**: a one-paragraph role statement that names
the `rules/` it grounds on, a **Process** (identify diff → cluster →
checklist → report), a **Checklist** organized by concern, and an
**Output format** (`Must fix` / `Should fix` / `Nice to have`, each
`file:line — observation — suggestion`). End with "Do not restate the
diff. Do not rewrite the patch. Stay short."
* body for an **architect**: trade-off framing, decision questions, and
"returns a recommendation with trade-offs, not implementation".
4. **Index it**: add a row to the **Sub-agents** table in
`.claude/CLAUDE.md` and to the `agents/` tree in `.claude/README.md`.
5. Print: file created + the index rows added.
Ground every reviewer checklist item in an actual rule/skill so the
feedback is concrete. Always update both indexes in the same change.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.