Skip to content
/
Tier B A16 Cross-vendor router

CCG Workflow

ccg-workflow · fengshao1227/ccg-workflow · ★ 5.4k · last commit 2026-05-22

Routes Claude + Codex + Gemini to task-appropriate collaboration strategies (direct-fix through full-collaborate) with hook-based per-turn state tracking that survives context compaction.

Best whenDifferent models excel at different coding roles — auto-routing to the right model for the right phase eliminates the tradeoff between Claude's reasoning and…
Skip ifUsing pip install instead of uv (N/A — different ecosystem), Hardcoding model names in templates (all models are {{BACKEND_PRIMARY}}/{{FRONTEND_PRIMARY}} variables)
vs seeds
spec-kit's mirror-hook pattern but serves different purposes. The loop detection meta-cognition mechanism has no analog in any o…
Primitive shape 124 total
Commands 13 Skills 100 Subagents 7 Hooks 4
00

Summary

CCG Workflow — Summary

CCG Workflow is a Claude Code plugin (npx ccg-workflow) that orchestrates three AI models — Claude (primary), Codex CLI, and Gemini CLI — in task-appropriate collaboration patterns, with hook-based per-turn state injection, persistent task directories, and a 10-strategy routing engine. The name is explicit: Claude + Codex + Gemini. The v3.0 rewrite (current, 5,357 stars) reduced 29 commands to one entry point (/ccg:go): the user describes what they want in plain language, and the engine classifies intent, selects a strategy (direct-fix through full-collaborate), creates a task directory, and dispatches models in the right configuration. Four Claude Code hooks inject breadcrumb state on every user turn, ensuring Claude stays on track after context compaction. The codeagent-wrapper binary is the multi-model execution bridge, invoking Codex and Gemini as subprocesses and streaming their output back. Agent Teams (parallel Builder subagents) handle large tasks with isolated file ownership. CCG Workflow is closest to taskmaster-ai in using a structured task state with persistent YAML tracking, but adds explicit multi-model dispatch where taskmaster uses Claude exclusively and routes to Codex/Gemini only via config.

01

Overview

CCG Workflow — Overview

Origin

Published by fengshao1227 on GitHub (5,357 stars, MIT, Go binary + TypeScript installer, last commit 2026-05-22). The project is Chinese-first (README in both zh-CN and English); the CLAUDE.md is Chinese, the community is on Linux.do and @CCG_Workflow on X. Version 3.1.1 (June 2026). v3.0 was a "ground-up rewrite" that replaced 29 commands with one smart entry point.

Philosophy

The fundamental insight: different coding tasks benefit from different models. Claude excels at reasoning and architecture; Codex excels at implementation; Gemini has a long context window good for research. CCG routes automatically:

  • Simple bugs: Claude alone (no overhead)
  • Complex features: Codex + Gemini parallel analysis → plan → Claude implementation → dual-model review

From the README's strategy table — the routing logic is explicit:

Strategy When External models
direct-fix Simple bug No
full-collaborate Complex feature Dual model parallel
deep-research Research Dual model exploration

The hook engine ensures Claude never loses task context even after compaction: every user turn injects the current phase + strategy + gate status as a <ccg-state> XML block.

Key Design Decisions

  1. Model routing is configuration, not hardcoding: Step 2 of the installer sets {{FRONTEND_PRIMARY}} and {{BACKEND_PRIMARY}} model variables substituted into all 29 templates
  2. Loop detection: The workflow-state hook detects when the same phase+nextAction repeats 3+ times and injects a BREAK-LOOP PROTOCOL
  3. HARD STOP gates: Plan approval at medium+ complexity is a mandatory phase gate before implementation begins
  4. Domain knowledge injection: When message mentions security/caching/RAG/etc., the skill-router hook auto-injects the relevant knowledge file
02

Architecture

CCG Workflow — Architecture

Distribution

  • Type: npm-package (installer) + Claude Code commands/skills
  • Binary: ccg (via bin: { ccg: 'bin/ccg.mjs' })
  • Version: 3.1.1
  • Language: TypeScript (installer) + JavaScript (hooks) + Go binary (codeagent-wrapper)

Install Methods

npx ccg-workflow
# Interactive 4-step installer (or 2-step for new users):
# Step 1: API config (Anthropic key + optional 302.AI / third-party)
# Step 2: Model routing (choose frontend/backend model: gemini/codex/claude)
# Step 3: MCP tools (optional)
# Step 4: Performance mode

Required Runtime

  • Node.js >= 20
  • Claude Code CLI (required)
  • Codex CLI (optional, enables multi-model features)
  • Gemini CLI (optional, enables multi-model features)

Installed File Layout (~/.claude/)

~/.claude/
├── commands/ccg/          # 13 slash commands (v3 default) [+ 18 legacy optional]
├── agents/ccg/            # 7 sub-agent definitions
├── hooks/ccg/             # 4 hook scripts (JavaScript, zero dependencies)
│   ├── workflow-state.js  # UserPromptSubmit — state breadcrumb injection
│   ├── session-start.js   # SessionStart — full project context injection
│   ├── subagent-context.js # PreToolUse (Bash/Agent) — spec + task context
│   └── skill-router.js    # UserPromptSubmit — domain knowledge auto-injection
├── skills/ccg/            # 100+ skill files (quality gates + domain knowledge)
├── rules/                 # 2 global rules (quality gate triggers + domain routing)
├── output-styles/         # 8 output style files (installed via menu)
├── .ccg/
│   ├── config.toml        # Model routing, MCP, performance mode
│   ├── engine/            # Strategy files + model router
│   └── prompts/           # Expert prompts (claude/6, codex/6, gemini/7)
└── bin/codeagent-wrapper  # Multi-model execution bridge binary (Go)

Multi-Model Bridge (codeagent-wrapper)

A Go binary that:

  • Invokes Codex CLI or Gemini CLI as a subprocess
  • Handles session resume (Gemini session_id capture, Codex thread resume)
  • Streams progress output to stderr (--progress flag)
  • Maps {{BACKEND_PRIMARY}}/{{FRONTEND_PRIMARY}} template variables to actual CLI invocations
  • Windows-compatible (cmd.exe multi-line arg workaround)

Config Files

  • ~/.claude/settings.json — hooks installed here by the installer
  • ~/.claude/.ccg/config.toml — model routing, timeouts, MCP providers
  • .ccg/tasks/<task-id>/task.json — per-task state (project-local)

Task State Directory (project-local)

.ccg/tasks/<task-id>/
├── task.json         # Status, strategy, current phase, gate
├── requirements.md   # Enhanced requirements
├── plan.md           # Approved plan
├── context.jsonl     # Spec files for sub-agent injection
├── review.md         # Review results
└── research/         # Persisted research
03

Components

CCG Workflow — Components

Slash Commands (13 default + 18 legacy optional)

Core

Command Purpose
/ccg:go Smart entry — describe intent, engine selects strategy

Git

Command Purpose
/ccg:commit Smart conventional commit
/ccg:rollback Interactive rollback
/ccg:clean-branches Clean merged branches
/ccg:worktree Worktree management

Project

Command Purpose
/ccg:init Initialize project CLAUDE.md
/ccg:context Project context management

OpenSpec

Command Purpose
/ccg:spec-init Initialize OPSX environment
/ccg:spec-research Requirements → constraints
/ccg:spec-plan Constraints → zero-decision plan
/ccg:spec-impl Execute plan + archive
/ccg:spec-review Dual-model cross-review

Additional legacy commands include: /ccg:workflow, /ccg:plan, /ccg:execute, /ccg:debug, /ccg:refactor, /ccg:team, /ccg:review, and more.

Sub-Agents (7, defined in templates/commands/agents/)

Agent Role in /ccg:team
team-architect Architecture design
team-qa QA engineering
team-reviewer Code review
(4 additional Builder agents) Parallel implementation

Hooks (4, installed in ~/.claude/hooks/ccg/)

Hook File Event Purpose
workflow-state.js UserPromptSubmit Injects <ccg-state> breadcrumb every turn; detects loops (3+ repeats = BREAK-LOOP PROTOCOL)
session-start.js SessionStart Injects full project context on start/clear/compact
subagent-context.js PreToolUse (Bash/Agent) Injects spec + task context into codeagent-wrapper calls and Agent Team spawns
skill-router.js UserPromptSubmit Auto-injects domain knowledge when keywords detected

Skills (100+, in ~/.claude/skills/ccg/)

Categories:

  • Quality gates: verify-security, verify-quality, verify-change
  • Domain knowledge: 10 domains × ~6 files each (security, architecture, DevOps, AI, development, frontend, infra, mobile, data engineering, orchestration)
  • Impeccable UI/UX set: 20 skills (polish, audit, harden, clarify, critique, etc.)
  • Tools: scrapling (web scraping), override-refusal (/hi anti-refusal)

Expert Prompts (19 files in ~/.claude/.ccg/prompts/)

Group Count Purpose
claude/ 6 Claude-specific expert prompts
codex/ 6 Codex-specific expert prompts
gemini/ 7 Gemini-specific expert prompts

Strategies (10, in ~/.claude/.ccg/engine/)

Strategy External Models Agent Teams
direct-fix No No
quick-implement No No
guided-develop Single model No
full-collaborate Dual model parallel Yes
debug-investigate Dual model diagnosis No
refactor-safely Dual model review No
deep-research Dual model exploration No
optimize-measure Optional No
review-audit Dual model cross-review No
git-action No No

Output Styles (8, optional install)

8 output style files including: cold-blade brief, iron-law military, ritual scroll, and other stylistic variations.

05

Prompts

CCG Workflow — Prompts

/ccg:go Command (templates/commands/go.md) — Verbatim Excerpt

---
description: 'CCG 智能入口 — 描述你要做什么，AI 自动选择最佳策略执行'
---

# /ccg:go — CCG 智能入口

$ARGUMENTS

## 你的角色

你是 **CCG Engine**，一个智能编排器。你的职责是：分析用户的自然语言意图，自动选择最优的
开发策略，然后严格按策略执行。用户不需要记住任何命令，只需要描述他们想做什么。

## Phase 0: 逃生舱检测

在开始分析之前，先检查 $ARGUMENTS 是否命中逃生舱：

**直接执行短语**（跳过所有分析，Claude 直接处理）：
- "直接做" / "just do it" / "skip" / "不用分析" / "别分析了" / "小修一下"

**快捷路由**（跳过意图分析，直接加载对应策略）：
- 以 `commit` 开头 → 加载 `git-action` 策略
- 以 `review` / `审查` 开头 → 加载 `review-audit` 策略

## Phase 1.3 复杂度评估

| 级别 | 判定标准 |
|------|---------|
| **S** | 单文件变更，范围清晰，预估 <30 行 |
| **M** | 2-5 文件，单模块内，路径明确 |
| **L** | 5+ 文件，跨模块，需要规划和协调 |
| **XL** | 架构级变更，API/Schema 变动，多模块协作 |

**不确定时默认选高一级**。

Prompting technique: Role assignment (CCEngine orchestrator) + escape hatch detection (bypass expensive analysis for simple requests) + complexity table with default-to-higher bias. The Chinese-first prompts are unusual — internationalization is baked into the engine, not just the docs.

workflow-state.js Hook — Verbatim (loop detection section)

const lines = [
  '<ccg-state>',
  `Task: ${task.title || task.id} (${task.status})`,
  `Strategy: ${task.strategy}`,
  `Phase: ${task.currentPhase}`,
];

if (loop) {
  lines.push('');
  lines.push(`⚠️ LOOP DETECTED: Phase "${loop.phase}" with same nextAction repeated ${loop.count} turns (${loop.elapsedSec}s).`);
  lines.push('🔄 BREAK-LOOP PROTOCOL:');
  lines.push('  1. STOP current approach immediately');
  lines.push('  2. Root-cause analysis: why is this phase not progressing?');
  lines.push('  3. Options: (a) try alternative approach, (b) escalate to user, (c) upgrade strategy');
  lines.push('  4. If blocked by external dependency → tell user explicitly');
  lines.push('  5. Do NOT repeat the same action — that is what caused this loop');
  lines.push('</ccg-state>');
}

Prompting technique: Meta-cognition injection — the hook teaches Claude to recognize and break out of behavioral loops it's already in. The BREAK-LOOP PROTOCOL is a numbered escape hatch with explicit branching logic (try alternative / escalate / upgrade strategy).

09

Uniqueness

CCG Workflow — Uniqueness

differs_from_seeds

CCG Workflow is closest to taskmaster-ai (hook-based state tracking, persistent task files, prompt chaining) but extends it with explicit multi-model dispatch: where taskmaster uses a single model (Claude) and routes internally, CCG routes different models for different roles. The hook architecture (4 hooks injecting state every turn) resembles spec-kit's mirror-hook pattern, but CCG's hooks are state machines rather than pre/post command decorators. Unlike openspec (model-agnostic, multi-tool portability), CCG names all three target models explicitly and ships bespoke expert prompts for each. The codeagent-wrapper binary (Go, managing Codex + Gemini subprocess invocation) has no parallel in any seed — it is the physical implementation of multi-model routing as a process manager. The loop detection mechanism in workflow-state.js (BREAK-LOOP PROTOCOL) is novel engineering not seen in any other framework analyzed.

Distinctive Positioning

  1. Named model trilogy: The only framework in the corpus that explicitly names and routes Claude + Codex + Gemini as distinct roles, with bespoke expert prompts for each (19 prompt files across 3 models)
  2. Loop detection: The workflow-state hook tracks phase+nextAction across turns and injects meta-cognitive recovery instructions when loops are detected
  3. codeagent-wrapper: A Go binary purpose-built to manage Codex CLI and Gemini CLI as subprocesses with session resume, Windows compatibility, and progress streaming
  4. Configurable model routing: {{BACKEND_PRIMARY}}/{{FRONTEND_PRIMARY}} template variables make the routing configuration explicit and changeable without code edits
  5. 5,357 stars + Chinese-first development: The most popular framework in this batch; the Chinese developer community orientation is reflected in the Chinese-primary CLAUDE.md and community on linux.do
  6. Codex-Led Mode: A fully inverted mode where Codex is the primary orchestrator and Claude/Gemini become subagents — no other framework in the corpus supports this inversion

Observable Failure Modes

  • Codex/Gemini dependency: Multi-model features require both CLIs to be installed and authorized — many users may only have Claude Code
  • codeagent-wrapper subprocess complexity: Windows-specific bugs (cmd.exe multi-line truncation, Gemini session_id parsing) appear repeatedly in the changelog, suggesting the subprocess management is fragile
  • Agent Teams is experimental: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 — the API flag signals this could break
  • Template variable fragility: 21 templates with {{BACKEND_PRIMARY}}/{{FRONTEND_PRIMARY}} substitution — any inconsistency causes incorrect model routing (multiple bug fixes in changelog)
  • Chinese-English UX split: Some features are documented only in Chinese (CLAUDE.md changelog); English users may miss context
04

Workflow

CCG Workflow — Workflow

/ccg:go Engine Flow

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

CCG Engine:
  1. Phase 0: Escape hatch detection (skip analysis for "just do it", "skip", etc.)
  2. Phase 1: Intent Analysis
     1.1 Get project context (git status, tech stack, directory structure)
     1.2 Classify task type (bug-fix/feature/refactor/research/optimize/review/git)
     1.3 Assess complexity (S/M/L/XL)
     1.4 Assess risk (low/medium/high)
  3. Phase 2: Strategy Selection (engine picks from 10 strategies)
  4. Phase 3: Task creation → .ccg/tasks/<id>/task.json
  5. Phase 4: Execute strategy (may dispatch Codex + Gemini via codeagent-wrapper)
  6. Phase 5: Plan → HARD STOP for approval (medium+ complexity)
  7. Phase 6: Implementation (Agent Teams for XL tasks)
  8. Phase 7: Quality gates (verify-security, verify-quality, verify-change)
  9. Phase 8: Dual-model cross-review

Hook Injection (every turn)

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

Loop detection: if same phase+nextAction repeats 3+ turns, BREAK-LOOP PROTOCOL injected.

Phases + Artifacts

Phase Artifact Gate
Intent Analysis None None
Strategy Selection None None
Task Creation .ccg/tasks/<id>/task.json None
Requirements Enhancement requirements.md None
Plan Generation plan.md HARD STOP — human approval required
Implementation Code changes None
Quality Gate Review output Auto-check (verify-security, verify-quality)
Cross-Review review.md None

Agent Teams (full-collaborate strategy)

For XL complexity tasks:

  1. CCG spawns multiple Builder sub-agents via CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
  2. Each Builder gets isolated file ownership (scope-partitioned)
  3. Builders execute in parallel
  4. Evaluator-Optimizer feedback loop: up to 2 rounds of auto-fix for Critical issues

Session Continuity

  • session-start.js hook re-injects full task context after compaction or new session
  • Task state persists in .ccg/tasks/ files — no state lost to context compaction
06

Memory Context

CCG Workflow — Memory & Context

State Storage

Task Persistence (project-local, .ccg/tasks/)

.ccg/tasks/<task-id>/
├── task.json         # Status, strategy, current phase, gate (read by workflow-state hook)
├── requirements.md   # Enhanced requirements document
├── plan.md           # Approved implementation plan
├── context.jsonl     # Spec file references for sub-agent injection
├── review.md         # Review results
└── research/         # Persisted research findings

Spec System (project-local, .ccg/spec/)

.ccg/spec/
├── backend/index.md    # Backend coding conventions
├── frontend/index.md   # Frontend coding conventions
└── guides/index.md     # Cross-module guidelines

These are injected into every codeagent-wrapper call and Agent Team spawn via the subagent-context hook.

CCG Configuration (~/.claude/.ccg/config.toml)

Model routing, MCP providers, timeouts — persisted globally.

Memory Persistence

Project + global hybrid: Task state is project-scoped (.ccg/tasks/); model routing and tool config are global (~/.claude/.ccg/); hooks are user-global (~/.claude/hooks/ccg/).

Cross-Session Handoff

Full — the session-start.js hook fires on every new session/clear/compact event and re-injects the full project context + active task state. The workflow-state.js hook reads task.json every user turn. Even after context compaction, the agent regains full task awareness at the next turn.

Context Compaction Handling

Explicit — session-start.js specifically targets the SessionStart event which fires on --resume, /clear, and after context compaction. The task state in task.json is the source of truth that survives compaction.

Domain Knowledge as Memory

The skill-router.js hook maps user message keywords to domain knowledge files (~/.claude/skills/ccg/). This is a form of "semantic trigger" memory — the knowledge is not loaded into context continuously, only when relevant keywords appear. Categories: security, caching, RAG, DevOps, AI/LLM integration, frontend design, infrastructure, mobile, data engineering, orchestration.

07

Orchestration

CCG Workflow — Orchestration

Multi-Agent Pattern

Hierarchical with parallel-fan-out for complex tasks:

  • Primary: Claude (CCG Engine) — analyzes, selects strategy, coordinates
  • Secondary: Codex + Gemini (via codeagent-wrapper) — dispatched for analysis, research, review
  • Agent Teams: parallel Builder subagents (Claude Code's experimental AGENT_TEAMS feature) for XL tasks with isolated file ownership

Multi-Model Routing

The defining feature of CCG Workflow. Three models, three roles:

Model Role When Used
Claude Primary orchestrator + implementer Always
Codex Backend analysis, prototype generation guided-develop, full-collaborate, debug-investigate, refactor-safely
Gemini Frontend analysis, research, review full-collaborate, deep-research, review-audit

Model assignment is configurable at install time — {{BACKEND_PRIMARY}} and {{FRONTEND_PRIMARY}} are template variables substituted into all 29 command templates. Users can swap Codex/Gemini in/out, configure Gemini model variant, and use third-party API keys.

Codex-Led Mode (optional): Install menu option X inverts the hierarchy — Codex writes code directly and dispatches analysis/review to Gemini + Claude via codeagent-wrapper.

Execution Mode

Interactive-loop — Claude Code session-based. The hooks run on every user turn, keeping the agent informed continuously.

Prompt Chaining

Yes — multi-step chains within strategies:

  1. Codex produces prototype/analysis → output becomes Claude's implementation context
  2. Dual-model parallel analysis → merged plan → HARD STOP → implementation
  3. Implementation → quality gate verification → cross-review → final output

Isolation

Worktree per task (for full-collaborate with Agent Teams): each Builder gets isolated file ownership via Claude Code's Agent Teams feature. No OS-level sandbox — isolation is at the file-ownership assignment level.

Agent Teams

Requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 environment variable. The subagent-context hook injects task context + spec files into every Agent spawn. The Evaluator-Optimizer feedback loop runs up to 2 rounds of auto-fix on Critical issues.

Execution Constraints

  • CODEX_TIMEOUT: default 7200s (2 hours) for long-running codeagent-wrapper calls
  • CODEAGENT_POST_MESSAGE_DELAY: 5s delay after completion
08

Ui Cli Surface

CCG Workflow — UI & CLI Surface

CLI Binary: ccg

Minimal CLI (bin: { ccg: 'bin/ccg.mjs' }) — primarily used as the installer/updater:

npx ccg-workflow          # Install (interactive 4-step or 2-step)
npx ccg-workflow@latest   # Update
npx ccg-workflow          # Select "Uninstall" from menu

The ccg binary itself is the setup wizard, not a runtime controller. Runtime interaction happens through Claude Code slash commands.

Slash Commands (Claude Code)

13 slash commands installed into ~/.claude/commands/ccg/. The primary interface is natural language via /ccg:go.

Dashboard / UI

None — CCG is a Claude Code plugin. All interaction is through the Claude Code terminal. The codeagent-wrapper binary outputs progress to stderr for real-time feedback, but there is no separate dashboard.

IDE Integration

Claude Code only (primary). The codeagent-wrapper in Codex-Led Mode can also be controlled from Codex CLI directly.

Observability

  • <ccg-state> breadcrumbs: Every user turn receives an injected XML block with current task state — visible in Claude's context
  • Loop detection: 3+ same-phase repeats trigger a visible ⚠️ LOOP DETECTED warning
  • .ccg/tasks/<id>/: Persistent task directory with plan.md, review.md, and context files — human-readable audit trail
  • codeagent-wrapper --progress flag: After 2026-03-20, all templates use --progress for real-time Codex/Gemini progress output to stderr
  • CLAUDE.md changelog: Detailed version history in the CLAUDE.md file tracks every bug fix and feature (unusual transparency)

Update/Uninstall

npx ccg-workflow@latest   # Update to latest version
npx ccg-workflow          # Menu → Uninstall

The installer provides menu options for: API config update, model routing update, MCP tools update, performance mode update, and full uninstall.

Related frameworks

same archetype · same primary tool · same memory type

CodeMachine CLI ★ 2.5k
A16 Cross-vendor router

JavaScript-DSL workflow orchestration engine that captures repeatable AI coding agent workflows with tracks, condition groups,…

Codexia ★ 690
A16 Cross-vendor router

Tauri desktop app providing visual control plane, task scheduler, git worktree manager, and headless REST API for Codex CLI +…

Kagan ★ 88
A16 Cross-vendor router

Kanban TUI for AI coding agents with a structurally enforced human review gate (REVIEW → DONE cannot be automated) — one git…

oh-my-claudecode (Yeachan-Heo) ★ 35k
A16 Cross-vendor router

Zero-learning-curve teams-first multi-agent orchestration for Claude Code with autopilot (6-phase lifecycle), ralph (PRD-driven…

Paseo ★ 6.8k
A16 Cross-vendor router

Multi-provider AI coding agent orchestration daemon with cross-device access (phone/desktop/CLI) and git worktree isolation.

CCS (Claude Code Switch) ★ 2.4k
A16 Cross-vendor router

Routes Claude Code tasks to the optimal AI agent (Codex, Factory Droid, Ollama, Claude) based on configurable cost/capability…