ccg-workflow 1.7.75 → 1.7.77

package/README.md

@@ -5,6 +5,7 @@
 [![npm version](https://img.shields.io/npm/v/ccg-workflow.svg)](https://www.npmjs.com/package/ccg-workflow)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![Claude Code](https://img.shields.io/badge/Claude%20Code-Compatible-green.svg)](https://claude.ai/code)
+[![Tests](https://img.shields.io/badge/Tests-131%20passed-brightgreen.svg)]()
 
 [简体中文](./README.zh-CN.md) | English
 
@@ -12,98 +13,136 @@
 
 A multi-model collaboration development system where Claude Code orchestrates Codex + Gemini. Frontend tasks route to Gemini, backend tasks route to Codex, and Claude handles orchestration and code review.
 
-## Installation
+## Why CCG?
+
+- **Zero-config model routing** — Frontend tasks automatically go to Gemini, backend tasks to Codex. No manual switching.
+- **Security by design** — External models have no write access. They return patches; Claude reviews before applying.
+- **26 slash commands** — From planning to execution, git workflow to code review, all accessible via `/ccg:*`.
+- **Spec-driven development** — Integrates [OPSX](https://github.com/fission-ai/opsx) to turn vague requirements into verifiable constraints, eliminating AI improvisation.
+
+## Architecture
+
+```
+Claude Code (Orchestrator)
+       │
+   ┌───┴───┐
+   ↓       ↓
+Codex   Gemini
+(Backend) (Frontend)
+   │       │
+   └───┬───┘
+       ↓
+  Unified Patch
+```
+
+External models have no write access — they only return patches, which Claude reviews before applying.
+
+## Quick Start
+
+### Prerequisites
+
+| Dependency | Required | Notes |
+|------------|----------|-------|
+| **Node.js 20+** | Yes | `ora@9.x` requires Node >= 20. Node 18 causes `SyntaxError` |
+| **Claude Code CLI** | Yes | [Install guide](#install-claude-code) |
+| **jq** | Yes | Used for auto-authorization hook ([install](#install-jq)) |
+| **Codex CLI** | No | Enables backend routing |
+| **Gemini CLI** | No | Enables frontend routing |
+
+### Installation
 
 ```bash
 npx ccg-workflow
 ```
 
-**Requirements**: Claude Code CLI, Node.js 20+
+On first run, CCG prompts you to select a language (English / Chinese). This preference is saved for all future sessions.
 
-> **Important**: This project depends on `ora@9.x` and `string-width@8.x`, which require Node.js >= 20. Using Node.js 18 will cause `SyntaxError: Invalid regular expression flags`. Please upgrade to Node.js 20 or higher.
+### Install jq
 
-**Optional**: Codex CLI (backend), Gemini CLI (frontend)
+```bash
+# macOS
+brew install jq
 
-## First-Time Setup
+# Linux (Debian/Ubuntu)
+sudo apt install jq
 
-On first run, CCG will prompt you to select your preferred language (English or Chinese). This preference is saved and used for all subsequent sessions.
+# Linux (RHEL/CentOS)
+sudo yum install jq
 
-## Commands
+# Windows
+choco install jq   # or: scoop install jq
+```
 
-| Command | Description |
-|---------|-------------|
-| `/ccg:workflow` | Full 6-phase development workflow |
-| `/ccg:plan` | Multi-model collaborative planning (Phase 1-2) |
-| `/ccg:execute` | Multi-model collaborative execution (Phase 3-5) |
-| `/ccg:feat` | Smart feature development |
-| `/ccg:frontend` | Frontend tasks (Gemini) |
-| `/ccg:backend` | Backend tasks (Codex) |
-| `/ccg:analyze` | Technical analysis |
-| `/ccg:debug` | Problem diagnosis |
-| `/ccg:optimize` | Performance optimization |
-| `/ccg:test` | Test generation |
-| `/ccg:review` | Code review |
-| `/ccg:commit` | Git commit |
-| `/ccg:rollback` | Git rollback |
-| `/ccg:clean-branches` | Clean branches |
-| `/ccg:worktree` | Worktree management |
-| `/ccg:init` | Initialize CLAUDE.md |
-| `/ccg:enhance` | Prompt enhancement |
-| `/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 |
-| `/ccg:team-research` | Agent Teams requirements → constraints |
-| `/ccg:team-plan` | Agent Teams constraints → parallel plan |
-| `/ccg:team-exec` | Agent Teams parallel execution |
-| `/ccg:team-review` | Agent Teams dual-model review |
-| `/ccg:codex-exec` | Codex full execution (plan → code → review) |
+### Install Claude Code
 
-### OPSX Spec-Driven (v1.7.52+)
+```bash
+npx ccg-workflow menu  # Select "Install Claude Code"
+```
 
-Integrates [OPSX architecture](https://github.com/fission-ai/opsx) to turn requirements into constraints, eliminating AI improvisation:
+Supports: npm, homebrew, curl, powershell, cmd.
 
-```bash
-# Initialize OPSX environment
-/ccg:spec-init
+## Commands
 
-# Research requirements → output constraints
-/ccg:spec-research implement user authentication
+### Development Workflow
 
-# Parallel analysis → zero-decision plan
-/ccg:spec-plan
+| Command | Description | Model |
+|---------|-------------|-------|
+| `/ccg:workflow` | Full 6-phase development workflow | Codex + Gemini |
+| `/ccg:plan` | Multi-model collaborative planning (Phase 1-2) | Codex + Gemini |
+| `/ccg:execute` | Multi-model collaborative execution (Phase 3-5) | Codex + Gemini + Claude |
+| `/ccg:codex-exec` | Codex full execution (plan → code → review) | Codex + multi-model review |
+| `/ccg:feat` | Smart feature development | Auto-routed |
+| `/ccg:frontend` | Frontend tasks (fast mode) | Gemini |
+| `/ccg:backend` | Backend tasks (fast mode) | Codex |
 
-# Execute the plan
-/ccg:spec-impl
+### Analysis & Quality
 
-# Independent review (available anytime)
-/ccg:spec-review
-```
+| Command | Description | Model |
+|---------|-------------|-------|
+| `/ccg:analyze` | Technical analysis | Codex + Gemini |
+| `/ccg:debug` | Problem diagnosis + fix | Codex + Gemini |
+| `/ccg:optimize` | Performance optimization | Codex + Gemini |
+| `/ccg:test` | Test generation | Auto-routed |
+| `/ccg:review` | Code review (auto git diff) | Codex + Gemini |
+| `/ccg:enhance` | Prompt enhancement | Built-in |
 
-**Note**: `/ccg:spec-*` commands are CCG's wrapper around OPSX, internally calling `/opsx:*` commands. You can `/clear` between phases — state is persisted in the `openspec/` directory, so context overflow is not a concern.
+### OPSX Spec-Driven
 
-### Agent Teams Parallel Execution (v1.7.60+)
+| Command | Description |
+|---------|-------------|
+| `/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 |
 
-Leverage Claude Code Agent Teams experimental feature to spawn multiple Builder teammates for parallel coding:
+### Agent Teams (v1.7.60+)
 
-```bash
-# 1. Requirements research → constraints (recommended for complex projects)
-/ccg:team-research implement real-time collaboration kanban API
+| Command | Description |
+|---------|-------------|
+| `/ccg:team-research` | Requirements → constraints (parallel exploration) |
+| `/ccg:team-plan` | Constraints → parallel implementation plan |
+| `/ccg:team-exec` | Spawn Builder teammates for parallel coding |
+| `/ccg:team-review` | Dual-model cross-review |
 
-# 2. /clear then plan → zero-decision parallel plan
-/ccg:team-plan kanban-api
+> **Prerequisite**: Enable Agent Teams in `settings.json`: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`
 
-# 3. /clear then parallel execution → Builder teammates write code in parallel
-/ccg:team-exec
+### Git Tools
 
-# 4. /clear then review → dual-model cross-review
-/ccg:team-review
-```
+| Command | Description |
+|---------|-------------|
+| `/ccg:commit` | Smart commit (conventional commit format) |
+| `/ccg:rollback` | Interactive rollback |
+| `/ccg:clean-branches` | Clean merged branches |
+| `/ccg:worktree` | Worktree management |
 
-**Prerequisite**: Manually enable Agent Teams (`settings.json`: set `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`)
+### Project Setup
 
-**vs Traditional Workflow**: Team series uses `/clear` between steps to isolate context, passing state through files. Builders work in parallel, ideal for tasks decomposable into 3+ independent modules.
+| Command | Description |
+|---------|-------------|
+| `/ccg:init` | Initialize project CLAUDE.md |
+
+## Workflow Guides
 
 ### Planning & Execution Separation
 
@@ -121,31 +160,66 @@ Leverage Claude Code Agent Teams experimental feature to spawn multiple Builder
 /ccg:codex-exec .claude/plan/user-auth.md
 ```
 
+### OPSX Spec-Driven Workflow
+
+Integrates [OPSX architecture](https://github.com/fission-ai/opsx) to turn requirements into constraints, eliminating AI improvisation:
+
+```bash
+/ccg:spec-init                          # Initialize OPSX environment
+/ccg:spec-research implement user auth  # Research → constraints
+/ccg:spec-plan                          # Parallel analysis → zero-decision plan
+/ccg:spec-impl                          # Execute the plan
+/ccg:spec-review                        # Independent review (anytime)
+```
+
+> **Tip**: `/ccg:spec-*` commands internally call `/opsx:*`. You can `/clear` between phases — state is persisted in the `openspec/` directory.
+
+### Agent Teams Parallel Workflow
+
+Leverage Claude Code Agent Teams to spawn multiple Builder teammates for parallel coding:
+
+```bash
+/ccg:team-research implement kanban API  # 1. Requirements → constraints
+# /clear
+/ccg:team-plan kanban-api               # 2. Plan → parallel tasks
+# /clear
+/ccg:team-exec                          # 3. Builders code in parallel
+# /clear
+/ccg:team-review                        # 4. Dual-model cross-review
+```
+
+> **vs Traditional Workflow**: Team series uses `/clear` between steps to isolate context, passing state through files. Ideal for tasks decomposable into 3+ independent modules.
+
 ## Configuration
 
 ### Directory Structure
 
 ```
 ~/.claude/
-├── commands/ccg/       # Slash commands
+├── commands/ccg/       # 26 slash commands
 ├── agents/ccg/         # Sub-agents
-├── skills/             # Quality gates + multi-agent orchestration
+├── skills/ccg/         # Quality gates + multi-agent orchestration
 ├── bin/codeagent-wrapper
 └── .ccg/
-    ├── config.toml
-    └── prompts/{codex,gemini}/
+    ├── config.toml     # CCG configuration
+    └── prompts/
+        ├── codex/      # 6 Codex expert prompts
+        └── gemini/     # 7 Gemini expert prompts
 ```
 
 ### Environment Variables
 
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `CODEAGENT_POST_MESSAGE_DELAY` | Wait time after Codex completion (seconds) | 5 |
-| `CODEX_TIMEOUT` | codeagent-wrapper execution timeout (seconds) | 7200 |
-| `BASH_DEFAULT_TIMEOUT_MS` | Claude Code Bash default timeout (ms) | 120000 |
-| `BASH_MAX_TIMEOUT_MS` | Claude Code Bash max timeout (ms) | 600000 |
+Configure in `~/.claude/settings.json` under `"env"`:
+
+| Variable | Description | Default | When to change |
+|----------|-------------|---------|----------------|
+| `CODEAGENT_POST_MESSAGE_DELAY` | Wait after Codex completion (sec) | `5` | Set to `1` if Codex process hangs |
+| `CODEX_TIMEOUT` | Wrapper execution timeout (sec) | `7200` | Increase for very long tasks |
+| `BASH_DEFAULT_TIMEOUT_MS` | Claude Code Bash timeout (ms) | `120000` | Increase if commands time out |
+| `BASH_MAX_TIMEOUT_MS` | Claude Code Bash max timeout (ms) | `600000` | Increase for long builds |
 
-Configuration in `~/.claude/settings.json`:
+<details>
+<summary>Example settings.json</summary>
 
 ```json
 {
@@ -158,79 +232,32 @@ Configuration in `~/.claude/settings.json`:
 }
 ```
 
-### codeagent-wrapper Auto-Authorization
-
-CCG automatically installs a Hook in `settings.json` to auto-authorize codeagent-wrapper commands, so you don't have to manually approve each collaboration call.
-
-**Requirement**: `jq` must be installed on your system.
-
-```bash
-# macOS
-brew install jq
-
-# Linux (Debian/Ubuntu)
-sudo apt install jq
-
-# Linux (RHEL/CentOS)
-sudo yum install jq
-
-# Windows
-choco install jq
-# or
-scoop install jq
-```
+</details>
 
 ### MCP Configuration
 
-Code retrieval MCP (choose one):
-- **ace-tool** (recommended) - Code search via `search_context` (note: `enhance_prompt` is no longer available). [Official](https://augmentcode.com/) | [Third-party proxy (recommended)](https://acemcp.heroman.wtf/)
-- **ContextWeaver** (alternative) - Local hybrid search, requires SiliconFlow API Key (free)
-
-Optional MCP tools:
-- **Context7** - Latest library documentation
-- **Playwright** - Browser automation/testing
-- **DeepWiki** - Knowledge base queries
-- **Exa** - Search engine (requires API Key)
-
 ```bash
-# Configure MCP
 npx ccg-workflow menu  # Select "Configure MCP"
 ```
 
-## Tools
-
-```bash
-npx ccg-workflow menu  # Select "Tools"
-```
-
-- **ccusage** - Claude Code usage analytics
-- **CCometixLine** - Status bar tool (Git + usage tracking)
-
-## Install Claude Code
-
-```bash
-npx ccg-workflow menu  # Select "Install Claude Code"
-```
-
-Supports multiple installation methods: npm, homebrew, curl, powershell, cmd
+**Code retrieval** (choose one):
+- **ace-tool** (recommended) — Code search via `search_context`. [Official](https://augmentcode.com/) | [Third-party proxy](https://acemcp.heroman.wtf/)
+- **ContextWeaver** (alternative) — Local hybrid search, requires SiliconFlow API Key (free)
 
-## Update / Uninstall
+**Optional tools**:
+- **Context7** — Latest library documentation (auto-installed)
+- **Playwright** — Browser automation / testing
+- **DeepWiki** — Knowledge base queries
+- **Exa** — Search engine (requires API Key)
 
-```bash
-# Update
-npx ccg-workflow@latest          # npx users
-npm install -g ccg-workflow@latest  # npm global users
-
-# Uninstall
-npx ccg-workflow  # Select "Uninstall"
-npm uninstall -g ccg-workflow  # npm global users need this extra step
-```
+### Auto-Authorization Hook
 
-## FAQ
+CCG automatically installs a Hook to auto-authorize `codeagent-wrapper` commands (requires [jq](#install-jq)).
 
-### 1. How to auto-authorize codeagent-wrapper without manual approval?
+<details>
+<summary>Manual setup (for versions before v1.7.71)</summary>
 
-CCG automatically installs the Hook during setup (v1.7.71+). If you installed an older version, add this to `~/.claude/settings.json`:
+Add to `~/.claude/settings.json`:
 
 ```json
 {
@@ -251,37 +278,49 @@ CCG automatically installs the Hook during setup (v1.7.71+). If you installed an
 }
 ```
 
-> **Note**: Requires `jq` installed on your system. See [codeagent-wrapper Auto-Authorization](#codeagent-wrapper-auto-authorization) for install instructions.
+</details>
 
-### 2. Codex CLI 0.80.0 process does not exit
+## Utilities
 
-In `--json` mode, Codex does not automatically exit after output completion.
+```bash
+npx ccg-workflow menu  # Select "Tools"
+```
 
-Fix: Set `CODEAGENT_POST_MESSAGE_DELAY=1`
+- **ccusage** — Claude Code usage analytics
+- **CCometixLine** — Status bar tool (Git + usage tracking)
 
-## Architecture
+## Update / Uninstall
 
-```
-Claude Code (Orchestrator)
-       │
-   ┌───┴───┐
-   ↓       ↓
-Codex   Gemini
-(Backend) (Frontend)
-   │       │
-   └───┬───┘
-       ↓
-  Unified Patch
+```bash
+# Update
+npx ccg-workflow@latest            # npx users
+npm install -g ccg-workflow@latest  # npm global users
+
+# Uninstall
+npx ccg-workflow  # Select "Uninstall"
+npm uninstall -g ccg-workflow  # npm global users need this extra step
 ```
 
-External models have no write access — they only return patches, which Claude reviews before applying.
+## FAQ
+
+### Codex CLI 0.80.0 process does not exit
+
+In `--json` mode, Codex does not automatically exit after output completion.
+
+**Fix**: Set `CODEAGENT_POST_MESSAGE_DELAY=1` in your environment variables.
+
+## Contributing
+
+We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+
+Looking for a place to start? Check out issues labeled [`good first issue`](https://github.com/fengshao1227/ccg-workflow/labels/good%20first%20issue).
 
 ## Credits
 
-- [cexll/myclaude](https://github.com/cexll/myclaude) - codeagent-wrapper
-- [UfoMiao/zcf](https://github.com/UfoMiao/zcf) - Git tools
-- [GudaStudio/skills](https://github.com/GuDaStudio/skills) - Routing design
-- [ace-tool](https://linux.do/t/topic/1344562) - MCP tool
+- [cexll/myclaude](https://github.com/cexll/myclaude) — codeagent-wrapper
+- [UfoMiao/zcf](https://github.com/UfoMiao/zcf) — Git tools
+- [GudaStudio/skills](https://github.com/GuDaStudio/skills) — Routing design
+- [ace-tool](https://linux.do/t/topic/1344562) — MCP tool
 
 ## Star History
 
@@ -293,4 +332,4 @@ MIT
 
 ---
 
-v1.7.75 | [Issues](https://github.com/fengshao1227/ccg-workflow/issues)
+v1.7.77 | [Issues](https://github.com/fengshao1227/ccg-workflow/issues) | [Contributing](./CONTRIBUTING.md)

package/README.zh-CN.md

@@ -1,10 +1,11 @@
-# CCG - Claude + Codex + Gemini Multi-Model Collaboration
+# CCG - Claude + Codex + Gemini 多模型协作
 
 <div align="center">
 
 [![npm version](https://img.shields.io/npm/v/ccg-workflow.svg)](https://www.npmjs.com/package/ccg-workflow)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![Claude Code](https://img.shields.io/badge/Claude%20Code-Compatible-green.svg)](https://claude.ai/code)
+[![Tests](https://img.shields.io/badge/Tests-131%20passed-brightgreen.svg)]()
 
 简体中文 | [English](./README.md)
 
@@ -12,102 +13,138 @@
 
 Claude Code 编排 Codex + Gemini 的多模型协作开发系统。前端任务路由至 Gemini，后端任务路由至 Codex，Claude 负责编排决策和代码审核。
 
-## 安装
+## 为什么选择 CCG？
+
+- **零配置模型路由** — 前端任务自动走 Gemini，后端任务自动走 Codex，无需手动切换。
+- **安全设计** — 外部模型无写入权限，仅返回 Patch，由 Claude 审核后应用。
+- **26 个斜杠命令** — 从规划到执行、Git 工作流到代码审查，通过 `/ccg:*` 一站式访问。
+- **规范驱动开发** — 集成 [OPSX](https://github.com/fission-ai/opsx)，将模糊需求变成可验证约束，让 AI 没法自由发挥。
+
+## 架构
+
+```
+Claude Code (编排)
+       │
+   ┌───┴───┐
+   ↓       ↓
+Codex   Gemini
+(后端)   (前端)
+   │       │
+   └───┬───┘
+       ↓
+  Unified Patch
+```
+
+外部模型无写入权限，仅返回 Patch，由 Claude 审核后应用。
+
+## 快速开始
+
+### 前置条件
+
+| 依赖 | 必需 | 说明 |
+|------|------|------|
+| **Node.js 20+** | 是 | `ora@9.x` 要求 Node >= 20，Node 18 会报 `SyntaxError` |
+| **Claude Code CLI** | 是 | [安装方法](#安装-claude-code) |
+| **jq** | 是 | 用于自动授权 Hook（[安装方法](#安装-jq)） |
+| **Codex CLI** | 否 | 启用后端路由 |
+| **Gemini CLI** | 否 | 启用前端路由 |
+
+### 安装
 
 ```bash
 npx ccg-workflow
 ```
 
-**要求**：Claude Code CLI、Node.js 20+
+首次运行会提示选择语言（简体中文 / English），选择后自动保存，后续无需再选。
 
-> **重要**：本项目依赖 `ora@9.x` 和 `string-width@8.x`，这些包要求 Node.js >= 20。使用 Node.js 18 会导致 `SyntaxError: Invalid regular expression flags` 错误。请确保升级到 Node.js 20 或更高版本。
+### 安装 jq
 
-**可选**：Codex CLI（后端）、Gemini CLI（前端）
+```bash
+# macOS
+brew install jq
 
-## 首次设置
+# Linux (Debian/Ubuntu)
+sudo apt install jq
 
-首次运行时，CCG 会提示你选择语言（简体中文 / English）。选择后自动保存，后续使用无需再选。
+# Linux (RHEL/CentOS)
+sudo yum install jq
 
-## 命令
+# Windows
+choco install jq   # 或: scoop install jq
+```
 
-| 命令 | 说明 |
-|------|------|
-| `/ccg:workflow` | 6 阶段完整工作流 |
-| `/ccg:plan` | 多模型协作规划 (Phase 1-2) |
-| `/ccg:execute` | 多模型协作执行 (Phase 3-5) |
-| `/ccg:feat` | 新功能开发 |
-| `/ccg:frontend` | 前端任务 (Gemini) |
-| `/ccg:backend` | 后端任务 (Codex) |
-| `/ccg:analyze` | 技术分析 |
-| `/ccg:debug` | 问题诊断 |
-| `/ccg:optimize` | 性能优化 |
-| `/ccg:test` | 测试生成 |
-| `/ccg:review` | 代码审查 |
-| `/ccg:commit` | Git 提交 |
-| `/ccg:rollback` | Git 回滚 |
-| `/ccg:clean-branches` | 清理分支 |
-| `/ccg:worktree` | Worktree 管理 |
-| `/ccg:init` | 初始化 CLAUDE.md |
-| `/ccg:enhance` | Prompt 增强 |
-| `/ccg:spec-init` | 初始化 OPSX 环境 |
-| `/ccg:spec-research` | 需求 → 约束集 |
-| `/ccg:spec-plan` | 约束 → 零决策计划 |
-| `/ccg:spec-impl` | 按计划执行 + 归档 |
-| `/ccg:spec-review` | 双模型交叉审查 |
-| `/ccg:team-research` | Agent Teams 需求 → 约束集 |
-| `/ccg:team-plan` | Agent Teams 约束 → 并行计划 |
-| `/ccg:team-exec` | Agent Teams 并行实施 |
-| `/ccg:team-review` | Agent Teams 双模型审查 |
-| `/ccg:codex-exec` | Codex 全权执行（计划 → 代码 → 审核） |
+### 安装 Claude Code
 
-### OPSX 规范驱动（v1.7.52+）
+```bash
+npx ccg-workflow menu  # 选择「安装 Claude Code」
+```
 
-集成 [OPSX 架构](https://github.com/fission-ai/opsx)，把需求变成约束，让 AI 没法自由发挥：
+支持：npm、homebrew、curl、powershell、cmd。
 
-```bash
-# 初始化 OPSX 环境
-/ccg:spec-init
+## 命令
 
-# 研究需求 → 输出约束集
-/ccg:spec-research 实现用户认证
+### 开发工作流
 
-# 并行分析 → 零决策计划
-/ccg:spec-plan
+| 命令 | 说明 | 模型 |
+|------|------|------|
+| `/ccg:workflow` | 6 阶段完整工作流 | Codex + Gemini |
+| `/ccg:plan` | 多模型协作规划 (Phase 1-2) | Codex + Gemini |
+| `/ccg:execute` | 多模型协作执行 (Phase 3-5) | Codex + Gemini + Claude |
+| `/ccg:codex-exec` | Codex 全权执行（计划 → 代码 → 审核） | Codex + 多模型审核 |
+| `/ccg:feat` | 智能功能开发 | 自动路由 |
+| `/ccg:frontend` | 前端任务（快速模式） | Gemini |
+| `/ccg:backend` | 后端任务（快速模式） | Codex |
 
-# 按计划执行
-/ccg:spec-impl
+### 分析与质量
 
-# 独立审查（随时可用）
-/ccg:spec-review
-```
+| 命令 | 说明 | 模型 |
+|------|------|------|
+| `/ccg:analyze` | 技术分析 | Codex + Gemini |
+| `/ccg:debug` | 问题诊断 + 修复 | Codex + Gemini |
+| `/ccg:optimize` | 性能优化 | Codex + Gemini |
+| `/ccg:test` | 测试生成 | 自动路由 |
+| `/ccg:review` | 代码审查（自动 git diff） | Codex + Gemini |
+| `/ccg:enhance` | Prompt 增强 | 内置 |
 
-**说明**：`/ccg:spec-*` 命令是 CCG 对 OPSX 的封装，内部调用 `/opsx:*` 命令。每阶段之间可 `/clear`，状态存在 `openspec/` 目录，不怕上下文爆。
+### OPSX 规范驱动
 
-### Agent Teams 并行实施（v1.7.60+）
+| 命令 | 说明 |
+|------|------|
+| `/ccg:spec-init` | 初始化 OPSX 环境 |
+| `/ccg:spec-research` | 需求 → 约束集 |
+| `/ccg:spec-plan` | 约束 → 零决策计划 |
+| `/ccg:spec-impl` | 按计划执行 + 归档 |
+| `/ccg:spec-review` | 双模型交叉审查 |
 
-利用 Claude Code Agent Teams 实验特性，spawn 多个 Builder teammates 并行写代码：
+### Agent Teams（v1.7.60+）
 
-```bash
-# 1. 需求研究 → 约束集（复杂项目推荐，简单项目可跳过）
-/ccg:team-research 实现实时协作看板 API
+| 命令 | 说明 |
+|------|------|
+| `/ccg:team-research` | 需求 → 约束集（并行探索） |
+| `/ccg:team-plan` | 约束 → 并行实施计划 |
+| `/ccg:team-exec` | spawn Builder teammates 并行写代码 |
+| `/ccg:team-review` | 双模型交叉审查 |
 
-# 2. /clear 后规划 → 零决策并行计划
-/ccg:team-plan kanban-api
+> **前置条件**：需在 `settings.json` 中启用：`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`
 
-# 3. /clear 后并行实施 → Builder teammates 并行写代码
-/ccg:team-exec
+### Git 工具
 
-# 4. /clear 后审查 → 双模型交叉审查
-/ccg:team-review
-```
+| 命令 | 说明 |
+|------|------|
+| `/ccg:commit` | 智能提交（conventional commit 格式） |
+| `/ccg:rollback` | 交互式回滚 |
+| `/ccg:clean-branches` | 清理已合并分支 |
+| `/ccg:worktree` | Worktree 管理 |
 
-**前置条件**：需手动启用 Agent Teams（`settings.json` 中设置 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`）
+### 项目管理
 
-**vs 传统工作流**：Team 系列每步 `/clear` 隔离上下文，通过文件传递状态。Builder 并行实施，适合可拆分为 3+ 独立模块的任务。
+| 命令 | 说明 |
+|------|------|
+| `/ccg:init` | 初始化项目 CLAUDE.md |
 
-### 规划与执行分离
+## 工作流指南
 
-v1.7.39 新增 `/ccg:plan` 和 `/ccg:execute` 命令，将规划与执行解耦：
+### 规划与执行分离
 
 ```bash
 # 1. 生成实施计划
@@ -123,31 +160,66 @@ v1.7.39 新增 `/ccg:plan` 和 `/ccg:execute` 命令，将规划与执行解耦
 /ccg:codex-exec .claude/plan/user-auth.md
 ```
 
+### OPSX 规范驱动工作流
+
+集成 [OPSX 架构](https://github.com/fission-ai/opsx)，把需求变成约束，让 AI 没法自由发挥：
+
+```bash
+/ccg:spec-init                       # 初始化 OPSX 环境
+/ccg:spec-research 实现用户认证        # 研究需求 → 输出约束集
+/ccg:spec-plan                       # 并行分析 → 零决策计划
+/ccg:spec-impl                       # 按计划执行
+/ccg:spec-review                     # 独立审查（随时可用）
+```
+
+> **提示**：`/ccg:spec-*` 命令内部调用 `/opsx:*`。每阶段之间可 `/clear`，状态存在 `openspec/` 目录，不怕上下文爆。
+
+### Agent Teams 并行工作流
+
+利用 Claude Code Agent Teams 实验特性，spawn 多个 Builder teammates 并行写代码：
+
+```bash
+/ccg:team-research 实现实时协作看板 API  # 1. 需求 → 约束集
+# /clear
+/ccg:team-plan kanban-api               # 2. 规划 → 并行计划
+# /clear
+/ccg:team-exec                          # 3. Builder 并行写代码
+# /clear
+/ccg:team-review                        # 4. 双模型交叉审查
+```
+
+> **vs 传统工作流**：Team 系列每步 `/clear` 隔离上下文，通过文件传递状态。适合可拆分为 3+ 独立模块的任务。
+
 ## 配置
 
 ### 目录结构
 
 ```
 ~/.claude/
-├── commands/ccg/       # 斜杠命令
+├── commands/ccg/       # 26 个斜杠命令
 ├── agents/ccg/         # 子智能体
-├── skills/             # 质量关卡 + 多 Agent 协同
+├── skills/ccg/         # 质量关卡 + 多 Agent 协同
 ├── bin/codeagent-wrapper
 └── .ccg/
-    ├── config.toml
-    └── prompts/{codex,gemini}/
+    ├── config.toml     # CCG 配置
+    └── prompts/
+        ├── codex/      # 6 个 Codex 专家提示词
+        └── gemini/     # 7 个 Gemini 专家提示词
 ```
 
 ### 环境变量
 
-| 变量 | 说明 | 默认值 |
-|------|------|--------|
-| `CODEAGENT_POST_MESSAGE_DELAY` | Codex 完成后等待时间（秒） | 5 |
-| `CODEX_TIMEOUT` | codeagent-wrapper 执行超时（秒） | 7200 |
-| `BASH_DEFAULT_TIMEOUT_MS` | Claude Code Bash 默认超时（毫秒） | 120000 |
-| `BASH_MAX_TIMEOUT_MS` | Claude Code Bash 最大超时（毫秒） | 600000 |
+在 `~/.claude/settings.json` 的 `"env"` 中配置：
+
+| 变量 | 说明 | 默认值 | 何时修改 |
+|------|------|--------|----------|
+| `CODEAGENT_POST_MESSAGE_DELAY` | Codex 完成后等待时间（秒） | `5` | Codex 进程挂起时设为 `1` |
+| `CODEX_TIMEOUT` | wrapper 执行超时（秒） | `7200` | 超长任务时增大 |
+| `BASH_DEFAULT_TIMEOUT_MS` | Claude Code Bash 超时（毫秒） | `120000` | 命令超时时增大 |
+| `BASH_MAX_TIMEOUT_MS` | Claude Code Bash 最大超时（毫秒） | `600000` | 长时间构建时增大 |
 
-配置方式（`~/.claude/settings.json`）：
+<details>
+<summary>settings.json 示例</summary>
 
 ```json
 {
@@ -160,79 +232,32 @@ v1.7.39 新增 `/ccg:plan` 和 `/ccg:execute` 命令，将规划与执行解耦
 }
 ```
 
-### codeagent-wrapper 自动授权
-
-CCG 安装时会自动向 `settings.json` 写入 Hook 配置，自动授权 codeagent-wrapper 命令，无需每次手动确认。
-
-**前置条件**：需要系统安装 `jq` 命令。
-
-```bash
-# macOS
-brew install jq
-
-# Linux (Debian/Ubuntu)
-sudo apt install jq
-
-# Linux (RHEL/CentOS)
-sudo yum install jq
-
-# Windows
-choco install jq
-# 或
-scoop install jq
-```
+</details>
 
 ### MCP 配置
 
-代码检索 MCP（二选一）：
-- **ace-tool**（推荐）- 代码检索 `search_context` 可用（注：`enhance_prompt` 已不可用）。[官方](https://augmentcode.com/) | [第三方中转（推荐）](https://acemcp.heroman.wtf/)
-- **ContextWeaver**（备选）- 本地混合搜索，需要硅基流动 API Key（免费）
-
-辅助工具 MCP（可选）：
-- **Context7** - 获取最新库文档
-- **Playwright** - 浏览器自动化/测试
-- **DeepWiki** - 知识库查询
-- **Exa** - 搜索引擎（需 API Key）
-
 ```bash
-# 配置 MCP
 npx ccg-workflow menu  # 选择「配置 MCP」
 ```
 
-## 实用工具
-
-```bash
-npx ccg-workflow menu  # 选择「实用工具」
-```
-
-- **ccusage** - Claude Code 用量分析
-- **CCometixLine** - 状态栏工具（Git + 用量跟踪）
-
-## 安装 Claude Code
+**代码检索**（二选一）：
+- **ace-tool**（推荐）— 代码检索 `search_context` 可用。[官方](https://augmentcode.com/) | [第三方中转](https://acemcp.heroman.wtf/)
+- **ContextWeaver**（备选）— 本地混合搜索，需要硅基流动 API Key（免费）
 
-```bash
-npx ccg-workflow menu  # 选择「安装 Claude Code」
-```
-
-支持多种安装方式：npm、homebrew、curl、powershell、cmd
-
-## 更新 / 卸载
-
-```bash
-# 更新
-npx ccg-workflow@latest          # npx 用户
-npm install -g ccg-workflow@latest  # npm 全局用户
+**辅助工具**（可选）：
+- **Context7** — 获取最新库文档（自动安装）
+- **Playwright** — 浏览器自动化 / 测试
+- **DeepWiki** — 知识库查询
+- **Exa** — 搜索引擎（需 API Key）
 
-# 卸载
-npx ccg-workflow  # 选择 "卸载工作流"
-npm uninstall -g ccg-workflow  # npm 全局用户需额外执行
-```
+### 自动授权 Hook
 
-## 常见问题
+CCG 安装时自动写入 Hook，自动授权 `codeagent-wrapper` 命令（需 [jq](#安装-jq)）。
 
-### 1. 如何让 codeagent-wrapper 无需手动同意即可运行？
+<details>
+<summary>手动配置（v1.7.71 之前的版本）</summary>
 
-v1.7.71+ 安装时会自动写入 Hook。如果你是旧版本用户，可手动在 `~/.claude/settings.json` 中添加：
+在 `~/.claude/settings.json` 中添加：
 
 ```json
 {
@@ -243,7 +268,7 @@ v1.7.71+ 安装时会自动写入 Hook。如果你是旧版本用户，可手动
         "hooks": [
           {
             "type": "command",
-            "command": "jq -r '.tool_input.command' | grep -q 'codeagent-wrapper' && echo '{\"hookSpecificOutput\": {\"hookEventName\": \"PreToolUse\", \"permissionDecision\": \"allow\", \"permissionDecisionReason\": \"codeagent-wrapper 命令自动通过\"}}' || exit 1",
+            "command": "jq -r '.tool_input.command' | grep -q 'codeagent-wrapper' && echo '{\"hookSpecificOutput\": {\"hookEventName\": \"PreToolUse\", \"permissionDecision\": \"allow\", \"permissionDecisionReason\": \"codeagent-wrapper auto-approved\"}}' || exit 1",
             "timeout": 1
           }
         ]
@@ -253,37 +278,49 @@ v1.7.71+ 安装时会自动写入 Hook。如果你是旧版本用户，可手动
 }
 ```
 
-> **注**：需要确保电脑已经安装了 `jq` 命令。安装方法见 [codeagent-wrapper 自动授权](#codeagent-wrapper-自动授权)。
+</details>
 
-### 2. Codex CLI 0.80.0 进程不退出
+## 实用工具
 
-`--json` 模式下 Codex 完成输出后进程不会自动退出。
+```bash
+npx ccg-workflow menu  # 选择「实用工具」
+```
 
-解决：设置 `CODEAGENT_POST_MESSAGE_DELAY=1`
+- **ccusage** — Claude Code 用量分析
+- **CCometixLine** — 状态栏工具（Git + 用量跟踪）
 
-## 架构
+## 更新 / 卸载
 
-```
-Claude Code (编排)
-       │
-   ┌───┴───┐
-   ↓       ↓
-Codex   Gemini
-(后端)   (前端)
-   │       │
-   └───┬───┘
-       ↓
-  Unified Patch
+```bash
+# 更新
+npx ccg-workflow@latest            # npx 用户
+npm install -g ccg-workflow@latest  # npm 全局用户
+
+# 卸载
+npx ccg-workflow  # 选择「卸载工作流」
+npm uninstall -g ccg-workflow  # npm 全局用户需额外执行
 ```
 
-外部模型无写入权限，仅返回 Patch，由 Claude 审核后应用。
+## 常见问题
+
+### Codex CLI 0.80.0 进程不退出
+
+`--json` 模式下 Codex 完成输出后进程不会自动退出。
+
+**解决**：将 `CODEAGENT_POST_MESSAGE_DELAY` 设为 `1`，详见[环境变量](#环境变量)。
+
+## 参与贡献
+
+欢迎贡献！请阅读 [CONTRIBUTING.md](./CONTRIBUTING.md) 了解开发指南。
+
+想找一个入手点？查看标记为 [`good first issue`](https://github.com/fengshao1227/ccg-workflow/labels/good%20first%20issue) 的 Issue。
 
 ## 致谢
 
-- [cexll/myclaude](https://github.com/cexll/myclaude) - codeagent-wrapper
-- [UfoMiao/zcf](https://github.com/UfoMiao/zcf) - Git 工具
-- [GudaStudio/skills](https://github.com/GuDaStudio/skills) - 路由设计
-- [ace-tool](https://linux.do/t/topic/1344562) - MCP 工具
+- [cexll/myclaude](https://github.com/cexll/myclaude) — codeagent-wrapper
+- [UfoMiao/zcf](https://github.com/UfoMiao/zcf) — Git 工具
+- [GudaStudio/skills](https://github.com/GuDaStudio/skills) — 路由设计
+- [ace-tool](https://linux.do/t/topic/1344562) — MCP 工具
 
 ## Star History
 
@@ -295,4 +332,4 @@ MIT
 
 ---
 
-v1.7.75 | [Issues](https://github.com/fengshao1227/ccg-workflow/issues)
+v1.7.77 | [Issues](https://github.com/fengshao1227/ccg-workflow/issues) | [参与贡献](./CONTRIBUTING.md)

package/dist/cli.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import cac from 'cac';
 import ansis from 'ansis';
-import { z as diagnoseMcpConfig, A as isWindows, B as readClaudeCodeConfig, C as fixWindowsMcpConfig, D as writeClaudeCodeConfig, r as readCcgConfig, b as initI18n, a as i18n, s as showMainMenu, i as init, E as configMcp, F as version } from './shared/ccg-workflow.C09usDEA.mjs';
+import { z as diagnoseMcpConfig, A as isWindows, B as readClaudeCodeConfig, C as fixWindowsMcpConfig, D as writeClaudeCodeConfig, r as readCcgConfig, b as initI18n, a as i18n, s as showMainMenu, i as init, E as configMcp, F as version } from './shared/ccg-workflow.Dgh3VYDe.mjs';
 import 'inquirer';
 import 'node:child_process';
 import 'node:util';

package/dist/index.mjs

@@ -1,4 +1,4 @@
-export { c as changeLanguage, x as checkForUpdates, y as compareVersions, d as createDefaultConfig, e as createDefaultRouting, g as getCcgDir, f as getConfigPath, t as getCurrentVersion, v as getLatestVersion, j as getWorkflowById, h as getWorkflowConfigs, a as i18n, i as init, b as initI18n, l as installAceTool, m as installAceToolRs, k as installWorkflows, p as migrateToV1_4_0, q as needsMigration, r as readCcgConfig, s as showMainMenu, o as uninstallAceTool, n as uninstallWorkflows, u as update, w as writeCcgConfig } from './shared/ccg-workflow.C09usDEA.mjs';
+export { c as changeLanguage, x as checkForUpdates, y as compareVersions, d as createDefaultConfig, e as createDefaultRouting, g as getCcgDir, f as getConfigPath, t as getCurrentVersion, v as getLatestVersion, j as getWorkflowById, h as getWorkflowConfigs, a as i18n, i as init, b as initI18n, l as installAceTool, m as installAceToolRs, k as installWorkflows, p as migrateToV1_4_0, q as needsMigration, r as readCcgConfig, s as showMainMenu, o as uninstallAceTool, n as uninstallWorkflows, u as update, w as writeCcgConfig } from './shared/ccg-workflow.Dgh3VYDe.mjs';
 import 'ansis';
 import 'inquirer';
 import 'node:child_process';

package/dist/shared/{ccg-workflow.C09usDEA.mjs → ccg-workflow.Dgh3VYDe.mjs}

@@ -10,7 +10,7 @@ import { parse, stringify } from 'smol-toml';
 import i18next from 'i18next';
 import ora from 'ora';
 
-const version = "1.7.75";
+const version = "1.7.77";
 
 function isWindows() {
   return process.platform === "win32";
@@ -156,6 +156,9 @@ async function diagnoseMcpConfig() {
   return issues;
 }
 
+const GITHUB_REPO = "fengshao1227/ccg-workflow";
+const RELEASE_TAG = "preset";
+const BINARY_DOWNLOAD_URL = `https://github.com/${GITHUB_REPO}/releases/download/${RELEASE_TAG}`;
 const __filename$2 = fileURLToPath(import.meta.url);
 const __dirname$2 = dirname(__filename$2);
 function findPackageRoot$1(startDir) {
@@ -169,6 +172,19 @@ function findPackageRoot$1(startDir) {
   return startDir;
 }
 const PACKAGE_ROOT$1 = findPackageRoot$1(__dirname$2);
+async function downloadBinaryFromRelease(binaryName, destPath) {
+  const url = `${BINARY_DOWNLOAD_URL}/${binaryName}`;
+  const response = await fetch(url, { redirect: "follow" });
+  if (!response.ok) {
+    return false;
+  }
+  const buffer = Buffer.from(await response.arrayBuffer());
+  await fs.writeFile(destPath, buffer);
+  if (process.platform !== "win32") {
+    await fs.chmod(destPath, 493);
+  }
+  return true;
+}
 const WORKFLOW_CONFIGS = [
   {
     id: "workflow",
@@ -729,13 +745,23 @@ ${workflow.description}
       result.configPath = commandsDir;
       return result;
     }
-    const srcBinary = join(PACKAGE_ROOT$1, "bin", binaryName);
     const destBinary = join(binDir, platform === "win32" ? "codeagent-wrapper.exe" : "codeagent-wrapper");
-    if (await fs.pathExists(srcBinary)) {
-      await fs.copy(srcBinary, destBinary);
-      if (platform !== "win32") {
-        await fs.chmod(destBinary, 493);
+    let installed = false;
+    try {
+      installed = await downloadBinaryFromRelease(binaryName, destBinary);
+    } catch {
+    }
+    if (!installed) {
+      const srcBinary = join(PACKAGE_ROOT$1, "bin", binaryName);
+      if (await fs.pathExists(srcBinary)) {
+        await fs.copy(srcBinary, destBinary);
+        if (platform !== "win32") {
+          await fs.chmod(destBinary, 493);
+        }
+        installed = true;
       }
+    }
+    if (installed) {
       try {
         const { execSync } = await import('node:child_process');
         execSync(`"${destBinary}" --version`, { stdio: "pipe" });
@@ -746,7 +772,7 @@ ${workflow.description}
         result.success = false;
       }
     } else {
-      result.errors.push(`Binary not found in package: ${binaryName}`);
+      result.errors.push(`Failed to obtain binary: ${binaryName} (download failed, no local fallback)`);
       result.success = false;
     }
   } catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccg-workflow",
-  "version": "1.7.75",
+  "version": "1.7.77",
   "description": "Claude + Codex + Gemini multi-model collaboration system - smart routing development workflow",
   "type": "module",
   "packageManager": "pnpm@10.17.1",
@@ -25,7 +25,7 @@
   "module": "dist/index.mjs",
   "types": "dist/index.d.mts",
   "files": [
-    "bin",
+    "bin/ccg.mjs",
     "dist",
     "templates/commands/analyze.md",
     "templates/commands/backend.md",