How It Works — Multi-Model AI Orchestration Engine

CCG is a hook-driven workflow engine. It runs inside a Claude Code session, using 4 JavaScript hooks for per-turn state tracking, and invokes Codex CLI / Gemini CLI for parallel analysis when needed.

Full Execution Flow

Using /ccg:go add JWT authentication to this API as an example:

You: /ccg:go add JWT authentication to this API

CCG Engine:
  1. Reads project context (git status, tech stack, file structure)
  2. Classifies: feature / L complexity / backend / high risk
  3. Selects strategy: full-collaborate
  4. Creates .ccg/tasks/add-jwt-auth/task.json
  5. Launches dual-model analysis (Codex + Gemini in parallel)
  6. Produces plan → HARD STOP for your approval
  7. Spawns Agent Teams Builders for parallel implementation
  8. Runs quality gates + dual-model cross-review
  9. Reports results

Step Breakdown

Step 1 — Project Context Collection

The engine reads current git status, dependency files (package.json / go.mod), and directory structure to understand the project’s tech stack.

Step 2 — Intent Classification

User input is classified across four dimensions:

• Type: feature / bugfix / refactor / research / review / git-action
• Complexity: S (single file) / M (2-5 files) / L (cross-module) / XL (architecture-level)
• Domain: frontend / backend / fullstack / infra
• Risk: low / medium / high

Step 3 — Strategy Selection

Based on classification results, one of 10 strategies is automatically matched. See Strategies for details.

Step 4 — Task Persistence

Tasks with M+ complexity create .ccg/tasks/<slug>/task.json. This file tracks strategy, current phase, gate status, etc.

Step 5-6 — Multi-Model Analysis + HARD STOP

The engine calls Codex CLI and Gemini CLI in parallel via codeagent-wrapper, each returning analysis and recommendations. The engine synthesizes a plan and forces a stop for human approval.

Step 7 — Agent Teams Parallel Implementation

After approval, large tasks spawn multiple Builder teammates for parallel coding. Each Builder has isolated file ownership.

Step 8-9 — Quality Gates + Report

Runs verify-security, verify-quality, verify-change quality Skills, then Codex + Gemini cross-review, and finally outputs the result report.

Per-Turn State Injection

Every time you send a message, the workflow-state.js hook auto-injects current task state:

<ccg-state>
Task: add-jwt-auth (in_progress)
Strategy: full-collaborate
Phase: 4-implementation
Next: Layer 1 Builders executing
</ccg-state>

This breadcrumb ensures Claude always knows what phase the current task is in, even after many conversation turns.

Tip

Even if context gets compacted, session-start.js re-injects full task context on the next turn. State is never lost.

Three-Model Division

Model	Role	Responsibility
Claude	Orchestrator	Intent analysis, strategy selection, code writes, review decisions
Codex	Backend Analyst	API design, database logic, business flow analysis
Gemini	Frontend Analyst	UI components, styling, interaction logic analysis

Caution

External models (Codex / Gemini) have no file write access. They return analysis and patch suggestions only. All actual code writes are executed by Claude after review.

codeagent-wrapper Execution Bridge

codeagent-wrapper is a Go binary that invokes external model CLIs:

codeagent-wrapper --backend <codex|gemini> [working-dir] <<'EOF'
<task content>
EOF

Features:

• Automatic timeout control (default 7200 seconds)
• Standardized output format
• Error retry with silent failure
• Cross-platform support (macOS / Linux / Windows)

Hook and Strategy Collaboration

┌───────────────────────────────────────────────────┐
│                 Claude Code Session                 │
├───────────────────────────────────────────────────┤
│                                                     │
│  [Hook: session-start]  → Inject project context   │
│  [Hook: workflow-state] → Per-turn <ccg-state>     │
│  [Hook: skill-router]   → Detect keywords → inject │
│                                                     │
│  /ccg:go command → Strategy engine                  │
│       ↓                                            │
│  codeagent-wrapper → Codex CLI / Gemini CLI        │
│       ↓                                            │
│  [Hook: subagent-context] → Inject spec to agents  │
│       ↓                                            │
│  Agent Teams Builders (parallel coding)            │
│       ↓                                            │
│  Quality Gates (verify-*)                          │
│       ↓                                            │
│  Output results                                    │
└───────────────────────────────────────────────────┘

This architecture ensures:

1. State continuity — Hooks inject state every turn; Claude always knows current progress
2. Standard compliance — Spec files auto-injected into sub-agents without manual reminders
3. Quality assurance — Verification phase enforces quality gates
4. Parallel efficiency — External model analysis and Builder implementation run in parallel