diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
new file mode 100644
index 00000000..8a90f2c5
--- /dev/null
+++ 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
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 00000000..9cef6da9
--- /dev/null
+++ 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
diff --git a/EXAMPLES.md b/EXAMPLES.md
new file mode 100644
index 00000000..fa505409
--- /dev/null
+++ 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-index "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 code analysis
+/cli:mode:code-analysis --tool gemini "Analyze React component lifecycle and event listener management for potential memory leaks"
+
+# 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
diff --git a/FAQ.md b/FAQ.md
new file mode 100644
index 00000000..3b35c0e6
--- /dev/null
+++ b/FAQ.md
@@ -0,0 +1,744 @@
+# ❓ 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:
+- Feature requires multiple perspectives (architecture, security, UX, etc.)
+- You need thorough requirements analysis
+- Architecture decisions have significant impact
+- Starting a complex project from scratch
+
+**Example**:
+```bash
+/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)!
diff --git a/README.md b/README.md
index ec26e2c7..f295e48a 100644
--- a/README.md
+++ b/README.md
@@ -159,11 +159,38 @@ 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))
+- [**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
 
diff --git a/README_CN.md b/README_CN.md
index 94f2f61b..737038f0 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -159,11 +159,38 @@ CCW 包含内置的**命令指南技能**，帮助您有效地发现和使用命
 
 ---
 
+## 📚 文档
+
+CCW 提供全面的文档，帮助您快速上手并掌握高级功能：
+
+### 📖 **快速入门**
+- [**快速上手指南**](GETTING_STARTED_CN.md) - 5 分钟快速入门教程
+- [**安装指南**](INSTALL_CN.md) - 详细安装说明 ([English](INSTALL.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) 了解贡献指南。
 
 ## 📄 许可证