ROS-Plan ROS 2 Toolchain

Expert guidance for working with the ROS-Plan project - a comprehensive ROS 2 toolchain providing declarative plan format, plan compilation, runtime process management, and launch file analysis tools.

Project Overview

ROS-Plan is a comprehensive ROS 2 toolchain that provides:

1. **Declarative plan format** - YAML-based node configuration with socket/link abstraction

2. **Plan compiler** - Transforms plans into executable ROS 2 launch files

3. **Runtime system** - Process management with graceful shutdown, restart policies, and dynamic parameter updates

4. **Metadata extraction** - launch2dump tool for analyzing existing launch files

5. **Launch conversion** - launch2plan tool for converting ROS 2 launch files to plan format

The project consists of both Rust (core compiler and runtime) and Python (launch file integration) components.

Project Status

**Current Phase**: Phase 12 (Launch-to-Plan Conversion) - In Progress

✅ 440 tests passing (330 Rust + 110 Python)

✅ Zero warnings (clippy + compiler)

✅ 54 features implemented across 11 phases

✅ Phase 8 Complete: Metadata tracking with TODO completion detection

⏳ Phase 9-12: Validation, end-to-end testing, QoS, recursive conversion (not yet started)

See `book/src/launch2plan.md` for complete design and progress tracking.

Core Architecture

Rust Crates (Workspace)

1. **ros-plan-format** - Data structures and parsing for ROS plan files (YAML format)

- Handles node definitions, links, sockets, parameters, QoS settings

- Key types: `Plan`, `Node`, `Link`, `NodeSocket`, `PlanSocket`

- Custom YAML tags: `!pub`, `!sub`, `!pubsub`, `!i64`, `!f64`, `!bool`, `!path`, `!expr`

2. **ros-plan-compiler** - Core compilation logic

- Main entry point: `Compiler::compile()`

- Evaluation, linking, program generation

- Lua integration for dynamic expressions

- Link resolution and validation

3. **ros-plan-runtime** - Process management and lifecycle

- Node spawning with ROS 2 arguments

- Graceful shutdown (SIGTERM → SIGKILL)

- Restart policies: Never, Always, OnFailure

- Dynamic parameter updates with program diffing

- Launch include tracking and reloading

- Status reporting (table and JSON formats)

- Event logging with circular buffer

4. **ros2plan** - CLI tool

- Commands: `compile`, `run` (with runtime)

- Usage: `ros2plan compile <plan-file> [args]`

5. **ros-utils** - ROS 2 integration utilities

- Package and executable resolution via `ros2` CLI

- Node command-line generation with remapping

Python Components

**launch2dump** - Metadata extraction from ROS 2 launch files

- Extracts nodes, parameters, remappings, containers

- JSON/YAML output formats

- Uses UV for dependency management

**ros2-introspect** - ROS 2 node interface introspection

- Discovers publishers, subscriptions, services, clients without middleware

- Uses rmw_introspect_cpp RMW implementation

- Requires workspace to be built and sourced

**launch2plan** - Launch-to-Plan conversion tool (Phase 12)

- Converts ROS 2 launch files to ROS-Plan YAML format

- Socket inference from introspection and remappings

- Conditional branch exploration with `when` clauses

- Automatic link generation from topic connections

- Argument type inference from default values

- Include handling with cycle detection

- Metadata tracking with TODO completion detection

External Dependencies

**rmw_introspect** - Git submodule at `external/rmw_introspect/`

- C++ RMW implementation for lightweight introspection

- Python wrapper for ROS 2 node introspection

- Built automatically via `make build` using colcon

- Required by launch2plan for node interface introspection

Instructions for AI Agent

When working with this codebase, follow these guidelines:

1. Before Making Changes

**Read documentation first**: Check relevant files in `book/src/` before modifying code

**Understand architecture**: Review the Core Architecture section above

**Check project status**: Verify which phase is active and what's complete

**Review test coverage**: Ensure you understand existing test patterns

2. Development Workflow

**Build the project:**

```bash

make build

```

**Run tests frequently:**

```bash

make test

```

**Check code quality:**

```bash

make lint

```

**Run specific crate tests:**

```bash

cargo nextest run -p ros-plan-compiler --cargo-profile release-with-debug

```

3. Code Patterns to Follow

**Value Types:**

```rust

// Use the Value enum from ros-plan-format

pub enum Value {

I64(i64),

F64(f64),

Bool(bool),

String(String),

Path(PathBuf),

Expr(String), // Lua expression

}

```

**Socket References in YAML:**

```yaml

link:

camera_image: !pubsub

src: ["camera/image"] # Node ID "camera", socket "image"

dst: ["detector/image"] # Node ID "detector", socket "image"

```

**When Clauses (Conditional Compilation):**

```yaml

node:

optional_node:

pkg: my_pkg

exec: my_node

when: "$(enable_feature)" # Lua expression

```

**Restart Policies:**

```rust

pub enum RestartPolicy {

Never,

Always { backoff: Duration },

OnFailure { max_retries: u32, backoff: Duration },

}

```

4. Testing Guidelines

**Run all tests before committing**: `make lint && make test` must pass

**Python tests require ROS 2**: Makefile automatically sources workspace

**Use cargo-nextest**: All Rust tests run with `release-with-debug` profile

**Zero tolerance for warnings**: Clippy runs with `-D warnings`

**Test structure**:

- 330 Rust tests (format, compiler, runtime, CLI, ros-utils)

- 110 Python tests (25 launch2dump + 9 ros2-introspect + 85 launch2plan)

5. Python Development

**Install dependencies:**

```bash

cd python && uv sync

```

**Run launch2dump:**

```bash

cd python/launch2dump && uv run launch2dump <launch-file>

```

**Run ros2-introspect (requires workspace sourced):**

```bash

source install/setup.bash

cd python/ros2-introspect && uv run ros2-introspect <package> <executable>

```

**Run launch2plan (requires workspace sourced):**

```bash

source install/setup.bash

cd python/launch2plan && uv run launch2plan convert <launch-file>

```

6. Critical Makefile Pattern

**IMPORTANT**: Each line in a Makefile target runs in a separate shell. Environment sourcing must be on the same line as commands that need it.

**Correct:**

```makefile

. install/setup.sh && cd python/launch2plan && uv run pytest

```

**Incorrect:**

```makefile

. install/setup.sh && \

cd python/launch2plan && \

uv run pytest

```

7. Phase 12 (launch2plan) Implementation

Current implementation follows incremental phase-by-phase approach:

**Completed Phases:**

✅ Phase 1-5: Foundation, introspection, socket inference, argument handling, plan generation

✅ Phase 6: Conditional branch exploration (18 tests)

✅ Phase 7: Include handling & plan hierarchy (8 tests)

✅ Phase 8: Metadata tracking with TODO completion detection (13 tests)

**Remaining Phases:**

⏳ Phase 9: Validation & error handling

⏳ Phase 10: End-to-end integration testing

⏳ Phase 11: QoS policy conversion

⏳ Phase 12: Recursive conversion

**When implementing new phases:**

Follow the design in `book/src/launch2plan.md`

Add tests for each feature incrementally

Update phase completion status in documentation

Ensure all tests pass before moving to next phase

8. File Location Reference

**Key Format Files:**

`crates/ros-plan-format/src/lib.rs` - Plan data structures

`crates/ros-plan-format/src/value.rs` - Value type definitions

**Key Compiler Files:**

`crates/ros-plan-compiler/src/compiler.rs` - Main compilation logic

`crates/ros-plan-compiler/src/eval.rs` - Lua expression evaluation

**Key Runtime Files:**

`crates/ros-plan-runtime/src/runtime.rs` - Process management

`crates/ros-plan-runtime/src/program_diff.rs` - Parameter change detection

**Key Python Files:**

`python/launch2plan/launch2plan/builder.py` - Plan generation logic

`python/launch2plan/launch2plan/metadata.py` - Metadata tracking

`python/launch2plan/launch2plan/introspect.py` - Socket inference

**Documentation:**

`book/src/roadmap.md` - Implementation status

`book/src/plan-format.md` - YAML specification

`book/src/launch2plan.md` - Phase 12 design

9. Common Tasks

**Compile a plan file:**

```bash

cargo run --bin ros2plan -- compile examples/introduction.yaml

```

**Run with runtime:**

```bash

cargo run --bin ros2plan -- run examples/introduction.yaml

```

**Convert launch file to plan:**

```bash

source install/setup.bash

cd python/launch2plan && uv run launch2plan convert <launch-file>

```

**Check conversion status:**

```bash

cd python/launch2plan && uv run launch2plan status <plan-file>

```

10. Important Implementation Details

**Socket/link abstraction**: Decouples node definitions from topic names

**Lua integration**: Used for dynamic expression evaluation in plan files

**Transparent includes**: Support multi-level socket forwarding

**Node identifiers**: Use identifiers (not names) for references

**Graceful shutdown**: SIGTERM → wait → SIGKILL pattern

**Program diffing**: Detects parameter changes for selective restarts

**Dependency checking**: Explicit error messages for missing ROS 2 or rmw_introspect_cpp

11. Before Committing

Always ensure:

1. `make lint` passes (formatting + clippy with `-D warnings`)

2. `make test` passes (all 440 tests)

3. Documentation updated if behavior changes

4. Phase tracking updated in `book/src/launch2plan.md` for Phase 12 work

Examples

**Example Plan File:**

```yaml

node:

camera:

pkg: camera_driver

exec: camera_node

socket:

image: !pub

detector:

pkg: object_detector

exec: detector_node

socket:

image: !sub

link:

camera_image: !pubsub

type: sensor_msgs/msg/Image

src: ["camera/image"]

dst: ["detector/image"]

```

**Example Restart Policy:**

```yaml

node:

resilient_node:

pkg: my_pkg

exec: my_node

restart: !on_failure

max_retries: 3

backoff_secs: 5

```

Notes

The project uses a Makefile for common tasks - use `make help` to see all targets

Rust code uses `release-with-debug` profile for test performance

Python packages managed with UV (migrated from Rye)

All Python tests requiring ROS 2 environment are handled by Makefile

rmw_introspect is a git submodule - update with `git submodule update --init --recursive`

ROS-Plan ROS 2 Toolchain

ROS-Plan ROS 2 Toolchain

Project Overview

Project Status

Core Architecture

Rust Crates (Workspace)

Python Components

External Dependencies

Instructions for AI Agent

1. Before Making Changes

2. Development Workflow

3. Code Patterns to Follow

4. Testing Guidelines

5. Python Development

6. Critical Makefile Pattern

7. Phase 12 (launch2plan) Implementation

8. File Location Reference

9. Common Tasks

10. Important Implementation Details

11. Before Committing

Examples

Notes

Reviews (0)