docs: add CLI results as memory/context section

Add comprehensive explanation of how CLI tool results can be saved and reused as context for subsequent operations: - Result persistence in workflow sessions (.chat/ directory) - Using analysis results as planning basis - Using analysis results as implementation basis - Cross-session references - Memory update loops with iterative optimization - Visual memory flow diagram showing phase-to-phase context passing - Best practices for maintaining continuity and quality This enables intelligent workflows where Gemini/Qwen analysis informs Codex implementation, and all results accumulate as project memory for future decision-making. Integrates with /workflow:plan and /workflow:lite-plan commands.
docs: add CLI tools collaboration mode to Workflow Decision Guide
2026-02-13 02:41:50 +08:00 · 2025-11-20 09:53:21 +00:00 · 2025-11-20 09:51:50 +00:00 · 2025-11-20 17:40:30 +08:00 · 2025-11-20 17:40:11 +08:00 · 2025-11-20 09:35:45 +00:00
17 changed files with 4695 additions and 165 deletions
--- a/.claude/commands/memory/docs.md
+++ b/.claude/commands/memory/docs.md
@@ -89,7 +89,7 @@ bash(if [ -d .workflow/docs/\${project_name} ]; then find .workflow/docs/\${proj
 bash(if [ -d .workflow/docs/\${project_name} ]; then find .workflow/docs/\${project_name} -type f -name "*.md" ! -path "*/README.md" ! -path "*/ARCHITECTURE.md" ! -path "*/EXAMPLES.md" ! -path "*/api/*" 2>/dev/null | xargs cat 2>/dev/null; fi)
 ```

-**Data Processing**: Parse bash outputs, calculate statistics, use **Write tool** to create `${session_dir}/.process/phase2-analysis.json` with structure:
+**Data Processing**: Parse bash outputs, calculate statistics, use **Write tool** to create `${session_dir}/.process/doc-planning-data.json` with structure:

 ```json
 {
@@ -118,7 +118,7 @@ bash(if [ -d .workflow/docs/\${project_name} ]; then find .workflow/docs/\${proj

 **Then** use **Edit tool** to update `workflow-session.json` adding analysis field.

-**Output**: Single `phase2-analysis.json` with all analysis data (no temp files or Python scripts).
+**Output**: Single `doc-planning-data.json` with all analysis data (no temp files or Python scripts).

 **Auto-skipped**: Tests (`**/test/**`, `**/*.test.*`), Build (`**/node_modules/**`, `**/dist/**`), Config (root-level files), Vendor directories.

@@ -127,8 +127,8 @@ bash(if [ -d .workflow/docs/\${project_name} ]; then find .workflow/docs/\${proj
 **Commands**:

 ```bash
-# Count existing docs from phase2-analysis.json
-bash(cat .workflow/active/WFS-docs-{timestamp}/.process/phase2-analysis.json | jq '.existing_docs.file_list | length')
+# Count existing docs from doc-planning-data.json
+bash(cat .workflow/active/WFS-docs-{timestamp}/.process/doc-planning-data.json | jq '.existing_docs.file_list | length')
 ```

 **Data Processing**: Use count result, then use **Edit tool** to update `workflow-session.json`:
@@ -182,8 +182,8 @@ Large Projects (single dir >10 docs):
 **Commands**:

 ```bash
-# 1. Get top-level directories from phase2-analysis.json
-bash(cat .workflow/active/WFS-docs-{timestamp}/.process/phase2-analysis.json | jq -r '.top_level_dirs[]')
+# 1. Get top-level directories from doc-planning-data.json
+bash(cat .workflow/active/WFS-docs-{timestamp}/.process/doc-planning-data.json | jq -r '.top_level_dirs[]')

 # 2. Get mode from workflow-session.json
 bash(cat .workflow/active/WFS-docs-{timestamp}/workflow-session.json | jq -r '.mode // "full"')
@@ -201,7 +201,7 @@ bash(grep -r "router\.|@Get\|@Post" src/ 2>/dev/null && echo "API_FOUND" || echo
   - If total ≤10 docs: create group
   - If total >10 docs: split to 1 dir/group or subdivide
   - If single dir >10 docs: split by subdirectories
-3. Use **Edit tool** to update `phase2-analysis.json` adding groups field:
+3. Use **Edit tool** to update `doc-planning-data.json` adding groups field:
   ```json
   "groups": {
     "count": 3,
@@ -215,7 +215,7 @@ bash(grep -r "router\.|@Get\|@Post" src/ 2>/dev/null && echo "API_FOUND" || echo

 **Task ID Calculation**:
 ```bash
-group_count=$(jq '.groups.count' .workflow/active/WFS-docs-{timestamp}/.process/phase2-analysis.json)
+group_count=$(jq '.groups.count' .workflow/active/WFS-docs-{timestamp}/.process/doc-planning-data.json)
 readme_id=$((group_count + 1))   # Next ID after groups
 arch_id=$((group_count + 2))
 api_id=$((group_count + 3))
@@ -237,7 +237,7 @@ api_id=$((group_count + 3))

 **Generation Process**:
 1. Read configuration values (tool, cli_execute, mode) from workflow-session.json
-2. Read group assignments from phase2-analysis.json
+2. Read group assignments from doc-planning-data.json
 3. Generate Level 1 tasks (IMPL-001 to IMPL-N, one per group)
 4. Generate Level 2+ tasks if mode=full (README, ARCHITECTURE, HTTP API)

@@ -262,14 +262,14 @@ api_id=$((group_count + 3))
  },
  "context": {
    "requirements": [
-      "Process directories from group ${group_number} in phase2-analysis.json",
+      "Process directories from group ${group_number} in doc-planning-data.json",
      "Generate docs to .workflow/docs/${project_name}/ (mirrored structure)",
      "Code folders: API.md + README.md; Navigation folders: README.md only",
      "Use pre-analyzed data from Phase 2 (no redundant analysis)"
    ],
    "focus_paths": ["${group_dirs_from_json}"],
    "precomputed_data": {
-      "phase2_analysis": "${session_dir}/.process/phase2-analysis.json"
+      "phase2_analysis": "${session_dir}/.process/doc-planning-data.json"
    }
  },
  "flow_control": {
@@ -278,8 +278,8 @@ api_id=$((group_count + 3))
        "step": "load_precomputed_data",
        "action": "Load Phase 2 analysis and extract group directories",
        "commands": [
-          "bash(cat ${session_dir}/.process/phase2-analysis.json)",
-          "bash(jq '.groups.assignments[] | select(.group_id == \"${group_number}\") | .directories' ${session_dir}/.process/phase2-analysis.json)"
+          "bash(cat ${session_dir}/.process/doc-planning-data.json)",
+          "bash(jq '.groups.assignments[] | select(.group_id == \"${group_number}\") | .directories' ${session_dir}/.process/doc-planning-data.json)"
        ],
        "output_to": "phase2_context",
        "note": "Single JSON file contains all Phase 2 analysis results"
@@ -324,7 +324,7 @@ api_id=$((group_count + 3))
 {
  "step": 2,
  "title": "Batch generate documentation via CLI",
-  "command": "bash(dirs=$(jq -r '.groups.assignments[] | select(.group_id == \"${group_number}\") | .directories[]' ${session_dir}/.process/phase2-analysis.json); for dir in $dirs; do cd \"$dir\" && gemini --approval-mode yolo -p \"PURPOSE: Generate module docs\\nTASK: Create documentation\\nMODE: write\\nCONTEXT: @**/* [phase2_context]\\nEXPECTED: API.md and README.md\\nRULES: Mirror structure\" || echo \"Failed: $dir\"; cd -; done)",
+  "command": "bash(dirs=$(jq -r '.groups.assignments[] | select(.group_id == \"${group_number}\") | .directories[]' ${session_dir}/.process/doc-planning-data.json); for dir in $dirs; do cd \"$dir\" && gemini --approval-mode yolo -p \"PURPOSE: Generate module docs\\nTASK: Create documentation\\nMODE: write\\nCONTEXT: @**/* [phase2_context]\\nEXPECTED: API.md and README.md\\nRULES: Mirror structure\" || echo \"Failed: $dir\"; cd -; done)",
  "depends_on": [1],
  "output": "generated_docs"
 }
@@ -464,7 +464,7 @@ api_id=$((group_count + 3))
    ├── IMPL_PLAN.md
    ├── TODO_LIST.md
    ├── .process/
-    │   └── phase2-analysis.json         # All Phase 2 analysis data (replaces 7+ files)
+    │   └── doc-planning-data.json       # All Phase 2 analysis data (replaces 7+ files)
    └── .task/
        ├── IMPL-001.json                # Small: all modules | Large: group 1
        ├── IMPL-00N.json                # (Large only: groups 2-N)
@@ -473,7 +473,7 @@ api_id=$((group_count + 3))
        └── IMPL-{N+3}.json              # HTTP API (optional)
 ```

-**phase2-analysis.json Structure**:
+**doc-planning-data.json Structure**:
 ```json
 {
  "metadata": {
--- a/.claude/commands/workflow/tdd-plan.md
+++ b/.claude/commands/workflow/tdd-plan.md
@@ -417,110 +417,6 @@ Convert user input to TDD-structured format:
 - **Command failure**: Keep phase in_progress, report error
 - **TDD validation failure**: Report incomplete chains or wrong dependencies

-## TDD Workflow Enhancements
-
-### Overview
-The TDD workflow has been significantly enhanced by integrating best practices from both traditional `plan --agent` and `test-gen` workflows, creating a hybrid approach that bridges the gap between idealized TDD and real-world development complexity.
-
-### Key Improvements
-
-#### 1. Test Coverage Analysis (Phase 3)
-**Adopted from test-gen workflow**
-
-Before planning TDD tasks, the workflow now analyzes the existing codebase:
- Detects existing test patterns and conventions
- Identifies current test coverage
- Discovers related components and integration points
- Detects test framework automatically
-
-**Benefits**:
- Context-aware TDD planning
- Avoids duplicate test creation
- Enables integration with existing tests
- No longer assumes greenfield scenarios
-
-#### 2. Iterative Green Phase with Test-Fix Cycle
-**Adopted from test-gen workflow**
-
-IMPL (Green phase) tasks now include automatic test-fix cycle for resilient implementation:
-
-**Enhanced IMPL Task Flow**:
-```
-1. Write minimal implementation code
-2. Execute test suite
-3. IF tests pass → Complete task
-4. IF tests fail → Enter fix cycle:
-   a. Gemini diagnoses with bug-fix template
-   b. Apply fix (manual or Codex)
-   c. Retest
-   d. Repeat (max 3 iterations)
-5. IF max iterations → Auto-revert changes 🔄
-```
-
-**Benefits**:
- Faster feedback within Green phase
- Autonomous recovery from implementation errors
- Systematic debugging with Gemini
- Safe rollback prevents broken state
-
-#### 3. Agent-Driven Planning
-**From plan --agent workflow**
-
-Supports action-planning-agent for more autonomous TDD planning with:
- MCP tool integration (code-index, exa)
- Memory-first principles
- Brainstorming artifact integration
- Task merging over decomposition
-
-### Workflow Comparison
-
-| Aspect | Previous | Current (Optimized) |
-|--------|----------|---------------------|
-| **Phases** | 6 (with test coverage) | 7 (added concept verification) |
-| **Context** | Greenfield assumption | Existing codebase aware |
-| **Task Structure** | 1 feature = 3 tasks (TEST/IMPL/REFACTOR) | 1 feature = 1 task (internal TDD cycle) |
-| **Task Count** | 5 features = 15 tasks | 5 features = 5 tasks (70% reduction) |
-| **Green Phase** | Single implementation | Iterative with fix cycle |
-| **Failure Handling** | Manual intervention | Auto-diagnose + fix + revert |
-| **Test Analysis** | None | Deep coverage analysis |
-| **Feedback Loop** | Post-execution | During Green phase |
-| **Task Management** | High overhead (15 tasks) | Low overhead (5 tasks) |
-| **Execution Efficiency** | Frequent context switching | Continuous context per feature |
-
-### Migration Notes
-
-**Backward Compatibility**: Fully compatible
- Existing TDD workflows continue to work
- New features are additive, not breaking
- Phase 3 can be skipped if test-context-gather not available
-
-**Session Structure**:
-```
-.workflow/active/WFS-xxx/
-├── IMPL_PLAN.md (unified plan with TDD Implementation Tasks section)
-├── TODO_LIST.md (with internal TDD phase indicators)
-├── .process/
-│   ├── context-package.json
-│   ├── test-context-package.json
-│   ├── ANALYSIS_RESULTS.md (enhanced with TDD breakdown)
-│   └── green-fix-iteration-*.md (fix logs from Green phase cycles)
-└── .task/
-    ├── IMPL-1.json (Complete TDD task: Red-Green-Refactor internally)
-    ├── IMPL-2.json (Complete TDD task)
-    ├── IMPL-3.json (Complex feature container, if needed)
-    ├── IMPL-3.1.json (Complex feature subtask, if needed)
-    └── IMPL-3.2.json (Complex feature subtask, if needed)
-```
-
-**File Count Comparison**:
- **Old structure**: 5 features = 15 task files (TEST/IMPL/REFACTOR × 5)
- **New structure**: 5 features = 5 task files (IMPL-N × 5)
- **Complex features**: Add container + subtasks only when necessary
-
-**Configuration Options** (in IMPL tasks):
- `meta.max_iterations`: Fix attempts (default: 3)
- `meta.use_codex`: Auto-fix mode (default: false)
-
 ## Related Commands

 **Prerequisite Commands**:
--- a/.claude/skills/command-guide/reference/commands/memory/docs.md
+++ b/.claude/skills/command-guide/reference/commands/memory/docs.md
@@ -89,7 +89,7 @@ bash(if [ -d .workflow/docs/\${project_name} ]; then find .workflow/docs/\${proj
 bash(if [ -d .workflow/docs/\${project_name} ]; then find .workflow/docs/\${project_name} -type f -name "*.md" ! -path "*/README.md" ! -path "*/ARCHITECTURE.md" ! -path "*/EXAMPLES.md" ! -path "*/api/*" 2>/dev/null | xargs cat 2>/dev/null; fi)
 ```

-**Data Processing**: Parse bash outputs, calculate statistics, use **Write tool** to create `${session_dir}/.process/phase2-analysis.json` with structure:
+**Data Processing**: Parse bash outputs, calculate statistics, use **Write tool** to create `${session_dir}/.process/doc-planning-data.json` with structure:

 ```json
 {
@@ -118,7 +118,7 @@ bash(if [ -d .workflow/docs/\${project_name} ]; then find .workflow/docs/\${proj

 **Then** use **Edit tool** to update `workflow-session.json` adding analysis field.

-**Output**: Single `phase2-analysis.json` with all analysis data (no temp files or Python scripts).
+**Output**: Single `doc-planning-data.json` with all analysis data (no temp files or Python scripts).

 **Auto-skipped**: Tests (`**/test/**`, `**/*.test.*`), Build (`**/node_modules/**`, `**/dist/**`), Config (root-level files), Vendor directories.

@@ -127,8 +127,8 @@ bash(if [ -d .workflow/docs/\${project_name} ]; then find .workflow/docs/\${proj
 **Commands**:

 ```bash
-# Count existing docs from phase2-analysis.json
-bash(cat .workflow/WFS-docs-{timestamp}/.process/phase2-analysis.json | jq '.existing_docs.file_list | length')
+# Count existing docs from doc-planning-data.json
+bash(cat .workflow/WFS-docs-{timestamp}/.process/doc-planning-data.json | jq '.existing_docs.file_list | length')
 ```

 **Data Processing**: Use count result, then use **Edit tool** to update `workflow-session.json`:
@@ -182,8 +182,8 @@ Large Projects (single dir >10 docs):
 **Commands**:

 ```bash
-# 1. Get top-level directories from phase2-analysis.json
-bash(cat .workflow/WFS-docs-{timestamp}/.process/phase2-analysis.json | jq -r '.top_level_dirs[]')
+# 1. Get top-level directories from doc-planning-data.json
+bash(cat .workflow/WFS-docs-{timestamp}/.process/doc-planning-data.json | jq -r '.top_level_dirs[]')

 # 2. Get mode from workflow-session.json
 bash(cat .workflow/WFS-docs-{timestamp}/workflow-session.json | jq -r '.mode // "full"')
@@ -201,7 +201,7 @@ bash(grep -r "router\.|@Get\|@Post" src/ 2>/dev/null && echo "API_FOUND" || echo
   - If total ≤10 docs: create group
   - If total >10 docs: split to 1 dir/group or subdivide
   - If single dir >10 docs: split by subdirectories
-3. Use **Edit tool** to update `phase2-analysis.json` adding groups field:
+3. Use **Edit tool** to update `doc-planning-data.json` adding groups field:
   ```json
   "groups": {
     "count": 3,
@@ -215,7 +215,7 @@ bash(grep -r "router\.|@Get\|@Post" src/ 2>/dev/null && echo "API_FOUND" || echo

 **Task ID Calculation**:
 ```bash
-group_count=$(jq '.groups.count' .workflow/WFS-docs-{timestamp}/.process/phase2-analysis.json)
+group_count=$(jq '.groups.count' .workflow/WFS-docs-{timestamp}/.process/doc-planning-data.json)
 readme_id=$((group_count + 1))   # Next ID after groups
 arch_id=$((group_count + 2))
 api_id=$((group_count + 3))
@@ -237,7 +237,7 @@ api_id=$((group_count + 3))

 **Generation Process**:
 1. Read configuration values (tool, cli_execute, mode) from workflow-session.json
-2. Read group assignments from phase2-analysis.json
+2. Read group assignments from doc-planning-data.json
 3. Generate Level 1 tasks (IMPL-001 to IMPL-N, one per group)
 4. Generate Level 2+ tasks if mode=full (README, ARCHITECTURE, HTTP API)

@@ -262,14 +262,14 @@ api_id=$((group_count + 3))
  },
  "context": {
    "requirements": [
-      "Process directories from group ${group_number} in phase2-analysis.json",
+      "Process directories from group ${group_number} in doc-planning-data.json",
      "Generate docs to .workflow/docs/${project_name}/ (mirrored structure)",
      "Code folders: API.md + README.md; Navigation folders: README.md only",
      "Use pre-analyzed data from Phase 2 (no redundant analysis)"
    ],
    "focus_paths": ["${group_dirs_from_json}"],
    "precomputed_data": {
-      "phase2_analysis": "${session_dir}/.process/phase2-analysis.json"
+      "phase2_analysis": "${session_dir}/.process/doc-planning-data.json"
    }
  },
  "flow_control": {
@@ -278,8 +278,8 @@ api_id=$((group_count + 3))
        "step": "load_precomputed_data",
        "action": "Load Phase 2 analysis and extract group directories",
        "commands": [
-          "bash(cat ${session_dir}/.process/phase2-analysis.json)",
-          "bash(jq '.groups.assignments[] | select(.group_id == \"${group_number}\") | .directories' ${session_dir}/.process/phase2-analysis.json)"
+          "bash(cat ${session_dir}/.process/doc-planning-data.json)",
+          "bash(jq '.groups.assignments[] | select(.group_id == \"${group_number}\") | .directories' ${session_dir}/.process/doc-planning-data.json)"
        ],
        "output_to": "phase2_context",
        "note": "Single JSON file contains all Phase 2 analysis results"
@@ -324,7 +324,7 @@ api_id=$((group_count + 3))
 {
  "step": 2,
  "title": "Batch generate documentation via CLI",
-  "command": "bash(dirs=$(jq -r '.groups.assignments[] | select(.group_id == \"${group_number}\") | .directories[]' ${session_dir}/.process/phase2-analysis.json); for dir in $dirs; do cd \"$dir\" && gemini --approval-mode yolo -p \"PURPOSE: Generate module docs\\nTASK: Create documentation\\nMODE: write\\nCONTEXT: @**/* [phase2_context]\\nEXPECTED: API.md and README.md\\nRULES: Mirror structure\" || echo \"Failed: $dir\"; cd -; done)",
+  "command": "bash(dirs=$(jq -r '.groups.assignments[] | select(.group_id == \"${group_number}\") | .directories[]' ${session_dir}/.process/doc-planning-data.json); for dir in $dirs; do cd \"$dir\" && gemini --approval-mode yolo -p \"PURPOSE: Generate module docs\\nTASK: Create documentation\\nMODE: write\\nCONTEXT: @**/* [phase2_context]\\nEXPECTED: API.md and README.md\\nRULES: Mirror structure\" || echo \"Failed: $dir\"; cd -; done)",
  "depends_on": [1],
  "output": "generated_docs"
 }
@@ -464,7 +464,7 @@ api_id=$((group_count + 3))
    ├── IMPL_PLAN.md
    ├── TODO_LIST.md
    ├── .process/
-    │   └── phase2-analysis.json         # All Phase 2 analysis data (replaces 7+ files)
+    │   └── doc-planning-data.json         # All Phase 2 analysis data (replaces 7+ files)
    └── .task/
        ├── IMPL-001.json                # Small: all modules | Large: group 1
        ├── IMPL-00N.json                # (Large only: groups 2-N)
@@ -473,7 +473,7 @@ api_id=$((group_count + 3))
        └── IMPL-{N+3}.json              # HTTP API (optional)
 ```

-**phase2-analysis.json Structure**:
+**doc-planning-data.json Structure**:
 ```json
 {
  "metadata": {
--- 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_DOCS_AUDIT_REPORT.md
+++ b/COMMAND_DOCS_AUDIT_REPORT.md
@@ -0,0 +1,278 @@
+# 命令文档审计报告
+
+**审计日期**: 2025-11-20
+**审计范围**: 73个命令文档文件
+**审计方法**: 自动化扫描 + 手动内容分析
+
+---
+
+## 发现的问题
+
+### 1. 包含版本信息的文件
+
+#### [CRITICAL] version.md
+**文件路径**: `/home/user/Claude-Code-Workflow/.claude/commands/version.md`
+
+**问题位置**:
+- 第1-3行：包含在YAML头中
+- 第96-102行：示例中包含完整版本号和发布日期（如"v3.2.2"、"2025-10-03"）
+- 第127-130行：包含开发版本号和日期
+- 第155-172行：版本比较和升级建议
+
+**内容摘要**:
+```
+Latest Stable: v3.2.2
+Release: v3.2.2: Independent Test-Gen Workflow with Cross-Session Context
+Published: 2025-10-03T04:10:08Z
+
+Latest Dev: a03415b
+Message: feat: Add version tracking and upgrade check system
+Date: 2025-10-03T04:46:44Z
+```
+
+**严重程度**: ⚠️ 高 - 文件本质上是版本管理命令，但包含具体版本号、发布日期和完整版本历史
+
+---
+
+### 2. 包含额外无关内容的文件
+
+#### [HIGH] tdd-plan.md
+**文件路径**: `/home/user/Claude-Code-Workflow/.claude/commands/workflow/tdd-plan.md`
+
+**问题位置**: 第420-523行
+
+**部分内容**:
+```markdown
+## TDD Workflow Enhancements
+
+### Overview
+The TDD workflow has been significantly enhanced by integrating best practices
+from both traditional `plan --agent` and `test-gen` workflows...
+
+### Key Improvements
+
+#### 1. Test Coverage Analysis (Phase 3)
+**Adopted from test-gen workflow**
+
+#### 2. Iterative Green Phase with Test-Fix Cycle
+**Adopted from test-gen workflow**
+
+#### 3. Agent-Driven Planning
+**From plan --agent workflow**
+
+### Workflow Comparison
+| Aspect | Previous | Current (Optimized) |
+| **Task Count** | 5 features = 15 tasks | 5 features = 5 tasks (70% reduction) |
+| **Task Management** | High overhead (15 tasks) | Low overhead (5 tasks) |
+
+### Migration Notes
+**Backward Compatibility**: Fully compatible
+- Existing TDD workflows continue to work
+- New features are additive, not breaking
+```
+
+**问题分析**:
+- 包含"增强"、"改进"、"演进"等版本历史相关内容
+- 包含"工作流比较"部分，对比了"之前"和"现在"的版本
+- 包含"迁移说明"，描述了从旧版本的升级路径
+- 约100行内容（第420-523行）不是关于命令如何使用，而是关于如何改进的
+
+**严重程度**: ⚠️ 中-高 - 约18%的文件内容（100/543行）是版本演进相关，而不是核心功能说明
+
+---
+
+### 3. 任务不够专注的文件
+
+#### [MEDIUM] tdd-plan.md (继续)
+**问题**: 文件中包含过多关于与其他命令（plan、test-gen）集成的说明
+
+**相关部分**:
+- 第475-488行：与"plan --agent"工作流的比较
+- 第427-441行：描述从test-gen工作流"采纳"的特性
+- 第466-473行：描述从plan --agent工作流"采纳"的特性
+
+**问题分析**: 虽然这些集成说明可能有用，但在命令文档中过度强调其他命令的关系，使文档的焦点分散。建议这类内容应放在项目级文档或架构文档中，而不是在具体命令文档中。
+
+**严重程度**: ⚠️ 中 - 降低了文档的焦点，但不是严重问题
+
+---
+
+## 合规文件统计
+
+### 审计结果汇总
+
+| 类别 | 计数 | 百分比 |
+|------|------|--------|
+| **完全合规的文件** | 70 | 95.9% |
+| **有版本信息的文件** | 1 | 1.4% |
+| **包含额外无关内容的文件** | 1 | 1.4% |
+| **任务不够专注的文件** | 1* | 1.4% |
+| **总计** | 73 | 100% |
+
+*注: tdd-plan.md 同时出现在"额外无关内容"和"任务不专注"两个类别中
+
+### 问题严重程度分布
+
+| 严重程度 | 文件数 | 说明 |
+|---------|--------|------|
+| CRITICAL | 0 | 没有需要立即阻止执行的问题 |
+| HIGH | 1 | version.md - 包含完整版本号和发布信息 |
+| MEDIUM | 1 | tdd-plan.md - 包含过度的版本演进说明和工作流对比 |
+| LOW | 0 | 无其他问题 |
+
+---
+
+## 详细发现
+
+### version.md - 完整分析
+
+**问题本质**: version.md命令的存在目的就是管理和报告版本信息。文件中包含版本号、发布日期、更新日志等内容不仅是合理的，而是必需的。
+
+**但审计角度**: 根据用户的审计标准：
+- ✓ "包含版本号、版本历史、changelog等内容" - **是的，明确包含**
+  - 示例版本号: v3.2.1, v3.2.2, 3.4.0-dev
+  - 发布日期: 2025-10-03T12:00:00Z
+  - 版本历史信息和升级路径
+
+**结论**: 该文件符合审计标准中的"版本信息"类别，应被标记为有问题（尽管这是功能需求）
+
+---
+
+### tdd-plan.md - 完整分析
+
+**第一个问题 - 额外的版本演进信息**:
+```
+## TDD Workflow Enhancements (行420)
+### Overview
+The TDD workflow has been **significantly enhanced** by integrating best practices
+from **both traditional `plan --agent` and `test-gen` workflows**
+
+### Key Improvements
+#### 1. Test Coverage Analysis (Phase 3)
+**Adopted from test-gen workflow** (行428)
+
+#### 2. Iterative Green Phase with Test-Fix Cycle
+**Adopted from test-gen workflow** (行443)
+
+#### 3. Agent-Driven Planning
+**From plan --agent workflow** (行467)
+```
+
+这部分内容完全是关于命令的历史演变和改进，不是关于如何使用该命令。
+
+**第二个问题 - 工作流对比表**:
+```
+### Workflow Comparison (行475)
+| Aspect | Previous | Current (Optimized) |
+| **Phases** | 6 | 7 |
+| **Task Count** | 5 features = 15 tasks | 5 features = 5 tasks (70% reduction) |
+```
+
+直接对比了"之前"和"现在"的实现，这是版本历史相关内容。
+
+**第三个问题 - 迁移说明**:
+```
+### Migration Notes (行490)
+**Backward Compatibility**: Fully compatible
+- Existing TDD workflows continue to work
+- New features are additive, not breaking
+```
+
+这是版本升级路径说明，不是命令核心功能文档的一部分。
+
+**统计**:
+- 总行数: 543行
+- 有问题的行: ~103行（第420-523行）
+- 占比: ~19%
+
+**结论**: tdd-plan.md 同时违反了两个审计标准：
+1. 包含版本演进历史相关内容
+2. 过度描述与其他命令的关系（缺乏任务专注度）
+
+---
+
+## 建议
+
+### 高优先级
+
+1. **移除 version.md 中的具体版本号**
+   - 当前做法: 包含硬编码的版本号、日期等
+   - 建议: 使用变量或运行时获取版本信息，文档中只描述版本命令的功能
+   - 理由: 版本号应该由版本控制系统管理，而不是在文档中硬编码
+
+2. **从 tdd-plan.md 中移除第420-523行（版本演进部分）**
+   - 当前: ~103行关于"增强"、"改进"、"迁移"的内容
+   - 建议: 移到单独的"CHANGELOG.md"或项目级文档
+   - 理由: 这是历史演变信息，不是使用指南
+
+### 中优先级
+
+3. **重构 tdd-plan.md 中的工作流关系**
+   - 当前: 第475-495行详细对比与其他命令的区别
+   - 建议: 简化对其他命令的引用，保留"Related Commands"部分即可
+   - 理由: 过度关注与其他命令的关系分散了文档焦点
+
+4. **统一版本信息管理策略**
+   - 建议: 建立项目级文档规范，明确哪些信息应在命令文档中出现
+   - 范围: 适用于所有命令文档
+
+---
+
+## 合规性评定
+
+### 总体评分: 96/100
+
+- ✓ **整体质量高**: 95.9%的文件完全合规
+- ⚠️ **两个文件需要整改**:
+  - version.md: 版本信息管理需要优化
+  - tdd-plan.md: 版本演进内容需要分离
+
+### 推荐行动
+
+| 优先级 | 行动 | 预期影响 |
+|--------|------|---------|
+| **高** | 清理 version.md 的硬编码版本号 | 提高版本管理的可维护性 |
+| **高** | 从 tdd-plan.md 移除第420-523行 | 提高文档专注度，减少19% |
+| **中** | 建立版本信息管理规范 | 防止未来重复问题 |
+| **低** | 简化 tdd-plan.md 中的工作流关系说明 | 进一步改善文档清晰度 |
+
+---
+
+## 附录
+
+### 审计方法论
+
+1. **自动扫描**: 使用grep搜索关键词（version, changelog, release, history等）
+2. **内容分析**: 手动读取匹配文件的完整内容
+3. **结构分析**: 检查是否包含与核心功能无关的内容
+4. **统计分析**: 计算问题内容占比
+
+### 数据来源
+
+- 总文件数: 73
+- 详细分析文件: 15
+- 快速扫描文件: 58
+
+### 文件列表（完整性检查）
+
+已审计的所有命令文档:
+- ✓ version.md (有问题)
+- ✓ enhance-prompt.md
+- ✓ test-fix-gen.md
+- ✓ test-gen.md
+- ✓ test-cycle-execute.md
+- ✓ tdd-plan.md (有问题)
+- ✓ tdd-verify.md
+- ✓ status.md
+- ✓ review.md
+- ✓ plan.md
+- ✓ lite-plan.md
+- ✓ lite-execute.md
+- ✓ init.md
+- ✓ execute.md
+- ✓ action-plan-verify.md
+- ... 以及其他58个文件 (全部合规)
+
+---
+
+**审计完成** - 生成时间: 2025-11-20
--- 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. |

--- 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/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,713 @@
+# 🌳 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
+```
+
+---
+
+### 7️⃣ **CLI 工具协作模式 - 多模型智能协同**
+
+本项目集成了三种 CLI 工具，支持灵活的串联、并行和混合执行方式：
+
+| 工具 | 核心能力 | 上下文长度 | 适用场景 |
+|------|---------|-----------|---------|
+| **Gemini** | 深度分析、架构设计、规划 | 超长上下文 | 代码理解、执行流追踪、技术方案评估 |
+| **Qwen** | 代码审查、模式识别 | 超长上下文 | Gemini 备选、多维度分析 |
+| **Codex** | 精确代码撰写、Bug定位 | 标准上下文 | 功能实现、测试生成、代码重构 |
+
+#### 📋 三种执行模式
+
+**1. 串联执行（Serial Execution）** - 顺序依赖
+
+适用场景：后续任务依赖前一任务的结果
+
+```bash
+# 示例：分析后实现
+# Step 1: Gemini 分析架构
+使用 gemini 分析认证模块的架构设计，识别关键组件和数据流
+
+# Step 2: Codex 基于分析结果实现
+让 codex 根据上述架构分析，实现 JWT 认证中间件
+```
+
+**执行流程**：
+```
+Gemini 分析 → 输出架构报告 → Codex 读取报告 → 实现代码
+```
+
+---
+
+**2. 并行执行（Parallel Execution）** - 同时进行
+
+适用场景：多个独立任务，无依赖关系
+
+```bash
+# 示例：多维度分析
+用 gemini 分析认证模块的安全性，关注 JWT、密码存储、会话管理
+用 qwen 分析认证模块的性能瓶颈，识别慢查询和优化点
+让 codex 为认证模块生成单元测试，覆盖所有核心功能
+```
+
+**执行流程**：
+```
+        ┌─ Gemini: 安全分析 ─┐
+并行 ───┼─ Qwen: 性能分析 ──┼─→ 汇总结果
+        └─ Codex: 测试生成 ─┘
+```
+
+---
+
+**3. 混合执行（Hybrid Execution）** - 串并结合
+
+适用场景：复杂任务，部分并行、部分串联
+
+```bash
+# 示例：完整功能开发
+# Phase 1: 并行分析（独立任务）
+使用 gemini 分析现有认证系统的架构模式
+用 qwen 评估 OAuth2 集成的技术方案
+
+# Phase 2: 串联实现（依赖 Phase 1）
+让 codex 基于上述分析，实现 OAuth2 认证流程
+
+# Phase 3: 并行优化（独立任务）
+用 gemini 审查代码质量和安全性
+让 codex 生成集成测试
+```
+
+**执行流程**：
+```
+Phase 1: Gemini 分析 ──┐
+         Qwen 评估 ────┼─→ Phase 2: Codex 实现 ──→ Phase 3: Gemini 审查 ──┐
+                       │                                    Codex 测试 ──┼─→ 完成
+                       └────────────────────────────────────────────────┘
+```
+
+---
+
+#### 🎯 语义调用 vs 命令调用
+
+**方式一：自然语言语义调用**（推荐）
+
+```bash
+# 用户只需自然描述，Claude Code 自动调用工具
+"使用 gemini 分析这个模块的依赖关系"
+→ Claude Code 自动生成：cd src && gemini -p "分析依赖关系"
+
+"让 codex 实现用户注册功能"
+→ Claude Code 自动生成：codex -C src/auth --full-auto exec "实现注册"
+```
+
+**方式二：直接命令调用**
+
+```bash
+# 通过 Slash 命令精准调用
+/cli:chat --tool gemini "解释这个算法"
+/cli:analyze --tool qwen "分析性能瓶颈"
+/cli:execute --tool codex "优化查询性能"
+```
+
+---
+
+#### 🔗 CLI 结果作为上下文（Memory）
+
+CLI 工具的分析结果可以被保存并作为后续操作的上下文（memory），实现智能化的工作流程：
+
+**1. 结果持久化**
+
+```bash
+# CLI 执行结果自动保存到会话目录
+/cli:chat --tool gemini "分析认证模块架构"
+→ 保存到：.workflow/active/WFS-xxx/.chat/chat-[timestamp].md
+
+/cli:analyze --tool qwen "评估性能瓶颈"
+→ 保存到：.workflow/active/WFS-xxx/.chat/analyze-[timestamp].md
+
+/cli:execute --tool codex "实现功能"
+→ 保存到：.workflow/active/WFS-xxx/.chat/execute-[timestamp].md
+```
+
+**2. 结果作为规划依据**
+
+```bash
+# Step 1: 分析现状（生成 memory）
+使用 gemini 深度分析认证系统的架构、安全性和性能问题
+→ 输出：详细分析报告（自动保存）
+
+# Step 2: 基于分析结果规划
+/workflow:plan "根据上述 Gemini 分析报告重构认证系统"
+→ 系统自动读取 .chat/ 中的分析报告作为上下文
+→ 生成精准的实施计划
+```
+
+**3. 结果作为实现依据**
+
+```bash
+# Step 1: 并行分析（生成多个 memory）
+使用 gemini 分析现有代码结构
+用 qwen 评估技术方案可行性
+→ 输出：多份分析报告
+
+# Step 2: 基于所有分析结果实现
+让 codex 综合上述 Gemini 和 Qwen 的分析，实现最优方案
+→ Codex 自动读取前序分析结果
+→ 生成符合架构设计的代码
+```
+
+**4. 跨会话引用**
+
+```bash
+# 引用历史会话的分析结果
+/cli:execute --tool codex "参考 WFS-2024-001 中的架构分析，实现新的支付模块"
+→ 系统自动加载指定会话的上下文
+→ 基于历史分析进行实现
+```
+
+**5. Memory 更新循环**
+
+```bash
+# 迭代优化流程
+使用 gemini 分析当前实现的问题
+→ 生成问题报告（memory）
+
+让 codex 根据问题报告优化代码
+→ 实现改进（更新 memory）
+
+用 qwen 验证优化效果
+→ 验证报告（追加 memory）
+
+# 所有结果累积为完整的项目 memory
+→ 支持后续决策和实现
+```
+
+**Memory 流转示例**：
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Phase 1: 分析阶段（生成 Memory）                             │
+├─────────────────────────────────────────────────────────────┤
+│  Gemini 分析  →  架构分析报告 (.chat/analyze-001.md)          │
+│  Qwen 评估    →  方案评估报告 (.chat/analyze-002.md)          │
+└─────────────────────┬───────────────────────────────────────┘
+                      │ 作为 Memory 输入
+                      ↓
+┌─────────────────────────────────────────────────────────────┐
+│  Phase 2: 规划阶段（使用 Memory）                             │
+├─────────────────────────────────────────────────────────────┤
+│  /workflow:plan  →  读取分析报告  →  生成实施计划             │
+│                     (.task/IMPL-*.json)                      │
+└─────────────────────┬───────────────────────────────────────┘
+                      │ 作为 Memory 输入
+                      ↓
+┌─────────────────────────────────────────────────────────────┐
+│  Phase 3: 实现阶段（使用 Memory）                             │
+├─────────────────────────────────────────────────────────────┤
+│  Codex 实现   →  读取计划+分析  →  生成代码                   │
+│                     (.chat/execute-001.md)                   │
+└─────────────────────┬───────────────────────────────────────┘
+                      │ 作为 Memory 输入
+                      ↓
+┌─────────────────────────────────────────────────────────────┐
+│  Phase 4: 验证阶段（使用 Memory）                             │
+├─────────────────────────────────────────────────────────────┤
+│  Gemini 审查  →  读取实现代码  →  质量报告                    │
+│                     (.chat/review-001.md)                    │
+└─────────────────────────────────────────────────────────────┘
+                      │
+                      ↓
+            完整的项目 Memory 库
+          支持未来所有决策和实现
+```
+
+**最佳实践**：
+
+1. **保持连续性**：在同一会话中执行相关任务，自动共享 memory
+2. **显式引用**：跨会话时明确引用历史分析（如"参考 WFS-xxx 的分析"）
+3. **增量更新**：每次分析和实现都追加到 memory，形成完整的决策链
+4. **定期整理**：使用 `/memory:update-related` 将 CLI 结果整合到 CLAUDE.md
+5. **质量优先**：高质量的分析 memory 能显著提升后续实现质量
+
+---
+
+#### 🔄 工作流集成示例
+
+**集成到 Lite 工作流**：
+
+```bash
+# 1. 规划阶段：Gemini 分析
+/workflow:lite-plan -e "重构支付模块"
+→ 三维确认选择 "CLI 工具执行"
+
+# 2. 执行阶段：选择执行方式
+# 选项 A: 串联执行
+→ "使用 gemini 分析支付流程" → "让 codex 重构代码"
+
+# 选项 B: 并行分析 + 串联实现
+→ "用 gemini 分析架构" + "用 qwen 评估方案"
+→ "让 codex 基于分析结果重构"
+```
+
+**集成到 Full 工作流**：
+
+```bash
+# 1. 规划阶段
+/workflow:plan "实现分布式缓存"
+/workflow:action-plan-verify
+
+# 2. 分析阶段（并行）
+使用 gemini 分析现有缓存架构
+用 qwen 评估 Redis 集群方案
+
+# 3. 实现阶段（串联）
+/workflow:execute  # 或使用 CLI
+让 codex 实现 Redis 集群集成
+
+# 4. 测试阶段（并行）
+/workflow:test-gen WFS-cache
+→ 内部使用 gemini 分析 + codex 生成测试
+
+# 5. 审查阶段（串联）
+用 gemini 审查代码质量
+/workflow:review --type architecture
+```
+
+---
+
+#### 💡 最佳实践
+
+**何时使用串联**：
+- 实现依赖设计方案
+- 测试依赖代码实现
+- 优化依赖性能分析
+
+**何时使用并行**：
+- 多维度分析（安全+性能+架构）
+- 多模块独立开发
+- 同时生成代码和测试
+
+**何时使用混合**：
+- 复杂功能开发（分析→设计→实现→测试）
+- 大规模重构（评估→规划→执行→验证）
+- 技术栈迁移（调研→方案→实施→优化）
+
+**工具选择建议**：
+1. **需要理解代码** → Gemini（首选）或 Qwen
+2. **需要编写代码** → Codex
+3. **复杂分析** → Gemini + Qwen 并行（互补验证）
+4. **精确实现** → Codex（基于 Gemini 分析）
+5. **快速原型** → 直接使用 Codex
+
+---
+
+## 🔄 典型场景完整流程
+
+### 场景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
--- a/WORKFLOW_DECISION_GUIDE_EN.md
+++ b/WORKFLOW_DECISION_GUIDE_EN.md
@@ -0,0 +1,713 @@
+# 🌳 CCW Workflow Decision Guide
+
+This guide helps you choose the right commands and workflows for the complete software development lifecycle.
+
+---
+
+## 📊 Full Lifecycle Command Selection Flowchart
+
+```mermaid
+flowchart TD
+    Start([Start New Feature/Project]) --> Q1{Know what to build?}
+
+    Q1 -->|No| Ideation[💡 Ideation Phase<br>Requirements Exploration]
+    Q1 -->|Yes| Q2{Know how to build?}
+
+    Ideation --> BrainIdea[/ /workflow:brainstorm:auto-parallel<br>Explore product direction and positioning /]
+    BrainIdea --> Q2
+
+    Q2 -->|No| Design[🏗️ Design Exploration<br>Architecture Solution Discovery]
+    Q2 -->|Yes| Q3{Need UI design?}
+
+    Design --> BrainDesign[/ /workflow:brainstorm:auto-parallel<br>Explore technical solutions and architecture /]
+    BrainDesign --> Q3
+
+    Q3 -->|Yes| UIDesign[🎨 UI Design Phase]
+    Q3 -->|No| Q4{Task complexity?}
+
+    UIDesign --> Q3a{Have reference design?}
+    Q3a -->|Yes| UIImitate[/ /workflow:ui-design:imitate-auto<br>--input reference URL /]
+    Q3a -->|No| UIExplore[/ /workflow:ui-design:explore-auto<br>--prompt design description /]
+
+    UIImitate --> UISync[/ /workflow:ui-design:design-sync<br>Sync design system /]
+    UIExplore --> UISync
+    UISync --> Q4
+
+    Q4 -->|Simple & Quick| LitePlan[⚡ Lightweight Planning<br>/workflow:lite-plan]
+    Q4 -->|Complex & Complete| FullPlan[📋 Full Planning<br>/workflow:plan]
+
+    LitePlan --> Q5{Need code exploration?}
+    Q5 -->|Yes| LitePlanE[/ /workflow:lite-plan -e<br>task description /]
+    Q5 -->|No| LitePlanNormal[/ /workflow:lite-plan<br>task description /]
+
+    LitePlanE --> LiteConfirm[Three-Dimensional Confirmation:<br>1️⃣ Task Approval<br>2️⃣ Execution Method<br>3️⃣ Code Review]
+    LitePlanNormal --> LiteConfirm
+
+    LiteConfirm --> Q6{Choose execution method}
+    Q6 -->|Agent| LiteAgent[/ /workflow:lite-execute<br>Using @code-developer /]
+    Q6 -->|CLI Tools| LiteCLI[CLI Execution<br>Gemini/Qwen/Codex]
+    Q6 -->|Plan Only| UserImpl[Manual User Implementation]
+
+    FullPlan --> PlanVerify{Verify plan quality?}
+    PlanVerify -->|Yes| Verify[/ /workflow:action-plan-verify /]
+    PlanVerify -->|No| Execute
+    Verify --> Q7{Verification passed?}
+    Q7 -->|No| FixPlan[Fix plan issues]
+    Q7 -->|Yes| Execute
+    FixPlan --> Execute
+
+    Execute[🚀 Execution Phase<br>/workflow:execute]
+    LiteAgent --> TestDecision
+    LiteCLI --> TestDecision
+    UserImpl --> TestDecision
+    Execute --> TestDecision
+
+    TestDecision{Need testing?}
+    TestDecision -->|TDD Mode| TDD[/ /workflow:tdd-plan<br>Test-Driven Development /]
+    TestDecision -->|Post-Implementation Testing| TestGen[/ /workflow:test-gen<br>Generate tests /]
+    TestDecision -->|Existing Tests| TestCycle[/ /workflow:test-cycle-execute<br>Test-fix cycle /]
+    TestDecision -->|No| Review
+
+    TDD --> TDDExecute[/ /workflow:execute<br>Red-Green-Refactor /]
+    TDDExecute --> TDDVerify[/ /workflow:tdd-verify<br>Verify TDD compliance /]
+    TDDVerify --> Review
+
+    TestGen --> TestExecute[/ /workflow:execute<br>Execute test tasks /]
+    TestExecute --> TestResult{Tests passed?}
+    TestResult -->|No| TestCycle
+    TestResult -->|Yes| Review
+
+    TestCycle --> TestPass{Pass rate ≥95%?}
+    TestPass -->|No, continue fixing| TestCycle
+    TestPass -->|Yes| Review
+
+    Review[📝 Review Phase]
+    Review --> Q8{Need specialized review?}
+    Q8 -->|Security| SecurityReview[/ /workflow:review<br>--type security /]
+    Q8 -->|Architecture| ArchReview[/ /workflow:review<br>--type architecture /]
+    Q8 -->|Quality| QualityReview[/ /workflow:review<br>--type quality /]
+    Q8 -->|Comprehensive| GeneralReview[/ /workflow:review<br>Comprehensive review /]
+    Q8 -->|No| Complete
+
+    SecurityReview --> Complete
+    ArchReview --> Complete
+    QualityReview --> Complete
+    GeneralReview --> Complete
+
+    Complete[✅ Completion Phase<br>/workflow:session:complete]
+    Complete --> End([Project Complete])
+
+    style Start fill:#e1f5ff
+    style End fill:#c8e6c9
+    style BrainIdea fill:#fff9c4
+    style BrainDesign fill:#fff9c4
+    style UIImitate fill:#f8bbd0
+    style UIExplore fill:#f8bbd0
+    style LitePlan fill:#b3e5fc
+    style FullPlan fill:#b3e5fc
+    style Execute fill:#c5e1a5
+    style TDD fill:#ffccbc
+    style TestGen fill:#ffccbc
+    style TestCycle fill:#ffccbc
+    style Review fill:#d1c4e9
+    style Complete fill:#c8e6c9
+```
+
+---
+
+## 🎯 Decision Point Explanations
+
+### 1️⃣ **Ideation Phase - "Know what to build?"**
+
+| Situation | Command | Description |
+|-----------|---------|-------------|
+| ❌ Uncertain about product direction | `/workflow:brainstorm:auto-parallel "Explore XXX domain product opportunities"` | Multi-role analysis with Product Manager, UX Expert, etc. |
+| ✅ Clear feature requirements | Skip to design phase | Already know what functionality to build |
+
+**Examples**:
+```bash
+# Uncertain scenario: Want to build a collaboration tool, but unsure what exactly
+/workflow:brainstorm:auto-parallel "Explore team collaboration tool positioning and core features" --count 5
+
+# Certain scenario: Building a real-time document collaboration editor (requirements clear)
+# Skip ideation, move to design phase
+```
+
+---
+
+### 2️⃣ **Design Phase - "Know how to build?"**
+
+| Situation | Command | Description |
+|-----------|---------|-------------|
+| ❌ Don't know technical approach | `/workflow:brainstorm:auto-parallel "Design XXX system architecture"` | System Architect, Security Expert analyze technical solutions |
+| ✅ Clear implementation path | Skip to planning | Already know tech stack, architecture patterns |
+
+**Examples**:
+```bash
+# Don't know how: Real-time collaboration conflict resolution? Which algorithm?
+/workflow:brainstorm:auto-parallel "Design conflict resolution mechanism for real-time collaborative document editing" --count 4
+
+# Know how: Using Operational Transformation + WebSocket + Redis
+# Skip design exploration, go directly to planning
+/workflow:plan "Implement real-time collaborative editing using OT algorithm, WebSocket communication, Redis storage"
+```
+
+---
+
+### 3️⃣ **UI Design Phase - "Need UI design?"**
+
+| Situation | Command | Description |
+|-----------|---------|-------------|
+| 🎨 Have reference design | `/workflow:ui-design:imitate-auto --input "URL"` | Copy from existing design |
+| 🎨 Design from scratch | `/workflow:ui-design:explore-auto --prompt "description"` | Generate multiple design variants |
+| ⏭️ Backend/No UI | Skip | Pure backend API, CLI tools, etc. |
+
+**Examples**:
+```bash
+# Have reference: Imitate Google Docs collaboration interface
+/workflow:ui-design:imitate-auto --input "https://docs.google.com"
+
+# No reference: Design from scratch
+/workflow:ui-design:explore-auto --prompt "Modern minimalist document collaboration editing interface" --style-variants 3
+
+# Sync design to project
+/workflow:ui-design:design-sync --session WFS-xxx --selected-prototypes "v1,v2"
+```
+
+---
+
+### 4️⃣ **Planning Phase - Choose Workflow Type**
+
+| Workflow | Use Case | Characteristics |
+|----------|----------|-----------------|
+| `/workflow:lite-plan` | Quick tasks, small features | In-memory planning, three-dimensional confirmation, fast execution |
+| `/workflow:plan` | Complex projects, team collaboration | Persistent plans, quality gates, complete traceability |
+
+**Lite-Plan Three-Dimensional Confirmation**:
+1. **Task Approval**: Confirm / Modify / Cancel
+2. **Execution Method**: Agent / Provide Plan / CLI Tools (Gemini/Qwen/Codex)
+3. **Code Review**: No / Claude / Gemini / Qwen / Codex
+
+**Examples**:
+```bash
+# Simple task
+/workflow:lite-plan "Add user avatar upload feature"
+
+# Need code exploration
+/workflow:lite-plan -e "Refactor authentication module to OAuth2 standard"
+
+# Complex project
+/workflow:plan "Implement complete real-time collaborative editing system"
+/workflow:action-plan-verify  # Verify plan quality
+/workflow:execute
+```
+
+---
+
+### 5️⃣ **Testing Phase - Choose Testing Strategy**
+
+| Strategy | Command | Use Case |
+|----------|---------|----------|
+| **TDD Mode** | `/workflow:tdd-plan` | Starting from scratch, test-driven development |
+| **Post-Implementation Testing** | `/workflow:test-gen` | Code complete, add tests |
+| **Test Fixing** | `/workflow:test-cycle-execute` | Existing tests, need to fix failures |
+
+**Examples**:
+```bash
+# TDD: Write tests first, then implement
+/workflow:tdd-plan "User authentication module"
+/workflow:execute  # Red-Green-Refactor cycle
+/workflow:tdd-verify  # Verify TDD compliance
+
+# Post-implementation testing: Add tests after code complete
+/workflow:test-gen WFS-user-auth-implementation
+/workflow:execute
+
+# Test fixing: Existing tests with high failure rate
+/workflow:test-cycle-execute --max-iterations 5
+# Auto-iterate fixes until pass rate ≥95%
+```
+
+---
+
+### 6️⃣ **Review Phase - Choose Review Type**
+
+| Type | Command | Focus |
+|------|---------|-------|
+| **Security Review** | `/workflow:review --type security` | SQL injection, XSS, authentication vulnerabilities |
+| **Architecture Review** | `/workflow:review --type architecture` | Design patterns, coupling, scalability |
+| **Quality Review** | `/workflow:review --type quality` | Code style, complexity, maintainability |
+| **Comprehensive Review** | `/workflow:review` | All-around inspection |
+
+**Examples**:
+```bash
+# Security-critical system
+/workflow:review --type security
+
+# After architecture refactoring
+/workflow:review --type architecture
+
+# Daily development
+/workflow:review --type quality
+```
+
+---
+
+### 7️⃣ **CLI Tools Collaboration Mode - Multi-Model Intelligent Coordination**
+
+This project integrates three CLI tools supporting flexible serial, parallel, and hybrid execution:
+
+| Tool | Core Capabilities | Context Length | Use Cases |
+|------|------------------|----------------|-----------|
+| **Gemini** | Deep analysis, architecture design, planning | Ultra-long context | Code understanding, execution flow tracing, technical solution evaluation |
+| **Qwen** | Code review, pattern recognition | Ultra-long context | Gemini alternative, multi-dimensional analysis |
+| **Codex** | Precise code writing, bug location | Standard context | Feature implementation, test generation, code refactoring |
+
+#### 📋 Three Execution Modes
+
+**1. Serial Execution** - Sequential dependency
+
+Use case: Subsequent tasks depend on previous results
+
+```bash
+# Example: Analyze then implement
+# Step 1: Gemini analyzes architecture
+Use gemini to analyze the authentication module's architecture design, identify key components and data flow
+
+# Step 2: Codex implements based on analysis
+Have codex implement JWT authentication middleware based on the above architecture analysis
+```
+
+**Execution flow**:
+```
+Gemini analysis → Output architecture report → Codex reads report → Implement code
+```
+
+---
+
+**2. Parallel Execution** - Concurrent processing
+
+Use case: Multiple independent tasks with no dependencies
+
+```bash
+# Example: Multi-dimensional analysis
+Use gemini to analyze authentication module security, focus on JWT, password storage, session management
+Use qwen to analyze authentication module performance bottlenecks, identify slow queries and optimization points
+Have codex generate unit tests for authentication module, covering all core features
+```
+
+**Execution flow**:
+```
+        ┌─ Gemini: Security analysis ─┐
+Parallel ┼─ Qwen: Performance analysis ┼─→ Aggregate results
+        └─ Codex: Test generation ────┘
+```
+
+---
+
+**3. Hybrid Execution** - Combined serial and parallel
+
+Use case: Complex tasks with both parallel and serial phases
+
+```bash
+# Example: Complete feature development
+# Phase 1: Parallel analysis (independent tasks)
+Use gemini to analyze existing authentication system architecture patterns
+Use qwen to evaluate OAuth2 integration technical solutions
+
+# Phase 2: Serial implementation (depends on Phase 1)
+Have codex implement OAuth2 authentication flow based on above analysis
+
+# Phase 3: Parallel optimization (independent tasks)
+Use gemini to review code quality and security
+Have codex generate integration tests
+```
+
+**Execution flow**:
+```
+Phase 1: Gemini analysis ──┐
+         Qwen evaluation ──┼─→ Phase 2: Codex implementation ──→ Phase 3: Gemini review ──┐
+                           │                                              Codex tests ───┼─→ Complete
+                           └──────────────────────────────────────────────────────────────┘
+```
+
+---
+
+#### 🎯 Semantic Invocation vs Command Invocation
+
+**Method 1: Natural Language Semantic Invocation** (Recommended)
+
+```bash
+# Users simply describe naturally, Claude Code auto-invokes tools
+"Use gemini to analyze this module's dependencies"
+→ Claude Code auto-generates: cd src && gemini -p "Analyze dependencies"
+
+"Have codex implement user registration feature"
+→ Claude Code auto-generates: codex -C src/auth --full-auto exec "Implement registration"
+```
+
+**Method 2: Direct Command Invocation**
+
+```bash
+# Precise invocation via Slash commands
+/cli:chat --tool gemini "Explain this algorithm"
+/cli:analyze --tool qwen "Analyze performance bottlenecks"
+/cli:execute --tool codex "Optimize query performance"
+```
+
+---
+
+#### 🔗 CLI Results as Context (Memory)
+
+CLI tool analysis results can be saved and used as context (memory) for subsequent operations, enabling intelligent workflows:
+
+**1. Result Persistence**
+
+```bash
+# CLI execution results automatically saved to session directory
+/cli:chat --tool gemini "Analyze authentication module architecture"
+→ Saved to: .workflow/active/WFS-xxx/.chat/chat-[timestamp].md
+
+/cli:analyze --tool qwen "Evaluate performance bottlenecks"
+→ Saved to: .workflow/active/WFS-xxx/.chat/analyze-[timestamp].md
+
+/cli:execute --tool codex "Implement feature"
+→ Saved to: .workflow/active/WFS-xxx/.chat/execute-[timestamp].md
+```
+
+**2. Results as Planning Basis**
+
+```bash
+# Step 1: Analyze current state (generate memory)
+Use gemini to deeply analyze authentication system architecture, security, and performance issues
+→ Output: Detailed analysis report (auto-saved)
+
+# Step 2: Plan based on analysis results
+/workflow:plan "Refactor authentication system based on above Gemini analysis report"
+→ System automatically reads analysis reports from .chat/ as context
+→ Generate precise implementation plan
+```
+
+**3. Results as Implementation Basis**
+
+```bash
+# Step 1: Parallel analysis (generate multiple memories)
+Use gemini to analyze existing code structure
+Use qwen to evaluate technical solution feasibility
+→ Output: Multiple analysis reports
+
+# Step 2: Implement based on all analysis results
+Have codex synthesize above Gemini and Qwen analyses to implement optimal solution
+→ Codex automatically reads prior analysis results
+→ Generate code conforming to architecture design
+```
+
+**4. Cross-Session References**
+
+```bash
+# Reference historical session analysis results
+/cli:execute --tool codex "Refer to architecture analysis in WFS-2024-001, implement new payment module"
+→ System automatically loads specified session context
+→ Implement based on historical analysis
+```
+
+**5. Memory Update Loop**
+
+```bash
+# Iterative optimization flow
+Use gemini to analyze problems in current implementation
+→ Generate problem report (memory)
+
+Have codex optimize code based on problem report
+→ Implement improvements (update memory)
+
+Use qwen to verify optimization effectiveness
+→ Verification report (append to memory)
+
+# All results accumulate as complete project memory
+→ Support subsequent decisions and implementation
+```
+
+**Memory Flow Example**:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Phase 1: Analysis Phase (Generate Memory)                   │
+├─────────────────────────────────────────────────────────────┤
+│  Gemini analysis  →  Architecture report (.chat/analyze-001.md)│
+│  Qwen evaluation  →  Solution report (.chat/analyze-002.md)   │
+└─────────────────────┬───────────────────────────────────────┘
+                      │ As Memory Input
+                      ↓
+┌─────────────────────────────────────────────────────────────┐
+│  Phase 2: Planning Phase (Use Memory)                        │
+├─────────────────────────────────────────────────────────────┤
+│  /workflow:plan  →  Read analysis reports  →  Generate plan   │
+│                     (.task/IMPL-*.json)                      │
+└─────────────────────┬───────────────────────────────────────┘
+                      │ As Memory Input
+                      ↓
+┌─────────────────────────────────────────────────────────────┐
+│  Phase 3: Implementation Phase (Use Memory)                   │
+├─────────────────────────────────────────────────────────────┤
+│  Codex implement  →  Read plan+analysis  →  Generate code     │
+│                     (.chat/execute-001.md)                   │
+└─────────────────────┬───────────────────────────────────────┘
+                      │ As Memory Input
+                      ↓
+┌─────────────────────────────────────────────────────────────┐
+│  Phase 4: Verification Phase (Use Memory)                     │
+├─────────────────────────────────────────────────────────────┤
+│  Gemini review   →  Read implementation code  →  Quality report│
+│                     (.chat/review-001.md)                    │
+└─────────────────────────────────────────────────────────────┘
+                      │
+                      ↓
+            Complete Project Memory Library
+          Supporting All Future Decisions and Implementation
+```
+
+**Best Practices**:
+
+1. **Maintain Continuity**: Execute related tasks in the same session to automatically share memory
+2. **Explicit References**: Explicitly reference historical analyses when crossing sessions (e.g., "Refer to WFS-xxx analysis")
+3. **Incremental Updates**: Each analysis and implementation appends to memory, forming complete decision chain
+4. **Regular Organization**: Use `/memory:update-related` to consolidate CLI results into CLAUDE.md
+5. **Quality First**: High-quality analysis memory significantly improves subsequent implementation quality
+
+---
+
+#### 🔄 Workflow Integration Examples
+
+**Integration with Lite Workflow**:
+
+```bash
+# 1. Planning phase: Gemini analysis
+/workflow:lite-plan -e "Refactor payment module"
+→ Three-dimensional confirmation selects "CLI Tools execution"
+
+# 2. Execution phase: Choose execution method
+# Option A: Serial execution
+→ "Use gemini to analyze payment flow" → "Have codex refactor code"
+
+# Option B: Parallel analysis + Serial implementation
+→ "Use gemini to analyze architecture" + "Use qwen to evaluate solution"
+→ "Have codex refactor based on analysis results"
+```
+
+**Integration with Full Workflow**:
+
+```bash
+# 1. Planning phase
+/workflow:plan "Implement distributed cache"
+/workflow:action-plan-verify
+
+# 2. Analysis phase (parallel)
+Use gemini to analyze existing cache architecture
+Use qwen to evaluate Redis cluster solution
+
+# 3. Implementation phase (serial)
+/workflow:execute  # Or use CLI
+Have codex implement Redis cluster integration
+
+# 4. Testing phase (parallel)
+/workflow:test-gen WFS-cache
+→ Internally uses gemini analysis + codex test generation
+
+# 5. Review phase (serial)
+Use gemini to review code quality
+/workflow:review --type architecture
+```
+
+---
+
+#### 💡 Best Practices
+
+**When to use serial**:
+- Implementation depends on design solution
+- Testing depends on code implementation
+- Optimization depends on performance analysis
+
+**When to use parallel**:
+- Multi-dimensional analysis (security + performance + architecture)
+- Multi-module independent development
+- Simultaneous code and test generation
+
+**When to use hybrid**:
+- Complex feature development (analysis → design → implementation → testing)
+- Large-scale refactoring (evaluation → planning → execution → verification)
+- Tech stack migration (research → solution → implementation → optimization)
+
+**Tool selection guidelines**:
+1. **Need to understand code** → Gemini (preferred) or Qwen
+2. **Need to write code** → Codex
+3. **Complex analysis** → Gemini + Qwen parallel (complementary verification)
+4. **Precise implementation** → Codex (based on Gemini analysis)
+5. **Quick prototype** → Direct Codex usage
+
+---
+
+## 🔄 Complete Flow for Typical Scenarios
+
+### Scenario A: New Feature Development (Know How to Build)
+
+```bash
+# 1. Planning
+/workflow:plan "Add JWT authentication and permission management"
+
+# 2. Verify plan
+/workflow:action-plan-verify
+
+# 3. Execute
+/workflow:execute
+
+# 4. Testing
+/workflow:test-gen WFS-jwt-auth
+/workflow:execute
+
+# 5. Review
+/workflow:review --type security
+
+# 6. Complete
+/workflow:session:complete
+```
+
+---
+
+### Scenario B: New Feature Development (Don't Know How to Build)
+
+```bash
+# 1. Design exploration
+/workflow:brainstorm:auto-parallel "Design distributed cache system architecture" --count 5
+
+# 2. UI design (if needed)
+/workflow:ui-design:explore-auto --prompt "Cache management dashboard interface"
+/workflow:ui-design:design-sync --session WFS-xxx
+
+# 3. Planning
+/workflow:plan
+
+# 4. Verification
+/workflow:action-plan-verify
+
+# 5. Execution
+/workflow:execute
+
+# 6. TDD testing
+/workflow:tdd-plan "Cache system core modules"
+/workflow:execute
+
+# 7. Review
+/workflow:review --type architecture
+/workflow:review --type security
+
+# 8. Complete
+/workflow:session:complete
+```
+
+---
+
+### Scenario C: Quick Feature Development (Lite Workflow)
+
+```bash
+# 1. Lightweight planning (may need code exploration)
+/workflow:lite-plan -e "Optimize database query performance"
+
+# 2. Three-dimensional confirmation
+# - Confirm task
+# - Choose Agent execution
+# - Choose Gemini code review
+
+# 3. Auto-execution (called internally by /workflow:lite-execute)
+
+# 4. Complete
+```
+
+---
+
+### Scenario D: Bug Fixing
+
+```bash
+# 1. Diagnosis
+/cli:mode:bug-diagnosis --tool gemini "User login fails with token expired error"
+
+# 2. Quick fix
+/workflow:lite-plan "Fix JWT token expiration validation logic"
+
+# 3. Test fix
+/workflow:test-cycle-execute
+
+# 4. Complete
+```
+
+---
+
+## 🎓 Quick Command Reference
+
+### Choose by Knowledge Level
+
+| Your Situation | Recommended Command |
+|----------------|---------------------|
+| 💭 Don't know what to build | `/workflow:brainstorm:auto-parallel "Explore product direction"` |
+| ❓ Know what, don't know how | `/workflow:brainstorm:auto-parallel "Design technical solution"` |
+| ✅ Know what and how | `/workflow:plan "Specific implementation description"` |
+| ⚡ Simple, clear small task | `/workflow:lite-plan "Task description"` |
+| 🐛 Bug fixing | `/cli:mode:bug-diagnosis` + `/workflow:lite-plan` |
+
+### Choose by Project Phase
+
+| Phase | Command |
+|-------|---------|
+| 📋 **Requirements Analysis** | `/workflow:brainstorm:auto-parallel` |
+| 🏗️ **Architecture Design** | `/workflow:brainstorm:auto-parallel` |
+| 🎨 **UI Design** | `/workflow:ui-design:explore-auto` / `imitate-auto` |
+| 📝 **Implementation Planning** | `/workflow:plan` / `/workflow:lite-plan` |
+| 🚀 **Coding Implementation** | `/workflow:execute` / `/workflow:lite-execute` |
+| 🧪 **Testing** | `/workflow:tdd-plan` / `/workflow:test-gen` |
+| 🔧 **Test Fixing** | `/workflow:test-cycle-execute` |
+| 📖 **Code Review** | `/workflow:review` |
+| ✅ **Project Completion** | `/workflow:session:complete` |
+
+### Choose by Work Mode
+
+| Mode | Workflow | Use Case |
+|------|----------|----------|
+| **🚀 Agile & Fast** | Lite Workflow | Personal dev, rapid iteration, prototype validation |
+| **📋 Standard & Complete** | Full Workflow | Team collaboration, enterprise projects, long-term maintenance |
+| **🧪 Quality-First** | TDD Workflow | Core modules, critical features, high reliability requirements |
+| **🎨 Design-Driven** | UI-Design Workflow | Frontend projects, user interfaces, design systems |
+
+---
+
+## 💡 Expert Advice
+
+### ✅ Best Practices
+
+1. **Use brainstorming when uncertain**: Better to spend 10 minutes exploring solutions than blindly implementing and rewriting
+2. **Use Full workflow for complex projects**: Persistent plans facilitate team collaboration and long-term maintenance
+3. **Use Lite workflow for small tasks**: Complete quickly, reduce overhead
+4. **Use TDD for critical modules**: Test-driven development ensures quality
+5. **Regularly update memory**: `/memory:update-related` keeps context accurate
+
+### ❌ Common Pitfalls
+
+1. **Blindly skipping brainstorming**: Not exploring unfamiliar technical domains leads to rework
+2. **Overusing brainstorming**: Brainstorming even simple features wastes time
+3. **Ignoring plan verification**: Not running `/workflow:action-plan-verify` causes execution issues
+4. **Ignoring testing**: Not generating tests, code quality cannot be guaranteed
+5. **Not completing sessions**: Not running `/workflow:session:complete` causes session state confusion
+
+---
+
+## 🔗 Related Documentation
+
+- [Getting Started Guide](GETTING_STARTED.md) - Quick start tutorial
+- [Command Reference](COMMAND_REFERENCE.md) - Complete command list
+- [Architecture Overview](ARCHITECTURE.md) - System architecture explanation
+- [Examples](EXAMPLES.md) - Real-world scenario examples
+- [FAQ](FAQ.md) - Frequently asked questions
+
+---
+
+**Last Updated**: 2025-11-20
+**Version**: 5.8.1
Author	SHA1	Message	Date
Claude	c34a6042c0	docs: add CLI results as memory/context section Add comprehensive explanation of how CLI tool results can be saved and reused as context for subsequent operations: - Result persistence in workflow sessions (.chat/ directory) - Using analysis results as planning basis - Using analysis results as implementation basis - Cross-session references - Memory update loops with iterative optimization - Visual memory flow diagram showing phase-to-phase context passing - Best practices for maintaining continuity and quality This enables intelligent workflows where Gemini/Qwen analysis informs Codex implementation, and all results accumulate as project memory for future decision-making. Integrates with /workflow:plan and /workflow:lite-plan commands.	2025-11-20 09:53:21 +00:00
Claude	383da9ebb7	docs: add CLI tools collaboration mode to Workflow Decision Guide Add comprehensive section on multi-model CLI collaboration (Gemini/Qwen/Codex): - Three execution modes: serial, parallel, and hybrid - Semantic invocation vs command invocation patterns - Integration examples with Lite and Full workflows - Best practices for tool selection and execution strategies Updates both Chinese and English versions with practical examples showing how to leverage ultra-long context models (Gemini/Qwen) for analysis and Codex for precise code implementation.	2025-11-20 09:51:50 +00:00
catlog22	fc965c87d7	Merge pull request #17 from catlog22/claude/optimize-doc-phase2-filename-012ABaeYT56XeMJ73zUeA3kt Optimize JSON filename in doc command phase2	2025-11-20 17:40:30 +08:00
catlog22	50a36ded97	Merge pull request #18 from catlog22/claude/add-english-workflow-guide-01EfMQYn5ZBavQWNB5PgSN85 Add English version of Workflow Decision Guide	2025-11-20 17:40:11 +08:00
Claude	c5a0f635f4	docs: add English version of Workflow Decision Guide Add WORKFLOW_DECISION_GUIDE_EN.md with complete English translation of the workflow decision guide, including: - Full lifecycle command selection flowchart - Decision point explanations with examples - Testing and review strategies - Complete flows for typical scenarios - Quick reference tables by knowledge level, project phase, and work mode - Best practices and common pitfalls	2025-11-20 09:35:45 +00:00
Claude	ca9653c2e6	refactor: rename phase2-analysis.json to doc-planning-data.json Optimize the Phase 2 output filename in /memory:docs command for better clarity: - Old: phase2-analysis.json (generic, non-descriptive) - New: doc-planning-data.json (clear purpose, self-documenting) The new name better reflects that this file contains comprehensive documentation planning data including folder analysis, grouping information, existing docs, and statistics. Updated all references in command documentation and skill guides.	2025-11-20 09:22:32 +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
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
Claude	c56bf68d87	Remove version evolution content from tdd-plan.md Removed 104 lines of version history and enhancement documentation (lines 420-523): - TDD Workflow Enhancements section - Key Improvements (adopted features from test-gen and plan workflows) - Workflow Comparison table (Previous vs Current) - Migration Notes and backward compatibility info - Configuration examples This content represented ~19% of the file and was historical/evolutionary information rather than core command functionality. Focuses the documentation on what the command does, not how it evolved. Improves task focus and documentation clarity as identified in audit report.	2025-11-20 02:57:21 +00:00
Claude	9627b42c03	Add comprehensive audit report for command docs and agent files Completed systematic audit of 87 files (73 commands + 14 agents) to verify: - No version information in docs (except version.md) - No extraneous content unrelated to core tasks - Focus on single responsibility Key findings: - Overall compliance: 89.7% (78/87 files) - Commands: 95.9% compliant (70/73) - Agents: 57.1% compliant (8/14) Issues identified: 1. tdd-plan.md contains 103 lines of version evolution content 2. 6 agents have duplicate Windows path guidelines 3. ui-design-agent.md contains 607 lines of JSON schema templates Report provides actionable recommendations with priority levels and estimated effort.	2025-11-20 02:49:36 +00:00