new-ros2-workspace

name: new_ros2_workspace description: Bootstrap a complete ROS 2 colcon workspace from scratch — directory layout, .gitignore, top-level README, this .claude/ config, an interfaces package and a first Clean Architecture package, and a bringup package. Trigger when the user asks to create a new workspace / start a new ROS 2 project from zero.

Bootstrapping a complete ROS 2 workspace

Use this when there is no workspace yet (the new_ros2_package skill assumes one already exists). The goal is a ready-to-build colcon workspace that already carries this template's .claude/ config, so every later /new-* command works immediately.

Target layout

<workspace>/
├── .claude/                     # this template's config (rules, skills, commands, agents)
├── .gitignore                   # ignores build/ install/ log/
├── README.md                    # how to build & run
├── src/
│   ├── <project>_interfaces/    # msgs/srvs/actions (ament_cmake), created first
│   ├── <project>_core/          # first Clean Architecture package
│   └── <project>_bringup/       # launch + params aggregator (ament_python)
├── build/   install/   log/     # generated by colcon (git-ignored)

Steps

1 — Create the workspace root + src/

mkdir -p <workspace>/src
cd <workspace>
git init      # optional but recommended

2 — Drop in the .claude/ config

Copy the template config so the workspace is self-documenting and the slash commands are available:

cp -r <path-to>/ros2-claude-code-template/.claude <workspace>/.claude

If the user is inside the template repo already, this step is a no-op.

3 — .gitignore

build/
install/
log/
__pycache__/
*.pyc

4 — Top-level README.md

Include the canonical bring-up commands:

colcon build --symlink-install
source install/setup.bash
colcon test && colcon test-result --all

5 — Seed packages (use the package skill / /new-package)

Create them in dependency order:

1. <project>_interfaces — only if custom msgs/srvs/actions are needed. ament_cmake + rosidl_default_generators (see rules/ros2_communication.md). Create this first.
2. <project>_core — the first real package, full Clean Architecture layout (domain/application/infrastructure/presentation). Delegate to the new_ros2_package skill or /new-package <name> <py|cpp>.
3. <project>_bringup — ament_python, holds top-level launch/ and config/ that compose the system (see ros2_launch_config).

6 — First build

cd <workspace>
colcon build --symlink-install
source install/setup.bash

Do not run the build automatically unless the user asks — print the commands instead.

Decisions to confirm with the user

• Workspace name / path (e.g. ~/my_robot_ws).
• Project prefix for package names (e.g. acme).
• Domains needed — if the project is a fleet bridge, a controller suite, a behavior-tree app, etc., point them at the matching command afterwards (/new-vda5050-connector, /new-controller, /new-bt-node, /new-nav2-plugin, …).
• ROS distro — affects nothing in the layout but note it in the README.

After bootstrap

The workspace now supports the full command set. Typical next steps:

Keep domain/ ROS-free, lifecycle by default for resource owners, and declare_parameter for every parameter — the rules in .claude/rules/ apply from the first commit.