Refactor documentation for code commands and workflows

- Updated command syntax formatting to use code blocks for clarity in `prep.md`, `review.md`, and `spec.md`. - Enhanced architectural diagrams in `ch01-what-is-claude-dms3.md` and core concepts in `ch03-core-concepts.md` using mermaid syntax for better visualization. - Improved workflow diagrams in `ch04-workflow-basics.md` and `4-level.md` to provide clearer representations of processes. - Added troubleshooting section in `installation.md` to address common installation issues and provide quick start examples. - Revised skill documentation in `claude-meta.md` and `claude-workflow.md` to standardize command triggers and output structures. - Updated best practices and workflow index documentation to enhance readability and understanding of workflow levels and practices.
2026-03-01 15:03:57 +08:00 · 2026-02-28 19:53:24 +08:00
parent b0bfdb907a
commit 4a89f626fc
51 changed files with 741 additions and 619 deletions
--- a/docs/COMMAND_SPEC.md
+++ b/docs/COMMAND_SPEC.md
@@ -1,8 +1,8 @@

 # Claude Code Workflow (CCW) - Command Specification

-**Version**: 6.2.0
-**Updated**: 2025-12-20
+**Version**: 7.0.6
+**Updated**: 2026-02-28

 ## 1. Introduction

--- a/docs/commands/claude/cli.md
+++ b/docs/commands/claude/cli.md
@@ -26,7 +26,7 @@
 **Function**: Generate `.gemini/` and `.qwen/` configuration directories based on workspace tech detection, including settings.json and ignore files.

 **Syntax**:
-```
+```bash
 /cli:cli-init [--tool gemini|qwen|all] [--output path] [--preview]
 ```

@@ -36,7 +36,7 @@
 - `--preview`: Preview mode (don't actually create)

 **Generated File Structure**:
-```
+```plaintext
 .gemini/
 ├── settings.json      # Gemini configuration
 └── ignore            # Ignore patterns
@@ -75,7 +75,7 @@
 **Function**: Interactive code review using Codex CLI via ccw endpoint, supporting configurable review targets, models, and custom instructions.

 **Syntax**:
-```
+```bash
 /cli:codex-review [--uncommitted|--base <branch>|--commit <sha>] [--model <model>] [--title <title>] [prompt]
 ```

--- a/docs/commands/claude/core-orchestration.md
+++ b/docs/commands/claude/core-orchestration.md
@@ -18,7 +18,7 @@
 **Function**: Main workflow orchestrator - intent analysis -> workflow selection -> command chain execution

 **Syntax**:
-```
+```bash
 /ccw "task description"
 ```

@@ -80,7 +80,7 @@ graph TD
 **Function**: Command orchestration tool - analyze tasks, recommend command chains, sequential execution, state persistence

 **Syntax**:
-```
+```bash
 /ccw-coordinator "task description"
 ```

--- a/docs/commands/claude/index.md
+++ b/docs/commands/claude/index.md
@@ -11,7 +11,7 @@
 | **Core Orchestration** | 2 | Main workflow orchestrators (ccw, ccw-coordinator) |
 | **Workflow** | 20+ | Planning, execution, review, TDD, testing workflows |
 | **Session Management** | 6 | Session creation, listing, resuming, completion |
-| **Issue Workflow** | 7 | Issue discovery, planning, queue, execution |
+| **Issue Workflow** | 8 | Issue discovery, planning, queue, execution |
 | **Memory** | 8 | Memory capture, update, document generation |
 | **CLI Tools** | 2 | CLI initialization, Codex review |
 | **UI Design** | 10 | UI design prototype generation, style extraction |
@@ -52,6 +52,7 @@
 | [`/workflow:session:start`](./session.md#start) | Discover existing sessions or start new workflow session | Intermediate |
 | [`/workflow:session:list`](./session.md#list) | List all workflow sessions | Beginner |
 | [`/workflow:session:resume`](./session.md#resume) | Resume most recently paused workflow session | Intermediate |
+| [`/workflow:session:sync`](./session.md#sync) | Quick-sync session work to specs and project-tech | Intermediate |
 | [`/workflow:session:complete`](./session.md#complete) | Mark active workflow session as completed | Intermediate |
 | [`/workflow:session:solidify`](./session.md#solidify) | Crystallize session learnings into project guidelines | Intermediate |

@@ -62,6 +63,7 @@
 | [`/issue:new`](./issue.md#new) | Create structured issue from GitHub URL or text description | Intermediate |
 | [`/issue:discover`](./issue.md#discover) | Discover potential issues from multiple perspectives | Intermediate |
 | [`/issue:discover-by-prompt`](./issue.md#discover-by-prompt) | Discover issues via user prompt | Intermediate |
+| [`/issue:from-brainstorm`](./issue.md#from-brainstorm) | Convert brainstorm session ideas into issue with executable solution | Intermediate |
 | [`/issue:plan`](./issue.md#plan) | Batch plan issue solutions | Intermediate |
 | [`/issue:queue`](./issue.md#queue) | Form execution queue | Intermediate |
 | [`/issue:execute`](./issue.md#execute) | Execute queue | Intermediate |
@@ -73,7 +75,7 @@
 |---------|----------|------------|
 | [`/memory:compact`](./memory.md#compact) | Compress current session memory to structured text | Intermediate |
 | [`/memory:tips`](./memory.md#tips) | Quick note-taking | Beginner |
-| [`/memory:load`](./memory.md#load) | Load task context via CLI project analysis | Intermediate |
+| [`/memory:prepare`](./memory.md#prepare) | Load task context via CLI project analysis | Intermediate |
 | [`/memory:update-full`](./memory.md#update-full) | Update all CLAUDE.md files | Intermediate |
 | [`/memory:update-related`](./memory.md#update-related) | Update CLAUDE.md for git-changed modules | Intermediate |
 | [`/memory:docs-full-cli`](./memory.md#docs-full-cli) | Generate full project documentation using CLI | Intermediate |
--- a/docs/commands/claude/issue.md
+++ b/docs/commands/claude/issue.md
@@ -32,7 +32,7 @@
 **Function**: Create structured issue from GitHub URL or text description, supporting requirement clarity detection.

 **Syntax**:
-```
+```bash
 /issue:new [-y|--yes] <github-url | text description> [--priority 1-5]
 ```

@@ -92,7 +92,7 @@ interface Issue {
 **Function**: Discover potential issues from multiple perspectives (Bug, UX, Test, Quality, Security, Performance, Maintainability, Best Practices).

 **Syntax**:
-```
+```bash
 /issue:discover [-y|--yes] <path pattern> [--perspectives=bug,ux,...] [--external]
 ```

@@ -125,7 +125,7 @@ interface Issue {
 **Function**: Discover issues via user prompt, using Gemini-planned iterative multi-agent exploration, supporting cross-module comparison.

 **Syntax**:
-```
+```bash
 /issue:discover-by-prompt [-y|--yes] <prompt> [--scope=src/**] [--depth=standard|deep] [--max-iterations=5]
 ```

@@ -151,7 +151,7 @@ interface Issue {
 **Function**: Batch plan issue solutions, using issue-plan-agent (explore + plan closed loop).

 **Syntax**:
-```
+```bash
 /issue:plan [-y|--yes] --all-pending <issue-id>[,<issue-id>,...] [--batch-size 3]
 ```

@@ -176,7 +176,7 @@ interface Issue {
 **Function**: Form execution queue from bound solutions, using issue-queue-agent (solution level).

 **Syntax**:
-```
+```bash
 /issue:queue [-y|--yes] [--queues <n>] [--issue <id>]
 ```

@@ -201,7 +201,7 @@ interface Issue {
 **Function**: Execute queue, using DAG parallel orchestration (one commit per solution).

 **Syntax**:
-```
+```bash
 /issue:execute [-y|--yes] --queue <queue-id> [--worktree [<existing-path>]]
 ```

@@ -223,7 +223,7 @@ interface Issue {
 **Function**: Convert planning artifact (lite-plan, workflow session, markdown) to issue solution.

 **Syntax**:
-```
+```bash
 /issue:convert-to-plan [-y|--yes] [--issue <id>] [--supplement] <source>
 ```

@@ -253,7 +253,7 @@ interface Issue {
 **Function**: Convert brainstorm session ideas to issues and generate executable solutions.

 **Syntax**:
-```
+```bash
 /issue:from-brainstorm SESSION="session-id" [--idea=<index>] [--auto] [-y|--yes]
 ```

--- a/docs/commands/claude/memory.md
+++ b/docs/commands/claude/memory.md
@@ -19,7 +19,7 @@
 |---------|----------|--------|
 | [`compact`](#compact) | Compress current session memory to structured text | `/memory:compact [optional: session description]` |
 | [`tips`](#tips) | Quick note-taking | `/memory:tips <note content> [--tag tags] [--context context]` |
-| [`load`](#load) | Load task context via CLI project analysis | `/memory:load [--tool gemini\|qwen] "task context description"` |
+| [`prepare`](#prepare) | Load task context via CLI project analysis | `/memory:prepare [--tool gemini\|qwen] "task context description"` |
 | [`update-full`](#update-full) | Update all CLAUDE.md files | `/memory:update-full [--tool gemini\|qwen\|codex] [--path directory]` |
 | [`update-related`](#update-related) | Update CLAUDE.md for git-changed modules | `/memory:update-related [--tool gemini\|qwen\|codex]` |
 | [`docs-full-cli`](#docs-full-cli) | Generate full project documentation using CLI | `/memory:docs-full-cli [path] [--tool tool]` |
@@ -33,7 +33,7 @@
 **Function**: Compress current session memory to structured text, extracting objectives, plans, files, decisions, constraints, and state, saving via MCP core_memory tool.

 **Syntax**:
-```
+```bash
 /memory:compact [optional: session description]
 ```

@@ -59,7 +59,7 @@
 **Function**: Quick note-taking command, capturing thoughts, snippets, reminders, and insights for future reference.

 **Syntax**:
-```
+```bash
 /memory:tips <note content> [--tag <tag1,tag2>] [--context <context>]
 ```

@@ -79,13 +79,13 @@
 /memory:tips "use Redis to cache user sessions" --context "login optimization"
 ```

-### load
+### prepare

 **Function**: Delegate to universal-executor agent, analyzing project via Gemini/Qwen CLI and returning JSON core content package for task context.

 **Syntax**:
-```
-/memory:load [--tool gemini|qwen] "task context description"
+```bash
+/memory:prepare [--tool gemini|qwen] "task context description"
 ```

 **Options**:
@@ -96,10 +96,10 @@
 **Examples**:
 ```bash
 # Use default tool
-/memory:load "user authentication module"
+/memory:prepare "user authentication module"

 # Specify tool
-/memory:load --tool gemini "payment system architecture"
+/memory:prepare --tool gemini "payment system architecture"
 ```

 ### update-full
@@ -107,7 +107,7 @@
 **Function**: Update all CLAUDE.md files, using layer-based execution (Layer 3->1), batch agent processing (4 modules/agent), and gemini->qwen->codex fallback.

 **Syntax**:
-```
+```bash
 /memory:update-full [--tool gemini|qwen|codex] [--path <directory>]
 ```

@@ -137,7 +137,7 @@
 **Function**: Update CLAUDE.md files for git-changed modules, using batch agent execution (4 modules/agent) and gemini->qwen->codex fallback.

 **Syntax**:
-```
+```bash
 /memory:update-related [--tool gemini|qwen|codex]
 ```

@@ -158,7 +158,7 @@
 **Function**: Generate full project documentation using CLI (Layer 3->1), batch agent processing (4 modules/agent), gemini->qwen->codex fallback, direct parallel for <20 modules.

 **Syntax**:
-```
+```bash
 /memory:docs-full-cli [path] [--tool <gemini|qwen|codex>]
 ```

@@ -179,7 +179,7 @@
 **Function**: Generate documentation for git-changed modules using CLI, batch agent processing (4 modules/agent), gemini->qwen->codex fallback, direct execution for <15 modules.

 **Syntax**:
-```
+```bash
 /memory:docs-related-cli [--tool <gemini|qwen|codex>]
 ```

@@ -197,7 +197,7 @@
 **Function**: Generate SKILL memory package from style reference, facilitating loading and consistent design system usage.

 **Syntax**:
-```
+```bash
 /memory:style-skill-memory [package-name] [--regenerate]
 ```

--- a/docs/commands/claude/session.md
+++ b/docs/commands/claude/session.md
@@ -20,6 +20,7 @@
 | [`start`](#start) | Discover existing sessions or start new workflow session | `/workflow:session:start [--type type] [--auto\|--new] [description]` |
 | [`list`](#list) | List all workflow sessions | `/workflow:session:list` |
 | [`resume`](#resume) | Resume most recently paused workflow session | `/workflow:session:resume` |
+| [`sync`](#sync) | Quick-sync session work to specs and project-tech | `/workflow:session:sync [-y] ["what was done"]` |
 | [`complete`](#complete) | Mark active workflow session as completed | `/workflow:session:complete [-y] [--detailed]` |
 | [`solidify`](#solidify) | Crystallize session learnings into project guidelines | `/workflow:session:solidify [-y] [--type type] [--category category] "rule"` |

@@ -30,7 +31,7 @@
 **Function**: Discover existing sessions or start new workflow session, supporting intelligent session management and conflict detection.

 **Syntax**:
-```
+```bash
 /workflow:session:start [--type <workflow|review|tdd|test|docs>] [--auto|--new] [optional: task description]
 ```

@@ -99,7 +100,7 @@ graph TD
 **Function**: List all workflow sessions, supporting state filtering, displaying session metadata and progress information.

 **Syntax**:
-```
+```bash
 /workflow:session:list
 ```

@@ -122,7 +123,7 @@ graph TD
 **Function**: Resume most recently paused workflow session, supporting automatic session discovery and state update.

 **Syntax**:
-```
+```bash
 /workflow:session:resume
 ```

@@ -144,12 +145,50 @@ graph TD
 /workflow:session:resume
 ```

+### sync
+
+**Function**: Quick-sync session work to specs and project-tech, extracting guidelines and tech entries from recent changes.
+
+**Syntax**:
+```bash
+/workflow:session:sync [-y|--yes] ["what was done"]
+```
+
+**Options**:
+- `--yes` or `-y`: Skip confirmation, auto-write both files
+
+**Workflow**:
+
+```mermaid
+graph TD
+    A[Start] --> B[Gather Context]
+    B --> C[Extract Updates]
+    C --> D{Auto Mode?}
+    D -->|Yes| E[Write Files]
+    D -->|No| F[Preview & Confirm]
+    F -->|Confirmed| E
+    E --> G[Update specs and project-tech.json]
+    G --> H[Confirm Synced]
+```
+
+**Examples**:
+```bash
+# Sync with confirmation prompt
+/workflow:session:sync "implemented user authentication"
+
+# Auto-sync without confirmation
+/workflow:session:sync --yes "fixed login bug"
+
+# Quick sync with auto-yes
+/workflow:session:sync -y
+```
+
 ### complete

 **Function**: Mark active workflow session as completed, archive and learn from experience, update checklist and remove active flag.

 **Syntax**:
-```
+```bash
 /workflow:session:complete [-y|--yes] [--detailed]
 ```

@@ -189,8 +228,8 @@ graph TD
 **Function**: Crystallize session learnings and user-defined constraints into permanent project guidelines.

 **Syntax**:
-```
-/workflow:session:solidify [-y|--yes] [--type <convention|constraint|learning>] [--category <category>] "rule or insight"
+```bash
+/workflow:session:solidify [-y|--yes] [--type <convention|constraint|learning|compress>] [--category <category>] "rule or insight"
 ```

 **Options**:
@@ -198,12 +237,14 @@ graph TD
  - `convention`: Code convention
  - `constraint`: Constraint condition
  - `learning`: Experience learning
+  - `compress`: Consolidate multiple memories into core memory
 - `--category=category`: Category name (e.g., `authentication`, `testing`)

 **Output Locations**:
 - Conventions: `.workflow/specs/conventions/<category>.md`
 - Constraints: `.workflow/specs/constraints/<category>.md`
 - Learnings: `.workflow/specs/learnings/<category>.md`
+- Compress: Core memory (MEMORY.md)

 **Examples**:
 ```bash
@@ -215,6 +256,9 @@ graph TD

 # Add learning
 /workflow:session:solidify --type=learning --category=api "REST API design lessons learned"
+
+# Consolidate memories into core memory
+/workflow:session:solidify --type=compress --category=workflow "session learnings summary"
 ```

 ## Session Directory Structure
--- a/docs/commands/claude/ui-design.md
+++ b/docs/commands/claude/ui-design.md
@@ -47,7 +47,7 @@
 **Function**: Interactive exploratory UI design workflow, style-centric batch generation, creating design variants from prompts/images, supporting parallel execution and user selection.

 **Syntax**:
-```
+```bash
 /workflow:ui-design:explore-auto [--input "<value>"] [--targets "<list>"] [--target-type "page|component"] [--session <id>] [--style-variants <count>] [--layout-variants <count>]
 ```

@@ -76,7 +76,7 @@
 **Function**: UI design workflow supporting direct code/image input for design token extraction and prototype generation.

 **Syntax**:
-```
+```bash
 /workflow:ui-design:imitate-auto [--input "<value>"] [--session <id>]
 ```

@@ -98,7 +98,7 @@
 **Function**: Extract design styles using Claude analysis from reference images or text prompts, supporting variant generation or refine mode.

 **Syntax**:
-```
+```bash
 /workflow:ui-design:style-extract [-y|--yes] [--design-id <id>] [--session <id>] [--images "<glob>"] [--prompt "<description>"] [--variants <count>] [--interactive] [--refine]
 ```

@@ -126,7 +126,7 @@
 **Function**: Extract structural layout information using Claude analysis from reference images or text prompts, supporting variant generation or refine mode.

 **Syntax**:
-```
+```bash
 /workflow:ui-design:layout-extract [-y|--yes] [--design-id <id>] [--session <id>] [--images "<glob>"] [--prompt "<description>"] [--targets "<list>"] [--variants <count>] [--device-type <desktop|mobile|tablet|responsive>] [--interactive] [--refine]
 ```

@@ -151,7 +151,7 @@
 **Function**: Extract animation and transition patterns from prompts inference and image references for design system documentation.

 **Syntax**:
-```
+```bash
 /workflow:ui-design:animation-extract [-y|--yes] [--design-id <id>] [--session <id>] [--images "<glob>"] [--focus "<type>"] [--interactive] [--refine]
 ```

@@ -172,7 +172,7 @@
 **Function**: Import design system from code files (CSS/JS/HTML/SCSS), using automatic file discovery and parallel agent analysis.

 **Syntax**:
-```
+```bash
 /workflow:ui-design:import-from-code [--design-id <id>] [--session <id>] [--source <path>]
 ```

@@ -193,7 +193,7 @@
 **Function**: Orchestrator extracts styles from code and generates shareable reference package, supporting preview (automatic file discovery).

 **Syntax**:
-```
+```bash
 /workflow:ui-design:codify-style <path> [--package-name <name>] [--output-dir <path>] [--overwrite]
 ```

@@ -216,7 +216,7 @@
 **Function**: Extract and generate multi-component reference pages and documentation from design run.

 **Syntax**:
-```
+```bash
 /workflow:ui-design:reference-page-generator [--design-run <path>] [--package-name <name>] [--output-dir <path>]
 ```

@@ -234,7 +234,7 @@
 **Function**: Assemble UI prototypes, combining layout templates with design tokens (default animation support), pure assembler with no new content generation.

 **Syntax**:
-```
+```bash
 /workflow:ui-design:generate [--design-id <id>] [--session <id>]
 ```

@@ -252,7 +252,7 @@
 **Function**: Sync final design system reference to brainstorm artifacts, preparing for consumption by `/workflow:plan`.

 **Syntax**:
-```
+```bash
 /workflow:ui-design:design-sync --session <session_id> [--selected-prototypes "<list>"]
 ```

@@ -286,7 +286,7 @@ graph TD

 ## Design Run Structure

-```
+```plaintext
 .workflow/ui-design-runs/<run-id>/
 ├── design-tokens.json       # Design tokens
 ├── layouts/                 # Layout templates
--- a/docs/commands/claude/workflow.md
+++ b/docs/commands/claude/workflow.md
@@ -72,7 +72,7 @@
 **Function**: Ultra-lightweight multi-tool analysis and direct execution. Simple tasks have no artifacts, complex tasks automatically create planning documents in `.workflow/.scratchpad/`.

 **Syntax**:
-```
+```bash
 /workflow:lite-lite-lite [-y|--yes] <task description>
 ```

@@ -95,7 +95,7 @@
 **Function**: Lightweight interactive planning workflow, supporting in-memory planning, code exploration, and execution to lite-execute.

 **Syntax**:
-```
+```bash
 /workflow:lite-plan [-y|--yes] [-e|--explore] "task description" | file.md
 ```

@@ -116,7 +116,7 @@
 **Function**: Execute tasks based on in-memory plan, prompt description, or file content.

 **Syntax**:
-```
+```bash
 /workflow:lite-execute [-y|--yes] [--in-memory] ["task description" | file-path]
 ```

@@ -137,7 +137,7 @@
 **Function**: Lightweight bug diagnosis and fix workflow, supporting intelligent severity assessment and optional hotfix mode.

 **Syntax**:
-```
+```bash
 /workflow:lite-fix [-y|--yes] [--hotfix] "bug description or issue reference"
 ```

@@ -158,7 +158,7 @@
 **Function**: 5-phase planning workflow, outputting IMPL_PLAN.md and task JSON.

 **Syntax**:
-```
+```bash
 /workflow:plan [-y|--yes] "text description" | file.md
 ```

@@ -183,7 +183,7 @@
 **Function**: Coordinate agent execution of workflow tasks, supporting automatic session discovery, parallel task processing, and state tracking.

 **Syntax**:
-```
+```bash
 /workflow:execute [-y|--yes] [--resume-session="session-id"]
 ```

@@ -201,7 +201,7 @@
 **Function**: Interactive workflow replanning, supporting session-level artifact updates and scope clarification.

 **Syntax**:
-```
+```bash
 /workflow:replan [-y|--yes] [--session session-id] [task-id] "requirement" | file.md [--interactive]
 ```

@@ -219,7 +219,7 @@
 **Function**: Multi-CLI collaborative planning workflow, using ACE context collection and iterative cross-validation.

 **Syntax**:
-```
+```bash
 /workflow:multi-cli-plan [-y|--yes] <task description> [--max-rounds=3] [--tools=gemini,codex] [--mode=parallel|serial]
 ```

@@ -242,7 +242,7 @@
 **Function**: Interactive brainstorming, multi-CLI collaboration, idea expansion, and documented thinking evolution.

 **Syntax**:
-```
+```bash
 /workflow:brainstorm-with-file [-y|--yes] [-c|--continue] [-m|--mode creative|structured] "idea or topic"
 ```

@@ -264,7 +264,7 @@
 **Function**: Interactive collaborative analysis with documented discussion, CLI-assisted exploration, and evolving understanding.

 **Syntax**:
-```
+```bash
 /workflow:analyze-with-file [-y|--yes] [-c|--continue] "topic or question"
 ```

@@ -282,7 +282,7 @@
 **Function**: Interactive hypothesis-driven debugging with documented exploration, understanding evolution, and Gemini-assisted correction.

 **Syntax**:
-```
+```bash
 /workflow:debug-with-file [-y|--yes] "bug description or error message"
 ```

@@ -300,7 +300,7 @@
 **Function**: Universal execution engine consuming any planning/brainstorming/analysis output, supporting minimal progress tracking, multi-agent coordination, and incremental execution.

 **Syntax**:
-```
+```bash
 /workflow:unified-execute-with-file [-y|--yes] [-p|--plan <path>] [-m|--mode sequential|parallel] ["execution context"]
 ```

--- a/docs/commands/codex/prep.md
+++ b/docs/commands/codex/prep.md
@@ -38,7 +38,7 @@
 **Function**: Delegate to universal-executor agent, analyzing project via Gemini/Qwen CLI and returning JSON core content package for task context.

 **Syntax**:
-```
+```bash
 /memory:prepare [--tool gemini|qwen] "task context description"
 ```

--- a/docs/commands/codex/review.md
+++ b/docs/commands/codex/review.md
@@ -19,7 +19,7 @@
 **Function**: Interactive code review using Codex CLI via ccw endpoint, supporting configurable review targets, models, and custom instructions.

 **Syntax**:
-```
+```bash
 /cli:codex-review [--uncommitted|--base <branch>|--commit <sha>] [--model <model>] [--title <title>] [prompt]
 ```

--- a/docs/features/api-settings.md
+++ b/docs/features/api-settings.md
@@ -22,8 +22,8 @@
 |---------|------|--------|
 | **Gemini** | Builtin | gemini-2.5-flash, gemini-2.5-pro |
 | **Qwen** | Builtin | coder-model |
-| **Codex** | Builtin | gpt-4o, gpt-4o-mini |
-| **Claude** | Builtin | claude-sonnet, claude-haiku |
+| **Codex** | Builtin | gpt-5.2 |
+| **Claude** | Builtin | sonnet, haiku |
 | **OpenCode** | Builtin | opencode/glm-4.7-free |

 ---
@@ -44,7 +44,8 @@
    },
    "codex": {
      "enabled": true,
-      "primaryModel": "gpt-4o",
+      "primaryModel": "gpt-5.2",
+      "secondaryModel": "gpt-5.2",
      "tags": [],
      "type": "builtin"
    }
--- a/docs/features/memory.md
+++ b/docs/features/memory.md
@@ -60,7 +60,7 @@ ccw memory search "authentication"
 ## Configuration

 ```json
-// ~/.claude/cli-settings.json
+// ~/.claude/settings.json
 {
  "memory": {
    "enabled": true,
--- a/docs/guide/ch01-what-is-claude-dms3.md
+++ b/docs/guide/ch01-what-is-claude-dms3.md
@@ -50,32 +50,24 @@

 ## 1.4 Architecture Overview

-```
-┌─────────────────────────────────────────────────────────────┐
-│                    Claude_dms3 Architecture                  │
-├─────────────────────────────────────────────────────────────┤
-│                                                              │
-│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
-│  │  CodexLens  │  │     CCW     │  │   Memory    │          │
-│  │ (Semantic   │  │  (CLI Call  │  │ (Persistent │          │
-│  │   Index)    │  │  Framework) │  │   Context)  │          │
-│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘          │
-│         │                │                │                  │
-│         └────────────────┼────────────────┘                  │
-│                          │                                   │
-│                    ┌─────┴─────┐                             │
-│                    │   Spec    │                             │
-│                    │  System   │                             │
-│                    └─────┬─────┘                             │
-│                          │                                   │
-│         ┌────────────────┼────────────────┐                  │
-│         │                │                │                  │
-│    ┌────┴────┐     ┌─────┴─────┐    ┌────┴────┐             │
-│    │  Hooks  │     │  Skills   │    │ Agents  │             │
-│    │(Inject) │     │(Reusable) │    │(Roles)  │             │
-│    └─────────┘     └───────────┘    └─────────┘             │
-│                                                              │
-└─────────────────────────────────────────────────────────────┘
+```mermaid
+graph TB
+    subgraph Claude_dms3_Architecture[Claude_dms3 Architecture]
+        A[CodexLens<br/>Semantic Index]
+        B[CCW<br/>CLI Call Framework]
+        C[Memory<br/>Persistent Context]
+        D[Spec System]
+        E[Hooks<br/>Inject]
+        F[Skills<br/>Reusable]
+        G[Agents<br/>Roles]
+
+        A --> D
+        B --> D
+        C --> D
+        D --> E
+        D --> F
+        D --> G
+    end
 ```

 ---
--- a/docs/guide/ch02-getting-started.md
+++ b/docs/guide/ch02-getting-started.md
@@ -20,8 +20,8 @@
 ### 2.1.2 Clone Project

 ```bash
-# Clone repository
-git clone https://github.com/your-repo/claude-dms3.git
+# Clone repository (replace with your fork or the actual repository URL)
+git clone https://github.com/[username]/claude-dms3.git
 cd claude-dms3

 # Install dependencies
@@ -30,24 +30,38 @@ npm install

 ### 2.1.3 Configure API Keys

-Configure API Keys in `~/.claude/settings.json`:
+Configure API Keys in `~/.claude/cli-tools.json`:

 ```json
 {
-  "openai": {
-    "apiKey": "sk-xxx"
-  },
-  "anthropic": {
-    "apiKey": "sk-ant-xxx"
-  },
-  "google": {
-    "apiKey": "AIza-xxx"
+  "tools": {
+    "gemini": {
+      "enabled": true,
+      "primaryModel": "gemini-2.5-flash",
+      "settings": {
+        "apiKey": "AIza-xxx"
+      }
+    },
+    "claude": {
+      "enabled": true,
+      "primaryModel": "sonnet",
+      "settings": {
+        "apiKey": "sk-ant-xxx"
+      }
+    },
+    "codex": {
+      "enabled": true,
+      "primaryModel": "gpt-5.2",
+      "settings": {
+        "apiKey": "sk-xxx"
+      }
+    }
  }
 }
 ```

 ::: tip Tip
-API Keys can also be configured at the project level in `.claude/settings.json`. Project-level configuration takes priority over global configuration.
+API Keys can also be configured at the project level in `.claude/cli-tools.json`. Project-level configuration takes priority over global configuration.
 :::

 ---
@@ -225,8 +239,8 @@ Or use Command Palette (Ctrl+Shift+P) and search "CCW Dashboard".
 **Q: Where to configure API Keys?**

 A: Can be configured in two locations:
- Global configuration: `~/.claude/settings.json`
- Project configuration: `.claude/settings.json`
+- Global configuration: `~/.claude/cli-tools.json`
+- Project configuration: `.claude/cli-tools.json`

 Project configuration takes priority over global configuration.

@@ -258,15 +272,15 @@ A: Select based on task objective:
 ### Installation Steps

 ```bash
-# 1. Clone project
-git clone https://github.com/your-repo/claude-dms3.git
+# 1. Clone project (replace with your fork or the actual repository URL)
+git clone https://github.com/[username]/claude-dms3.git
 cd claude-dms3

 # 2. Install dependencies
 npm install

 # 3. Configure API Keys
-# Edit ~/.claude/settings.json
+# Edit ~/.claude/cli-tools.json

 # 4. Start workflow session
 /workflow:session:start
--- a/docs/guide/ch03-core-concepts.md
+++ b/docs/guide/ch03-core-concepts.md
@@ -66,29 +66,15 @@ Codex Prompts are defined in the `.codex/prompts/` directory, optimized specific

 ## 3.2 Three-Layer Relationship

-```
-┌─────────────────────────────────────────────────────┐
-│                    User Request                      │
-└────────────────────┬────────────────────────────────┘
-                     │
-                     ▼
-┌─────────────────────────────────────────────────────┐
-│                  ccw (Orchestrator)                  │
-│  Intent Analysis → Workflow Selection → Execution    │
-└────────────────────┬────────────────────────────────┘
-                     │
-         ┌───────────┼───────────┐
-         ▼           ▼           ▼
-    ┌────────┐  ┌────────┐  ┌────────┐
-    │ Command│  │ Skill  │  │ Prompt │
-    │ (Atom) │  │(Composite)│ │(Template)│
-    └────────┘  └────────┘  └────────┘
-         │           │           │
-         └───────────┼───────────┘
-                     ▼
-            ┌────────────────┐
-            │ AI Model Call   │
-            └────────────────┘
+```mermaid
+graph TB
+    A[User Request] --> B[ccw Orchestrator<br/>Intent Analysis → Workflow Selection → Execution]
+    B --> C[Command Atom]
+    B --> D[Skill Composite]
+    B --> E[Prompt Template]
+    C --> F[AI Model Call]
+    D --> F
+    E --> F
 ```

 ### 3.2.1 Call Path
@@ -107,17 +93,13 @@ Codex Prompts are defined in the `.codex/prompts/` directory, optimized specific

 ### 3.3.1 Session Lifecycle

-```
-┌─────────┐     ┌─────────┐     ┌─────────┐     ┌─────────┐
-│  Start  │────▶│ Resume  │────▶│ Execute │────▶│Complete │
-│  Launch │     │  Resume │     │ Execute │     │ Complete│
-└─────────┘     └─────────┘     └─────────┘     └─────────┘
-     │                                │
-     ▼                                ▼
-┌─────────┐                     ┌─────────┐
-│  List   │                     │ Solidify│
-│  List   │                     │ Solidify│
-└─────────┘                     └─────────┘
+```mermaid
+graph LR
+    A[Start<br/>Launch] --> B[Resume<br/>Resume]
+    B --> C[Execute<br/>Execute]
+    C --> D[Complete<br/>Complete]
+    A --> E[List<br/>List]
+    D --> F[Solidify<br/>Solidify]
 ```

 ### 3.3.2 Session Commands
@@ -172,20 +154,11 @@ Claude_dms3 supports 8 team workflows, each defining different roles:

 Team members communicate via the message bus:

-```
-┌────────────┐                   ┌────────────┐
-│  Planner   │                   │ Executor   │
-└─────┬──────┘                   └──────┬─────┘
-      │                                 │
-      │  [plan_ready]                   │
-      ├────────────────────────────────▶
-      │                                 │
-      │                          [task_complete]
-      │◀────────────────────────────────┤
-      │                                 │
-      │   [plan_approved]               │
-      ├────────────────────────────────▶
-      │                                 │
+```mermaid
+graph LR
+    A[Planner] -->|plan_ready| B[Executor]
+    B -->|task_complete| A
+    A -->|plan_approved| B
 ```

 ### 3.4.3 Workflow Selection Guide
@@ -221,38 +194,25 @@ Team members communicate via the message bus:

 ## 3.6 Data Flow

-```
-User Request
-   │
-   ▼
-┌──────────────┐
-│  CCW Orchestrator│ ──▶ Intent Analysis
-└──────────────┘
-   │
-   ├─▶ Workflow Selection
-   │      │
-   │      ├─▶ PlanEx
-   │      ├─▶ IterDev
-   │      ├─▶ Lifecycle
-   │      └─▶ ...
-   │
-   ├─▶ Command Execution
-   │      │
-   │      ├─▶ Built-in commands
-   │      └─▶ Skill calls
-   │
-   ├─▶ AI Model Invocation
-   │      │
-   │      ├─▶ Gemini
-   │      ├─▶ Qwen
-   │      ├─▶ Codex
-   │      └─▶ Claude
-   │
-   └─▶ Result Return
-          │
-          ├─▶ File modification
-          ├─▶ Memory update
-          └─▶ Dashboard update
+```mermaid
+graph TB
+    A[User Request] --> B[CCW Orchestrator<br/>Intent Analysis]
+    B --> C[Workflow Selection]
+    B --> D[Command Execution]
+    B --> E[AI Model Invocation]
+    B --> F[Result Return]
+    C --> C1[PlanEx]
+    C --> C2[IterDev]
+    C --> C3[Lifecycle]
+    D --> D1[Built-in commands]
+    D --> D2[Skill calls]
+    E --> E1[Gemini]
+    E --> E2[Qwen]
+    E --> E3[Codex]
+    E --> E4[Claude]
+    F --> F1[File modification]
+    F --> F2[Memory update]
+    F --> F3[Dashboard update]
 ```

 ---
--- a/docs/guide/ch04-workflow-basics.md
+++ b/docs/guide/ch04-workflow-basics.md
@@ -29,31 +29,26 @@

 ### 4.2.2 Launch Method

-```
+```shell
 /workflow:plan
 ```

 Or describe requirements directly:

-```
+```plaintext
 Implement user login functionality, supporting email and phone number login
 ```

 ### 4.2.3 Workflow Process

-```
-┌─────────────┐     ┌─────────────┐     ┌─────────────┐
-│  Planner    │────▶│  Executor   │────▶│  Reviewer   │
-│  Planning   │     │  Execution  │     │  Review     │
-└─────────────┘     └─────────────┘     └─────────────┘
-     │                  │                    │
-     ▼                  ▼                    ▼
-┌─────────────┐  ┌─────────────┐    ┌─────────────┐
-│ Requirements│  │ Task        │    │ Code        │
-│ Analysis    │  │ Execution   │    │ Review      │
-│ Task Breakdown│  Code Gen    │    │ Quality     │
-│ Plan Gen    │  │ Test Write  │    │ Feedback    │
-└─────────────┘  └─────────────┘    └─────────────┘
+```mermaid
+graph LR
+    A[Planner<br/>Planning] -->|plan_ready| B[Executor<br/>Execution]
+    B -->|task_complete| C[Reviewer<br/>Review]
+
+    A --> A1[Requirements Analysis<br/>Task Breakdown<br/>Plan Gen]
+    B --> B1[Task Execution<br/>Code Gen<br/>Test Write]
+    C --> C1[Code Review<br/>Quality Check<br/>Feedback]
 ```

 ### 4.2.4 Output Artifacts
@@ -75,26 +70,20 @@ Implement user login functionality, supporting email and phone number login

 ### 4.3.2 Launch Method

-```
+```shell
 /refactor-cycle
 ```

 ### 4.3.3 Workflow Process

-```
-┌─────────────┐     ┌─────────────┐     ┌─────────────┐
-│  Discover   │────▶│   Plan      │────▶│  Refactor   │
-│  Discovery  │     │  Planning   │     │ Refactoring │
-└─────────────┘     └─────────────┘     └─────────────┘
-     │                  │                    │
-     ▼                  ▼                    ▼
-┌─────────────┐  ┌─────────────┐    ┌─────────────┐
-│ Code        │  │ Refactor    │    │ Code        │
-│ Analysis    │  │ Strategy    │    │ Modification│
-│ Problem     │  │ Priority    │    │ Test        │
-│ ID          │  │ Task Breakdown│  │ Verification│
-│ Tech Debt   │  │             │    │ Doc Update  │
-└─────────────┘  └─────────────┘    └─────────────┘
+```mermaid
+graph LR
+    A[Discover<br/>Discovery] -->|discoveries| B[Plan<br/>Planning]
+    B -->|plan| C[Refactor<br/>Refactoring]
+
+    A --> A1[Code Analysis<br/>Problem ID<br/>Tech Debt]
+    B --> B1[Refactor Strategy<br/>Priority<br/>Task Breakdown]
+    C --> C1[Code Modification<br/>Test Verification<br/>Doc Update]
 ```

 ### 4.3.4 Use Cases
@@ -117,7 +106,7 @@ Implement user login functionality, supporting email and phone number login

 ### 4.4.2 Launch Method

-```
+```shell
 /unified-execute-with-file <file>
 ```

@@ -132,17 +121,16 @@ Implement user login functionality, supporting email and phone number login

 ### 4.4.4 Workflow Process

-```
-┌─────────┐   ┌─────────┐   ┌─────────┐   ┌─────────┐
-│Analyzer │──▶│Developer│──▶│ Tester  │──▶│Reviewer │
-│ Analysis │   │ Develop │   │ Test    │   │ Review  │
-└─────────┘   └─────────┘   └─────────┘   └─────────┘
-     │            │            │            │
-     ▼            ▼            ▼            ▼
- Requirement   Code         Test         Quality
- Analysis      Implementation Verification Gate
- Code          Unit         Regression   Final
- Exploration   Test         Test         Confirmation
+```mermaid
+graph LR
+    A[Analyzer<br/>Analysis] --> B[Developer<br/>Develop]
+    B --> C[Tester<br/>Test]
+    C --> D[Reviewer<br/>Review]
+
+    A --> A1[Requirement Analysis<br/>Code Exploration]
+    B --> B1[Code Implementation<br/>Unit Test]
+    C --> C1[Test Verification<br/>Regression Test]
+    D --> D1[Quality Gate<br/>Final Confirmation]
 ```

 ---
@@ -166,17 +154,16 @@ Implement user login functionality, supporting email and phone number login

 ### 4.5.3 Workflow Process

-```
-┌─────────┐   ┌─────────┐   ┌─────────┐   ┌─────────┐
-│Discover │──▶│  Plan   │──▶│  Queue  │──▶│ Execute │
-│Discovery│   │  Plan   │   │  Queue  │   │ Execute │
-└─────────┘   └─────────┘   └─────────┘   └─────────┘
-     │            │            │            │
-     ▼            ▼            ▼            ▼
-  Identify      Analyze      Priority     Implement
-  Problems      Requirements Sort          Solution
-  Define        Plan         Dependencies Verify
-  Scope                      Results
+```mermaid
+graph LR
+    A[Discover<br/>Discovery] -->|issues| B[Plan<br/>Plan]
+    B -->|plan| C[Queue<br/>Queue]
+    C -->|queue| D[Execute<br/>Execute]
+
+    A --> A1[Identify Problems<br/>Define Scope]
+    B --> B1[Analyze Requirements<br/>Create Plan]
+    C --> C1[Priority Sort<br/>Dependencies]
+    D --> D1[Implement Solution<br/>Verify Results]
 ```

 ---
@@ -189,22 +176,20 @@ Implement user login functionality, supporting email and phone number login

 ### 4.6.2 Launch Method

-```
+```shell
 /integration-test-cycle
 ```

 ### 4.6.3 Workflow Process

-```
-┌─────────┐   ┌─────────┐   ┌─────────┐
-│Generate │──▶│ Execute │──▶│ Verify  │
-│ Generate │   │ Execute │   │ Verify  │
-└─────────┘   └─────────┘   └─────────┘
-     │            │            │
-     ▼            ▼            ▼
- Test Cases   Run Tests    Coverage
- Mock Data    Failure      Analysis
-              Analysis     Gap Fill
+```mermaid
+graph LR
+    A[Generate<br/>Generate] --> B[Execute<br/>Execute]
+    B --> C[Verify<br/>Verify]
+
+    A --> A1[Test Cases<br/>Mock Data]
+    B --> B1[Run Tests<br/>Failure Analysis]
+    C --> C1[Coverage Analysis<br/>Gap Fill]
 ```

 ---
@@ -217,7 +202,7 @@ Implement user login functionality, supporting email and phone number login

 ### 4.7.2 Launch Method

-```
+```shell
 /review-cycle
 ```

@@ -242,7 +227,7 @@ Implement user login functionality, supporting email and phone number login

 ### 4.8.2 Launch Method

-```
+```shell
 /brainstorm-with-file <file>
 ```

--- a/docs/guide/ch06-best-practices.md
+++ b/docs/guide/ch06-best-practices.md
@@ -68,15 +68,16 @@ Examples:

 ### 6.2.2 Review Process

-```
-┌─────────┐   ┌─────────┐   ┌─────────┐   ┌─────────┐
-│ Submit  │──▶│ Review  │──▶│ Feedback│──▶│  Fix    │
-│ Code    │   │ Code    │   │ Comments│   │ Issues  │
-└─────────┘   └─────────┘   └─────────┘   └─────────┘
-     │            │            │            │
-     ▼            ▼            ▼            ▼
-  Push PR      Auto Review  Manual Review  Fix Verify
-  CI Check     6 Dimensions  Code Walkthrough Re-review
+```mermaid
+graph LR
+    A[Submit Code] --> B[Review Code]
+    B --> C[Feedback Comments]
+    C --> D[Fix Issues]
+
+    A --> A1[Push PR<br/>CI Check]
+    B --> B1[Auto Review<br/>6 Dimensions]
+    C --> C1[Manual Review<br/>Code Walkthrough]
+    D --> D1[Fix Verify<br/>Re-review]
 ```

 ### 6.2.3 Review Checklist
--- a/docs/mcp/tools.md
+++ b/docs/mcp/tools.md
@@ -190,11 +190,11 @@ core_memory({

 ## MCP Configuration

-Configure MCP servers in `~/.claude/mcp.json`:
+Configure MCP servers in `~/.claude/settings.json`:

 ```json
 {
-  "servers": {
+  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem", "/path/to/allowed"]
--- a/docs/qa/test-report.md
+++ b/docs/qa/test-report.md
@@ -21,7 +21,7 @@
 **Initial State**: Build failed with critical Vue SFC parsing errors

 **Iteration 1**:
-```
+```text
 Error: At least one <template> or <script> is required in a single file component
 File: ColorSchemeSelector.vue
 Severity: CRITICAL
@@ -41,7 +41,7 @@ Severity: CRITICAL
 | VitePress config | Added `ignoreDeadLinks: true` for incomplete docs | ✅ Applied |

 **Final Build Result**:
-```
+```text
 ✓ building client + server bundles...
 ✓ rendering pages...
 build complete in 113.68s
@@ -62,7 +62,7 @@ build complete in 113.68s
 **Distribution Directory**: `D:\ccw-doc2\.vitepress\dist\`

 **Generated Assets**:
-```
+```text
 ✓ 404.html
 ✓ index.html
 ✓ README.html
--- a/docs/skills/claude-meta.md
+++ b/docs/skills/claude-meta.md
@@ -32,7 +32,7 @@
 **One-Liner**: Specification generator — 6-stage document chain generates complete specification package (product brief, PRD, architecture, Epics)

 **Trigger**:
-```
+```shell
 /spec-generator <idea>
 /spec-generator --continue        # Resume from checkpoint
 /spec-generator -y <idea>        # Auto mode
@@ -46,7 +46,7 @@
 - Documentation only: No code generation or execution — clean handoff to existing execution workflows

 **Architecture Overview**:
-```
+```plaintext
 Phase 0:   Specification Study (Read specs/ + templates/ - mandatory prerequisite)
           |
 Phase 1:   Discovery               -> spec-config.json + discovery-context.json
@@ -85,7 +85,7 @@ Phase 6:   Readiness Check         -> readiness-report.md + spec-summary.md
 | [templates/epics-template.md](templates/epics-template.md) | Epic/Story document template |

 **Output Structure**:
-```
+```plaintext
 .workflow/.spec/SPEC-{slug}-{YYYY-MM-DD}/
 ├── spec-config.json              # Session config + stage status
 ├── discovery-context.json        # Codebase exploration results (optional)
@@ -119,7 +119,7 @@ Phase 6:   Readiness Check         -> readiness-report.md + spec-summary.md
 **One-Liner**: Brainstorming — Interactive framework generation, multi-role parallel analysis, and cross-role synthesis

 **Trigger**:
-```
+```shell
 /brainstorm <topic>
 /brainstorm --count 3 "Build platform"
 /brainstorm -y "GOAL: Build SCOPE: Users" --count 5
@@ -169,7 +169,7 @@ Artifacts  N×Role  Synthesis  1×Role
 | `ux-expert` | UX Expert | User research, information architecture, journeys |

 **Output Structure**:
-```
+```plaintext
 .workflow/active/WFS-{topic}/
 ├── workflow-session.json              # Session metadata
 ├── .process/
@@ -204,7 +204,7 @@ Artifacts  N×Role  Synthesis  1×Role
 **One-Liner**: Skill generator — Meta-skill for creating new Claude Code Skills

 **Trigger**:
-```
+```shell
 /skill-generator
 /create skill
 /new skill
@@ -242,7 +242,7 @@ Artifacts  N×Role  Synthesis  1×Role
 | [templates/autonomous-action.md](templates/autonomous-action.md) | Autonomous action template |

 **Execution Flow**:
-```
+```plaintext
 Phase 0: Specification Study (Mandatory)
   - Read: ../_shared/SKILL-DESIGN-SPEC.md
   - Read: All templates/*.md files
@@ -269,7 +269,7 @@ Phase 5: Verification and Documentation
 ```

 **Output Structure** (Sequential):
-```
+```plaintext
 .claude/skills/{skill-name}/
 ├── SKILL.md                        # Entry file
 ├── phases/
@@ -294,7 +294,7 @@ Phase 5: Verification and Documentation
 **One-Liner**: CCW command help system — Command search, recommendations, documentation viewing

 **Trigger**:
-```
+```shell
 /ccw-help
 /ccw "task description"          # Auto-select workflow and execute
 /ccw-help search <keyword>       # Search commands
@@ -356,7 +356,7 @@ Phase 5: Verification and Documentation
 **One-Liner**: Skill tuning diagnosis — Automated diagnosis and optimization recommendations

 **Trigger**:
-```
+```shell
 /skill-tuning <skill-name>
 ```

@@ -367,7 +367,7 @@ Phase 5: Verification and Documentation
 - Verify improvements

 **Diagnosis Flow**:
-```
+```plaintext
 Analyze Skill → Identify issues → Generate recommendations → Apply optimizations → Verify effects
 ```

@@ -378,7 +378,7 @@ Analyze Skill → Identify issues → Generate recommendations → Apply optimiz
 **One-Liner**: Command generator — Generate Claude commands

 **Trigger**:
-```
+```shell
 /command-generator
 ```

@@ -394,7 +394,7 @@ Analyze Skill → Identify issues → Generate recommendations → Apply optimiz
 **One-Liner**: Issue management — Issue creation, updates, status management

 **Trigger**:
-```
+```shell
 /issue-manage
 /issue:new
 ```
--- a/docs/skills/claude-workflow.md
+++ b/docs/skills/claude-workflow.md
@@ -33,7 +33,7 @@
 **One-Liner**: Unified planning skill — 4-stage workflow, plan verification, interactive re-planning

 **Trigger**:
-```
+```shell
 /workflow:plan <task-description>
 /workflow:plan-verify --session <session-id>
 /workflow:replan --session <session-id> [task-id] "requirements"
@@ -61,7 +61,7 @@ default → 'plan'
 6. **Accumulated state**: planning-notes.md carries context across phases for N+1 decisions

 **Plan Mode Data Flow**:
-```
+```plaintext
 User Input (task description)
    ↓
 [Convert to structured format]
@@ -106,7 +106,7 @@ Plan Confirmation (User Decision Gate):
 **One-Liner**: Agent-coordinated execution — Systematic task discovery, agent coordination, and state tracking

 **Trigger**:
-```
+```shell
 /workflow:execute
 /workflow:execute --resume-session="WFS-auth"
 /workflow:execute --yes
@@ -125,7 +125,7 @@ Plan Confirmation (User Decision Gate):
 - **Completion selection**: Auto-complete session (run `/workflow:session:complete --yes`)

 **Execution Process**:
-```
+```plaintext
 Phase 1: Discovery
   ├─ Count active sessions
   └─ Decision:
@@ -188,7 +188,7 @@ Phase 5: Completion
 **One-Liner**: Lightweight quick planning — Quick planning and execution for super simple tasks

 **Trigger**:
-```
+```shell
 /workflow:lite-plan <simple-task>
 ```

@@ -210,7 +210,7 @@ Phase 5: Completion
 **One-Liner**: Multi-CLI collaborative planning — Analysis and planning with multiple CLI tools collaborating

 **Trigger**:
-```
+```shell
 /workflow:multi-cli-plan <task>
 ```

@@ -231,7 +231,7 @@ Phase 5: Completion
 **One-Liner**: TDD workflow — Test-driven development process

 **Trigger**:
-```
+```shell
 /workflow:tdd <feature-description>
 ```

@@ -242,7 +242,7 @@ Phase 5: Completion
 - Loop until passing

 **Pipeline**:
-```
+```plaintext
 Plan Tests → Write Tests → [Fail] → Implement Feature → [Pass] → Complete
                    ↑___________|
 ```
@@ -254,7 +254,7 @@ Plan Tests → Write Tests → [Fail] → Implement Feature → [Pass] → Compl
 **One-Liner**: Test-fix workflow — Diagnosis and fixing of failing tests

 **Trigger**:
-```
+```shell
 /workflow:test-fix <failing-tests>
 ```

@@ -265,7 +265,7 @@ Plan Tests → Write Tests → [Fail] → Implement Feature → [Pass] → Compl
 - Loop until passing

 **Pipeline**:
-```
+```plaintext
 Diagnose Failure → Identify Root Cause → [Code Issue] → Fix Code → Verify
                          ↑___________|
 ```
@@ -277,7 +277,7 @@ Diagnose Failure → Identify Root Cause → [Code Issue] → Fix Code → Verif
 **One-Liner**: Skill design workflow — Create new Claude Code Skills

 **Trigger**:
-```
+```shell
 /workflow:skill-designer <skill-idea>
 ```

@@ -289,7 +289,7 @@ Diagnose Failure → Identify Root Cause → [Code Issue] → Fix Code → Verif
 - Verification and documentation

 **Output Structure**:
-```
+```plaintext
 .claude/skills/{skill-name}/
 ├── SKILL.md              # Entry file
 ├── phases/
@@ -307,7 +307,7 @@ Diagnose Failure → Identify Root Cause → [Code Issue] → Fix Code → Verif
 **One-Liner**: Wave batch planning — Parallel processing planning for batch issues

 **Trigger**:
-```
+```shell
 /workflow:wave-plan <issue-list>
 ```

@@ -318,7 +318,7 @@ Diagnose Failure → Identify Root Cause → [Code Issue] → Fix Code → Verif
 - Execution queue generation

 **Wave Model**:
-```
+```plaintext
 Wave 1: Issue 1-5 → Parallel planning → Parallel execution
 Wave 2: Issue 6-10 → Parallel planning → Parallel execution
 ...
--- a/docs/skills/codex-index.md
+++ b/docs/skills/codex-index.md
@@ -40,7 +40,7 @@
 **One-Liner**: Full lifecycle orchestrator — spawn-wait-close pipeline for spec/implementation/test

 **Triggers**:
-```
+```shell
 /team-lifecycle <task-description>
 ```

@@ -65,7 +65,7 @@
 | fe-qa | Frontend QA, GC loop | 2.3 Deep Interaction |

 **Pipeline Definition**:
-```
+```plaintext
 Spec-only (6 beats):
  RESEARCH-001(+D1) → DRAFT-001(+D2) → DRAFT-002(+D3) → DRAFT-003(+D4) → DRAFT-004(+D5) → QUALITY-001(+D6)

@@ -77,7 +77,7 @@ Full-lifecycle (9 beats):
 ```

 **Beat Cycle**:
-```
+```plaintext
 event (phase advance / user resume)
      ↓
  [Orchestrator]
@@ -93,7 +93,7 @@ event (phase advance / user resume)
 ```

 **Session Directory**:
-```
+```plaintext
 .workflow/.team/TLS-<slug>-<date>/
 ├── team-session.json           # Pipeline state
 ├── spec/                       # Specification artifacts
@@ -112,7 +112,7 @@ event (phase advance / user resume)
 **One-Liner**: Multi-agent parallel development cycle — requirements analysis, exploration planning, code development, validation

 **Triggers**:
-```
+```shell
 /parallel-dev-cycle TASK="Implement feature"
 /parallel-dev-cycle --cycle-id=cycle-v1-20260122-abc123
 /parallel-dev-cycle --auto TASK="Add OAuth"
@@ -138,7 +138,7 @@ event (phase advance / user resume)
 - Eliminates redundant codebase exploration

 **Session Structure**:
-```
+```plaintext
 {projectRoot}/.workflow/.cycle/
 ├── {cycleId}.json                     # Main state file
 ├── {cycleId}.progress/
@@ -156,7 +156,7 @@ event (phase advance / user resume)
 ```

 **Execution Flow**:
-```
+```plaintext
 Phase 1: Session initialization
    ↓ cycleId, state, progressDir

@@ -190,13 +190,13 @@ Phase 4: Completion and summary
 **One-Liner**: Collaborative analysis — interactive analysis with documented discussions, inline exploration, and evolving understanding

 **Triggers**:
-```
+```shell
 /analyze-with-file TOPIC="<question>"
 /analyze-with-file TOPIC="--depth=deep"
 ```

 **Core Workflow**:
-```
+```plaintext
 Topic → Explore → Discuss → Document → Refine → Conclude → (Optional) Quick Execute
 ```

@@ -222,7 +222,7 @@ Topic → Explore → Discuss → Document → Refine → Conclude → (Optional
 **One-Liner**: Multi-perspective brainstorming — 4 perspectives (Product, Technical, Risk, User) parallel analysis

 **Triggers**:
-```
+```shell
 /brainstorm-with-file TOPIC="<idea>"
 ```

@@ -246,12 +246,12 @@ Topic → Explore → Discuss → Document → Refine → Conclude → (Optional
 **One-Liner**: Hypothesis-driven debugging — documented exploration, understanding evolution, analysis-assisted correction

 **Triggers**:
-```
+```shell
 /debug-with-file BUG="<bug description>"
 ```

 **Core Workflow**:
-```
+```plaintext
 Explore → Document → Log → Analyze → Correct Understanding → Fix → Verify
 ```

@@ -262,7 +262,7 @@ Explore → Document → Log → Analyze → Correct Understanding → Fix → V
 - **Learning preservation**: Retain insights from failed attempts

 **Session Folder Structure**:
-```
+```plaintext
 {projectRoot}/.workflow/.debug/DBG-{slug}-{date}/
 ├── debug.log           # NDJSON log (execution evidence)
 ├── understanding.md    # Exploration timeline + consolidated understanding
@@ -283,7 +283,7 @@ Explore → Document → Log → Analyze → Correct Understanding → Fix → V
 **One-Liner**: Collaborative planning — multi-agent collaborative planning (alternative to team-planex)

 **Triggers**:
-```
+```shell
 /collaborative-plan-with-file <task>
 ```

@@ -299,7 +299,7 @@ Explore → Document → Log → Analyze → Correct Understanding → Fix → V
 **One-Liner**: Universal execution engine — alternative to workflow-execute

 **Triggers**:
-```
+```shell
 /unified-execute-with-file <session>
 ```

@@ -315,7 +315,7 @@ Explore → Document → Log → Analyze → Correct Understanding → Fix → V
 **One-Liner**: Requirement roadmap planning

 **Triggers**:
-```
+```shell
 /roadmap-with-file <requirements>
 ```

@@ -331,7 +331,7 @@ Explore → Document → Log → Analyze → Correct Understanding → Fix → V
 **One-Liner**: Review cycle (Codex version)

 **Triggers**:
-```
+```shell
 /review-cycle <target>
 ```

@@ -347,7 +347,7 @@ Explore → Document → Log → Analyze → Correct Understanding → Fix → V
 **One-Liner**: Test-fix workflow

 **Triggers**:
-```
+```shell
 /workflow-test-fix-cycle <failing-tests>
 ```

@@ -364,7 +364,7 @@ Explore → Document → Log → Analyze → Correct Understanding → Fix → V
 **One-Liner**: Intelligent code cleanup

 **Triggers**:
-```
+```shell
 /clean <target>
 ```

@@ -380,7 +380,7 @@ Explore → Document → Log → Analyze → Correct Understanding → Fix → V
 **One-Liner**: CSV wave processing pipeline

 **Triggers**:
-```
+```shell
 /csv-wave-pipeline <csv-file>
 ```

@@ -396,7 +396,7 @@ Explore → Document → Log → Analyze → Correct Understanding → Fix → V
 **One-Liner**: Memory compression (Codex version)

 **Triggers**:
-```
+```shell
 /memory-compact
 ```

@@ -412,7 +412,7 @@ Explore → Document → Log → Analyze → Correct Understanding → Fix → V
 **One-Liner**: CLI tool execution specification

 **Triggers**:
-```
+```shell
 /ccw-cli-tools <command>
 ```

@@ -428,7 +428,7 @@ Explore → Document → Log → Analyze → Correct Understanding → Fix → V
 **One-Liner**: Issue discovery

 **Triggers**:
-```
+```shell
 /issue-discover <context>
 ```

--- a/docs/workflows/4-level.md
+++ b/docs/workflows/4-level.md
@@ -4,7 +4,7 @@ The CCW 4-level workflow system provides a structured approach to software devel

 ## Overview

-```
+```text
 Level 1: SPECIFICATION → Level 2: PLANNING → Level 3: IMPLEMENTATION → Level 4: VALIDATION
 ```

@@ -38,7 +38,7 @@ Level 1: SPECIFICATION → Level 2: PLANNING → Level 3: IMPLEMENTATION → Lev

 ### Example Tasks

-```
+```text
 RESEARCH-001 → DRAFT-001 → DRAFT-002 → DRAFT-003 → DRAFT-004 → QUALITY-001
 ```

@@ -95,7 +95,7 @@ RESEARCH-001 → DRAFT-001 → DRAFT-002 → DRAFT-003 → DRAFT-004 → QUALITY

 Tasks executed in topological order based on dependencies:

-```
+```text
 TASK-001 (no deps) → TASK-002 (depends on 001) → TASK-003 (depends on 002)
 ```

@@ -142,7 +142,7 @@ TASK-001 (no deps) → TASK-002 (depends on 001) → TASK-003 (depends on 002)

 Event-driven execution with coordinator orchestration:

-```
+```text
 Event           Coordinator              Workers
 ────────────────────────────────────────────────
 callback/resume → handleCallback ─────────────────┐
@@ -172,7 +172,7 @@ callback <───────────────────────

 For simple linear successions, workers can spawn successors directly:

-```
+```text
 [Worker A] complete
    → Check: 1 ready task? simple successor?
    → YES: Spawn Worker B directly
@@ -183,7 +183,7 @@ For simple linear successions, workers can spawn successors directly:

 Some epics can execute in parallel:

-```
+```text
 EPIC-003: Content Modules ──┐
                           ├──→ EPIC-005: Interaction Features
 EPIC-004: Search & Nav ────┘
--- a/docs/workflows/best-practices.md
+++ b/docs/workflows/best-practices.md
@@ -135,7 +135,7 @@ Optimize your CCW workflows for maximum efficiency and quality.

 ### Good Workflow

-```
+```text
 [Specification]
  ↓ Clear requirements with acceptance criteria
 [Planning]
@@ -149,7 +149,7 @@ Optimize your CCW workflows for maximum efficiency and quality.

 ### Problematic Workflow

-```
+```text
 [Specification]
  ↓ Vague requirements, no acceptance criteria
 [Planning]
--- a/docs/workflows/examples.md
+++ b/docs/workflows/examples.md
@@ -51,7 +51,7 @@ This is an output from `workflow:lite-plan` command.

 ### Execution Steps

-```bash
+```shell
 # Execute the plan
 ccw workflow:execute --session WFS-001
 ```
--- a/docs/workflows/index.md
+++ b/docs/workflows/index.md
@@ -4,7 +4,7 @@ CCW's 4-level workflow system orchestrates the entire development lifecycle from

 ## Workflow Levels

-```
+```text
 Level 1: SPECIFICATION
    ↓
 Level 2: PLANNING
@@ -90,8 +90,9 @@ Ensure quality.

 ```bash
 # Level 1: Specification
-Skill(skill="team-lifecycle-v4", args="Build user authentication system")
+Skill(skill="team-lifecycle-v5", args="Build user authentication system")
 # => Creates RESEARCH-001, DRAFT-001/002/003/004, QUALITY-001
+# Note: v5 is the latest version with team-worker architecture

 # Level 2: Planning (auto-triggered after QUALITY-001)
 # => Creates PLAN-001 with task breakdown
@@ -105,7 +106,7 @@ Skill(skill="team-lifecycle-v4", args="Build user authentication system")

 ## Workflow Visualization

-```
+```text
 ┌─────────────────────────────────────────────────────────────┐
 │                    WORKFLOW ORCHESTRATION                    │
 ├─────────────────────────────────────────────────────────────┤
--- a/docs/workflows/teams.md
+++ b/docs/workflows/teams.md
@@ -127,7 +127,7 @@ The latest architecture uses the `team-worker` agent with dynamic role assignmen

 ### Wave Pipeline (team-planex)

-```
+```text
 Wave 1: Plan ──────────────────────────────────┐
         ↓                                      │
 Wave 2: Exec  ←────────────────────────────────┘
@@ -139,7 +139,7 @@ Concurrent planning and execution - executor works on wave N while planner plans

 ### Generator-Critic Loop (team-iterdev)

-```
+```text
 Generator → Output → Critic → Feedback → Generator
                ↓
            Integrator → Validator
@@ -149,7 +149,7 @@ Iterative improvement through feedback cycles.

 ### CP-9 Dual-Track (team-uidesign)

-```
+```text
 Design Track:  Designer → Tokens → Style
                           ↓
 Implementation Track:        Developer → Components
@@ -161,7 +161,7 @@ Design and implementation proceed in parallel tracks.

 ### 5-Phase Lifecycle (team-lifecycle-v4)

-```
+```text
 1. Spec Planning (coordinator + spec-lead)
 2. Architecture Design (architect)
 3. Implementation Planning (impl-lead + dev team)
--- a/docs/zh/commands/claude/cli.md
+++ b/docs/zh/commands/claude/cli.md
@@ -26,7 +26,7 @@
 **功能**: 根据工作空间技术检测生成 `.gemini/` 和 `.qwen/` 配置目录，包含 settings.json 和 ignore 文件。

 **语法**:
-```
+```bash
 /cli:cli-init [--tool gemini|qwen|all] [--output path] [--preview]
 ```

@@ -75,7 +75,7 @@
 **功能**: 使用 Codex CLI 通过 ccw 端点进行交互式代码审查，支持可配置的审查目标、模型和自定义指令。

 **语法**:
-```
+```bash
 /cli:codex-review [--uncommitted|--base <branch>|--commit <sha>] [--model <model>] [--title <title>] [prompt]
 ```

--- a/docs/zh/commands/claude/core-orchestration.md
+++ b/docs/zh/commands/claude/core-orchestration.md
@@ -18,7 +18,7 @@
 **功能**: 主工作流编排器 - 意图分析→工作流选择→命令链执行

 **语法**:
-```
+```bash
 /ccw "任务描述"
 ```

@@ -80,7 +80,7 @@ graph TD
 **功能**: 命令编排工具 - 分析任务、推荐命令链、顺序执行、状态持久化

 **语法**:
-```
+```bash
 /ccw-coordinator "任务描述"
 ```

--- a/docs/zh/commands/claude/index.md
+++ b/docs/zh/commands/claude/index.md
@@ -111,6 +111,110 @@
 /ccw "实现用户认证" --yes
 ```

+## 使用示例
+
+### 快速分析
+
+```bash
+# 分析代码库结构
+/ccw "分析认证模块的架构"
+
+# 快速 Bug 诊断
+/ccw "诊断登录超时问题发生的原因"
+```
+
+### 规划与实施
+
+```bash
+# 创建实施计划
+/workflow:plan "添加 OAuth2 认证，支持 Google 和 GitHub 提供商"
+
+# 使用自动模式执行
+/workflow:execute --yes
+```
+
+### 代码审查
+
+```bash
+# 审查当前变更
+/cli:codex-review
+
+# 专注于特定区域
+/cli:codex-review "重点关注认证模块中的安全漏洞"
+```
+
+### 会话管理
+
+```bash
+# 列出所有会话
+/workflow:session:list
+
+# 恢复暂停的会话
+/workflow:session:resume "WFS-001"
+
+# 标记会话为完成
+/workflow:session:complete "WFS-001"
+```
+
+### Issue 工作流
+
+```bash
+# 从代码库中发现 Issue
+/issue:discover
+
+# 为特定 Issue 创建计划
+/issue:plan "ISSUE-001"
+
+# 执行修复
+/issue:execute --commit
+```
+
+### Memory 管理
+
+```bash
+# 捕获当前会话的学习内容
+/memory:capture "认证重构的关键见解"
+
+# 列出所有记忆
+/memory:list
+
+# 搜索记忆
+/memory:search "认证模式"
+```
+
+### CLI 工具调用
+
+```bash
+# 初始化 CLI 配置
+/cli:cli-init
+
+# 运行 Gemini 分析
+ccw cli -p "分析 src/auth 中的代码模式" --tool gemini --mode analysis
+
+# 使用特定规则模板运行
+ccw cli -p "审查代码质量" --tool gemini --mode analysis --rule analysis-review-code-quality
+```
+
+### UI 设计工作流
+
+```bash
+# 从参考图片提取样式
+/workflow:ui-design:style-extract --input "path/to/reference.png"
+
+# 生成原型
+/workflow:ui-design:generate --layout "dashboard" --tokens "design-tokens.json"
+```
+
+## 使用技巧
+
+1. **谨慎使用自动模式**：仅在常规任务时使用 `--yes` 或 `-y`。对于复杂决策保持手动确认。
+
+2. **会话持久化**：始终使用 `/workflow:session:complete` 完成会话以保留学习内容。
+
+3. **记忆捕获**：定期使用 `/memory:capture` 捕获重要见解以构建项目知识。
+
+4. **CLI 工具选择**：让 `/ccw` 自动选择合适的工具，或使用 `--tool gemini|qwen|codex` 显式指定。
+
 ## 相关文档

 - [Skills 参考](../skills/)
--- a/docs/zh/commands/claude/issue.md
+++ b/docs/zh/commands/claude/issue.md
@@ -32,7 +32,7 @@
 **功能**: 从 GitHub URL 或文本描述创建结构化 Issue，支持需求清晰度检测。

 **语法**:
-```
+```bash
 /issue:new [-y|--yes] <github-url | 文本描述> [--priority 1-5]
 ```

@@ -92,7 +92,7 @@ interface Issue {
 **功能**: 从多个角度（Bug、UX、测试、质量、安全、性能、可维护性、最佳实践）发现潜在 Issue。

 **语法**:
-```
+```bash
 /issue:discover [-y|--yes] <路径模式> [--perspectives=bug,ux,...] [--external]
 ```

@@ -125,7 +125,7 @@ interface Issue {
 **功能**: 通过用户提示发现 Issue，使用 Gemini 规划的迭代多代理探索，支持跨模块比较。

 **语法**:
-```
+```bash
 /issue:discover-by-prompt [-y|--yes] <提示> [--scope=src/**] [--depth=standard|deep] [--max-iterations=5]
 ```

@@ -151,7 +151,7 @@ interface Issue {
 **功能**: 批量规划 Issue 解决方案，使用 issue-plan-agent（探索+规划闭环）。

 **语法**:
-```
+```bash
 /issue:plan [-y|--yes] --all-pending <issue-id>[,<issue-id>,...] [--batch-size 3]
 ```

@@ -176,7 +176,7 @@ interface Issue {
 **功能**: 从绑定解决方案形成执行队列，使用 issue-queue-agent（解决方案级别）。

 **语法**:
-```
+```bash
 /issue:queue [-y|--yes] [--queues <n>] [--issue <id>]
 ```

@@ -201,7 +201,7 @@ interface Issue {
 **功能**: 执行队列，使用 DAG 并行编排（每个解决方案一次提交）。

 **语法**:
-```
+```bash
 /issue:execute [-y|--yes] --queue <queue-id> [--worktree [<existing-path>]]
 ```

@@ -223,7 +223,7 @@ interface Issue {
 **功能**: 转换规划工件（lite-plan、工作流会话、markdown）为 Issue 解决方案。

 **语法**:
-```
+```bash
 /issue:convert-to-plan [-y|--yes] [--issue <id>] [--supplement] <来源>
 ```

@@ -253,7 +253,7 @@ interface Issue {
 **功能**: 从头脑风暴会话想法转换为 Issue 并生成可执行解决方案。

 **语法**:
-```
+```bash
 /issue:from-brainstorm SESSION="会话-id" [--idea=<索引>] [--auto] [-y|--yes]
 ```

--- a/docs/zh/commands/claude/memory.md
+++ b/docs/zh/commands/claude/memory.md
@@ -33,7 +33,7 @@
 **功能**: 压缩当前会话记忆为结构化文本，提取目标、计划、文件、决策、约束、状态，并通过 MCP core_memory 工具保存。

 **语法**:
-```
+```bash
 /memory:compact [可选: 会话描述]
 ```

@@ -59,7 +59,7 @@
 **功能**: 快速笔记记录命令，捕获想法、片段、提醒和洞察供后续参考。

 **语法**:
-```
+```bash
 /memory:tips <笔记内容> [--tag <标签1,标签2>] [--context <上下文>]
 ```

@@ -84,7 +84,7 @@
 **功能**: 委托给 universal-executor 代理，通过 Gemini/Qwen CLI 分析项目并返回 JSON 核心内容包用于任务上下文。

 **语法**:
-```
+```bash
 /memory:load [--tool gemini|qwen] "任务上下文描述"
 ```

@@ -107,7 +107,7 @@
 **功能**: 更新所有 CLAUDE.md 文件，使用基于层的执行（Layer 3→1），批量代理处理（4 模块/代理）和 gemini→qwen→codex 回退。

 **语法**:
-```
+```bash
 /memory:update-full [--tool gemini|qwen|codex] [--path <目录>]
 ```

@@ -137,7 +137,7 @@
 **功能**: 更新 git 变更模块的 CLAUDE.md 文件，使用批量代理执行（4 模块/代理）和 gemini→qwen→codex 回退。

 **语法**:
-```
+```bash
 /memory:update-related [--tool gemini|qwen|codex]
 ```

@@ -158,7 +158,7 @@
 **功能**: 使用 CLI 执行生成完整项目文档（Layer 3→1），批量代理处理（4 模块/代理）和 gemini→qwen→codex 回退，<20 模块使用直接并行。

 **语法**:
-```
+```bash
 /memory:docs-full-cli [路径] [--tool <gemini|qwen|codex>]
 ```

@@ -179,7 +179,7 @@
 **功能**: 使用 CLI 执行生成 git 变更模块文档，批量代理处理（4 模块/代理）和 gemini→qwen→codex 回退，<15 模块使用直接执行。

 **语法**:
-```
+```bash
 /memory:docs-related-cli [--tool <gemini|qwen|codex>]
 ```

@@ -197,7 +197,7 @@
 **功能**: 从样式参考生成 SKILL 记忆包，便于加载和一致的设计系统使用。

 **语法**:
-```
+```bash
 /memory:style-skill-memory [包名] [--regenerate]
 ```

--- a/docs/zh/commands/claude/session.md
+++ b/docs/zh/commands/claude/session.md
@@ -30,7 +30,7 @@
 **功能**: 发现现有会话或启动新工作流会话，支持智能会话管理和冲突检测。

 **语法**:
-```
+```bash
 /workflow:session:start [--type <workflow|review|tdd|test|docs>] [--auto|--new] [可选: 任务描述]
 ```

@@ -99,7 +99,7 @@ graph TD
 **功能**: 列出所有工作流会话，支持状态过滤，显示会话元数据和进度信息。

 **语法**:
-```
+```bash
 /workflow:session:list
 ```

@@ -122,7 +122,7 @@ graph TD
 **功能**: 恢复最近暂停的工作流会话，支持自动会话发现和状态更新。

 **语法**:
-```
+```bash
 /workflow:session:resume
 ```

@@ -149,7 +149,7 @@ graph TD
 **功能**: 标记活动工作流会话为完成，归档并学习经验，更新清单并移除活动标志。

 **语法**:
-```
+```bash
 /workflow:session:complete [-y|--yes] [--detailed]
 ```

@@ -189,7 +189,7 @@ graph TD
 **功能**: 将会话学习和用户定义的约束结晶为永久项目指南。

 **语法**:
-```
+```bash
 /workflow:session:solidify [-y|--yes] [--type <convention|constraint|learning>] [--category <类别>] "规则或洞察"
 ```

--- a/docs/zh/commands/claude/ui-design.md
+++ b/docs/zh/commands/claude/ui-design.md
@@ -47,7 +47,7 @@
 **功能**: 交互式探索性 UI 设计工作流，以样式为中心的批量生成，从提示/图片创建设计变体，支持并行执行和用户选择。

 **语法**:
-```
+```bash
 /workflow:ui-design:explore-auto [--input "<值>"] [--targets "<列表>"] [--target-type "page|component"] [--session <id>] [--style-variants <数量>] [--layout-variants <数量>]
 ```

@@ -76,7 +76,7 @@
 **功能**: UI 设计工作流，支持直接代码/图片输入进行设计令牌提取和原型生成。

 **语法**:
-```
+```bash
 /workflow:ui-design:imitate-auto [--input "<值>"] [--session <id>]
 ```

@@ -98,7 +98,7 @@
 **功能**: 从参考图片或文本提示使用 Claude 分析提取设计样式，支持变体生成或精化模式。

 **语法**:
-```
+```bash
 /workflow:ui-design:style-extract [-y|--yes] [--design-id <id>] [--session <id>] [--images "<glob>"] [--prompt "<描述>"] [--variants <数量>] [--interactive] [--refine]
 ```

@@ -126,7 +126,7 @@
 **功能**: 从参考图片或文本提示使用 Claude 分析提取结构布局信息，支持变体生成或精化模式。

 **语法**:
-```
+```bash
 /workflow:ui-design:layout-extract [-y|--yes] [--design-id <id>] [--session <id>] [--images "<glob>"] [--prompt "<描述>"] [--targets "<列表>"] [--variants <数量>] [--device-type <desktop|mobile|tablet|responsive>] [--interactive] [--refine]
 ```

@@ -151,7 +151,7 @@
 **功能**: 从提示推断和图片引用提取动画和过渡模式，用于设计系统文档。

 **语法**:
-```
+```bash
 /workflow:ui-design:animation-extract [-y|--yes] [--design-id <id>] [--session <id>] [--images "<glob>"] [--focus "<类型>"] [--interactive] [--refine]
 ```

@@ -172,7 +172,7 @@
 **功能**: 从代码文件（CSS/JS/HTML/SCSS）导入设计系统，使用自动文件发现和并行代理分析。

 **语法**:
-```
+```bash
 /workflow:ui-design:import-from-code [--design-id <id>] [--session <id>] [--source <path>]
 ```

@@ -193,7 +193,7 @@
 **功能**: 编排器从代码提取样式并生成可共享引用包，支持预览（自动文件发现）。

 **语法**:
-```
+```bash
 /workflow:ui-design:codify-style <path> [--package-name <name>] [--output-dir <path>] [--overwrite]
 ```

@@ -216,7 +216,7 @@
 **功能**: 从设计运行提取生成多组件参考页面和文档。

 **语法**:
-```
+```bash
 /workflow:ui-design:reference-page-generator [--design-run <path>] [--package-name <name>] [--output-dir <path>]
 ```

@@ -234,7 +234,7 @@
 **功能**: 组装 UI 原型，将布局模板与设计令牌（默认动画支持）组合，纯组装器无新内容生成。

 **语法**:
-```
+```bash
 /workflow:ui-design:generate [--design-id <id>] [--session <id>]
 ```

@@ -252,7 +252,7 @@
 **功能**: 同步最终设计系统引用到头脑风暴工件，准备供 `/workflow:plan` 消费。

 **语法**:
-```
+```bash
 /workflow:ui-design:design-sync --session <session_id> [--selected-prototypes "<列表>"]
 ```

--- a/docs/zh/commands/claude/workflow.md
+++ b/docs/zh/commands/claude/workflow.md
@@ -72,7 +72,7 @@
 **功能**: 超轻量级多工具分析和直接执行。简单任务无工件，复杂任务自动在 `.workflow/.scratchpad/` 创建规划文档。

 **语法**:
-```
+```bash
 /workflow:lite-lite-lite [-y|--yes] <任务描述>
 ```

@@ -95,7 +95,7 @@
 **功能**: 轻量级交互式规划工作流，支持内存规划、代码探索和执行到 lite-execute。

 **语法**:
-```
+```bash
 /workflow:lite-plan [-y|--yes] [-e|--explore] "任务描述" | file.md
 ```

@@ -116,7 +116,7 @@
 **功能**: 基于内存计划、提示描述或文件内容执行任务。

 **语法**:
-```
+```bash
 /workflow:lite-execute [-y|--yes] [--in-memory] ["任务描述" | file-path]
 ```

@@ -137,7 +137,7 @@
 **功能**: 轻量级 Bug 诊断和修复工作流，支持智能严重程度评估和可选的热修复模式。

 **语法**:
-```
+```bash
 /workflow:lite-fix [-y|--yes] [--hotfix] "Bug 描述或 Issue 引用"
 ```

@@ -158,7 +158,7 @@
 **功能**: 5 阶段规划工作流，输出 IMPL_PLAN.md 和任务 JSON。

 **语法**:
-```
+```bash
 /workflow:plan [-y|--yes] "文本描述" | file.md
 ```

@@ -183,7 +183,7 @@
 **功能**: 协调代理执行工作流任务，支持自动会话发现、并行任务处理和状态跟踪。

 **语法**:
-```
+```bash
 /workflow:execute [-y|--yes] [--resume-session="session-id"]
 ```

@@ -201,7 +201,7 @@
 **功能**: 交互式工作流重新规划，支持会话级工件更新和边界澄清。

 **语法**:
-```
+```bash
 /workflow:replan [-y|--yes] [--session session-id] [task-id] "需求" | file.md [--interactive]
 ```

@@ -219,7 +219,7 @@
 **功能**: 多 CLI 协作规划工作流，使用 ACE 上下文收集和迭代交叉验证。

 **语法**:
-```
+```bash
 /workflow:multi-cli-plan [-y|--yes] <任务描述> [--max-rounds=3] [--tools=gemini,codex] [--mode=parallel|serial]
 ```

@@ -242,7 +242,7 @@
 **功能**: 交互式头脑风暴，多 CLI 协作、想法扩展和文档化思维演化。

 **语法**:
-```
+```bash
 /workflow:brainstorm-with-file [-y|--yes] [-c|--continue] [-m|--mode creative|structured] "想法或主题"
 ```

@@ -264,7 +264,7 @@
 **功能**: 交互式协作分析，有文档化的讨论、CLI 辅助探索和演化理解。

 **语法**:
-```
+```bash
 /workflow:analyze-with-file [-y|--yes] [-c|--continue] "主题或问题"
 ```

@@ -282,7 +282,7 @@
 **功能**: 交互式假设驱动调试，有文档化的探索、理解演化和 Gemini 辅助修正。

 **语法**:
-```
+```bash
 /workflow:debug-with-file [-y|--yes] "Bug 描述或错误信息"
 ```

@@ -300,7 +300,7 @@
 **功能**: 通用执行引擎，消费任何规划/头脑风暴/分析输出，支持最小进度跟踪、多代理协调和增量执行。

 **语法**:
-```
+```bash
 /workflow:unified-execute-with-file [-y|--yes] [-p|--plan <path>] [-m|--mode sequential|parallel] ["执行上下文"]
 ```

--- a/docs/zh/commands/codex/prep.md
+++ b/docs/zh/commands/codex/prep.md
@@ -38,7 +38,7 @@
 **功能**: 委托给 universal-executor 代理，通过 Gemini/Qwen CLI 分析项目并返回 JSON 核心内容包用于任务上下文。

 **语法**:
-```
+```bash
 /memory:prepare [--tool gemini|qwen] "任务上下文描述"
 ```

--- a/docs/zh/commands/codex/review.md
+++ b/docs/zh/commands/codex/review.md
@@ -19,7 +19,7 @@
 **功能**: 使用 Codex CLI 通过 ccw 端点进行交互式代码审查，支持可配置的审查目标、模型和自定义指令。

 **语法**:
-```
+```bash
 /cli:codex-review [--uncommitted|--base <分支>|--commit <sha>] [--model <模型>] [--title <标题>] [提示]
 ```

--- a/docs/zh/features/spec.md
+++ b/docs/zh/features/spec.md
@@ -80,7 +80,7 @@ ccw spec init
 ```

 **输出**:
-```
+```bash
 Initializing spec system...

 Directories created:
--- a/docs/zh/guide/ch01-what-is-claude-dms3.md
+++ b/docs/zh/guide/ch01-what-is-claude-dms3.md
@@ -50,32 +50,24 @@

 ## 1.4 架构概览

-```
-┌─────────────────────────────────────────────────────────────┐
-│                    Claude_dms3 架构                          │
-├─────────────────────────────────────────────────────────────┤
-│                                                              │
-│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
-│  │  CodexLens  │  │     CCW     │  │   Memory    │          │
-│  │  (语义索引)  │  │  (CLI调用   │  │  (持久化    │          │
-│  │             │  │   框架)     │  │   上下文)   │          │
-│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘          │
-│         │                │                │                  │
-│         └────────────────┼────────────────┘                  │
-│                          │                                   │
-│                    ┌─────┴─────┐                             │
-│                    │   Spec    │                             │
-│                    │  规范系统  │                             │
-│                    └─────┬─────┘                             │
-│                          │                                   │
-│         ┌────────────────┼────────────────┐                  │
-│         │                │                │                  │
-│    ┌────┴────┐     ┌─────┴─────┐    ┌────┴────┐             │
-│    │  Hooks  │     │  Skills   │    │ Agents  │             │
-│    │ (注入)  │     │ (可复用)  │    │ (角色)  │             │
-│    └─────────┘     └───────────┘    └─────────┘             │
-│                                                              │
-└─────────────────────────────────────────────────────────────┘
+```mermaid
+graph TB
+    subgraph Claude_dms3_Architecture[Claude_dms3 架构]
+        A[CodexLens<br/>语义索引]
+        B[CCW<br/>CLI调用框架]
+        C[Memory<br/>持久化上下文]
+        D[Spec 规范系统]
+        E[Hooks<br/>注入]
+        F[Skills<br/>可复用]
+        G[Agents<br/>角色]
+
+        A --> D
+        B --> D
+        C --> D
+        D --> E
+        D --> F
+        D --> G
+    end
 ```

 ---
--- a/docs/zh/guide/ch03-core-concepts.md
+++ b/docs/zh/guide/ch03-core-concepts.md
@@ -66,29 +66,15 @@ Codex Prompts 定义在 `.codex/prompts/` 目录，专为 Codex 模型优化。

 ## 3.2 三层关系

-```
-┌─────────────────────────────────────────────────────┐
-│                    用户请求                          │
-└────────────────────┬────────────────────────────────┘
-                     │
-                     ▼
-┌─────────────────────────────────────────────────────┐
-│                  ccw (编排器)                        │
-│  意图分析 → 工作流选择 → 命令链执行                  │
-└────────────────────┬────────────────────────────────┘
-                     │
-         ┌───────────┼───────────┐
-         ▼           ▼           ▼
-    ┌────────┐  ┌────────┐  ┌────────┐
-    │ Command│  │ Skill  │  │ Prompt │
-    │ (原子) │  │ (复合) │  │(模板)  │
-    └────────┘  └────────┘  └────────┘
-         │           │           │
-         └───────────┼───────────┘
-                     ▼
-            ┌────────────────┐
-            │  AI 模型调用    │
-            └────────────────┘
+```mermaid
+graph TB
+    A[用户请求] --> B[ccw 编排器<br/>意图分析 → 工作流选择 → 命令链执行]
+    B --> C[Command 原子]
+    B --> D[Skill 复合]
+    B --> E[Prompt 模板]
+    C --> F[AI 模型调用]
+    D --> F
+    E --> F
 ```

 ### 3.2.1 调用路径
@@ -107,17 +93,13 @@ Codex Prompts 定义在 `.codex/prompts/` 目录，专为 Codex 模型优化。

 ### 3.3.1 会话生命周期

-```
-┌─────────┐     ┌─────────┐     ┌─────────┐     ┌─────────┐
-│  Start  │────▶│ Resume  │────▶│ Execute │────▶│Complete │
-│  启动   │     │  恢复   │     │  执行   │     │  完成   │
-└─────────┘     └─────────┘     └─────────┘     └─────────┘
-     │                                │
-     ▼                                ▼
-┌─────────┐                     ┌─────────┐
-│  List   │                     │ Solidify│
-│  列出   │                     │  固化   │
-└─────────┘                     └─────────┘
+```mermaid
+graph LR
+    A[Start<br/>启动] --> B[Resume<br/>恢复]
+    B --> C[Execute<br/>执行]
+    C --> D[Complete<br/>完成]
+    A --> E[List<br/>列出]
+    D --> F[Solidify<br/>固化]
 ```

 ### 3.3.2 会话命令
@@ -172,20 +154,11 @@ Claude_dms3 支持 8 种团队工作流，每种工作流定义了不同的角

 团队成员通过消息总线通信：

-```
-┌────────────┐                   ┌────────────┐
-│  Planner   │                   │ Executor   │
-└─────┬──────┘                   └──────┬─────┘
-      │                                 │
-      │  [plan_ready]                   │
-      ├────────────────────────────────▶
-      │                                 │
-      │                          [task_complete]
-      │◀────────────────────────────────┤
-      │                                 │
-      │   [plan_approved]               │
-      ├────────────────────────────────▶
-      │                                 │
+```mermaid
+graph LR
+    A[Planner] -->|plan_ready| B[Executor]
+    B -->|task_complete| A
+    A -->|plan_approved| B
 ```

 ### 3.4.3 工作流选择指南
@@ -221,38 +194,25 @@ Claude_dms3 支持 8 种团队工作流，每种工作流定义了不同的角

 ## 3.6 数据流

-```
-用户请求
-   │
-   ▼
-┌──────────────┐
-│  CCW 编排器   │ ──▶ 意图分析
-└──────────────┘
-   │
-   ├─▶ Workflow 选择
-   │      │
-   │      ├─▶ PlanEx
-   │      ├─▶ IterDev
-   │      ├─▶ Lifecycle
-   │      └─▶ ...
-   │
-   ├─▶ Command 执行
-   │      │
-   │      ├─▶ 内置命令
-   │      └─▶ Skill 调用
-   │
-   ├─▶ AI 模型调用
-   │      │
-   │      ├─▶ Gemini
-   │      ├─▶ Qwen
-   │      ├─▶ Codex
-   │      └─▶ Claude
-   │
-   └─▶ 结果返回
-          │
-          ├─▶ 文件修改
-          ├─▶ Memory 更新
-          └─▶ Dashboard 更新
+```mermaid
+graph TB
+    A[用户请求] --> B[CCW 编排器<br/>意图分析]
+    B --> C[Workflow 选择]
+    B --> D[Command 执行]
+    B --> E[AI 模型调用]
+    B --> F[结果返回]
+    C --> C1[PlanEx]
+    C --> C2[IterDev]
+    C --> C3[Lifecycle]
+    D --> D1[内置命令]
+    D --> D2[Skill 调用]
+    E --> E1[Gemini]
+    E --> E2[Qwen]
+    E --> E3[Codex]
+    E --> E4[Claude]
+    F --> F1[文件修改]
+    F --> F2[Memory 更新]
+    F --> F3[Dashboard 更新]
 ```

 ---
--- a/docs/zh/guide/ch04-workflow-basics.md
+++ b/docs/zh/guide/ch04-workflow-basics.md
@@ -29,30 +29,26 @@

 ### 4.2.2 启动方式

-```
+```shell
 /workflow:plan
 ```

 或直接描述需求：

-```
+```plaintext
 实现用户登录功能，支持邮箱和手机号登录
 ```

 ### 4.2.3 工作流程

-```
-┌─────────────┐     ┌─────────────┐     ┌─────────────┐
-│  Planner    │────▶│  Executor   │────▶│  Reviewer   │
-│  规划阶段    │     │  执行阶段    │     │  审查阶段    │
-└─────────────┘     └─────────────┘     └─────────────┘
-     │                  │                    │
-     ▼                  ▼                    ▼
-┌─────────────┐  ┌─────────────┐    ┌─────────────┐
-│ 需求分析    │  │ 任务执行    │    │ 代码审查    │
-│ 任务分解    │  │ 代码生成    │    │ 质量检查    │
-│ 计划生成    │  │ 测试编写    │    │ 反馈修复    │
-└─────────────┘  └─────────────┘    └─────────────┘
+```mermaid
+graph LR
+    A[Planner<br/>规划阶段] -->|plan_ready| B[Executor<br/>执行阶段]
+    B -->|task_complete| C[Reviewer<br/>审查阶段]
+
+    A --> A1[需求分析<br/>任务分解<br/>计划生成]
+    B --> B1[任务执行<br/>代码生成<br/>测试编写]
+    C --> C1[代码审查<br/>质量检查<br/>反馈修复]
 ```

 ### 4.2.4 输出产物
@@ -74,24 +70,20 @@

 ### 4.3.2 启动方式

-```
+```shell
 /refactor-cycle
 ```

 ### 4.3.3 工作流程

-```
-┌─────────────┐     ┌─────────────┐     ┌─────────────┐
-│  Discover   │────▶│   Plan      │────▶│  Refactor   │
-│  发现阶段    │     │  规划阶段    │     │  重构阶段    │
-└─────────────┘     └─────────────┘     └─────────────┘
-     │                  │                    │
-     ▼                  ▼                    ▼
-┌─────────────┐  ┌─────────────┐    ┌─────────────┐
-│ 代码分析    │  │ 重构策略    │    │ 代码修改    │
-│ 问题识别    │  │ 优先级排序  │    │ 测试验证    │
-│ 技术债记录  │  │ 任务分解    │    │ 文档更新    │
-└─────────────┘  └─────────────┘    └─────────────┘
+```mermaid
+graph LR
+    A[Discover<br/>发现阶段] -->|discoveries| B[Plan<br/>规划阶段]
+    B -->|plan| C[Refactor<br/>重构阶段]
+
+    A --> A1[代码分析<br/>问题识别<br/>技术债记录]
+    B --> B1[重构策略<br/>优先级排序<br/>任务分解]
+    C --> C1[代码修改<br/>测试验证<br/>文档更新]
 ```

 ### 4.3.4 使用场景
@@ -114,7 +106,7 @@

 ### 4.4.2 启动方式

-```
+```shell
 /unified-execute-with-file <file>
 ```

@@ -129,15 +121,16 @@

 ### 4.4.4 工作流程

-```
-┌─────────┐   ┌─────────┐   ┌─────────┐   ┌─────────┐
-│Analyzer │──▶│Developer│──▶│ Tester  │──▶│Reviewer │
-│ 分析    │   │ 开发    │   │ 测试    │   │ 审查    │
-└─────────┘   └─────────┘   └─────────┘   └─────────┘
-     │            │            │            │
-     ▼            ▼            ▼            ▼
- 需求分析      代码实现      测试验证      质量把关
- 代码探索      单元测试      回归测试      最终确认
+```mermaid
+graph LR
+    A[Analyzer<br/>分析] --> B[Developer<br/>开发]
+    B --> C[Tester<br/>测试]
+    C --> D[Reviewer<br/>审查]
+
+    A --> A1[需求分析<br/>代码探索]
+    B --> B1[代码实现<br/>单元测试]
+    C --> C1[测试验证<br/>回归测试]
+    D --> D1[质量把关<br/>最终确认]
 ```

 ---
@@ -161,15 +154,16 @@

 ### 4.5.3 工作流程

-```
-┌─────────┐   ┌─────────┐   ┌─────────┐   ┌─────────┐
-│Discover │──▶│  Plan   │──▶│  Queue  │──▶│ Execute │
-│ 发现    │   │ 规划    │   │ 排队    │   │ 执行    │
-└─────────┘   └─────────┘   └─────────┘   └─────────┘
-     │            │            │            │
-     ▼            ▼            ▼            ▼
- 识别问题      分析需求      优先级排序    实现方案
- 定义范围      制定计划      依赖关系      验证结果
+```mermaid
+graph LR
+    A[Discover<br/>发现] -->|issues| B[Plan<br/>规划]
+    B -->|plan| C[Queue<br/>排队]
+    C -->|queue| D[Execute<br/>执行]
+
+    A --> A1[识别问题<br/>定义范围]
+    B --> B1[分析需求<br/>制定计划]
+    C --> C1[优先级排序<br/>依赖关系]
+    D --> D1[实现方案<br/>验证结果]
 ```

 ---
@@ -182,21 +176,20 @@

 ### 4.6.2 启动方式

-```
+```shell
 /integration-test-cycle
 ```

 ### 4.6.3 工作流程

-```
-┌─────────┐   ┌─────────┐   ┌─────────┐
-│Generate │──▶│ Execute │──▶│ Verify  │
-│ 生成    │   │ 执行    │   │ 验证    │
-└─────────┘   └─────────┘   └─────────┘
-     │            │            │
-     ▼            ▼            ▼
- 测试用例      运行测试      覆盖率分析
- Mock 数据     失败分析      缺口补充
+```mermaid
+graph LR
+    A[Generate<br/>生成] --> B[Execute<br/>执行]
+    B --> C[Verify<br/>验证]
+
+    A --> A1[测试用例<br/>Mock 数据]
+    B --> B1[运行测试<br/>失败分析]
+    C --> C1[覆盖率分析<br/>缺口补充]
 ```

 ---
@@ -209,7 +202,7 @@

 ### 4.7.2 启动方式

-```
+```shell
 /review-cycle
 ```

@@ -234,7 +227,7 @@

 ### 4.8.2 启动方式

-```
+```shell
 /brainstorm-with-file <file>
 ```

--- a/docs/zh/guide/ch06-best-practices.md
+++ b/docs/zh/guide/ch06-best-practices.md
@@ -68,15 +68,16 @@

 ### 6.2.2 审查流程

-```
-┌─────────┐   ┌─────────┐   ┌─────────┐   ┌─────────┐
-│  提交   │──▶│  审查   │──▶│  反馈   │──▶│  修复   │
-│ 代码    │   │ 代码    │   │ 意见    │   │ 问题    │
-└─────────┘   └─────────┘   └─────────┘   └─────────┘
-     │            │            │            │
-     ▼            ▼            ▼            ▼
-  Push PR      自动审查      人工审查      修复验证
-  CI 检查      6 维度检查    代码走查      再次审查
+```mermaid
+graph LR
+    A[提交代码] --> B[审查代码]
+    B --> C[反馈意见]
+    C --> D[修复问题]
+
+    A --> A1[Push PR<br/>CI检查]
+    B --> B1[自动审查<br/>6维度检查]
+    C --> C1[人工审查<br/>代码走查]
+    D --> D1[修复验证<br/>再次审查]
 ```

 ### 6.2.3 审查清单
--- a/docs/zh/guide/installation.md
+++ b/docs/zh/guide/installation.md
@@ -113,6 +113,78 @@ npm uninstall -g claude-code-workflow
 rm -rf ~/.claude
 ```

+## 故障排除
+
+### 权限问题
+
+如果遇到权限错误：
+
+```bash
+# 使用 sudo（不推荐）
+sudo npm install -g claude-code-workflow
+
+# 或修复 npm 权限（推荐）
+mkdir ~/.npm-global
+npm config set prefix '~/.npm-global'
+export PATH=~/.npm-global/bin:$PATH
+```
+
+### PATH 问题
+
+将 npm 全局 bin 添加到您的 PATH：
+
+```bash
+# 对于 bash/zsh
+echo 'export PATH=$(npm config get prefix)/bin:$PATH' >> ~/.bashrc
+
+# 对于 fish
+echo 'set -gx PATH (npm config get prefix)/bin $PATH' >> ~/.config/fish/config.fish
+```
+
 ::: info 下一步
 安装完成后，查看[第一个工作流](./first-workflow.md)指南。
 :::
+
+## 快速开始示例
+
+安装完成后，尝试以下命令验证一切正常：
+
+```bash
+# 1. 在您的项目中初始化
+cd your-project
+ccw init
+
+# 2. 尝试简单的分析
+ccw cli -p "分析项目结构" --tool gemini --mode analysis
+
+# 3. 运行主编排器
+/ccw "总结代码库架构"
+
+# 4. 检查可用命令
+ccw --help
+```
+
+### 预期输出
+
+```
+$ ccw --version
+CCW v7.0.5
+
+$ ccw init
+✔ Created .claude/CLAUDE.md
+✔ Created .ccw/workflows/
+✔ Configuration complete
+
+$ ccw cli -p "Analyze project" --tool gemini --mode analysis
+Analyzing with Gemini...
+✔ Analysis complete
+```
+
+### 常见首次使用问题
+
+| 问题 | 解决方案 |
+|-------|----------|
+| `ccw: command not found` | 将 npm 全局 bin 添加到 PATH，或重新安装 |
+| `Permission denied` | 使用 `sudo` 或修复 npm 权限 |
+| `API key not found` | 在 `~/.claude/cli-tools.json` 中配置 API 密钥 |
+| `Node version mismatch` | 更新到 Node.js >= 18.0.0 |
--- a/docs/zh/skills/claude-meta.md
+++ b/docs/zh/skills/claude-meta.md
@@ -32,7 +32,7 @@
 **一句话定位**: 规范生成器 — 6 阶段文档链生成完整规范包（产品简报、PRD、架构、Epics）

 **触发**:
-```
+```shell
 /spec-generator <idea>
 /spec-generator --continue        # 从断点恢复
 /spec-generator -y <idea>        # 自动模式
@@ -46,7 +46,7 @@
 - 纯文档：无代码生成或执行 — 干净移交给现有执行工作流

 **架构概览**:
-```
+```plaintext
 Phase 0:   Specification Study (Read specs/ + templates/ - mandatory prerequisite)
           |
 Phase 1:   Discovery               -> spec-config.json + discovery-context.json
@@ -85,7 +85,7 @@ Phase 6:   Readiness Check         -> readiness-report.md + spec-summary.md
 | [templates/epics-template.md](templates/epics-template.md) | Epic/Story 文档模板 |

 **输出结构**:
-```
+```plaintext
 .workflow/.spec/SPEC-{slug}-{YYYY-MM-DD}/
 ├── spec-config.json              # 会话配置 + 阶段状态
 ├── discovery-context.json        # 代码库探索结果（可选）
@@ -119,7 +119,7 @@ Phase 6:   Readiness Check         -> readiness-report.md + spec-summary.md
 **一句话定位**: 头脑风暴 — 交互式框架生成、多角色并行分析和跨角色综合

 **触发**:
-```
+```shell
 /brainstorm <topic>
 /brainstorm --count 3 "Build platform"
 /brainstorm -y "GOAL: Build SCOPE: Users" --count 5
@@ -169,7 +169,7 @@ Artifacts  N×Role  Synthesis  1×Role
 | `ux-expert` | UX专家 | 用户研究、信息架构、旅程 |

 **输出结构**:
-```
+```plaintext
 .workflow/active/WFS-{topic}/
 ├── workflow-session.json              # 会话元数据
 ├── .process/
@@ -204,7 +204,7 @@ Artifacts  N×Role  Synthesis  1×Role
 **一句话定位**: Skill 生成器 — 元技能，用于创建新的 Claude Code Skills

 **触发**:
-```
+```shell
 /skill-generator
 /create skill
 /new skill
@@ -242,7 +242,7 @@ Artifacts  N×Role  Synthesis  1×Role
 | [templates/autonomous-action.md](templates/autonomous-action.md) | 自治动作模板 |

 **执行流程**:
-```
+```plaintext
 Phase 0: 规范研究（强制）
   - Read: ../_shared/SKILL-DESIGN-SPEC.md
   - Read: All templates/*.md files
@@ -269,7 +269,7 @@ Phase 5: 验证和文档
 ```

 **输出结构** (Sequential):
-```
+```plaintext
 .claude/skills/{skill-name}/
 ├── SKILL.md                        # 入口文件
 ├── phases/
@@ -294,7 +294,7 @@ Phase 5: 验证和文档
 **一句话定位**: CCW 命令帮助系统 — 命令搜索、推荐、文档查看

 **触发**:
-```
+```shell
 /ccw-help
 /ccw "task description"          # 自动选择工作流并执行
 /ccw-help search <keyword>       # 搜索命令
@@ -356,7 +356,7 @@ Phase 5: 验证和文档
 **一句话定位**: Skill 调优诊断 — 自动化诊断和优化建议

 **触发**:
-```
+```shell
 /skill-tuning <skill-name>
 ```

@@ -367,7 +367,7 @@ Phase 5: 验证和文档
 - 验证改进

 **诊断流程**:
-```
+```plaintext
 分析 Skill → 识别问题 → 生成建议 → 应用优化 → 验证效果
 ```

@@ -378,7 +378,7 @@ Phase 5: 验证和文档
 **一句话定位**: 命令生成器 — 生成 Claude 命令

 **触发**:
-```
+```shell
 /command-generator
 ```

@@ -394,7 +394,7 @@ Phase 5: 验证和文档
 **一句话定位**: Issue 管理 — Issue 创建、更新、状态管理

 **触发**:
-```
+```shell
 /issue-manage
 /issue:new
 ```
--- a/docs/zh/skills/claude-workflow.md
+++ b/docs/zh/skills/claude-workflow.md
@@ -33,7 +33,7 @@
 **一句话定位**: 统一规划技能 — 4 阶段工作流、计划验证、交互式重规划

 **触发**:
-```
+```shell
 /workflow:plan <task-description>
 /workflow:plan-verify --session <session-id>
 /workflow:replan --session <session-id> [task-id] "requirements"
@@ -61,7 +61,7 @@ default → 'plan'
 6. **累积状态**: planning-notes.md 跨阶段携带上下文用于 N+1 决策

 **计划模式数据流**:
-```
+```plaintext
 用户输入（任务描述）
    ↓
 [转换为结构化格式]
@@ -106,7 +106,7 @@ Phase 4: task-generate-agent --session sessionId
 **一句话定位**: 代理协调执行 — 系统化任务发现、代理协调和状态跟踪

 **触发**:
-```
+```shell
 /workflow:execute
 /workflow:execute --resume-session="WFS-auth"
 /workflow:execute --yes
@@ -125,7 +125,7 @@ Phase 4: task-generate-agent --session sessionId
 - **完成选择**: 自动完成会话（运行 `/workflow:session:complete --yes`）

 **执行过程**:
-```
+```plaintext
 Phase 1: 发现
   ├─ 计算活跃会话数
   └─ 决策:
@@ -188,7 +188,7 @@ Phase 5: 完成
 **一句话定位**: 轻量级快速规划 — 超简单任务的快速规划和执行

 **触发**:
-```
+```shell
 /workflow:lite-plan <simple-task>
 ```

@@ -210,7 +210,7 @@ Phase 5: 完成
 **一句话定位**: 多 CLI 协作规划 — 多个 CLI 工具协作的分析和规划

 **触发**:
-```
+```shell
 /workflow:multi-cli-plan <task>
 ```

@@ -231,7 +231,7 @@ Phase 5: 完成
 **一句话定位**: TDD 工作流 — 测试驱动的开发流程

 **触发**:
-```
+```shell
 /workflow:tdd <feature-description>
 ```

@@ -242,7 +242,7 @@ Phase 5: 完成
 - 循环直到通过

 **流水线**:
-```
+```plaintext
 规划测试 → 编写测试 → [失败] → 实现功能 → [通过] → 完成
                    ↑___________|
 ```
@@ -254,7 +254,7 @@ Phase 5: 完成
 **一句话定位**: 测试修复工作流 — 失败测试的诊断和修复

 **触发**:
-```
+```shell
 /workflow:test-fix <failing-tests>
 ```

@@ -265,7 +265,7 @@ Phase 5: 完成
 - 循环直到通过

 **流水线**:
-```
+```plaintext
 诊断失败 → 确定根因 → [代码问题] → 修复代码 → 验证
                          ↑___________|
 ```
@@ -277,7 +277,7 @@ Phase 5: 完成
 **一句话定位**: Skill 设计工作流 — 创建新的 Claude Code Skills

 **触发**:
-```
+```shell
 /workflow:skill-designer <skill-idea>
 ```

@@ -289,7 +289,7 @@ Phase 5: 完成
 - 验证和文档

 **输出结构**:
-```
+```plaintext
 .claude/skills/{skill-name}/
 ├── SKILL.md              # 入口文件
 ├── phases/
@@ -307,7 +307,7 @@ Phase 5: 完成
 **一句话定位**: Wave 批处理规划 — 批量 Issue 的并行处理规划

 **触发**:
-```
+```shell
 /workflow:wave-plan <issue-list>
 ```

@@ -318,7 +318,7 @@ Phase 5: 完成
 - 执行队列生成

 **Wave 模型**:
-```
+```plaintext
 Wave 1: Issue 1-5 → 并行规划 → 并行执行
 Wave 2: Issue 6-10 → 并行规划 → 并行执行
 ...
--- a/docs/zh/skills/codex-index.md
+++ b/docs/zh/skills/codex-index.md
@@ -40,7 +40,7 @@
 **一句话定位**: 全生命周期编排器 — 规范/实现/测试的 spawn-wait-close 流水线

 **触发**:
-```
+```shell
 /team-lifecycle <task-description>
 ```

@@ -65,7 +65,7 @@
 | fe-qa | 前端 QA、GC 循环 | 2.3 Deep Interaction |

 **流水线定义**:
-```
+```plaintext
 Spec-only (6 beats):
  RESEARCH-001(+D1) → DRAFT-001(+D2) → DRAFT-002(+D3) → DRAFT-003(+D4) → DRAFT-004(+D5) → QUALITY-001(+D6)

@@ -77,7 +77,7 @@ Full-lifecycle (9 beats):
 ```

 **Beat Cycle**:
-```
+```plaintext
 event (phase advance / user resume)
      ↓
  [Orchestrator]
@@ -93,7 +93,7 @@ event (phase advance / user resume)
 ```

 **会话目录**:
-```
+```plaintext
 .workflow/.team/TLS-<slug>-<date>/
 ├── team-session.json           # 流水线状态
 ├── spec/                       # 规范产物
@@ -112,7 +112,7 @@ event (phase advance / user resume)
 **一句话定位**: 多代理并行开发循环 — 需求分析、探索规划、代码开发、验证

 **触发**:
-```
+```shell
 /parallel-dev-cycle TASK="Implement feature"
 /parallel-dev-cycle --cycle-id=cycle-v1-20260122-abc123
 /parallel-dev-cycle --auto TASK="Add OAuth"
@@ -138,7 +138,7 @@ event (phase advance / user resume)
 - 消除冗余代码库探索

 **会话结构**:
-```
+```plaintext
 {projectRoot}/.workflow/.cycle/
 ├── {cycleId}.json                     # 主状态文件
 ├── {cycleId}.progress/
@@ -156,7 +156,7 @@ event (phase advance / user resume)
 ```

 **执行流程**:
-```
+```plaintext
 Phase 1: 会话初始化
    ↓ cycleId, state, progressDir

@@ -190,13 +190,13 @@ Phase 4: 完成和摘要
 **一句话定位**: 协作分析 — 文档化讨论、内联探索、理解演进的交互式分析

 **触发**:
-```
+```shell
 /analyze-with-file TOPIC="<question>"
 /analyze-with-file TOPIC="--depth=deep"
 ```

 **核心工作流**:
-```
+```plaintext
 Topic → Explore → Discuss → Document → Refine → Conclude → (Optional) Quick Execute
 ```

@@ -222,7 +222,7 @@ Topic → Explore → Discuss → Document → Refine → Conclude → (Optional
 **一句话定位**: 多视角头脑风暴 — 4 视角（Product、Technical、Risk、User）并行分析

 **触发**:
-```
+```shell
 /brainstorm-with-file TOPIC="<idea>"
 ```

@@ -246,12 +246,12 @@ Topic → Explore → Discuss → Document → Refine → Conclude → (Optional
 **一句话定位**: 假设驱动调试 — 文档化探索、理解演进、分析辅助修正

 **触发**:
-```
+```shell
 /debug-with-file BUG="<bug description>"
 ```

 **核心工作流**:
-```
+```plaintext
 Explore → Document → Log → Analyze → Correct Understanding → Fix → Verify
 ```

@@ -262,7 +262,7 @@ Explore → Document → Log → Analyze → Correct Understanding → Fix → V
 - **学习保留**: 保留从失败尝试中学到的内容

 **会话文件夹结构**:
-```
+```plaintext
 {projectRoot}/.workflow/.debug/DBG-{slug}-{date}/
 ├── debug.log           # NDJSON 日志（执行证据）
 ├── understanding.md    # 探索时间线 + 整合理解
@@ -283,7 +283,7 @@ Explore → Document → Log → Analyze → Correct Understanding → Fix → V
 **一句话定位**: 协作规划 — 多代理协作规划（替代 team-planex）

 **触发**:
-```
+```shell
 /collaborative-plan-with-file <task>
 ```

@@ -299,7 +299,7 @@ Explore → Document → Log → Analyze → Correct Understanding → Fix → V
 **一句话定位**: 通用执行引擎 — 替代 workflow-execute

 **触发**:
-```
+```shell
 /unified-execute-with-file <session>
 ```

@@ -315,7 +315,7 @@ Explore → Document → Log → Analyze → Correct Understanding → Fix → V
 **一句话定位**: 需求路线图规划

 **触发**:
-```
+```shell
 /roadmap-with-file <requirements>
 ```

@@ -331,7 +331,7 @@ Explore → Document → Log → Analyze → Correct Understanding → Fix → V
 **一句话定位**: 审查循环（Codex 版本）

 **触发**:
-```
+```shell
 /review-cycle <target>
 ```

@@ -347,7 +347,7 @@ Explore → Document → Log → Analyze → Correct Understanding → Fix → V
 **一句话定位**: 测试修复工作流

 **触发**:
-```
+```shell
 /workflow-test-fix-cycle <failing-tests>
 ```

@@ -364,7 +364,7 @@ Explore → Document → Log → Analyze → Correct Understanding → Fix → V
 **一句话定位**: 智能代码清理

 **触发**:
-```
+```shell
 /clean <target>
 ```

@@ -380,7 +380,7 @@ Explore → Document → Log → Analyze → Correct Understanding → Fix → V
 **一句话定位**: CSV 波处理管道

 **触发**:
-```
+```shell
 /csv-wave-pipeline <csv-file>
 ```

@@ -396,7 +396,7 @@ Explore → Document → Log → Analyze → Correct Understanding → Fix → V
 **一句话定位**: Memory 压缩（Codex 版本）

 **触发**:
-```
+```shell
 /memory-compact
 ```

@@ -412,7 +412,7 @@ Explore → Document → Log → Analyze → Correct Understanding → Fix → V
 **一句话定位**: CLI 工具执行规范

 **触发**:
-```
+```shell
 /ccw-cli-tools <command>
 ```

@@ -428,7 +428,7 @@ Explore → Document → Log → Analyze → Correct Understanding → Fix → V
 **一句话定位**: Issue 发现

 **触发**:
-```
+```shell
 /issue-discover <context>
 ```

--- a/docs/zh/workflows/4-level.md
+++ b/docs/zh/workflows/4-level.md
@@ -4,7 +4,7 @@ CCW 四级工作流系统提供了一种从规格说明到部署的结构化软

 ## 概述

-```
+```text
 Level 1: 规格说明 → Level 2: 规划 → Level 3: 实现 → Level 4: 验证
 ```

@@ -38,7 +38,7 @@ Level 1: 规格说明 → Level 2: 规划 → Level 3: 实现 → Level 4: 验

 ### 示例任务

-```
+```text
 RESEARCH-001 → DRAFT-001 → DRAFT-002 → DRAFT-003 → DRAFT-004 → QUALITY-001
 ```

@@ -95,7 +95,7 @@ RESEARCH-001 → DRAFT-001 → DRAFT-002 → DRAFT-003 → DRAFT-004 → QUALITY

 任务根据依赖关系按拓扑顺序执行:

-```
+```text
 TASK-001 (无依赖) → TASK-002 (依赖 001) → TASK-003 (依赖 002)
 ```

@@ -142,7 +142,7 @@ TASK-001 (无依赖) → TASK-002 (依赖 001) → TASK-003 (依赖 002)

 事件驱动执行，由协调器编排:

-```
+```text
 Event           Coordinator              Workers
 ────────────────────────────────────────────────
 callback/resume → handleCallback ─────────────────┐
@@ -172,7 +172,7 @@ callback <───────────────────────

 对于简单的线性继任，工作器可以直接生成后继者:

-```
+```text
 [Worker A] complete
    → Check: 1 ready task? simple successor?
    → YES: Spawn Worker B directly
@@ -183,7 +183,7 @@ callback <───────────────────────

 某些史诗可以并行执行:

-```
+```text
 EPIC-003: Content Modules ──┐
                           ├──→ EPIC-005: Interaction Features
 EPIC-004: Search & Nav ────┘
--- a/docs/zh/workflows/best-practices.md
+++ b/docs/zh/workflows/best-practices.md
@@ -135,7 +135,7 @@

 ### 良好的工作流

-```
+```text
 [Specification]
  ↓ Clear requirements with acceptance criteria
 [Planning]
@@ -149,7 +149,7 @@

 ### 有问题的工作流

-```
+```text
 [Specification]
  ↓ Vague requirements, no acceptance criteria
 [Planning]
--- a/docs/zh/workflows/index.md
+++ b/docs/zh/workflows/index.md
@@ -4,7 +4,7 @@ CCW 的 4 级工作流系统编排从需求到部署代码的整个开发生命

 ## 工作流级别

-```
+```text
 Level 1: 规范
    ↓
 Level 2: 规划
@@ -105,7 +105,7 @@ Skill(skill="team-lifecycle-v4", args="构建用户身份验证系统")

 ## 工作流可视化

-```
+```text
 ┌─────────────────────────────────────────────────────────────┐
 │                    工作流编排                               │
 ├─────────────────────────────────────────────────────────────┤