docs: add English version of Workflow Decision Guide

Add WORKFLOW_DECISION_GUIDE_EN.md with complete English translation of the workflow decision guide, including:
- Full lifecycle command selection flowchart
- Decision point explanations with examples
- Testing and review strategies
- Complete flows for typical scenarios
- Quick reference tables by knowledge level, project phase, and work mode
- Best practices and common pitfalls

.claude/commands/task/replan.md

@@ -7,6 +7,14 @@ allowed-tools: Read(*), Write(*), Edit(*), TodoWrite(*), Glob(*), Bash(*)
 
 # Task Replan Command (/task:replan)
 
+> **⚠️ DEPRECATION NOTICE**: This command is maintained for backward compatibility. For new workflows, use `/workflow:replan` which provides:
+> - Session-level replanning with comprehensive artifact updates
+> - Interactive boundary clarification
+> - Updates to IMPL_PLAN.md, TODO_LIST.md, and session metadata
+> - Better integration with workflow sessions
+>
+> **Migration**: Replace `/task:replan IMPL-1 "changes"` with `/workflow:replan IMPL-1 "changes"`
+
 ## Overview
 Replans individual tasks or batch processes multiple tasks with change tracking and backup management.
 
@@ -14,9 +22,6 @@ Replans individual tasks or batch processes multiple tasks with change tracking
 - **Single Task Mode**: Replan one task with specific changes
 - **Batch Mode**: Process multiple tasks from action-plan verification report
 
-## Core Principles
-**Task System:** @~/.claude/workflows/task-core.md
-
 ## Key Features
 - **Single/Batch Operations**: Single task or multiple tasks from verification report
 - **Multiple Input Sources**: Text, files, or verification report

.claude/commands/workflow/replan.md

@@ -0,0 +1,470 @@
+---
+name: replan
+description: Interactive workflow replanning with session-level artifact updates and boundary clarification through guided questioning
+argument-hint: "[--session session-id] [task-id] \"requirements\"|file.md [--interactive]"
+allowed-tools: Read(*), Write(*), Edit(*), TodoWrite(*), Glob(*), Bash(*)
+---
+
+# Workflow Replan Command
+
+## Overview
+Intelligently replans workflow sessions or individual tasks with interactive boundary clarification and comprehensive artifact updates.
+
+**Core Capabilities**:
+- **Session Replan**: Updates multiple artifacts (IMPL_PLAN.md, TODO_LIST.md, task JSONs)
+- **Task Replan**: Focused updates within session context
+- **Interactive Clarification**: Guided questioning to define modification boundaries
+- **Impact Analysis**: Automatic detection of affected files and dependencies
+- **Backup Management**: Preserves previous versions with restore capability
+
+## Operation Modes
+
+### Session Replan Mode
+
+```bash
+# Auto-detect active session
+/workflow:replan "添加双因素认证支持"
+
+# Explicit session
+/workflow:replan --session WFS-oauth "添加双因素认证支持"
+
+# File-based input
+/workflow:replan --session WFS-oauth requirements-update.md
+
+# Interactive mode
+/workflow:replan --interactive
+```
+
+### Task Replan Mode
+
+```bash
+# Direct task update
+/workflow:replan IMPL-1 "修改为使用 OAuth2.0 标准"
+
+# Task with explicit session
+/workflow:replan --session WFS-oauth IMPL-2 "增加单元测试覆盖率到 90%"
+
+# Interactive mode
+/workflow:replan IMPL-1 --interactive
+```
+
+## Execution Lifecycle
+
+### Phase 1: Mode Detection & Session Discovery
+
+**Process**:
+1. **Detect Operation Mode**:
+   - Check if task ID provided (IMPL-N or IMPL-N.M format) → Task mode
+   - Otherwise → Session mode
+
+2. **Discover/Validate Session**:
+   - Use `--session` flag if provided
+   - Otherwise auto-detect from `.workflow/active/`
+   - Validate session exists
+
+3. **Load Session Context**:
+   - Read `workflow-session.json`
+   - List existing tasks
+   - Read `IMPL_PLAN.md` and `TODO_LIST.md`
+
+**Output**: Session validated, context loaded, mode determined
+
+---
+
+### Phase 2: Interactive Requirement Clarification
+
+**Purpose**: Define modification scope through guided questioning
+
+#### Session Mode Questions
+
+**Q1: Modification Scope**
+```javascript
+Options:
+- 仅更新任务细节 (tasks_only)
+- 修改规划方案 (plan_update)
+- 重构任务结构 (task_restructure)
+- 全面重规划 (comprehensive)
+```
+
+**Q2: Affected Modules** (if scope >= plan_update)
+```javascript
+Options: Dynamically generated from existing tasks' focus_paths
+- 认证模块 (src/auth)
+- 用户管理 (src/user)
+- 全部模块
+```
+
+**Q3: Task Changes** (if scope >= task_restructure)
+```javascript
+Options:
+- 添加新任务
+- 删除现有任务
+- 合并任务
+- 拆分任务
+- 仅更新内容
+```
+
+**Q4: Dependency Changes**
+```javascript
+Options:
+- 是,需要重新梳理依赖
+- 否,保持现有依赖
+```
+
+#### Task Mode Questions
+
+**Q1: Update Type**
+```javascript
+Options:
+- 需求和验收标准 (requirements & acceptance)
+- 实现方案 (implementation_approach)
+- 文件范围 (focus_paths)
+- 依赖关系 (depends_on)
+- 全部更新
+```
+
+**Q2: Ripple Effect**
+```javascript
+Options:
+- 是,需要同步更新依赖任务
+- 否,仅影响当前任务
+- 不确定,请帮我分析
+```
+
+**Output**: User selections stored, modification boundaries defined
+
+---
+
+### Phase 3: Impact Analysis & Planning
+
+**Step 3.1: Analyze Required Changes**
+
+Determine affected files based on clarification:
+
+```typescript
+interface ImpactAnalysis {
+  affected_files: {
+    impl_plan: boolean;
+    todo_list: boolean;
+    session_meta: boolean;
+    tasks: string[];
+  };
+
+  operations: {
+    type: 'create' | 'update' | 'delete' | 'merge' | 'split';
+    target: string;
+    reason: string;
+  }[];
+
+  backup_strategy: {
+    timestamp: string;
+    files: string[];
+  };
+}
+```
+
+**Step 3.2: Generate Modification Plan**
+
+```markdown
+## 修改计划
+
+### 影响范围
+- [ ] IMPL_PLAN.md: 更新技术方案第 3 节
+- [ ] TODO_LIST.md: 添加 2 个新任务,删除 1 个废弃任务
+- [ ] IMPL-001.json: 更新实现方案
+- [ ] workflow-session.json: 更新任务计数
+
+### 变更操作
+1. **创建**: IMPL-004.json (双因素认证实现)
+2. **更新**: IMPL-001.json (添加 2FA 准备工作)
+3. **删除**: IMPL-003.json (已被新方案替代)
+```
+
+**Step 3.3: User Confirmation**
+
+```javascript
+Options:
+- 确认执行: 开始应用所有修改
+- 调整计划: 重新回答问题调整范围
+- 取消操作: 放弃本次重规划
+```
+
+**Output**: Modification plan confirmed or adjusted
+
+---
+
+### Phase 4: Backup Creation
+
+**Process**:
+
+1. **Create Backup Directory**:
+```bash
+timestamp=$(date -u +"%Y-%m-%dT%H-%M-%S")
+backup_dir=".workflow/active/$SESSION_ID/.process/backup/replan-$timestamp"
+mkdir -p "$backup_dir"
+```
+
+2. **Backup All Affected Files**:
+   - IMPL_PLAN.md
+   - TODO_LIST.md
+   - workflow-session.json
+   - Affected task JSONs
+
+3. **Create Backup Manifest**:
+```markdown
+# Replan Backup Manifest
+
+**Timestamp**: {timestamp}
+**Reason**: {replan_reason}
+**Scope**: {modification_scope}
+
+## Restoration Command
+cp {backup_dir}/* .workflow/active/{session}/
+```
+
+**Output**: All files safely backed up with manifest
+
+---
+
+### Phase 5: Apply Modifications
+
+**Step 5.1: Update IMPL_PLAN.md** (if needed)
+
+Use Edit tool to modify specific sections:
+- Update affected technical sections
+- Update modification date
+
+**Step 5.2: Update TODO_LIST.md** (if needed)
+
+- Add new tasks with `[ ]` checkbox
+- Mark deleted tasks as `[x] ~~task~~ (已废弃)`
+- Update modified task descriptions
+
+**Step 5.3: Update Task JSONs**
+
+For each affected task:
+```typescript
+const updated_task = {
+  ...task,
+  context: {
+    ...task.context,
+    requirements: [...updated_requirements],
+    acceptance: [...updated_acceptance]
+  },
+  flow_control: {
+    ...task.flow_control,
+    implementation_approach: [...updated_steps]
+  }
+};
+
+Write({
+  file_path: `.workflow/active/${SESSION_ID}/.task/${task_id}.json`,
+  content: JSON.stringify(updated_task, null, 2)
+});
+```
+
+**Step 5.4: Create New Tasks** (if needed)
+
+Generate complete task JSON with all required fields:
+- id, title, status
+- meta (type, agent)
+- context (requirements, focus_paths, acceptance)
+- flow_control (pre_analysis, implementation_approach, target_files)
+
+**Step 5.5: Delete Obsolete Tasks** (if needed)
+
+Move to backup instead of hard delete:
+```bash
+mv ".workflow/active/$SESSION_ID/.task/{task-id}.json" "$backup_dir/"
+```
+
+**Step 5.6: Update Session Metadata**
+
+Update workflow-session.json:
+- progress.current_tasks
+- progress.last_replan
+- replan_history array
+
+**Output**: All modifications applied, artifacts updated
+
+---
+
+### Phase 6: Verification & Summary
+
+**Step 6.1: Verify Consistency**
+
+1. Validate all task JSONs are valid JSON
+2. Check task count within limits (max 10)
+3. Verify dependency graph is acyclic
+
+**Step 6.2: Generate Change Summary**
+
+```markdown
+## 重规划完成
+
+### 会话信息
+- **Session**: {session-id}
+- **时间**: {timestamp}
+- **备份**: {backup-path}
+
+### 变更摘要
+**范围**: {scope}
+**原因**: {reason}
+
+### 修改的文件
+- ✓ IMPL_PLAN.md: {changes}
+- ✓ TODO_LIST.md: {changes}
+- ✓ Task JSONs: {count} files updated
+
+### 任务变更
+- **新增**: {task-ids}
+- **删除**: {task-ids}
+- **更新**: {task-ids}
+
+### 回滚方法
+cp {backup-path}/* .workflow/active/{session}/
+```
+
+**Output**: Summary displayed, replan complete
+
+---
+
+## TodoWrite Progress Tracking
+
+### Session Mode Progress
+
+```json
+[
+  {"content": "检测模式和发现会话", "status": "completed", "activeForm": "检测模式和发现会话"},
+  {"content": "交互式需求明确", "status": "completed", "activeForm": "交互式需求明确"},
+  {"content": "影响分析和计划生成", "status": "completed", "activeForm": "影响分析和计划生成"},
+  {"content": "创建备份", "status": "completed", "activeForm": "创建备份"},
+  {"content": "更新会话产出文件", "status": "completed", "activeForm": "更新会话产出文件"},
+  {"content": "验证一致性", "status": "completed", "activeForm": "验证一致性"}
+]
+```
+
+### Task Mode Progress
+
+```json
+[
+  {"content": "检测会话和加载任务", "status": "completed", "activeForm": "检测会话和加载任务"},
+  {"content": "交互式更新确认", "status": "completed", "activeForm": "交互式更新确认"},
+  {"content": "应用任务修改", "status": "completed", "activeForm": "应用任务修改"}
+]
+```
+
+## Error Handling
+
+### Session Errors
+
+```bash
+# No active session found
+ERROR: No active session found
+Run /workflow:session:start to create a session
+
+# Session not found
+ERROR: Session WFS-invalid not found
+Available sessions: [list]
+
+# No changes specified
+WARNING: No modifications specified
+Use --interactive mode or provide requirements
+```
+
+### Task Errors
+
+```bash
+# Task not found
+ERROR: Task IMPL-999 not found in session
+Available tasks: [list]
+
+# Task completed
+WARNING: Task IMPL-001 is completed
+Consider creating new task for additional work
+
+# Circular dependency
+ERROR: Circular dependency detected
+Resolve dependency conflicts before proceeding
+```
+
+### Validation Errors
+
+```bash
+# Task limit exceeded
+ERROR: Replan would create 12 tasks (limit: 10)
+Consider: combining tasks, splitting sessions, or removing tasks
+
+# Invalid JSON
+ERROR: Generated invalid JSON
+Backup preserved, rolling back changes
+```
+
+## File Structure
+
+```
+.workflow/active/WFS-session-name/
+├── workflow-session.json
+├── IMPL_PLAN.md
+├── TODO_LIST.md
+├── .task/
+│   ├── IMPL-001.json
+│   ├── IMPL-002.json
+│   └── IMPL-003.json
+└── .process/
+    ├── context-package.json
+    └── backup/
+        └── replan-{timestamp}/
+            ├── MANIFEST.md
+            ├── IMPL_PLAN.md
+            ├── TODO_LIST.md
+            ├── workflow-session.json
+            └── IMPL-*.json
+```
+
+## Examples
+
+### Session Replan - Add Feature
+
+```bash
+/workflow:replan "添加双因素认证支持"
+
+# Interactive clarification
+Q: 修改范围?
+A: 全面重规划
+
+Q: 受影响模块?
+A: 认证模块, API接口
+
+Q: 任务变更?
+A: 添加新任务, 更新内容
+
+# Execution
+✓ 创建备份
+✓ 更新 IMPL_PLAN.md
+✓ 更新 TODO_LIST.md
+✓ 创建 IMPL-004.json
+✓ 更新 IMPL-001.json, IMPL-002.json
+
+重规划完成! 新增 1 任务,更新 2 任务
+```
+
+### Task Replan - Update Requirements
+
+```bash
+/workflow:replan IMPL-001 "支持 OAuth2.0 标准"
+
+# Interactive clarification
+Q: 更新部分?
+A: 需求和验收标准, 实现方案
+
+Q: 影响其他任务?
+A: 是,需要同步更新依赖任务
+
+# Execution
+✓ 创建备份
+✓ 更新 IMPL-001.json
+✓ 更新 IMPL-002.json (依赖任务)
+
+任务重规划完成! 更新 2 个任务
+```

.claude/skills/command-guide/reference/commands/task/replan.md

@@ -7,6 +7,14 @@ allowed-tools: Read(*), Write(*), Edit(*), TodoWrite(*), Glob(*), Bash(*)
 
 # Task Replan Command (/task:replan)
 
+> **⚠️ DEPRECATION NOTICE**: This command is maintained for backward compatibility. For new workflows, use `/workflow:replan` which provides:
+> - Session-level replanning with comprehensive artifact updates
+> - Interactive boundary clarification
+> - Updates to IMPL_PLAN.md, TODO_LIST.md, and session metadata
+> - Better integration with workflow sessions
+>
+> **Migration**: Replace `/task:replan IMPL-1 "changes"` with `/workflow:replan IMPL-1 "changes"`
+
 ## Overview
 Replans individual tasks or batch processes multiple tasks with change tracking and backup management.
 
@@ -14,9 +22,6 @@ Replans individual tasks or batch processes multiple tasks with change tracking
 - **Single Task Mode**: Replan one task with specific changes
 - **Batch Mode**: Process multiple tasks from action-plan verification report
 
-## Core Principles
-**Task System:** @~/.claude/workflows/task-core.md
-
 ## Key Features
 - **Single/Batch Operations**: Single task or multiple tasks from verification report
 - **Multiple Input Sources**: Text, files, or verification report
@@ -274,7 +279,7 @@ Backup saved to .task/backup/IMPL-2-v1.0.json
 
 ### Batch Mode - From Verification Report
 ```bash
-/task:replan --batch .workflow/WFS-{session}/.process/ACTION_PLAN_VERIFICATION.md
+/task:replan --batch .workflow/active/WFS-{session}/.process/ACTION_PLAN_VERIFICATION.md
 
 Parsing verification report...
 Found 4 tasks requiring replanning:

.claude/skills/command-guide/reference/commands/workflow/replan.md

@@ -0,0 +1,470 @@
+---
+name: replan
+description: Interactive workflow replanning with session-level artifact updates and boundary clarification through guided questioning
+argument-hint: "[--session session-id] [task-id] \"requirements\"|file.md [--interactive]"
+allowed-tools: Read(*), Write(*), Edit(*), TodoWrite(*), Glob(*), Bash(*)
+---
+
+# Workflow Replan Command
+
+## Overview
+Intelligently replans workflow sessions or individual tasks with interactive boundary clarification and comprehensive artifact updates.
+
+**Core Capabilities**:
+- **Session Replan**: Updates multiple artifacts (IMPL_PLAN.md, TODO_LIST.md, task JSONs)
+- **Task Replan**: Focused updates within session context
+- **Interactive Clarification**: Guided questioning to define modification boundaries
+- **Impact Analysis**: Automatic detection of affected files and dependencies
+- **Backup Management**: Preserves previous versions with restore capability
+
+## Operation Modes
+
+### Session Replan Mode
+
+```bash
+# Auto-detect active session
+/workflow:replan "添加双因素认证支持"
+
+# Explicit session
+/workflow:replan --session WFS-oauth "添加双因素认证支持"
+
+# File-based input
+/workflow:replan --session WFS-oauth requirements-update.md
+
+# Interactive mode
+/workflow:replan --interactive
+```
+
+### Task Replan Mode
+
+```bash
+# Direct task update
+/workflow:replan IMPL-1 "修改为使用 OAuth2.0 标准"
+
+# Task with explicit session
+/workflow:replan --session WFS-oauth IMPL-2 "增加单元测试覆盖率到 90%"
+
+# Interactive mode
+/workflow:replan IMPL-1 --interactive
+```
+
+## Execution Lifecycle
+
+### Phase 1: Mode Detection & Session Discovery
+
+**Process**:
+1. **Detect Operation Mode**:
+   - Check if task ID provided (IMPL-N or IMPL-N.M format) → Task mode
+   - Otherwise → Session mode
+
+2. **Discover/Validate Session**:
+   - Use `--session` flag if provided
+   - Otherwise auto-detect from `.workflow/active/`
+   - Validate session exists
+
+3. **Load Session Context**:
+   - Read `workflow-session.json`
+   - List existing tasks
+   - Read `IMPL_PLAN.md` and `TODO_LIST.md`
+
+**Output**: Session validated, context loaded, mode determined
+
+---
+
+### Phase 2: Interactive Requirement Clarification
+
+**Purpose**: Define modification scope through guided questioning
+
+#### Session Mode Questions
+
+**Q1: Modification Scope**
+```javascript
+Options:
+- 仅更新任务细节 (tasks_only)
+- 修改规划方案 (plan_update)
+- 重构任务结构 (task_restructure)
+- 全面重规划 (comprehensive)
+```
+
+**Q2: Affected Modules** (if scope >= plan_update)
+```javascript
+Options: Dynamically generated from existing tasks' focus_paths
+- 认证模块 (src/auth)
+- 用户管理 (src/user)
+- 全部模块
+```
+
+**Q3: Task Changes** (if scope >= task_restructure)
+```javascript
+Options:
+- 添加新任务
+- 删除现有任务
+- 合并任务
+- 拆分任务
+- 仅更新内容
+```
+
+**Q4: Dependency Changes**
+```javascript
+Options:
+- 是,需要重新梳理依赖
+- 否,保持现有依赖
+```
+
+#### Task Mode Questions
+
+**Q1: Update Type**
+```javascript
+Options:
+- 需求和验收标准 (requirements & acceptance)
+- 实现方案 (implementation_approach)
+- 文件范围 (focus_paths)
+- 依赖关系 (depends_on)
+- 全部更新
+```
+
+**Q2: Ripple Effect**
+```javascript
+Options:
+- 是,需要同步更新依赖任务
+- 否,仅影响当前任务
+- 不确定,请帮我分析
+```
+
+**Output**: User selections stored, modification boundaries defined
+
+---
+
+### Phase 3: Impact Analysis & Planning
+
+**Step 3.1: Analyze Required Changes**
+
+Determine affected files based on clarification:
+
+```typescript
+interface ImpactAnalysis {
+  affected_files: {
+    impl_plan: boolean;
+    todo_list: boolean;
+    session_meta: boolean;
+    tasks: string[];
+  };
+
+  operations: {
+    type: 'create' | 'update' | 'delete' | 'merge' | 'split';
+    target: string;
+    reason: string;
+  }[];
+
+  backup_strategy: {
+    timestamp: string;
+    files: string[];
+  };
+}
+```
+
+**Step 3.2: Generate Modification Plan**
+
+```markdown
+## 修改计划
+
+### 影响范围
+- [ ] IMPL_PLAN.md: 更新技术方案第 3 节
+- [ ] TODO_LIST.md: 添加 2 个新任务,删除 1 个废弃任务
+- [ ] IMPL-001.json: 更新实现方案
+- [ ] workflow-session.json: 更新任务计数
+
+### 变更操作
+1. **创建**: IMPL-004.json (双因素认证实现)
+2. **更新**: IMPL-001.json (添加 2FA 准备工作)
+3. **删除**: IMPL-003.json (已被新方案替代)
+```
+
+**Step 3.3: User Confirmation**
+
+```javascript
+Options:
+- 确认执行: 开始应用所有修改
+- 调整计划: 重新回答问题调整范围
+- 取消操作: 放弃本次重规划
+```
+
+**Output**: Modification plan confirmed or adjusted
+
+---
+
+### Phase 4: Backup Creation
+
+**Process**:
+
+1. **Create Backup Directory**:
+```bash
+timestamp=$(date -u +"%Y-%m-%dT%H-%M-%S")
+backup_dir=".workflow/active/$SESSION_ID/.process/backup/replan-$timestamp"
+mkdir -p "$backup_dir"
+```
+
+2. **Backup All Affected Files**:
+   - IMPL_PLAN.md
+   - TODO_LIST.md
+   - workflow-session.json
+   - Affected task JSONs
+
+3. **Create Backup Manifest**:
+```markdown
+# Replan Backup Manifest
+
+**Timestamp**: {timestamp}
+**Reason**: {replan_reason}
+**Scope**: {modification_scope}
+
+## Restoration Command
+cp {backup_dir}/* .workflow/active/{session}/
+```
+
+**Output**: All files safely backed up with manifest
+
+---
+
+### Phase 5: Apply Modifications
+
+**Step 5.1: Update IMPL_PLAN.md** (if needed)
+
+Use Edit tool to modify specific sections:
+- Update affected technical sections
+- Update modification date
+
+**Step 5.2: Update TODO_LIST.md** (if needed)
+
+- Add new tasks with `[ ]` checkbox
+- Mark deleted tasks as `[x] ~~task~~ (已废弃)`
+- Update modified task descriptions
+
+**Step 5.3: Update Task JSONs**
+
+For each affected task:
+```typescript
+const updated_task = {
+  ...task,
+  context: {
+    ...task.context,
+    requirements: [...updated_requirements],
+    acceptance: [...updated_acceptance]
+  },
+  flow_control: {
+    ...task.flow_control,
+    implementation_approach: [...updated_steps]
+  }
+};
+
+Write({
+  file_path: `.workflow/active/${SESSION_ID}/.task/${task_id}.json`,
+  content: JSON.stringify(updated_task, null, 2)
+});
+```
+
+**Step 5.4: Create New Tasks** (if needed)
+
+Generate complete task JSON with all required fields:
+- id, title, status
+- meta (type, agent)
+- context (requirements, focus_paths, acceptance)
+- flow_control (pre_analysis, implementation_approach, target_files)
+
+**Step 5.5: Delete Obsolete Tasks** (if needed)
+
+Move to backup instead of hard delete:
+```bash
+mv ".workflow/active/$SESSION_ID/.task/{task-id}.json" "$backup_dir/"
+```
+
+**Step 5.6: Update Session Metadata**
+
+Update workflow-session.json:
+- progress.current_tasks
+- progress.last_replan
+- replan_history array
+
+**Output**: All modifications applied, artifacts updated
+
+---
+
+### Phase 6: Verification & Summary
+
+**Step 6.1: Verify Consistency**
+
+1. Validate all task JSONs are valid JSON
+2. Check task count within limits (max 10)
+3. Verify dependency graph is acyclic
+
+**Step 6.2: Generate Change Summary**
+
+```markdown
+## 重规划完成
+
+### 会话信息
+- **Session**: {session-id}
+- **时间**: {timestamp}
+- **备份**: {backup-path}
+
+### 变更摘要
+**范围**: {scope}
+**原因**: {reason}
+
+### 修改的文件
+- ✓ IMPL_PLAN.md: {changes}
+- ✓ TODO_LIST.md: {changes}
+- ✓ Task JSONs: {count} files updated
+
+### 任务变更
+- **新增**: {task-ids}
+- **删除**: {task-ids}
+- **更新**: {task-ids}
+
+### 回滚方法
+cp {backup-path}/* .workflow/active/{session}/
+```
+
+**Output**: Summary displayed, replan complete
+
+---
+
+## TodoWrite Progress Tracking
+
+### Session Mode Progress
+
+```json
+[
+  {"content": "检测模式和发现会话", "status": "completed", "activeForm": "检测模式和发现会话"},
+  {"content": "交互式需求明确", "status": "completed", "activeForm": "交互式需求明确"},
+  {"content": "影响分析和计划生成", "status": "completed", "activeForm": "影响分析和计划生成"},
+  {"content": "创建备份", "status": "completed", "activeForm": "创建备份"},
+  {"content": "更新会话产出文件", "status": "completed", "activeForm": "更新会话产出文件"},
+  {"content": "验证一致性", "status": "completed", "activeForm": "验证一致性"}
+]
+```
+
+### Task Mode Progress
+
+```json
+[
+  {"content": "检测会话和加载任务", "status": "completed", "activeForm": "检测会话和加载任务"},
+  {"content": "交互式更新确认", "status": "completed", "activeForm": "交互式更新确认"},
+  {"content": "应用任务修改", "status": "completed", "activeForm": "应用任务修改"}
+]
+```
+
+## Error Handling
+
+### Session Errors
+
+```bash
+# No active session found
+ERROR: No active session found
+Run /workflow:session:start to create a session
+
+# Session not found
+ERROR: Session WFS-invalid not found
+Available sessions: [list]
+
+# No changes specified
+WARNING: No modifications specified
+Use --interactive mode or provide requirements
+```
+
+### Task Errors
+
+```bash
+# Task not found
+ERROR: Task IMPL-999 not found in session
+Available tasks: [list]
+
+# Task completed
+WARNING: Task IMPL-001 is completed
+Consider creating new task for additional work
+
+# Circular dependency
+ERROR: Circular dependency detected
+Resolve dependency conflicts before proceeding
+```
+
+### Validation Errors
+
+```bash
+# Task limit exceeded
+ERROR: Replan would create 12 tasks (limit: 10)
+Consider: combining tasks, splitting sessions, or removing tasks
+
+# Invalid JSON
+ERROR: Generated invalid JSON
+Backup preserved, rolling back changes
+```
+
+## File Structure
+
+```
+.workflow/active/WFS-session-name/
+├── workflow-session.json
+├── IMPL_PLAN.md
+├── TODO_LIST.md
+├── .task/
+│   ├── IMPL-001.json
+│   ├── IMPL-002.json
+│   └── IMPL-003.json
+└── .process/
+    ├── context-package.json
+    └── backup/
+        └── replan-{timestamp}/
+            ├── MANIFEST.md
+            ├── IMPL_PLAN.md
+            ├── TODO_LIST.md
+            ├── workflow-session.json
+            └── IMPL-*.json
+```
+
+## Examples
+
+### Session Replan - Add Feature
+
+```bash
+/workflow:replan "添加双因素认证支持"
+
+# Interactive clarification
+Q: 修改范围?
+A: 全面重规划
+
+Q: 受影响模块?
+A: 认证模块, API接口
+
+Q: 任务变更?
+A: 添加新任务, 更新内容
+
+# Execution
+✓ 创建备份
+✓ 更新 IMPL_PLAN.md
+✓ 更新 TODO_LIST.md
+✓ 创建 IMPL-004.json
+✓ 更新 IMPL-001.json, IMPL-002.json
+
+重规划完成! 新增 1 任务,更新 2 任务
+```
+
+### Task Replan - Update Requirements
+
+```bash
+/workflow:replan IMPL-001 "支持 OAuth2.0 标准"
+
+# Interactive clarification
+Q: 更新部分?
+A: 需求和验收标准, 实现方案
+
+Q: 影响其他任务?
+A: 是,需要同步更新依赖任务
+
+# Execution
+✓ 创建备份
+✓ 更新 IMPL-001.json
+✓ 更新 IMPL-002.json (依赖任务)
+
+任务重规划完成! 更新 2 个任务
+```

ARCHITECTURE.md

@@ -0,0 +1,567 @@
+# 🏗️ Claude Code Workflow (CCW) - Architecture Overview
+
+This document provides a high-level overview of CCW's architecture, design principles, and system components.
+
+---
+
+## 📋 Table of Contents
+
+- [Design Philosophy](#design-philosophy)
+- [System Architecture](#system-architecture)
+- [Core Components](#core-components)
+- [Data Flow](#data-flow)
+- [Multi-Agent System](#multi-agent-system)
+- [CLI Tool Integration](#cli-tool-integration)
+- [Session Management](#session-management)
+- [Memory System](#memory-system)
+
+---
+
+## 🎯 Design Philosophy
+
+CCW is built on several core design principles that differentiate it from traditional AI-assisted development tools:
+
+### 1. **Context-First Architecture**
+- Pre-defined context gathering eliminates execution uncertainty
+- Agents receive the correct information *before* implementation
+- Context is loaded dynamically based on task requirements
+
+### 2. **JSON-First State Management**
+- Task states live in `.task/IMPL-*.json` files as the single source of truth
+- Markdown documents are read-only generated views
+- Eliminates state drift and synchronization complexity
+- Enables programmatic orchestration
+
+### 3. **Autonomous Multi-Phase Orchestration**
+- Commands chain specialized sub-commands and agents
+- Automates complex workflows with zero user intervention
+- Each phase validates its output before proceeding
+
+### 4. **Multi-Model Strategy**
+- Leverages unique strengths of different AI models
+- Gemini for analysis and exploration
+- Codex for implementation
+- Qwen for architecture and planning
+
+### 5. **Hierarchical Memory System**
+- 4-layer documentation system (CLAUDE.md files)
+- Provides context at the appropriate level of abstraction
+- Prevents information overload
+
+### 6. **Specialized Role-Based Agents**
+- Suite of agents mirrors a real software team
+- Each agent has specific responsibilities
+- Agents collaborate to complete complex tasks
+
+---
+
+## 🏛️ System Architecture
+
+```mermaid
+graph TB
+    subgraph "User Interface Layer"
+        CLI[Slash Commands]
+        CHAT[Natural Language]
+    end
+
+    subgraph "Orchestration Layer"
+        WF[Workflow Engine]
+        SM[Session Manager]
+        TM[Task Manager]
+    end
+
+    subgraph "Agent Layer"
+        AG1[@code-developer]
+        AG2[@test-fix-agent]
+        AG3[@ui-design-agent]
+        AG4[@cli-execution-agent]
+        AG5[More Agents...]
+    end
+
+    subgraph "Tool Layer"
+        GEMINI[Gemini CLI]
+        QWEN[Qwen CLI]
+        CODEX[Codex CLI]
+        BASH[Bash/System]
+    end
+
+    subgraph "Data Layer"
+        JSON[Task JSON Files]
+        MEM[CLAUDE.md Memory]
+        STATE[Session State]
+    end
+
+    CLI --> WF
+    CHAT --> WF
+    WF --> SM
+    WF --> TM
+    SM --> STATE
+    TM --> JSON
+    WF --> AG1
+    WF --> AG2
+    WF --> AG3
+    WF --> AG4
+    AG1 --> GEMINI
+    AG1 --> QWEN
+    AG1 --> CODEX
+    AG2 --> BASH
+    AG3 --> GEMINI
+    AG4 --> CODEX
+    GEMINI --> MEM
+    QWEN --> MEM
+    CODEX --> JSON
+```
+
+---
+
+## 🔧 Core Components
+
+### 1. **Workflow Engine**
+
+The workflow engine orchestrates complex development processes through multiple phases:
+
+- **Planning Phase**: Analyzes requirements and generates implementation plans
+- **Execution Phase**: Coordinates agents to implement tasks
+- **Verification Phase**: Validates implementation quality
+- **Testing Phase**: Generates and executes tests
+- **Review Phase**: Performs code review and quality analysis
+
+**Key Features**:
+- Multi-phase orchestration
+- Automatic session management
+- Context propagation between phases
+- Quality gates at each phase transition
+
+### 2. **Session Manager**
+
+Manages isolated workflow contexts:
+
+```
+.workflow/
+├── active/                    # Active sessions
+│   ├── WFS-user-auth/        # User authentication session
+│   ├── WFS-payment/          # Payment integration session
+│   └── WFS-dashboard/        # Dashboard redesign session
+└── archives/                  # Completed sessions
+    └── WFS-old-feature/      # Archived session
+```
+
+**Capabilities**:
+- Directory-based session tracking
+- Session state persistence
+- Parallel session support
+- Session archival and resumption
+
+### 3. **Task Manager**
+
+Handles hierarchical task structures:
+
+```json
+{
+  "id": "IMPL-1.2",
+  "title": "Implement JWT authentication",
+  "status": "pending",
+  "meta": {
+    "type": "feature",
+    "agent": "code-developer"
+  },
+  "context": {
+    "requirements": ["JWT authentication", "OAuth2 support"],
+    "focus_paths": ["src/auth", "tests/auth"],
+    "acceptance": ["JWT validation works", "OAuth flow complete"]
+  },
+  "flow_control": {
+    "pre_analysis": [...],
+    "implementation_approach": {...}
+  }
+}
+```
+
+**Features**:
+- JSON-first data model
+- Hierarchical task decomposition (max 2 levels)
+- Dynamic subtask creation
+- Dependency tracking
+
+### 4. **Memory System**
+
+Four-layer hierarchical documentation:
+
+```
+CLAUDE.md (Project root - high-level overview)
+├── src/CLAUDE.md (Source layer - module summaries)
+│   ├── auth/CLAUDE.md (Module layer - component details)
+│   │   └── jwt/CLAUDE.md (Component layer - implementation details)
+```
+
+**Memory Commands**:
+- `/memory:update-full` - Complete project rebuild
+- `/memory:update-related` - Incremental updates for changed modules
+- `/memory:load` - Quick context loading for specific tasks
+
+---
+
+## 🔄 Data Flow
+
+### Typical Workflow Execution Flow
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant CLI
+    participant Workflow
+    participant Agent
+    participant Tool
+    participant Data
+
+    User->>CLI: /workflow:plan "Feature description"
+    CLI->>Workflow: Initialize planning workflow
+    Workflow->>Data: Create session
+    Workflow->>Agent: @action-planning-agent
+    Agent->>Tool: gemini-wrapper analyze
+    Tool->>Data: Update CLAUDE.md
+    Agent->>Data: Generate IMPL-*.json
+    Workflow->>User: Plan complete
+
+    User->>CLI: /workflow:execute
+    CLI->>Workflow: Start execution
+    Workflow->>Data: Load tasks from JSON
+    Workflow->>Agent: @code-developer
+    Agent->>Tool: Read context
+    Agent->>Tool: Implement code
+    Agent->>Data: Update task status
+    Workflow->>User: Execution complete
+```
+
+### Context Flow
+
+```mermaid
+graph LR
+    A[User Request] --> B[Context Gathering]
+    B --> C[CLAUDE.md Memory]
+    B --> D[Task JSON]
+    B --> E[Session State]
+    C --> F[Agent Context]
+    D --> F
+    E --> F
+    F --> G[Tool Execution]
+    G --> H[Implementation]
+    H --> I[Update State]
+```
+
+---
+
+## 🤖 Multi-Agent System
+
+### Agent Specialization
+
+CCW uses specialized agents for different types of tasks:
+
+| Agent | Responsibility | Tools Used |
+|-------|---------------|------------|
+| **@code-developer** | Code implementation | Gemini, Qwen, Codex, Bash |
+| **@test-fix-agent** | Test generation and fixing | Codex, Bash |
+| **@ui-design-agent** | UI design and prototyping | Gemini, Claude Vision |
+| **@action-planning-agent** | Task planning and decomposition | Gemini |
+| **@cli-execution-agent** | Autonomous CLI task handling | Codex, Gemini, Qwen |
+| **@cli-explore-agent** | Codebase exploration | ripgrep, find |
+| **@context-search-agent** | Context gathering | Grep, Glob |
+| **@doc-generator** | Documentation generation | Gemini, Qwen |
+| **@memory-bridge** | Memory system updates | Gemini, Qwen |
+| **@universal-executor** | General task execution | All tools |
+
+### Agent Communication
+
+Agents communicate through:
+1. **Shared Session State**: All agents can read/write session JSON
+2. **Task JSON Files**: Tasks contain context for agent handoffs
+3. **CLAUDE.md Memory**: Shared project knowledge base
+4. **Flow Control**: Pre-analysis and implementation approach definitions
+
+---
+
+## 🛠️ CLI Tool Integration
+
+### Three CLI Tools
+
+CCW integrates three external AI tools, each optimized for specific tasks:
+
+#### 1. **Gemini CLI** - Deep Analysis
+- **Strengths**: Pattern recognition, architecture understanding, comprehensive analysis
+- **Use Cases**:
+  - Codebase exploration
+  - Architecture analysis
+  - Bug diagnosis
+  - Memory system updates
+
+#### 2. **Qwen CLI** - Architecture & Planning
+- **Strengths**: System design, code generation, architectural planning
+- **Use Cases**:
+  - Architecture design
+  - System planning
+  - Code generation
+  - Refactoring strategies
+
+#### 3. **Codex CLI** - Autonomous Development
+- **Strengths**: Self-directed implementation, error fixing, test generation
+- **Use Cases**:
+  - Feature implementation
+  - Bug fixes
+  - Test generation
+  - Autonomous development
+
+### Tool Selection Strategy
+
+CCW automatically selects the best tool based on task type:
+
+```
+Analysis Task → Gemini CLI
+Planning Task → Qwen CLI
+Implementation Task → Codex CLI
+```
+
+Users can override with `--tool` parameter:
+```bash
+/cli:analyze --tool codex "Analyze authentication flow"
+```
+
+---
+
+## 📦 Session Management
+
+### Session Lifecycle
+
+```mermaid
+stateDiagram-v2
+    [*] --> Creating: /workflow:session:start
+    Creating --> Active: Session initialized
+    Active --> Paused: User pauses
+    Paused --> Active: /workflow:session:resume
+    Active --> Completed: /workflow:session:complete
+    Completed --> Archived: Move to archives/
+    Archived --> [*]
+```
+
+### Session Structure
+
+```
+.workflow/active/WFS-feature-name/
+├── workflow-session.json          # Session metadata
+├── .task/                          # Task JSON files
+│   ├── IMPL-1.json
+│   ├── IMPL-1.1.json
+│   └── IMPL-2.json
+├── .chat/                          # Chat logs
+├── brainstorming/                  # Brainstorm artifacts
+│   ├── guidance-specification.md
+│   └── system-architect/analysis.md
+└── artifacts/                      # Generated files
+    ├── IMPL_PLAN.md
+    └── verification-report.md
+```
+
+---
+
+## 💾 Memory System
+
+### Hierarchical CLAUDE.md Structure
+
+The memory system maintains project knowledge across four layers:
+
+#### **Layer 1: Project Root**
+```markdown
+# Project Overview
+- High-level architecture
+- Technology stack
+- Key design decisions
+- Entry points
+```
+
+#### **Layer 2: Source Directory**
+```markdown
+# Source Code Structure
+- Module summaries
+- Dependency relationships
+- Common patterns
+```
+
+#### **Layer 3: Module Directory**
+```markdown
+# Module Details
+- Component responsibilities
+- API interfaces
+- Internal structure
+```
+
+#### **Layer 4: Component Directory**
+```markdown
+# Component Implementation
+- Function signatures
+- Implementation details
+- Usage examples
+```
+
+### Memory Update Strategies
+
+#### Full Update (`/memory:update-full`)
+- Rebuilds entire project documentation
+- Uses layer-based execution (Layer 3 → 1)
+- Batch processing (4 modules/agent)
+- Fallback mechanism (gemini → qwen → codex)
+
+#### Incremental Update (`/memory:update-related`)
+- Updates only changed modules
+- Analyzes git changes
+- Efficient for daily development
+
+#### Quick Load (`/memory:load`)
+- No file updates
+- Task-specific context gathering
+- Returns JSON context package
+- Fast context injection
+
+---
+
+## 🔐 Quality Assurance
+
+### Quality Gates
+
+CCW enforces quality at multiple levels:
+
+1. **Planning Phase**:
+   - Requirements coverage check
+   - Dependency validation
+   - Task specification quality assessment
+
+2. **Execution Phase**:
+   - Context validation before implementation
+   - Pattern consistency checks
+   - Test generation
+
+3. **Review Phase**:
+   - Code quality analysis
+   - Security review
+   - Architecture review
+
+### Verification Commands
+
+- `/workflow:action-plan-verify` - Validates plan quality before execution
+- `/workflow:tdd-verify` - Verifies TDD cycle compliance
+- `/workflow:review` - Post-implementation review
+
+---
+
+## 🚀 Performance Optimizations
+
+### 1. **Lazy Loading**
+- Files created only when needed
+- On-demand document generation
+- Minimal upfront cost
+
+### 2. **Parallel Execution**
+- Independent tasks run concurrently
+- Multi-agent parallel brainstorming
+- Batch processing for memory updates
+
+### 3. **Context Caching**
+- CLAUDE.md acts as knowledge cache
+- Reduces redundant analysis
+- Faster context retrieval
+
+### 4. **Atomic Session Management**
+- Ultra-fast session switching (<10ms)
+- Simple file marker system
+- No database overhead
+
+---
+
+## 📊 Scalability
+
+### Horizontal Scalability
+
+- **Multiple Sessions**: Run parallel workflows for different features
+- **Team Collaboration**: Session-based isolation prevents conflicts
+- **Incremental Updates**: Only update affected modules
+
+### Vertical Scalability
+
+- **Hierarchical Tasks**: Efficient task decomposition (max 2 levels)
+- **Selective Context**: Load only relevant context for each task
+- **Batch Processing**: Process multiple modules per agent invocation
+
+---
+
+## 🔮 Extensibility
+
+### Adding New Agents
+
+Create agent definition in `.claude/agents/`:
+
+```markdown
+# Agent Name
+
+## Role
+Agent description
+
+## Tools Available
+- Tool 1
+- Tool 2
+
+## Prompt
+Agent instructions...
+```
+
+### Adding New Commands
+
+Create command in `.claude/commands/`:
+
+```bash
+#!/usr/bin/env bash
+# Command implementation
+```
+
+### Custom Workflows
+
+Combine existing commands to create custom workflows:
+
+```bash
+/workflow:brainstorm:auto-parallel "Topic"
+/workflow:plan
+/workflow:action-plan-verify
+/workflow:execute
+/workflow:review
+```
+
+---
+
+## 🎓 Best Practices
+
+### For Users
+
+1. **Keep Memory Updated**: Run `/memory:update-related` after major changes
+2. **Use Quality Gates**: Run `/workflow:action-plan-verify` before execution
+3. **Session Management**: Complete sessions with `/workflow:session:complete`
+4. **Tool Selection**: Let CCW auto-select tools unless you have specific needs
+
+### For Developers
+
+1. **Follow JSON-First**: Never modify markdown documents directly
+2. **Agent Context**: Provide complete context in task JSON
+3. **Error Handling**: Implement graceful fallbacks
+4. **Testing**: Test agents independently before integration
+
+---
+
+## 📚 Further Reading
+
+- [Getting Started Guide](GETTING_STARTED.md) - Quick start tutorial
+- [Command Reference](COMMAND_REFERENCE.md) - All available commands
+- [Command Specification](COMMAND_SPEC.md) - Detailed command specs
+- [Workflow Diagrams](WORKFLOW_DIAGRAMS.md) - Visual workflow representations
+- [Contributing Guide](CONTRIBUTING.md) - How to contribute
+- [Examples](EXAMPLES.md) - Real-world use cases
+
+---
+
+**Last Updated**: 2025-11-20
+**Version**: 5.8.1

COMMAND_REFERENCE.md

@@ -16,7 +16,7 @@ These commands provide direct access to AI tools for quick analysis and interact
 | `/cli:codex-execute` | Automated task decomposition and execution with Codex using resume mechanism. |
 | `/cli:discuss-plan` | Orchestrates an iterative, multi-model discussion for planning and analysis without implementation. |
 | `/cli:execute` | Auto-execution of implementation tasks with YOLO permissions and intelligent context inference. |
-| `/cli:mode:bug-index` | Bug analysis and fix suggestions using CLI tools. |
+| `/cli:mode:bug-diagnosis` | Bug analysis and fix suggestions using CLI tools. |
 | `/cli:mode:code-analysis` | Deep code analysis and debugging using CLI tools with specialized template. |
 | `/cli:mode:plan` | Project planning and architecture analysis using CLI tools. |
 
@@ -39,6 +39,7 @@ These commands orchestrate complex, multi-phase development processes, from plan
 |---|---|
 | `/workflow:plan` | Orchestrate 5-phase planning workflow with quality gate, executing commands and passing context between phases. |
 | `/workflow:lite-plan` | ⚡ **NEW** Lightweight interactive planning and execution workflow with in-memory planning, smart code exploration, three-dimensional multi-select confirmation (task approval + execution method + code review), and parallel task execution support. |
+| `/workflow:replan` | ⚡ **NEW** Interactive workflow replanning with session-level artifact updates and boundary clarification through guided questioning. Supports both session-wide and task-specific modifications. |
 | `/workflow:execute` | Coordinate agents for existing workflow tasks with automatic discovery. |
 | `/workflow:resume` | Intelligent workflow session resumption with automatic progress analysis. |
 | `/workflow:review` | Optional specialized review (security, architecture, docs) for completed implementation. |
@@ -122,7 +123,7 @@ Commands for managing individual tasks within a workflow session.
 | `/task:create` | Create implementation tasks with automatic context awareness. |
 | `/task:breakdown` | Intelligent task decomposition with context-aware subtask generation. |
 | `/task:execute` | Execute tasks with appropriate agents and context-aware orchestration. |
-| `/task:replan` | Replan individual tasks with detailed user input and change tracking. |
+| `/task:replan` | ⚠️ **DEPRECATED** Use `/workflow:replan` instead. Legacy command for task replanning (maintained for backward compatibility). |
 
 ## Memory and Versioning Commands
 

COMMAND_SPEC.md

@@ -79,8 +79,8 @@ High-level orchestrators for complex, multi-phase development processes.
   # Force code exploration
   /workflow:lite-plan -e "Refactor logging module for better performance"
 
-  # Preset CLI tool
-  /workflow:lite-plan --tool codex "Add unit tests for auth service"
+  # Basic usage
+  /workflow:lite-plan "Add unit tests for auth service"
   ```
 
 ### **/workflow:execute**
@@ -247,13 +247,13 @@ Direct access to AI tools for analysis and code interaction without a full workf
   /cli:execute "implement JWT authentication with middleware"
   ```
 
-### **/cli:mode:bug-index**
-- **Syntax**: `/cli:mode:bug-index [--agent] [--tool ...] [--enhance] [--cd path] <bug description>`
+### **/cli:mode:bug-diagnosis**
+- **Syntax**: `/cli:mode:bug-diagnosis [--tool ...] [--enhance] [--cd path] <bug description>`
 - **Responsibilities**: Performs systematic bug analysis using the `bug-fix.md` template. Read-only.
-- **Agent Calls**: `@cli-execution-agent` (if `--agent` is used).
+- **Agent Calls**: `@cli-execution-agent` (default).
 - **Example**:
   ```bash
-  /cli:mode:bug-index "null pointer error in login flow"
+  /cli:mode:bug-diagnosis "null pointer error in login flow"
   ```
 
 ### **/cli:mode:code-analysis**

CONTRIBUTING.md

@@ -0,0 +1,712 @@
+# 🤝 Contributing to Claude Code Workflow
+
+Thank you for your interest in contributing to Claude Code Workflow (CCW)! This document provides guidelines and instructions for contributing to the project.
+
+---
+
+## 📋 Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [Development Setup](#development-setup)
+- [How to Contribute](#how-to-contribute)
+- [Coding Standards](#coding-standards)
+- [Testing Guidelines](#testing-guidelines)
+- [Documentation Guidelines](#documentation-guidelines)
+- [Submitting Changes](#submitting-changes)
+- [Release Process](#release-process)
+
+---
+
+## 📜 Code of Conduct
+
+### Our Pledge
+
+We are committed to providing a welcoming and inclusive environment for all contributors, regardless of:
+- Experience level
+- Background
+- Identity
+- Perspective
+
+### Our Standards
+
+**Positive behaviors**:
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+**Unacceptable behaviors**:
+- Trolling, insulting/derogatory comments, and personal attacks
+- Public or private harassment
+- Publishing others' private information without permission
+- Other conduct which could reasonably be considered inappropriate
+
+---
+
+## 🚀 Getting Started
+
+### Prerequisites
+
+Before contributing, ensure you have:
+
+1. **Claude Code** - The latest version installed ([Installation Guide](INSTALL.md))
+2. **Git** - For version control
+3. **Text Editor** - VS Code, Vim, or your preferred editor
+4. **Basic Knowledge**:
+   - Bash scripting
+   - Markdown formatting
+   - JSON structure
+   - Git workflow
+
+### Understanding the Codebase
+
+Start by reading:
+1. [README.md](README.md) - Project overview
+2. [ARCHITECTURE.md](ARCHITECTURE.md) - System architecture
+3. [GETTING_STARTED.md](GETTING_STARTED.md) - Basic usage
+4. [COMMAND_SPEC.md](COMMAND_SPEC.md) - Command specifications
+
+---
+
+## 💻 Development Setup
+
+### 1. Fork and Clone
+
+```bash
+# Fork the repository on GitHub
+# Then clone your fork
+git clone https://github.com/YOUR_USERNAME/Claude-Code-Workflow.git
+cd Claude-Code-Workflow
+```
+
+### 2. Set Up Upstream Remote
+
+```bash
+git remote add upstream https://github.com/catlog22/Claude-Code-Workflow.git
+git fetch upstream
+```
+
+### 3. Create Development Branch
+
+```bash
+# Update your main branch
+git checkout main
+git pull upstream main
+
+# Create feature branch
+git checkout -b feature/your-feature-name
+```
+
+### 4. Install CCW for Testing
+
+```bash
+# Install your development version
+bash Install-Claude.sh
+
+# Or on Windows
+powershell -ExecutionPolicy Bypass -File Install-Claude.ps1
+```
+
+---
+
+## 🛠️ How to Contribute
+
+### Types of Contributions
+
+#### 1. **Bug Fixes**
+- Report bugs via [GitHub Issues](https://github.com/catlog22/Claude-Code-Workflow/issues)
+- Include reproduction steps
+- Provide system information (OS, Claude Code version)
+- Submit PR with fix
+
+#### 2. **New Features**
+- Discuss in [GitHub Discussions](https://github.com/catlog22/Claude-Code-Workflow/discussions)
+- Create feature proposal issue
+- Get community feedback
+- Implement after approval
+
+#### 3. **Documentation**
+- Fix typos or clarify existing docs
+- Add missing documentation
+- Improve examples
+- Translate to other languages
+
+#### 4. **New Commands**
+- Follow command template structure
+- Include comprehensive documentation
+- Add tests for command execution
+- Update COMMAND_REFERENCE.md
+
+#### 5. **New Agents**
+- Define agent role clearly
+- Specify tools required
+- Provide usage examples
+- Document in ARCHITECTURE.md
+
+---
+
+## 📏 Coding Standards
+
+### General Principles
+
+Follow the project's core beliefs (from [CLAUDE.md](CLAUDE.md)):
+
+1. **Pursue good taste** - Eliminate edge cases for natural, elegant code
+2. **Embrace extreme simplicity** - Avoid unnecessary complexity
+3. **Be pragmatic** - Solve real-world problems
+4. **Data structures first** - Focus on data design
+5. **Never break backward compatibility** - Existing functionality is sacred
+6. **Incremental progress** - Small changes that compile and pass tests
+7. **Learn from existing code** - Study patterns before implementing
+8. **Clear intent over clever code** - Be boring and obvious
+
+### Bash Script Standards
+
+```bash
+#!/usr/bin/env bash
+# Command: /workflow:example
+# Description: Brief description of what this command does
+
+set -euo pipefail  # Exit on error, undefined vars, pipe failures
+
+# Function definitions
+function example_function() {
+    local param1="$1"
+    local param2="${2:-default}"
+
+    # Implementation
+}
+
+# Main execution
+function main() {
+    # Validate inputs
+    # Execute logic
+    # Handle errors
+}
+
+# Run main if executed directly
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    main "$@"
+fi
+```
+
+### JSON Standards
+
+```json
+{
+  "id": "IMPL-1",
+  "title": "Task title",
+  "status": "pending",
+  "meta": {
+    "type": "feature",
+    "agent": "code-developer",
+    "priority": "high"
+  },
+  "context": {
+    "requirements": ["Requirement 1", "Requirement 2"],
+    "focus_paths": ["src/module/"],
+    "acceptance": ["Criterion 1", "Criterion 2"]
+  }
+}
+```
+
+**Rules**:
+- Use 2-space indentation
+- Always validate JSON syntax
+- Include all required fields
+- Use clear, descriptive values
+
+### Markdown Standards
+
+```markdown
+# Main Title (H1) - One per document
+
+## Section Title (H2)
+
+### Subsection (H3)
+
+- Use bullet points for lists
+- Use `code blocks` for commands
+- Use **bold** for emphasis
+- Use *italics* for technical terms
+
+```bash
+# Code blocks with language specification
+command --flag value
+```
+
+> Use blockquotes for important notes
+```
+
+### File Organization
+
+```
+.claude/
+├── agents/                 # Agent definitions
+│   ├── agent-name.md
+├── commands/               # Slash commands
+│   └── workflow/
+│       ├── workflow-plan.md
+├── skills/                 # Agent skills
+│   └── skill-name/
+│       ├── SKILL.md
+└── workflows/              # Workflow docs
+    ├── workflow-architecture.md
+```
+
+---
+
+## 🧪 Testing Guidelines
+
+### Manual Testing
+
+Before submitting PR:
+
+1. **Test the Happy Path**
+   ```bash
+   # Test basic functionality
+   /your:new:command "basic input"
+   ```
+
+2. **Test Error Handling**
+   ```bash
+   # Test with invalid input
+   /your:new:command ""
+   /your:new:command --invalid-flag
+   ```
+
+3. **Test Edge Cases**
+   ```bash
+   # Test with special characters
+   /your:new:command "input with 'quotes'"
+
+   # Test with long input
+   /your:new:command "very long input string..."
+   ```
+
+### Integration Testing
+
+Test how your changes interact with existing commands:
+
+```bash
+# Example workflow test
+/workflow:session:start "Test Feature"
+/your:new:command "test input"
+/workflow:status
+/workflow:session:complete
+```
+
+### Testing Checklist
+
+- [ ] Command executes without errors
+- [ ] Error messages are clear and helpful
+- [ ] Session state is preserved correctly
+- [ ] JSON files are created with correct structure
+- [ ] Memory system updates work correctly
+- [ ] Works on both Linux and Windows
+- [ ] Documentation is accurate
+
+---
+
+## 📚 Documentation Guidelines
+
+### Command Documentation
+
+Every new command must include:
+
+#### 1. **Inline Documentation** (in command file)
+
+```bash
+#!/usr/bin/env bash
+# Command: /workflow:example
+# Description: One-line description
+# Usage: /workflow:example [options] <arg>
+#
+# Options:
+#   --option1    Description of option1
+#   --option2    Description of option2
+#
+# Examples:
+#   /workflow:example "basic usage"
+#   /workflow:example --option1 value "advanced usage"
+```
+
+#### 2. **COMMAND_REFERENCE.md Entry**
+
+Add entry to the appropriate section:
+
+```markdown
+| `/workflow:example` | Brief description of the command. |
+```
+
+#### 3. **COMMAND_SPEC.md Entry**
+
+Add detailed specification:
+
+```markdown
+### `/workflow:example`
+
+**Purpose**: Detailed description of what this command does and when to use it.
+
+**Parameters**:
+- `arg` (required): Description of argument
+- `--option1` (optional): Description of option
+
+**Workflow**:
+1. Step 1
+2. Step 2
+3. Step 3
+
+**Output**:
+- Creates: Files created
+- Updates: Files updated
+- Returns: Return value
+
+**Examples**:
+```bash
+/workflow:example "example input"
+```
+
+**Related Commands**:
+- `/related:command1` - Description
+- `/related:command2` - Description
+```
+
+### Agent Documentation
+
+Every new agent must include:
+
+```markdown
+# Agent Name
+
+## Role
+Clear description of agent's responsibility and purpose.
+
+## Specialization
+What makes this agent unique and when to use it.
+
+## Tools Available
+- Tool 1: Usage
+- Tool 2: Usage
+- Tool 3: Usage
+
+## Invocation
+How the agent is typically invoked (manually or by workflow).
+
+## Context Requirements
+What context the agent needs to function effectively.
+
+## Output
+What the agent produces.
+
+## Examples
+Real usage examples.
+
+## Prompt
+The actual agent instructions...
+```
+
+---
+
+## 📤 Submitting Changes
+
+### Commit Message Guidelines
+
+Follow the [Conventional Commits](https://www.conventionalcommits.org/) specification:
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+**Types**:
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation changes
+- `style`: Code style changes (formatting, etc.)
+- `refactor`: Code refactoring
+- `test`: Adding or updating tests
+- `chore`: Maintenance tasks
+
+**Examples**:
+
+```
+feat(workflow): add workflow:example command
+
+Add new workflow command for example functionality.
+Includes:
+- Command implementation
+- Documentation updates
+- Test cases
+
+Closes #123
+```
+
+```
+fix(memory): resolve memory update race condition
+
+Fix race condition when multiple agents update memory
+simultaneously by adding file locking mechanism.
+
+Fixes #456
+```
+
+```
+docs(readme): update installation instructions
+
+Clarify Windows installation steps and add troubleshooting
+section for common issues.
+```
+
+### Pull Request Process
+
+1. **Update your branch**
+   ```bash
+   git fetch upstream
+   git rebase upstream/main
+   ```
+
+2. **Push to your fork**
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+3. **Create Pull Request**
+   - Go to GitHub and create PR
+   - Fill out PR template
+   - Link related issues
+   - Add screenshots/examples if applicable
+
+4. **PR Title Format**
+   ```
+   feat: Add workflow:example command
+   fix: Resolve memory update issue
+   docs: Update contributing guide
+   ```
+
+5. **PR Description Template**
+   ```markdown
+   ## Description
+   Brief description of changes
+
+   ## Type of Change
+   - [ ] Bug fix
+   - [ ] New feature
+   - [ ] Documentation update
+   - [ ] Refactoring
+
+   ## Related Issues
+   Closes #123
+
+   ## Testing
+   - [ ] Tested on Linux
+   - [ ] Tested on Windows
+   - [ ] Added/updated documentation
+
+   ## Screenshots (if applicable)
+
+   ## Checklist
+   - [ ] Code follows project style guidelines
+   - [ ] Self-review completed
+   - [ ] Documentation updated
+   - [ ] No breaking changes (or documented)
+   ```
+
+6. **Address Review Comments**
+   - Respond to all comments
+   - Make requested changes
+   - Push updates to same branch
+   - Re-request review when ready
+
+---
+
+## 🎯 Development Workflow
+
+### Feature Development
+
+```bash
+# 1. Create branch
+git checkout -b feat/new-command
+
+# 2. Implement feature
+# - Write code
+# - Add documentation
+# - Test thoroughly
+
+# 3. Commit changes
+git add .
+git commit -m "feat(workflow): add new command"
+
+# 4. Push and create PR
+git push origin feat/new-command
+```
+
+### Bug Fix
+
+```bash
+# 1. Create branch
+git checkout -b fix/issue-123
+
+# 2. Fix bug
+# - Identify root cause
+# - Implement fix
+# - Add regression test
+
+# 3. Commit fix
+git commit -m "fix: resolve issue #123"
+
+# 4. Push and create PR
+git push origin fix/issue-123
+```
+
+---
+
+## 🔄 Release Process
+
+### Version Numbering
+
+CCW follows [Semantic Versioning](https://semver.org/):
+
+- **MAJOR**: Breaking changes
+- **MINOR**: New features (backward compatible)
+- **PATCH**: Bug fixes (backward compatible)
+
+Example: `v5.8.1`
+- `5`: Major version
+- `8`: Minor version
+- `1`: Patch version
+
+### Release Checklist
+
+Maintainers will:
+
+1. Update version in:
+   - `README.md`
+   - `README_CN.md`
+   - All documentation headers
+
+2. Update `CHANGELOG.md`:
+   ```markdown
+   ## [v5.9.0] - 2025-11-20
+
+   ### Added
+   - New feature 1
+   - New feature 2
+
+   ### Fixed
+   - Bug fix 1
+   - Bug fix 2
+
+   ### Changed
+   - Change 1
+   ```
+
+3. Create release tag:
+   ```bash
+   git tag -a v5.9.0 -m "Release v5.9.0"
+   git push origin v5.9.0
+   ```
+
+4. Create GitHub Release with:
+   - Release notes from CHANGELOG.md
+   - Installation scripts
+   - Migration guide (if breaking changes)
+
+---
+
+## 💡 Tips for Contributors
+
+### Best Practices
+
+1. **Start Small**
+   - Fix documentation typos
+   - Add examples
+   - Improve error messages
+   - Then move to larger features
+
+2. **Ask Questions**
+   - Use GitHub Discussions for questions
+   - Ask before starting major work
+   - Clarify requirements early
+
+3. **Follow Existing Patterns**
+   - Study similar commands before creating new ones
+   - Maintain consistency with existing code
+   - Reuse existing utilities
+
+4. **Test Thoroughly**
+   - Test on both Linux and Windows if possible
+   - Test with different input types
+   - Test integration with existing workflows
+
+5. **Document Everything**
+   - Clear commit messages
+   - Comprehensive PR descriptions
+   - Updated documentation
+   - Code comments where necessary
+
+### Common Pitfalls to Avoid
+
+❌ **Don't**:
+- Break backward compatibility without discussion
+- Add features without documentation
+- Submit large PRs without prior discussion
+- Ignore failing tests
+- Copy code without attribution
+
+✅ **Do**:
+- Keep PRs focused and small
+- Update documentation with code changes
+- Add tests for new features
+- Follow project coding standards
+- Be responsive to review comments
+
+---
+
+## 📞 Getting Help
+
+### Resources
+
+- **Documentation**: Read all docs in repository
+- **Discussions**: [GitHub Discussions](https://github.com/catlog22/Claude-Code-Workflow/discussions)
+- **Issues**: [GitHub Issues](https://github.com/catlog22/Claude-Code-Workflow/issues)
+- **Command Guide**: Use `CCW-help` within Claude Code
+
+### Contact
+
+- **Bug Reports**: GitHub Issues
+- **Feature Requests**: GitHub Discussions
+- **Questions**: GitHub Discussions
+- **Security Issues**: Create private security advisory
+
+---
+
+## 🙏 Recognition
+
+Contributors will be:
+- Listed in CHANGELOG.md for their contributions
+- Mentioned in release notes
+- Credited in commit history
+- Appreciated by the community!
+
+---
+
+## 📄 License
+
+By contributing to CCW, you agree that your contributions will be licensed under the [MIT License](LICENSE).
+
+---
+
+**Thank you for contributing to Claude Code Workflow!** 🎉
+
+Your contributions help make AI-assisted development better for everyone.
+
+---
+
+**Last Updated**: 2025-11-20
+**Version**: 5.8.1

EXAMPLES.md

@@ -0,0 +1,820 @@
+# 📖 Claude Code Workflow - Real-World Examples
+
+This document provides practical, real-world examples of using CCW for common development tasks.
+
+---
+
+## 📋 Table of Contents
+
+- [Quick Start Examples](#quick-start-examples)
+- [Web Development](#web-development)
+- [API Development](#api-development)
+- [Testing & Quality Assurance](#testing--quality-assurance)
+- [Refactoring](#refactoring)
+- [UI/UX Design](#uiux-design)
+- [Bug Fixes](#bug-fixes)
+- [Documentation](#documentation)
+- [DevOps & Automation](#devops--automation)
+- [Complex Projects](#complex-projects)
+
+---
+
+## 🚀 Quick Start Examples
+
+### Example 1: Simple Express API
+
+**Objective**: Create a basic Express.js API with CRUD operations
+
+```bash
+# Option 1: Lite workflow (fastest)
+/workflow:lite-plan "Create Express API with CRUD endpoints for users (GET, POST, PUT, DELETE)"
+
+# Option 2: Full workflow (more structured)
+/workflow:plan "Create Express API with CRUD endpoints for users"
+/workflow:execute
+```
+
+**What CCW does**:
+1. Analyzes your project structure
+2. Creates Express app setup
+3. Implements CRUD routes
+4. Adds error handling middleware
+5. Creates basic tests
+
+**Result**:
+```
+src/
+├── app.js              # Express app setup
+├── routes/
+│   └── users.js        # User CRUD routes
+├── controllers/
+│   └── userController.js
+└── tests/
+    └── users.test.js
+```
+
+### Example 2: React Component
+
+**Objective**: Create a React login form component
+
+```bash
+/workflow:lite-plan "Create a React login form component with email and password fields, validation, and submit handling"
+```
+
+**What CCW does**:
+1. Creates LoginForm component
+2. Adds form validation (email format, password requirements)
+3. Implements state management
+4. Adds error display
+5. Creates component tests
+
+**Result**:
+```jsx
+// components/LoginForm.jsx
+import React, { useState } from 'react';
+
+export function LoginForm({ onSubmit }) {
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+  const [errors, setErrors] = useState({});
+
+  // ... validation and submit logic
+}
+```
+
+---
+
+## 🌐 Web Development
+
+### Example 3: Full-Stack Todo Application
+
+**Objective**: Build a complete todo application with React frontend and Express backend
+
+#### Phase 1: Planning with Brainstorming
+
+```bash
+# Multi-perspective analysis
+/workflow:brainstorm:auto-parallel "Full-stack todo application with user authentication, real-time updates, and dark mode"
+
+# Review brainstorming artifacts
+# Then create implementation plan
+/workflow:plan
+
+# Verify plan quality
+/workflow:action-plan-verify
+```
+
+**Brainstorming generates**:
+- System architecture analysis
+- UI/UX design recommendations
+- Data model design
+- Security considerations
+- API design patterns
+
+#### Phase 2: Implementation
+
+```bash
+# Execute the plan
+/workflow:execute
+
+# Monitor progress
+/workflow:status
+```
+
+**What CCW implements**:
+
+**Backend** (`server/`):
+- Express server setup
+- MongoDB/PostgreSQL integration
+- JWT authentication
+- RESTful API endpoints
+- WebSocket for real-time updates
+- Input validation middleware
+
+**Frontend** (`client/`):
+- React app with routing
+- Authentication flow
+- Todo CRUD operations
+- Real-time updates via WebSocket
+- Dark mode toggle
+- Responsive design
+
+#### Phase 3: Testing
+
+```bash
+# Generate comprehensive tests
+/workflow:test-gen WFS-todo-application
+
+# Execute test tasks
+/workflow:execute
+
+# Run iterative test-fix cycle
+/workflow:test-cycle-execute
+```
+
+**Tests created**:
+- Unit tests for components
+- Integration tests for API
+- E2E tests for user flows
+- Authentication tests
+- WebSocket connection tests
+
+#### Phase 4: Quality Review
+
+```bash
+# Security review
+/workflow:review --type security
+
+# Architecture review
+/workflow:review --type architecture
+
+# General quality review
+/workflow:review
+```
+
+**Complete session**:
+```bash
+/workflow:session:complete
+```
+
+---
+
+### Example 4: E-commerce Product Catalog
+
+**Objective**: Build product catalog with search, filters, and pagination
+
+```bash
+# Start with UI design exploration
+/workflow:ui-design:explore-auto --prompt "Modern e-commerce product catalog with grid layout, filters sidebar, and search bar" --targets "catalog,product-card" --style-variants 3
+
+# Review designs in compare.html
+# Sync selected designs
+/workflow:ui-design:design-sync --session <session-id> --selected-prototypes "catalog-v2,product-card-v1"
+
+# Create implementation plan
+/workflow:plan
+
+# Execute
+/workflow:execute
+```
+
+**Features implemented**:
+- Product grid with responsive layout
+- Search functionality with debounce
+- Category/price/rating filters
+- Pagination with infinite scroll option
+- Product card with image, title, price, rating
+- Sort options (price, popularity, newest)
+
+---
+
+## 🔌 API Development
+
+### Example 5: RESTful API with Authentication
+
+**Objective**: Create RESTful API with JWT authentication and role-based access control
+
+```bash
+# Detailed planning
+/workflow:plan "RESTful API with JWT authentication, role-based access control (admin, user), and protected endpoints for posts resource"
+
+# Verify plan
+/workflow:action-plan-verify
+
+# Execute
+/workflow:execute
+```
+
+**Implementation includes**:
+
+**Authentication**:
+```javascript
+// routes/auth.js
+POST /api/auth/register
+POST /api/auth/login
+POST /api/auth/refresh
+POST /api/auth/logout
+```
+
+**Protected Resources**:
+```javascript
+// routes/posts.js
+GET    /api/posts        # Public
+GET    /api/posts/:id    # Public
+POST   /api/posts        # Authenticated
+PUT    /api/posts/:id    # Authenticated (owner or admin)
+DELETE /api/posts/:id    # Authenticated (owner or admin)
+```
+
+**Middleware**:
+- `authenticate` - Verifies JWT token
+- `authorize(['admin'])` - Role-based access
+- `validateRequest` - Input validation
+- `errorHandler` - Centralized error handling
+
+### Example 6: GraphQL API
+
+**Objective**: Convert REST API to GraphQL
+
+```bash
+# Analyze existing REST API
+/cli:analyze "Analyze REST API structure in src/routes/"
+
+# Plan GraphQL migration
+/workflow:plan "Migrate REST API to GraphQL with queries, mutations, and subscriptions for posts and users"
+
+# Execute migration
+/workflow:execute
+```
+
+**GraphQL schema created**:
+```graphql
+type Query {
+  posts(limit: Int, offset: Int): [Post!]!
+  post(id: ID!): Post
+  user(id: ID!): User
+}
+
+type Mutation {
+  createPost(input: CreatePostInput!): Post!
+  updatePost(id: ID!, input: UpdatePostInput!): Post!
+  deletePost(id: ID!): Boolean!
+}
+
+type Subscription {
+  postCreated: Post!
+  postUpdated: Post!
+}
+```
+
+---
+
+## 🧪 Testing & Quality Assurance
+
+### Example 7: Test-Driven Development (TDD)
+
+**Objective**: Implement user authentication using TDD approach
+
+```bash
+# Start TDD workflow
+/workflow:tdd-plan "User authentication with email/password login, registration, and password reset"
+
+# Execute (Red-Green-Refactor cycles)
+/workflow:execute
+
+# Verify TDD compliance
+/workflow:tdd-verify
+```
+
+**TDD cycle tasks created**:
+
+**Cycle 1: Registration**
+1. `IMPL-1.1` - Write failing test for user registration
+2. `IMPL-1.2` - Implement registration to pass test
+3. `IMPL-1.3` - Refactor registration code
+
+**Cycle 2: Login**
+1. `IMPL-2.1` - Write failing test for login
+2. `IMPL-2.2` - Implement login to pass test
+3. `IMPL-2.3` - Refactor login code
+
+**Cycle 3: Password Reset**
+1. `IMPL-3.1` - Write failing test for password reset
+2. `IMPL-3.2` - Implement password reset
+3. `IMPL-3.3` - Refactor password reset
+
+### Example 8: Adding Tests to Existing Code
+
+**Objective**: Generate comprehensive tests for existing authentication module
+
+```bash
+# Create test generation workflow from existing code
+/workflow:test-gen WFS-authentication-implementation
+
+# Execute test tasks
+/workflow:execute
+
+# Run test-fix cycle until all tests pass
+/workflow:test-cycle-execute --max-iterations 5
+```
+
+**Tests generated**:
+- Unit tests for each function
+- Integration tests for auth flow
+- Edge case tests (invalid input, expired tokens, etc.)
+- Security tests (SQL injection, XSS, etc.)
+- Performance tests (load testing, rate limiting)
+
+**Test coverage**: Aims for 80%+ coverage
+
+---
+
+## 🔄 Refactoring
+
+### Example 9: Monolith to Microservices
+
+**Objective**: Refactor monolithic application to microservices architecture
+
+#### Phase 1: Analysis
+
+```bash
+# Deep architecture analysis
+/cli:mode:plan --tool gemini "Analyze current monolithic architecture and create microservices migration strategy"
+
+# Multi-role brainstorming
+/workflow:brainstorm:auto-parallel "Migrate monolith to microservices with API gateway, service discovery, and message queue" --count 5
+```
+
+#### Phase 2: Planning
+
+```bash
+# Create detailed migration plan
+/workflow:plan "Phase 1 microservices migration: Extract user service and auth service from monolith"
+
+# Verify plan
+/workflow:action-plan-verify
+```
+
+#### Phase 3: Implementation
+
+```bash
+# Execute migration
+/workflow:execute
+
+# Review architecture
+/workflow:review --type architecture
+```
+
+**Microservices created**:
+```
+services/
+├── user-service/
+│   ├── src/
+│   ├── Dockerfile
+│   └── package.json
+├── auth-service/
+│   ├── src/
+│   ├── Dockerfile
+│   └── package.json
+├── api-gateway/
+│   ├── src/
+│   └── config/
+└── docker-compose.yml
+```
+
+### Example 10: Code Optimization
+
+**Objective**: Optimize database queries for performance
+
+```bash
+# Analyze current performance
+/cli:mode:code-analysis "Analyze database query performance in src/repositories/"
+
+# Create optimization plan
+/workflow:plan "Optimize database queries with indexing, query optimization, and caching"
+
+# Execute optimizations
+/workflow:execute
+```
+
+**Optimizations implemented**:
+- Database indexing strategy
+- N+1 query elimination
+- Query result caching (Redis)
+- Connection pooling
+- Pagination for large datasets
+- Database query monitoring
+
+---
+
+## 🎨 UI/UX Design
+
+### Example 11: Design System Creation
+
+**Objective**: Create a complete design system for a SaaS application
+
+```bash
+# Extract design from reference
+/workflow:ui-design:imitate-auto --input "https://example-saas.com"
+
+# Or create from scratch
+/workflow:ui-design:explore-auto --prompt "Modern SaaS design system with primary components: buttons, inputs, cards, modals, navigation" --targets "button,input,card,modal,navbar" --style-variants 3
+```
+
+**Design system includes**:
+- Color palette (primary, secondary, accent, neutral)
+- Typography scale (headings, body, captions)
+- Spacing system (4px grid)
+- Component library:
+  - Buttons (primary, secondary, outline, ghost)
+  - Form inputs (text, select, checkbox, radio)
+  - Cards (basic, elevated, outlined)
+  - Modals (small, medium, large)
+  - Navigation (sidebar, topbar, breadcrumbs)
+- Animation patterns
+- Responsive breakpoints
+
+**Output**:
+```
+design-system/
+├── tokens/
+│   ├── colors.json
+│   ├── typography.json
+│   └── spacing.json
+├── components/
+│   ├── Button.jsx
+│   ├── Input.jsx
+│   └── ...
+└── documentation/
+    └── design-system.html
+```
+
+### Example 12: Responsive Landing Page
+
+**Objective**: Design and implement a marketing landing page
+
+```bash
+# Design exploration
+/workflow:ui-design:explore-auto --prompt "Modern SaaS landing page with hero section, features grid, pricing table, testimonials, and CTA" --targets "hero,features,pricing,testimonials" --style-variants 2 --layout-variants 3 --device-type responsive
+
+# Select best designs and sync
+/workflow:ui-design:design-sync --session <session-id> --selected-prototypes "hero-v2,features-v1,pricing-v3"
+
+# Implement
+/workflow:plan
+/workflow:execute
+```
+
+**Sections implemented**:
+- Hero section with animated background
+- Feature cards with icons
+- Pricing comparison table
+- Customer testimonials carousel
+- FAQ accordion
+- Contact form
+- Responsive navigation
+- Dark mode support
+
+---
+
+## 🐛 Bug Fixes
+
+### Example 13: Quick Bug Fix
+
+**Objective**: Fix login button not working on mobile
+
+```bash
+# Analyze bug
+/cli:mode:bug-diagnosis "Login button click event not firing on mobile Safari"
+
+# Claude analyzes and implements fix
+```
+
+**Fix implemented**:
+```javascript
+// Before
+button.onclick = handleLogin;
+
+// After (adds touch event support)
+button.addEventListener('click', handleLogin);
+button.addEventListener('touchend', (e) => {
+  e.preventDefault();
+  handleLogin(e);
+});
+```
+
+### Example 14: Complex Bug Investigation
+
+**Objective**: Debug memory leak in React application
+
+#### Investigation
+
+```bash
+# Start session for thorough investigation
+/workflow:session:start "Memory Leak Investigation"
+
+# Deep bug analysis
+/cli:mode:bug-diagnosis --tool gemini "Memory leak in React components - event listeners not cleaned up"
+
+# Create fix plan
+/workflow:plan "Fix memory leaks in React components: cleanup event listeners and cancel subscriptions"
+```
+
+#### Implementation
+
+```bash
+# Execute fixes
+/workflow:execute
+
+# Generate tests to prevent regression
+/workflow:test-gen WFS-memory-leak-investigation
+
+# Execute tests
+/workflow:execute
+```
+
+**Issues found and fixed**:
+1. Missing cleanup in `useEffect` hooks
+2. Event listeners not removed
+3. Uncancelled API requests on unmount
+4. Large state objects not cleared
+
+---
+
+## 📝 Documentation
+
+### Example 15: API Documentation Generation
+
+**Objective**: Generate comprehensive API documentation
+
+```bash
+# Analyze existing API
+/memory:load "Generate API documentation for all endpoints"
+
+# Create documentation
+/workflow:plan "Generate OpenAPI/Swagger documentation for REST API with examples and authentication info"
+
+# Execute
+/workflow:execute
+```
+
+**Documentation includes**:
+- OpenAPI 3.0 specification
+- Interactive Swagger UI
+- Request/response examples
+- Authentication guide
+- Rate limiting info
+- Error codes reference
+
+### Example 16: Project README Generation
+
+**Objective**: Create comprehensive README for open-source project
+
+```bash
+# Update project memory first
+/memory:update-full --tool gemini
+
+# Generate README
+/workflow:plan "Create comprehensive README.md with installation, usage, examples, API reference, and contributing guidelines"
+
+/workflow:execute
+```
+
+**README sections**:
+- Project overview
+- Features
+- Installation instructions
+- Quick start guide
+- Usage examples
+- API reference
+- Configuration
+- Contributing guidelines
+- License
+
+---
+
+## ⚙️ DevOps & Automation
+
+### Example 17: CI/CD Pipeline Setup
+
+**Objective**: Set up GitHub Actions CI/CD pipeline
+
+```bash
+/workflow:plan "Create GitHub Actions workflow for Node.js app with linting, testing, building, and deployment to AWS"
+
+/workflow:execute
+```
+
+**Pipeline created**:
+```yaml
+# .github/workflows/ci-cd.yml
+name: CI/CD
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Run tests
+        run: npm test
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Build
+        run: npm run build
+
+  deploy:
+    needs: build
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to AWS
+        run: npm run deploy
+```
+
+### Example 18: Docker Containerization
+
+**Objective**: Dockerize full-stack application
+
+```bash
+# Plan containerization
+/workflow:plan "Dockerize full-stack app with React frontend, Express backend, PostgreSQL database, and Redis cache using docker-compose"
+
+# Execute
+/workflow:execute
+
+# Review
+/workflow:review --type architecture
+```
+
+**Created files**:
+```
+├── docker-compose.yml
+├── frontend/
+│   └── Dockerfile
+├── backend/
+│   └── Dockerfile
+├── .dockerignore
+└── README.docker.md
+```
+
+---
+
+## 🏗️ Complex Projects
+
+### Example 19: Real-Time Chat Application
+
+**Objective**: Build real-time chat with WebSocket, message history, and file sharing
+
+#### Complete Workflow
+
+```bash
+# 1. Brainstorm
+/workflow:brainstorm:auto-parallel "Real-time chat application with WebSocket, message history, file upload, user presence, typing indicators" --count 5
+
+# 2. UI Design
+/workflow:ui-design:explore-auto --prompt "Modern chat interface with message list, input box, user sidebar, file preview" --targets "chat-window,message-bubble,user-list" --style-variants 2
+
+# 3. Sync designs
+/workflow:ui-design:design-sync --session <session-id>
+
+# 4. Plan implementation
+/workflow:plan
+
+# 5. Verify plan
+/workflow:action-plan-verify
+
+# 6. Execute
+/workflow:execute
+
+# 7. Generate tests
+/workflow:test-gen <session-id>
+
+# 8. Execute tests
+/workflow:execute
+
+# 9. Review
+/workflow:review --type security
+/workflow:review --type architecture
+
+# 10. Complete
+/workflow:session:complete
+```
+
+**Features implemented**:
+- WebSocket server (Socket.io)
+- Real-time messaging
+- Message persistence (MongoDB)
+- File upload (S3/local storage)
+- User authentication
+- Typing indicators
+- Read receipts
+- User presence (online/offline)
+- Message search
+- Emoji support
+- Mobile responsive
+
+### Example 20: Data Analytics Dashboard
+
+**Objective**: Build interactive dashboard with charts and real-time data
+
+```bash
+# Brainstorm data viz approach
+/workflow:brainstorm:auto-parallel "Data analytics dashboard with real-time metrics, interactive charts, filters, and export functionality"
+
+# Plan implementation
+/workflow:plan "Analytics dashboard with Chart.js/D3.js, real-time data updates via WebSocket, date range filters, and CSV export"
+
+# Execute
+/workflow:execute
+```
+
+**Dashboard features**:
+- Real-time metric cards (users, revenue, conversions)
+- Line charts (trends over time)
+- Bar charts (comparisons)
+- Pie charts (distributions)
+- Data tables with sorting/filtering
+- Date range picker
+- Export to CSV/PDF
+- Responsive grid layout
+- Dark mode
+- WebSocket updates every 5 seconds
+
+---
+
+## 💡 Tips for Effective Examples
+
+### Best Practices
+
+1. **Start with clear objectives**
+   - Define what you want to build
+   - List key features
+   - Specify technologies if needed
+
+2. **Use appropriate workflow**
+   - Simple tasks: `/workflow:lite-plan`
+   - Complex features: `/workflow:brainstorm` → `/workflow:plan`
+   - Existing code: `/workflow:test-gen` or `/cli:analyze`
+
+3. **Leverage quality gates**
+   - Run `/workflow:action-plan-verify` before execution
+   - Use `/workflow:review` after implementation
+   - Generate tests with `/workflow:test-gen`
+
+4. **Maintain memory**
+   - Update memory after major changes
+   - Use `/memory:load` for quick context
+   - Keep CLAUDE.md files up to date
+
+5. **Complete sessions**
+   - Always run `/workflow:session:complete`
+   - Generates lessons learned
+   - Archives session for reference
+
+---
+
+## 🔗 Related Resources
+
+- [Getting Started Guide](GETTING_STARTED.md) - Basics
+- [Architecture](ARCHITECTURE.md) - How it works
+- [Command Reference](COMMAND_REFERENCE.md) - All commands
+- [FAQ](FAQ.md) - Common questions
+- [Contributing](CONTRIBUTING.md) - How to contribute
+
+---
+
+## 📬 Share Your Examples
+
+Have a great example to share? Contribute to this document!
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+---
+
+**Last Updated**: 2025-11-20
+**Version**: 5.8.1

FAQ.md

@@ -0,0 +1,761 @@
+# ❓ Frequently Asked Questions (FAQ)
+
+This document answers common questions about Claude Code Workflow (CCW).
+
+---
+
+## 📋 Table of Contents
+
+- [General Questions](#general-questions)
+- [Installation & Setup](#installation--setup)
+- [Usage & Workflows](#usage--workflows)
+- [Commands & Syntax](#commands--syntax)
+- [Sessions & Tasks](#sessions--tasks)
+- [Agents & Tools](#agents--tools)
+- [Memory System](#memory-system)
+- [Troubleshooting](#troubleshooting)
+- [Advanced Topics](#advanced-topics)
+
+---
+
+## 🌟 General Questions
+
+### What is Claude Code Workflow (CCW)?
+
+CCW is an advanced AI-powered development automation framework for Claude Code. It transforms AI development from simple prompt chaining into a robust, context-first orchestration system with structured planning, deterministic execution, and intelligent multi-model orchestration.
+
+### How is CCW different from using Claude Code directly?
+
+| Claude Code (Vanilla) | Claude Code with CCW |
+|----------------------|---------------------|
+| Manual task management | Automated workflow orchestration |
+| No context preservation | Hierarchical memory system (CLAUDE.md) |
+| Single conversation context | Session-based project isolation |
+| Manual planning | Automated multi-phase planning |
+| One model/approach | Multi-model strategy (Gemini, Qwen, Codex) |
+| No quality gates | Built-in verification and review |
+
+### Do I need external CLI tools (Gemini, Qwen, Codex)?
+
+**No, they're optional.** CCW can work with Claude Code alone. External CLI tools enhance CCW's capabilities by:
+- Providing specialized analysis (Gemini)
+- Enabling autonomous development (Codex)
+- Supporting architectural planning (Qwen)
+
+But all core workflows function without them.
+
+### Is CCW suitable for beginners?
+
+**Yes!** CCW provides:
+- Simple commands like `/workflow:plan` and `/workflow:execute`
+- Interactive command guide (`CCW-help`)
+- Comprehensive documentation
+- Built-in examples and tutorials
+
+Start with the [5-minute Quick Start](GETTING_STARTED.md) to get a feel for it.
+
+### What languages/frameworks does CCW support?
+
+CCW is **language-agnostic**. It works with any programming language or framework that Claude Code supports:
+- JavaScript/TypeScript (Node.js, React, Vue, etc.)
+- Python (Django, Flask, FastAPI, etc.)
+- Java/Kotlin (Spring Boot, etc.)
+- Go, Rust, C++, C#, Ruby, PHP, etc.
+
+### Is CCW free?
+
+**Yes!** CCW is open-source under the MIT License. However, you need:
+- Claude Code subscription (for the base platform)
+- Optional: API keys for external CLI tools (Gemini, Qwen, Codex)
+
+---
+
+## 🔧 Installation & Setup
+
+### How do I install CCW?
+
+**One-line installation**:
+
+**Windows**:
+```powershell
+Invoke-Expression (Invoke-WebRequest -Uri "https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1" -UseBasicParsing).Content
+```
+
+**Linux/macOS**:
+```bash
+bash <(curl -fsSL https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.sh)
+```
+
+See [INSTALL.md](INSTALL.md) for detailed instructions.
+
+### How do I verify CCW is installed correctly?
+
+Open Claude Code and run:
+```bash
+/workflow:session:list
+```
+
+If the command is recognized, installation succeeded.
+
+### Where are CCW files installed?
+
+CCW installs to your home directory:
+```
+~/.claude/
+├── agents/       # Agent definitions
+├── commands/     # Slash commands
+├── skills/       # Agent skills
+└── workflows/    # Workflow documentation
+```
+
+### Can I customize CCW after installation?
+
+**Yes!** All files in `~/.claude/` can be customized:
+- Modify agent prompts in `agents/`
+- Add custom commands in `commands/`
+- Adjust workflow templates in `workflows/`
+
+### How do I update CCW to the latest version?
+
+Run the installation command again. It will overwrite existing files with the latest version.
+
+**Note**: Custom modifications in `~/.claude/` will be overwritten. Back up customizations first.
+
+### Do I need to install CLI tools?
+
+**Optional**. To use CLI tools:
+
+1. **Gemini CLI**: Follow [setup instructions](https://github.com/your-repo)
+2. **Qwen CLI**: Follow [setup instructions](https://github.com/your-repo)
+3. **Codex CLI**: Follow [setup instructions](https://github.com/your-repo)
+
+Then initialize with:
+```bash
+/cli:cli-init
+```
+
+---
+
+## 🚀 Usage & Workflows
+
+### What's the simplest way to use CCW?
+
+**Two-command workflow**:
+```bash
+/workflow:plan "Your feature description"
+/workflow:execute
+```
+
+That's it! CCW handles planning, task generation, and implementation.
+
+### What's the difference between `/workflow:plan` and `/workflow:lite-plan`?
+
+| `/workflow:plan` | `/workflow:lite-plan` |
+|-----------------|---------------------|
+| Full 5-phase planning | Lightweight interactive planning |
+| Creates persistent artifacts | In-memory planning |
+| Best for complex projects | Best for quick tasks |
+| Includes verification phase | Streamlined flow |
+| Suitable for team collaboration | Suitable for solo development |
+
+**Use `/workflow:plan`** for: Complex features, team projects, when you need detailed documentation
+
+**Use `/workflow:lite-plan`** for: Quick fixes, small features, rapid prototyping
+
+### When should I use brainstorming workflows?
+
+**Use `/workflow:brainstorm:auto-parallel` when you know WHAT to build, but NOT HOW to build it.**
+
+**Brainstorming scenarios**:
+- 🤔 **Unclear solution approach** - Multiple ways to solve the problem, need expert analysis
+- 🏗️ **Architectural exploration** - Need to explore different architectural patterns
+- 📋 **Requirements clarification** - High-level goal is clear, but technical details are not
+- 🔀 **Multiple trade-offs** - Need to analyze pros/cons of different approaches
+- 🆕 **Unfamiliar domain** - Building something new without clear implementation path
+
+**Skip brainstorming, use `/workflow:plan` directly when**:
+- ✅ **Clear implementation approach** - You already know how to build it
+- ✅ **Similar to existing code** - Following established patterns in your codebase
+- ✅ **Well-defined requirements** - Technical specs are clear from the start
+- ✅ **Simple features** - Straightforward implementation, no architectural decisions
+
+**Workflow comparison**:
+
+| Know what + Know how | Know what, NOT how |
+|---------------------|-------------------|
+| `/workflow:plan "Add JWT auth"` | `/workflow:brainstorm:auto-parallel "Design auth system"` → `/workflow:plan` |
+| Plan generates tasks directly | Brainstorm explores solutions → Plan generates tasks |
+
+**Example**:
+```bash
+# When you DON'T know how to build it
+/workflow:brainstorm:auto-parallel "Build real-time collaborative document editing system"
+/workflow:plan
+/workflow:execute
+```
+
+### How do I check the status of my workflow?
+
+```bash
+/workflow:status
+```
+
+Shows:
+- Current session
+- Task completion status
+- Currently executing task
+- Next steps
+
+### Can I run multiple workflows simultaneously?
+
+**Yes!** CCW supports parallel sessions:
+
+```bash
+# Session 1: Authentication
+/workflow:session:start "User Authentication"
+/workflow:plan "JWT-based authentication"
+
+# Session 2: Payment
+/workflow:session:start "Payment Integration"
+/workflow:plan "Stripe payment integration"
+
+# Execute each session independently
+/workflow:execute --session WFS-user-authentication
+/workflow:execute --session WFS-payment-integration
+```
+
+### How do I resume a paused workflow?
+
+```bash
+/workflow:session:resume
+```
+
+Automatically detects and resumes the most recent paused session.
+
+---
+
+## 💬 Commands & Syntax
+
+### Where can I find all available commands?
+
+See [COMMAND_REFERENCE.md](COMMAND_REFERENCE.md) for a complete list.
+
+Or use the interactive guide:
+```bash
+CCW-help
+```
+
+### What's the difference between `/cli:*` and `/workflow:*` commands?
+
+**`/cli:*` commands**:
+- Direct access to external AI tools
+- No workflow session required
+- Quick one-off tasks
+- Examples: `/cli:analyze`, `/cli:chat`
+
+**`/workflow:*` commands**:
+- Multi-phase orchestration
+- Session-based
+- Complex development workflows
+- Examples: `/workflow:plan`, `/workflow:execute`
+
+### How do I use command flags?
+
+Most commands support flags for customization:
+
+```bash
+# Basic usage
+/workflow:plan "Feature description"
+
+# With CLI execution flag
+/workflow:plan --cli-execute "Feature description"
+
+# With tool selection
+/cli:analyze --tool gemini "Code analysis"
+
+# With multiple flags
+/workflow:ui-design:explore-auto --prompt "Login page" --style-variants 3 --layout-variants 2
+```
+
+### Can I use natural language instead of commands?
+
+**Yes!** Claude understands semantic invocation:
+
+Instead of:
+```bash
+/cli:analyze --tool gemini "Authentication module"
+```
+
+You can say:
+```
+"Use Gemini to analyze the authentication module architecture"
+```
+
+Claude will automatically execute the appropriate command.
+
+### What does the `-e` or `--enhance` flag do?
+
+The `-e` flag triggers the **prompt-enhancer** skill in natural conversation:
+
+```
+User: "Analyze authentication module -e"
+```
+
+Claude will expand and enhance your request for better results.
+
+**Note**: `--enhance` in CLI commands (e.g., `/cli:analyze --enhance`) is a different feature built into CLI tools.
+
+---
+
+## 📦 Sessions & Tasks
+
+### What is a workflow session?
+
+A workflow session is an **isolated workspace** for a specific feature or project. It contains:
+- Task definitions (JSON files)
+- Brainstorming artifacts
+- Generated plans
+- Chat logs
+- Session state
+
+**Location**: `.workflow/active/WFS-<session-name>/`
+
+### How are sessions created?
+
+Sessions are created automatically when you run:
+```bash
+/workflow:session:start "Feature name"
+/workflow:plan "Feature description"
+/workflow:brainstorm:auto-parallel "Topic"
+```
+
+### How do I list all sessions?
+
+```bash
+/workflow:session:list
+```
+
+Shows all sessions with their status (active, paused, completed).
+
+### What happens when I complete a session?
+
+```bash
+/workflow:session:complete
+```
+
+CCW will:
+1. Archive session to `.workflow/archives/`
+2. Remove active flag
+3. Generate lessons learned
+4. Update session manifest
+
+### What are tasks in CCW?
+
+Tasks are **atomic units of work** stored as JSON files in `.task/` directory:
+
+```
+.workflow/active/WFS-feature/.task/
+├── IMPL-1.json       # Main task
+├── IMPL-1.1.json     # Subtask
+└── IMPL-2.json       # Another task
+```
+
+Each task contains:
+- Title and description
+- Requirements and acceptance criteria
+- Context and focus paths
+- Implementation approach
+- Status (pending, in_progress, completed)
+
+### How deep can task hierarchies go?
+
+**Maximum 2 levels**:
+- `IMPL-1` - Main task
+- `IMPL-1.1`, `IMPL-1.2` - Subtasks
+- No further nesting (no `IMPL-1.1.1`)
+
+### Can I manually edit task JSON files?
+
+**Yes**, but:
+- ⚠️ JSON files are the source of truth
+- ⚠️ Markdown documents are read-only views
+- ✅ Edit JSON directly for fine-grained control
+- ✅ Validate JSON syntax after editing
+- ✅ Use `/workflow:status` to regenerate views
+
+---
+
+## 🤖 Agents & Tools
+
+### What agents are available in CCW?
+
+| Agent | Purpose |
+|-------|---------|
+| `@code-developer` | Code implementation |
+| `@test-fix-agent` | Test generation and fixing |
+| `@ui-design-agent` | UI design and prototyping |
+| `@action-planning-agent` | Task planning and decomposition |
+| `@cli-execution-agent` | Autonomous CLI task handling |
+| `@cli-explore-agent` | Codebase exploration |
+| `@context-search-agent` | Context gathering |
+| `@doc-generator` | Documentation generation |
+| `@memory-bridge` | Memory system updates |
+
+See [ARCHITECTURE.md](ARCHITECTURE.md#multi-agent-system) for details.
+
+### How do agents get selected for tasks?
+
+**Automatic selection** based on task type defined in JSON:
+
+```json
+{
+  "meta": {
+    "agent": "code-developer"
+  }
+}
+```
+
+CCW automatically invokes the appropriate agent during `/workflow:execute`.
+
+### What's the difference between Gemini, Qwen, and Codex?
+
+| Tool | Strengths | Best For |
+|------|-----------|----------|
+| **Gemini** | Deep analysis, pattern recognition | Code exploration, architecture analysis |
+| **Qwen** | System design, planning | Architectural planning, system design |
+| **Codex** | Autonomous implementation | Feature development, bug fixes |
+
+CCW auto-selects the best tool for each task, but you can override with `--tool` flag.
+
+### Can I create custom agents?
+
+**Yes!** Create a new file in `.claude/agents/`:
+
+```markdown
+# My Custom Agent
+
+## Role
+Agent description
+
+## Tools Available
+- Tool 1
+- Tool 2
+
+## Prompt
+Agent instructions...
+```
+
+Then reference it in task JSON:
+```json
+{
+  "meta": {
+    "agent": "my-custom-agent"
+  }
+}
+```
+
+---
+
+## 💾 Memory System
+
+### What is the CLAUDE.md memory system?
+
+A **hierarchical documentation system** that maintains project knowledge across 4 layers:
+
+```
+CLAUDE.md (Project root)
+└── src/CLAUDE.md (Source layer)
+    └── auth/CLAUDE.md (Module layer)
+        └── jwt/CLAUDE.md (Component layer)
+```
+
+Each layer provides context at the appropriate abstraction level.
+
+### When should I update memory?
+
+**Update memory when**:
+- After completing a feature
+- After refactoring modules
+- After changing architecture
+- Before starting complex tasks
+- Weekly maintenance
+
+### What's the difference between memory update commands?
+
+| Command | Scope | When to Use |
+|---------|-------|-------------|
+| `/memory:update-full` | Entire project | Major changes, first-time setup, monthly maintenance |
+| `/memory:update-related` | Changed modules only | Daily development, after feature completion |
+| `/memory:load` | Task-specific, no files | Quick context for immediate task |
+
+### How long does memory update take?
+
+- **`/memory:update-full`**: 5-20 minutes (depends on project size)
+- **`/memory:update-related`**: 1-5 minutes (only changed modules)
+- **`/memory:load`**: <1 minute (no file updates)
+
+### Do I need to update memory manually?
+
+**Recommended but not required**. Benefits of regular updates:
+- ✅ Higher quality AI outputs
+- ✅ Accurate pattern recognition
+- ✅ Better context understanding
+- ✅ Reduced hallucinations
+
+Without updates:
+- ⚠️ AI may reference outdated code
+- ⚠️ Incorrect architectural assumptions
+- ⚠️ Lower output quality
+
+### Can I exclude files from memory?
+
+**Yes!** Use ignore files:
+- `.geminiignore` - For Gemini CLI
+- `.qwenignore` - For Qwen CLI
+- `.gitignore` - Automatically respected
+
+Example `.geminiignore`:
+```
+node_modules/
+dist/
+*.log
+*.test.js
+```
+
+---
+
+## 🔧 Troubleshooting
+
+### "No active session found" error
+
+**Cause**: No workflow session is currently active.
+
+**Solution**:
+```bash
+# Option 1: Start new session
+/workflow:session:start "Feature name"
+
+# Option 2: Resume existing session
+/workflow:session:resume
+```
+
+### Command execution fails or hangs
+
+**Troubleshooting steps**:
+
+1. **Check status**:
+   ```bash
+   /workflow:status
+   ```
+
+2. **Review logs**:
+   ```bash
+   # Session logs location
+   .workflow/active/WFS-<session>/.chat/
+   ```
+
+3. **Simplify task**:
+   Break complex requests into smaller tasks
+
+4. **Check CLI tools**:
+   Ensure external tools (if used) are properly configured
+
+### Task execution produces errors
+
+**Common causes**:
+
+1. **Outdated memory**: Run `/memory:update-related`
+2. **Insufficient context**: Add more details to task requirements
+3. **Tool misconfiguration**: Check CLI tool setup with `/cli:cli-init`
+
+### Memory update fails
+
+**Solutions**:
+
+1. **Check file permissions**: Ensure write access to project
+2. **Try different tool**:
+   ```bash
+   /memory:update-full --tool qwen
+   ```
+3. **Update incrementally**:
+   ```bash
+   /memory:update-related
+   ```
+
+### Workflow gets stuck in a phase
+
+**Steps**:
+
+1. **Check current phase**:
+   ```bash
+   /workflow:status
+   ```
+
+2. **Review session JSON**:
+   ```bash
+   cat .workflow/active/WFS-<session>/workflow-session.json
+   ```
+
+3. **Manually advance** (if needed):
+   Edit session JSON to update phase
+
+4. **Restart session**:
+   ```bash
+   /workflow:session:complete
+   /workflow:session:start "New attempt"
+   ```
+
+### CLI tools not working
+
+**Checklist**:
+
+1. ✅ Tools installed correctly?
+2. ✅ API keys configured?
+3. ✅ `.gemini/` or `.qwen/` directories exist?
+4. ✅ Configuration files valid?
+
+**Re-initialize**:
+```bash
+/cli:cli-init --tool gemini
+```
+
+### Performance is slow
+
+**Optimization tips**:
+
+1. **Use incremental updates**:
+   ```bash
+   /memory:update-related  # Instead of update-full
+   ```
+
+2. **Exclude unnecessary files**:
+   Add to `.geminiignore` or `.qwenignore`
+
+3. **Break down large tasks**:
+   Smaller tasks = faster execution
+
+4. **Use lite workflows**:
+   ```bash
+   /workflow:lite-plan  # Instead of full workflow:plan
+   ```
+
+---
+
+## 🚀 Advanced Topics
+
+### How does CCW handle dependencies between tasks?
+
+Tasks can reference dependencies in their JSON:
+
+```json
+{
+  "id": "IMPL-2",
+  "dependencies": ["IMPL-1"],
+  "context": {
+    "inherited_from": "IMPL-1"
+  }
+}
+```
+
+CCW ensures dependencies are completed before dependent tasks execute.
+
+### Can I integrate CCW with CI/CD pipelines?
+
+**Yes!** CCW can be used in automated workflows:
+
+1. **Generate tests**:
+   ```bash
+   /workflow:test-gen WFS-feature
+   /workflow:execute
+   ```
+
+2. **Run verification**:
+   ```bash
+   /workflow:action-plan-verify
+   ```
+
+3. **Automated reviews**:
+   ```bash
+   /workflow:review --type security
+   ```
+
+### How do I create custom workflows?
+
+Combine existing commands:
+
+```bash
+# Custom TDD workflow
+/workflow:tdd-plan "Feature"
+/workflow:execute
+/workflow:tdd-verify
+/workflow:review --type quality
+```
+
+Or create custom command in `.claude/commands/`.
+
+### What's the JSON-first architecture?
+
+**Principle**: JSON files are the **single source of truth** for all task state.
+
+- ✅ JSON files contain actual state
+- ❌ Markdown documents are **read-only** generated views
+- ✅ Edit JSON to change state
+- ❌ Never edit markdown documents
+
+**Benefits**:
+- No synchronization complexity
+- Programmatic access
+- Clear data model
+- Deterministic state
+
+### How does context flow between agents?
+
+Agents share context through:
+
+1. **Session JSON**: Shared session state
+2. **Task JSON**: Task-specific context
+3. **CLAUDE.md**: Project knowledge base
+4. **Flow Control**: Pre-analysis and implementation approach
+
+### Can I use CCW for non-code projects?
+
+**Yes!** CCW can manage any structured project:
+- Documentation writing
+- Content creation
+- Data analysis
+- Research projects
+- Process automation
+
+### How do I migrate from one CCW version to another?
+
+1. **Backup customizations**: Save `.claude/` modifications
+2. **Run installation**: Install new version
+3. **Restore customizations**: Reapply your changes
+4. **Check changelog**: Review breaking changes in [CHANGELOG.md](CHANGELOG.md)
+5. **Test workflows**: Verify existing workflows work
+
+### Where can I get more help?
+
+- 📖 **Documentation**: [README.md](README.md), [GETTING_STARTED.md](GETTING_STARTED.md)
+- 💬 **Discussions**: [GitHub Discussions](https://github.com/catlog22/Claude-Code-Workflow/discussions)
+- 🐛 **Issues**: [GitHub Issues](https://github.com/catlog22/Claude-Code-Workflow/issues)
+- 🤖 **Command Guide**: `CCW-help` within Claude Code
+- 📚 **Examples**: [EXAMPLES.md](EXAMPLES.md)
+
+---
+
+## 📚 Additional Resources
+
+- [Getting Started Guide](GETTING_STARTED.md) - 5-minute tutorial
+- [Architecture Overview](ARCHITECTURE.md) - System design
+- [Command Reference](COMMAND_REFERENCE.md) - All commands
+- [Contributing Guide](CONTRIBUTING.md) - How to contribute
+- [Examples](EXAMPLES.md) - Real-world use cases
+- [Changelog](CHANGELOG.md) - Version history
+
+---
+
+**Last Updated**: 2025-11-20
+**Version**: 5.8.1
+
+**Didn't find your question?** Ask in [GitHub Discussions](https://github.com/catlog22/Claude-Code-Workflow/discussions)!

GETTING_STARTED.md

@@ -114,7 +114,7 @@ For UI-focused projects, start with design exploration before implementation: **
 
 ### Scenario 3: Complex Feature with Multi-Agent Brainstorming
 
-For complex features requiring thorough analysis, use the complete workflow: **brainstorm → plan → execute**
+**Use brainstorming when you know WHAT to build, but don't know HOW to build it.** The complete workflow: **brainstorm → plan → execute**
 
 ```bash
 # Step 1: Multi-agent brainstorming (auto-creates session)
@@ -136,9 +136,16 @@ For complex features requiring thorough analysis, use the complete workflow: **b
 - **Comprehensive specification**: Generates integrated requirements and design document
 
 **When to Use Brainstorming**:
-- Complex features requiring multiple perspectives
-- Architectural decisions with significant impact
-- When you need thorough requirements before implementation
+- **You know WHAT to build, but NOT HOW** - Need to explore solution approaches
+- **Multiple solution paths exist** - Need expert analysis to choose the best approach
+- **Unclear technical requirements** - Need to clarify architecture, data models, APIs
+- **Significant architectural decisions** - Need multi-perspective analysis before committing
+
+**When to Skip Brainstorming** (use `/workflow:plan` directly):
+- You already know the implementation approach
+- Clear technical requirements from the start
+- Simple, straightforward features
+- Similar to existing implementations in your codebase
 
 ### Scenario 4: Quality Assurance - Action Plan Verification
 
@@ -182,7 +189,7 @@ Quick bug analysis and fix workflow:
 
 ```bash
 # Analyze the bug
-/cli:mode:bug-index "Incorrect success message with wrong password"
+/cli:mode:bug-diagnosis "Incorrect success message with wrong password"
 
 # Claude will analyze and then directly implement the fix based on the analysis
 ```

GETTING_STARTED_CN.md

@@ -136,9 +136,16 @@
 - **综合规格说明**：生成整合的需求和设计文档
 
 **何时使用头脑风暴**：
-- 需要多视角分析的复杂功能
-- 具有重大影响的架构决策
-- 实现前需要详尽需求分析
+- **知道要做什么，但不知道怎么做** - 需要探索解决方案
+- **存在多个解决路径** - 需要专家分析选择最佳方案
+- **技术需求不明确** - 需要澄清架构、数据模型、API
+- **重大架构决策** - 需要多角度分析再做决定
+
+**何时跳过头脑风暴**（直接使用 `/workflow:plan`）：
+- 已经知道实现方法
+- 一开始就有清晰的技术需求
+- 简单直接的功能
+- 与代码库中现有实现类似
 
 ### 场景 4：质量保证 - 行动计划验证
 
@@ -182,7 +189,7 @@
 
 ```bash
 # 分析 Bug
-/cli:mode:bug-index "密码错误时仍显示成功消息"
+/cli:mode:bug-diagnosis "密码错误时仍显示成功消息"
 
 # Claude 会分析后直接根据分析结果实现修复
 ```
@@ -233,7 +240,7 @@ CCW 支持通过统一的 CLI 接口直接调用外部 AI 工具（Gemini、Qwen
 /cli:mode:code-analysis --tool qwen "分析 src/utils/ 目录下的工具函数"
 
 # Bug 分析模式
-/cli:mode:bug-index --tool gemini "分析内存泄漏问题的可能原因"
+/cli:mode:bug-diagnosis --tool gemini "分析内存泄漏问题的可能原因"
 ```
 
 ### 工具语义调用

PROJECT_INTRODUCTION.md

@@ -200,13 +200,13 @@ CCW 基于任务类型自动选择最适合的工具：
 
 ```bash
 # 探索和理解阶段
-/gemini:analyze "认证系统架构模式"
+/cli:analyze --tool gemini "认证系统架构模式"
 
 # 设计和规划阶段
-/qwen:mode:plan "微服务认证架构设计"
+/cli:mode:plan --tool qwen "微服务认证架构设计"
 
 # 实现和开发阶段
-/codex:mode:auto "实现 JWT 认证系统"
+/cli:execute --tool codex "实现 JWT 认证系统"
 ```
 
 ### 🔄 完整开发生命周期
@@ -304,8 +304,8 @@ CCW 基于任务类型自动选择最适合的工具：
 ```bash
 # 快速错误解决工作流
 /workflow:session:start "支付验证修复"
-/gemini:mode:bug-index "并发请求时支付验证失败"
-/codex:mode:bug-index "修复支付验证竞态条件"
+/cli:mode:bug-diagnosis --tool gemini "并发请求时支付验证失败"
+/cli:execute --tool codex "修复支付验证竞态条件"
 /workflow:review
 ```
 
@@ -313,9 +313,9 @@ CCW 基于任务类型自动选择最适合的工具：
 ```bash
 # 深度架构分析和重构
 /workflow:session:start "微服务重构"
-/gemini:analyze "当前单体架构的技术债务"
-/workflow:plan-deep "单体到微服务的迁移策略"
-/qwen:mode:auto "重构用户服务为微服务架构"
+/cli:analyze --tool gemini "当前单体架构的技术债务"
+/workflow:plan "单体到微服务的迁移策略"
+/workflow:execute
 /workflow:test-gen WFS-microservice-refactoring
 ```
 

README.md

@@ -126,8 +126,8 @@ Lightweight interactive workflow with in-memory planning and immediate execution
 # Force code exploration
 /workflow:lite-plan -e "Refactor logging module for better performance"
 
-# Preset CLI tool
-/workflow:lite-plan --tool codex "Add unit tests for auth service"
+# Basic usage
+/workflow:lite-plan "Add unit tests for auth service"
 ```
 
 **Interactive Flow**:
@@ -159,11 +159,39 @@ Traditional multi-phase workflow for complex projects:
 
 ---
 
+## 📚 Documentation
+
+CCW provides comprehensive documentation to help you get started and master advanced features:
+
+### 📖 **Getting Started**
+- [**Getting Started Guide**](GETTING_STARTED.md) - 5-minute quick start tutorial
+- [**Installation Guide**](INSTALL.md) - Detailed installation instructions ([中文](INSTALL_CN.md))
+- [**Workflow Decision Guide**](WORKFLOW_DECISION_GUIDE.md) - 🌳 Interactive flowchart for choosing the right commands
+- [**Examples**](EXAMPLES.md) - Real-world use cases and practical examples
+- [**FAQ**](FAQ.md) - Frequently asked questions and troubleshooting
+
+### 🏗️ **Architecture & Design**
+- [**Architecture Overview**](ARCHITECTURE.md) - System design and core components
+- [**Project Introduction**](PROJECT_INTRODUCTION.md) - Detailed project overview (中文)
+- [**Workflow Diagrams**](WORKFLOW_DIAGRAMS.md) - Visual workflow representations
+
+### 📋 **Command Reference**
+- [**Command Reference**](COMMAND_REFERENCE.md) - Complete list of all commands
+- [**Command Specification**](COMMAND_SPEC.md) - Detailed technical specifications
+- [**Command Flow Standard**](COMMAND_FLOW_STANDARD.md) - Command design patterns
+
+### 🤝 **Contributing**
+- [**Contributing Guide**](CONTRIBUTING.md) - How to contribute to CCW
+- [**Changelog**](CHANGELOG.md) - Version history and release notes
+
+---
+
 ## 🤝 Contributing & Support
 
 - **Repository**: [GitHub - Claude-Code-Workflow](https://github.com/catlog22/Claude-Code-Workflow)
 - **Issues**: Report bugs or request features on [GitHub Issues](https://github.com/catlog22/Claude-Code-Workflow/issues).
 - **Discussions**: Join the [Community Forum](https://github.com/catlog22/Claude-Code-Workflow/discussions).
+- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.
 
 ## 📄 License
 

README_CN.md

@@ -126,8 +126,8 @@ CCW 包含内置的**命令指南技能**，帮助您有效地发现和使用命
 # 强制代码探索
 /workflow:lite-plan -e "重构日志模块以提高性能"
 
-# 预设 CLI 工具
-/workflow:lite-plan --tool codex "为认证服务添加单元测试"
+# 基本用法
+/workflow:lite-plan "为认证服务添加单元测试"
 ```
 
 **交互流程**:
@@ -159,11 +159,39 @@ CCW 包含内置的**命令指南技能**，帮助您有效地发现和使用命
 
 ---
 
+## 📚 文档
+
+CCW 提供全面的文档，帮助您快速上手并掌握高级功能：
+
+### 📖 **快速入门**
+- [**快速上手指南**](GETTING_STARTED_CN.md) - 5 分钟快速入门教程
+- [**安装指南**](INSTALL_CN.md) - 详细安装说明 ([English](INSTALL.md))
+- [**工作流决策指南**](WORKFLOW_DECISION_GUIDE.md) - 🌳 交互式流程图帮助选择正确的命令
+- [**示例**](EXAMPLES.md) - 真实世界用例和实践示例 (English)
+- [**常见问题**](FAQ.md) - 常见问题和故障排除 (English)
+
+### 🏗️ **架构与设计**
+- [**架构概览**](ARCHITECTURE.md) - 系统设计和核心组件 (English)
+- [**项目介绍**](PROJECT_INTRODUCTION.md) - 详细项目概览
+- [**工作流图示**](WORKFLOW_DIAGRAMS.md) - 可视化工作流表示 (English)
+
+### 📋 **命令参考**
+- [**命令参考**](COMMAND_REFERENCE.md) - 所有命令的完整列表 (English)
+- [**命令规范**](COMMAND_SPEC.md) - 详细技术规范 (English)
+- [**命令流程标准**](COMMAND_FLOW_STANDARD.md) - 命令设计模式 (English)
+
+### 🤝 **贡献**
+- [**贡献指南**](CONTRIBUTING.md) - 如何为 CCW 做贡献 (English)
+- [**更新日志**](CHANGELOG.md) - 版本历史和发布说明
+
+---
+
 ## 🤝 贡献与支持
 
 - **仓库**: [GitHub - Claude-Code-Workflow](https://github.com/catlog22/Claude-Code-Workflow)
 - **问题**: 在 [GitHub Issues](https://github.com/catlog22/Claude-Code-Workflow/issues) 上报告错误或请求功能。
 - **讨论**: 加入 [社区论坛](https://github.com/catlog22/Claude-Code-Workflow/discussions)。
+- **贡献**: 查看 [CONTRIBUTING.md](CONTRIBUTING.md) 了解贡献指南。
 
 ## 📄 许可证
 

WORKFLOW_DECISION_GUIDE.md

@@ -0,0 +1,419 @@
+# 🌳 CCW Workflow Decision Guide
+
+本指南帮助您选择正确的命令和工作流程，适用于软件开发的完整生命周期。
+
+---
+
+## 📊 全生命周期命令选择流程图
+
+```mermaid
+flowchart TD
+    Start([开始新功能/项目]) --> Q1{知道要做什么吗?}
+
+    Q1 -->|不知道| Ideation[💡 构思阶段<br>需求探索]
+    Q1 -->|知道| Q2{知道怎么做吗?}
+
+    Ideation --> BrainIdea[/ /workflow:brainstorm:auto-parallel<br>探索产品方向和功能定位 /]
+    BrainIdea --> Q2
+
+    Q2 -->|不知道| Design[🏗️ 设计探索阶段<br>架构方案探索]
+    Q2 -->|知道| Q3{需要UI设计吗?}
+
+    Design --> BrainDesign[/ /workflow:brainstorm:auto-parallel<br>探索技术方案和架构 /]
+    BrainDesign --> Q3
+
+    Q3 -->|需要| UIDesign[🎨 UI设计阶段]
+    Q3 -->|不需要| Q4{任务复杂度?}
+
+    UIDesign --> Q3a{有参考设计吗?}
+    Q3a -->|有| UIImitate[/ /workflow:ui-design:imitate-auto<br>--input 参考URL /]
+    Q3a -->|无| UIExplore[/ /workflow:ui-design:explore-auto<br>--prompt 设计描述 /]
+
+    UIImitate --> UISync[/ /workflow:ui-design:design-sync<br>同步设计系统 /]
+    UIExplore --> UISync
+    UISync --> Q4
+
+    Q4 -->|简单快速| LitePlan[⚡ 轻量规划<br>/workflow:lite-plan]
+    Q4 -->|复杂完整| FullPlan[📋 完整规划<br>/workflow:plan]
+
+    LitePlan --> Q5{需要代码探索?}
+    Q5 -->|需要| LitePlanE[/ /workflow:lite-plan -e<br>任务描述 /]
+    Q5 -->|不需要| LitePlanNormal[/ /workflow:lite-plan<br>任务描述 /]
+
+    LitePlanE --> LiteConfirm[三维确认:<br>1️⃣ 任务批准<br>2️⃣ 执行方式<br>3️⃣ 代码审查]
+    LitePlanNormal --> LiteConfirm
+
+    LiteConfirm --> Q6{选择执行方式}
+    Q6 -->|Agent| LiteAgent[/ /workflow:lite-execute<br>使用@code-developer /]
+    Q6 -->|CLI工具| LiteCLI[CLI执行<br>Gemini/Qwen/Codex]
+    Q6 -->|仅计划| UserImpl[用户手动实现]
+
+    FullPlan --> PlanVerify{验证计划质量?}
+    PlanVerify -->|是| Verify[/ /workflow:action-plan-verify /]
+    PlanVerify -->|否| Execute
+    Verify --> Q7{验证通过?}
+    Q7 -->|否| FixPlan[修复计划问题]
+    Q7 -->|是| Execute
+    FixPlan --> Execute
+
+    Execute[🚀 执行阶段<br>/workflow:execute]
+    LiteAgent --> TestDecision
+    LiteCLI --> TestDecision
+    UserImpl --> TestDecision
+    Execute --> TestDecision
+
+    TestDecision{需要测试吗?}
+    TestDecision -->|TDD模式| TDD[/ /workflow:tdd-plan<br>测试驱动开发 /]
+    TestDecision -->|后置测试| TestGen[/ /workflow:test-gen<br>生成测试 /]
+    TestDecision -->|已有测试| TestCycle[/ /workflow:test-cycle-execute<br>测试修复循环 /]
+    TestDecision -->|不需要| Review
+
+    TDD --> TDDExecute[/ /workflow:execute<br>Red-Green-Refactor /]
+    TDDExecute --> TDDVerify[/ /workflow:tdd-verify<br>验证TDD合规 /]
+    TDDVerify --> Review
+
+    TestGen --> TestExecute[/ /workflow:execute<br>执行测试任务 /]
+    TestExecute --> TestResult{测试通过?}
+    TestResult -->|否| TestCycle
+    TestResult -->|是| Review
+
+    TestCycle --> TestPass{通过率≥95%?}
+    TestPass -->|否,继续修复| TestCycle
+    TestPass -->|是| Review
+
+    Review[📝 审查阶段]
+    Review --> Q8{需要专项审查?}
+    Q8 -->|安全| SecurityReview[/ /workflow:review<br>--type security /]
+    Q8 -->|架构| ArchReview[/ /workflow:review<br>--type architecture /]
+    Q8 -->|质量| QualityReview[/ /workflow:review<br>--type quality /]
+    Q8 -->|综合| GeneralReview[/ /workflow:review<br>综合审查 /]
+    Q8 -->|不需要| Complete
+
+    SecurityReview --> Complete
+    ArchReview --> Complete
+    QualityReview --> Complete
+    GeneralReview --> Complete
+
+    Complete[✅ 完成阶段<br>/workflow:session:complete]
+    Complete --> End([项目完成])
+
+    style Start fill:#e1f5ff
+    style End fill:#c8e6c9
+    style BrainIdea fill:#fff9c4
+    style BrainDesign fill:#fff9c4
+    style UIImitate fill:#f8bbd0
+    style UIExplore fill:#f8bbd0
+    style LitePlan fill:#b3e5fc
+    style FullPlan fill:#b3e5fc
+    style Execute fill:#c5e1a5
+    style TDD fill:#ffccbc
+    style TestGen fill:#ffccbc
+    style TestCycle fill:#ffccbc
+    style Review fill:#d1c4e9
+    style Complete fill:#c8e6c9
+```
+
+---
+
+## 🎯 决策关键点说明
+
+### 1️⃣ **构思阶段 - "知道要做什么吗？"**
+
+| 情况 | 命令 | 说明 |
+|------|------|------|
+| ❌ 不确定产品方向 | `/workflow:brainstorm:auto-parallel "探索XXX领域的产品机会"` | 产品经理、用户体验专家等多角色分析 |
+| ✅ 明确功能需求 | 跳过，进入设计阶段 | 已知道要构建什么功能 |
+
+**示例**：
+```bash
+# 不确定场景：我想做一个协作工具，但不确定具体做什么
+/workflow:brainstorm:auto-parallel "探索团队协作工具的产品定位和核心功能" --count 5
+
+# 确定场景：我要做一个实时文档协作编辑器（需求明确）
+# 跳过构思，进入设计阶段
+```
+
+---
+
+### 2️⃣ **设计阶段 - "知道怎么做吗？"**
+
+| 情况 | 命令 | 说明 |
+|------|------|------|
+| ❌ 不知道技术方案 | `/workflow:brainstorm:auto-parallel "设计XXX系统架构"` | 系统架构师、安全专家等分析技术方案 |
+| ✅ 清晰实现路径 | 跳过，直接进入规划 | 已知道用什么技术栈、架构模式 |
+
+**示例**：
+```bash
+# 不知道怎么做：实时协作编辑的冲突解决机制？用什么算法？
+/workflow:brainstorm:auto-parallel "设计实时协作文档编辑系统的冲突解决机制" --count 4
+
+# 知道怎么做：使用Operational Transformation + WebSocket + Redis
+# 跳过设计探索，直接规划实现
+/workflow:plan "使用OT算法实现实时协作编辑，WebSocket通信，Redis存储"
+```
+
+---
+
+### 3️⃣ **UI设计阶段 - "需要UI设计吗？"**
+
+| 情况 | 命令 | 说明 |
+|------|------|------|
+| 🎨 有参考设计 | `/workflow:ui-design:imitate-auto --input "URL"` | 基于现有设计复制 |
+| 🎨 从零设计 | `/workflow:ui-design:explore-auto --prompt "描述"` | 生成多个设计变体 |
+| ⏭️ 后端/无UI | 跳过 | 纯后端API、CLI工具等 |
+
+**示例**：
+```bash
+# 有参考：模仿Google Docs的协作界面
+/workflow:ui-design:imitate-auto --input "https://docs.google.com"
+
+# 无参考：从零设计
+/workflow:ui-design:explore-auto --prompt "现代简洁的文档协作编辑界面" --style-variants 3
+
+# 同步设计到项目
+/workflow:ui-design:design-sync --session WFS-xxx --selected-prototypes "v1,v2"
+```
+
+---
+
+### 4️⃣ **规划阶段 - 选择工作流类型**
+
+| 工作流 | 适用场景 | 特点 |
+|--------|---------|------|
+| `/workflow:lite-plan` | 快速任务、小功能 | 内存规划、三维确认、快速执行 |
+| `/workflow:plan` | 复杂项目、团队协作 | 持久化计划、质量门禁、完整追溯 |
+
+**Lite-Plan 三维确认**：
+1. **任务批准**：确认/修改/取消
+2. **执行方式**：Agent / 提供计划 / CLI工具（Gemini/Qwen/Codex）
+3. **代码审查**：否 / Claude / Gemini / Qwen / Codex
+
+**示例**：
+```bash
+# 简单任务
+/workflow:lite-plan "添加用户头像上传功能"
+
+# 需要代码探索
+/workflow:lite-plan -e "重构认证模块为OAuth2标准"
+
+# 复杂项目
+/workflow:plan "实现完整的实时协作编辑系统"
+/workflow:action-plan-verify  # 验证计划质量
+/workflow:execute
+```
+
+---
+
+### 5️⃣ **测试阶段 - 选择测试策略**
+
+| 策略 | 命令 | 适用场景 |
+|------|------|---------|
+| **TDD模式** | `/workflow:tdd-plan` | 从头开始，测试驱动开发 |
+| **后置测试** | `/workflow:test-gen` | 代码已完成，补充测试 |
+| **测试修复** | `/workflow:test-cycle-execute` | 已有测试，需要修复失败用例 |
+
+**示例**：
+```bash
+# TDD：先写测试，再实现
+/workflow:tdd-plan "用户认证模块"
+/workflow:execute  # Red-Green-Refactor循环
+/workflow:tdd-verify  # 验证TDD合规
+
+# 后置测试：代码完成后补测试
+/workflow:test-gen WFS-user-auth-implementation
+/workflow:execute
+
+# 测试修复：已有测试，但失败率高
+/workflow:test-cycle-execute --max-iterations 5
+# 自动迭代修复直到通过率≥95%
+```
+
+---
+
+### 6️⃣ **审查阶段 - 选择审查类型**
+
+| 类型 | 命令 | 关注点 |
+|------|------|--------|
+| **安全审查** | `/workflow:review --type security` | SQL注入、XSS、认证漏洞 |
+| **架构审查** | `/workflow:review --type architecture` | 设计模式、耦合度、可扩展性 |
+| **质量审查** | `/workflow:review --type quality` | 代码风格、复杂度、可维护性 |
+| **综合审查** | `/workflow:review` | 全方位检查 |
+
+**示例**：
+```bash
+# 安全关键系统
+/workflow:review --type security
+
+# 架构重构后
+/workflow:review --type architecture
+
+# 日常开发
+/workflow:review --type quality
+```
+
+---
+
+## 🔄 典型场景完整流程
+
+### 场景A：新功能开发（知道怎么做）
+
+```bash
+# 1. 规划
+/workflow:plan "添加JWT认证和权限管理"
+
+# 2. 验证计划
+/workflow:action-plan-verify
+
+# 3. 执行
+/workflow:execute
+
+# 4. 测试
+/workflow:test-gen WFS-jwt-auth
+/workflow:execute
+
+# 5. 审查
+/workflow:review --type security
+
+# 6. 完成
+/workflow:session:complete
+```
+
+---
+
+### 场景B：新功能开发（不知道怎么做）
+
+```bash
+# 1. 设计探索
+/workflow:brainstorm:auto-parallel "设计分布式缓存系统架构" --count 5
+
+# 2. UI设计（如需要）
+/workflow:ui-design:explore-auto --prompt "缓存管理后台界面"
+/workflow:ui-design:design-sync --session WFS-xxx
+
+# 3. 规划
+/workflow:plan
+
+# 4. 验证
+/workflow:action-plan-verify
+
+# 5. 执行
+/workflow:execute
+
+# 6. TDD测试
+/workflow:tdd-plan "缓存系统核心模块"
+/workflow:execute
+
+# 7. 审查
+/workflow:review --type architecture
+/workflow:review --type security
+
+# 8. 完成
+/workflow:session:complete
+```
+
+---
+
+### 场景C：快速功能开发（Lite工作流）
+
+```bash
+# 1. 轻量规划（可能需要代码探索）
+/workflow:lite-plan -e "优化数据库查询性能"
+
+# 2. 三维确认
+# - 确认任务
+# - 选择Agent执行
+# - 选择Gemini代码审查
+
+# 3. 自动执行（/workflow:lite-execute内部调用）
+
+# 4. 完成
+```
+
+---
+
+### 场景D：Bug修复
+
+```bash
+# 1. 诊断
+/cli:mode:bug-diagnosis --tool gemini "用户登录失败，提示token过期"
+
+# 2. 快速修复
+/workflow:lite-plan "修复JWT token过期验证逻辑"
+
+# 3. 测试修复
+/workflow:test-cycle-execute
+
+# 4. 完成
+```
+
+---
+
+## 🎓 命令选择快速参考
+
+### 按知识程度选择
+
+| 你的情况 | 推荐命令 |
+|---------|---------|
+| 💭 不知道做什么 | `/workflow:brainstorm:auto-parallel "探索产品方向"` |
+| ❓ 知道做什么，不知道怎么做 | `/workflow:brainstorm:auto-parallel "设计技术方案"` |
+| ✅ 知道做什么，知道怎么做 | `/workflow:plan "具体实现描述"` |
+| ⚡ 简单明确的小任务 | `/workflow:lite-plan "任务描述"` |
+| 🐛 修复bug | `/cli:mode:bug-diagnosis` + `/workflow:lite-plan` |
+
+### 按项目阶段选择
+
+| 阶段 | 命令 |
+|------|------|
+| 📋 **需求分析** | `/workflow:brainstorm:auto-parallel` |
+| 🏗️ **架构设计** | `/workflow:brainstorm:auto-parallel` |
+| 🎨 **UI设计** | `/workflow:ui-design:explore-auto` / `imitate-auto` |
+| 📝 **实现规划** | `/workflow:plan` / `/workflow:lite-plan` |
+| 🚀 **编码实现** | `/workflow:execute` / `/workflow:lite-execute` |
+| 🧪 **测试** | `/workflow:tdd-plan` / `/workflow:test-gen` |
+| 🔧 **测试修复** | `/workflow:test-cycle-execute` |
+| 📖 **代码审查** | `/workflow:review` |
+| ✅ **项目完成** | `/workflow:session:complete` |
+
+### 按工作模式选择
+
+| 模式 | 工作流 | 适用场景 |
+|------|--------|---------|
+| **🚀 敏捷快速** | Lite工作流 | 个人开发、快速迭代、原型验证 |
+| **📋 规范完整** | Full工作流 | 团队协作、企业项目、长期维护 |
+| **🧪 质量优先** | TDD工作流 | 核心模块、关键功能、高可靠性需求 |
+| **🎨 设计导向** | UI-Design工作流 | 前端项目、用户界面、设计系统 |
+
+---
+
+## 💡 专家建议
+
+### ✅ 最佳实践
+
+1. **不确定时用头脑风暴**：宁可多花10分钟探索方案，也不要盲目实现后推翻重来
+2. **复杂项目用Full工作流**：持久化计划便于团队协作和长期维护
+3. **小任务用Lite工作流**：快速完成，减少overhead
+4. **关键模块用TDD**：测试驱动开发保证质量
+5. **定期更新内存**：`/memory:update-related` 保持上下文准确
+
+### ❌ 常见陷阱
+
+1. **盲目跳过头脑风暴**：对不熟悉的技术领域也不探索，导致返工
+2. **过度使用头脑风暴**：简单功能也头脑风暴，浪费时间
+3. **忽略计划验证**：不运行 `/workflow:action-plan-verify`，导致执行时发现计划问题
+4. **忽略测试**：不生成测试，代码质量无法保证
+5. **不完成会话**：不运行 `/workflow:session:complete`，会话状态混乱
+
+---
+
+## 🔗 相关文档
+
+- [Getting Started Guide](GETTING_STARTED.md) - 快速入门教程
+- [Command Reference](COMMAND_REFERENCE.md) - 完整命令列表
+- [Architecture Overview](ARCHITECTURE.md) - 系统架构说明
+- [Examples](EXAMPLES.md) - 真实场景示例
+- [FAQ](FAQ.md) - 常见问题解答
+
+---
+
+**最后更新**: 2025-11-20
+**版本**: 5.8.1

WORKFLOW_DECISION_GUIDE_EN.md

@@ -0,0 +1,419 @@
+# 🌳 CCW Workflow Decision Guide
+
+This guide helps you choose the right commands and workflows for the complete software development lifecycle.
+
+---
+
+## 📊 Full Lifecycle Command Selection Flowchart
+
+```mermaid
+flowchart TD
+    Start([Start New Feature/Project]) --> Q1{Know what to build?}
+
+    Q1 -->|No| Ideation[💡 Ideation Phase<br>Requirements Exploration]
+    Q1 -->|Yes| Q2{Know how to build?}
+
+    Ideation --> BrainIdea[/ /workflow:brainstorm:auto-parallel<br>Explore product direction and positioning /]
+    BrainIdea --> Q2
+
+    Q2 -->|No| Design[🏗️ Design Exploration<br>Architecture Solution Discovery]
+    Q2 -->|Yes| Q3{Need UI design?}
+
+    Design --> BrainDesign[/ /workflow:brainstorm:auto-parallel<br>Explore technical solutions and architecture /]
+    BrainDesign --> Q3
+
+    Q3 -->|Yes| UIDesign[🎨 UI Design Phase]
+    Q3 -->|No| Q4{Task complexity?}
+
+    UIDesign --> Q3a{Have reference design?}
+    Q3a -->|Yes| UIImitate[/ /workflow:ui-design:imitate-auto<br>--input reference URL /]
+    Q3a -->|No| UIExplore[/ /workflow:ui-design:explore-auto<br>--prompt design description /]
+
+    UIImitate --> UISync[/ /workflow:ui-design:design-sync<br>Sync design system /]
+    UIExplore --> UISync
+    UISync --> Q4
+
+    Q4 -->|Simple & Quick| LitePlan[⚡ Lightweight Planning<br>/workflow:lite-plan]
+    Q4 -->|Complex & Complete| FullPlan[📋 Full Planning<br>/workflow:plan]
+
+    LitePlan --> Q5{Need code exploration?}
+    Q5 -->|Yes| LitePlanE[/ /workflow:lite-plan -e<br>task description /]
+    Q5 -->|No| LitePlanNormal[/ /workflow:lite-plan<br>task description /]
+
+    LitePlanE --> LiteConfirm[Three-Dimensional Confirmation:<br>1️⃣ Task Approval<br>2️⃣ Execution Method<br>3️⃣ Code Review]
+    LitePlanNormal --> LiteConfirm
+
+    LiteConfirm --> Q6{Choose execution method}
+    Q6 -->|Agent| LiteAgent[/ /workflow:lite-execute<br>Using @code-developer /]
+    Q6 -->|CLI Tools| LiteCLI[CLI Execution<br>Gemini/Qwen/Codex]
+    Q6 -->|Plan Only| UserImpl[Manual User Implementation]
+
+    FullPlan --> PlanVerify{Verify plan quality?}
+    PlanVerify -->|Yes| Verify[/ /workflow:action-plan-verify /]
+    PlanVerify -->|No| Execute
+    Verify --> Q7{Verification passed?}
+    Q7 -->|No| FixPlan[Fix plan issues]
+    Q7 -->|Yes| Execute
+    FixPlan --> Execute
+
+    Execute[🚀 Execution Phase<br>/workflow:execute]
+    LiteAgent --> TestDecision
+    LiteCLI --> TestDecision
+    UserImpl --> TestDecision
+    Execute --> TestDecision
+
+    TestDecision{Need testing?}
+    TestDecision -->|TDD Mode| TDD[/ /workflow:tdd-plan<br>Test-Driven Development /]
+    TestDecision -->|Post-Implementation Testing| TestGen[/ /workflow:test-gen<br>Generate tests /]
+    TestDecision -->|Existing Tests| TestCycle[/ /workflow:test-cycle-execute<br>Test-fix cycle /]
+    TestDecision -->|No| Review
+
+    TDD --> TDDExecute[/ /workflow:execute<br>Red-Green-Refactor /]
+    TDDExecute --> TDDVerify[/ /workflow:tdd-verify<br>Verify TDD compliance /]
+    TDDVerify --> Review
+
+    TestGen --> TestExecute[/ /workflow:execute<br>Execute test tasks /]
+    TestExecute --> TestResult{Tests passed?}
+    TestResult -->|No| TestCycle
+    TestResult -->|Yes| Review
+
+    TestCycle --> TestPass{Pass rate ≥95%?}
+    TestPass -->|No, continue fixing| TestCycle
+    TestPass -->|Yes| Review
+
+    Review[📝 Review Phase]
+    Review --> Q8{Need specialized review?}
+    Q8 -->|Security| SecurityReview[/ /workflow:review<br>--type security /]
+    Q8 -->|Architecture| ArchReview[/ /workflow:review<br>--type architecture /]
+    Q8 -->|Quality| QualityReview[/ /workflow:review<br>--type quality /]
+    Q8 -->|Comprehensive| GeneralReview[/ /workflow:review<br>Comprehensive review /]
+    Q8 -->|No| Complete
+
+    SecurityReview --> Complete
+    ArchReview --> Complete
+    QualityReview --> Complete
+    GeneralReview --> Complete
+
+    Complete[✅ Completion Phase<br>/workflow:session:complete]
+    Complete --> End([Project Complete])
+
+    style Start fill:#e1f5ff
+    style End fill:#c8e6c9
+    style BrainIdea fill:#fff9c4
+    style BrainDesign fill:#fff9c4
+    style UIImitate fill:#f8bbd0
+    style UIExplore fill:#f8bbd0
+    style LitePlan fill:#b3e5fc
+    style FullPlan fill:#b3e5fc
+    style Execute fill:#c5e1a5
+    style TDD fill:#ffccbc
+    style TestGen fill:#ffccbc
+    style TestCycle fill:#ffccbc
+    style Review fill:#d1c4e9
+    style Complete fill:#c8e6c9
+```
+
+---
+
+## 🎯 Decision Point Explanations
+
+### 1️⃣ **Ideation Phase - "Know what to build?"**
+
+| Situation | Command | Description |
+|-----------|---------|-------------|
+| ❌ Uncertain about product direction | `/workflow:brainstorm:auto-parallel "Explore XXX domain product opportunities"` | Multi-role analysis with Product Manager, UX Expert, etc. |
+| ✅ Clear feature requirements | Skip to design phase | Already know what functionality to build |
+
+**Examples**:
+```bash
+# Uncertain scenario: Want to build a collaboration tool, but unsure what exactly
+/workflow:brainstorm:auto-parallel "Explore team collaboration tool positioning and core features" --count 5
+
+# Certain scenario: Building a real-time document collaboration editor (requirements clear)
+# Skip ideation, move to design phase
+```
+
+---
+
+### 2️⃣ **Design Phase - "Know how to build?"**
+
+| Situation | Command | Description |
+|-----------|---------|-------------|
+| ❌ Don't know technical approach | `/workflow:brainstorm:auto-parallel "Design XXX system architecture"` | System Architect, Security Expert analyze technical solutions |
+| ✅ Clear implementation path | Skip to planning | Already know tech stack, architecture patterns |
+
+**Examples**:
+```bash
+# Don't know how: Real-time collaboration conflict resolution? Which algorithm?
+/workflow:brainstorm:auto-parallel "Design conflict resolution mechanism for real-time collaborative document editing" --count 4
+
+# Know how: Using Operational Transformation + WebSocket + Redis
+# Skip design exploration, go directly to planning
+/workflow:plan "Implement real-time collaborative editing using OT algorithm, WebSocket communication, Redis storage"
+```
+
+---
+
+### 3️⃣ **UI Design Phase - "Need UI design?"**
+
+| Situation | Command | Description |
+|-----------|---------|-------------|
+| 🎨 Have reference design | `/workflow:ui-design:imitate-auto --input "URL"` | Copy from existing design |
+| 🎨 Design from scratch | `/workflow:ui-design:explore-auto --prompt "description"` | Generate multiple design variants |
+| ⏭️ Backend/No UI | Skip | Pure backend API, CLI tools, etc. |
+
+**Examples**:
+```bash
+# Have reference: Imitate Google Docs collaboration interface
+/workflow:ui-design:imitate-auto --input "https://docs.google.com"
+
+# No reference: Design from scratch
+/workflow:ui-design:explore-auto --prompt "Modern minimalist document collaboration editing interface" --style-variants 3
+
+# Sync design to project
+/workflow:ui-design:design-sync --session WFS-xxx --selected-prototypes "v1,v2"
+```
+
+---
+
+### 4️⃣ **Planning Phase - Choose Workflow Type**
+
+| Workflow | Use Case | Characteristics |
+|----------|----------|-----------------|
+| `/workflow:lite-plan` | Quick tasks, small features | In-memory planning, three-dimensional confirmation, fast execution |
+| `/workflow:plan` | Complex projects, team collaboration | Persistent plans, quality gates, complete traceability |
+
+**Lite-Plan Three-Dimensional Confirmation**:
+1. **Task Approval**: Confirm / Modify / Cancel
+2. **Execution Method**: Agent / Provide Plan / CLI Tools (Gemini/Qwen/Codex)
+3. **Code Review**: No / Claude / Gemini / Qwen / Codex
+
+**Examples**:
+```bash
+# Simple task
+/workflow:lite-plan "Add user avatar upload feature"
+
+# Need code exploration
+/workflow:lite-plan -e "Refactor authentication module to OAuth2 standard"
+
+# Complex project
+/workflow:plan "Implement complete real-time collaborative editing system"
+/workflow:action-plan-verify  # Verify plan quality
+/workflow:execute
+```
+
+---
+
+### 5️⃣ **Testing Phase - Choose Testing Strategy**
+
+| Strategy | Command | Use Case |
+|----------|---------|----------|
+| **TDD Mode** | `/workflow:tdd-plan` | Starting from scratch, test-driven development |
+| **Post-Implementation Testing** | `/workflow:test-gen` | Code complete, add tests |
+| **Test Fixing** | `/workflow:test-cycle-execute` | Existing tests, need to fix failures |
+
+**Examples**:
+```bash
+# TDD: Write tests first, then implement
+/workflow:tdd-plan "User authentication module"
+/workflow:execute  # Red-Green-Refactor cycle
+/workflow:tdd-verify  # Verify TDD compliance
+
+# Post-implementation testing: Add tests after code complete
+/workflow:test-gen WFS-user-auth-implementation
+/workflow:execute
+
+# Test fixing: Existing tests with high failure rate
+/workflow:test-cycle-execute --max-iterations 5
+# Auto-iterate fixes until pass rate ≥95%
+```
+
+---
+
+### 6️⃣ **Review Phase - Choose Review Type**
+
+| Type | Command | Focus |
+|------|---------|-------|
+| **Security Review** | `/workflow:review --type security` | SQL injection, XSS, authentication vulnerabilities |
+| **Architecture Review** | `/workflow:review --type architecture` | Design patterns, coupling, scalability |
+| **Quality Review** | `/workflow:review --type quality` | Code style, complexity, maintainability |
+| **Comprehensive Review** | `/workflow:review` | All-around inspection |
+
+**Examples**:
+```bash
+# Security-critical system
+/workflow:review --type security
+
+# After architecture refactoring
+/workflow:review --type architecture
+
+# Daily development
+/workflow:review --type quality
+```
+
+---
+
+## 🔄 Complete Flow for Typical Scenarios
+
+### Scenario A: New Feature Development (Know How to Build)
+
+```bash
+# 1. Planning
+/workflow:plan "Add JWT authentication and permission management"
+
+# 2. Verify plan
+/workflow:action-plan-verify
+
+# 3. Execute
+/workflow:execute
+
+# 4. Testing
+/workflow:test-gen WFS-jwt-auth
+/workflow:execute
+
+# 5. Review
+/workflow:review --type security
+
+# 6. Complete
+/workflow:session:complete
+```
+
+---
+
+### Scenario B: New Feature Development (Don't Know How to Build)
+
+```bash
+# 1. Design exploration
+/workflow:brainstorm:auto-parallel "Design distributed cache system architecture" --count 5
+
+# 2. UI design (if needed)
+/workflow:ui-design:explore-auto --prompt "Cache management dashboard interface"
+/workflow:ui-design:design-sync --session WFS-xxx
+
+# 3. Planning
+/workflow:plan
+
+# 4. Verification
+/workflow:action-plan-verify
+
+# 5. Execution
+/workflow:execute
+
+# 6. TDD testing
+/workflow:tdd-plan "Cache system core modules"
+/workflow:execute
+
+# 7. Review
+/workflow:review --type architecture
+/workflow:review --type security
+
+# 8. Complete
+/workflow:session:complete
+```
+
+---
+
+### Scenario C: Quick Feature Development (Lite Workflow)
+
+```bash
+# 1. Lightweight planning (may need code exploration)
+/workflow:lite-plan -e "Optimize database query performance"
+
+# 2. Three-dimensional confirmation
+# - Confirm task
+# - Choose Agent execution
+# - Choose Gemini code review
+
+# 3. Auto-execution (called internally by /workflow:lite-execute)
+
+# 4. Complete
+```
+
+---
+
+### Scenario D: Bug Fixing
+
+```bash
+# 1. Diagnosis
+/cli:mode:bug-diagnosis --tool gemini "User login fails with token expired error"
+
+# 2. Quick fix
+/workflow:lite-plan "Fix JWT token expiration validation logic"
+
+# 3. Test fix
+/workflow:test-cycle-execute
+
+# 4. Complete
+```
+
+---
+
+## 🎓 Quick Command Reference
+
+### Choose by Knowledge Level
+
+| Your Situation | Recommended Command |
+|----------------|---------------------|
+| 💭 Don't know what to build | `/workflow:brainstorm:auto-parallel "Explore product direction"` |
+| ❓ Know what, don't know how | `/workflow:brainstorm:auto-parallel "Design technical solution"` |
+| ✅ Know what and how | `/workflow:plan "Specific implementation description"` |
+| ⚡ Simple, clear small task | `/workflow:lite-plan "Task description"` |
+| 🐛 Bug fixing | `/cli:mode:bug-diagnosis` + `/workflow:lite-plan` |
+
+### Choose by Project Phase
+
+| Phase | Command |
+|-------|---------|
+| 📋 **Requirements Analysis** | `/workflow:brainstorm:auto-parallel` |
+| 🏗️ **Architecture Design** | `/workflow:brainstorm:auto-parallel` |
+| 🎨 **UI Design** | `/workflow:ui-design:explore-auto` / `imitate-auto` |
+| 📝 **Implementation Planning** | `/workflow:plan` / `/workflow:lite-plan` |
+| 🚀 **Coding Implementation** | `/workflow:execute` / `/workflow:lite-execute` |
+| 🧪 **Testing** | `/workflow:tdd-plan` / `/workflow:test-gen` |
+| 🔧 **Test Fixing** | `/workflow:test-cycle-execute` |
+| 📖 **Code Review** | `/workflow:review` |
+| ✅ **Project Completion** | `/workflow:session:complete` |
+
+### Choose by Work Mode
+
+| Mode | Workflow | Use Case |
+|------|----------|----------|
+| **🚀 Agile & Fast** | Lite Workflow | Personal dev, rapid iteration, prototype validation |
+| **📋 Standard & Complete** | Full Workflow | Team collaboration, enterprise projects, long-term maintenance |
+| **🧪 Quality-First** | TDD Workflow | Core modules, critical features, high reliability requirements |
+| **🎨 Design-Driven** | UI-Design Workflow | Frontend projects, user interfaces, design systems |
+
+---
+
+## 💡 Expert Advice
+
+### ✅ Best Practices
+
+1. **Use brainstorming when uncertain**: Better to spend 10 minutes exploring solutions than blindly implementing and rewriting
+2. **Use Full workflow for complex projects**: Persistent plans facilitate team collaboration and long-term maintenance
+3. **Use Lite workflow for small tasks**: Complete quickly, reduce overhead
+4. **Use TDD for critical modules**: Test-driven development ensures quality
+5. **Regularly update memory**: `/memory:update-related` keeps context accurate
+
+### ❌ Common Pitfalls
+
+1. **Blindly skipping brainstorming**: Not exploring unfamiliar technical domains leads to rework
+2. **Overusing brainstorming**: Brainstorming even simple features wastes time
+3. **Ignoring plan verification**: Not running `/workflow:action-plan-verify` causes execution issues
+4. **Ignoring testing**: Not generating tests, code quality cannot be guaranteed
+5. **Not completing sessions**: Not running `/workflow:session:complete` causes session state confusion
+
+---
+
+## 🔗 Related Documentation
+
+- [Getting Started Guide](GETTING_STARTED.md) - Quick start tutorial
+- [Command Reference](COMMAND_REFERENCE.md) - Complete command list
+- [Architecture Overview](ARCHITECTURE.md) - System architecture explanation
+- [Examples](EXAMPLES.md) - Real-world scenario examples
+- [FAQ](FAQ.md) - Frequently asked questions
+
+---
+
+**Last Updated**: 2025-11-20
+**Version**: 5.8.1