ccg-workflow 1.7.68 → 1.7.70

package/README.md

@@ -6,137 +6,141 @@
 [![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)
 
+[简体中文](./README.zh-CN.md) | English
+
 </div>
 
-Claude Code 编排 Codex + Gemini 的多模型协作开发系统。前端任务路由至 Gemini，后端任务路由至 Codex，Claude 负责编排决策和代码审核。
+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
 
 ```bash
 npx ccg-workflow
 ```
 
-**要求**：Claude Code CLI、Node.js 20+
-
-> **重要**：本项目依赖 `ora@9.x` 和 `string-width@8.x`，这些包要求 Node.js >= 20。使用 Node.js 18 会导致 `SyntaxError: Invalid regular expression flags` 错误。请确保升级到 Node.js 20 或更高版本。
-
-**可选**：Codex CLI（后端）、Gemini CLI（前端）
-
-## 命令
-
-| 命令 | 说明 |
-|------|------|
-| `/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 双模型审查 |
-
-### OPSX 规范驱动（v1.7.52+）
-
-集成 [OPSX 架构](https://github.com/fission-ai/opsx)，把需求变成约束，让 AI 没法自由发挥：
+**Requirements**: Claude Code CLI, Node.js 20+
+
+> **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.
+
+**Optional**: Codex CLI (backend), Gemini CLI (frontend)
+
+## First-Time Setup
+
+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.
+
+## Commands
+
+| 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 |
+
+### OPSX Spec-Driven (v1.7.52+)
+
+Integrates [OPSX architecture](https://github.com/fission-ai/opsx) to turn requirements into constraints, eliminating AI improvisation:
 
 ```bash
-# 初始化 OPSX 环境
+# Initialize OPSX environment
 /ccg:spec-init
 
-# 研究需求 → 输出约束集
-/ccg:spec-research 实现用户认证
+# Research requirements → output constraints
+/ccg:spec-research implement user authentication
 
-# 并行分析 → 零决策计划
+# Parallel analysis → zero-decision plan
 /ccg:spec-plan
 
-# 按计划执行
+# Execute the plan
 /ccg:spec-impl
 
-# 独立审查（随时可用）
+# Independent review (available anytime)
 /ccg:spec-review
 ```
 
-**说明**：`/ccg:spec-*` 命令是 CCG 对 OPSX 的封装，内部调用 `/opsx:*` 命令。每阶段之间可 `/clear`，状态存在 `openspec/` 目录，不怕上下文爆。
+**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.
 
-### Agent Teams 并行实施（v1.7.60+）
+### Agent Teams Parallel Execution (v1.7.60+)
 
-利用 Claude Code Agent Teams 实验特性，spawn 多个 Builder teammates 并行写代码：
+Leverage Claude Code Agent Teams experimental feature to spawn multiple Builder teammates for parallel coding:
 
 ```bash
-# 1. 需求研究 → 约束集（复杂项目推荐，简单项目可跳过）
-/ccg:team-research 实现实时协作看板 API
+# 1. Requirements research → constraints (recommended for complex projects)
+/ccg:team-research implement real-time collaboration kanban API
 
-# 2. /clear 后规划 → 零决策并行计划
+# 2. /clear then plan → zero-decision parallel plan
 /ccg:team-plan kanban-api
 
-# 3. /clear 后并行实施 → Builder teammates 并行写代码
+# 3. /clear then parallel execution → Builder teammates write code in parallel
 /ccg:team-exec
 
-# 4. /clear 后审查 → 双模型交叉审查
+# 4. /clear then review → dual-model cross-review
 /ccg:team-review
 ```
 
-**前置条件**：需手动启用 Agent Teams（`settings.json` 中设置 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`）
-
-**vs 传统工作流**：Team 系列每步 `/clear` 隔离上下文，通过文件传递状态。Builder 并行实施，适合可拆分为 3+ 独立模块的任务。
+**Prerequisite**: Manually enable Agent Teams (`settings.json`: set `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`)
 
-### 规划与执行分离
+**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.
 
-v1.7.39 新增 `/ccg:plan` 和 `/ccg:execute` 命令，将规划与执行解耦：
+### Planning & Execution Separation
 
 ```bash
-# 1. 生成实施计划
-/ccg:plan 实现用户认证功能
+# 1. Generate implementation plan
+/ccg:plan implement user authentication
 
-# 2. 审查计划（可修改）
-# 计划保存至 .claude/plan/user-auth.md
+# 2. Review the plan (editable)
+# Plan saved to .claude/plan/user-auth.md
 
-# 3. 执行计划（新会话也可执行）
+# 3. Execute the plan (works in new sessions too)
 /ccg:execute .claude/plan/user-auth.md
 ```
 
-## 配置
+## Configuration
 
-### 目录结构
+### Directory Structure
 
 ```
 ~/.claude/
-├── commands/ccg/       # 斜杠命令
-├── agents/ccg/         # 子智能体
+├── commands/ccg/       # Slash commands
+├── agents/ccg/         # Sub-agents
 ├── bin/codeagent-wrapper
 └── .ccg/
     ├── config.toml
     └── prompts/{codex,gemini}/
 ```
 
-### 环境变量
+### Environment Variables
 
-| 变量 | 说明 | 默认值 |
-|------|------|--------|
-| `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 |
+| 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 |
 
-配置方式（`~/.claude/settings.json`）：
+Configuration in `~/.claude/settings.json`:
 
 ```json
 {
@@ -149,83 +153,130 @@ v1.7.39 新增 `/ccg:plan` 和 `/ccg:execute` 命令，将规划与执行解耦
 }
 ```
 
-### MCP 配置
+### 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
+```
+
+### MCP Configuration
 
-代码检索 MCP（二选一）：
-- **ContextWeaver**（推荐）- 本地混合搜索，需要硅基流动 API Key（免费）
-- **ace-tool**（收费）- Augment 官方，Token 获取：https://augmentcode.com/
+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)
 
-辅助工具 MCP（可选）：
-- **Context7** - 获取最新库文档
-- **Playwright** - 浏览器自动化/测试
-- **DeepWiki** - 知识库查询
-- **Exa** - 搜索引擎（需 API Key）
+Optional MCP tools:
+- **Context7** - Latest library documentation
+- **Playwright** - Browser automation/testing
+- **DeepWiki** - Knowledge base queries
+- **Exa** - Search engine (requires API Key)
 
 ```bash
-# 配置 MCP
-npx ccg-workflow menu  # 选择「配置 MCP」
+# Configure MCP
+npx ccg-workflow menu  # Select "Configure MCP"
 ```
 
-## 实用工具
+## Tools
 
 ```bash
-npx ccg-workflow menu  # 选择「实用工具」
+npx ccg-workflow menu  # Select "Tools"
 ```
 
-- **ccusage** - Claude Code 用量分析
-- **CCometixLine** - 状态栏工具（Git + 用量跟踪）
+- **ccusage** - Claude Code usage analytics
+- **CCometixLine** - Status bar tool (Git + usage tracking)
 
-## 安装 Claude Code
+## Install Claude Code
 
 ```bash
-npx ccg-workflow menu  # 选择「安装 Claude Code」
+npx ccg-workflow menu  # Select "Install Claude Code"
 ```
 
-支持多种安装方式：npm、homebrew、curl、powershell、cmd
+Supports multiple installation methods: npm, homebrew, curl, powershell, cmd
 
-## 更新 / 卸载
+## Update / Uninstall
 
 ```bash
-# 更新
-npx ccg-workflow@latest          # npx 用户
-npm install -g ccg-workflow@latest  # npm 全局用户
+# 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
+```
+
+## FAQ
+
+### 1. How to auto-authorize codeagent-wrapper without manual approval?
 
-# 卸载
-npx ccg-workflow  # 选择 "卸载工作流"
-npm uninstall -g ccg-workflow  # npm 全局用户需额外执行
+CCG automatically installs the Hook during setup (v1.7.70+). If you installed an older version, add this to `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "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
+          }
+        ]
+      }
+    ]
+  }
+}
 ```
 
-## 已知问题
+> **Note**: Requires `jq` installed on your system. See [codeagent-wrapper Auto-Authorization](#codeagent-wrapper-auto-authorization) for install instructions.
 
-**Codex CLI 0.80.0 进程不退出**
+### 2. Codex CLI 0.80.0 process does not exit
 
-`--json` 模式下 Codex 完成输出后进程不会自动退出。
+In `--json` mode, Codex does not automatically exit after output completion.
 
-解决：设置 `CODEAGENT_POST_MESSAGE_DELAY=1`
+Fix: Set `CODEAGENT_POST_MESSAGE_DELAY=1`
 
-## 架构
+## Architecture
 
 ```
-Claude Code (编排)
+Claude Code (Orchestrator)
        │
    ┌───┴───┐
    ↓       ↓
 Codex   Gemini
-(后端)   (前端)
+(Backend) (Frontend)
    │       │
    └───┬───┘
        ↓
   Unified Patch
 ```
 
-外部模型无写入权限，仅返回 Patch，由 Claude 审核后应用。
+External models have no write access — they only return patches, which Claude reviews before applying.
 
-## 致谢
+## Credits
 
 - [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 工具
+- [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
 
@@ -237,4 +288,4 @@ MIT
 
 ---
 
-v1.7.68 | [Issues](https://github.com/fengshao1227/ccg-workflow/issues)
+v1.7.70 | [Issues](https://github.com/fengshao1227/ccg-workflow/issues)