From 261196a804147efbbab21a91b54db6688aa4a9e0 Mon Sep 17 00:00:00 2001
From: catlog22 <catlog22@github.com>
Date: Sat, 24 Jan 2026 15:05:37 +0800
Subject: [PATCH] docs: update CCW CLI commands with recommended commands and
 usage examples

---
 .claude/commands/ccw-coordinator.md | 10 +++++--
 README.md                           | 43 +++++++++++++++++++++++++++++
 README_CN.md                        | 43 +++++++++++++++++++++++++++++
 3 files changed, 93 insertions(+), 3 deletions(-)

diff --git a/.claude/commands/ccw-coordinator.md b/.claude/commands/ccw-coordinator.md
index 9de38302..c72261aa 100644
--- a/.claude/commands/ccw-coordinator.md
+++ b/.claude/commands/ccw-coordinator.md
@@ -882,7 +882,10 @@ Task: Implement user registration' --tool claude --mode write
 
 ### Serial Blocking
 
-Commands execute one-by-one. After launching CLI in background, orchestrator stops immediately and waits for hook callback.
+**CRITICAL**: Commands execute one-by-one. After launching CLI in background:
+1. Orchestrator stops immediately (`break`)
+2. Wait for hook callback - **DO NOT use TaskOutput polling**
+3. Hook callback triggers next command
 
 **Prompt Structure**: Command must be first in prompt content
 
@@ -892,12 +895,13 @@ const prompt = '/workflow:plan -y "Implement user authentication"\n\nTask: Imple
 const taskId = Bash(`ccw cli -p "${prompt}" --tool claude --mode write`, { run_in_background: true }).task_id;
 state.execution_results.push({ status: 'in-progress', task_id: taskId, ... });
 Write(`${stateDir}/state.json`, JSON.stringify(state, null, 2));
-break; // Stop, wait for hook callback
+break; // ⚠️ STOP HERE - DO NOT use TaskOutput polling
 
-// Hook calls handleCliCompletion(sessionId, taskId, output) when done
+// Hook callback will call handleCliCompletion(sessionId, taskId, output) when done
 // → Updates state → Triggers next command via resumeChainExecution()
 ```
 
+
 ## Available Commands
 
 All from `~/.claude/commands/workflow/`:
diff --git a/README.md b/README.md
index 6a57d9e9..786f50c2 100644
--- a/README.md
+++ b/README.md
@@ -263,6 +263,49 @@ Open Dashboard via `ccw view`, manage indexes and execute searches in **CodexLen
 
 ## 💻 CCW CLI Commands
 
+### 🌟 Recommended Commands (Main Features)
+
+<div align="center">
+<table>
+<tr><th>Command</th><th>Description</th><th>When to Use</th></tr>
+<tr>
+  <td><b>/ccw</b></td>
+  <td>Auto workflow orchestrator - analyzes intent, selects workflow level, executes command chain in main process</td>
+  <td>✅ General tasks, auto workflow selection, quick development</td>
+</tr>
+<tr>
+  <td><b>/ccw-coordinator</b></td>
+  <td>Manual orchestrator - recommends command chains, executes via external CLI with state persistence</td>
+  <td>🔧 Complex multi-step workflows, custom chains, resumable sessions</td>
+</tr>
+</table>
+</div>
+
+**Quick Examples**:
+
+```bash
+# /ccw - Auto workflow selection (Main Process)
+/ccw "Add user authentication"              # Auto-selects workflow based on intent
+/ccw "Fix memory leak in WebSocket"         # Detects bugfix workflow
+/ccw "Implement with TDD"                   # Routes to TDD workflow
+
+# /ccw-coordinator - Manual chain orchestration (External CLI)
+/ccw-coordinator "Implement OAuth2 system"  # Analyzes → Recommends chain → User confirms → Executes
+```
+
+**Key Differences**:
+
+| Aspect | /ccw | /ccw-coordinator |
+|--------|------|------------------|
+| **Execution** | Main process (SlashCommand) | External CLI (background tasks) |
+| **Selection** | Auto intent-based | Manual chain confirmation |
+| **State** | TodoWrite tracking | Persistent state.json |
+| **Use Case** | General tasks, quick dev | Complex chains, resumable |
+
+---
+
+### Other CLI Commands
+
 ```bash
 ccw install           # Install workflow files
 ccw view              # Open dashboard
diff --git a/README_CN.md b/README_CN.md
index 016a1f21..cef78c7b 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -263,6 +263,49 @@ codexlens index /path/to/project
 
 ## 💻 CCW CLI 命令
 
+### 🌟 推荐命令（核心功能）
+
+<div align="center">
+<table>
+<tr><th>命令</th><th>说明</th><th>适用场景</th></tr>
+<tr>
+  <td><b>/ccw</b></td>
+  <td>自动工作流编排器 - 分析意图、自动选择工作流级别、在主进程中执行命令链</td>
+  <td>✅ 通用任务、自动选择工作流、快速开发</td>
+</tr>
+<tr>
+  <td><b>/ccw-coordinator</b></td>
+  <td>手动编排器 - 推荐命令链、通过外部 CLI 执行、持久化状态</td>
+  <td>🔧 复杂多步骤工作流、自定义链、可恢复会话</td>
+</tr>
+</table>
+</div>
+
+**快速示例**：
+
+```bash
+# /ccw - 自动工作流选择（主进程）
+/ccw "添加用户认证"                    # 自动根据意图选择工作流
+/ccw "修复 WebSocket 中的内存泄漏"     # 识别为 bugfix 工作流
+/ccw "使用 TDD 方式实现"                # 路由到 TDD 工作流
+
+# /ccw-coordinator - 手动链编排（外部 CLI）
+/ccw-coordinator "实现 OAuth2 系统"     # 分析 → 推荐链 → 用户确认 → 执行
+```
+
+**主要区别**：
+
+| 方面 | /ccw | /ccw-coordinator |
+|------|------|------------------|
+| **执行方式** | 主进程（SlashCommand） | 外部 CLI（后台任务） |
+| **选择方式** | 自动基于意图识别 | 手动链确认 |
+| **状态管理** | TodoWrite 跟踪 | 持久化 state.json |
+| **适用场景** | 通用任务、快速开发 | 复杂链条、可恢复 |
+
+---
+
+### 其他 CLI 命令
+
 ```bash
 ccw install           # 安装工作流文件
 ccw view              # 打开 Dashboard