docs: add visual before/after comparison for output structure

- Clear side-by-side comparison of current vs proposed structure - Safety indicators (safe vs dangerous operations) - Command output examples showing the improvements - User experience improvements with concrete examples - Performance impact analysis - Timeline and decision framework - Complements OUTPUT_DIRECTORY_REORGANIZATION.md with visual summary
docs: comprehensive output directory reorganization recommendations
2026-02-15 02:42:45 +08:00 · 2025-11-20 09:20:43 +00:00 · 2025-11-20 09:19:20 +00:00 · 2025-11-20 09:06:21 +00:00 · 2025-11-20 13:58:18 +08:00 · 2025-11-20 05:45:41 +00:00
19 changed files with 5769 additions and 37 deletions
--- a/.claude/commands/task/replan.md
+++ b/.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
--- a/.claude/commands/workflow/replan.md
+++ b/.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 个任务
+```
--- a/.claude/skills/command-guide/reference/commands/task/replan.md
+++ b/.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:
--- a/.claude/skills/command-guide/reference/commands/workflow/replan.md
+++ b/.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 个任务
+```
--- a/ARCHITECTURE.md
+++ b/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
--- a/COMMAND_AMBIGUITY_ANALYSIS.md
+++ b/COMMAND_AMBIGUITY_ANALYSIS.md
@@ -0,0 +1,374 @@
+# Command Ambiguity Analysis
+
+## Executive Summary
+
+Analysis of 74 commands reveals **5 major ambiguity clusters** that could cause user confusion. The primary issues involve overlapping functionality in planning, execution, and analysis commands, with inconsistent parameter usage and unclear decision criteria.
+
+---
+
+## Critical Ambiguities (HIGH Priority)
+
+### 1. Planning Command Overload ⚠️ CRITICAL
+
+**Problem**: 5 different "plan" commands with overlapping but distinct purposes
+
+| Command | Purpose | Outputs | Mode |
+|---------|---------|---------|------|
+| `/workflow:plan` | 5-phase planning workflow | IMPL_PLAN.md + task JSONs | Autonomous |
+| `/workflow:lite-plan` | Lightweight interactive planning | In-memory plan | Interactive |
+| `/workflow:replan` | Modify existing plans | Updates existing artifacts | Interactive |
+| `/cli:mode:plan` | Architecture planning | .chat/plan-*.md | Read-only |
+| `/cli:discuss-plan` | Multi-round collaborative planning | .chat/discuss-plan-*.md | Multi-model discussion |
+
+**Ambiguities**:
+- ❌ **Intent confusion**: Users don't know which to use for "planning"
+- ❌ **Output confusion**: Some create tasks, some don't
+- ❌ **Workflow confusion**: Different levels of automation
+- ❌ **Scope confusion**: Project-level vs architecture-level vs modification planning
+
+**User Questions**:
+- "I want to plan my project - which command do I use?"
+- "What's the difference between `/workflow:plan` and `/workflow:lite-plan`?"
+- "When should I use `/cli:mode:plan` vs `/workflow:plan`?"
+
+**Recommendations**:
+1. ✅ Create decision tree documentation
+2. ✅ Rename commands to clarify scope:
+   - `/workflow:plan` → `/workflow:project-plan` (full workflow)
+   - `/workflow:lite-plan` → `/workflow:quick-plan` (fast planning)
+   - `/cli:mode:plan` → `/cli:architecture-plan` (read-only)
+3. ✅ Add command hints in descriptions about when to use each
+
+---
+
+### 2. Execution Command Confusion ⚠️ CRITICAL
+
+**Problem**: 5 different "execute" commands with different behaviors
+
+| Command | Input | Modifies Code | Auto-Approval | Context |
+|---------|-------|---------------|---------------|---------|
+| `/workflow:execute` | Session | Via agents | No | Full workflow |
+| `/workflow:lite-execute` | Plan/prompt/file | Via agent/codex | User choice | Lightweight |
+| `/cli:execute` | Description/task-id | YES | YOLO | Direct implementation |
+| `/cli:codex-execute` | Description | YES | YOLO | Multi-stage Codex |
+| `/task:execute` | task-id | Via agent | No | Single task |
+
+**Ambiguities**:
+- ❌ **Safety confusion**: Some have YOLO auto-approval, others don't
+- ❌ **Input confusion**: Different input formats
+- ❌ **Scope confusion**: Workflow vs task vs direct execution
+- ❌ **Tool confusion**: Agent vs CLI tool execution
+
+**Critical Risk**:
+- Users may accidentally use `/cli:execute` (YOLO) when they meant `/workflow:execute` (controlled)
+- This could result in unwanted code modifications
+
+**User Questions**:
+- "I have a workflow session - do I use `/workflow:execute` or `/task:execute`?"
+- "What's the difference between `/cli:execute` and `/workflow:lite-execute`?"
+- "Which execute command is safest for production code?"
+
+**Recommendations**:
+1. 🚨 Add safety warnings to YOLO commands
+2. ✅ Clear documentation on execution modes:
+   - **Workflow execution**: `/workflow:execute` (controlled, session-based)
+   - **Quick execution**: `/workflow:lite-execute` (flexible input)
+   - **Direct implementation**: `/cli:execute` (⚠️ YOLO auto-approval)
+3. ✅ Consider renaming:
+   - `/cli:execute` → `/cli:implement-auto` (emphasizes auto-approval)
+   - `/cli:codex-execute` → `/cli:codex-multi-stage`
+
+---
+
+### 3. Analysis Command Overlap ⚠️ MEDIUM
+
+**Problem**: Multiple analysis commands with unclear distinctions
+
+| Command | Tool | Purpose | Output |
+|---------|------|---------|--------|
+| `/cli:analyze` | Gemini/Qwen/Codex | General codebase analysis | .chat/analyze-*.md |
+| `/cli:mode:code-analysis` | Gemini/Qwen/Codex | Execution path tracing | .chat/code-analysis-*.md |
+| `/cli:mode:bug-diagnosis` | Gemini/Qwen/Codex | Bug root cause analysis | .chat/bug-diagnosis-*.md |
+| `/cli:chat` | Gemini/Qwen/Codex | Q&A interaction | .chat/chat-*.md |
+
+**Ambiguities**:
+- ❌ **Use case overlap**: When to use general analysis vs specialized modes
+- ❌ **Template confusion**: Different templates but similar outputs
+- ❌ **Mode naming**: "mode" prefix adds extra layer of confusion
+
+**User Questions**:
+- "Should I use `/cli:analyze` or `/cli:mode:code-analysis` to understand this code?"
+- "What's special about the 'mode' commands?"
+
+**Recommendations**:
+1. ✅ Consolidate or clarify:
+   - Keep `/cli:analyze` for general use
+   - Document `/cli:mode:*` as specialized templates
+2. ✅ Add use case examples in descriptions
+3. ✅ Consider flattening:
+   - `/cli:mode:code-analysis` → `/cli:trace-execution`
+   - `/cli:mode:bug-diagnosis` → `/cli:diagnose-bug`
+
+---
+
+## Medium Priority Ambiguities
+
+### 4. Task vs Workflow Command Overlap
+
+**Problem**: Parallel command hierarchies
+
+**Workflow Commands**:
+- `/workflow:plan` - Create workflow with tasks
+- `/workflow:execute` - Execute all tasks
+- `/workflow:replan` - Modify workflow
+
+**Task Commands**:
+- `/task:create` - Create individual task
+- `/task:execute` - Execute single task
+- `/task:replan` - Modify task
+
+**Ambiguities**:
+- ❌ **Scope confusion**: When to use workflow vs task commands
+- ❌ **Execution confusion**: `/task:execute` vs `/workflow:execute`
+
+**Recommendations**:
+1. ✅ Document relationship clearly:
+   - Workflow commands: Multi-task orchestration
+   - Task commands: Single-task operations
+2. ✅ Add cross-references in documentation
+
+---
+
+### 5. Tool Selection Confusion (`--tool` flag)
+
+**Problem**: Many commands accept `--tool codex|gemini|qwen` without clear criteria
+
+**Commands with --tool**:
+- `/cli:execute --tool`
+- `/cli:analyze --tool`
+- `/cli:mode:plan --tool`
+- `/memory:update-full --tool`
+- And more...
+
+**Ambiguities**:
+- ❌ **Selection criteria**: No clear guidance on when to use which tool
+- ❌ **Default inconsistency**: Different defaults across commands
+- ❌ **Capability confusion**: What each tool is best for
+
+**Recommendations**:
+1. ✅ Create tool selection guide:
+   - **Gemini**: Best for analysis, planning (default for most)
+   - **Qwen**: Fallback when Gemini unavailable
+   - **Codex**: Best for complex implementation, multi-stage execution
+2. ✅ Add tool selection hints to command descriptions
+3. ✅ Document tool capabilities clearly
+
+---
+
+### 6. Enhancement Flag Inconsistency
+
+**Problem**: Different enhancement flags with different meanings
+
+| Command | Flag | Meaning |
+|---------|------|---------|
+| `/cli:execute` | `--enhance` | Enhance prompt via `/enhance-prompt` |
+| `/cli:analyze` | `--enhance` | Enhance prompt via `/enhance-prompt` |
+| `/workflow:lite-plan` | `-e` or `--explore` | Force code exploration |
+| `/memory:skill-memory` | `--regenerate` | Regenerate existing files |
+
+**Ambiguities**:
+- ❌ **Flag meaning**: `-e` means different things
+- ❌ **Inconsistent naming**: `--enhance` vs `--explore` vs `--regenerate`
+
+**Recommendations**:
+1. ✅ Standardize flags:
+   - Use `--enhance` consistently for prompt enhancement
+   - Use `--explore` specifically for codebase exploration
+   - Use `--regenerate` for file regeneration
+2. ✅ Avoid short flags (`-e`) that could be ambiguous
+
+---
+
+## Low Priority Observations
+
+### 7. Session Management Commands (Well-Designed ✅)
+
+**Commands**:
+- `/workflow:session:start`
+- `/workflow:session:resume`
+- `/workflow:session:complete`
+- `/workflow:session:list`
+
+**Analysis**: These are **well-designed** with clear, distinct purposes. No ambiguity found.
+
+---
+
+### 8. Memory Commands (Acceptable)
+
+Memory commands follow consistent patterns but could benefit from better organization:
+- `/memory:load`
+- `/memory:docs`
+- `/memory:skill-memory`
+- `/memory:code-map-memory`
+- `/memory:update-full`
+- `/memory:update-related`
+
+**Minor Issue**: Many memory commands, but purposes are relatively clear.
+
+---
+
+## Parameter Ambiguity Analysis
+
+### Common Parameter Patterns
+
+| Parameter | Commands Using It | Ambiguity Level |
+|-----------|-------------------|-----------------|
+| `--tool` | 10+ commands | HIGH - Inconsistent defaults |
+| `--enhance` | 5+ commands | MEDIUM - Similar but not identical |
+| `--session` | 8+ commands | LOW - Consistent meaning |
+| `--cli-execute` | 3+ commands | LOW - Clear meaning |
+| `-e` / `--explore` | 2+ commands | HIGH - Different meanings |
+
+---
+
+## Output Ambiguity Analysis
+
+### Output Location Confusion
+
+Multiple commands output to similar locations:
+
+**`.chat/` outputs** (read-only analysis):
+- `/cli:analyze` → `.chat/analyze-*.md`
+- `/cli:mode:plan` → `.chat/plan-*.md`
+- `/cli:discuss-plan` → `.chat/discuss-plan-*.md`
+- `/cli:execute` → `.chat/execute-*.md` (❌ Misleading - actually modifies code!)
+
+**Ambiguity**:
+- Users might think all `.chat/` outputs are read-only
+- `/cli:execute` outputs to `.chat/` but modifies code (YOLO)
+
+**Recommendation**:
+- ✅ Separate execution logs from analysis logs
+- ✅ Use different directory for code-modifying operations
+
+---
+
+## Decision Tree Recommendations
+
+### When to Use Planning Commands
+
+```
+START: I need to plan something
+│
+├─ Is this a new full project workflow?
+│  └─ YES → /workflow:plan (5-phase, creates tasks)
+│
+├─ Do I need quick planning without full workflow?
+│  └─ YES → /workflow:lite-plan (fast, interactive)
+│
+├─ Do I need architecture-level planning only?
+│  └─ YES → /cli:mode:plan (read-only, no tasks)
+│
+├─ Do I need multi-perspective discussion?
+│  └─ YES → /cli:discuss-plan (Gemini + Codex + Claude)
+│
+└─ Am I modifying an existing plan?
+   └─ YES → /workflow:replan (modify artifacts)
+```
+
+### When to Use Execution Commands
+
+```
+START: I need to execute/implement something
+│
+├─ Do I have an active workflow session with tasks?
+│  └─ YES → /workflow:execute (execute all tasks)
+│
+├─ Do I have a single task ID to execute?
+│  └─ YES → /task:execute IMPL-N (single task)
+│
+├─ Do I have a plan or description to execute quickly?
+│  └─ YES → /workflow:lite-execute (flexible input)
+│
+├─ Do I want direct, autonomous implementation (⚠️ YOLO)?
+│  ├─ Single-stage → /cli:execute (auto-approval)
+│  └─ Multi-stage → /cli:codex-execute (complex tasks)
+│
+└─ ⚠️ WARNING: CLI execute commands modify code without confirmation
+```
+
+### When to Use Analysis Commands
+
+```
+START: I need to analyze code
+│
+├─ General codebase understanding?
+│  └─ /cli:analyze (broad analysis)
+│
+├─ Specific execution path tracing?
+│  └─ /cli:mode:code-analysis (detailed flow)
+│
+├─ Bug diagnosis?
+│  └─ /cli:mode:bug-diagnosis (root cause)
+│
+└─ Quick Q&A?
+   └─ /cli:chat (interactive)
+```
+
+---
+
+## Summary of Findings
+
+### Ambiguity Count by Severity
+
+| Severity | Count | Commands Affected |
+|----------|-------|-------------------|
+| 🚨 CRITICAL | 2 | Planning (5 cmds), Execution (5 cmds) |
+| ⚠️ HIGH | 2 | Tool selection, Enhancement flags |
+| ℹ️ MEDIUM | 3 | Analysis, Task/Workflow overlap, Output locations |
+| ✅ LOW | Multiple | Most other commands acceptable |
+
+### Key Recommendations Priority
+
+1. **🚨 URGENT**: Add safety warnings to YOLO execution commands
+2. **🚨 URGENT**: Create decision trees for planning and execution commands
+3. **⚠️ HIGH**: Standardize tool selection criteria documentation
+4. **⚠️ HIGH**: Clarify enhancement flag meanings
+5. **ℹ️ MEDIUM**: Reorganize output directories by operation type
+6. **ℹ️ MEDIUM**: Consider renaming most ambiguous commands
+
+---
+
+## Recommended Actions
+
+### Immediate (Week 1)
+1. ✅ Add decision trees to documentation
+2. ✅ Add ⚠️ WARNING labels to YOLO commands
+3. ✅ Create "Which command should I use?" guide
+
+### Short-term (Month 1)
+1. ✅ Standardize flag meanings across commands
+2. ✅ Add tool selection guide
+3. ✅ Clarify command descriptions
+
+### Long-term (Future)
+1. 🤔 Consider command consolidation or renaming
+2. 🤔 Reorganize output directory structure
+3. 🤔 Add interactive command selector tool
+
+---
+
+## Conclusion
+
+The command system is **powerful but complex**. The main ambiguities stem from:
+- Multiple commands with similar names serving different purposes
+- Inconsistent parameter usage
+- Unclear decision criteria for command selection
+
+**Overall Assessment**: The codebase has a well-structured command system, but would benefit significantly from:
+1. Better documentation (decision trees, use case examples)
+2. Clearer naming conventions
+3. Consistent parameter patterns
+4. Safety warnings for destructive operations
+
+**Risk Level**: MEDIUM - Experienced users can navigate, but new users will struggle. The YOLO execution commands pose the highest risk of accidental misuse.
--- a/COMMAND_REFERENCE.md
+++ b/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

--- a/COMMAND_SPEC.md
+++ b/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**
--- a/CONTRIBUTING.md
+++ b/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
--- a/EXAMPLES.md
+++ b/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
--- a/FAQ.md
+++ b/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)!
--- a/GETTING_STARTED.md
+++ b/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
 ```
--- a/GETTING_STARTED_CN.md
+++ b/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 "分析内存泄漏问题的可能原因"
 ```

 ### 工具语义调用
--- a/OUTPUT_DIRECTORY_REORGANIZATION.md
+++ b/OUTPUT_DIRECTORY_REORGANIZATION.md
@@ -0,0 +1,654 @@
+# Output Directory Reorganization Recommendations
+
+## Executive Summary
+
+Current output directory structure mixes different operation types (read-only analysis, code modifications, planning artifacts) in the same directories, leading to confusion and poor organization. This document proposes a **semantic directory structure** that separates outputs by purpose and operation type.
+
+**Impact**: Affects 30+ commands, requires phased migration
+**Priority**: MEDIUM (improves clarity, not critical functionality)
+**Effort**: 2-4 weeks for full implementation
+
+---
+
+## Current Structure Analysis
+
+### Active Session Structure
+
+```
+.workflow/active/WFS-{session-id}/
+├── workflow-session.json          # Session metadata
+├── IMPL_PLAN.md                   # Planning document
+├── TODO_LIST.md                   # Progress tracking
+│
+├── .chat/                         # ⚠️ MIXED PURPOSE
+│   ├── analyze-*.md               # Read-only analysis
+│   ├── plan-*.md                  # Read-only planning
+│   ├── discuss-plan-*.md          # Read-only discussion
+│   ├── execute-*.md               # ⚠️ Code-modifying execution
+│   └── chat-*.md                  # Q&A interactions
+│
+├── .summaries/                    # Task completion summaries
+│   ├── IMPL-*-summary.md
+│   └── TEST-FIX-*-summary.md
+│
+├── .task/                         # Task definitions
+│   ├── IMPL-001.json
+│   └── IMPL-001.1.json
+│
+└── .process/                      # ⚠️ MIXED PURPOSE
+    ├── context-package.json       # Planning context
+    ├── test-context-package.json  # Test context
+    ├── phase2-analysis.json       # Temporary analysis
+    ├── CONFLICT_RESOLUTION.md     # Planning artifact
+    ├── ACTION_PLAN_VERIFICATION.md # Verification report
+    └── backup/                    # Backup storage
+        └── replan-{timestamp}/
+```
+
+### Scratchpad Structure (No Session)
+
+```
+.workflow/.scratchpad/
+├── analyze-*.md
+├── execute-*.md
+├── chat-*.md
+└── plan-*.md
+```
+
+---
+
+## Problems Identified
+
+### 1. **Semantic Confusion** 🚨 CRITICAL
+
+**Problem**: `.chat/` directory contains both:
+- ✅ Read-only operations (analyze, chat, plan)
+- ⚠️ Code-modifying operations (execute)
+
+**Impact**: Users assume `.chat/` is safe (read-only), but some files represent dangerous operations
+
+**Example**:
+```bash
+# These both output to .chat/ but have VERY different impacts:
+/cli:analyze "review auth code"        # Read-only → .chat/analyze-*.md
+/cli:execute "implement auth feature"  # ⚠️ MODIFIES CODE → .chat/execute-*.md
+```
+
+### 2. **Purpose Overload**
+
+**Problem**: `.process/` used for multiple unrelated purposes:
+- Planning artifacts (context-package.json)
+- Temporary analysis (phase2-analysis.json)
+- Verification reports (ACTION_PLAN_VERIFICATION.md)
+- Backup storage (backup/)
+
+**Impact**: Difficult to understand what's in `.process/`
+
+### 3. **Inconsistent Organization**
+
+**Problem**: Different commands use different naming patterns:
+- Some use timestamps: `analyze-{timestamp}.md`
+- Some use topics: `plan-{topic}.md`
+- Some use task IDs: `IMPL-001-summary.md`
+
+**Impact**: Hard to find specific outputs
+
+### 4. **No Operation Type Distinction**
+
+**Problem**: Can't distinguish operation type from directory structure:
+- Analysis outputs mixed with execution logs
+- Planning discussions mixed with implementation records
+- No clear audit trail
+
+**Impact**: Poor traceability, difficult debugging
+
+---
+
+## Proposed New Structure
+
+### Design Principles
+
+1. **Semantic Organization**: Directories reflect operation type and safety level
+2. **Clear Hierarchy**: Separate by purpose → type → chronology
+3. **Safety Indicators**: Code-modifying operations clearly separated
+4. **Consistent Naming**: Standard patterns across all commands
+5. **Backward Compatible**: Old structure accessible during migration
+
+---
+
+## Recommended Structure v2.0
+
+```
+.workflow/active/WFS-{session-id}/
+│
+├── ## Core Artifacts (Root Level)
+├── workflow-session.json
+├── IMPL_PLAN.md
+├── TODO_LIST.md
+│
+├── ## Task Definitions
+├── tasks/                         # (renamed from .task/)
+│   ├── IMPL-001.json
+│   └── IMPL-001.1.json
+│
+├── ## 🟢 READ-ONLY Operations (Safe)
+├── analysis/                      # (split from .chat/)
+│   ├── code/
+│   │   ├── 2024-01-15T10-30-auth-patterns.md
+│   │   └── 2024-01-15T11-45-api-structure.md
+│   ├── architecture/
+│   │   └── 2024-01-14T09-00-caching-layer.md
+│   └── bugs/
+│       └── 2024-01-16T14-20-login-bug-diagnosis.md
+│
+├── planning/                      # (split from .chat/)
+│   ├── discussions/
+│   │   └── 2024-01-13T15-00-auth-strategy-3rounds.md
+│   ├── architecture/
+│   │   └── 2024-01-13T16-30-database-design.md
+│   └── revisions/
+│       └── 2024-01-17T10-00-replan-add-2fa.md
+│
+├── interactions/                  # (split from .chat/)
+│   ├── 2024-01-15T10-00-question-about-jwt.md
+│   └── 2024-01-15T14-30-how-to-test-auth.md
+│
+├── ## ⚠️ CODE-MODIFYING Operations (Dangerous)
+├── executions/                    # (split from .chat/)
+│   ├── implementations/
+│   │   ├── 2024-01-15T11-00-impl-jwt-auth.md
+│   │   ├── 2024-01-15T12-30-impl-user-api.md
+│   │   └── metadata.json          # Execution metadata
+│   ├── test-fixes/
+│   │   └── 2024-01-16T09-00-fix-auth-tests.md
+│   └── refactors/
+│       └── 2024-01-16T15-00-refactor-middleware.md
+│
+├── ## Completion Records
+├── summaries/                     # (kept same)
+│   ├── implementations/
+│   │   ├── IMPL-001-jwt-authentication.md
+│   │   └── IMPL-002-user-endpoints.md
+│   ├── tests/
+│   │   └── TEST-FIX-001-auth-validation.md
+│   └── index.json                 # Quick lookup
+│
+├── ## Planning Context & Artifacts
+├── context/                       # (split from .process/)
+│   ├── project/
+│   │   ├── context-package.json
+│   │   └── test-context-package.json
+│   ├── brainstorm/
+│   │   ├── guidance-specification.md
+│   │   ├── synthesis-output.md
+│   │   └── roles/
+│   │       ├── api-designer-analysis.md
+│   │       └── system-architect-analysis.md
+│   └── conflicts/
+│       └── 2024-01-14T10-00-resolution.md
+│
+├── ## Verification & Quality
+├── quality/                       # (split from .process/)
+│   ├── verifications/
+│   │   └── 2024-01-15T09-00-action-plan-verify.md
+│   ├── reviews/
+│   │   ├── 2024-01-17T11-00-security-review.md
+│   │   └── 2024-01-17T12-00-architecture-review.md
+│   └── tdd-compliance/
+│       └── 2024-01-16T16-00-cycle-analysis.md
+│
+├── ## History & Backups
+├── history/                       # (renamed from .process/backup/)
+│   ├── replans/
+│   │   └── 2024-01-17T10-00-add-2fa/
+│   │       ├── MANIFEST.md
+│   │       ├── IMPL_PLAN.md
+│   │       └── tasks/
+│   └── snapshots/
+│       └── 2024-01-15T00-00-milestone-1/
+│
+└── ## Temporary Working Data
+    └── temp/                      # (for transient analysis)
+        └── phase2-analysis.json
+```
+
+### Scratchpad Structure v2.0
+
+```
+.workflow/.scratchpad/
+├── analysis/
+├── planning/
+├── interactions/
+└── executions/          # ⚠️ Code-modifying
+```
+
+---
+
+## Directory Purpose Reference
+
+| Directory | Purpose | Safety | Retention |
+|-----------|---------|--------|-----------|
+| `analysis/` | Code understanding, bug diagnosis | 🟢 Read-only | Keep indefinitely |
+| `planning/` | Architecture plans, discussions | 🟢 Read-only | Keep indefinitely |
+| `interactions/` | Q&A, chat sessions | 🟢 Read-only | Keep 30 days |
+| `executions/` | Implementation logs | ⚠️ Modifies code | Keep indefinitely |
+| `summaries/` | Task completion records | 🟢 Reference | Keep indefinitely |
+| `context/` | Planning context, brainstorm | 🟢 Reference | Keep indefinitely |
+| `quality/` | Reviews, verifications | 🟢 Reference | Keep indefinitely |
+| `history/` | Backups, snapshots | 🟢 Archive | Keep indefinitely |
+| `temp/` | Transient analysis data | 🟢 Temporary | Clean on completion |
+
+---
+
+## Naming Convention Standards
+
+### Timestamp-based Files
+
+**Format**: `YYYY-MM-DDTHH-MM-{description}.md`
+
+**Examples**:
+- `2024-01-15T10-30-auth-patterns.md`
+- `2024-01-15T11-45-jwt-implementation.md`
+
+**Benefits**:
+- Chronological sorting
+- Unique identifiers
+- Easy to find by date
+
+### Task-based Files
+
+**Format**: `{TASK-ID}-{description}.md`
+
+**Examples**:
+- `IMPL-001-jwt-authentication.md`
+- `TEST-FIX-002-login-validation.md`
+
+**Benefits**:
+- Clear task association
+- Easy to find by task ID
+
+### Metadata Files
+
+**Format**: `{type}.json` or `{type}-metadata.json`
+
+**Examples**:
+- `context-package.json`
+- `execution-metadata.json`
+- `index.json`
+
+---
+
+## Command Output Mapping
+
+### Analysis Commands → `analysis/`
+
+| Command | Old Location | New Location |
+|---------|-------------|--------------|
+| `/cli:analyze` | `.chat/analyze-*.md` | `analysis/code/{timestamp}-{topic}.md` |
+| `/cli:mode:code-analysis` | `.chat/code-analysis-*.md` | `analysis/code/{timestamp}-{topic}.md` |
+| `/cli:mode:bug-diagnosis` | `.chat/bug-diagnosis-*.md` | `analysis/bugs/{timestamp}-{topic}.md` |
+
+### Planning Commands → `planning/`
+
+| Command | Old Location | New Location |
+|---------|-------------|--------------|
+| `/cli:mode:plan` | `.chat/plan-*.md` | `planning/architecture/{timestamp}-{topic}.md` |
+| `/cli:discuss-plan` | `.chat/discuss-plan-*.md` | `planning/discussions/{timestamp}-{topic}.md` |
+| `/workflow:replan` | (modifies artifacts) | `planning/revisions/{timestamp}-{reason}.md` |
+
+### Execution Commands → `executions/`
+
+| Command | Old Location | New Location |
+|---------|-------------|--------------|
+| `/cli:execute` | `.chat/execute-*.md` | `executions/implementations/{timestamp}-{description}.md` |
+| `/cli:codex-execute` | `.chat/codex-*.md` | `executions/implementations/{timestamp}-{description}.md` |
+| `/workflow:execute` | (multiple) | `executions/implementations/{timestamp}-{task-id}.md` |
+| `/workflow:test-cycle-execute` | (various) | `executions/test-fixes/{timestamp}-cycle-{n}.md` |
+
+### Quality Commands → `quality/`
+
+| Command | Old Location | New Location |
+|---------|-------------|--------------|
+| `/workflow:action-plan-verify` | `.process/ACTION_PLAN_VERIFICATION.md` | `quality/verifications/{timestamp}-action-plan.md` |
+| `/workflow:review` | (inline) | `quality/reviews/{timestamp}-{type}.md` |
+| `/workflow:tdd-verify` | (inline) | `quality/tdd-compliance/{timestamp}-verify.md` |
+
+### Context Commands → `context/`
+
+| Data Type | Old Location | New Location |
+|-----------|-------------|--------------|
+| Context packages | `.process/context-package.json` | `context/project/context-package.json` |
+| Brainstorm artifacts | `.process/` | `context/brainstorm/` |
+| Conflict resolution | `.process/CONFLICT_RESOLUTION.md` | `context/conflicts/{timestamp}-resolution.md` |
+
+---
+
+## Migration Strategy
+
+### Phase 1: Dual Write (Week 1-2)
+
+**Goal**: Write to both old and new locations
+
+**Implementation**:
+```bash
+# Example for /cli:analyze
+old_path=".workflow/active/$session/.chat/analyze-$timestamp.md"
+new_path=".workflow/active/$session/analysis/code/$timestamp-$topic.md"
+
+# Write to both locations
+Write($old_path, content)
+Write($new_path, content)
+
+# Add migration notice to old location
+echo "⚠️ This file has moved to: $new_path" >> $old_path
+```
+
+**Changes**:
+- Update all commands to write to new structure
+- Keep writing to old structure for compatibility
+- Add deprecation notices
+
+**Commands to Update**: 30+ commands
+
+### Phase 2: Dual Read (Week 3)
+
+**Goal**: Read from new location, fallback to old
+
+**Implementation**:
+```bash
+# Example read logic
+if [ -f "$new_path" ]; then
+  content=$(cat "$new_path")
+elif [ -f "$old_path" ]; then
+  content=$(cat "$old_path")
+  # Migrate on read
+  mkdir -p "$(dirname "$new_path")"
+  cp "$old_path" "$new_path"
+  echo "✓ Migrated: $old_path → $new_path"
+fi
+```
+
+**Changes**:
+- Update read logic in all commands
+- Automatic migration on read
+- Log migrations for verification
+
+### Phase 3: Legacy Deprecation (Week 4)
+
+**Goal**: Stop writing to old locations
+
+**Implementation**:
+```bash
+# Stop dual write, only write to new structure
+new_path=".workflow/active/$session/analysis/code/$timestamp-$topic.md"
+Write($new_path, content)
+
+# No longer write to old_path
+```
+
+**Changes**:
+- Remove old write logic
+- Keep read fallback for 1 release cycle
+- Update documentation
+
+### Phase 4: Full Migration (Future Release)
+
+**Goal**: Remove old structure entirely
+
+**Implementation**:
+```bash
+# One-time migration script
+/workflow:migrate-outputs --session all --dry-run
+/workflow:migrate-outputs --session all --execute
+```
+
+**Migration Script**:
+```bash
+#!/bin/bash
+# migrate-outputs.sh
+
+session_dir="$1"
+
+# Migrate .chat/ files
+for file in "$session_dir/.chat"/*; do
+  case "$file" in
+    *analyze*)
+      mv "$file" "$session_dir/analysis/code/"
+      ;;
+    *execute*)
+      mv "$file" "$session_dir/executions/implementations/"
+      ;;
+    *plan*)
+      mv "$file" "$session_dir/planning/architecture/"
+      ;;
+    *chat*)
+      mv "$file" "$session_dir/interactions/"
+      ;;
+  esac
+done
+
+# Migrate .process/ files
+mv "$session_dir/.process/context-package.json" "$session_dir/context/project/"
+mv "$session_dir/.process/backup" "$session_dir/history/"
+
+# Remove old directories
+rmdir "$session_dir/.chat" "$session_dir/.process" 2>/dev/null
+
+echo "✓ Migration complete: $session_dir"
+```
+
+---
+
+## Implementation Checklist
+
+### Week 1-2: Dual Write Setup
+
+**Core Commands** (Priority 1):
+- [ ] `/cli:analyze` → `analysis/code/`
+- [ ] `/cli:execute` → `executions/implementations/`
+- [ ] `/cli:mode:plan` → `planning/architecture/`
+- [ ] `/workflow:execute` → `executions/implementations/`
+- [ ] `/workflow:action-plan-verify` → `quality/verifications/`
+
+**Planning Commands** (Priority 2):
+- [ ] `/cli:discuss-plan` → `planning/discussions/`
+- [ ] `/workflow:replan` → `planning/revisions/`
+- [ ] `/workflow:plan` → (updates `context/project/`)
+
+**Context Commands** (Priority 3):
+- [ ] `/workflow:tools:context-gather` → `context/project/`
+- [ ] `/workflow:brainstorm:*` → `context/brainstorm/`
+- [ ] `/workflow:tools:conflict-resolution` → `context/conflicts/`
+
+### Week 3: Dual Read + Auto-Migration
+
+**Read Logic Updates**:
+- [ ] Update all Read() calls with fallback logic
+- [ ] Add migration-on-read for all file types
+- [ ] Log all automatic migrations
+
+**Testing**:
+- [ ] Test with existing sessions
+- [ ] Test with new sessions
+- [ ] Verify backward compatibility
+
+### Week 4: Documentation + Deprecation
+
+**Documentation Updates**:
+- [ ] Update command documentation with new paths
+- [ ] Add migration guide for users
+- [ ] Document new directory structure
+- [ ] Add "Directory Purpose Reference" to docs
+
+**Deprecation Notices**:
+- [ ] Add notices to old command outputs
+- [ ] Update error messages with new paths
+- [ ] Create migration FAQ
+
+---
+
+## Benefits Analysis
+
+### Immediate Benefits
+
+**1. Safety Clarity** 🟢
+- Clear separation: Read-only vs Code-modifying operations
+- Users can quickly identify dangerous operations
+- Reduces accidental code modifications
+
+**2. Better Organization** 📁
+- Semantic structure reflects operation purpose
+- Easy to find specific outputs
+- Clear audit trail
+
+**3. Improved Traceability** 🔍
+- Execution logs separated by type
+- Planning discussions organized chronologically
+- Quality checks easily accessible
+
+### Long-term Benefits
+
+**4. Scalability** 📈
+- Structure scales to 100+ sessions
+- Easy to add new operation types
+- Consistent organization patterns
+
+**5. Automation Potential** 🤖
+- Programmatic analysis of outputs
+- Automated cleanup of old files
+- Better CI/CD integration
+
+**6. User Experience** 👥
+- Intuitive directory structure
+- Self-documenting organization
+- Easier onboarding for new users
+
+---
+
+## Risk Assessment
+
+### Migration Risks
+
+| Risk | Severity | Mitigation |
+|------|----------|------------|
+| **Breaking Changes** | HIGH | Phased migration with dual write/read |
+| **Data Loss** | MEDIUM | Automatic migration on read, keep backups |
+| **User Confusion** | MEDIUM | Clear documentation, migration guide |
+| **Command Failures** | LOW | Fallback to old locations during transition |
+| **Performance Impact** | LOW | Dual write adds minimal overhead |
+
+### Rollback Strategy
+
+If migration causes issues:
+
+**Phase 1 Rollback** (Dual Write):
+- Stop writing to new locations
+- Continue using old structure
+- No data loss
+
+**Phase 2 Rollback** (Dual Read):
+- Disable migration-on-read
+- Continue reading from old locations
+- New files still in new structure (OK)
+
+**Phase 3+ Rollback**:
+- Run reverse migration script
+- Copy new structure files back to old locations
+- May require manual intervention
+
+---
+
+## Alternative Approaches Considered
+
+### Alternative 1: Flat Structure with Prefixes
+
+```
+.workflow/active/WFS-{session}/
+├── ANALYSIS_2024-01-15_auth-patterns.md
+├── EXEC_2024-01-15_jwt-impl.md
+└── PLAN_2024-01-14_architecture.md
+```
+
+**Rejected**: Too many files in one directory, poor organization
+
+### Alternative 2: Single "logs/" Directory
+
+```
+.workflow/active/WFS-{session}/
+└── logs/
+    ├── 2024-01-15T10-30-analyze-auth.md
+    └── 2024-01-15T11-00-execute-jwt.md
+```
+
+**Rejected**: Doesn't solve semantic confusion
+
+### Alternative 3: Minimal Change (Status Quo++)
+
+```
+.workflow/active/WFS-{session}/
+├── .chat/          # Rename to .interactions/
+├── .exec/          # NEW: Split executions out
+├── .summaries/
+└── .process/
+```
+
+**Partially Adopted**: Considered as "lite" version if full migration too complex
+
+---
+
+## Recommended Timeline
+
+### Immediate (This Sprint)
+1. ✅ Document current structure
+2. ✅ Create proposed structure v2.0
+3. ✅ Get stakeholder approval
+
+### Short-term (Next 2 Sprints - 4 weeks)
+1. 📝 Implement Phase 1: Dual Write
+2. 🔍 Implement Phase 2: Dual Read
+3. 📢 Implement Phase 3: Deprecation
+
+### Long-term (Future Release)
+1. 🗑️ Implement Phase 4: Full Migration
+2. 🧹 Remove old structure code
+3. 📚 Update all documentation
+
+---
+
+## Success Metrics
+
+### Quantitative
+- ✅ 100% of commands updated to new structure
+- ✅ 0 data loss during migration
+- ✅ <5% increase in execution time (dual write overhead)
+- ✅ 90% of sessions migrated within 1 month
+
+### Qualitative
+- ✅ User feedback: "Easier to find outputs"
+- ✅ User feedback: "Clearer which operations are safe"
+- ✅ Developer feedback: "Easier to maintain"
+
+---
+
+## Conclusion
+
+The proposed directory reorganization addresses critical semantic confusion in the current structure by:
+
+1. **Separating read-only from code-modifying operations** (safety)
+2. **Organizing by purpose** (usability)
+3. **Using consistent naming** (maintainability)
+4. **Providing clear migration path** (feasibility)
+
+**Recommendation**: Proceed with phased migration starting with dual-write implementation.
+
+**Next Steps**:
+1. Review and approve proposed structure
+2. Identify pilot commands for Phase 1
+3. Create detailed implementation tasks
+4. Begin dual-write implementation
+
+**Questions for Discussion**:
+1. Should we use "lite" version (minimal changes) or full v2.0?
+2. What's the acceptable timeline for full migration?
+3. Are there any other directory purposes we should consider?
+4. Should we add more automation (e.g., auto-cleanup old files)?
--- a/OUTPUT_STRUCTURE_COMPARISON.md
+++ b/OUTPUT_STRUCTURE_COMPARISON.md
@@ -0,0 +1,404 @@
+# Output Structure: Before vs After
+
+## Quick Visual Comparison
+
+### Current Structure (v1.0) - ⚠️ Problematic
+
+```
+.workflow/active/WFS-session/
+├── .chat/                    ⚠️ MIXED: Safe + Dangerous operations
+│   ├── analyze-*.md          ✅ Read-only
+│   ├── plan-*.md             ✅ Read-only
+│   ├── chat-*.md             ✅ Read-only
+│   └── execute-*.md          ⚠️ MODIFIES CODE!
+│
+├── .summaries/               ✅ OK
+├── .task/                    ✅ OK
+└── .process/                 ⚠️ MIXED: Multiple purposes
+    ├── context-package.json  (planning context)
+    ├── phase2-analysis.json  (temp data)
+    ├── CONFLICT_RESOLUTION.md (planning artifact)
+    └── backup/               (history)
+```
+
+**Problems**:
+- ❌ `.chat/` mixes safe (read-only) and dangerous (code-modifying) operations
+- ❌ `.process/` serves too many purposes
+- ❌ No clear organization by operation type
+- ❌ Hard to find specific outputs
+
+---
+
+### Proposed Structure (v2.0) - ✅ Clear & Semantic
+
+```
+.workflow/active/WFS-session/
+│
+├── 🟢 SAFE: Read-only Operations
+│   ├── analysis/             Split from .chat/
+│   │   ├── code/            Code understanding
+│   │   ├── architecture/    Architecture analysis
+│   │   └── bugs/            Bug diagnosis
+│   │
+│   ├── planning/            Split from .chat/
+│   │   ├── discussions/     Multi-round planning
+│   │   ├── architecture/    Architecture plans
+│   │   └── revisions/       Replan history
+│   │
+│   └── interactions/        Split from .chat/
+│       └── *-chat.md        Q&A sessions
+│
+├── ⚠️ DANGEROUS: Code-modifying Operations
+│   └── executions/          Split from .chat/
+│       ├── implementations/ Code implementations
+│       ├── test-fixes/      Test fixes
+│       └── refactors/       Refactoring
+│
+├── 📊 RECORDS: Completion & Quality
+│   ├── summaries/           Keep same (task completions)
+│   │
+│   └── quality/             Split from .process/
+│       ├── verifications/   Plan verifications
+│       ├── reviews/         Code reviews
+│       └── tdd-compliance/  TDD checks
+│
+├── 📦 CONTEXT: Planning Artifacts
+│   └── context/             Split from .process/
+│       ├── project/         Context packages
+│       ├── brainstorm/      Brainstorm artifacts
+│       └── conflicts/       Conflict resolutions
+│
+├── 📜 HISTORY: Backups & Archives
+│   └── history/             Rename from .process/backup/
+│       ├── replans/         Replan backups
+│       └── snapshots/       Session snapshots
+│
+└── 📋 TASKS: Definitions
+    └── tasks/               Rename from .task/
+```
+
+**Benefits**:
+- ✅ Clear separation: Safe vs Dangerous operations
+- ✅ Semantic organization by purpose
+- ✅ Easy to find outputs by type
+- ✅ Self-documenting structure
+
+---
+
+## Key Changes Summary
+
+### 1. Split `.chat/` by Safety Level
+
+| Current | New | Safety |
+|---------|-----|--------|
+| `.chat/analyze-*.md` | `analysis/code/` | 🟢 Safe |
+| `.chat/plan-*.md` | `planning/architecture/` | 🟢 Safe |
+| `.chat/chat-*.md` | `interactions/` | 🟢 Safe |
+| `.chat/execute-*.md` | `executions/implementations/` | ⚠️ Dangerous |
+
+### 2. Split `.process/` by Purpose
+
+| Current | New | Purpose |
+|---------|-----|---------|
+| `.process/context-package.json` | `context/project/` | Planning context |
+| `.process/CONFLICT_RESOLUTION.md` | `context/conflicts/` | Planning artifact |
+| `.process/ACTION_PLAN_VERIFICATION.md` | `quality/verifications/` | Quality check |
+| `.process/backup/` | `history/replans/` | Backups |
+| `.process/phase2-analysis.json` | `temp/` | Temporary data |
+
+### 3. Rename for Clarity
+
+| Current | New | Reason |
+|---------|-----|--------|
+| `.task/` | `tasks/` | Remove dot prefix (not hidden) |
+| `.summaries/` | `summaries/` | Keep same (already clear) |
+
+---
+
+## Command Output Changes (Examples)
+
+### Analysis Commands
+
+```bash
+# Current (v1.0)
+/cli:analyze "review auth code"
+→ .chat/analyze-2024-01-15.md               ⚠️ Mixed with dangerous ops
+
+# Proposed (v2.0)
+/cli:analyze "review auth code"
+→ analysis/code/2024-01-15T10-30-auth.md    ✅ Clearly safe
+```
+
+### Execution Commands
+
+```bash
+# Current (v1.0)
+/cli:execute "implement auth"
+→ .chat/execute-2024-01-15.md               ⚠️ Looks safe, but dangerous!
+
+# Proposed (v2.0)
+/cli:execute "implement auth"
+→ executions/implementations/2024-01-15T11-00-auth.md    ⚠️ Clearly dangerous
+```
+
+### Planning Commands
+
+```bash
+# Current (v1.0)
+/cli:discuss-plan "design caching"
+→ .chat/discuss-plan-2024-01-15.md          ⚠️ Mixed with dangerous ops
+
+# Proposed (v2.0)
+/cli:discuss-plan "design caching"
+→ planning/discussions/2024-01-15T15-00-caching-3rounds.md    ✅ Clearly safe
+```
+
+---
+
+## Migration Impact
+
+### Affected Commands: ~30
+
+**Analysis Commands** (6):
+- `/cli:analyze`
+- `/cli:mode:code-analysis`
+- `/cli:mode:bug-diagnosis`
+- `/cli:chat`
+- `/memory:code-map-memory`
+- `/workflow:review`
+
+**Planning Commands** (5):
+- `/cli:mode:plan`
+- `/cli:discuss-plan`
+- `/workflow:plan`
+- `/workflow:replan`
+- `/workflow:brainstorm:*`
+
+**Execution Commands** (8):
+- `/cli:execute`
+- `/cli:codex-execute`
+- `/workflow:execute`
+- `/workflow:lite-execute`
+- `/task:execute`
+- `/workflow:test-cycle-execute`
+- `/workflow:test-fix-gen`
+- `/workflow:test-gen`
+
+**Quality Commands** (4):
+- `/workflow:action-plan-verify`
+- `/workflow:review`
+- `/workflow:tdd-verify`
+- `/workflow:tdd-coverage-analysis`
+
+**Context Commands** (7):
+- `/workflow:tools:context-gather`
+- `/workflow:tools:conflict-resolution`
+- `/workflow:brainstorm:artifacts`
+- `/memory:skill-memory`
+- `/memory:docs`
+- `/memory:load`
+- `/memory:tech-research`
+
+---
+
+## Safety Indicators
+
+### Directory Color Coding
+
+- 🟢 **Green** (Safe): Read-only operations, no code changes
+  - `analysis/`
+  - `planning/`
+  - `interactions/`
+  - `summaries/`
+  - `quality/`
+  - `context/`
+  - `history/`
+
+- ⚠️ **Yellow** (Dangerous): Code-modifying operations
+  - `executions/`
+
+### File Naming Patterns
+
+**Safe Operations** (🟢):
+```
+analysis/code/2024-01-15T10-30-auth-patterns.md
+planning/discussions/2024-01-15T15-00-caching-3rounds.md
+interactions/2024-01-15T14-00-jwt-question.md
+```
+
+**Dangerous Operations** (⚠️):
+```
+executions/implementations/2024-01-15T11-00-impl-auth.md
+executions/test-fixes/2024-01-16T09-00-fix-login-tests.md
+executions/refactors/2024-01-16T15-00-refactor-middleware.md
+```
+
+---
+
+## User Experience Improvements
+
+### Before (v1.0) - Confusing ❌
+
+**User wants to review analysis logs**:
+```bash
+$ ls .workflow/active/WFS-auth/.chat/
+analyze-2024-01-15.md
+execute-2024-01-15.md    # ⚠️ Wait, which one is safe?
+plan-2024-01-14.md
+execute-2024-01-16.md    # ⚠️ More dangerous files mixed in!
+chat-2024-01-15.md
+```
+
+User thinks: "They're all in `.chat/`, so they're all logs... right?" 😰
+
+### After (v2.0) - Clear ✅
+
+**User wants to review analysis logs**:
+```bash
+$ ls .workflow/active/WFS-auth/
+analysis/      # ✅ Safe - code understanding
+planning/      # ✅ Safe - planning discussions
+interactions/  # ✅ Safe - Q&A logs
+executions/    # ⚠️ DANGER - code modifications
+```
+
+User thinks: "Oh, `executions/` is separate. I know that modifies code!" 😊
+
+---
+
+## Performance Impact
+
+### Storage
+
+**Overhead**: Negligible
+- Deeper directory nesting adds ~10 bytes per file
+- For 1000 files: ~10 KB additional metadata
+
+### Access Speed
+
+**Overhead**: Negligible
+- Modern filesystems handle nested directories efficiently
+- Typical lookup: O(log n) regardless of depth
+
+### Migration Cost
+
+**Phase 1 (Dual Write)**: ~5-10% overhead
+- Writing to both old and new locations
+- Temporary during migration period
+
+**Phase 2+ (New Structure Only)**: No overhead
+- Single write location
+- Actually slightly faster (better organization)
+
+---
+
+## Rollback Plan
+
+If migration causes issues:
+
+### Easy Rollback (Phase 1-2)
+
+```bash
+# Stop using new structure
+git revert <migration-commit>
+# Continue with old structure
+# No data loss (dual write preserved both)
+```
+
+### Manual Rollback (Phase 3+)
+
+```bash
+# Copy files back to old locations
+cp -r analysis/code/* .chat/
+cp -r executions/implementations/* .chat/
+cp -r context/project/* .process/
+# etc.
+```
+
+---
+
+## Timeline Summary
+
+| Phase | Duration | Status | Risk |
+|-------|----------|--------|------|
+| **Phase 1**: Dual Write | 2 weeks | 📋 Planned | LOW |
+| **Phase 2**: Dual Read | 1 week | 📋 Planned | LOW |
+| **Phase 3**: Deprecation | 1 week | 📋 Planned | MEDIUM |
+| **Phase 4**: Full Migration | Future | 🤔 Optional | MEDIUM |
+
+**Total**: 4 weeks for Phases 1-3
+**Effort**: ~20-30 hours development time
+
+---
+
+## Decision: Which Approach?
+
+### Option A: Full v2.0 Migration (Recommended) ✅
+
+**Pros**:
+- ✅ Clear semantic separation
+- ✅ Future-proof organization
+- ✅ Best user experience
+- ✅ Solves all identified problems
+
+**Cons**:
+- ❌ 4-week migration period
+- ❌ Affects 30+ commands
+- ❌ Requires documentation updates
+
+**Recommendation**: **YES** - Worth the investment
+
+### Option B: Minimal Changes (Quick Fix)
+
+**Change**:
+```
+.chat/ → Split into .analysis/ and .executions/
+.process/ → Keep as-is with better docs
+```
+
+**Pros**:
+- ✅ Quick implementation (1 week)
+- ✅ Solves main safety confusion
+
+**Cons**:
+- ❌ Partial solution
+- ❌ Still some confusion
+- ❌ May need full migration later anyway
+
+**Recommendation**: Only if time-constrained
+
+### Option C: Status Quo (No Change)
+
+**Pros**:
+- ✅ No development effort
+
+**Cons**:
+- ❌ Problems remain
+- ❌ User confusion continues
+- ❌ Safety risks
+
+**Recommendation**: **NO** - Not recommended
+
+---
+
+## Conclusion
+
+**Recommended Action**: Proceed with **Option A (Full v2.0 Migration)**
+
+**Key Benefits**:
+1. 🟢 Clear safety separation (read-only vs code-modifying)
+2. 📁 Semantic organization by purpose
+3. 🔍 Easy to find specific outputs
+4. 📈 Scales for future growth
+5. 👥 Better user experience
+
+**Next Steps**:
+1. ✅ Review and approve this proposal
+2. 📋 Create detailed implementation tasks
+3. 🚀 Begin Phase 1: Dual Write implementation
+4. 📚 Update documentation in parallel
+
+**Questions?**
+- See detailed analysis in: `OUTPUT_DIRECTORY_REORGANIZATION.md`
+- Implementation guide: Migration Strategy section
+- Risk assessment: Risk Assessment section
--- a/PROJECT_INTRODUCTION.md
+++ b/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
 ```

--- a/README.md
+++ b/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

--- a/README_CN.md
+++ b/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) 了解贡献指南。

 ## 📄 许可证

--- a/WORKFLOW_DECISION_GUIDE.md
+++ b/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
Author	SHA1	Message	Date
Claude	63ca455c64	docs: add visual before/after comparison for output structure - Clear side-by-side comparison of current vs proposed structure - Safety indicators (safe vs dangerous operations) - Command output examples showing the improvements - User experience improvements with concrete examples - Performance impact analysis - Timeline and decision framework - Complements OUTPUT_DIRECTORY_REORGANIZATION.md with visual summary	2025-11-20 09:20:43 +00:00
Claude	9f1a9a7731	docs: comprehensive output directory reorganization recommendations - Analyzed current structure across 30+ commands - Identified semantic confusion: .chat/ mixes read-only and code-modifying operations - Proposed v2.0 structure with clear separation: * analysis/ - Read-only code understanding * planning/ - Read-only architecture planning * executions/ - Code-modifying operations (clearly marked) * quality/ - Reviews and verifications * context/ - Planning context and brainstorm artifacts * history/ - Backups and snapshots - Detailed 4-phase migration strategy (dual write → dual read → deprecation → full migration) - Command output mapping for all affected commands - Risk assessment and rollback strategies - Implementation checklist with timeline	2025-11-20 09:19:20 +00:00
Claude	38f8175780	docs: comprehensive command ambiguity analysis - Identified 5 major ambiguity clusters in 74 commands - Critical issues: Planning command overload (5 variants) - Critical issues: Execution command confusion (5 variants) - High priority: Tool selection and enhancement flag inconsistency - Added decision trees for command selection - Provided recommendations for immediate, short-term, and long-term improvements	2025-11-20 09:06:21 +00:00
catlog22	751d251433	Merge pull request #16 from catlog22/claude/fix-lexical-error-01QGNCxKABnMVrn1PSTCMLCW Fix lexical error in rich display rendering	2025-11-20 13:58:18 +08:00
Claude	51b1eb5da6	fix: correct Mermaid parallelogram syntax for command nodes Fixed lexical error in Mermaid diagram where nodes starting with [/workflow: were not properly closed. Changed to use correct parallelogram syntax [/ text /] to resolve "Unrecognized text" error. Affected nodes: - BrainIdea, BrainDesign (brainstorm commands) - UIImitate, UIExplore, UISync (UI design commands) - LitePlanE, LitePlanNormal, LiteAgent (lite workflow commands) - Verify, Execute variants (verification/execution commands) - TDD, TestGen, TestCycle (testing commands) - SecurityReview, ArchReview, QualityReview, GeneralReview (review commands)	2025-11-20 05:45:41 +00:00
catlog22	275ed051c6	Merge pull request #15 from catlog22/claude/add-project-documentation-01KoecebaGvjvFiUYgAWyL6F fix: remove quotes from Mermaid node labels to resolve rendering error	2025-11-20 13:32:26 +08:00
Claude	fa7f37695e	fix: remove quotes from Mermaid node labels to resolve rendering error	2025-11-20 05:26:25 +00:00
catlog22	5e69748016	Merge pull request #14 from catlog22/claude/add-project-documentation-01KoecebaGvjvFiUYgAWyL6F fix: replace <br/> with <br> for GitHub Mermaid compatibility	2025-11-20 13:22:49 +08:00
Claude	f1fff34a9d	fix: replace <br/> with <br> for GitHub Mermaid compatibility GitHub's Mermaid renderer requires <br> instead of <br/> for line breaks in node labels. Fixed all 32 occurrences in the workflow decision flowchart.	2025-11-20 05:20:23 +00:00
catlog22	8ae3da8f61	Merge pull request #13 from catlog22/claude/add-project-documentation-01KoecebaGvjvFiUYgAWyL6F docs: clarify brainstorm vs plan workflow and add decision guide	2025-11-20 13:19:03 +08:00
Claude	62ffc5c645	docs: clarify brainstorm vs plan workflow and add decision guide Major improvements to workflow understanding and guidance: 1. New Document: WORKFLOW_DECISION_GUIDE.md - Comprehensive decision flowchart for full software lifecycle - Interactive Mermaid diagram with 40+ decision points - Clear guidance on when to use each command - Real-world scenarios for all workflow types - Quick reference tables by knowledge level, project stage, and mode - Expert tips and common pitfalls 2. Clarified Brainstorm vs Plan Relationship Core concept correction: - Brainstorm: Use when you know WHAT to build, NOT HOW - Plan: Use when you know both WHAT and HOW - Plan can accept user input OR brainstorm output 3. Updated Documentation Files - GETTING_STARTED.md: Added clear distinction and decision criteria - GETTING_STARTED_CN.md: Chinese version with same clarifications - FAQ.md: Enhanced brainstorm usage explanation with workflow comparison table - README.md: Added Workflow Decision Guide link - README_CN.md: Added Chinese link to decision guide 4. Key Improvements When to Use Brainstorming: - Unclear solution approach (multiple ways to solve) - Architectural exploration needed - Requirements clarification (high-level clear, details not) - Multiple trade-offs to analyze - Unfamiliar domain When to Skip Brainstorming: - Clear implementation approach - Similar to existing code patterns - Well-defined requirements - Simple features 5. Decision Flowchart Covers: - Ideation phase (know what to build?) - Design phase (know how to build?) - UI design phase (need UI design?) - Planning phase (complexity level?) - Testing phase (TDD, post-test, test-fix?) - Review phase (security, architecture, quality?) - Completion Benefits: - Eliminates confusion about brainstorm usage - Provides clear decision criteria for all commands - Visual flowchart helps users navigate workflows - Comprehensive coverage of all development stages - Reduces trial-and-error in workflow selection Files modified: 5 Files added: 1 (WORKFLOW_DECISION_GUIDE.md)	2025-11-20 05:14:57 +00:00
catlog22	758321b829	Merge pull request #12 from catlog22/claude/add-project-documentation-01KoecebaGvjvFiUYgAWyL6F docs: add comprehensive project documentation	2025-11-20 13:08:54 +08:00
Claude	85d7fd9340	docs: fix command name inconsistencies across documentation Fix multiple command naming and parameter inconsistencies: 1. Command Name Fixes: - Change /cli:mode:bug-index to /cli:mode:bug-diagnosis - Affected files: COMMAND_REFERENCE.md, COMMAND_SPEC.md, EXAMPLES.md, GETTING_STARTED.md, GETTING_STARTED_CN.md, PROJECT_INTRODUCTION.md 2. Parameter Fixes: - Remove invalid --tool parameter from /workflow:lite-plan - The lite-plan command does not support --tool flag - Affected files: README.md, README_CN.md, COMMAND_SPEC.md 3. Invalid Command Fixes in PROJECT_INTRODUCTION.md: - Change /gemini:analyze to /cli:analyze --tool gemini - Change /qwen:mode:plan to /cli:mode:plan --tool qwen - Change /codex:mode:auto to /cli:execute --tool codex - Change /workflow:plan-deep to /workflow:plan - These legacy command formats are no longer valid Impact: - All documentation now matches actual command implementations - Users will not encounter "command not found" errors - Examples are now executable and correct - Consistent command syntax across all docs Files modified: 8 - COMMAND_REFERENCE.md - COMMAND_SPEC.md - EXAMPLES.md - GETTING_STARTED.md - GETTING_STARTED_CN.md - PROJECT_INTRODUCTION.md - README.md - README_CN.md	2025-11-20 05:07:36 +00:00
Claude	fbd41a0851	docs: add comprehensive project documentation Add four new comprehensive documentation files and update READMEs: New Documentation: - ARCHITECTURE.md: High-level system architecture overview * Design philosophy and core principles * System components and data flow * Multi-agent system details * CLI tool integration strategy * Session and memory management * Performance optimizations and best practices - CONTRIBUTING.md: Contributor guidelines * Code of conduct * Development setup instructions * Coding standards and best practices * Testing guidelines * Documentation requirements * Pull request process * Release process - FAQ.md: Frequently asked questions * General questions about CCW * Installation and setup * Usage and workflows * Commands and syntax * Sessions and tasks * Agents and tools * Memory system * Troubleshooting * Advanced topics - EXAMPLES.md: Real-world use cases * Quick start examples * Web development (Express, React, e-commerce) * API development (REST, GraphQL) * Testing & quality assurance (TDD, test generation) * Refactoring (monolith to microservices) * UI/UX design (design systems, landing pages) * Bug fixes (simple and complex) * Documentation generation * DevOps & automation (CI/CD, Docker) * Complex projects (chat app, analytics dashboard) Updated Documentation: - README.md: Added comprehensive documentation section * Organized docs into categories * Links to all new documentation files * Improved navigation structure - README_CN.md: Added documentation section (Chinese) * Same organization as English version * Links to all documentation resources Benefits: - Provides clear entry points for new users - Comprehensive reference for all features - Real-world examples for practical learning - Complete contributor onboarding - Better project discoverability	2025-11-20 04:44:15 +00:00
catlog22	2a63ab5e0a	Merge pull request #11 from catlog22/claude/refactor-task-workflow-01WBDUE6UgN74q4JhmwDJ6c1 Refactor task replan into workflow structure	2025-11-20 12:34:31 +08:00
Claude	46527c5b9a	docs: remove Core Principles sections from replan commands Remove unnecessary Core Principles sections that reference task-core.md and workflow-architecture.md from both workflow:replan and task:replan documentation to align with execute.md style and maintain simplicity.	2025-11-20 04:32:00 +00:00
Claude	b9e893245b	refactor(workflow): simplify workflow:replan documentation ## Changes ### Documentation Simplification - Removed version information and comparison tables - Removed "Migration from task:replan" section - Removed "Related Commands" section - Removed redundant "Implementation Notes" section - Streamlined examples to essential use cases only ### Followed execute.md Style - Clean, focused structure - Direct entry into core functionality - Clear phase-based execution lifecycle - Concise error handling - Essential file structure reference ### Maintained Core Content - Overview with core capabilities - Operation modes (Session/Task) - 6-phase execution lifecycle - Interactive clarification questions - TodoWrite progress tracking - Error handling examples - Practical usage examples The documentation now follows the established pattern from execute.md and other workflow commands, providing essential information without redundant sections or comparisons.	2025-11-20 03:19:47 +00:00
Claude	d96a8a06a0	feat(workflow): add workflow:replan command with session-level replanning support ## Changes ### New Command: workflow:replan - Created `.claude/commands/workflow/replan.md` with comprehensive session-level replanning - Supports dual modes: session-wide and task-specific replanning - Interactive boundary clarification using guided questioning - Updates multiple artifacts: IMPL_PLAN.md, TODO_LIST.md, task JSONs, session metadata - Comprehensive backup management with restore capability ### Key Features 1. Interactive Clarification: Guided questions to define modification scope - Modification scope (tasks only, plan update, task restructure, comprehensive) - Affected modules detection - Task change types (add, remove, merge, split, update) - Dependency relationship updates 2. Session-Aware Operations: - Auto-detects active sessions from `.workflow/active/` - Updates all session artifacts consistently - Maintains backup history in `.process/backup/replan-{timestamp}/` 3. Comprehensive Artifact Updates: - IMPL_PLAN.md section modifications - TODO_LIST.md task list updates - Task JSON files (requirements, implementation, dependencies) - Session metadata tracking 4. Impact Analysis: Automatically determines affected files and operations ### Deprecation - Added deprecation notice to `/task:replan` in both command and reference files - Updated `COMMAND_REFERENCE.md` to: - Add workflow:replan to Core Workflow section - Mark task:replan as deprecated with migration guidance ### Migration Path - Old: `/task:replan IMPL-1 "changes"` - New: `/workflow:replan IMPL-1 "changes"` ### Files Modified - `.claude/commands/task/replan.md`: Added deprecation notice - `.claude/commands/workflow/replan.md`: New command implementation - `.claude/skills/command-guide/reference/commands/task/replan.md`: Deprecation notice - `.claude/skills/command-guide/reference/commands/workflow/replan.md`: Reference documentation - `COMMAND_REFERENCE.md`: Updated command listings This change enhances workflow replanning capabilities by providing interactive, session-aware modifications that maintain consistency across all workflow artifacts.	2025-11-20 03:11:28 +00:00
catlog22	957473aa71	Merge pull request #10 from catlog22/claude/audit-command-docs-agents-011tVdT2942cX3W3fib9pYQz Claude/audit command docs agents 011t vd t2942c x3 w3fib9p y qz	2025-11-20 11:05:05 +08:00