ROS 2 Agent Workspace

Vision

This workspace exists to help develop robust, well-documented, and well-tested ROS 2 packages using AI agent assistance.

The immediate goal is practical: build reliable autonomous marine systems — starting with uncrewed surface vessels that can safely survey an area of the seafloor without operator intervention. That demands software that is robust in the face of real-world conditions, reliable enough to operate without intervention, and easy to deploy.

Agent-assisted development is the means, not the end. The workspace provides the infrastructure — worktree isolation, build tooling, agent instructions, quality enforcement — that makes AI agents effective contributors to ROS 2 projects. The workspace should improve over time, informed both by experience from real project use and by evolving practices in the agentic coding domain. The measure of improvement is whether projects get better faster — not whether the workspace itself is more sophisticated.

What "better packages" means in practice:

Well-documented — useful to teammates, contributors, and the broader ROS 2 community
Well-tested — reliable enough for real-world deployment
Maintainable — clear code and documentation that others can work with
Distribution-ready — packageable for rosdep installation, visible in the ROS ecosystem

The workspace infrastructure is project-agnostic by design. While its primary project is UNH marine autonomy, the tooling generalizes to any ROS 2 project. This is intentional — it makes the workspace useful beyond its origin, encourages contributions from other domains, and ensures the infrastructure doesn't become coupled to any single project.

About

This repository provides management of multiple layered ROS 2 workspaces, configured for use with AI agents. It is developed by the Center for Coastal and Ocean Mapping / Joint Hydrographic Center (CCOM/JHC) at the University of New Hampshire (UNH) -- a national center of expertise in ocean mapping and hydrographic sciences.

As currently configured, the workspace hosts the UNH Marine Autonomy Framework, automatically importing repositories from the project's manifest repository (unh_marine_autonomy):

Project11: Main autonomy system.
Marine AIS: AIS message decoding and handling.
UNH Marine Navigation: Navigation tools and utilities.
Mission/Helm Managers: Core logic for autonomy control.

Quick Start

For AI Agents

Each framework has a self-contained instruction file with all rules inline:

Claude Code: CLAUDE.md (auto-loaded)
GitHub Copilot: .github/copilot-instructions.md
Gemini CLI: .agent/instructions/gemini-cli.instructions.md
Other/Unknown: .agent/AI_RULES.md

For Human Users

New to this workspace? See QUICKSTART.md for a step-by-step setup guide.

Experienced users? Jump to Usage below.

For Containerized/Custom Agents

See .agent/AGENT_ONBOARDING.md for setup instructions.

Sandboxed Development (Recommended)

This workspace supports DevContainers, allowing you to run the entire environment in a Docker container. This is the preferred method for AI Agents and users who want a clean, safe setup.

GitHub Codespaces: Open this repo in Codespaces for a zero-setup cloud desktop.
VS Code Local: Install the "Dev Containers" extension and choose "Reopen in Container".

Documentation

For AI Agents

📋 CLAUDE.md - Claude Code operational rules (auto-loaded)
📋 AI Rules - Universal fallback rules
🌲 Worktree Guide - Parallel development with git worktrees
📚 Agent Onboarding - Onboarding for containerized agents

For All Users

📚 Quick Start Guide - Get up and running in minutes
🏗️ Architecture Guide - Understanding the layered workspace system
🤝 Contributing Guide - Development workflow and best practices
🔒 Security Policy - Security guidelines and reporting

Structure

.agent/: Agent infrastructure (scripts, hooks, knowledge, templates, identity).
configs/: Bootstrap URL, manifest symlink to project config, optional manifest_repo/ clone.
.agent/scripts/: Helper scripts for setup and environment sourcing.
layers/: The ROS 2 workspace layers (source code and build artifacts).

Usage

1. Setup Layers

To initialize workspace layers:

# Auto-setup all layers (recommended)
./.agent/scripts/setup_layers.sh

# Or setup specific layer
./.agent/scripts/setup_layers.sh core

This will:

Bootstrap the manifest repository (if needed) and create configs/manifest symlink
Read layer definitions from configs/manifest/layers.txt
Import repositories from configs/manifest/repos/<layer>.repos files

2. Sourcing the Environment

To source the layers in the correct order (Underlay -> ... -> Overlay):

source .agent/scripts/setup.bash

Getting Started for Humans (Agentic Coding)

This workspace is designed to be used with an AI Agent. If you are new to agentic coding, here is how you should interact with this repository:

Just Ask: The agent is capable of managing the entire lifecycle of the workspace. You can ask it to "add a repo", "build the workspace", or "fix this build error".
Agent Instructions: Each agent framework has a self-contained instruction file (e.g., CLAUDE.md) with all rules and a script reference table. Common operations include building (make build), testing (make test), and status checking (make dashboard).
Let the Agent Drive: The agent is aware of the directory structure (layers in layers/, manifest config at configs/manifest/). Trust it to place files in the correct location.

Using with Custom Projects

This workspace can be configured to bootstrap from a manifest repository of your choice. The manifest repo provides layer definitions (.repos files) and optionally project-specific agent context.

Create a configs/project_bootstrap.url file containing the raw URL to your bootstrap configuration:
```
https://raw.githubusercontent.com/your-org/your-repo/main/config/bootstrap.yaml
```
[!CAUTION] Security Warning: executes code (via vcs import) based on the configuration downloaded from this URL. Ensure you trust the source URL and that it is not compromised. Always use HTTPS.
Ensure your manifest repo has the following structure:
- config/bootstrap.yaml:
```
git_url: https://github.com/your-org/your-repo.git
branch: main
# layer: core          # If your repo also contains ROS packages (Pattern B)
# config_path: config  # Defaults to "config" if omitted
```
- config/repos/: Directory containing .repos files (e.g., core.repos, ui.repos).
- config/layers.txt: Layer names in source order (one per line).
- .agents/workspace-context/ (optional): Project-specific AI agent knowledge (at repo root, not under config/).
Run ./.agent/scripts/setup_layers.sh to import all repositories defined in your manifest repo.

Pattern A vs Pattern B: If your manifest repo is config-only (no ROS packages), omit the layer field. It will be cloned to configs/manifest_repo/. If it also contains ROS packages, set layer to the target layer (e.g., core) and it will be cloned into that layer's src/ directory.

Adding New Layers

Create a <new_layer>.repos file in the manifest repo's config/repos/ directory.
Add the layer name to config/layers.txt in the manifest repo.
Run ./.agent/scripts/setup_layers.sh to set up all layers (including the new one).

Troubleshooting

Common Issues

VCS Command Not Found

If you see "vcs command not found":

pip install vcstool
# or
sudo apt install python3-vcstool

ROS 2 Jazzy Not Found

Ensure ROS 2 Jazzy is installed:

./.agent/scripts/bootstrap.sh

Build Failures

Check the build report: cat .agent/scratchpad/build_report.md
Try rebuilding all layers:
```
make build
```

Check for missing dependencies:

rosdep install --from-paths layers/main/core_ws/src --ignore-src -r -y

Workspace Locked

If you see "Workspace is LOCKED":

./.agent/scripts/unlock.sh

Environment Not Sourced

If ROS commands aren't working:

source .agent/scripts/setup.bash

Permission Denied

Make sure scripts are executable:

chmod +x .agent/scripts/*.sh

Getting Help

Review ARCHITECTURE.md for system design
Check CONTRIBUTING.md for development guidelines
See SECURITY.md for security policies
Open an issue on GitHub for bugs or feature requests

Development Tools

Makefile

Common operations are available via make:

make help            # Show all available targets
make build           # Build all layers (auto-setup on first run)
make test            # Run all tests
make lint            # Run pre-commit hooks on all files
make clean           # Clean build artifacts and reset stamps
make setup-all       # Run full setup without building
make dashboard       # Unified workspace status (worktrees, PRs, health)
make dashboard QUICK=1  # Quick local-only mode
make validate        # Validate workspace config (CI-oriented)

Claude Code users: All .PHONY Makefile targets (except help) are available as /make_* slash commands (e.g., /make_build, /make_test, /make_dashboard). Run make generate-skills to regenerate them after Makefile changes.

Helper Scripts

verify_change.sh: Targeted verification (unit/lint) for a specific package.
dashboard.sh: Unified workspace status with --quick, --skip-sync, and --skip-github flags.

IDE Setup

VS Code Setup Guide: Multi-root workspace, build tasks, C++/Python IntelliSense configuration.

Pre-commit Hooks

Pre-commit hooks are auto-installed on first make lint (via the stamp chain):

make lint         # installs pre-commit if needed, then runs all hooks

Validation

Validate configuration files:

python3 .agent/scripts/validate_repos.py

Name	skill-importer
Description	Standardized procedure to import external skills (e.g. from anthropics/skills) into the workspace.

skill-importer

SKILL.md

ROS 2 Agent Workspace

Vision

About

Quick Start

For AI Agents

For Human Users

For Containerized/Custom Agents

Sandboxed Development (Recommended)

Documentation

For AI Agents

For All Users

Structure

Usage

1. Setup Layers

2. Sourcing the Environment

Getting Started for Humans (Agentic Coding)

Using with Custom Projects

Adding New Layers

Troubleshooting

Common Issues

VCS Command Not Found

ROS 2 Jazzy Not Found

Build Failures

Workspace Locked

Environment Not Sourced

Permission Denied

Getting Help

Development Tools

Makefile

Helper Scripts

IDE Setup

Pre-commit Hooks

Validation