ccg-workflow 1.7.74 → 1.7.76

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.74 | [Issues](https://github.com/fengshao1227/ccg-workflow/issues)
+v1.7.76 | [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.74 | [Issues](https://github.com/fengshao1227/ccg-workflow/issues)
+v1.7.76 | [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.Cj1gMkci.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.Dt7J0_mT.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.Cj1gMkci.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.Dt7J0_mT.mjs';
 import 'ansis';
 import 'inquirer';
 import 'node:child_process';

package/dist/shared/{ccg-workflow.Cj1gMkci.mjs → ccg-workflow.Dt7J0_mT.mjs}

@@ -10,7 +10,7 @@ import { parse, stringify } from 'smol-toml';
 import i18next from 'i18next';
 import ora from 'ora';
 
-const version = "1.7.74";
+const version = "1.7.76";
 
 function isWindows() {
   return process.platform === "win32";
@@ -669,9 +669,22 @@ ${workflow.description}
     }
   }
   const skillsTemplateDir = join(templateDir, "skills");
-  const skillsDestDir = join(installDir, "skills");
+  const skillsDestDir = join(installDir, "skills", "ccg");
   if (await fs.pathExists(skillsTemplateDir)) {
     try {
+      const oldSkillsRoot = join(installDir, "skills");
+      const ccgLegacyItems = ["tools", "orchestration", "SKILL.md", "run_skill.js"];
+      const needsMigration = !await fs.pathExists(skillsDestDir) && await fs.pathExists(join(oldSkillsRoot, "tools"));
+      if (needsMigration) {
+        await fs.ensureDir(skillsDestDir);
+        for (const item of ccgLegacyItems) {
+          const oldPath = join(oldSkillsRoot, item);
+          const newPath = join(skillsDestDir, item);
+          if (await fs.pathExists(oldPath)) {
+            await fs.move(oldPath, newPath, { overwrite: true });
+          }
+        }
+      }
       await fs.copy(skillsTemplateDir, skillsDestDir, {
         overwrite: force,
         errorOnExist: false
@@ -756,7 +769,7 @@ async function uninstallWorkflows(installDir) {
   const commandsDir = join(installDir, "commands", "ccg");
   join(installDir, ".ccg", "prompts");
   const agentsDir = join(installDir, "agents", "ccg");
-  const skillsDir = join(installDir, "skills");
+  const skillsDir = join(installDir, "skills", "ccg");
   const binDir = join(installDir, "bin");
   const ccgConfigDir = join(installDir, ".ccg");
   if (await fs.pathExists(commandsDir)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccg-workflow",
-  "version": "1.7.74",
+  "version": "1.7.76",
   "description": "Claude + Codex + Gemini multi-model collaboration system - smart routing development workflow",
   "type": "module",
   "packageManager": "pnpm@10.17.1",

package/templates/commands/spec-impl.md

@@ -22,13 +22,17 @@ description: '按规范执行 + 多模型协作 + 归档'
    - Confirm with user which change ID to implement.
    - Run `openspec status --change "<change_id>" --json` to review tasks.
 
-2. **Apply OPSX Change**
+2. **Apply OPSX Change (Pre-flight Check)**
    - Call `/opsx:apply` internally to enter implementation mode:
      ```
      /opsx:apply
      ```
    - This will load the change context and guide you through the tasks defined in `tasks.md`.
    - **Note**: This is an internal call. If this step fails, guide the user to re-run `/ccg:spec-impl`.
+   - **HARD GATE**: Check the returned `state` field:
+     - If `state: "blocked"` → STOP immediately. Inform the user which artifacts are missing and suggest: "Run `/ccg:spec-plan` to generate missing artifacts first."
+     - If `progress.total === 0` → STOP immediately. Inform: "tasks.md has no parseable tasks. Run `/ccg:spec-plan` to regenerate."
+     - Only proceed to Step 3 when `state: "ready"` and `progress.total > 0`.
 
 3. **Identify Minimal Verifiable Phase**
    - Review `tasks.md` and identify the **smallest verifiable phase**.

package/templates/commands/spec-plan.md

@@ -15,6 +15,7 @@ description: '多模型分析 → 消除歧义 → 零决策可执行计划'
 - Refer to `openspec/config.yaml` for project conventions.
 - **USER GUIDANCE RULE**: When suggesting next steps to the user, ALWAYS use CCG commands (`/ccg:spec-research`, `/ccg:spec-plan`, `/ccg:spec-impl`, `/ccg:spec-review`). NEVER suggest `/opsx:*` commands to the user. If OpenSpec CLI returns error messages referencing OPSX skills, translate them to CCG equivalents.
 - **TASKS FORMAT RULE**: When generating or modifying `tasks.md`, ALL tasks MUST use checkbox format (`- [ ] X.Y description`). Heading+bullet format will cause OpenSpec CLI to parse 0 tasks and block the workflow.
+- **PHASE BOUNDARY**: This phase ONLY generates OPSX artifacts (specs.md, design.md, tasks.md). Do NOT modify any source code. Do NOT proceed to implementation. After artifacts are generated, STOP and inform the user: "Plan complete. Run `/ccg:spec-impl` to start implementation."
 
 **Steps**
 1. **Select Change**
@@ -114,6 +115,9 @@ description: '多模型分析 → 消除歧义 → 零决策可执行计划'
      ```
    - The OPSX skill will use the above summary to create specs.md, design.md, and tasks.md.
    - **Note**: This is an internal call. If this step fails, guide the user to re-run `/ccg:spec-plan`.
+   - **STOP**: After artifacts are generated, verify they exist and inform user:
+     "Plan phase complete. Artifacts generated: specs.md, design.md, tasks.md. Run `/ccg:spec-impl` to start implementation."
+     Do NOT proceed to modify source code.
 
 6. **Context Checkpoint**
    - Report current context usage.

package/templates/commands/spec-research.md

@@ -16,6 +16,7 @@ description: '需求 → 约束集（并行探索 + OPSX 提案）'
 - Use `{{MCP_SEARCH_TOOL}}` to minimize grep/find operations.
 - Do not make architectural decisions—surface constraints that guide decisions.
 - **USER GUIDANCE RULE**: When suggesting next steps to the user, ALWAYS use CCG commands (`/ccg:spec-research`, `/ccg:spec-plan`, `/ccg:spec-impl`, `/ccg:spec-review`). NEVER suggest `/opsx:*` commands to the user. If OpenSpec CLI returns error messages referencing OPSX skills, translate them to CCG equivalents.
+- **PHASE BOUNDARY**: This phase ONLY generates the OPSX proposal artifact. Do NOT modify any source code. Do NOT proceed to planning or implementation. After the proposal is generated, STOP and inform the user: "Research complete. Run `/ccg:spec-plan` to continue."
 
 **Steps**
 0. **MANDATORY: Enhance Requirement FIRST**
@@ -137,6 +138,9 @@ description: '需求 → 约束集（并行探索 + OPSX 提案）'
      ```
    - The OPSX skill will use the above summary to write proposal.md.
    - **Note**: This is an internal call. If this step fails, guide the user to re-run `/ccg:spec-research`.
+   - **STOP**: After proposal is generated, verify it exists and inform user:
+     "Research phase complete. Proposal generated. Run `/ccg:spec-plan` to continue planning."
+     Do NOT proceed to planning or implementation.
 
 8. **Context Checkpoint**
    - Report current context usage.