refactor: 更新模块文档更新流程，简化任务描述并增强执行脚本的失败处理

docs: 更新文档，明确任务结构和操作模式的约束条件
refactor: 移除策略参数，改为基于目录深度自动选择更新策略
2026-02-06 01:54:11 +08:00 · 2025-10-22 12:17:52 +08:00 · 2025-10-22 11:16:34 +08:00 · 2025-10-22 10:50:46 +08:00 · 2025-10-22 10:35:30 +08:00 · 2025-10-21 21:02:17 +08:00
39 changed files with 1544 additions and 1725 deletions
--- a/.claude/agents/cli-execution-agent.md
+++ b/.claude/agents/cli-execution-agent.md
@@ -174,7 +174,7 @@ score = 0

 **2. Context Assembly**:
 ```bash
-CONTEXT: @{CLAUDE.md} @{discovered_file1} @{discovered_file2} ...
+CONTEXT: @CLAUDE.md @{discovered_file1} @{discovered_file2} ...

 ## Discovered Context
 - **Project Structure**: {module_summary}
--- a/.claude/agents/doc-generator.md
+++ b/.claude/agents/doc-generator.md
@@ -53,8 +53,7 @@ You are an expert technical documentation specialist. Your responsibility is to
 {
  "step": "analyze_module_structure",
  "action": "Deep analysis of module structure and API",
-  "command": "bash(cd src/auth && ~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Document module comprehensively\nTASK: Extract module purpose, architecture, public API, dependencies\nMODE: analysis\nCONTEXT: @{**/*}
-         System: [system_context]\nEXPECTED: Complete module analysis for documentation\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/module-documentation.txt)\")",
+  "command": "bash(cd src/auth && gemini \"PURPOSE: Document module comprehensively\nTASK: Extract module purpose, architecture, public API, dependencies\nMODE: analysis\nCONTEXT: @**/* System: [system_context]\nEXPECTED: Complete module analysis for documentation\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/module-documentation.txt)\")",
  "output_to": "module_analysis",
  "on_error": "fail"
 }
--- a/.claude/agents/memory-bridge.md
+++ b/.claude/agents/memory-bridge.md
@@ -16,7 +16,6 @@ You will receive:
 ```
 - Total modules: [count]
 - Tool: [gemini|qwen|codex]
- Mode: [full|related]
 - Module list (depth|path|files|types|has_claude format)
 ```

@@ -42,9 +41,13 @@ TodoWrite([
 # 2. Extract module paths for current depth
 # 3. Launch parallel jobs (max 4)

-# Depth 5 example:
-~/.claude/scripts/update_module_claude.sh "./.claude/workflows/cli-templates/prompts/analysis" "full" "gemini" &
-~/.claude/scripts/update_module_claude.sh "./.claude/workflows/cli-templates/prompts/development" "full" "gemini" &
+# Depth 5 example (Layer 3 - use multi-layer):
+~/.claude/scripts/update_module_claude.sh "multi-layer" "./.claude/workflows/cli-templates/prompts/analysis" "gemini" &
+~/.claude/scripts/update_module_claude.sh "multi-layer" "./.claude/workflows/cli-templates/prompts/development" "gemini" &
+
+# Depth 1 example (Layer 2 - use single-layer):
+~/.claude/scripts/update_module_claude.sh "single-layer" "./src/auth" "gemini" &
+~/.claude/scripts/update_module_claude.sh "single-layer" "./src/api" "gemini" &
 # ... up to 4 concurrent jobs

 # 4. Wait for all depth jobs to complete
@@ -63,21 +66,24 @@ git status --short

 ## Tool Parameter Flow

-**Command Format**: `update_module_claude.sh <path> <mode> <tool>`
+**Command Format**: `update_module_claude.sh <strategy> <path> <tool>`

 Examples:
- Gemini: `update_module_claude.sh "./.claude/agents" "full" "gemini" &`
- Qwen: `update_module_claude.sh "./src/api" "full" "qwen" &`
- Codex: `update_module_claude.sh "./tests" "full" "codex" &`
+- Layer 3 (depth ≥3): `update_module_claude.sh "multi-layer" "./.claude/agents" "gemini" &`
+- Layer 2 (depth 1-2): `update_module_claude.sh "single-layer" "./src/api" "qwen" &`
+- Layer 1 (depth 0): `update_module_claude.sh "single-layer" "./tests" "codex" &`

 ## Execution Rules

 1. **Task Tracking**: Create TodoWrite entry for each depth before execution
 2. **Parallelism**: Max 4 jobs per depth, sequential across depths
-3. **Tool Passing**: Always pass tool parameter as 3rd argument
-4. **Path Accuracy**: Extract exact path from `depth:N|path:X|...` format
-5. **Completion**: Mark todo completed only after all depth jobs finish
-6. **No Skipping**: Process every module from input list
+3. **Strategy Assignment**: Assign strategy based on depth:
+   - Depth ≥3 (Layer 3): Use "multi-layer" strategy
+   - Depth 0-2 (Layers 1-2): Use "single-layer" strategy
+4. **Tool Passing**: Always pass tool parameter as 3rd argument
+5. **Path Accuracy**: Extract exact path from `depth:N|path:X|...` format
+6. **Completion**: Mark todo completed only after all depth jobs finish
+7. **No Skipping**: Process every module from input list

 ## Concise Output

--- a/.claude/commands/cli/analyze.md
+++ b/.claude/commands/cli/analyze.md
@@ -67,24 +67,24 @@ The agent handles all phases internally (understanding, discovery, enhancement,

 ## File Pattern Auto-Detection

-Keywords trigger specific file patterns:
- "auth" → `@{**/*auth*,**/*user*}`
- "component" → `@{src/components/**/*,**/*.component.*}`
- "API" → `@{**/api/**/*,**/routes/**/*}`
- "test" → `@{**/*.test.*,**/*.spec.*}`
- "config" → `@{*.config.*,**/config/**/*}`
- Generic → `@{src/**/*}`
+Keywords trigger specific file patterns (each @ references one pattern):
+- "auth" → `@**/*auth* @**/*user*`
+- "component" → `@src/components/**/* @**/*.component.*`
+- "API" → `@**/api/**/* @**/routes/**/*`
+- "test" → `@**/*.test.* @**/*.spec.*`
+- "config" → `@*.config.* @**/config/**/*`
+- Generic → `@src/**/*`

 For complex patterns, use `rg` or MCP tools to discover files first, then execute CLI with precise file references.

 ## Command Template

 ```bash
-cd . && ~/.claude/scripts/gemini-wrapper -p "
+cd . && gemini -p "
 PURPOSE: [analysis goal from target]
 TASK: [auto-detected analysis type]
 MODE: analysis
-CONTEXT: @{CLAUDE.md} [auto-detected file patterns]
+CONTEXT: @CLAUDE.md [auto-detected file patterns]
 EXPECTED: Insights, patterns, recommendations (NO code modification)
 RULES: [auto-selected template] | Focus on [analysis aspect]
 "
@@ -112,7 +112,7 @@ RULES: [auto-selected template] | Focus on [analysis aspect]

 **Architecture Analysis**:
 ```bash
-/cli:analyze --tool qwen "component architecture"
+/cli:analyze --tool qwen -p "component architecture"
 # Executes: Qwen with component file patterns
 # Returns: Architecture review, design patterns, improvement suggestions
 ```
--- a/.claude/commands/cli/chat.md
+++ b/.claude/commands/cli/chat.md
@@ -27,7 +27,6 @@ Direct Q&A interaction with CLI tools for codebase analysis. **Analysis only - d
 - `--agent` - Use cli-execution-agent for automated context discovery (5-phase intelligent mode)
 - `--tool <codex|gemini|qwen>` - Select CLI tool (default: gemini, ignored in agent mode)
 - `--enhance` - Enhance inquiry with `/enhance-prompt` first
- `--all-files` - Include entire codebase in context
 - `--save-session` - Save interaction to workflow session

 ## Execution Flow
@@ -36,7 +35,7 @@ Direct Q&A interaction with CLI tools for codebase analysis. **Analysis only - d

 1. Parse tool selection (default: gemini)
 2. If `--enhance`: Execute `/enhance-prompt` to expand user intent
-3. Assemble context: `@{CLAUDE.md}` + user-specified files or `--all-files`
+3. Assemble context: `@CLAUDE.md` + user-specified files or `@**/*` for entire codebase
 4. Execute CLI tool with assembled context (read-only, analysis mode)
 5. Return explanations and insights (NO code changes)
 6. Optionally save to workflow session
@@ -54,7 +53,6 @@ Task(
    Task: ${inquiry}
    Mode: analyze (Q&A)
    Tool Preference: ${tool_flag || 'auto-select'}
-    ${all_files_flag ? 'Scope: all-files' : ''}

    Agent will autonomously:
    - Discover files relevant to the question
@@ -69,22 +67,24 @@ The agent handles all phases internally.

 ## Context Assembly

-**Always included**: `@{CLAUDE.md,**/*CLAUDE.md}` (project guidelines)
+**Always included**: `@CLAUDE.md @**/*CLAUDE.md` (project guidelines, space-separated)

 **Optional**:
 - User-explicit files from inquiry keywords
- `--all-files` flag includes entire codebase (`--all-files` wrapper parameter)
+- Use `@**/*` in CONTEXT for entire codebase

 For targeted analysis, use `rg` or MCP tools to discover relevant files first, then build precise CONTEXT field.

 ## Command Template

 ```bash
-cd . && ~/.claude/scripts/gemini-wrapper -p "
-INQUIRY: [user question]
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [inferred or --all-files]
+cd . && gemini -p "
+PURPOSE: Answer user inquiry about codebase
+TASK: [user question]
 MODE: analysis
-RESPONSE: Direct answer, explanation, insights (NO code modification)
+CONTEXT: @CLAUDE.md @**/*CLAUDE.md [inferred files or @**/* for all files]
+EXPECTED: Direct answer, explanation, insights (NO code modification)
+RULES: Focus on clarity and accuracy
 "
 ```

@@ -110,7 +110,7 @@ RESPONSE: Direct answer, explanation, insights (NO code modification)

 **Architecture Question**:
 ```bash
-/cli:chat --tool qwen "how does React component optimization work here"
+/cli:chat --tool qwen -p "how does React component optimization work here"
 # Executes: Qwen architecture analysis
 # Returns: Component structure explanation, optimization patterns used
 ```
@@ -130,13 +130,6 @@ RESPONSE: Direct answer, explanation, insights (NO code modification)
 # Returns: Detailed explanation of login flow and potential issues
 ```

-**Broad Context**:
-```bash
-/cli:chat --all-files "find all API endpoints"
-# Executes: Analysis across entire codebase
-# Returns: List and explanation of API endpoints (NO code generation)
-```
-
 ## Output Routing

 **Output Destination Logic**:
--- a/.claude/commands/cli/codex-execute.md
+++ b/.claude/commands/cli/codex-execute.md
@@ -130,7 +130,7 @@ git status --short
 codex -C [dir] --full-auto exec "
 PURPOSE: [group goal]
 TASK: [subtask description - first in group]
-CONTEXT: @{relevant_files} @{CLAUDE.md}
+CONTEXT: @{relevant_files} @CLAUDE.md
 EXPECTED: [specific deliverables]
 RULES: [constraints]
 Group [X]: [group name] - Subtask 1 of N in this group
@@ -164,7 +164,7 @@ git add -A
 codex -C [dir] --full-auto exec "
 PURPOSE: [new group goal]
 TASK: [subtask description - first in new group]
-CONTEXT: @{different_files} @{CLAUDE.md}
+CONTEXT: @{different_files} @CLAUDE.md
 EXPECTED: [specific deliverables]
 RULES: [constraints]
 Group [Y]: [new group name] - Subtask 1 of N in this group
--- a/.claude/commands/cli/discuss-plan.md
+++ b/.claude/commands/cli/discuss-plan.md
@@ -69,11 +69,11 @@ Gemini analyzes the topic and proposes preliminary plan.
 ```bash
 # Round 1: CONTEXT_INPUT is the initial topic
 # Subsequent rounds: CONTEXT_INPUT is the synthesis from previous round
-~/.claude/scripts/gemini-wrapper -p "
+gemini -p "
 PURPOSE: Analyze and propose a plan for '[topic]'
 TASK: Provide initial analysis, identify key modules, and draft implementation plan
 MODE: analysis
-CONTEXT: @{CLAUDE.md} [auto-detected files]
+CONTEXT: @CLAUDE.md [auto-detected files]
 INPUT: [CONTEXT_INPUT]
 EXPECTED: Structured analysis and draft plan for discussion
 RULES: Focus on technical depth and practical considerations
@@ -90,7 +90,7 @@ codex --full-auto exec "
 PURPOSE: Critically review technical plan
 TASK: Review the provided plan, identify weaknesses, suggest alternatives, reason about trade-offs
 MODE: analysis
-CONTEXT: @{CLAUDE.md} [relevant files]
+CONTEXT: @CLAUDE.md [relevant files]
 INPUT_PLAN: [Output from Gemini's analysis]
 EXPECTED: Critical review with alternative ideas and risk analysis
 RULES: Focus on architectural soundness and implementation feasibility
--- a/.claude/commands/cli/execute.md
+++ b/.claude/commands/cli/execute.md
@@ -45,11 +45,11 @@ Auto-approves: file pattern inference, execution, **file modifications**, summar

 ### Context Inference

-Auto-selects files based on keywords and technology:
- "auth" → `@{**/*auth*,**/*user*}`
- "React" → `@{src/**/*.{jsx,tsx}}`
- "api" → `@{**/api/**/*,**/routes/**/*}`
- Always includes: `@{CLAUDE.md,**/*CLAUDE.md}`
+Auto-selects files based on keywords and technology (each @ references one pattern):
+- "auth" → `@**/*auth* @**/*user*`
+- "React" → `@src/**/*.jsx @src/**/*.tsx`
+- "api" → `@**/api/**/* @**/routes/**/*`
+- Always includes: `@CLAUDE.md @**/*CLAUDE.md`

 For precise file targeting, use `rg` or MCP tools to discover files first.

@@ -111,11 +111,11 @@ Use `resume --last` when current task extends/relates to previous execution. See
 ### Standard Mode (Default)
 ```bash
 # Gemini/Qwen: MODE=write with --approval-mode yolo
-cd . && ~/.claude/scripts/gemini-wrapper --approval-mode yolo -p "
+cd . && gemini --approval-mode yolo "
 PURPOSE: [implementation goal]
 TASK: [specific implementation]
 MODE: write
-CONTEXT: @{CLAUDE.md} [auto-detected files]
+CONTEXT: @CLAUDE.md [auto-detected files]
 EXPECTED: Working implementation with code changes
 RULES: [constraints] | Auto-approve all changes
 "
--- a/.claude/commands/cli/mode/bug-index.md
+++ b/.claude/commands/cli/mode/bug-index.md
@@ -79,11 +79,11 @@ The agent handles all phases internally.
 ## Command Template

 ```bash
-cd [directory] && ~/.claude/scripts/gemini-wrapper --all-files -p "
+cd [directory] && gemini -p "
 PURPOSE: [bug analysis goal]
 TASK: Systematic bug analysis and fix recommendations
 MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [entire codebase in directory]
+CONTEXT: @CLAUDE.md @**/*CLAUDE.md [entire codebase in directory]
 EXPECTED: Root cause analysis, code path tracing, targeted fix suggestions
 RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: [description]
 "
@@ -111,11 +111,11 @@ RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: [description]

 **Standard Template Example**:
 ```bash
-cd . && ~/.claude/scripts/gemini-wrapper --all-files -p "
+cd . && gemini -p "
 PURPOSE: Debug authentication null pointer error
 TASK: Identify root cause and provide fix recommendations
 MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
+CONTEXT: @CLAUDE.md @**/*CLAUDE.md
 EXPECTED: Root cause, code path, minimal fix suggestion, impact assessment
 RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: null pointer in login flow
 "
@@ -123,11 +123,11 @@ RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: null pointer in login

 **Directory-Specific**:
 ```bash
-cd src/auth && ~/.claude/scripts/gemini-wrapper --all-files -p "
+cd src/auth && gemini -p "
 PURPOSE: Fix token validation failure
 TASK: Analyze token validation bug in auth module
 MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
+CONTEXT: @CLAUDE.md @**/*CLAUDE.md
 EXPECTED: Validation logic analysis, fix recommendation with minimal changes
 RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: token validation fails intermittently
 "
@@ -161,4 +161,4 @@ mcp__code-index__search_code_advanced(pattern="error|exception", file_pattern="*
 - Command templates and file patterns: see intelligent-tools-strategy.md (loaded in memory)
 - Scratchpad directory details: see workflow-architecture.md
 - Template path: `~/.claude/prompt-templates/bug-fix.md`
- Always uses `--all-files` for comprehensive codebase context
+- Uses `@**/*` for in CONTEXT field for comprehensive codebase context
--- a/.claude/commands/cli/mode/code-analysis.md
+++ b/.claude/commands/cli/mode/code-analysis.md
@@ -82,11 +82,11 @@ The agent handles all phases internally.
 ## Command Template

 ```bash
-cd [directory] && ~/.claude/scripts/gemini-wrapper --all-files -p "
+cd [directory] && gemini -p "
 PURPOSE: [analysis goal]
 TASK: Systematic code analysis and execution path tracing
 MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [entire codebase in directory]
+CONTEXT: @CLAUDE.md @**/*CLAUDE.md [entire codebase in directory]
 EXPECTED: Execution trace, call flow diagram, debugging insights
 RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on [aspect]
 "
@@ -114,11 +114,11 @@ RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on [aspect]

 **Standard Template Example**:
 ```bash
-cd . && ~/.claude/scripts/gemini-wrapper --all-files -p "
+cd . && gemini -p "
 PURPOSE: Trace authentication execution flow
 TASK: Analyze complete auth flow from request to response
 MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
+CONTEXT: @CLAUDE.md @**/*CLAUDE.md
 EXPECTED: Step-by-step execution trace with call diagram, variable states
 RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on control flow
 "
@@ -126,11 +126,11 @@ RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on control flo

 **Directory-Specific Analysis**:
 ```bash
-cd src/auth && ~/.claude/scripts/gemini-wrapper --all-files -p "
+cd src/auth && gemini -p "
 PURPOSE: Understand JWT token validation logic
 TASK: Trace JWT validation from middleware to service layer
 MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
+CONTEXT: @CLAUDE.md @**/*CLAUDE.md
 EXPECTED: Validation flow diagram, token lifecycle analysis
 RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on security
 "
@@ -167,4 +167,4 @@ mcp__code-index__search_code_advanced(pattern="authenticate|login", file_pattern
 - Command templates and file patterns: see intelligent-tools-strategy.md (loaded in memory)
 - Scratchpad directory details: see workflow-architecture.md
 - Template path: `~/.claude/prompt-templates/code-analysis.md`
- Always uses `--all-files` for comprehensive code context
+- Uses `@**/*` for in CONTEXT field for comprehensive code context
--- a/.claude/commands/cli/mode/plan.md
+++ b/.claude/commands/cli/mode/plan.md
@@ -80,11 +80,11 @@ The agent handles all phases internally.
 ## Command Template

 ```bash
-cd [directory] && ~/.claude/scripts/gemini-wrapper --all-files -p "
+cd [directory] && gemini -p "
 PURPOSE: [planning goal from topic]
 TASK: Comprehensive planning and architecture analysis
 MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [entire codebase in directory]
+CONTEXT: @CLAUDE.md @**/*CLAUDE.md [entire codebase in directory]
 EXPECTED: Strategic insights, implementation recommendations, key decisions
 RULES: $(cat ~/.claude/prompt-templates/plan.md) | Focus on [topic area]
 "
@@ -112,11 +112,11 @@ RULES: $(cat ~/.claude/prompt-templates/plan.md) | Focus on [topic area]

 **Standard Template Example**:
 ```bash
-cd . && ~/.claude/scripts/gemini-wrapper --all-files -p "
+cd . && gemini -p "
 PURPOSE: Design user dashboard architecture
 TASK: Plan dashboard component structure and data flow
 MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
+CONTEXT: @CLAUDE.md @**/*CLAUDE.md
 EXPECTED: Architecture recommendations, component design, data flow diagram
 RULES: $(cat ~/.claude/prompt-templates/plan.md) | Focus on scalability
 "
@@ -124,11 +124,11 @@ RULES: $(cat ~/.claude/prompt-templates/plan.md) | Focus on scalability

 **Directory-Specific Planning**:
 ```bash
-cd src/api && ~/.claude/scripts/gemini-wrapper --all-files -p "
+cd src/api && gemini -p "
 PURPOSE: Plan API refactoring strategy
 TASK: Analyze current API structure and recommend improvements
 MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
+CONTEXT: @CLAUDE.md @**/*CLAUDE.md
 EXPECTED: Refactoring roadmap, breaking change analysis, migration plan
 RULES: $(cat ~/.claude/prompt-templates/plan.md) | Maintain backward compatibility
 "
@@ -165,4 +165,4 @@ rg "architecture|design" --files-with-matches
 - Command templates and file patterns: see intelligent-tools-strategy.md (loaded in memory)
 - Scratchpad directory details: see workflow-architecture.md
 - Template path: `~/.claude/prompt-templates/plan.md`
- Always uses `--all-files` for comprehensive project context
+- Uses `@**/*` for in CONTEXT field for comprehensive project context
--- a/.claude/commands/memory/docs.md
+++ b/.claude/commands/memory/docs.md
@@ -129,9 +129,11 @@ EOF

 ### Phase 2: Analyze Structure

+**Smart filter**: Auto-detect and skip tests/build/config/vendor based on project tech stack (Node.js/Python/Go/Rust/etc).
+
 #### Step 1: Discover and Classify Folders
 ```bash
-# Run analysis pipeline (module discovery + folder classification)
+# Run analysis pipeline (module discovery + folder classification + smart filtering)
 bash(~/.claude/scripts/get_modules_by_depth.sh | ~/.claude/scripts/classify-folders.sh > .workflow/WFS-docs-20240120/.process/folder-analysis.txt)
 ```

@@ -142,6 +144,12 @@ bash(~/.claude/scripts/get_modules_by_depth.sh | ~/.claude/scripts/classify-fold
 ./src/utils|navigation|code:0|dirs:4
 ```

+**Auto-skipped**:
+- Tests: `**/test/**`, `**/*.test.*`, `**/__tests__/**`
+- Build: `**/node_modules/**`, `**/dist/**`, `**/build/**`
+- Config: Root-level config files (package.json, tsconfig.json, etc)
+- Vendor: Language-specific dependency directories
+
 #### Step 2: Extract Top-Level Directories
 ```bash
 # Group folders by top-level directory
@@ -394,7 +402,7 @@ bash(
      },
      {
        "step": "analyze_module_tree",
-        "command": "bash(cd src/modules && ~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Analyze module structure\\nTASK: Generate documentation outline\\nMODE: analysis\\nCONTEXT: @{**/*} [target_folders]\\nEXPECTED: Structure outline\\nRULES: Analyze only\")",
+        "command": "bash(cd src/modules && gemini \"PURPOSE: Analyze module structure\\nTASK: Generate documentation outline\\nMODE: analysis\\nCONTEXT: @**/* [target_folders]\\nEXPECTED: Structure outline\\nRULES: Analyze only\")",
        "output_to": "tree_outline",
        "note": "CLI for analysis only"
      }
@@ -490,7 +498,7 @@ bash(
          "CLI writes documentation to .workflow/docs/src/modules/",
          "Maintains directory structure mirroring"
        ],
-        "command": "bash(cd src/modules && ~/.claude/scripts/gemini-wrapper --approval-mode yolo -p \"PURPOSE: Generate module docs\\nTASK: Create documentation files in .workflow/docs/src/modules/\\nMODE: write\\nCONTEXT: @{**/*} [target_folders] [existing_module_docs]\\nEXPECTED: API.md and README.md in .workflow/docs/src/modules/\\nRULES: Mirror source structure, generate complete docs\")",
+        "command": "bash(cd src/modules && gemini --approval-mode yolo \"PURPOSE: Generate module docs\\nTASK: Create documentation files in .workflow/docs/src/modules/\\nMODE: write\\nCONTEXT: @**/* [target_folders] [existing_module_docs]\\nEXPECTED: API.md and README.md in .workflow/docs/src/modules/\\nRULES: Mirror source structure, generate complete docs\")",
        "depends_on": [1],
        "output": "generated_docs"
      }
@@ -533,7 +541,7 @@ bash(
      },
      {
        "step": "analyze_project",
-        "command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Analyze project structure\\nTASK: Extract overview from modules\\nMODE: analysis\\nCONTEXT: [all_module_docs]\\nEXPECTED: Project outline\")",
+        "command": "bash(gemini \"PURPOSE: Analyze project structure\\nTASK: Extract overview from modules\\nMODE: analysis\\nCONTEXT: [all_module_docs]\\nEXPECTED: Project outline\")",
        "output_to": "project_outline"
      }
    ],
@@ -583,7 +591,7 @@ bash(
      },
      {
        "step": "analyze_architecture_and_examples",
-        "command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Analyze system architecture and generate examples\\nTASK: Synthesize architectural overview and usage patterns\\nMODE: analysis\\nCONTEXT: [all_docs]\\nEXPECTED: Architecture outline + Examples outline\")",
+        "command": "bash(gemini \"PURPOSE: Analyze system architecture and generate examples\\nTASK: Synthesize architectural overview and usage patterns\\nMODE: analysis\\nCONTEXT: [all_docs]\\nEXPECTED: Architecture outline + Examples outline\")",
        "output_to": "arch_examples_outline"
      }
    ],
@@ -645,7 +653,7 @@ bash(
      },
      {
        "step": "analyze_api",
-        "command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Document HTTP API\\nTASK: Analyze API endpoints\\nMODE: analysis\\nCONTEXT: @{src/api/**/*} [endpoint_discovery]\\nEXPECTED: API outline\")",
+        "command": "bash(gemini \"PURPOSE: Document HTTP API\\nTASK: Analyze API endpoints\\nMODE: analysis\\nCONTEXT: @src/api/**/* [endpoint_discovery]\\nEXPECTED: API outline\")",
        "output_to": "api_outline"
      }
    ],
--- a/.claude/commands/memory/load.md
+++ b/.claude/commands/memory/load.md
@@ -5,7 +5,7 @@ argument-hint: "[--tool gemini|qwen] \"task context description\""
 allowed-tools: Task(*), Bash(*)
 examples:
  - /memory:load "在当前前端基础上开发用户认证功能"
-  - /memory:load --tool qwen "重构支付模块API"
+  - /memory:load --tool qwen -p "重构支付模块API"
 ---

 # Memory Load Command (/memory:load)
@@ -140,7 +140,7 @@ cd . && ~/.claude/scripts/${tool}-wrapper -p "
 PURPOSE: Extract project core context for task: ${task_description}
 TASK: Analyze project architecture, tech stack, key patterns, relevant files
 MODE: analysis
-CONTEXT: @{CLAUDE.md,README.md,${discovered_files}}
+CONTEXT: @CLAUDE.md,README.md @${discovered_files}
 EXPECTED: Structured project summary and integration point analysis
 RULES:
 - Focus on task-relevant core information
@@ -212,7 +212,7 @@ Before returning:
 ### Example 2: Using Qwen Tool

 ```bash
-/memory:load --tool qwen "重构支付模块API"
+/memory:load --tool qwen -p "重构支付模块API"
 ```

 Agent uses Qwen CLI for analysis, returns same structured package.
--- a/.claude/commands/memory/update-full.md
+++ b/.claude/commands/memory/update-full.md
@@ -0,0 +1,329 @@
+---
+name: update-full
+description: Complete project-wide CLAUDE.md documentation update with agent-based parallel execution and tool fallback
+argument-hint: "[--tool gemini|qwen|codex] [--path <directory>]"
+---
+
+# Full Documentation Update (/memory:update-full)
+
+## Overview
+
+Orchestrates project-wide CLAUDE.md updates using batched agent execution with automatic tool fallback and 3-layer architecture support.
+
+**Parameters**:
+- `--tool <gemini|qwen|codex>`: Primary tool (default: gemini)
+- `--path <directory>`: Target specific directory (default: entire project)
+
+**Execution Flow**: Discovery → Plan Presentation → Execution → Safety Verification
+
+## 3-Layer Architecture & Auto-Strategy Selection
+
+### Layer Definition & Strategy Assignment
+
+| Layer | Depth | Strategy | Purpose | Context Pattern |
+|-------|-------|----------|---------|----------------|
+| **Layer 3** (Deepest) | ≥3 | `multi-layer` | Handle unstructured files, generate docs for all subdirectories | `@**/*` (all files) |
+| **Layer 2** (Middle) | 1-2 | `single-layer` | Aggregate from children + current code | `@*/CLAUDE.md @*.{ts,tsx,js,...}` |
+| **Layer 1** (Top) | 0 | `single-layer` | Aggregate from children + current code | `@*/CLAUDE.md @*.{ts,tsx,js,...}` |
+
+**Update Direction**: Layer 3 → Layer 2 → Layer 1 (bottom-up dependency flow)
+
+**Strategy Auto-Selection**: Strategies are automatically determined by directory depth - no user configuration needed.
+
+### Strategy Details
+
+#### Multi-Layer Strategy (Layer 3 Only)
+- **Use Case**: Deepest directories with unstructured file layouts
+- **Behavior**: Generates CLAUDE.md for current directory AND each subdirectory containing files
+- **Context**: All files in current directory tree (`@**/*`)
+- **Benefits**: Creates foundation documentation for upper layers to reference
+
+#### Single-Layer Strategy (Layers 1-2)
+- **Use Case**: Upper layers that aggregate from existing documentation
+- **Behavior**: Generates CLAUDE.md only for current directory
+- **Context**: Direct children CLAUDE.md files + current directory code files
+- **Benefits**: Minimal context consumption, clear layer separation
+
+### Example Flow
+```
+src/auth/handlers/ (depth 3) → MULTI-LAYER STRATEGY
+  CONTEXT: @**/* (all files in handlers/ and subdirs)
+  GENERATES: ./CLAUDE.md + CLAUDE.md in each subdir with files
+  ↓
+src/auth/ (depth 2) → SINGLE-LAYER STRATEGY
+  CONTEXT: @*/CLAUDE.md @*.ts (handlers/CLAUDE.md + current code)
+  GENERATES: ./CLAUDE.md only
+  ↓
+src/ (depth 1) → SINGLE-LAYER STRATEGY
+  CONTEXT: @*/CLAUDE.md (auth/CLAUDE.md, utils/CLAUDE.md)
+  GENERATES: ./CLAUDE.md only
+  ↓
+./ (depth 0) → SINGLE-LAYER STRATEGY
+  CONTEXT: @*/CLAUDE.md (src/CLAUDE.md, tests/CLAUDE.md)
+  GENERATES: ./CLAUDE.md only
+```
+
+## Core Execution Rules
+
+1. **Analyze First**: Git cache + module discovery before updates
+2. **Wait for Approval**: Present plan, no execution without user confirmation
+3. **Execution Strategy**:
+   - **<20 modules**: Direct parallel execution (max 4 concurrent per layer)
+   - **≥20 modules**: Agent batch processing (4 modules/agent, 73% overhead reduction)
+4. **Tool Fallback**: Auto-retry with fallback tools on failure
+5. **Layer Sequential**: Process layers 3→2→1 (bottom-up), parallel batches within layer
+6. **Safety Check**: Verify only CLAUDE.md files modified
+7. **Layer-based Grouping**: Group modules by LAYER (not depth) for execution
+
+## Tool Fallback Hierarchy
+
+```javascript
+--tool gemini  →  [gemini, qwen, codex]  // default
+--tool qwen    →  [qwen, gemini, codex]
+--tool codex   →  [codex, gemini, qwen]
+```
+
+**Trigger**: Non-zero exit code from update script
+
+| Tool   | Best For                       | Fallback To    |
+|--------|--------------------------------|----------------|
+| gemini | Documentation, patterns        | qwen → codex   |
+| qwen   | Architecture, system design    | gemini → codex |
+| codex  | Implementation, code quality   | gemini → qwen  |
+
+## Execution Phases
+
+### Phase 1: Discovery & Analysis
+
+```bash
+# Cache git changes
+bash(git add -A 2>/dev/null || true)
+
+# Get module structure
+bash(~/.claude/scripts/get_modules_by_depth.sh list)
+# OR with --path
+bash(cd <target-path> && ~/.claude/scripts/get_modules_by_depth.sh list)
+```
+
+**Parse output** `depth:N|path:<PATH>|...` to extract module paths and count.
+
+**Smart filter**: Auto-detect and skip tests/build/config/docs based on project tech stack.
+
+### Phase 2: Plan Presentation
+
+**For <20 modules**:
+```
+Update Plan:
+  Tool: gemini (fallback: qwen → codex)
+  Total: 7 modules
+  Execution: Direct parallel (< 20 modules threshold)
+
+  Will update:
+  - ./core/interfaces (12 files) - depth 2 [Layer 2] - single-layer strategy
+  - ./core (22 files) - depth 1 [Layer 2] - single-layer strategy
+  - ./models (9 files) - depth 1 [Layer 2] - single-layer strategy
+  - ./utils (12 files) - depth 1 [Layer 2] - single-layer strategy
+  - . (5 files) - depth 0 [Layer 1] - single-layer strategy
+
+  Context Strategy (Auto-Selected):
+  - Layer 2 (depth 1-2): @*/CLAUDE.md + current code files
+  - Layer 1 (depth 0): @*/CLAUDE.md + current code files
+
+  Auto-skipped: ./tests, __pycache__, setup.py (15 paths)
+  Execution order: Layer 2 → Layer 1
+  Estimated time: ~5-10 minutes
+
+  Confirm execution? (y/n)
+```
+
+**For ≥20 modules**:
+```
+Update Plan:
+  Tool: gemini (fallback: qwen → codex)
+  Total: 31 modules
+  Execution: Agent batch processing (4 modules/agent)
+
+  Will update:
+  - ./src/features/auth (12 files) - depth 3 [Layer 3] - multi-layer strategy
+  - ./.claude/commands/cli (6 files) - depth 3 [Layer 3] - multi-layer strategy
+  - ./src/utils (8 files) - depth 2 [Layer 2] - single-layer strategy
+  ...
+
+  Context Strategy (Auto-Selected):
+  - Layer 3 (depth ≥3): @**/* (all files)
+  - Layer 2 (depth 1-2): @*/CLAUDE.md + current code files
+  - Layer 1 (depth 0): @*/CLAUDE.md + current code files
+
+  Agent allocation (by LAYER):
+  - Layer 3 (14 modules, depth ≥3): 4 agents [4, 4, 4, 2]
+  - Layer 2 (15 modules, depth 1-2): 4 agents [4, 4, 4, 3]
+  - Layer 1 (2 modules, depth 0): 1 agent [2]
+
+  Estimated time: ~15-25 minutes
+
+  Confirm execution? (y/n)
+```
+
+### Phase 3A: Direct Execution (<20 modules)
+
+**Strategy**: Parallel execution within layer (max 4 concurrent), no agent overhead.
+
+```javascript
+// Group modules by LAYER (not depth)
+let modules_by_layer = group_by_layer(module_list);
+let tool_order = construct_tool_order(primary_tool);
+
+// Process by LAYER (3 → 2 → 1), not by depth
+for (let layer of [3, 2, 1]) {
+  if (modules_by_layer[layer].length === 0) continue;
+
+  let batches = batch_modules(modules_by_layer[layer], 4);
+
+  for (let batch of batches) {
+    let parallel_tasks = batch.map(module => {
+      return async () => {
+        // Auto-determine strategy based on depth
+        let strategy = module.depth >= 3 ? "multi-layer" : "single-layer";
+
+        for (let tool of tool_order) {
+          let exit_code = bash(`cd ${module.path} && ~/.claude/scripts/update_module_claude.sh "${strategy}" "." "${tool}"`);
+          if (exit_code === 0) {
+            report(`✅ ${module.path} (Layer ${layer}) updated with ${tool}`);
+            return true;
+          }
+        }
+        report(`❌ FAILED: ${module.path} (Layer ${layer}) failed all tools`);
+        return false;
+      };
+    });
+
+    await Promise.all(parallel_tasks.map(task => task()));
+  }
+}
+```
+
+### Phase 3B: Agent Batch Execution (≥20 modules)
+
+**Strategy**: Batch modules into groups of 4, spawn memory-bridge agents per batch.
+
+```javascript
+// Group modules by LAYER and batch within each layer
+let modules_by_layer = group_by_layer(module_list);
+let tool_order = construct_tool_order(primary_tool);
+
+for (let layer of [3, 2, 1]) {
+  if (modules_by_layer[layer].length === 0) continue;
+
+  let batches = batch_modules(modules_by_layer[layer], 4);
+  let worker_tasks = [];
+
+  for (let batch of batches) {
+    worker_tasks.push(
+      Task(
+        subagent_type="memory-bridge",
+        description=`Update ${batch.length} modules in Layer ${layer}`,
+        prompt=generate_batch_worker_prompt(batch, tool_order, layer)
+      )
+    );
+  }
+
+  await parallel_execute(worker_tasks);
+}
+```
+
+**Batch Worker Prompt Template**:
+```
+PURPOSE: Update CLAUDE.md for assigned modules with tool fallback
+
+TASK: Update documentation for assigned modules using specified strategies.
+
+MODULES:
+{{module_path_1}} (strategy: {{strategy_1}})
+{{module_path_2}} (strategy: {{strategy_2}})
+...
+
+TOOLS (try in order): {{tool_1}}, {{tool_2}}, {{tool_3}}
+
+EXECUTION SCRIPT: ~/.claude/scripts/update_module_claude.sh
+  - Accepts strategy parameter: multi-layer | single-layer
+  - Tool execution via CLI wrapper (gemini/qwen/codex)
+
+EXECUTION FLOW (for each module):
+  1. Tool fallback loop (exit on first success):
+     for tool in {{tool_1}} {{tool_2}} {{tool_3}}; do
+       bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "{{strategy}}" "." "${tool}")
+       exit_code=$?
+
+       if [ $exit_code -eq 0 ]; then
+         report "✅ {{module_path}} updated with $tool"
+         break
+       else
+         report "⚠️  {{module_path}} failed with $tool, trying next..."
+         continue
+       fi
+     done
+
+  2. Handle complete failure (all tools failed):
+     if [ $exit_code -ne 0 ]; then
+       report "❌ FAILED: {{module_path}} - all tools exhausted"
+       # Continue to next module (do not abort batch)
+     fi
+
+FAILURE HANDLING:
+  - Module-level isolation: One module's failure does not affect others
+  - Exit code detection: Non-zero exit code triggers next tool
+  - Exhaustion reporting: Log modules where all tools failed
+  - Batch continuation: Always process remaining modules
+
+REPORTING FORMAT:
+  Per-module status:
+    ✅ path/to/module updated with {tool}
+    ⚠️  path/to/module failed with {tool}, trying next...
+    ❌ FAILED: path/to/module - all tools exhausted
+```
+### Phase 4: Safety Verification
+
+```bash
+# Check only CLAUDE.md modified
+bash(git diff --cached --name-only | grep -v "CLAUDE.md" || echo "Only CLAUDE.md files modified")
+
+# Display status
+bash(git status --short)
+```
+
+**Result Summary**:
+```
+Update Summary:
+  Total: 31 | Success: 29 | Failed: 2
+  Tool usage: gemini: 25, qwen: 4, codex: 0
+  Failed: path1, path2
+```
+
+## Error Handling
+
+**Batch Worker**: Tool fallback per module, batch isolation, clear status reporting
+**Coordinator**: Invalid path abort, user decline handling, safety check with auto-revert
+**Fallback Triggers**: Non-zero exit code, script timeout, unexpected output
+
+## Usage Examples
+
+```bash
+# Full project update (auto-strategy selection)
+/memory:update-full
+
+# Target specific directory
+/memory:update-full --path .claude
+/memory:update-full --path src/features/auth
+
+# Use specific tool
+/memory:update-full --tool qwen
+/memory:update-full --path .claude --tool qwen
+```
+
+## Key Advantages
+
+- **Efficiency**: 30 modules → 8 agents (73% reduction from sequential)
+- **Resilience**: 3-tier tool fallback per module
+- **Performance**: Parallel batches, no concurrency limits
+- **Observability**: Per-module tool usage, batch-level metrics
+- **Automation**: Zero configuration - strategy auto-selected by directory depth
--- a/.claude/commands/memory/update-memory-full.md
+++ b/.claude/commands/memory/update-memory-full.md
@@ -1,330 +0,0 @@
---
-name: update-full
-description: Complete project-wide CLAUDE.md documentation update
-argument-hint: "[--tool gemini|qwen|codex] [--path <directory>]"
---
-
-# Full Documentation Update (/memory:update-full)
-
-## Coordinator Role
-
-**This command orchestrates project-wide CLAUDE.md updates** using depth-parallel execution strategy with intelligent complexity detection.
-
-**Execution Model**:
-
-1. **Initial Analysis**: Cache git changes, discover module structure
-2. **Complexity Detection**: Analyze module count, determine strategy
-3. **Plan Presentation**: Show user exactly what will be updated
-4. **Depth-Parallel Execution**: Update modules by depth (highest to lowest)
-5. **Safety Verification**: Ensure only CLAUDE.md files modified
-
-**Tool Selection**:
- `--tool gemini` (default): Documentation generation, pattern recognition
- `--tool qwen`: Architecture analysis, system design docs
- `--tool codex`: Implementation validation, code quality analysis
-
-**Path Parameter**:
- `--path <directory>` (optional): Target specific directory for updates
- If not specified: Updates entire project from current directory
- If specified: Changes to target directory before discovery
-
-## Core Rules
-
-1. **Analyze First**: Run git cache and module discovery before any updates
-2. **Scope Control**: Use --path to target specific directories, default is entire project
-3. **Wait for Approval**: Present plan, no execution without user confirmation
-4. **Depth-Parallel**: Same depth runs parallel (max 4 jobs), different depths sequential
-5. **Safety Check**: Verify only CLAUDE.md files modified, revert if source files touched
-6. **Independent Commands**: Each update is a separate bash() call
-7. **No Background Bash Tool**: Never use `run_in_background` parameter in bash() calls; use shell `&` for parallelism
-
-## Execution Workflow
-
-### Phase 1: Discovery & Analysis
-
-**Cache git changes:**
-```bash
-bash(git add -A 2>/dev/null || true)
-```
-
-**Get module structure:**
-
-*If no --path parameter:*
-```bash
-bash(~/.claude/scripts/get_modules_by_depth.sh list)
-```
-
-*If --path parameter specified:*
-```bash
-bash(cd <target-path> && ~/.claude/scripts/get_modules_by_depth.sh list)
-```
-
-**Example with path:**
-```bash
-# Update only .claude directory
-bash(cd .claude && ~/.claude/scripts/get_modules_by_depth.sh list)
-
-# Update specific feature directory
-bash(cd src/features/auth && ~/.claude/scripts/get_modules_by_depth.sh list)
-```
-
-**Parse Output**:
- Extract module paths from `depth:N|path:<PATH>|...` format
- Count total modules
- Identify which modules have/need CLAUDE.md
-
-**Example output:**
-```
-depth:5|path:./.claude/workflows/cli-templates/prompts/analysis|files:5|has_claude:no
-depth:4|path:./.claude/commands/cli/mode|files:3|has_claude:no
-depth:3|path:./.claude/commands/cli|files:6|has_claude:no
-depth:0|path:.|files:14|has_claude:yes
-```
-
-**Validation**:
- If --path specified, directory exists and is accessible
- Module list contains depth and path information
- At least one module exists
- All paths are relative to target directory (if --path used)
-
---
-
-### Phase 2: Plan Presentation
-
-**Decision Logic**:
- **Simple projects (≤20 modules)**: Present plan to user, wait for approval
- **Complex projects (>20 modules)**: Delegate to memory-bridge agent
-
-**Plan format:**
-```
-📋 Update Plan:
-  Tool: gemini
-  Total modules: 31
-
-  NEW CLAUDE.md files (30):
-    - ./.claude/workflows/cli-templates/prompts/analysis/CLAUDE.md
-    - ./.claude/commands/cli/mode/CLAUDE.md
-    - ... (28 more)
-
-  UPDATE existing CLAUDE.md files (1):
-    - ./CLAUDE.md
-
-  ⚠️ Confirm execution? (y/n)
-```
-
-**User Confirmation Required**: No execution without explicit approval
-
---
-
-### Phase 3: Depth-Parallel Execution
-
-**Pattern**: Process highest depth first, parallel within depth, sequential across depths.
-
-**Command structure:**
-```bash
-bash(cd <module-path> && ~/.claude/scripts/update_module_claude.sh "." "full" "<tool>" &)
-```
-
-**Example - Depth 5 (8 modules):**
-```bash
-bash(cd ./.claude/workflows/cli-templates/prompts/analysis && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini" &)
-```
-```bash
-bash(cd ./.claude/workflows/cli-templates/prompts/development && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini" &)
-```
-```bash
-bash(cd ./.claude/workflows/cli-templates/prompts/documentation && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini" &)
-```
-```bash
-bash(cd ./.claude/workflows/cli-templates/prompts/implementation && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini" &)
-```
-
-*Wait for depth 5 completion...*
-
-**Example - Depth 4 (7 modules):**
-```bash
-bash(cd ./.claude/commands/cli/mode && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini" &)
-```
-```bash
-bash(cd ./.claude/commands/workflow/brainstorm && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini" &)
-```
-
-*Continue for remaining depths (3 → 2 → 1 → 0)...*
-
-**Execution Rules**:
- Each command is separate bash() call
- Up to 4 concurrent jobs per depth
- Wait for all jobs in current depth before proceeding
- Extract path from `depth:N|path:<PATH>|...` format
- All paths relative to target directory (current dir or --path value)
-
-**Path Context**:
- Without --path: Paths relative to current directory
- With --path: Paths relative to specified target directory
- Module discovery runs in target directory context
-
---
-
-### Phase 4: Safety Verification
-
-**Check modified files:**
-```bash
-bash(git diff --cached --name-only | grep -v "CLAUDE.md" || echo "✅ Only CLAUDE.md files modified")
-```
-
-**Expected output:**
-```
-✅ Only CLAUDE.md files modified
-```
-
-**If non-CLAUDE.md files detected:**
-```
-⚠️ Warning: Non-CLAUDE.md files were modified
-Modified files: src/index.ts, package.json
-→ Run: git restore --staged .
-```
-
-**Display final status:**
-```bash
-bash(git status --short)
-```
-
-**Example output:**
-```
-A  .claude/workflows/cli-templates/prompts/analysis/CLAUDE.md
-A  .claude/commands/cli/mode/CLAUDE.md
-M  CLAUDE.md
-... (30 more files)
-```
-
-## Command Pattern Reference
-
-**Single module update:**
-```bash
-bash(cd <module-path> && ~/.claude/scripts/update_module_claude.sh "." "full" "<tool>" &)
-```
-
-**Components**:
- `cd <module-path>` - Navigate to module (from `path:` field)
- `&&` - Ensure cd succeeds
- `update_module_claude.sh` - Update script
- `"."` - Current directory
- `"full"` - Full update mode
- `"<tool>"` - gemini/qwen/codex
- `&` - Background execution
-
-**Path extraction:**
-```bash
-# From: depth:5|path:./src/auth|files:10|has_claude:no
-# Extract: ./src/auth
-# Command: bash(cd ./src/auth && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini" &)
-```
-
-## Complex Projects Strategy
-
-For projects >20 modules, delegate to memory-bridge agent:
-
-```javascript
-Task(
-  subagent_type="memory-bridge",
-  description="Complex project full update",
-  prompt=`
-CONTEXT:
- Total modules: ${module_count}
- Tool: ${tool}
- Mode: full
-
-MODULE LIST:
-${modules_output}
-
-REQUIREMENTS:
-1. Use TodoWrite to track each depth level
-2. Process depths N→0 sequentially, max 4 parallel per depth
-3. Command: cd "<path>" && update_module_claude.sh "." "full" "${tool}" &
-4. Extract path from "depth:N|path:<PATH>|..." format
-5. Verify all modules processed
-6. Run safety check
-7. Display git status
-`
-)
-```
-
-## Error Handling
-
- **Invalid path parameter**: Report error if --path directory doesn't exist, abort execution
- **Module discovery failure**: Report error, abort execution
- **User declines approval**: Abort execution, no changes made
- **Safety check failure**: Automatic staging revert, report modified files
- **Update script failure**: Report failed modules, continue with remaining
-
-## Coordinator Checklist
-
-✅ Parse `--tool` parameter (default: gemini)
-✅ Parse `--path` parameter (optional, default: current directory)
-✅ Execute git cache in current directory
-✅ Execute module discovery (with cd if --path specified)
-✅ Parse module list, count total modules
-✅ Determine strategy based on module count (≤20 vs >20)
-✅ Present plan with exact file paths
-✅ **Wait for user confirmation** (simple projects only)
-✅ Organize modules by depth
-✅ For each depth (highest to lowest):
-  - Launch up to 5 parallel updates
-  - Wait for depth completion
-  - Proceed to next depth
-✅ Run safety check after all updates
-✅ Display git status
-✅ Report completion summary
-
-
-
-## Tool Parameter Reference
-
-**Gemini** (default):
- Best for: Documentation generation, pattern recognition, architecture review
- Context window: Large, handles complex codebases
- Output style: Comprehensive, detailed explanations
-
-**Qwen**:
- Best for: Architecture analysis, system design documentation
- Context window: Large, similar to Gemini
- Output style: Structured, systematic analysis
-
-**Codex**:
- Best for: Implementation validation, code quality analysis
- Capabilities: Mathematical reasoning, autonomous development
- Output style: Technical, implementation-focused
-
-## Path Parameter Reference
-
-**Use Cases**:
-
-**Update configuration directory only:**
-```bash
-/memory:update-full --path .claude
-```
- Updates only .claude directory and subdirectories
- Useful after workflow or command modifications
- Faster than full project update
-
-**Update specific feature module:**
-```bash
-/memory:update-full --path src/features/auth
-```
- Updates authentication feature and sub-modules
- Ideal for feature-specific documentation
- Isolates scope for targeted updates
-
-**Update nested structure:**
-```bash
-/memory:update-full --path .claude/workflows/cli-templates
-```
- Updates deeply nested directory tree
- Maintains relative path structure in output
- All module paths relative to specified directory
-
-**Best Practices**:
- Use `--path` when working on specific features/modules
- Omit `--path` for project-wide architectural changes
- Combine with `--tool` for specialized documentation needs
- Verify directory exists before execution (automatic validation)
--- a/.claude/commands/memory/update-memory-related.md
+++ b/.claude/commands/memory/update-memory-related.md
@@ -1,306 +0,0 @@
---
-name: update-related
-description: Context-aware CLAUDE.md documentation updates based on recent changes
-argument-hint: "[--tool gemini|qwen|codex]"
---
-
-# Related Documentation Update (/memory:update-related)
-
-## Coordinator Role
-
-**This command orchestrates context-aware CLAUDE.md updates** for modules affected by recent changes using intelligent change detection.
-
-**Execution Model**:
-
-1. **Change Detection**: Analyze git changes to identify affected modules
-2. **Complexity Analysis**: Evaluate change count and determine strategy
-3. **Plan Presentation**: Show user which modules need updates
-4. **Depth-Parallel Execution**: Update affected modules by depth (highest to lowest)
-5. **Safety Verification**: Ensure only CLAUDE.md files modified
-
-**Tool Selection**:
- `--tool gemini` (default): Documentation generation, pattern recognition
- `--tool qwen`: Architecture analysis, system design docs
- `--tool codex`: Implementation validation, code quality analysis
-
-## Core Rules
-
-1. **Detect Changes First**: Use git diff to identify affected modules before updates
-2. **Wait for Approval**: Present plan, no execution without user confirmation
-3. **Related Mode**: Update only changed modules and their parent contexts
-4. **Depth-Parallel**: Same depth runs parallel (max 4 jobs), different depths sequential
-5. **Safety Check**: Verify only CLAUDE.md files modified, revert if source files touched
-6. **No Background Bash Tool**: Never use `run_in_background` parameter in bash() calls; use shell `&` for parallelism
-
-## Execution Workflow
-
-### Phase 1: Change Detection & Analysis
-
-**Refresh code index:**
-```bash
-bash(mcp__code-index__refresh_index)
-```
-
-**Detect changed modules:**
-```bash
-bash(~/.claude/scripts/detect_changed_modules.sh list)
-```
-
-**Cache git changes:**
-```bash
-bash(git add -A 2>/dev/null || true)
-```
-
-**Parse Output**:
- Extract changed module paths from `depth:N|path:<PATH>|...` format
- Count affected modules
- Identify which modules have/need CLAUDE.md updates
-
-**Example output:**
-```
-depth:3|path:./src/api/auth|files:5|types:[ts]|has_claude:no|change:new
-depth:2|path:./src/api|files:12|types:[ts]|has_claude:yes|change:modified
-depth:1|path:./src|files:8|types:[ts]|has_claude:yes|change:parent
-depth:0|path:.|files:14|has_claude:yes|change:parent
-```
-
-**Fallback behavior**:
- If no git changes detected, use recent modules (first 10 by depth)
-
-**Validation**:
- Changed module list contains valid paths
- At least one affected module exists
-
---
-
-### Phase 2: Plan Presentation
-
-**Decision Logic**:
- **Simple changes (≤15 modules)**: Present plan to user, wait for approval
- **Complex changes (>15 modules)**: Delegate to memory-bridge agent
-
-**Plan format:**
-```
-📋 Related Update Plan:
-  Tool: gemini
-  Changed modules: 4
-
-  NEW CLAUDE.md files (1):
-    - ./src/api/auth/CLAUDE.md [new module]
-
-  UPDATE existing CLAUDE.md files (3):
-    - ./src/api/CLAUDE.md [parent of changed auth/]
-    - ./src/CLAUDE.md [parent context]
-    - ./CLAUDE.md [root level]
-
-  ⚠️ Confirm execution? (y/n)
-```
-
-**User Confirmation Required**: No execution without explicit approval
-
---
-
-### Phase 3: Depth-Parallel Execution
-
-**Pattern**: Process highest depth first, parallel within depth, sequential across depths.
-
-**Command structure:**
-```bash
-bash(cd <module-path> && ~/.claude/scripts/update_module_claude.sh "." "related" "<tool>" &)
-```
-
-**Example - Depth 3 (new module):**
-```bash
-bash(cd ./src/api/auth && ~/.claude/scripts/update_module_claude.sh "." "related" "gemini" &)
-```
-
-*Wait for depth 3 completion...*
-
-**Example - Depth 2 (modified parent):**
-```bash
-bash(cd ./src/api && ~/.claude/scripts/update_module_claude.sh "." "related" "gemini" &)
-```
-
-*Wait for depth 2 completion...*
-
-**Example - Depth 1 & 0 (parent contexts):**
-```bash
-bash(cd ./src && ~/.claude/scripts/update_module_claude.sh "." "related" "gemini" &)
-```
-```bash
-bash(cd . && ~/.claude/scripts/update_module_claude.sh "." "related" "gemini" &)
-```
-
-*Wait for all depths completion...*
-
-**Execution Rules**:
- Each command is separate bash() call
- Up to 4 concurrent jobs per depth
- Wait for all jobs in current depth before proceeding
- Use "related" mode (not "full") for context-aware updates
- Extract path from `depth:N|path:<PATH>|...` format
-
-**Related Mode Behavior**:
- Updates module based on recent git changes
- Includes parent context for better documentation coherence
- More efficient than full updates for iterative development
-
---
-
-### Phase 4: Safety Verification
-
-**Check modified files:**
-```bash
-bash(git diff --cached --name-only | grep -v "CLAUDE.md" || echo "✅ Only CLAUDE.md files modified")
-```
-
-**Expected output:**
-```
-✅ Only CLAUDE.md files modified
-```
-
-**If non-CLAUDE.md files detected:**
-```
-⚠️ Warning: Non-CLAUDE.md files were modified
-Modified files: src/api/auth/index.ts, package.json
-→ Run: git restore --staged .
-```
-
-**Display final statistics:**
-```bash
-bash(git diff --stat)
-```
-
-**Example output:**
-```
-.claude/workflows/cli-templates/prompts/analysis/CLAUDE.md | 45 +++++++++++++++++++++
-src/api/CLAUDE.md                                          | 23 +++++++++--
-src/CLAUDE.md                                              | 12 ++++--
-CLAUDE.md                                                  | 8 ++--
-4 files changed, 82 insertions(+), 6 deletions(-)
-```
-
-## Command Pattern Reference
-
-**Single module update:**
-```bash
-bash(cd <module-path> && ~/.claude/scripts/update_module_claude.sh "." "related" "<tool>" &)
-```
-
-**Components**:
- `cd <module-path>` - Navigate to module (from `path:` field)
- `&&` - Ensure cd succeeds
- `update_module_claude.sh` - Update script
- `"."` - Current directory
- `"related"` - Related mode (context-aware, change-based)
- `"<tool>"` - gemini/qwen/codex
- `&` - Background execution
-
-**Path extraction:**
-```bash
-# From: depth:3|path:./src/api/auth|files:5|change:new|has_claude:no
-# Extract: ./src/api/auth
-# Command: bash(cd ./src/api/auth && ~/.claude/scripts/update_module_claude.sh "." "related" "gemini" &)
-```
-
-**Mode comparison:**
- `"full"` - Complete module documentation regeneration
- `"related"` - Context-aware update based on recent changes (faster)
-
-## Complex Changes Strategy
-
-For changes affecting >15 modules, delegate to memory-bridge agent:
-
-```javascript
-Task(
-  subagent_type="memory-bridge",
-  description="Complex project related update",
-  prompt=`
-CONTEXT:
- Total modules: ${change_count}
- Tool: ${tool}
- Mode: related
-
-MODULE LIST:
-${changed_modules_output}
-
-REQUIREMENTS:
-1. Use TodoWrite to track each depth level
-2. Process depths N→0 sequentially, max 4 parallel per depth
-3. Command: cd "<path>" && update_module_claude.sh "." "related" "${tool}" &
-4. Extract path from "depth:N|path:<PATH>|..." format
-5. Verify all ${change_count} modules processed
-6. Run safety check
-7. Display git diff --stat
-`
-)
-```
-
-## Error Handling
-
- **No changes detected**: Use fallback mode (recent 10 modules)
- **Change detection failure**: Report error, abort execution
- **User declines approval**: Abort execution, no changes made
- **Safety check failure**: Automatic staging revert, report modified files
- **Update script failure**: Report failed modules, continue with remaining
-
-## Coordinator Checklist
-
-✅ Parse `--tool` parameter (default: gemini)
-✅ Refresh code index for accurate change detection
-✅ Detect changed modules via detect_changed_modules.sh
-✅ Cache git changes to protect current state
-✅ Parse changed module list, count affected modules
-✅ Apply fallback if no changes detected (recent 10 modules)
-✅ Determine strategy based on change count (≤15 vs >15)
-✅ Present plan with exact file paths and change types
-✅ **Wait for user confirmation** (simple changes only)
-✅ Organize modules by depth
-✅ For each depth (highest to lowest):
-  - Launch up to 4 parallel updates with "related" mode
-  - Wait for depth completion
-  - Proceed to next depth
-✅ Run safety check after all updates
-✅ Display git diff statistics
-✅ Report completion summary
-
-## Usage Examples
-
-```bash
-# Daily development update (default: gemini)
-/memory:update-related
-
-# After feature work with specific tool
-/memory:update-related --tool qwen
-
-# Code quality review after implementation
-/memory:update-related --tool codex
-```
-
-## Tool Parameter Reference
-
-**Gemini** (default):
- Best for: Documentation generation, pattern recognition
- Use case: Daily development updates, feature documentation
- Output style: Comprehensive, contextual explanations
-
-**Qwen**:
- Best for: Architecture analysis, system design
- Use case: Structural changes, API design updates
- Output style: Structured, systematic documentation
-
-**Codex**:
- Best for: Implementation validation, code quality
- Use case: After implementation, refactoring work
- Output style: Technical, implementation-focused
-
-## Comparison with Full Update
-
-| Aspect | Related Update | Full Update |
-|--------|----------------|-------------|
-| **Scope** | Changed modules only | All project modules |
-| **Speed** | Fast (minutes) | Slower (10-30 min) |
-| **Use case** | Daily development | Major refactoring |
-| **Mode** | `"related"` | `"full"` |
-| **Trigger** | After commits | After major changes |
-| **Complexity threshold** | ≤15 modules | ≤20 modules |
--- a/.claude/commands/memory/update-related.md
+++ b/.claude/commands/memory/update-related.md
@@ -0,0 +1,352 @@
+---
+name: update-related
+description: Context-aware CLAUDE.md documentation updates based on recent changes with agent-based execution and tool fallback
+argument-hint: "[--tool gemini|qwen|codex]"
+---
+
+# Related Documentation Update (/memory:update-related)
+
+## Overview
+
+Orchestrates context-aware CLAUDE.md updates for changed modules using batched agent execution with automatic tool fallback (gemini→qwen→codex).
+
+**Parameters**:
+- `--tool <gemini|qwen|codex>`: Primary tool (default: gemini)
+
+**Execution Flow**:
+1. Change Detection → 2. Plan Presentation → 3. Batched Agent Execution → 4. Safety Verification
+
+## Core Rules
+
+1. **Detect Changes First**: Use git diff to identify affected modules
+2. **Wait for Approval**: Present plan, no execution without user confirmation
+3. **Execution Strategy**:
+   - <15 modules: Direct parallel execution (max 4 concurrent per depth, no agent overhead)
+   - ≥15 modules: Agent batch processing (4 modules/agent, 73% overhead reduction)
+4. **Tool Fallback**: Auto-retry with fallback tools on failure
+5. **Depth Sequential**: Process depths N→0, parallel batches within depth (both modes)
+6. **Related Mode**: Update only changed modules and their parent contexts
+
+## Tool Fallback Hierarchy
+
+```javascript
+--tool gemini  →  [gemini, qwen, codex]  // default
+--tool qwen    →  [qwen, gemini, codex]
+--tool codex   →  [codex, gemini, qwen]
+```
+
+**Trigger**: Non-zero exit code from update script
+
+## Phase 1: Change Detection & Analysis
+
+```bash
+# Refresh code index
+bash(mcp__code-index__refresh_index)
+
+# Detect changed modules
+bash(~/.claude/scripts/detect_changed_modules.sh list)
+
+# Cache git changes
+bash(git add -A 2>/dev/null || true)
+```
+
+**Parse output** `depth:N|path:<PATH>|change:<TYPE>` to extract affected modules.
+
+**Smart filter**: Auto-detect and skip tests/build/config/docs based on project tech stack (Node.js/Python/Go/Rust/etc).
+
+**Fallback**: If no changes detected, use recent modules (first 10 by depth).
+
+## Phase 2: Plan Presentation
+
+**Present filtered plan**:
+```
+Related Update Plan:
+  Tool: gemini (fallback: qwen → codex)
+  Changed: 4 modules | Batching: 4 modules/agent
+
+  Will update:
+  - ./src/api/auth (5 files) [new module]
+  - ./src/api (12 files) [parent of changed auth/]
+  - ./src (8 files) [parent context]
+  - . (14 files) [root level]
+
+  Auto-skipped (12 paths):
+  - Tests: ./src/api/auth.test.ts (8 paths)
+  - Config: tsconfig.json (3 paths)
+  - Other: node_modules (1 path)
+
+  Agent allocation:
+  - Depth 3 (1 module): 1 agent [1]
+  - Depth 2 (1 module): 1 agent [1]
+  - Depth 1 (1 module): 1 agent [1]
+  - Depth 0 (1 module): 1 agent [1]
+
+  Confirm execution? (y/n)
+```
+
+**Decision logic**:
+- User confirms "y": Proceed with execution
+- User declines "n": Abort, no changes
+- <15 modules: Direct execution
+- ≥15 modules: Agent batch execution
+
+## Phase 3A: Direct Execution (<15 modules)
+
+**Strategy**: Parallel execution within depth (max 4 concurrent), no agent overhead, tool fallback per module.
+
+```javascript
+let modules_by_depth = group_by_depth(changed_modules);
+let tool_order = construct_tool_order(primary_tool);
+
+for (let depth of sorted_depths.reverse()) {  // N → 0
+  let modules = modules_by_depth[depth];
+  let batches = batch_modules(modules, 4);  // Split into groups of 4
+
+  for (let batch of batches) {
+    // Execute batch in parallel (max 4 concurrent)
+    let parallel_tasks = batch.map(module => {
+      return async () => {
+        let success = false;
+        for (let tool of tool_order) {
+          let exit_code = bash(cd ${module.path} && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "${tool}");
+          if (exit_code === 0) {
+            report("${module.path} updated with ${tool}");
+            success = true;
+            break;
+          }
+        }
+        if (!success) {
+          report("FAILED: ${module.path} failed all tools");
+        }
+      };
+    });
+
+    await Promise.all(parallel_tasks.map(task => task()));  // Run batch in parallel
+  }
+}
+```
+
+**Benefits**:
+- No agent startup overhead
+- Parallel execution within depth (max 4 concurrent)
+- Tool fallback still applies per module
+- Faster for small changesets (<15 modules)
+- Same batching strategy as Phase 3B but without agent layer
+
+---
+
+## Phase 3B: Agent Batch Execution (≥15 modules)
+
+### Batching Strategy
+
+```javascript
+// Batch modules into groups of 4
+function batch_modules(modules, batch_size = 4) {
+  let batches = [];
+  for (let i = 0; i < modules.length; i += batch_size) {
+    batches.push(modules.slice(i, i + batch_size));
+  }
+  return batches;
+}
+// Examples: 10→[4,4,2] | 8→[4,4] | 3→[3]
+```
+
+### Coordinator Orchestration
+
+```javascript
+let modules_by_depth = group_by_depth(changed_modules);
+let tool_order = construct_tool_order(primary_tool);
+
+for (let depth of sorted_depths.reverse()) {  // N → 0
+  let batches = batch_modules(modules_by_depth[depth], 4);
+  let worker_tasks = [];
+
+  for (let batch of batches) {
+    worker_tasks.push(
+      Task(
+        subagent_type="memory-bridge",
+        description=`Update ${batch.length} modules at depth ${depth}`,
+        prompt=generate_batch_worker_prompt(batch, tool_order, "related")
+      )
+    );
+  }
+
+  await parallel_execute(worker_tasks);  // Batches run in parallel
+}
+```
+
+### Batch Worker Prompt Template
+
+```
+PURPOSE: Update CLAUDE.md for assigned modules with tool fallback (related mode)
+
+TASK:
+Update documentation for the following modules based on recent changes. For each module, try tools in order until success.
+
+MODULES:
+{{module_path_1}}
+{{module_path_2}}
+{{module_path_3}}
+{{module_path_4}}
+
+TOOLS (try in order):
+1. {{tool_1}}
+2. {{tool_2}}
+3. {{tool_3}}
+
+EXECUTION:
+For each module above:
+  1. cd "{{module_path}}"
+  2. Try tool 1:
+     bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "{{tool_1}}")
+     → Success: Report "{{module_path}} updated with {{tool_1}}", proceed to next module
+     → Failure: Try tool 2
+  3. Try tool 2:
+     bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "{{tool_2}}")
+     → Success: Report "{{module_path}} updated with {{tool_2}}", proceed to next module
+     → Failure: Try tool 3
+  4. Try tool 3:
+     bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "{{tool_3}}")
+     → Success: Report "{{module_path}} updated with {{tool_3}}", proceed to next module
+     → Failure: Report "FAILED: {{module_path}} failed all tools", proceed to next module
+
+REPORTING:
+Report final summary with:
+- Total processed: X modules
+- Successful: Y modules
+- Failed: Z modules
+- Tool usage: {{tool_1}}:X, {{tool_2}}:Y, {{tool_3}}:Z
+- Detailed results for each module
+```
+
+### Example Execution
+
+**Depth 3 (new module)**:
+```javascript
+Task(subagent_type="memory-bridge", batch=[./src/api/auth], mode="related")
+```
+
+**Benefits**:
+- 4 modules → 1 agent (75% reduction)
+- Parallel batches, sequential within batch
+- Each module gets full fallback chain
+- Context-aware updates based on git changes
+
+## Phase 4: Safety Verification
+
+```bash
+# Check only CLAUDE.md modified
+bash(git diff --cached --name-only | grep -v "CLAUDE.md" || echo "Only CLAUDE.md files modified")
+
+# Display statistics
+bash(git diff --stat)
+```
+
+**Aggregate results**:
+```
+Update Summary:
+  Total: 4 | Success: 4 | Failed: 0
+
+  Tool usage:
+  - gemini: 4 modules
+  - qwen: 0 modules (fallback)
+  - codex: 0 modules
+
+  Changes:
+  src/api/auth/CLAUDE.md  | 45 +++++++++++++++++++++
+  src/api/CLAUDE.md       | 23 +++++++++--
+  src/CLAUDE.md           | 12 ++++--
+  CLAUDE.md               | 8 ++--
+  4 files changed, 82 insertions(+), 6 deletions(-)
+```
+
+## Execution Summary
+
+**Module Count Threshold**:
+- **<15 modules**: Coordinator executes Phase 3A (Direct Execution)
+- **≥15 modules**: Coordinator executes Phase 3B (Agent Batch Execution)
+
+**Agent Hierarchy** (for ≥15 modules):
+- **Coordinator**: Handles batch division, spawns worker agents per depth
+- **Worker Agents**: Each processes 4 modules with tool fallback (related mode)
+
+## Error Handling
+
+**Batch Worker**:
+- Tool fallback per module (auto-retry)
+- Batch isolation (failures don't propagate)
+- Clear per-module status reporting
+
+**Coordinator**:
+- No changes: Use fallback (recent 10 modules)
+- User decline: No execution
+- Safety check fail: Auto-revert staging
+- Partial failures: Continue execution, report failed modules
+
+**Fallback Triggers**:
+- Non-zero exit code
+- Script timeout
+- Unexpected output
+
+## Tool Reference
+
+| Tool   | Best For                       | Fallback To    |
+|--------|--------------------------------|----------------|
+| gemini | Documentation, patterns        | qwen → codex   |
+| qwen   | Architecture, system design    | gemini → codex |
+| codex  | Implementation, code quality   | gemini → qwen  |
+
+## Usage Examples
+
+```bash
+# Daily development update
+/memory:update-related
+
+# After feature work with specific tool
+/memory:update-related --tool qwen
+
+# Code quality review after implementation
+/memory:update-related --tool codex
+```
+
+## Key Advantages
+
+**Efficiency**: 30 modules → 8 agents (73% reduction)
+**Resilience**: 3-tier fallback per module
+**Performance**: Parallel batches, no concurrency limits
+**Context-aware**: Updates based on actual git changes
+**Fast**: Only affected modules, not entire project
+
+## Coordinator Checklist
+
+- Parse `--tool` (default: gemini)
+- Refresh code index for accurate change detection
+- Detect changed modules via detect_changed_modules.sh
+- **Smart filter modules** (auto-detect tech stack, skip tests/build/config/docs)
+- Cache git changes
+- Apply fallback if no changes (recent 10 modules)
+- Construct tool fallback order
+- **Present filtered plan** with skip reasons and change types
+- **Wait for y/n confirmation**
+- Determine execution mode:
+  - **<15 modules**: Direct execution (Phase 3A)
+    - For each depth (N→0): Sequential module updates with tool fallback
+  - **≥15 modules**: Agent batch execution (Phase 3B)
+    - For each depth (N→0): Batch modules (4 per batch), spawn batch workers in parallel
+- Wait for depth/batch completion
+- Aggregate results
+- Safety check (only CLAUDE.md modified)
+- Display git diff statistics + summary
+
+## Comparison with Full Update
+
+| Aspect | Related Update | Full Update |
+|--------|----------------|-------------|
+| **Scope** | Changed modules only | All project modules |
+| **Speed** | Fast (minutes) | Slower (10-30 min) |
+| **Use case** | Daily development | Major refactoring |
+| **Mode** | `"related"` | `"full"` |
+| **Trigger** | After commits | After major changes |
+| **Batching** | 4 modules/agent | 4 modules/agent |
+| **Fallback** | gemini→qwen→codex | gemini→qwen→codex |
+| **Complexity threshold** | ≤15 modules | ≤20 modules |
--- a/.claude/commands/workflow/review.md
+++ b/.claude/commands/workflow/review.md
@@ -99,10 +99,10 @@ After bash validation, the model takes control to:
     ```
   - Use Gemini for security analysis:
     ```bash
-     cd .workflow/${sessionId} && ~/.claude/scripts/gemini-wrapper -p "
+     cd .workflow/${sessionId} && gemini -p "
     PURPOSE: Security audit of completed implementation
     TASK: Review code for security vulnerabilities, insecure patterns, auth/authz issues
-     CONTEXT: @{.summaries/IMPL-*.md,../..,../../CLAUDE.md}
+     CONTEXT: @.summaries/IMPL-*.md,../.. @../../CLAUDE.md
     EXPECTED: Security findings report with severity levels
     RULES: Focus on OWASP Top 10, authentication, authorization, data validation, injection risks
     " --approval-mode yolo
@@ -111,10 +111,10 @@ After bash validation, the model takes control to:
   **Architecture Review** (`--type=architecture`):
   - Use Qwen for architecture analysis:
     ```bash
-     cd .workflow/${sessionId} && ~/.claude/scripts/qwen-wrapper -p "
+     cd .workflow/${sessionId} && qwen -p "
     PURPOSE: Architecture compliance review
     TASK: Evaluate adherence to architectural patterns, identify technical debt, review design decisions
-     CONTEXT: @{.summaries/IMPL-*.md,../..,../../CLAUDE.md}
+     CONTEXT: @.summaries/IMPL-*.md,../.. @../../CLAUDE.md
     EXPECTED: Architecture assessment with recommendations
     RULES: Check for patterns, separation of concerns, modularity, scalability
     " --approval-mode yolo
@@ -123,10 +123,10 @@ After bash validation, the model takes control to:
   **Quality Review** (`--type=quality`):
   - Use Gemini for code quality:
     ```bash
-     cd .workflow/${sessionId} && ~/.claude/scripts/gemini-wrapper -p "
+     cd .workflow/${sessionId} && gemini -p "
     PURPOSE: Code quality and best practices review
     TASK: Assess code readability, maintainability, adherence to best practices
-     CONTEXT: @{.summaries/IMPL-*.md,../..,../../CLAUDE.md}
+     CONTEXT: @.summaries/IMPL-*.md,../.. @../../CLAUDE.md
     EXPECTED: Quality assessment with improvement suggestions
     RULES: Check for code smells, duplication, complexity, naming conventions
     " --approval-mode yolo
@@ -143,10 +143,10 @@ After bash validation, the model takes control to:
     ' {} \;

     # Check implementation summaries against requirements
-     cd .workflow/${sessionId} && ~/.claude/scripts/gemini-wrapper -p "
+     cd .workflow/${sessionId} && gemini -p "
     PURPOSE: Verify all requirements and acceptance criteria are met
     TASK: Cross-check implementation summaries against original requirements
-     CONTEXT: @{.task/IMPL-*.json,.summaries/IMPL-*.md,../..,../../CLAUDE.md}
+     CONTEXT: @.task/IMPL-*.json,.summaries/IMPL-*.md,../.. @../../CLAUDE.md
     EXPECTED:
     - Requirements coverage matrix
     - Acceptance criteria verification
--- a/.claude/commands/workflow/tdd-verify.md
+++ b/.claude/commands/workflow/tdd-verify.md
@@ -3,7 +3,7 @@ name: tdd-verify
 description: Verify TDD workflow compliance and generate quality report

 argument-hint: "[optional: WFS-session-id]"
-allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(gemini-wrapper:*)
+allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(gemini:*)
 ---

 # TDD Verification Command (/workflow:tdd-verify)
@@ -94,7 +94,7 @@ find .workflow/{sessionId}/.task/ -name '*.json' -exec jq -r '.meta.agent' {} \;
 **Gemini analysis for comprehensive TDD compliance report**

 ```bash
-cd project-root && ~/.claude/scripts/gemini-wrapper -p "
+cd project-root && gemini -p "
 PURPOSE: Generate TDD compliance report
 TASK: Analyze TDD workflow execution and generate quality report
 CONTEXT: @{.workflow/{sessionId}/.task/*.json,.workflow/{sessionId}/.summaries/*,.workflow/{sessionId}/.process/tdd-cycle-report.md}
--- a/.claude/commands/workflow/test-cycle-execute.md
+++ b/.claude/commands/workflow/test-cycle-execute.md
@@ -226,11 +226,11 @@ Iteration N (managed by test-cycle-execute orchestrator):

 #### CLI Analysis Command (executed by orchestrator)
 ```bash
-cd {project_root} && ~/.claude/scripts/gemini-wrapper -p "
+cd {project_root} && gemini -p "
 PURPOSE: Analyze test failures and generate fix strategy
 TASK: Review test failures and identify root causes
 MODE: analysis
-CONTEXT: @{test files, implementation files}
+CONTEXT: @test files @ implementation files

 [Test failure context and requirements...]

--- a/.claude/commands/workflow/tools/task-generate-tdd.md
+++ b/.claude/commands/workflow/tools/task-generate-tdd.md
@@ -2,7 +2,7 @@
 name: task-generate-tdd
 description: Generate TDD task chains with Red-Green-Refactor dependencies
 argument-hint: "--session WFS-session-id [--agent]"
-allowed-tools: Read(*), Write(*), Bash(gemini-wrapper:*), TodoWrite(*)
+allowed-tools: Read(*), Write(*), Bash(gemini:*), TodoWrite(*)
 ---

 # TDD Task Generation Command
--- a/.claude/commands/workflow/tools/task-generate.md
+++ b/.claude/commands/workflow/tools/task-generate.md
@@ -256,7 +256,7 @@ This enhanced 5-field schema embeds all necessary context, artifacts, and execut
        "action": "Analyze existing code patterns and identify modification targets",
        "commands": [
          "bash(cd \"[focus_paths]\")",
-          "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Identify modification targets TASK: Analyze '[title]' and locate specific files/functions/lines to modify CONTEXT: [synthesis_specification] [individual_artifacts] EXPECTED: Code locations in format 'file:function:lines' RULES: Prioritize synthesis-specification.md, identify exact modification points\")"
+          "bash(gemini \"PURPOSE: Identify modification targets TASK: Analyze '[title]' and locate specific files/functions/lines to modify CONTEXT: [synthesis_specification] [individual_artifacts] EXPECTED: Code locations in format 'file:function:lines' RULES: Prioritize synthesis-specification.md, identify exact modification points\")"
        ],
        "output_to": "task_context_with_targets",
        "on_error": "fail"
--- a/.claude/commands/workflow/tools/test-concept-enhanced.md
+++ b/.claude/commands/workflow/tools/test-concept-enhanced.md
@@ -48,7 +48,7 @@ Specialized analysis tool for test generation workflows that uses Gemini to anal

 **Tool Configuration**:
 ```bash
-cd .workflow/{test_session_id}/.process && ~/.claude/scripts/gemini-wrapper -p "
+cd .workflow/{test_session_id}/.process && gemini -p "
 PURPOSE: Analyze test coverage gaps and design comprehensive test generation strategy
 TASK: Study implementation context, existing tests, and generate test requirements for missing coverage
 MODE: analysis
--- a/.claude/commands/workflow/tools/test-task-generate.md
+++ b/.claude/commands/workflow/tools/test-task-generate.md
@@ -198,7 +198,7 @@ Generate **TWO task JSON files**:
        "Codex generates comprehensive test suite",
        "Codex validates test syntax and executability"
      ],
-      "command": "bash(codex -C [focus_paths] --full-auto exec \"PURPOSE: Generate comprehensive test suite TASK: Create test files based on TEST_ANALYSIS_RESULTS.md section 5 MODE: write CONTEXT: @{.workflow/WFS-test-[session]/.process/TEST_ANALYSIS_RESULTS.md,.workflow/WFS-test-[session]/.process/test-context-package.json} EXPECTED: All test files with happy path, error handling, edge cases, integration tests RULES: Follow test framework conventions, ensure tests are executable\" --skip-git-repo-check -s danger-full-access)",
+      "command": "bash(codex -C [focus_paths] --full-auto exec \"PURPOSE: Generate comprehensive test suite TASK: Create test files based on TEST_ANALYSIS_RESULTS.md section 5 MODE: write CONTEXT: @.workflow/WFS-test-[session]/.process/TEST_ANALYSIS_RESULTS.md @.workflow/WFS-test-[session]/.process/test-context-package.json EXPECTED: All test files with happy path, error handling, edge cases, integration tests RULES: Follow test framework conventions, ensure tests are executable\" --skip-git-repo-check -s danger-full-access)",
      "depends_on": [],
      "output": "test_generation"
    }],
@@ -323,7 +323,7 @@ Generate **TWO task JSON files**:
          "cycle_pattern": "test → gemini_diagnose → manual_fix (or codex if needed) → retest",
          "tools": {
            "test_execution": "bash(test_command)",
-            "diagnosis": "gemini-wrapper (MODE: analysis, uses bug-fix template)",
+            "diagnosis": "gemini (MODE: analysis, uses bug-fix template)",
            "fix_application": "manual (default) or codex exec resume --last (if explicitly needed)",
            "verification": "bash(test_command) + regression_check"
          },
@@ -354,11 +354,11 @@ Generate **TWO task JSON files**:
        "      * Source files from focus_paths",
        "      * Implementation summaries from source session",
        "    - Execute Gemini analysis with bug-fix template:",
-        "      bash(cd .workflow/WFS-test-[session]/.process && ~/.claude/scripts/gemini-wrapper --all-files -p \"",
+        "      bash(cd .workflow/WFS-test-[session]/.process && gemini \"",
        "      PURPOSE: Diagnose test failure iteration [N] and propose minimal fix",
        "      TASK: Systematic bug analysis and fix recommendations for test failure",
        "      MODE: analysis",
-        "      CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}",
+        "      CONTEXT: @CLAUDE.md,**/*CLAUDE.md",
        "               Test output: [test_failures]",
        "               Source files: [focus_paths]",
        "               Implementation: [implementation_context]",
--- a/.claude/scripts/gemini-wrapper
+++ b/.claude/scripts/gemini-wrapper
@@ -1,288 +0,0 @@
-#!/bin/bash
-# gemini-wrapper - Token-aware wrapper for gemini command
-# Location: ~/.claude/scripts/gemini-wrapper
-#
-# This wrapper automatically manages --all-files flag based on project token count
-# and provides intelligent approval mode defaults
-#
-# Usage: gemini-wrapper [all gemini options]
-#
-# Approval Mode Options:
-#   --approval-mode default    : Prompt for approval on each tool call (default)
-#   --approval-mode auto_edit  : Auto-approve edit tools, prompt for others
-#   --approval-mode yolo       : Auto-approve all tool calls
-#
-# Note: Executes in current working directory
-
-set -e
-
-# Function to show help
-show_help() {
-    echo "gemini-wrapper - Token-aware wrapper for gemini command"
-    echo ""
-    echo "Usage: gemini-wrapper [options] [gemini options]"
-    echo ""
-    echo "Options:"
-    echo "  --approval-mode <mode>  Sets the approval mode for tool calls"
-    echo "                          Available modes:"
-    echo "                            default    : Prompt for approval on each tool call (default)"
-    echo "                            auto_edit  : Auto-approve edit tools, prompt for others"
-    echo "                            yolo       : Auto-approve all tool calls"
-    echo "  --help                  Show this help message"
-    echo ""
-    echo "Features:"
-    echo "  - Automatically manages --all-files flag based on project token count"
-    echo "  - Intelligent approval mode detection based on task type"
-    echo "  - Token limit: $DEFAULT_TOKEN_LIMIT (set GEMINI_TOKEN_LIMIT to override)"
-    echo ""
-    echo "Examples:"
-    echo "  gemini-wrapper -p \"Analyze the codebase structure\""
-    echo "  gemini-wrapper --approval-mode yolo -p \"Implement user authentication\""
-    echo "  gemini-wrapper --approval-mode auto_edit -p \"Fix all linting errors\""
-    echo ""
-}
-
-# Configuration
-DEFAULT_TOKEN_LIMIT=2000000
-TOKEN_LIMIT=${GEMINI_TOKEN_LIMIT:-$DEFAULT_TOKEN_LIMIT}
-
-# Colors for output
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-NC='\033[0m' # No Color
-
-# Respect custom Gemini base URL
-if [[ -n "$GOOGLE_GEMINI_BASE_URL" ]]; then
-    echo -e "${GREEN}🌐 Using custom Gemini base URL: $GOOGLE_GEMINI_BASE_URL${NC}" >&2
-    export GOOGLE_GEMINI_BASE_URL
-fi
-
-# Function to count tokens (approximate: chars/4) - optimized version
-count_tokens() {
-    local total_chars=0
-    local file_count=0
-
-    # Use single find with bulk wc for better performance
-    # Common source file extensions
-    local extensions="py js ts tsx jsx java cpp c h rs go md txt json yaml yml xml html css scss sass php rb sh bash"
-
-    # Build find command with extension patterns
-    local find_cmd="find . -type f \("
-    local first=true
-    for ext in $extensions; do
-        if [[ "$first" == true ]]; then
-            find_cmd+=" -name \"*.$ext\""
-            first=false
-        else
-            find_cmd+=" -o -name \"*.$ext\""
-        fi
-    done
-    find_cmd+=" \)"
-
-    # Exclude common build/cache directories
-    find_cmd+=" -not -path \"*/node_modules/*\""
-    find_cmd+=" -not -path \"*/.git/*\""
-    find_cmd+=" -not -path \"*/dist/*\""
-    find_cmd+=" -not -path \"*/build/*\""
-    find_cmd+=" -not -path \"*/.next/*\""
-    find_cmd+=" -not -path \"*/.nuxt/*\""
-    find_cmd+=" -not -path \"*/target/*\""
-    find_cmd+=" -not -path \"*/vendor/*\""
-    find_cmd+=" -not -path \"*/__pycache__/*\""
-    find_cmd+=" -not -path \"*/.cache/*\""
-    find_cmd+=" 2>/dev/null"
-
-    # Use efficient bulk processing with wc
-    if command -v wc >/dev/null 2>&1; then
-        # Try bulk wc first - much faster for many files
-        local wc_output
-        wc_output=$(eval "$find_cmd" | xargs wc -c 2>/dev/null | tail -n 1)
-
-        # Parse the total line (last line of wc output when processing multiple files)
-        if [[ -n "$wc_output" && "$wc_output" =~ ^[[:space:]]*([0-9]+)[[:space:]]+total[[:space:]]*$ ]]; then
-            total_chars="${BASH_REMATCH[1]}"
-            file_count=$(eval "$find_cmd" | wc -l 2>/dev/null || echo 0)
-        else
-            # Fallback: single file processing
-            while IFS= read -r file; do
-                if [[ -f "$file" && -r "$file" ]]; then
-                    local chars=$(wc -c < "$file" 2>/dev/null || echo 0)
-                    total_chars=$((total_chars + chars))
-                    file_count=$((file_count + 1))
-                fi
-            done < <(eval "$find_cmd")
-        fi
-    else
-        # No wc available - fallback method
-        while IFS= read -r file; do
-            if [[ -f "$file" && -r "$file" ]]; then
-                local chars=$(stat -c%s "$file" 2>/dev/null || echo 0)
-                total_chars=$((total_chars + chars))
-                file_count=$((file_count + 1))
-            fi
-        done < <(eval "$find_cmd")
-    fi
-
-    local estimated_tokens=$((total_chars / 4))
-    echo "$estimated_tokens $file_count"
-}
-
-# Function to validate approval mode
-validate_approval_mode() {
-    local mode="$1"
-    case "$mode" in
-        "default"|"auto_edit"|"yolo")
-            return 0
-            ;;
-        *)
-            echo -e "${RED}❌ Invalid approval mode: $mode${NC}" >&2
-            echo -e "${YELLOW}Valid modes: default, auto_edit, yolo${NC}" >&2
-            return 1
-            ;;
-    esac
-}
-
-# Parse arguments to check for flags
-has_all_files=false
-has_approval_mode=false
-approval_mode_value=""
-args=()
-i=0
-
-# Parse arguments with proper handling of --approval-mode value
-args=("$@")  # Start with all arguments
-parsed_args=()
-skip_next=false
-
-for ((i=0; i<${#args[@]}; i++)); do
-    if [[ "$skip_next" == true ]]; then
-        skip_next=false
-        continue
-    fi
-
-    arg="${args[i]}"
-    case "$arg" in
-        "--help"|"-h")
-            show_help
-            exit 0
-            ;;
-        "--all-files")
-            has_all_files=true
-            parsed_args+=("$arg")
-            ;;
-        "--approval-mode")
-            has_approval_mode=true
-            # Get the next argument as the mode value
-            if [[ $((i+1)) -lt ${#args[@]} ]]; then
-                approval_mode_value="${args[$((i+1))]}"
-                if validate_approval_mode "$approval_mode_value"; then
-                    parsed_args+=("$arg" "$approval_mode_value")
-                    skip_next=true
-                else
-                    exit 1
-                fi
-            else
-                echo -e "${RED}❌ --approval-mode requires a value${NC}" >&2
-                echo -e "${YELLOW}Valid modes: default, auto_edit, yolo${NC}" >&2
-                exit 1
-            fi
-            ;;
-        --approval-mode=*)
-            has_approval_mode=true
-            approval_mode_value="${arg#*=}"
-            if validate_approval_mode "$approval_mode_value"; then
-                parsed_args+=("$arg")
-            else
-                exit 1
-            fi
-            ;;
-        *)
-            parsed_args+=("$arg")
-            ;;
-    esac
-done
-
-# Replace args with parsed_args
-args=("${parsed_args[@]}")
-
-# Analyze current working directory
-echo -e "${GREEN}📁 Analyzing current directory: $(pwd)${NC}" >&2
-
-# Count tokens (in the target directory if -c was used)
-echo -e "${YELLOW}🔍 Analyzing project size...${NC}" >&2
-read -r token_count file_count <<< "$(count_tokens)"
-
-echo -e "${YELLOW}📊 Project stats: ~${token_count} tokens across ${file_count} files${NC}" >&2
-
-# Decision logic for --all-files flag
-if [[ $token_count -lt $TOKEN_LIMIT ]]; then
-    if [[ "$has_all_files" == false ]]; then
-        echo -e "${GREEN}✅ Small project (${token_count} < ${TOKEN_LIMIT} tokens): Adding --all-files${NC}" >&2
-        args=("--all-files" "${args[@]}")
-    else
-        echo -e "${GREEN}✅ Small project (${token_count} < ${TOKEN_LIMIT} tokens): Keeping --all-files${NC}" >&2
-    fi
-else
-    if [[ "$has_all_files" == true ]]; then
-        echo -e "${RED}⚠️  Large project (${token_count} >= ${TOKEN_LIMIT} tokens): Removing --all-files to avoid token limits${NC}" >&2
-        echo -e "${YELLOW}💡 Consider using specific @{patterns} for targeted analysis${NC}" >&2
-        # Remove --all-files from args
-        new_args=()
-        for arg in "${args[@]}"; do
-            if [[ "$arg" != "--all-files" ]]; then
-                new_args+=("$arg")
-            fi
-        done
-        args=("${new_args[@]}")
-    else
-        echo -e "${RED}⚠️  Large project (${token_count} >= ${TOKEN_LIMIT} tokens): Avoiding --all-files${NC}" >&2
-        echo -e "${YELLOW}💡 Consider using specific @{patterns} for targeted analysis${NC}" >&2
-    fi
-fi
-
-# Auto-add approval-mode if not specified
-if [[ "$has_approval_mode" == false ]]; then
-    # Intelligent approval mode detection based on prompt content
-    prompt_text="${args[*]}"
-
-    # Analysis/Research tasks - use default (prompt for each tool)
-    if [[ "$prompt_text" =~ (analyze|analysis|review|understand|inspect|examine|research|study|explore|investigate) ]]; then
-        echo -e "${GREEN}📋 Analysis task detected: Adding --approval-mode default${NC}" >&2
-        args=("--approval-mode" "default" "${args[@]}")
-
-    # Development/Edit tasks - use auto_edit (auto-approve edits, prompt for others)
-    elif [[ "$prompt_text" =~ (implement|create|build|develop|code|write|edit|modify|update|fix|refactor|generate) ]]; then
-        echo -e "${GREEN}🔧 Development task detected: Adding --approval-mode auto_edit${NC}" >&2
-        args=("--approval-mode" "auto_edit" "${args[@]}")
-
-    # Automation/Batch tasks - use yolo (auto-approve all)
-    elif [[ "$prompt_text" =~ (automate|batch|mass|bulk|all|execute|run|deploy|install|setup) ]]; then
-        echo -e "${YELLOW}⚡ Automation task detected: Adding --approval-mode yolo${NC}" >&2
-        args=("--approval-mode" "yolo" "${args[@]}")
-
-    # Default fallback - use default mode for safety
-    else
-        echo -e "${YELLOW}🔍 General task detected: Adding --approval-mode default${NC}" >&2
-        args=("--approval-mode" "default" "${args[@]}")
-    fi
-
-    # Show approval mode explanation
-    case "${args[1]}" in
-        "default")
-            echo -e "${YELLOW}   → Will prompt for approval on each tool call${NC}" >&2
-            ;;
-        "auto_edit")
-            echo -e "${YELLOW}   → Will auto-approve edit tools, prompt for others${NC}" >&2
-            ;;
-        "yolo")
-            echo -e "${YELLOW}   → Will auto-approve all tool calls${NC}" >&2
-            ;;
-    esac
-fi
-
-# Show final command (for transparency)
-echo -e "${YELLOW}🚀 Executing: gemini ${args[*]}${NC}" >&2
-
-# Execute gemini with adjusted arguments (we're already in the right directory)
-gemini "${args[@]}"
--- a/.claude/scripts/qwen-wrapper
+++ b/.claude/scripts/qwen-wrapper
@@ -1,228 +0,0 @@
-#!/bin/bash
-# qwen-wrapper - Token-aware wrapper for qwen command
-# Location: ~/.claude/scripts/qwen-wrapper
-#
-# This wrapper automatically manages --all-files flag based on project token count
-# and provides intelligent approval mode defaults
-#
-# Usage: qwen-wrapper [all qwen options]
-#
-# Approval Mode Options:
-#   --approval-mode default    : Prompt for approval on each tool call (default)
-#   --approval-mode auto_edit  : Auto-approve edit tools, prompt for others
-#   --approval-mode yolo       : Auto-approve all tool calls
-#
-# Note: Executes in current working directory
-
-set -e
-
-# Function to show help
-show_help() {
-    echo "qwen-wrapper - Token-aware wrapper for qwen command"
-    echo ""
-    echo "Usage: qwen-wrapper [options] [qwen options]"
-    echo ""
-    echo "Options:"
-    echo "  --approval-mode <mode>  Sets the approval mode for tool calls"
-    echo "                          Available modes:"
-    echo "                            default    : Prompt for approval on each tool call (default)"
-    echo "                            auto_edit  : Auto-approve edit tools, prompt for others"
-    echo "                            yolo       : Auto-approve all tool calls"
-    echo "  --help                  Show this help message"
-    echo ""
-    echo "Features:"
-    echo "  - Automatically manages --all-files flag based on project token count"
-    echo "  - Intelligent approval mode detection based on task type"
-    echo "  - Token limit: $DEFAULT_TOKEN_LIMIT (set QWEN_TOKEN_LIMIT to override)"
-    echo ""
-    echo "Examples:"
-    echo "  qwen-wrapper -p \"Analyze the codebase structure\""
-    echo "  qwen-wrapper --approval-mode yolo -p \"Implement user authentication\""
-    echo "  qwen-wrapper --approval-mode auto_edit -p \"Fix all linting errors\""
-    echo ""
-}
-
-# Function to validate approval mode
-validate_approval_mode() {
-    local mode="$1"
-    case "$mode" in
-        "default"|"auto_edit"|"yolo")
-            return 0
-            ;;
-        *)
-            echo -e "${RED}❌ Invalid approval mode: $mode${NC}" >&2
-            echo -e "${YELLOW}Valid modes: default, auto_edit, yolo${NC}" >&2
-            return 1
-            ;;
-    esac
-}
-
-# Configuration
-DEFAULT_TOKEN_LIMIT=2000000
-TOKEN_LIMIT=${QWEN_TOKEN_LIMIT:-$DEFAULT_TOKEN_LIMIT}
-
-# Colors for output
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-NC='\033[0m' # No Color
-
-# Function to count tokens (approximate: chars/4)
-count_tokens() {
-    local total_chars=0
-    local file_count=0
-    
-    # Count characters in common source files
-    while IFS= read -r -d '' file; do
-        if [[ -f "$file" && -r "$file" ]]; then
-            local chars=$(wc -c < "$file" 2>/dev/null || echo 0)
-            total_chars=$((total_chars + chars))
-            file_count=$((file_count + 1))
-        fi
-    done < <(find . -type f \( -name "*.py" -o -name "*.js" -o -name "*.ts" -o -name "*.tsx" -o -name "*.jsx" -o -name "*.java" -o -name "*.cpp" -o -name "*.c" -o -name "*.h" -o -name "*.rs" -o -name "*.go" -o -name "*.md" -o -name "*.txt" -o -name "*.json" -o -name "*.yaml" -o -name "*.yml" -o -name "*.xml" -o -name "*.html" -o -name "*.css" -o -name "*.scss" -o -name "*.sass" -o -name "*.php" -o -name "*.rb" -o -name "*.sh" -o -name "*.bash" \) -not -path "*/node_modules/*" -not -path "*/.git/*" -not -path "*/dist/*" -not -path "*/build/*" -not -path "*/.next/*" -not -path "*/.nuxt/*" -not -path "*/target/*" -not -path "*/vendor/*" -print0 2>/dev/null)
-    
-    local estimated_tokens=$((total_chars / 4))
-    echo "$estimated_tokens $file_count"
-}
-
-# Parse arguments to check for flags
-has_all_files=false
-has_approval_mode=false
-approval_mode_value=""
-
-# Parse arguments with proper handling of --approval-mode value
-args=("$@")  # Start with all arguments
-parsed_args=()
-skip_next=false
-
-for ((i=0; i<${#args[@]}; i++)); do
-    if [[ "$skip_next" == true ]]; then
-        skip_next=false
-        continue
-    fi
-
-    arg="${args[i]}"
-    case "$arg" in
-        "--help"|"-h")
-            show_help
-            exit 0
-            ;;
-        "--all-files")
-            has_all_files=true
-            parsed_args+=("$arg")
-            ;;
-        "--approval-mode")
-            has_approval_mode=true
-            # Get the next argument as the mode value
-            if [[ $((i+1)) -lt ${#args[@]} ]]; then
-                approval_mode_value="${args[$((i+1))]}"
-                if validate_approval_mode "$approval_mode_value"; then
-                    parsed_args+=("$arg" "$approval_mode_value")
-                    skip_next=true
-                else
-                    exit 1
-                fi
-            else
-                echo -e "${RED}❌ --approval-mode requires a value${NC}" >&2
-                echo -e "${YELLOW}Valid modes: default, auto_edit, yolo${NC}" >&2
-                exit 1
-            fi
-            ;;
-        --approval-mode=*)
-            has_approval_mode=true
-            approval_mode_value="${arg#*=}"
-            if validate_approval_mode "$approval_mode_value"; then
-                parsed_args+=("$arg")
-            else
-                exit 1
-            fi
-            ;;
-        *)
-            parsed_args+=("$arg")
-            ;;
-    esac
-done
-
-# Replace args with parsed_args
-args=("${parsed_args[@]}")
-
-# Analyze current working directory
-echo -e "${GREEN}📁 Analyzing current directory: $(pwd)${NC}" >&2
-
-# Count tokens (in the target directory if -c was used)
-echo -e "${YELLOW}🔍 Analyzing project size...${NC}" >&2
-read -r token_count file_count <<< "$(count_tokens)"
-
-echo -e "${YELLOW}📊 Project stats: ~${token_count} tokens across ${file_count} files${NC}" >&2
-
-# Decision logic for --all-files flag
-if [[ $token_count -lt $TOKEN_LIMIT ]]; then
-    if [[ "$has_all_files" == false ]]; then
-        echo -e "${GREEN}✅ Small project (${token_count} < ${TOKEN_LIMIT} tokens): Adding --all-files${NC}" >&2
-        args=("--all-files" "${args[@]}")
-    else
-        echo -e "${GREEN}✅ Small project (${token_count} < ${TOKEN_LIMIT} tokens): Keeping --all-files${NC}" >&2
-    fi
-else
-    if [[ "$has_all_files" == true ]]; then
-        echo -e "${RED}⚠️  Large project (${token_count} >= ${TOKEN_LIMIT} tokens): Removing --all-files to avoid token limits${NC}" >&2
-        echo -e "${YELLOW}💡 Consider using specific @{patterns} for targeted analysis${NC}" >&2
-        # Remove --all-files from args
-        new_args=()
-        for arg in "${args[@]}"; do
-            if [[ "$arg" != "--all-files" ]]; then
-                new_args+=("$arg")
-            fi
-        done
-        args=("${new_args[@]}")
-    else
-        echo -e "${RED}⚠️  Large project (${token_count} >= ${TOKEN_LIMIT} tokens): Avoiding --all-files${NC}" >&2
-        echo -e "${YELLOW}💡 Consider using specific @{patterns} for targeted analysis${NC}" >&2
-    fi
-fi
-
-# Auto-add approval-mode if not specified
-if [[ "$has_approval_mode" == false ]]; then
-    # Intelligent approval mode detection based on prompt content
-    prompt_text="${args[*]}"
-
-    # Analysis/Research tasks - use default (prompt for each tool)
-    if [[ "$prompt_text" =~ (analyze|analysis|review|understand|inspect|examine|research|study|explore|investigate) ]]; then
-        echo -e "${GREEN}📋 Analysis task detected: Adding --approval-mode default${NC}" >&2
-        args=("--approval-mode" "default" "${args[@]}")
-
-    # Development/Edit tasks - use auto_edit (auto-approve edits, prompt for others)
-    elif [[ "$prompt_text" =~ (implement|create|build|develop|code|write|edit|modify|update|fix|refactor|generate) ]]; then
-        echo -e "${GREEN}🔧 Development task detected: Adding --approval-mode auto_edit${NC}" >&2
-        args=("--approval-mode" "auto_edit" "${args[@]}")
-
-    # Automation/Batch tasks - use yolo (auto-approve all)
-    elif [[ "$prompt_text" =~ (automate|batch|mass|bulk|all|execute|run|deploy|install|setup) ]]; then
-        echo -e "${YELLOW}⚡ Automation task detected: Adding --approval-mode yolo${NC}" >&2
-        args=("--approval-mode" "yolo" "${args[@]}")
-
-    # Default fallback - use default mode for safety
-    else
-        echo -e "${YELLOW}🔍 General task detected: Adding --approval-mode default${NC}" >&2
-        args=("--approval-mode" "default" "${args[@]}")
-    fi
-
-    # Show approval mode explanation
-    case "${args[1]}" in
-        "default")
-            echo -e "${YELLOW}   → Will prompt for approval on each tool call${NC}" >&2
-            ;;
-        "auto_edit")
-            echo -e "${YELLOW}   → Will auto-approve edit tools, prompt for others${NC}" >&2
-            ;;
-        "yolo")
-            echo -e "${YELLOW}   → Will auto-approve all tool calls${NC}" >&2
-            ;;
-    esac
-fi
-
-# Show final command (for transparency)
-echo -e "${YELLOW}🚀 Executing: qwen ${args[*]}${NC}" >&2
-
-# Execute qwen with adjusted arguments (we're already in the right directory)
-qwen "${args[@]}"
--- a/.claude/scripts/update_module_claude.sh
+++ b/.claude/scripts/update_module_claude.sh
@@ -1,14 +1,32 @@
 #!/bin/bash
-# Update CLAUDE.md for a specific module with unified template
-# Usage: update_module_claude.sh <module_path> [update_type] [tool]
+# Update CLAUDE.md for modules with two strategies
+# Usage: update_module_claude.sh <strategy> <module_path> [tool] [model]
+#   strategy: single-layer|multi-layer
 #   module_path: Path to the module directory
-#   update_type: full|related (default: full)
 #   tool: gemini|qwen|codex (default: gemini)
+#   model: Model name (optional, uses tool defaults)
+#
+# Default Models:
+#   gemini: gemini-2.5-flash
+#   qwen: coder-model
+#   codex: gpt5-codex
+#
+# Strategies:
+#   single-layer: Upward aggregation
+#     - Read: Current directory code + child CLAUDE.md files
+#     - Generate: Single ./CLAUDE.md in current directory
+#     - Use: Large projects, incremental bottom-up updates
+#
+#   multi-layer: Downward distribution
+#     - Read: All files in current and subdirectories
+#     - Generate: CLAUDE.md for each directory containing files
+#     - Use: Small projects, full documentation generation
 #
 # Features:
-# - Respects .gitignore patterns (current directory or git root)
-# - Unified template for all modules (folders and files)
-# - Template-based documentation generation
+#   - Minimal prompts based on unified template
+#   - Respects .gitignore patterns
+#   - Path-focused processing (script only cares about paths)
+#   - Template-driven generation

 # Build exclusion filters from .gitignore
 build_exclusion_filters() {
@@ -59,15 +77,84 @@ build_exclusion_filters() {
    echo "$filters"
 }

+# Scan directory structure and generate structured information
+scan_directory_structure() {
+    local target_path="$1"
+    local strategy="$2"
+
+    if [ ! -d "$target_path" ]; then
+        echo "Directory not found: $target_path"
+        return 1
+    fi
+
+    local exclusion_filters=$(build_exclusion_filters)
+    local structure_info=""
+
+    # Get basic directory info
+    local dir_name=$(basename "$target_path")
+    local total_files=$(eval "find \"$target_path\" -type f $exclusion_filters 2>/dev/null" | wc -l)
+    local total_dirs=$(eval "find \"$target_path\" -type d $exclusion_filters 2>/dev/null" | wc -l)
+
+    structure_info+="Directory: $dir_name\n"
+    structure_info+="Total files: $total_files\n"
+    structure_info+="Total directories: $total_dirs\n\n"
+
+    if [ "$strategy" = "multi-layer" ]; then
+        # For multi-layer: show all subdirectories with file counts
+        structure_info+="Subdirectories with files:\n"
+        while IFS= read -r dir; do
+            if [ -n "$dir" ] && [ "$dir" != "$target_path" ]; then
+                local rel_path=${dir#$target_path/}
+                local file_count=$(eval "find \"$dir\" -maxdepth 1 -type f $exclusion_filters 2>/dev/null" | wc -l)
+                if [ $file_count -gt 0 ]; then
+                    structure_info+="  - $rel_path/ ($file_count files)\n"
+                fi
+            fi
+        done < <(eval "find \"$target_path\" -type d $exclusion_filters 2>/dev/null")
+    else
+        # For single-layer: show direct children only
+        structure_info+="Direct subdirectories:\n"
+        while IFS= read -r dir; do
+            if [ -n "$dir" ]; then
+                local dir_name=$(basename "$dir")
+                local file_count=$(eval "find \"$dir\" -maxdepth 1 -type f $exclusion_filters 2>/dev/null" | wc -l)
+                local has_claude=$([ -f "$dir/CLAUDE.md" ] && echo " [has CLAUDE.md]" || echo "")
+                structure_info+="  - $dir_name/ ($file_count files)$has_claude\n"
+            fi
+        done < <(eval "find \"$target_path\" -maxdepth 1 -type d $exclusion_filters 2>/dev/null" | grep -v "^$target_path$")
+    fi
+
+    # Show main file types in current directory
+    structure_info+="\nCurrent directory files:\n"
+    local code_files=$(eval "find \"$target_path\" -maxdepth 1 -type f \\( -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' -o -name '*.py' -o -name '*.sh' \\) $exclusion_filters 2>/dev/null" | wc -l)
+    local config_files=$(eval "find \"$target_path\" -maxdepth 1 -type f \\( -name '*.json' -o -name '*.yaml' -o -name '*.yml' -o -name '*.toml' \\) $exclusion_filters 2>/dev/null" | wc -l)
+    local doc_files=$(eval "find \"$target_path\" -maxdepth 1 -type f -name '*.md' $exclusion_filters 2>/dev/null" | wc -l)
+
+    structure_info+="  - Code files: $code_files\n"
+    structure_info+="  - Config files: $config_files\n"
+    structure_info+="  - Documentation: $doc_files\n"
+
+    printf "%b" "$structure_info"
+}
+
 update_module_claude() {
-    local module_path="$1"
-    local update_type="${2:-full}"
+    local strategy="$1"
+    local module_path="$2"
    local tool="${3:-gemini}"
+    local model="$4"

    # Validate parameters
-    if [ -z "$module_path" ]; then
-        echo "❌ Error: Module path is required"
-        echo "Usage: update_module_claude.sh <module_path> [update_type]"
+    if [ -z "$strategy" ] || [ -z "$module_path" ]; then
+        echo "❌ Error: Strategy and module path are required"
+        echo "Usage: update_module_claude.sh <strategy> <module_path> [tool] [model]"
+        echo "Strategies: single-layer|multi-layer"
+        return 1
+    fi
+
+    # Validate strategy
+    if [ "$strategy" != "single-layer" ] && [ "$strategy" != "multi-layer" ]; then
+        echo "❌ Error: Invalid strategy '$strategy'"
+        echo "Valid strategies: single-layer, multi-layer"
        return 1
    fi

@@ -76,6 +163,24 @@ update_module_claude() {
        return 1
    fi

+    # Set default models if not specified
+    if [ -z "$model" ]; then
+        case "$tool" in
+            gemini)
+                model="gemini-2.5-flash"
+                ;;
+            qwen)
+                model="coder-model"
+                ;;
+            codex)
+                model="gpt5-codex"
+                ;;
+            *)
+                model=""
+                ;;
+        esac
+    fi
+
    # Build exclusion filters from .gitignore
    local exclusion_filters=$(build_exclusion_filters)

@@ -85,79 +190,105 @@ update_module_claude() {
        echo "⚠️  Skipping '$module_path' - no files found (after .gitignore filtering)"
        return 0
    fi
-    
+
    # Use unified template for all modules
    local template_path="$HOME/.claude/workflows/cli-templates/prompts/memory/claude-module-unified.txt"
-    local analysis_strategy="--all-files"
-    
+
+    # Read template content directly
+    local template_content=""
+    if [ -f "$template_path" ]; then
+        template_content=$(cat "$template_path")
+        echo "   📋 Loaded template: $(wc -l < "$template_path") lines"
+    else
+        echo "   ⚠️  Template not found: $template_path"
+        echo "   Using fallback template..."
+        template_content="Create comprehensive CLAUDE.md documentation following standard structure with Purpose, Structure, Components, Dependencies, Integration, and Implementation sections."
+    fi
+
+    # Scan directory structure first
+    echo "   🔍 Scanning directory structure..."
+    local structure_info=$(scan_directory_structure "$module_path" "$strategy")
+
    # Prepare logging info
    local module_name=$(basename "$module_path")

    echo "⚡ Updating: $module_path"
-    echo "   Type: $update_type | Tool: $tool | Files: $file_count"
-    echo "   Template: $(basename "$template_path")"
-    
-    # Generate prompt with template injection
-    local template_content=""
-    if [ -f "$template_path" ]; then
-        template_content=$(cat "$template_path")
-    else
-        echo "   ⚠️  Template not found: $template_path, using fallback"
-        template_content="Update CLAUDE.md documentation for this module: document structure, key components, dependencies, and integration points."
-    fi
-    
-    local update_context=""
-    if [ "$update_type" = "full" ]; then
-        update_context="
-        Update Mode: Complete refresh
-        - Perform comprehensive analysis of all content
-        - Document module structure, dependencies, and key components
-        - Follow template guidelines strictly"
-    else
-        update_context="
-        Update Mode: Context-aware update
-        - Focus on recent changes and affected areas
-        - Maintain consistency with existing documentation
-        - Update only relevant sections
-        - Follow template guidelines for updated content"
-    fi
-    
-    local base_prompt="
-    ⚠️ CRITICAL RULES - MUST FOLLOW:
-    1. ONLY modify CLAUDE.md files
-    2. NEVER modify source code files
-    3. Focus exclusively on updating documentation
-    4. Follow the template guidelines exactly
+    echo "   Strategy: $strategy | Tool: $tool | Model: $model | Files: $file_count"
+    echo "   Template: $(basename "$template_path") ($(echo "$template_content" | wc -l) lines)"
+    echo "   Structure: Scanned $(echo "$structure_info" | wc -l) lines of structure info"

-    $template_content
+    # Build minimal strategy-specific prompt with explicit paths and structure info
+    local final_prompt=""
+
+    if [ "$strategy" = "multi-layer" ]; then
+        # multi-layer strategy: read all, generate for each directory
+        final_prompt="Directory Structure Analysis:
+$structure_info
+
+Read: @**/*
+
+Generate CLAUDE.md files:
+- Primary: ./CLAUDE.md (current directory)
+- Additional: CLAUDE.md in each subdirectory containing files
+
+Template Guidelines:
+$template_content
+
+Instructions:
+- Work bottom-up: deepest directories first
+- Parent directories reference children
+- Each CLAUDE.md file must be in its respective directory
+- Follow the template guidelines above for consistent structure
+- Use the structure analysis to understand directory hierarchy"
+    else
+        # single-layer strategy: read current + child CLAUDE.md, generate current only
+        final_prompt="Directory Structure Analysis:
+$structure_info
+
+Read: @*/CLAUDE.md @*.ts @*.tsx @*.js @*.jsx @*.py @*.sh @*.md @*.json @*.yaml @*.yml
+
+Generate single file: ./CLAUDE.md
+
+Template Guidelines:
+$template_content
+
+Instructions:
+- Create exactly one CLAUDE.md file in the current directory
+- Reference child CLAUDE.md files, do not duplicate their content
+- Follow the template guidelines above for consistent structure
+- Use the structure analysis to understand the current directory context"
+    fi

-    $update_context"
-    
    # Execute update
    local start_time=$(date +%s)
    echo "   🔄 Starting update..."

    if cd "$module_path" 2>/dev/null; then
        local tool_result=0
-        local final_prompt="$base_prompt

-        Module Information:
-        - Name: $module_name
-        - Path: $module_path
-        - Tool: $tool"
-
-        # Execute with selected tool (always use --all-files)
+        # Execute with selected tool
+        # NOTE: Model parameter (-m) is placed AFTER the prompt
        case "$tool" in
            qwen)
-                qwen --all-files --yolo -p "$final_prompt" 2>&1
+                if [ "$model" = "coder-model" ]; then
+                    # coder-model is default, -m is optional
+                    qwen -p "$final_prompt" --yolo 2>&1
+                else
+                    qwen -p "$final_prompt" -m "$model" --yolo 2>&1
+                fi
                tool_result=$?
                ;;
            codex)
-                codex --full-auto exec "$final_prompt" --skip-git-repo-check -s danger-full-access 2>&1
+                codex --full-auto exec "$final_prompt" -m "$model" --skip-git-repo-check -s danger-full-access 2>&1
                tool_result=$?
                ;;
-            gemini|*)
-                gemini --all-files --yolo -p "$final_prompt" 2>&1
+            gemini)
+                gemini -p "$final_prompt" -m "$model" --yolo 2>&1
+                tool_result=$?
+                ;;
+            *)
+                echo "   ⚠️  Unknown tool: $tool, defaulting to gemini"
+                gemini -p "$final_prompt" -m "$model" --yolo 2>&1
                tool_result=$?
                ;;
        esac
@@ -181,5 +312,22 @@ update_module_claude() {

 # Execute function if script is run directly
 if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    # Show help if no arguments or help requested
+    if [ $# -eq 0 ] || [ "$1" = "-h" ] || [ "$1" = "--help" ]; then
+        echo "Usage: update_module_claude.sh <strategy> <module_path> [tool] [model]"
+        echo ""
+        echo "Strategies:"
+        echo "  single-layer    - Read current dir code + child CLAUDE.md, generate ./CLAUDE.md"
+        echo "  multi-layer     - Read all files, generate CLAUDE.md for each directory"
+        echo ""
+        echo "Tools: gemini (default), qwen, codex"
+        echo "Models: Use tool defaults if not specified"
+        echo ""
+        echo "Examples:"
+        echo "  ./update_module_claude.sh single-layer ./src/auth"
+        echo "  ./update_module_claude.sh multi-layer ./components gemini gemini-2.5-flash"
+        exit 0
+    fi
+
    update_module_claude "$@"
-fi
+fi
--- a/.claude/workflows/cli-templates/prompts/memory/claude-module-unified.txt
+++ b/.claude/workflows/cli-templates/prompts/memory/claude-module-unified.txt
@@ -1,6 +1,12 @@
 Create or update CLAUDE.md documentation using unified module/file template.

+## ⚠️ FILE NAMING RULE (CRITICAL)
+- Target file: MUST be named exactly `CLAUDE.md` in the current directory
+- NEVER create files like `ToolSidebar.CLAUDE.md` or `[filename].CLAUDE.md`
+- ALWAYS use the fixed name: `CLAUDE.md`
+
 ## CORE CHECKLIST ⚡
+□ MUST create/update file named exactly 'CLAUDE.md' (not variants)
 □ MUST include all 6 sections: Purpose, Structure, Components, Dependencies, Integration, Implementation
 □ For code files: Document all public/exported APIs with complete parameter details
 □ For folders: Reference subdirectory CLAUDE.md files instead of duplicating
@@ -64,6 +70,11 @@ Create or update CLAUDE.md documentation using unified module/file template.

 ## OUTPUT REQUIREMENTS

+### File Naming (CRITICAL)
+- **Output file**: MUST be named exactly `CLAUDE.md` in the current directory
+- **Examples of WRONG naming**: `ToolSidebar.CLAUDE.md`, `index.CLAUDE.md`, `utils.CLAUDE.md`
+- **Correct naming**: `CLAUDE.md` (always, for all directories)
+
 ### Template Structure
 ```markdown
 # [Module/File Name]
@@ -143,6 +154,7 @@ Create or update CLAUDE.md documentation using unified module/file template.
 - Update existing CLAUDE.md files rather than creating duplicate sections

 ## VERIFICATION CHECKLIST ✓
+□ Output file is named exactly 'CLAUDE.md' (not [filename].CLAUDE.md)
 □ All 6 required sections included (Purpose, Structure, Components, Dependencies, Integration, Implementation)
 □ All public/exported APIs documented with complete signatures
 □ Parameters documented with types, descriptions, and defaults
--- a/.claude/workflows/cli-templates/prompts/workflow/task-json-cli-mode.txt
+++ b/.claude/workflows/cli-templates/prompts/workflow/task-json-cli-mode.txt
@@ -148,10 +148,10 @@ bash(codex --full-auto exec "..." resume --last --skip-git-repo-check -s danger-

 ### Gemini/Qwen Commands (Analysis/Documentation)
 ```bash
-bash(~/.claude/scripts/gemini-wrapper -p "PURPOSE: {purpose} TASK: {task} MODE: analysis CONTEXT: @{{synthesis_spec_path}} EXPECTED: {expected} RULES: {rules}")
+bash(gemini "PURPOSE: {purpose} TASK: {task} MODE: analysis CONTEXT: @{synthesis_spec_path} EXPECTED: {expected} RULES: {rules}")

 # With write permission
-bash(~/.claude/scripts/gemini-wrapper --approval-mode yolo -p "PURPOSE: {purpose} TASK: {task} MODE: write CONTEXT: @{{context}} EXPECTED: {expected} RULES: {rules}")
+bash(gemini --approval-mode yolo "PURPOSE: {purpose} TASK: {task} MODE: write CONTEXT: @{context} EXPECTED: {expected} RULES: {rules}")
 ```

 ## Field Descriptions
@@ -175,4 +175,4 @@ bash(~/.claude/scripts/gemini-wrapper --approval-mode yolo -p "PURPOSE: {purpose
 5. **Step Dependencies**: Use `depends_on: [1, 2]` to specify execution order
 6. **Parameter Position**:
   - Codex: `--skip-git-repo-check -s danger-full-access` at END
-   - Gemini/Qwen: `--approval-mode yolo` AFTER wrapper command, BEFORE -p
+   - Gemini/Qwen: `--approval-mode yolo` BEFORE the prompt
--- a/.claude/workflows/context-search-strategy.md
+++ b/.claude/workflows/context-search-strategy.md
@@ -40,8 +40,8 @@ type: search-guideline
 ### Quick Command Reference
 ```bash
 # Semantic File Discovery (codebase-retrieval)
-~/.claude/scripts/gemini-wrapper --all-files -p "List all files relevant to: [task/feature description]"
-bash(~/.claude/scripts/gemini-wrapper --all-files -p "List all files relevant to: [task/feature description]")
+gemini "CONTEXT: @**/* List all files relevant to: [task/feature description]"
+bash(gemini "CONTEXT: @**/* List all files relevant to: [task/feature description]")

 # Program Architecture Analysis (MANDATORY FIRST)
 ~/.claude/scripts/get_modules_by_depth.sh  # Discover program architecture
@@ -65,7 +65,7 @@ grep -n -i "pattern" file.txt   # Line numbers, case-insensitive
 ### Workflow Integration Examples
 ```bash
 # Semantic Discovery → Content Search → Analysis (Recommended Pattern)
-~/.claude/scripts/gemini-wrapper --all-files -p "List all files relevant to: [task/feature]"  # Get relevant files
+gemini "CONTEXT: @**/* List all files relevant to: [task/feature]"  # Get relevant files
 rg "[pattern]" --type [filetype]  # Then search within discovered files

 # Program Architecture Analysis (MANDATORY BEFORE PLANNING)
--- a/.claude/workflows/intelligent-tools-strategy.md
+++ b/.claude/workflows/intelligent-tools-strategy.md
@@ -7,67 +7,93 @@ type: strategic-guideline
 # Intelligent Tools Selection Strategy

 ## 📋 Table of Contents
-1. [Core Framework](#-core-framework)
+1. [Quick Start](#-quick-start)
 2. [Tool Specifications](#-tool-specifications)
 3. [Command Templates](#-command-templates)
-4. [Tool Selection Guide](#-tool-selection-guide)
-5. [Usage Patterns](#-usage-patterns)
-6. [Best Practices](#-best-practices)
+4. [Execution Configuration](#-execution-configuration)
+5. [Best Practices](#-best-practices)

 ---

-## ⚡ Core Framework
+## ⚡ Quick Start

 ### Tool Overview
 - **Gemini**: Analysis, understanding, exploration & documentation (primary)
 - **Qwen**: Analysis, understanding, exploration & documentation (fallback, same capabilities as Gemini)
 - **Codex**: Development, implementation & automation

-### Decision Principles
+### Model Selection (-m parameter)
+
+**Gemini Models**:
+- `gemini-2.5-pro` - Analysis tasks (default)
+- `gemini-2.5-flash` - Documentation updates
+
+**Qwen Models**:
+- `coder-model` - Code analysis (default, -m optional)
+- `vision-model` - Image analysis (rare usage)
+
+**Codex Models**:
+- `gpt-5` - Analysis & execution (default)
+- `gpt5-codex` - Large context tasks
+
+**Usage**: `tool -p "prompt" -m model-name` (NOTE: -m placed AFTER prompt)
+
+### Quick Decision Matrix
+
+| Scenario | Tool | Command Pattern |
+|----------|------|-----------------|
+| **Exploring/Understanding** | Gemini → Qwen | `cd [dir] && gemini -p "PURPOSE:... CONTEXT: @**/*"` |
+| **Architecture/Analysis** | Gemini → Qwen | `cd [dir] && gemini -p "PURPOSE:... CONTEXT: @**/*"` |
+| **Building/Fixing** | Codex | `codex -C [dir] --full-auto exec "PURPOSE:... MODE: auto"` |
+| **Not sure?** | Multiple | Use tools in parallel |
+| **Small task?** | Still use tools | Tools are faster than manual work |
+
+### Core Principles
 - **Use tools early and often** - Tools are faster, more thorough, and reliable than manual approaches
 - **When in doubt, use both** - Parallel usage provides comprehensive coverage
 - **Default to tools** - Use specialized tools for most coding tasks, no matter how small
 - **Lower barriers** - Engage tools immediately when encountering any complexity
- **Context optimization** - Based on user intent, determine whether to use `-C [directory]` parameter for focused analysis to reduce irrelevant context import
 - **⚠️ Write operation protection** - For local codebase write/modify operations, require EXPLICIT user confirmation unless user provides clear instructions containing MODE=write or MODE=auto

-### Quick Decision Rules
-1. **Exploring/Understanding?** → Start with Gemini (fallback to Qwen if needed)
-2. **Architecture/Analysis?** → Start with Gemini (fallback to Qwen if needed)
-3. **Building/Fixing?** → Start with Codex
-4. **Not sure?** → Use multiple tools in parallel
-5. **Small task?** → Still use tools - they're faster than manual work
-
 ---

 ## 🎯 Tool Specifications

-### Gemini
- **Command**: `~/.claude/scripts/gemini-wrapper`
+### Gemini & Qwen
+
+#### Overview
+- **Commands**: `gemini` (primary) | `qwen` (fallback)
 - **Strengths**: Large context window, pattern recognition
- **Best For**: Analysis, documentation generation, code exploration
- **Permissions**: Default read-only analysis, MODE=write requires explicit specification (auto-enables --approval-mode yolo)
+- **Best For**: Analysis, documentation generation, code exploration, architecture review
+- **Permissions**: Default read-only analysis, MODE=write requires explicit specification
 - **Default MODE**: `analysis` (read-only)
 - **⚠️ Write Trigger**: Only when user explicitly requests "generate documentation", "modify code", or specifies MODE=write
+- **Priority**: Prefer Gemini; use Qwen as fallback when Gemini unavailable

 #### MODE Options
- `analysis` (default) - Read-only analysis and documentation generation
- `write` - ⚠️ Create/modify codebase files (requires explicit specification, auto-enables --approval-mode yolo)

-### Qwen
- **Command**: `~/.claude/scripts/qwen-wrapper`
- **Strengths**: Large context window, pattern recognition (same as Gemini)
- **Best For**: Analysis, documentation generation, code exploration (fallback option when Gemini unavailable)
- **Permissions**: Default read-only analysis, MODE=write requires explicit specification (auto-enables --approval-mode yolo)
- **Default MODE**: `analysis` (read-only)
- **⚠️ Write Trigger**: Only when user explicitly requests "generate documentation", "modify code", or specifies MODE=write
- **Priority**: Secondary to Gemini - use as fallback for same tasks
+**analysis** (default) - Read-only analysis and documentation generation
+- **⚠️ CRITICAL CONSTRAINT**: Absolutely NO file creation, modification, or deletion operations
+- Analysis output should be returned as text response only
+- Use for: code review, architecture analysis, pattern discovery, documentation reading

-#### MODE Options
- `analysis` (default) - Read-only analysis and documentation generation (same as Gemini)
- `write` - ⚠️ Create/modify codebase files (requires explicit specification, auto-enables --approval-mode yolo)
+**write** - ⚠️ Create/modify codebase files (requires explicit specification, auto-enables --approval-mode yolo)
+- Use for: generating documentation files, creating code files, modifying existing files
+
+#### Tool Selection
+```bash
+# Default: Use Gemini
+gemini -p "analysis prompt"
+
+# Fallback: Use Qwen if Gemini unavailable
+qwen -p "analysis prompt"
+```
+
+---

 ### Codex
+
+#### Overview
 - **Command**: `codex --full-auto exec`
 - **Strengths**: Autonomous development, mathematical reasoning
 - **Best For**: Implementation, testing, automation
@@ -76,27 +102,39 @@ type: strategic-guideline
 - **⚠️ Write Trigger**: Only when user explicitly requests "implement", "modify", "generate code" AND specifies MODE

 #### MODE Options
- `auto` - ⚠️ Autonomous development with full file operations (requires explicit specification, enables -s danger-full-access)
- `write` - ⚠️ Test generation and file modification (requires explicit specification)
- **Default**: No default mode, MODE must be explicitly specified
+
+**auto** - ⚠️ Autonomous development with full file operations
+- Requires explicit specification
+- Enables `-s danger-full-access`
+- Use for: feature implementation, bug fixes, autonomous development
+
+**write** - ⚠️ Test generation and file modification
+- Requires explicit specification
+- Use for: test generation, focused file modifications

 #### Session Management
- `codex resume` - Resume previous interactive session (picker by default)
- `codex exec "task" resume --last` - Continue most recent session with new task (maintains context)
- `codex -i <image_file>` - Attach image(s) to initial prompt (useful for UI/design references)
- **Multi-task Pattern**: First task uses `exec`, subsequent tasks use `exec "..." resume --last` for context continuity
-  - **Parameter Position**: `resume --last` must be placed AFTER the prompt string at command END
-  - **Example**:
-    ```bash
-    # First task - establish session
-    codex -C project --full-auto exec "Implement auth module" --skip-git-repo-check -s danger-full-access

-    # Subsequent tasks - continue same session
-    codex --full-auto exec "Add JWT validation" resume --last --skip-git-repo-check -s danger-full-access
-    codex --full-auto exec "Write auth tests" resume --last --skip-git-repo-check -s danger-full-access
-    ```
+**Basic Commands**:
+- `codex resume` - Resume previous interactive session (picker by default)
+- `codex resume --last` - Resume most recent session directly
+- `codex -i <image_file>` - Attach image(s) to initial prompt (useful for UI/design references)
+
+**Multi-task Pattern**: First task uses `exec`, subsequent tasks use `exec "..." resume --last` for context continuity
+
+**Parameter Position**: `resume --last` must be placed AFTER the prompt string at command END
+
+**Example**:
+```bash
+# First task - establish session
+codex -C project --full-auto exec "Implement auth module" --skip-git-repo-check -s danger-full-access
+
+# Subsequent tasks - continue same session
+codex --full-auto exec "Add JWT validation" resume --last --skip-git-repo-check -s danger-full-access
+codex --full-auto exec "Write auth tests" resume --last --skip-git-repo-check -s danger-full-access
+```

 #### Auto-Resume Decision Rules
+
 **When to use `resume --last`**:
 - Current task is related to/extends previous Codex task in conversation memory
 - Current task requires context from previous implementation
@@ -114,125 +152,170 @@ type: strategic-guideline
 ## 🎯 Command Templates

 ### Universal Template Structure
+
 Every command MUST follow this structure:
 - [ ] **PURPOSE** - Clear goal and intent
- [ ] **TASK** - Specific execution task
+- [ ] **TASK** - Specific execution task (use list format: • Task item 1 • Task item 2 • Task item 3)
 - [ ] **MODE** - Execution mode and permission level
 - [ ] **CONTEXT** - File references and memory context from previous sessions
 - [ ] **EXPECTED** - Clear expected results
- [ ] **RULES** - Template reference and constraints
+- [ ] **RULES** - Template reference and constraints (include mode constraints: analysis=READ-ONLY | write=CREATE/MODIFY/DELETE | auto=FULL operations)
+
+---

 ### Standard Command Formats

-#### Gemini Commands
+#### Gemini & Qwen Commands
+
 ```bash
-# Gemini Analysis (read-only, default)
-cd [directory] && ~/.claude/scripts/gemini-wrapper -p "
+# Analysis Mode (read-only, default)
+# Use 'gemini' (primary) or 'qwen' (fallback)
+cd [directory] && gemini -p "
 PURPOSE: [clear analysis goal]
 TASK: [specific analysis task]
 MODE: analysis
-CONTEXT: [file references and memory context]
+CONTEXT: @**/* [default: all files, or specify file patterns]
 EXPECTED: [expected output]
 RULES: [template reference and constraints]
 "

-# Gemini Write Mode (requires explicit MODE=write)
-# NOTE: --approval-mode yolo must be placed AFTER wrapper command, BEFORE -p
-cd [directory] && ~/.claude/scripts/gemini-wrapper --approval-mode yolo -p "
+# Model Selection Examples (NOTE: -m placed AFTER prompt)
+cd [directory] && gemini -p "..." -m gemini-2.5-pro      # Analysis (default)
+cd [directory] && gemini -p "..." -m gemini-2.5-flash    # Documentation updates
+cd [directory] && qwen -p "..."                          # coder-model (default, -m optional)
+cd [directory] && qwen -p "..." -m vision-model           # Image analysis (rare)
+
+# Write Mode (requires explicit MODE=write)
+# NOTE: --approval-mode yolo must be placed AFTER the prompt
+cd [directory] && gemini -p "
 PURPOSE: [clear goal]
 TASK: [specific task]
 MODE: write
-CONTEXT: [file references and memory context]
+CONTEXT: @**/* [default: all files, or specify file patterns]
 EXPECTED: [expected output]
 RULES: [template reference and constraints]
-"
-```
+" -m gemini-2.5-flash --approval-mode yolo

-#### Qwen Commands
-```bash
-# Qwen Analysis (read-only, default) - Same as Gemini, use as fallback
-cd [directory] && ~/.claude/scripts/qwen-wrapper -p "
-PURPOSE: [clear analysis goal]
-TASK: [specific analysis task]
-MODE: analysis
-CONTEXT: [file references and memory context]
-EXPECTED: [expected output]
-RULES: [template reference and constraints]
-"
-
-# Qwen Write Mode (requires explicit MODE=write)
-# NOTE: --approval-mode yolo must be placed AFTER wrapper command, BEFORE -p
-cd [directory] && ~/.claude/scripts/qwen-wrapper --approval-mode yolo -p "
-PURPOSE: [clear goal]
-TASK: [specific task]
-MODE: write
-CONTEXT: [file references and memory context]
-EXPECTED: [expected output]
-RULES: [template reference and constraints]
-"
+# Fallback: Replace 'gemini' with 'qwen' if Gemini unavailable
+cd [directory] && qwen -p "..." # coder-model default (-m optional)
 ```

 #### Codex Commands
+
 ```bash
 # Codex Development (requires explicit MODE=auto)
-# NOTE: --skip-git-repo-check and -s danger-full-access must be placed at command END
+# NOTE: -m, --skip-git-repo-check and -s danger-full-access must be placed at command END
 codex -C [directory] --full-auto exec "
 PURPOSE: [clear development goal]
 TASK: [specific development task]
 MODE: auto
-CONTEXT: [file references and memory context]
+CONTEXT: @**/* [default: all files, or specify file patterns and memory context]
 EXPECTED: [expected deliverables]
 RULES: [template reference and constraints]
-" --skip-git-repo-check -s danger-full-access
+" -m gpt-5 --skip-git-repo-check -s danger-full-access
+
+# Model Selection Examples (NOTE: -m placed AFTER prompt, BEFORE flags)
+codex -C [directory] --full-auto exec "..." -m gpt-5 --skip-git-repo-check -s danger-full-access        # Analysis & execution (default)
+codex -C [directory] --full-auto exec "..." -m gpt5-codex --skip-git-repo-check -s danger-full-access   # Large context tasks

 # Codex Test/Write Mode (requires explicit MODE=write)
-# NOTE: --skip-git-repo-check and -s danger-full-access must be placed at command END
+# NOTE: -m, --skip-git-repo-check and -s danger-full-access must be placed at command END
 codex -C [directory] --full-auto exec "
 PURPOSE: [clear goal]
 TASK: [specific task]
 MODE: write
-CONTEXT: [file references and memory context]
+CONTEXT: @**/* [default: all files, or specify file patterns and memory context]
 EXPECTED: [expected deliverables]
 RULES: [template reference and constraints]
-" --skip-git-repo-check -s danger-full-access
+" -m gpt-5 --skip-git-repo-check -s danger-full-access
 ```

+---
+
 ### Directory Context Configuration
-Tools execute in current working directory:
- **Gemini**: `cd path/to/project && ~/.claude/scripts/gemini-wrapper -p "prompt"`
- **Qwen**: `cd path/to/project && ~/.claude/scripts/qwen-wrapper -p "prompt"`
+
+**Tool Directory Navigation**:
+- **Gemini & Qwen**: `cd path/to/project && gemini -p "prompt"` (or `qwen`)
 - **Codex**: `codex -C path/to/project --full-auto exec "task"` (Codex still supports -C)
 - **Path types**: Supports both relative (`../project`) and absolute (`/full/path`) paths
- **Token analysis**: For gemini-wrapper and qwen-wrapper, token counting happens in current directory
+- **Token analysis**: For Gemini/Qwen, token counting happens in current directory

-### RULES Field Format
+#### ⚠️ Critical Directory Scope Rules
+
+**Once `cd` to a directory**:
+- **@ references ONLY apply to current directory and its subdirectories**
+- `@**/*` = All files within current directory tree
+- `@*.ts` = TypeScript files in current directory tree
+- `@src/**/*` = Files within src subdirectory (if exists under current directory)
+- **CANNOT reference parent or sibling directories via @ alone**
+
+**To reference files outside current directory (TWO-STEP REQUIREMENT)**:
+- **Step 1**: Add `--include-directories` parameter to make external directories ACCESSIBLE
+- **Step 2**: Explicitly reference external files in CONTEXT field with @ patterns
+- **⚠️ BOTH steps are MANDATORY** - missing either step will fail
+- Example: `cd src/auth && gemini -p "CONTEXT: @**/* @../shared/**/*" --include-directories ../shared`
+- **Rule**: If CONTEXT contains `@../dir/**/*`, command MUST include `--include-directories ../dir`
+- Without `--include-directories`, @ patterns CANNOT access parent/sibling directories at all
+
+#### Multi-Directory Support (Gemini & Qwen)
+
+**Purpose**: For large projects requiring fine-grained access across multiple directories
+
+**Use Case**: When `cd` limits scope but you need to reference files from parent/sibling folders
+
+**Parameter**: `--include-directories <dir1,dir2,...>`
+- Includes additional directories in the workspace beyond current `cd` directory
+- Can be specified multiple times or as comma-separated values
+- Maximum 5 directories can be added
+- **REQUIRED** when working in a subdirectory but needing context from parent or sibling directories
+
+**Syntax Options**:
 ```bash
-RULES: $(cat "~/.claude/workflows/cli-templates/prompts/[category]/[template].txt") | [constraints]
+# Comma-separated format
+gemini -p "prompt" --include-directories /path/to/project1,/path/to/project2
+
+# Multiple flags format
+gemini -p "prompt" --include-directories /path/to/project1 --include-directories /path/to/project2
+
+# Combined with cd for focused analysis with extended context (RECOMMENDED)
+cd src/auth && gemini -p "
+PURPOSE: Analyze authentication with shared utilities context
+TASK: Review auth implementation and its dependencies
+MODE: analysis
+CONTEXT: @**/* @../shared/**/* @../types/**/*
+EXPECTED: Complete analysis with cross-directory dependencies
+RULES: Focus on integration patterns
+" --include-directories ../shared,../types
 ```

-**⚠️ CRITICAL: Command Substitution Rules**
-When using `$(cat ...)` for template loading in actual CLI commands:
- **Template reference only, never read**: When user specifies template name, use `$(cat ...)` directly in RULES field, do NOT read template content first
- **NEVER use escape characters**: `\$`, `\"`, `\'` will break command substitution
- **In -p "..." context**: Path in `$(cat ...)` needs NO quotes (tilde expands correctly)
- **Correct**: `RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt)`
- **WRONG**: `RULES: \$(cat ...)` or `RULES: $(cat \"...\")` or `RULES: $(cat '...')`
- **Why**: Shell executes `$(...)` in subshell where path is safe without quotes
+**Best Practices**:
+- **Recommended Pattern**: Use `cd` to navigate to primary focus directory, then use `--include-directories` for additional context
+  - Example: `cd src/auth && gemini -p "CONTEXT: @**/* @../shared/**/*" --include-directories ../shared,../types`
+  - **⚠️ CRITICAL**: CONTEXT must explicitly list external files (e.g., `@../shared/**/*`), AND command must include `--include-directories ../shared`
+  - Benefits: More precise file references (relative to current directory), clearer intent, better context control
+- **Enforcement Rule**: When CONTEXT references external directories, ALWAYS add corresponding `--include-directories`
+- Use when `cd` alone limits necessary context visibility
+- Keep directory count ≤ 5 for optimal performance
+- **Pattern matching rule**: `@../dir/**/*` in CONTEXT → `--include-directories ../dir` in command (MANDATORY)
+- Prefer `cd + --include-directories` over multiple `cd` commands for cross-directory analysis

-**Examples**:
- Single template: `$(cat "~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt") | Focus on security`
- Multiple templates: `$(cat "template1.txt") $(cat "template2.txt") | Enterprise standards`
- No template: `Focus on security patterns, include dependency analysis`
- File patterns: `@{src/**/*.ts,CLAUDE.md} - Stay within scope`
+---

-### File Pattern Reference
- All files: `@{**/*}`
- Source files: `@{src/**/*}`
- TypeScript: `@{*.ts,*.tsx}`
- With docs: `@{CLAUDE.md,**/*CLAUDE.md}`
- Tests: `@{src/**/*.test.*}`
+### CONTEXT Field Configuration
+
+#### File Pattern Reference
+
+**Default Pattern**:
+- **All files (default)**: `@**/*` - Use this as default for comprehensive context
+
+**Common Patterns**:
+- Source files: `@src/**/*`
+- TypeScript: `@*.ts @*.tsx` (multiple @ for multiple patterns)
+- With docs: `@CLAUDE.md @**/*CLAUDE.md` (multiple @ for multiple patterns)
+- Tests: `@src/**/*.test.*`
+
+#### Complex Pattern Discovery

-**Complex Pattern Discovery**:
 For complex file pattern requirements, use semantic discovery tools BEFORE CLI execution:
 - **rg (ripgrep)**: Content-based file discovery with regex patterns
 - **Code Index MCP**: Semantic file search based on task requirements
@@ -245,14 +328,14 @@ rg "export.*Component" --files-with-matches --type ts  # Find component files
 mcp__code-index__search_code_advanced(pattern="interface.*Props", file_pattern="*.tsx")  # Find interface files

 # Step 2: Build precise CONTEXT from discovery results
-CONTEXT: @{src/components/Auth.tsx,src/types/auth.d.ts,src/hooks/useAuth.ts}
+CONTEXT: @src/components/Auth.tsx @src/types/auth.d.ts @src/hooks/useAuth.ts

 # Step 3: Execute CLI with precise file references
-cd src && ~/.claude/scripts/gemini-wrapper -p "
+cd src && gemini -p "
 PURPOSE: Analyze authentication components
 TASK: Review auth component patterns and props interfaces
 MODE: analysis
-CONTEXT: @{components/Auth.tsx,types/auth.d.ts,hooks/useAuth.ts}
+CONTEXT: @components/Auth.tsx @types/auth.d.ts @hooks/useAuth.ts
 EXPECTED: Pattern analysis and improvement suggestions
 RULES: Focus on type safety and component composition
 "
@@ -260,26 +343,38 @@ RULES: Focus on type safety and component composition

 ---

-## 📊 Tool Selection Guide
+### RULES Field Configuration

-### Selection Matrix
+#### Basic Format
+```bash
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/[category]/[template].txt) | [constraints]
+```

-| Task Type | Tool | Use Case | Template |
-|-----------|------|----------|-----------|
-| **Analysis** | Gemini (Qwen fallback) | Code exploration, architecture review, patterns | `analysis/pattern.txt` |
-| **Architecture** | Gemini (Qwen fallback) | System design, architectural analysis | `analysis/architecture.txt` |
-| **Documentation** | Gemini (Qwen fallback) | Code docs, API specs, guides | `analysis/quality.txt` |
-| **Development** | Codex | Feature implementation, bug fixes, testing | `development/feature.txt` |
-| **Planning** | Gemini/Qwen | Task breakdown, migration planning | `planning/task-breakdown.txt` |
-| **Security** | Codex | Vulnerability assessment, fixes | `analysis/security.txt` |
-| **Refactoring** | Multiple | Gemini/Qwen for analysis, Codex for execution | `development/refactor.txt` |
-| **Module Documentation** | Gemini (Qwen fallback) | Universal module/file documentation for all levels | `memory/claude-module-unified.txt` |
+#### ⚠️ CRITICAL: Command Substitution Rules
+
+When using `$(cat ...)` for template loading in actual CLI commands:
+- **Template reference only, never read**: When user specifies template name, use `$(cat ...)` directly in RULES field, do NOT read template content first
+- **NEVER use escape characters**: `\$`, `\"`, `\'` will break command substitution
+- **In prompt context**: Path in `$(cat ...)` needs NO quotes (tilde expands correctly)
+- **Correct**: `RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt)`
+- **WRONG**: `RULES: \$(cat ...)` or `RULES: $(cat \"...\")` or `RULES: $(cat '...')`
+- **Why**: Shell executes `$(...)` in subshell where path is safe without quotes
+
+#### Examples
+- Single template: `$(cat ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt) | Focus on security`
+- Multiple templates: `$(cat template1.txt) $(cat template2.txt) | Enterprise standards`
+- No template: `Focus on security patterns, include dependency analysis`
+- File patterns: `@src/**/*.ts @CLAUDE.md - Stay within scope`
+
+---

 ### Template System

-**Base Structure**: `~/.claude/workflows/cli-templates/`
+#### Base Structure
+`~/.claude/workflows/cli-templates/`

 #### Available Templates
+
 ```
 prompts/
 ├── analysis/
@@ -307,11 +402,103 @@ tech-stacks/
 └── react-dev.md         - React architecture
 ```

+#### Task-Template Selection Matrix
+
+| Task Type | Tool | Use Case | Template |
+|-----------|------|----------|-----------|
+| **Analysis** | Gemini (Qwen fallback) | Code exploration, architecture review, patterns | `analysis/pattern.txt` |
+| **Architecture** | Gemini (Qwen fallback) | System design, architectural analysis | `analysis/architecture.txt` |
+| **Documentation** | Gemini (Qwen fallback) | Code docs, API specs, guides | `analysis/quality.txt` |
+| **Development** | Codex | Feature implementation, bug fixes, testing | `development/feature.txt` |
+| **Planning** | Gemini/Qwen | Task breakdown, migration planning | `planning/task-breakdown.txt` |
+| **Security** | Codex | Vulnerability assessment, fixes | `analysis/security.txt` |
+| **Refactoring** | Multiple | Gemini/Qwen for analysis, Codex for execution | `development/refactor.txt` |
+| **Module Documentation** | Gemini (Qwen fallback) | Universal module/file documentation for all levels | `memory/claude-module-unified.txt` |
+
 ---

-## 🚀 Usage Patterns
+## ⚙️ Execution Configuration
+
+### Dynamic Timeout Allocation
+
+**Timeout Ranges**:
+- **Simple tasks** (analysis, search): 20-40min (1200000-2400000ms)
+- **Medium tasks** (refactoring, documentation): 40-60min (2400000-3600000ms)
+- **Complex tasks** (implementation, migration): 60-120min (3600000-7200000ms)
+
+**Codex Multiplier**: Codex commands use 1.5x of allocated time
+
+**Application**: All bash() wrapped commands including Gemini, Qwen and Codex executions
+
+**Auto-detection**: Analyze PURPOSE and TASK fields to determine appropriate timeout
+
+**Command Examples**:
+```bash
+bash(gemini -p "prompt")  # Simple analysis: 20-40min
+bash(codex -C directory --full-auto exec "task")  # Complex implementation: 90-180min
+```
+
+---
+
+### Permission Framework
+
+#### Write Operation Protection
+
+**⚠️ WRITE PROTECTION**: Local codebase write/modify requires EXPLICIT user confirmation
+
+**Mode Hierarchy**:
+- **Analysis Mode (default)**: Read-only, safe for auto-execution
+- **Write Mode**: Requires user explicitly states MODE=write or MODE=auto in prompt
+- **Exception**: User provides clear instructions like "modify", "create", "implement"
+
+#### Tool-Specific Permissions
+
+**Gemini/Qwen Write Access**:
+- Use `--approval-mode yolo` ONLY when MODE=write explicitly specified
+- **Parameter Position**: Place AFTER the prompt: `gemini -p "..." --approval-mode yolo`
+
+**Codex Write Access**:
+- Use `-s danger-full-access` and `--skip-git-repo-check` ONLY when MODE=auto explicitly specified
+- **Parameter Position**: Place AFTER the prompt string at command END: `codex ... exec "..." --skip-git-repo-check -s danger-full-access`
+
+**Default Behavior**: All tools default to analysis/read-only mode without explicit write permission
+
+---
+
+## 🔧 Best Practices
+
+### General Guidelines
+
+**Workflow Principles**:
+- **Start with templates** - Use predefined templates for consistency
+- **Be specific** - Clear PURPOSE, TASK, and EXPECTED fields
+- **Include constraints** - File patterns, scope, requirements in RULES
+- **Discover patterns first** - Use rg/MCP for complex file discovery before CLI execution
+- **Build precise CONTEXT** - Convert discovery results to explicit file references
+- **Document context** - Always reference CLAUDE.md for context
+- **Default to full context** - Use `@**/*` in CONTEXT for comprehensive analysis unless specific files needed
+- **⚠️ No escape characters in CLI commands** - NEVER use `\$`, `\"`, `\'` in actual CLI execution (breaks command substitution and path expansion)
+
+---
+
+### Context Optimization Strategy
+
+**Directory Navigation**: Use `cd [directory] &&` pattern when analyzing specific areas to reduce irrelevant context
+
+**When to change directory**:
+- Specific directory mentioned → Use `cd directory &&` pattern
+- Focused analysis needed → Target specific directory with cd
+- Multi-directory scope → Use `cd` + `--include-directories` for precise control
+
+**When to use `--include-directories`**:
+- Working in subdirectory but need parent/sibling context
+- Cross-directory dependency analysis required
+- Multiple related modules need simultaneous access
+
+---

 ### Workflow Integration (REQUIRED)
+
 When planning any coding task, **ALWAYS** integrate CLI tools:

 1. **Understanding Phase**: Use Gemini for analysis (Qwen as fallback)
@@ -319,185 +506,16 @@ When planning any coding task, **ALWAYS** integrate CLI tools:
 3. **Implementation Phase**: Use Codex for development
 4. **Quality Phase**: Use Codex for testing and validation

-### Common Scenarios
-
-#### Code Analysis
-```bash
-~/.claude/scripts/gemini-wrapper -p "
-PURPOSE: Understand codebase architecture
-TASK: Analyze project structure and identify patterns
-MODE: analysis
-CONTEXT: @{src/**/*.ts,CLAUDE.md} Previous analysis of auth system
-EXPECTED: Architecture overview and integration points
-RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/architecture.txt) | Focus on integration points
-"
-```
-
-#### Documentation Generation
-```bash
-~/.claude/scripts/gemini-wrapper -p "
-PURPOSE: Generate API documentation
-TASK: Create comprehensive API reference from code
-MODE: write
-CONTEXT: @{src/api/**/*}
-EXPECTED: API.md with all endpoints documented
-RULES: Follow project documentation standards
-"
-```
-
-#### Architecture Analysis (Qwen as Gemini fallback)
-```bash
-# Prefer Gemini for architecture analysis
-cd src/auth && ~/.claude/scripts/gemini-wrapper -p "
-PURPOSE: Analyze authentication system architecture
-TASK: Review JWT-based auth system design
-MODE: analysis
-CONTEXT: @{src/auth/**/*} Existing patterns and requirements
-EXPECTED: Architecture analysis report with recommendations
-RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/architecture.txt) | Focus on security
-"
-
-# Use Qwen only if Gemini unavailable
-cd src/auth && ~/.claude/scripts/qwen-wrapper -p "
-PURPOSE: Analyze authentication system architecture
-TASK: Review JWT-based auth system design
-MODE: analysis
-CONTEXT: @{src/auth/**/*} Existing patterns and requirements
-EXPECTED: Architecture analysis report with recommendations
-RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/architecture.txt) | Focus on security
-"
-```
-
-#### Feature Development (Multi-task with Resume)
-```bash
-# First task - establish session
-codex -C path/to/project --full-auto exec "
-PURPOSE: Implement user authentication
-TASK: Create JWT-based authentication system
-MODE: auto
-CONTEXT: @{src/auth/**/*} Database schema from session memory
-EXPECTED: Complete auth module with tests
-RULES: $(cat ~/.claude/workflows/cli-templates/prompts/development/feature.txt) | Follow security best practices
-" --skip-git-repo-check -s danger-full-access
-
-# Continue in same session - Add JWT validation
-codex --full-auto exec "
-PURPOSE: Enhance authentication security
-TASK: Add JWT token validation and refresh logic
-MODE: auto
-CONTEXT: Previous auth implementation from current session
-EXPECTED: JWT validation middleware and token refresh endpoints
-RULES: Follow JWT best practices, maintain session context
-" resume --last --skip-git-repo-check -s danger-full-access
-
-# Continue in same session - Add tests
-codex --full-auto exec "
-PURPOSE: Increase test coverage
-TASK: Generate comprehensive tests for auth module
-MODE: write
-CONTEXT: Auth implementation from current session
-EXPECTED: Complete test suite with 80%+ coverage
-RULES: Use Jest, follow existing patterns
-" resume --last --skip-git-repo-check -s danger-full-access
-```
-
-#### Interactive Session Resume
-```bash
-# Resume previous session with picker
-codex resume
-
-# Or resume most recent session directly
-codex resume --last
-```
-
 ---

-## 🔧 Best Practices
-
-### General Guidelines
- **Start with templates** - Use predefined templates for consistency
- **Be specific** - Clear PURPOSE, TASK, and EXPECTED fields
- **Include constraints** - File patterns, scope, requirements in RULES
- **Discover patterns first** - Use rg/MCP for complex file discovery before CLI execution
- **Build precise CONTEXT** - Convert discovery results to explicit file references
- **Document context** - Always reference CLAUDE.md for context
- **⚠️ No escape characters in CLI commands** - NEVER use `\$`, `\"`, `\'` in actual CLI execution (breaks command substitution and path expansion)
-
-### Context Optimization Strategy
-**Directory Navigation**: Use `cd [directory] &&` pattern when analyzing specific areas to reduce irrelevant context
-
-**When to change directory**:
- Specific directory mentioned → Use `cd directory &&` pattern
- Focused analysis needed → Target specific directory with cd
- Multi-directory scope → Stay in root, use explicit paths or multiple commands
-
-**Example**:
-```bash
-# Gemini - Focused analysis
-cd src/auth && ~/.claude/scripts/gemini-wrapper -p "
-PURPOSE: Understand authentication patterns
-TASK: Analyze auth implementation
-MODE: analysis
-CONTEXT: @{**/*.ts}
-EXPECTED: Pattern documentation
-RULES: Focus on security best practices
-"
-
-# Qwen - Analysis (fallback option, same as Gemini)
-cd src/auth && ~/.claude/scripts/qwen-wrapper -p "
-PURPOSE: Analyze auth architecture
-TASK: Review auth system design and patterns
-MODE: analysis
-CONTEXT: @{**/*}
-EXPECTED: Architecture analysis report
-RULES: Focus on modularity and security
-"
-
-# Codex - Implementation
-codex -C src/auth --full-auto exec "
-PURPOSE: Improve auth implementation
-TASK: Review and enhance auth code
-MODE: auto
-CONTEXT: @{**/*.ts}
-EXPECTED: Code improvements and fixes
-RULES: Maintain backward compatibility
-" --skip-git-repo-check -s danger-full-access
-```
-
 ### Planning Checklist

 For every development task:
 - [ ] **Purpose defined** - Clear goal and intent
 - [ ] **Mode selected** - Execution mode and permission level determined
- [ ] **Context gathered** - File references and session memory documented
+- [ ] **Context gathered** - File references and session memory documented (default `@**/*`)
+- [ ] **Directory navigation** - Determine if `cd` or `cd + --include-directories` needed
 - [ ] **Gemini analysis** completed for understanding
 - [ ] **Template selected** - Appropriate template chosen
 - [ ] **Constraints specified** - File patterns, scope, requirements
 - [ ] **Implementation approach** - Tool selection and workflow
- [ ] **Quality measures** - Testing and validation plan
- [ ] **Tool configuration** - Review `.gemini/CLAUDE.md` or `.codex/Agent.md` if needed
-
---
-
-## ⚙️ Execution Configuration
-
-### Core Execution Rules
- **Dynamic Timeout (20-120min)**: Allocate execution time based on task complexity
-  - Simple tasks (analysis, search): 20-40min (1200000-2400000ms)
-  - Medium tasks (refactoring, documentation): 40-60min (2400000-3600000ms)
-  - Complex tasks (implementation, migration): 60-120min (3600000-7200000ms)
- **Codex Multiplier**: Codex commands use 1.5x of allocated time
- **Apply to All Tools**: All bash() wrapped commands including Gemini, Qwen wrapper and Codex executions
- **Command Examples**: `bash(~/.claude/scripts/gemini-wrapper -p "prompt")`, `bash(codex -C directory --full-auto exec "task")`
- **Auto-detect**: Analyze PURPOSE and TASK fields to determine appropriate timeout
-
-### Permission Framework
- **⚠️ WRITE PROTECTION**: Local codebase write/modify requires EXPLICIT user confirmation
-  - **Analysis Mode (default)**: Read-only, safe for auto-execution
-  - **Write Mode**: Requires user explicitly states MODE=write or MODE=auto in prompt
-  - **Exception**: User provides clear instructions like "modify", "create", "implement"
- **Gemini/Qwen Write Access**: Use `--approval-mode yolo` ONLY when MODE=write explicitly specified
-  - **Parameter Position**: Place AFTER the wrapper command: `gemini-wrapper --approval-mode yolo -p "..."`
- **Codex Write Access**: Use `-s danger-full-access` and `--skip-git-repo-check` ONLY when MODE=auto explicitly specified
-  - **Parameter Position**: Place AFTER the prompt string at command END: `codex ... exec "..." --skip-git-repo-check -s danger-full-access`
- **Default Behavior**: All tools default to analysis/read-only mode without explicit write permission
--- a/.claude/workflows/mcp-tool-strategy.md
+++ b/.claude/workflows/mcp-tool-strategy.md
@@ -86,9 +86,9 @@ mcp__code-index__search_code_advanced(pattern="async.*function", file_pattern="*
 mcp__exa__get_code_context_exa(query="TypeScript async patterns", tokensNum="dynamic")

 # 3. Analyze with Gemini
-cd "src/async" && ~/.claude/scripts/gemini-wrapper -p "
+cd "src/async" && gemini "
 PURPOSE: Understand async patterns
-CONTEXT: Code index results + Exa context + @{src/async/**/*}
+CONTEXT: Code index results + Exa context + @src/async/**/*
 EXPECTED: Pattern analysis
 RULES: Focus on TypeScript best practices
 "
@@ -134,7 +134,7 @@ codex -C src/async --full-auto exec "Apply modern async patterns" -s danger-full
 mcp__code-index__search_code_advanced(pattern="router|routing", file_pattern="*.ts")
 mcp__exa__get_code_context_exa(query="Next.js 14 app router", tokensNum="dynamic")
 mcp__exa__web_search_exa(query="Next.js 14 best practices 2024", numResults=3)
-cd "src/app" && ~/.claude/scripts/gemini-wrapper -p "Learn Next.js patterns"
+cd "src/app" && gemini "Learn Next.js patterns"
 ```

 ### Debugging
@@ -153,7 +153,7 @@ mcp__code-index__refresh_index()  # 刷新索引
 mcp__code-index__find_files(pattern="*auth*")  # Find auth-related files
 mcp__code-index__search_code_advanced(pattern="function.*auth", file_pattern="*.ts")  # Find auth functions
 mcp__code-index__get_file_summary(file_path="src/auth/index.ts")  # Understand structure
-cd "src/auth" && ~/.claude/scripts/gemini-wrapper -p "Analyze auth architecture"
+cd "src/auth" && gemini "Analyze auth architecture"
 ```

 ### Project Setup Workflow
--- a/.claude/workflows/tool-control.yaml
+++ b/.claude/workflows/tool-control.yaml
@@ -1,10 +0,0 @@
-# Tool Control Configuration
-# Controls whether CLI tools (Gemini, Qwen, Codex) are enabled in the workspace
-
-tools:
-  gemini:
-    enabled: true
-  qwen:
-    enabled: true
-  codex:
-    enabled: true
--- a/.claude/workflows/workflow-architecture.md
+++ b/.claude/workflows/workflow-architecture.md
@@ -152,7 +152,7 @@ All task files use this unified 5-field schema with optional artifacts enhanceme
      {
        "step": "analyze_architecture",
        "action": "Review system architecture",
-        "command": "~/.claude/scripts/gemini-wrapper -p \"analyze patterns: [patterns]\"",
+        "command": "gemini \"analyze patterns: [patterns]\"",
        "output_to": "design"
      },
      {
@@ -416,7 +416,7 @@ The `[FLOW_CONTROL]` marker indicates that a task or prompt contains flow contro
 - **Bash commands**: `bash(command)` - Any shell command
 - **Tool calls**: `Read(file)`, `Glob(pattern)`, `Grep(pattern)`
 - **MCP tools**: `mcp__code-index__find_files()`, `mcp__exa__get_code_context_exa()`
- **CLI wrappers**: `~/.claude/scripts/gemini-wrapper`, `codex --full-auto exec`
+- **CLI commands**: `gemini`, `qwen`, `codex --full-auto exec`

 **Example**:
 ```json
@@ -477,10 +477,10 @@ The `[FLOW_CONTROL]` marker indicates that a task or prompt contains flow contro
 "command": "codex --full-auto exec \"task\" resume --last --skip-git-repo-check -s danger-full-access"

 // Gemini (user requested)
-"command": "~/.claude/scripts/gemini-wrapper -p \"analyze [context]\""
+"command": "gemini \"analyze [context]\""

 // Qwen (fallback for Gemini)
-"command": "~/.claude/scripts/qwen-wrapper -p \"analyze [context]\""
+"command": "qwen \"analyze [context]\""
 ```

 **Example Step**:
@@ -517,14 +517,14 @@ The `[FLOW_CONTROL]` marker indicates that a task or prompt contains flow contro

 **Gemini CLI**:
 ```bash
-~/.claude/scripts/gemini-wrapper -p "prompt"
-~/.claude/scripts/gemini-wrapper --approval-mode yolo -p "prompt"  # For write mode
+gemini "prompt"
+gemini --approval-mode yolo "prompt"  # For write mode
 ```

 **Qwen CLI** (Gemini fallback):
 ```bash
-~/.claude/scripts/qwen-wrapper -p "prompt"
-~/.claude/scripts/qwen-wrapper --approval-mode yolo -p "prompt"  # For write mode
+qwen "prompt"
+qwen --approval-mode yolo "prompt"  # For write mode
 ```

 **Codex CLI**:
@@ -892,13 +892,13 @@ fi
 - **Examples**: New features, API endpoints with integration, database schema changes
 - **Task Decomposition**: Two-level hierarchy when decomposition is needed
 - **Agent Coordination**: Context coordination between related tasks
- **Tool Strategy**: `gemini-wrapper` for pattern analysis, `codex --full-auto` for implementation
+- **Tool Strategy**: `gemini` for pattern analysis, `codex --full-auto` for implementation

 #### Complex Workflows
 - **Examples**: Major features, architecture refactoring, security implementations, multi-service deployments
 - **Task Decomposition**: Frequent use of two-level hierarchy with dynamic subtask creation
 - **Agent Coordination**: Multi-agent orchestration with deep context analysis
- **Tool Strategy**: `gemini-wrapper` for architecture analysis, `codex --full-auto` for complex problem solving, `bash()` commands for flexible analysis
+- **Tool Strategy**: `gemini` for architecture analysis, `codex --full-auto` for complex problem solving, `bash()` commands for flexible analysis

 ### Assessment & Upgrades
 - **During Creation**: System evaluates requirements and assigns complexity
--- a/.gemini/GEMINI.md
+++ b/.gemini/GEMINI.md
@@ -17,28 +17,43 @@ EXPECTED: [deliverables]
 RULES: [templates | additional constraints]
 ```

-## MODE Definitions
+## MODE Definitions - STRICT OPERATION BOUNDARIES

-### MODE: analysis (default)
+### MODE: analysis (default) - READ-ONLY OPERATIONS

-**Permissions**:
- Read all CONTEXT files
- Create/modify documentation files
+**ALLOWED OPERATIONS**:
+- **READ**: All CONTEXT files and analyze content
+- **ANALYZE**: Code patterns, architecture, dependencies
+- **GENERATE**: Text output, insights, recommendations
+- **DOCUMENT**: Analysis results in output response only
+
+**FORBIDDEN OPERATIONS**:
+- **NO FILE CREATION**: Cannot create any files on disk
+- **NO FILE MODIFICATION**: Cannot modify existing files
+- **NO FILE DELETION**: Cannot delete any files
+- **NO DIRECTORY OPERATIONS**: Cannot create/modify directories

 **Execute**:
 1. Read and analyze CONTEXT files
 2. Identify patterns and issues
 3. Generate insights and recommendations
-4. Create documentation if needed
-5. Output structured analysis
+4. Output structured analysis (text response only)

-**Constraint**: Do NOT modify source code files
+**CRITICAL CONSTRAINT**: Absolutely NO file system operations - ANALYSIS OUTPUT ONLY

-### MODE: write
+### MODE: write - FILE CREATION/MODIFICATION OPERATIONS

-**Permissions**:
- Full file operations
- Create/modify any files
+**ALLOWED OPERATIONS**:
+- **READ**: All CONTEXT files and analyze content
+- **CREATE**: New files (documentation, code, configuration)
+- **MODIFY**: Existing files (update content, refactor code)
+- **DELETE**: Files when explicitly required
+- **ORGANIZE**: Directory structure operations
+
+**STILL RESTRICTED**:
+- Must follow project conventions and patterns
+- Cannot break existing functionality
+- Must validate changes before completion

 **Execute**:
 1. Read CONTEXT files
--- a/.qwen/QWEN.md
+++ b/.qwen/QWEN.md
@@ -17,28 +17,43 @@ EXPECTED: [deliverables]
 RULES: [templates | additional constraints]
 ```

-## MODE Definitions
+## MODE Definitions - STRICT OPERATION BOUNDARIES

-### MODE: analysis (default)
+### MODE: analysis (default) - READ-ONLY OPERATIONS

-**Permissions**:
- Read all CONTEXT files
- Create/modify documentation files
+**ALLOWED OPERATIONS**:
+- **READ**: All CONTEXT files and analyze content
+- **ANALYZE**: Code patterns, architecture, dependencies
+- **GENERATE**: Text output, insights, recommendations
+- **DOCUMENT**: Analysis results in output response only
+
+**FORBIDDEN OPERATIONS**:
+- **NO FILE CREATION**: Cannot create any files on disk
+- **NO FILE MODIFICATION**: Cannot modify existing files
+- **NO FILE DELETION**: Cannot delete any files
+- **NO DIRECTORY OPERATIONS**: Cannot create/modify directories

 **Execute**:
 1. Read and analyze CONTEXT files
 2. Identify patterns and issues
 3. Generate insights and recommendations
-4. Create documentation if needed
-5. Output structured analysis
+4. Output structured analysis (text response only)

-**Constraint**: Do NOT modify source code files
+**CRITICAL CONSTRAINT**: Absolutely NO file system operations - ANALYSIS OUTPUT ONLY

-### MODE: write
+### MODE: write - FILE CREATION/MODIFICATION OPERATIONS

-**Permissions**:
- Full file operations
- Create/modify any files
+**ALLOWED OPERATIONS**:
+- **READ**: All CONTEXT files and analyze content
+- **CREATE**: New files (documentation, code, configuration)
+- **MODIFY**: Existing files (update content, refactor code)
+- **DELETE**: Files when explicitly required
+- **ORGANIZE**: Directory structure operations
+
+**STILL RESTRICTED**:
+- Must follow project conventions and patterns
+- Cannot break existing functionality
+- Must validate changes before completion

 **Execute**:
 1. Read CONTEXT files
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -5,7 +5,6 @@
 This document defines project-specific coding standards and development principles.
 ### CLI Tool Context Protocols
 For all CLI tool usage, command syntax, and integration guidelines:
- **Tool Control Configuration**: @~/.claude/workflows/tool-control.yaml - Controls CLI tool availability for all commands and agent executions (if disabled, use other enabled CLI tools or Claude's own capabilities)
 - **MCP Tool Strategy**: @~/.claude/workflows/mcp-tool-strategy.md
 - **Intelligent Context Strategy**: @~/.claude/workflows/intelligent-tools-strategy.md
 - **Context Search Commands**: @~/.claude/workflows/context-search-strategy.md
--- a/GETTING_STARTED.md
+++ b/GETTING_STARTED.md
@@ -82,42 +82,77 @@ Understanding these concepts will help you use CCW more effectively:

 ## 🛠️ Common Scenarios

-### Scenario 1: Developing a New Feature (as shown above)
+### Scenario 1: Quick Feature Development

-This is the most common use case, following the "start session → plan → execute" pattern.
+For simple, well-defined features, use the direct "plan → execute" pattern:

 ```bash
-# 1. Start a session
-/workflow:session:start "User Login Feature"
-
-# 2. Create a plan
+# Create plan (auto-creates session)
 /workflow:plan "Implement JWT-based user login and registration"

-# 3. Execute
+# Execute
 /workflow:execute
 ```

-### Scenario 2: UI Design
+> **💡 Note**: `/workflow:plan` automatically creates a session. You can also manually start a session first with `/workflow:session:start "Feature Name"`.

-CCW has powerful UI design capabilities, capable of generating complex UI prototypes from simple text descriptions.
+### Scenario 2: UI Design Exploration
+
+For UI-focused projects, start with design exploration before implementation: **ui-design → update → plan → execute**

 ```bash
-# 1. Start a UI design workflow
-/workflow:ui-design:explore-auto --prompt "A modern, clean admin dashboard login page with username, password fields and a login button"
+# Step 1: Generate UI design variations (auto-creates session)
+/workflow:ui-design:explore-auto --prompt "A modern, clean admin dashboard login page"

-# 2. View the generated prototype
-# After the command finishes, it will provide a path to a compare.html file. Open it in your browser to preview.
+# Step 2: Review designs in compare.html, then update brainstorming artifacts
+/workflow:ui-design:update --session <session-id> --selected-prototypes "login-v1,login-v2"
+
+# Step 3: Generate implementation plan with design references
+/workflow:plan
+
+# Step 4: Execute the implementation
+/workflow:execute
 ```

-### Scenario 3: Fixing a Bug
+> **💡 Tip**: The `update` command integrates selected design prototypes into brainstorming artifacts, ensuring implementation follows the approved designs.

-CCW can help you analyze and fix bugs.
+### Scenario 3: Complex Feature with Multi-Agent Brainstorming
+
+For complex features requiring thorough analysis, use the complete workflow: **brainstorm → plan → execute**

 ```bash
-# 1. Use the bug-index command to analyze the problem
-/cli:mode:bug-index "Incorrect success message even with wrong password on login"
+# Step 1: Multi-agent brainstorming (auto-creates session)
+/workflow:brainstorm:auto-parallel "Design a real-time collaborative document editing system with conflict resolution"

-# 2. The AI will analyze the relevant code and generate a fix plan. You can then execute this plan.
+# Optional: Specify number of expert roles (default: 3, max: 9)
+/workflow:brainstorm:auto-parallel "Build scalable microservices platform" --count 5
+
+# Step 2: Generate implementation plan from brainstorming results
+/workflow:plan
+
+# Step 3: Execute the plan
+/workflow:execute
+```
+
+**Brainstorming Benefits**:
+- **Auto role selection**: Analyzes your topic and selects 3-9 relevant expert roles (system-architect, ui-designer, product-manager, etc.)
+- **Parallel execution**: Multiple AI agents analyze simultaneously from different perspectives
+- **Comprehensive specification**: Generates integrated requirements and design document
+
+**When to Use Brainstorming**:
+- Complex features requiring multiple perspectives
+- Architectural decisions with significant impact
+- When you need thorough requirements before implementation
+
+### Scenario 4: Bug Fixing
+
+Quick bug analysis and fix workflow:
+
+```bash
+# Analyze the bug
+/cli:mode:bug-index "Incorrect success message with wrong password"
+
+# Generate and execute fix plan
 /workflow:execute
 ```

--- a/GETTING_STARTED_CN.md
+++ b/GETTING_STARTED_CN.md
@@ -1,7 +1,7 @@

 # 🚀 Claude Code Workflow (CCW) - 快速上手指南

-欢迎来到 Claude Code Workflow (CCW) v4.5.0！本指南将帮助您在 5 分钟内快速入门，体验由 AI 驱动的自动化软件开发流程，以及我们最新的工作流系统优化。
+欢迎来到 Claude Code Workflow (CCW) v4.6.2！本指南将帮助您在 5 分钟内快速入门，体验由 AI 驱动的自动化软件开发流程，以及我们最新的工作流系统优化。

 ---

@@ -13,30 +13,22 @@

 首先，请确保您已经根据 [安装指南](INSTALL_CN.md) 完成了 CCW 的安装。

-### 第 2 步：启动一个工作流会话
+### 第 2 步：创建执行计划（会自动启动会话）

-把“会话”想象成一个专门的项目文件夹。CCW 会在这里存放所有与您当前任务相关的文件。
-
-```bash
-/workflow:session:start "我的第一个 Web 应用"
-```
-
-您会看到系统创建了一个新的会话，例如 `WFS-我的第一个-web-应用`。
-
-### 第 3 步：创建执行计划
-
-现在，告诉 CCW 您想做什么。CCW 会分析您的需求，并自动生成一个详细的、可执行的任务计划。
+直接告诉 CCW 您想做什么。CCW 会分析您的需求，并自动生成一个详细的、可执行的任务计划。

 ```bash
 /workflow:plan "创建一个简单的 Express API，在根路径返回 Hello World"
 ```

+> **💡 提示**：`/workflow:plan` 会自动创建和启动工作流会话，无需手动执行 `/workflow:session:start`。会话会根据任务描述自动命名，例如 `WFS-创建一个简单的-express-api`。
+
 这个命令会启动一个完全自动化的规划流程，包括：
 1.  **上下文收集**：分析您的项目环境。
 2.  **智能体分析**：AI 智能体思考最佳实现路径。
 3.  **任务生成**：创建具体的任务文件（`.json` 格式）。

-### 第 4 步：执行计划
+### 第 3 步：执行计划

 当计划创建完毕后，您就可以命令 AI 智能体开始工作了。

@@ -46,7 +38,7 @@

 您会看到 CCW 的智能体（如 `@code-developer`）开始逐一执行任务。它会自动创建文件、编写代码、安装依赖。

-### 第 5 步：查看状态
+### 第 4 步：查看状态

 想知道进展如何？随时可以查看当前工作流的状态。

@@ -82,42 +74,77 @@

 ## 🛠️ 常见场景示例

-### 场景 1：开发一个新功能（如上所示）
+### 场景 1：快速功能开发

-这是最常见的用法，遵循“启动会话 → 规划 → 执行”的模式。
+对于简单、明确的功能，使用直接的"规划 → 执行"模式：

 ```bash
-# 1. 启动会话
-/workflow:session:start "用户登录功能"
-
-# 2. 创建计划
+# 创建计划（自动创建会话）
 /workflow:plan "实现基于 JWT 的用户登录和注册功能"

-# 3. 执行
+# 执行
 /workflow:execute
 ```

-### 场景 2：进行 UI 设计
+> **💡 提示**：`/workflow:plan` 会自动创建会话。您也可以先手动启动会话：`/workflow:session:start "功能名称"`。

-CCW 拥有强大的 UI 设计能力，可以从简单的文本描述生成复杂的 UI 原型。
+### 场景 2：UI 设计探索
+
+对于以 UI 为重点的项目，在实现前先进行设计探索：**ui-design → update → 规划 → 执行**

 ```bash
-# 1. 启动一个 UI 设计工作流
-/workflow:ui-design:explore-auto --prompt "一个现代、简洁的管理后台登录页面，包含用户名、密码输入框和登录按钮"
+# 第 1 步：生成 UI 设计变体（自动创建会话）
+/workflow:ui-design:explore-auto --prompt "一个现代、简洁的管理后台登录页面"

-# 2. 查看生成的原型
-# 命令执行完毕后，会提供一个 compare.html 文件的路径，在浏览器中打开即可预览。
+# 第 2 步：在 compare.html 中审查设计，然后更新头脑风暴工件
+/workflow:ui-design:update --session <session-id> --selected-prototypes "login-v1,login-v2"
+
+# 第 3 步：使用设计引用生成实现计划
+/workflow:plan
+
+# 第 4 步：执行实现
+/workflow:execute
 ```

-### 场景 3：修复一个 Bug
+> **💡 提示**：`update` 命令将选定的设计原型集成到头脑风暴工件中，确保实现遵循批准的设计。

-CCW 可以帮助您分析并修复 Bug。
+### 场景 3：复杂功能的多智能体头脑风暴
+
+对于需要深入分析的复杂功能，使用完整工作流：**头脑风暴 → 规划 → 执行**

 ```bash
-# 1. 使用 bug-index 命令分析问题
-/cli:mode:bug-index "用户登录时，即使密码错误也提示成功"
+# 第 1 步：多智能体头脑风暴（自动创建会话）
+/workflow:brainstorm:auto-parallel "设计一个支持冲突解决的实时协作文档编辑系统"

-# 2. AI 会分析相关代码，并生成一个修复计划。然后您可以执行这个计划。
+# 可选：指定专家角色数量（默认：3，最大：9）
+/workflow:brainstorm:auto-parallel "构建可扩展的微服务平台" --count 5
+
+# 第 2 步：从头脑风暴结果生成实现计划
+/workflow:plan
+
+# 第 3 步：执行计划
+/workflow:execute
+```
+
+**头脑风暴优势**：
+- **自动角色选择**：分析主题并选择 3-9 个相关专家角色（系统架构师、UI 设计师、产品经理等）
+- **并行执行**：多个 AI 智能体从不同视角同时分析
+- **综合规格说明**：生成整合的需求和设计文档
+
+**何时使用头脑风暴**：
+- 需要多视角分析的复杂功能
+- 具有重大影响的架构决策
+- 实现前需要详尽需求分析
+
+### 场景 4：Bug 修复
+
+快速 Bug 分析和修复工作流：
+
+```bash
+# 分析 Bug
+/cli:mode:bug-index "密码错误时仍显示成功消息"
+
+# 生成并执行修复计划
 /workflow:execute
 ```

@@ -226,6 +253,31 @@ CCW 使用分层的 CLAUDE.md 文档系统维护项目上下文。定期更新
 - 每周定期维护
 - 发现 AI 输出偏差时

+#### 快速加载特定任务上下文
+
+当您需要立即获取特定任务的上下文，而无需更新文档时：
+
+```bash
+# 为特定任务加载上下文到内存
+/memory:load "在当前前端基础上开发用户认证功能"
+
+# 使用其他 CLI 工具进行分析
+/memory:load --tool qwen "重构支付模块API"
+```
+
+**工作原理**：
+- 委托 AI 智能体进行自主项目分析
+- 发现相关文件并提取任务特定关键词
+- 使用 CLI 工具（Gemini/Qwen）进行深度分析以节省令牌
+- 返回加载到内存中的结构化"核心内容包"
+- 为后续智能体操作提供上下文
+
+**使用时机**：
+- 开始新功能或任务之前
+- 需要快速获取上下文而无需完整文档重建时
+- 针对特定任务的架构或模式发现
+- 作为基于智能体开发工作流的准备工作
+
 #### 增量更新相关模块

 适用于日常开发，只更新变更影响的模块：
Author	SHA1	Message	Date
catlog22	e3a6c885db	refactor: 更新模块文档更新流程，简化任务描述并增强执行脚本的失败处理	2025-10-22 12:17:52 +08:00
catlog22	eb9b10c96b	docs: 更新文档，明确任务结构和操作模式的约束条件	2025-10-22 11:16:34 +08:00
catlog22	804617d8cd	refactor: 移除策略参数，改为基于目录深度自动选择更新策略	2025-10-22 10:50:46 +08:00
catlog22	b6c1880abf	feat: 更新文档更新脚本，添加策略参数以支持单层和多层更新	2025-10-22 10:35:30 +08:00
catlog22	7783ee0ac5	refactor: 更新 update_module_claude.sh 脚本，调整参数顺序并添加模型选择说明	2025-10-21 21:02:17 +08:00
catlog22	de3dc35c5b	refactor: improve memory update commands with parallel execution and fix file naming - Renamed update-memory-full.md -> update-full.md for consistency - Renamed update-memory-related.md -> update-related.md for consistency - Added parallel execution support (max 4 concurrent) for both direct and agent modes - Fixed execution strategy: <20 modules direct parallel, ≥20 modules agent batch - Removed misleading "orchestrator agent" section that caused hierarchy confusion - Clarified coordinator always executes, agents only for batching ≥20 modules - Added explicit file naming rules to prevent ToolSidebar.CLAUDE.md errors - Updated template and script with CRITICAL file naming constraints - Removed all emoji symbols from documentation for clean text format - Added smart filtering strategy to docs.md for auto-skip patterns Key improvements: - Phase 3A: Direct parallel execution (max 4 concurrent per depth) - Phase 3B: Agent batch execution (4 modules/agent) - Both modes use same batching strategy, differ only in agent layer - Explicit CLAUDE.md file naming in 3 locations (script, template, checklist) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>	2025-10-21 20:28:11 +08:00
catlog22	c640cfefe8	docs: 更新智能工具选择策略文档，明确外部目录引用的两步要求和示例	2025-10-21 15:58:02 +08:00
catlog22	d3ddfadf16	docs: 更新智能工具选择策略文档，添加关键目录范围规则和多目录支持说明	2025-10-21 15:41:49 +08:00
catlog22	2072ddfa6e	feat: 添加提示增强器文档，提供模糊提示转化为可操作规范的详细说明	2025-10-21 15:33:27 +08:00
catlog22	9e584d911b	fix: 修正命令示例中的参数格式，确保一致性和正确性	2025-10-21 15:26:22 +08:00
catlog22	b30a5269d2	chore: merge detached commits back to main	2025-10-21 15:17:45 +08:00
catlog22	5046565d4c	chore: 删除不再使用的工具包装脚本和配置文件	2025-10-21 15:07:37 +08:00
catlog22	8ebae76b74	docs: 移除工具控制配置的冗余说明	2025-10-21 15:07:03 +08:00
catlog22	83664cb777	feat: migrate to Gemini CLI v0.11.0-nightly with native prompt support ## Major Changes ### Gemini CLI Integration (google-gemini/gemini-cli#11228) - Migrate from wrapper scripts to native Gemini CLI v0.11.0-nightly - Remove `-p` flag requirement for prompt strings - Deprecate `gemini-wrapper` and `qwen-wrapper` scripts - Update all commands and workflows to use direct CLI syntax ### Command Syntax Updates - Before: `gemini -p "CONTEXT: @*/ prompt"` - After: `gemini "CONTEXT: @*/ prompt"` - Apply to all 70+ command files and workflow templates - Maintain backward compatibility for Qwen fallback ### File Pattern Migration - Replace `@{CLAUDE.md}` with `@CLAUDE.md` - Replace `@{*/}` with `@*/` - Update all file references to use direct @ notation - Remove legacy brace syntax across all documentation ### Documentation Improvements - Reorganize `intelligent-tools-strategy.md` structure - Add Quick Start section with decision matrix - Enhance `--include-directories` best practices - Add comprehensive command templates and examples - Improve navigation with clearer section hierarchy ### Files Modified (75+ files) - Commands: All CLI commands updated (cli/, workflow/, task/, memory/) - Workflows: Core strategy files and templates - Agents: CLI execution agent and doc generator - Templates: Planning roles and tech stack guides ## Breaking Changes - Gemini CLI v0.11.0-nightly or later required - Old wrapper scripts no longer supported - Legacy `@{pattern}` syntax deprecated ## Migration Guide Users should: 1. Update Gemini CLI to v0.11.0-nightly or later 2. Remove `-p` flag from existing commands 3. Update file patterns from `@{pattern}` to `@pattern` 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>	2025-10-21 14:46:16 +08:00
catlog22	360a2b9edc	docs: 完善 UI 设计工作流，添加设计更新步骤 ### 主要改进 UI 设计完整工作流 - 从探索到实现的完整流程： - 场景 2 更新：ui-design → update → plan → execute（新增 update 步骤） - 明确说明需要使用 `/workflow:ui-design:update` 更新头脑风暴工件 - 确保实现遵循批准的设计原型新增步骤说明： ```bash # 第 2 步：审查设计后更新概念设计 /workflow:ui-design:update --session <session-id> --selected-prototypes "login-v1,login-v2" ``` 工作流逻辑： 1. explore-auto: 生成多个设计变体 2. update: 将选定的设计原型引用集成到头脑风暴工件 3. plan: 基于更新后的设计引用生成实现计划 4. execute: 执行实现为什么需要 update 步骤： - 将 UI 设计决策正式纳入项目规格 - 确保实现代码参考正确的设计原型 - 保持设计和实现的一致性 - 为后续的代码生成提供设计上下文双语文档同步： - 英文版：完整的 4 步工作流说明 - 中文版：相同流程的中文说明和提示 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>	2025-10-20 14:13:01 +08:00
catlog22	5123675fbf	docs: 重新组织场景顺序，突出头脑风暴在复杂功能开发中的作用 ### 主要改进场景顺序优化 - 从简单到复杂的逻辑流程： 1. 场景 1：快速功能开发 - 简单功能的 plan → execute 模式 2. 场景 2：复杂功能的多智能体头脑风暴 - 展示完整工作流：brainstorm → plan → execute 3. 场景 3：UI 设计 - 专业化工作流 4. 场景 4：Bug 修复 - 维护场景场景 2 的关键改进： - 明确头脑风暴应在 plan 之前，用于复杂功能的需求分析 - 展示完整的三阶段工作流（头脑风暴 → 规划 → 执行） - 简化说明，移除冗余的角色列表和阶段详情 - 聚焦于"何时使用头脑风暴"的实用指导内容精简： - 移除重复的专家角色详细列表（从原来的详细分类简化为一句话） - 移除工作流阶段的详细说明（用户可从实际执行中了解） - 更紧凑的场景描述，提高可读性 - 减少 22 行代码（99 → 77 行变更）逻辑一致性提升： - 场景 1：适合新手，快速上手 - 场景 2：展示 CCW 最强大的功能 - 多智能体协作 - 场景 3-4：专业化场景，展示多样性用户体验改进：用户现在可以清楚地理解： 1. 简单功能直接 plan 2. 复杂功能先 brainstorm 再 plan 3. 完整的工作流逻辑顺序 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>	2025-10-20 14:10:23 +08:00
catlog22	967490dcf6	docs: 添加多智能体头脑风暴工作流说明到入门指南 ### 新增内容 GETTING_STARTED.md (英文): - 添加"Scenario 4: Multi-Agent Brainstorming"场景示例 - 说明 `/workflow:brainstorm:auto-parallel` 命令的工作原理 - 列出 9 个可用专家角色（技术、产品设计、敏捷质量、API设计） - 解释工作流的 4 个阶段（框架生成、并行分析、综合整合、行动计划） - 提供使用时机指导 GETTING_STARTED_CN.md (中文): - 添加"场景 4：多智能体头脑风暴"场景示例 - 包含与英文版相同的详细说明和中文翻译 - 专家角色的中文注释（如"系统架构师"、"UI设计师"等） ### 功能亮点多智能体头脑风暴特性: - 自动角色选择：基于主题关键词智能选择专家角色 - 并行执行：多个 AI 智能体同时从不同视角分析 - 灵活配置：支持 `--count` 参数控制角色数量（默认 3，最大 9） - 综合输出：生成包含跨角色洞察的完整规格说明示例命令: ```bash /workflow:brainstorm:auto-parallel "设计实时协作文档编辑系统" /workflow:brainstorm:auto-parallel "构建可扩展微服务平台" --count 5 ``` ### 改进用户体验这些更新帮助用户： 1. 了解何时使用头脑风暴工作流 2. 理解多视角分析的价值 3. 掌握头脑风暴到实现的完整流程 4. 根据项目复杂度选择合适的工具 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>	2025-10-20 14:06:25 +08:00
catlog22	e15da0e461	docs: 更新中文入门指南 - 添加 /memory:load 说明和会话自动创建提示 ### 主要更新版本更新: - 更新版本号从 v4.5.0 到 v4.6.2 简化工作流步骤: - 修正快速入门步骤：从 5 步简化为 4 步 - 说明 `/workflow:plan` 会自动创建会话，无需手动 `/workflow:session:start` - 在场景 1 中添加提示：也可以手动启动会话后再规划添加 /memory:load 命令说明: - 在"内存管理"章节添加"快速加载特定任务上下文"小节 - 位于"完整项目重建索引"和"增量更新相关模块"之间 - 包含工作原理说明和使用时机指导 - 提供实用示例 UI 设计工作流说明: - 说明 UI 设计命令也会自动创建和管理会话 - 添加提示说明 `/workflow:ui-design:explore-auto` 和 `/workflow:brainstorm:auto-parallel` 的自动会话管理 ### 改进用户体验这些更新帮助用户理解： 1. 大多数工作流命令会自动管理会话，简化操作流程 2. `/memory:load` 提供快速上下文加载，无需完整文档重建 3. 更清晰的步骤说明，减少困惑 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>	2025-10-20 14:02:36 +08:00