ccg-ros2-workflow

CCG-ROS2 - Claude + Codex + Antigravity ROS2 Multi-Model Collaboration

简体中文 | English

CCG-ROS2 is a workflow engine for Claude Code that orchestrates multiple AI models (Codex for low-level control, Antigravity for upper-layer application, Claude for orchestration) with hook-based state tracking, automatic strategy selection, and Agent Teams parallel execution — specialized for ROS2 robotics development.

Fork from fengshao1227/ccg-workflow v3.1.0, customized for ROS2 Humble robotics development.

What's new in v3.0.0 (ROS2 Edition)

v3.0.0 brings the powerful v3.1.0 engine to ROS2 development with domain-specific enhancements:

• ROS2-aware routing — Upper-layer tasks (Launch files, Python nodes, RViz, simulation) route to Antigravity. Low-level tasks (C++ nodes, hardware drivers, real-time control) route to Codex.
• 7-phase workflow — Extended from 6 phases with dedicated hardware deployment phase (deployment scripts, hardware dependency checks, Gazebo simulation validation).
• ROS2 system integrator — Replaces UI/UX designer with system-integrator agent specialized in ROS2 node architecture, Topic/Service design, and QoS configuration.
• ROS2 domain skills — Perception (LiDAR/camera/point cloud), control (PID/trajectory/motor drivers), navigation (Nav2/SLAM/path planning), manipulation (MoveIt/grasp planning), hardware integration (CAN/serial/sensor drivers).
• Codex Mode for ROS2 — Codex-led orchestration with ROS2 context (node boundaries, message selection, QoS decisions).
• All v3.1.0 features — Hook engine, task persistence, Agent Teams, quality gates, domain knowledge hooks, Codex-Led Mode.

Quick Start

npx ccg-ros2-workflow

Requirements: Node.js 20+, Claude Code CLI
Optional: Codex CLI (low-level control), Antigravity CLI (upper-layer application)

The installer walks through 4 steps: API config, model routing, MCP tools, performance mode.

How it works (ROS2 Example)

You: /ccg:go implement autonomous navigation for differential drive robot

CCG-ROS2 Engine:
  1. Reads ROS2 project context (package.xml, colcon workspace, launch files)
  2. Classifies: feature / XL complexity / mixed (upper+lower) / high risk
  3. Selects strategy: full-collaborate
  4. Creates .ccg/tasks/autonomous-navigation/task.json
  5. Launches dual-model analysis:
     - Codex: motor driver, odometry, low-level control
     - Antigravity: Nav2 config, launch files, RViz setup
  6. Produces plan with node architecture + QoS design → HARD STOP for approval
  7. Spawns Agent Teams Builders for parallel implementation
  8. Runs quality gates (verify ROS2 message definitions, QoS policies, lifecycle)
  9. Hardware deployment phase: generates deployment scripts, checks CAN/serial, Gazebo sim
  10. Reports results

Every turn, a hook injects:
  <ccg-state>
  Task: autonomous-navigation (in_progress)
  Strategy: full-collaborate
  Phase: 4-implementation
  ROS2 Context: colcon workspace, 3 packages, Nav2 stack
  Next: Layer 1 Builders executing (motor_driver_node + nav2_config)
  </ccg-state>

ROS2 Model Routing

Model	Role	Suitable for
Codex	Low-level Control Authority	C++ nodes, hardware drivers, real-time control algorithms, message definitions
Antigravity	Upper-layer Application Authority	Launch files, Python nodes, RViz configuration, simulation setup
Claude	Orchestration + Delivery	Plan approval, code writing, quality control

Strategies (ROS2-aware)

The engine picks a strategy based on task type and complexity, with ROS2-specific context:

Strategy	When	External models	Teams	ROS2 Context
direct-fix	Simple bug, single file	No	No	Node crash, topic mismatch
quick-implement	Small feature, clear scope	No	No	Add parameter, simple service
guided-develop	Medium feature, needs planning	Single model	No	New node, message definition
full-collaborate	Complex feature, multi-module	Dual model parallel	Yes	Navigation stack, perception pipeline
debug-investigate	Complex bug, unknown cause	Dual model diagnosis	No	QoS mismatch, lifecycle issue
refactor-safely	Code restructuring	Dual model review	No	Node splitting, message refactor
deep-research	Technical research, comparison	Dual model exploration	No	SLAM algorithm, control strategy
optimize-measure	Performance optimization	Optional	No	CPU/memory, QoS tuning
review-audit	Code review	Dual model cross-review	No	QoS policies, lifecycle, safety
git-action	commit, rollback, branches	No	No	Standard git operations

Simple tasks run fast with no overhead. Complex ROS2 tasks get the full engine with hardware deployment phase.

Commands

Smart Entry Point

Command	Description
/ccg:go	Describe what you want in plain language. The engine analyzes your intent, picks the right strategy, and executes it.

ROS2 Development Workflow (Legacy Commands)

Command	Description
/ccg:workflow	7-phase complete workflow (with hardware deployment)
/ccg:plan	Multi-model collaborative planning (Phase 1-2)
/ccg:execute	Multi-model collaborative execution (Phase 3-5)
/ccg:frontend	Upper-layer application focus (Antigravity-led: Launch/Python/RViz)
/ccg:backend	Low-level control focus (Codex-led: C++/drivers/real-time)
/ccg:feat	Smart feature development
/ccg:analyze	Dual-model technical analysis
/ccg:debug	Multi-model problem diagnosis
/ccg:optimize	Multi-model performance optimization
/ccg:test	Smart test generation
/ccg:review	Dual-model code review
/ccg:enhance	Prompt enhancement
/ccg:init	Initialize CLAUDE.md

OpenSpec Specification-Driven

Command	Description
/ccg:spec-init	Initialize OPSX environment
/ccg:spec-research	Requirements → Constraint set
/ccg:spec-plan	Constraints → Zero-decision plan
/ccg:spec-impl	Execute by specification + archive
/ccg:spec-review	Dual-model cross-review

Agent Teams Parallel Implementation

Command	Description
/ccg:team	Unified workflow (recommended) — 8-phase full process with 7-role auto-orchestration
/ccg:team-research	Parallel constraint set research (Codex low-level + Antigravity upper-layer)
/ccg:team-plan	Zero-decision parallel implementation plan
/ccg:team-exec	Spawn Builder teammates for parallel coding
/ccg:team-review	Dual-model cross-review implementation output

Git Tools

Command	Description
/ccg:commit	Smart Git commit (conventional commit)
/ccg:rollback	Interactive Git rollback
/ccg:clean-branches	Clean merged branches
/ccg:worktree	Worktree management

Project Management

Command	Description
/ccg:context	Project context management (.context initialization/log/compress/history)
/ccg:codex-exec	Codex full execution plan (MCP + code + tests)

7-Phase ROS2 Workflow

Research → Ideation → Planning → Execution → Optimization → Review → Hardware Deployment

• Phase 1-2 (Research/Ideation): Codex + Antigravity parallel analysis, dual-perspective evaluation
• Phase 3 (Planning): Claude synthesizes solution, user approval then archive
• Phase 4 (Execution): Claude leads code implementation
• Phase 5 (Optimization): Codex + Antigravity parallel review, Claude integrates fixes
• Phase 6 (Review): Final quality control
• Phase 7 (Hardware Deployment): Generate deployment scripts, check hardware dependencies (serial/CAN/sensors), Gazebo simulation validation

Architecture

Claude (Orchestration + Final Code Writing)
  ├── Codex      → Read-only, returns patch (Low-level: C++/drivers/real-time)
  └── Antigravity → Read-only, returns patch (Upper-layer: Launch/Python/RViz)

External models have zero write permissions to the filesystem. All code is reviewed by Claude before landing.

Sub-Agents

Agent	Purpose
system-integrator	ROS2 system integration designer (node architecture/Topic-Service/QoS design)
planner	ROS2 task planner (WBS decomposition)
init-architect	Project initialization architect
get-current-datetime	Get current time
team-architect	Team architect (v3.0+)
team-qa	QA engineer (v3.0+)
team-reviewer	Code reviewer (v3.0+)

Output Styles

After installation, choose AI output style via output-styles directory:

• engineer-professional - SOLID/KISS/DRY professional engineer style
• nekomata-engineer - Cat-girl engineer (UFO Meow)
• laowang-engineer - Old Wang engineer
• abyss-cultivator - Abyss cultivator
• ojousama-engineer - Ojou-sama style
• abyss-concise - Abyss concise report
• abyss-command - Abyss iron command
• abyss-ritual - Abyss ritual scroll

Fixed Configuration

Item	Value
ROS2 Version	Humble Hawksbill (LTS)
Target Platform	Physical Robot
Upper-layer Application Model	Antigravity (default) / Gemini (fallback)
Low-level Control Model	Codex
Workflow Phases	7 phases (with hardware deployment)

Codex-Led Mode (Optional)

Install via menu option X. Codex Mode. Codex CLI acts as lead orchestrator with ROS2 context:

• ~/.codex/AGENTS.md — Adaptive decision framework with ROS2 context (node boundaries, message selection, QoS decisions)
• ~/.codex/hooks/ccg-workflow.py — Intelligent guardrail hook with ROS2 checkpoints (package.xml, CMakeLists.txt, launch files, colcon build)
• ~/.codex/config.toml — Multi-agent v2 enabled
• ~/.codex/agents/ — Native sub-agent definitions with ROS2 context

MCP Tools Integration

Optional MCP tools for enhanced functionality:

• fast-context (recommended) — Windsurf Fast Context for code retrieval
• ace-tool — Code search + prompt enhancement
• ContextWeaver — Local-first semantic code search
• context7 (auto-installed) — Free library documentation query

Related Links

• npm package
• GitHub repository
• Official ccg-workflow
• ROS2 Humble Documentation

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE for details.

Version: 3.0.0
Last Updated: 2026-05-20