docs: 更新文档，明确任务结构和操作模式的约束条件

2026-02-05 01:50:27 +08:00 · 2025-10-22 11:16:34 +08:00
parent 804617d8cd
commit eb9b10c96b
4 changed files with 139 additions and 369 deletions
--- a/.claude/commands/memory/update-full.md
+++ b/.claude/commands/memory/update-full.md
@@ -8,111 +8,72 @@ argument-hint: "[--tool gemini|qwen|codex] [--path <directory>]"

 ## Overview

-Orchestrates project-wide CLAUDE.md updates using batched agent execution with automatic tool fallback (gemini→qwen→codex) and 3-layer architecture support.
+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**:
-1. Discovery & Analysis → 2. Plan Presentation → 3. Batched Agent Execution → 4. Safety Verification
+**Execution Flow**: Discovery → Plan Presentation → Execution → Safety Verification

-## 3-Layer Architecture
+## 3-Layer Architecture & Auto-Strategy Selection

-**Layer Definition**:
- **Layer 3 (Bottom/Deepest)**: depth ≥ 3 - Use multi-layer strategy (generate CLAUDE.md for all subdirectories)
- **Layer 2 (Middle)**: depth 1-2 - Use single-layer strategy (aggregate from children)
- **Layer 1 (Top)**: depth 0 - Use single-layer strategy (aggregate from children)
+### Layer Definition & Strategy Assignment

-**Update Direction**: Layer 3 → Layer 2 → Layer 1 (bottom-up)
+| 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,...}` |

-**Strategy Auto-Selection**: Strategies are automatically determined by directory depth:
- **Layer 3 (depth ≥3)**: Uses `multi-layer` strategy (handles unstructured files)
- **Layer 2 (depth 1-2)**: Uses `single-layer` strategy (aggregates from children)
- **Layer 1 (depth 0)**: Uses `single-layer` strategy (aggregates from children)
+**Update Direction**: Layer 3 → Layer 2 → Layer 1 (bottom-up dependency flow)

-## Update Strategies
+**Strategy Auto-Selection**: Strategies are automatically determined by directory depth - no user configuration needed.

-### Strategy 1: single-layer (For Layers 1-2)
+### Strategy Details

-**Use Case**: Upper layers that aggregate from existing child CLAUDE.md files
+#### 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

-**Context Configuration**:
- **Layer 2** (depth 1-2): `@*/CLAUDE.md @*.{ts,tsx,js,jsx,py,sh,md,json,yaml,yml}` - Direct children CLAUDE.md + current layer code
- **Layer 1** (depth 0): `@*/CLAUDE.md @*.{ts,tsx,js,jsx,py,sh,md,json,yaml,yml}` - Direct children CLAUDE.md + current layer code
+#### 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

-**Benefits**:
- Minimal context consumption
- Clear layer separation
- Each layer reads only immediate children summaries
- Ideal for structured projects with defined hierarchy
-
-**Example Execution Flow**:
+### Example Flow
 ```
-src/auth/handlers/ (depth 3) - MULTI-LAYER STRATEGY
+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, middleware/CLAUDE.md, index.ts)
+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
+src/ (depth 1) → SINGLE-LAYER STRATEGY
  CONTEXT: @*/CLAUDE.md (auth/CLAUDE.md, utils/CLAUDE.md)
  GENERATES: ./CLAUDE.md only
  ↓
-./ (depth 0) - SINGLE-LAYER STRATEGY
+./ (depth 0) → SINGLE-LAYER STRATEGY
  CONTEXT: @*/CLAUDE.md (src/CLAUDE.md, tests/CLAUDE.md)
  GENERATES: ./CLAUDE.md only
 ```

-### Strategy 2: multi-layer (For Layer 3 only)
-
-**Use Case**: Deepest layer with unstructured files, initial documentation generation
-
-**Context Configuration**:
- **Layer 3** (depth ≥3): `@**/*` - All files in current directory and generate CLAUDE.md for each subdirectory
-
-**Benefits**:
- Handles unstructured file layouts
- Generates documentation for all directories with files
- Creates the foundation layer for upper layers to reference
- Ideal for leaf directories that haven't been documented yet
-
-**Example Execution Flow**:
-```
-src/auth/handlers/ (depth 3) - MULTI-LAYER STRATEGY
-  CONTEXT: @**/* (all files: login.ts, logout.ts, validation/)
-  GENERATES: ./CLAUDE.md + validation/CLAUDE.md (if validation/ has files)
-```
-
-### Strategy Selection Guidelines
-
-**Strategy Assignment by Layer**:
-
-| Layer | Depth | Strategy | Purpose |
-|-------|-------|----------|---------|
-| Layer 3 (Deepest) | ≥3 | multi-layer | Generate docs for unstructured directories |
-| Layer 2 (Middle) | 1-2 | single-layer | Aggregate from children + current code |
-| Layer 1 (Top) | 0 | single-layer | Aggregate from children + current code |
-
-**Layer 3 Processing**:
- Use multi-layer strategy to handle unstructured file layouts
- Generate CLAUDE.md for each directory containing files
- Create foundation for upper layers to reference
-
-## Core Rules
+## 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, no agent overhead)
-   - ≥20 modules: Agent batch processing (4 modules/agent, 73% overhead reduction)
+   - **<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. **Strategy Auto-Selection**: Strategies determined by directory depth (multi-layer for depth ≥3, single-layer for depth 0-2)
-8. **Layer-based Grouping**: Group modules by LAYER (not depth) for execution
+7. **Layer-based Grouping**: Group modules by LAYER (not depth) for execution

 ## Tool Fallback Hierarchy

@@ -124,7 +85,15 @@ src/auth/handlers/ (depth 3) - MULTI-LAYER STRATEGY

 **Trigger**: Non-zero exit code from update script

-## Phase 1: Discovery & Analysis
+| 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
@@ -138,23 +107,21 @@ 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 (Node.js/Python/Go/Rust/etc).
+**Smart filter**: Auto-detect and skip tests/build/config/docs based on project tech stack.

-## Phase 2: Plan Presentation
+### Phase 2: Plan Presentation

-**Present filtered plan**:
+**For <20 modules**:
 ```
 Update Plan:
  Tool: gemini (fallback: qwen → codex)
  Total: 7 modules
-  Execution: Direct sequential (< 20 modules threshold)
+  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
-  - ./parametric (6 files) - depth 1 [Layer 2] - single-layer strategy
-  - ./results (7 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

@@ -162,16 +129,8 @@ Update Plan:
  - Layer 2 (depth 1-2): @*/CLAUDE.md + current code files
  - Layer 1 (depth 0): @*/CLAUDE.md + current code files

-  Auto-skipped (15 paths):
-  - Tests: ./tests, **/*_test.py (8 paths)
-  - Build: __pycache__, dist, *.egg-info (5 paths)
-  - Config: setup.py, requirements.txt (2 paths)
-
-  Execution order (by depth):
-  1. Depth 2: ./core/interfaces
-  2. Depth 1: ./core, ./models, ./parametric, ./results, ./utils
-  3. Depth 0: .
-
+  Auto-skipped: ./tests, __pycache__, setup.py (15 paths)
+  Execution order: Layer 2 → Layer 1
  Estimated time: ~5-10 minutes

  Confirm execution? (y/n)
@@ -195,13 +154,6 @@ Update Plan:
  - Layer 2 (depth 1-2): @*/CLAUDE.md + current code files
  - Layer 1 (depth 0): @*/CLAUDE.md + current code files

-  Auto-skipped (45 paths):
-  - Tests: ./tests, ./src/**/*.test.ts (18 paths)
-  - Config: package.json, tsconfig.json, vite.config.ts (12 paths)
-  - Build: ./dist, ./node_modules, ./.next (8 paths)
-  - Docs: ./README.md, ./docs (5 paths)
-  - Other: .git, .vscode, coverage (2 paths)
-
  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]
@@ -212,38 +164,12 @@ Update Plan:
  Confirm execution? (y/n)
 ```

-**Decision logic**:
- User confirms "y": Proceed with execution
- User declines "n": Abort, no changes
- <20 modules: Direct execution (Phase 3A)
- ≥20 modules: Agent batch execution (Phase 3B)
+### Phase 3A: Direct Execution (<20 modules)

-## Phase 3A: Direct Execution (<20 modules)
-
-**Strategy**: Parallel execution within layer (max 4 concurrent), no agent overhead, tool fallback per module.
+**Strategy**: Parallel execution within layer (max 4 concurrent), no agent overhead.

 ```javascript
 // Group modules by LAYER (not depth)
-function group_by_layer(modules) {
-  let layers = {
-    3: [],  // Layer 3: depth ≥3
-    2: [],  // Layer 2: depth 1-2
-    1: []   // Layer 1: depth 0
-  };
-
-  modules.forEach(module => {
-    if (module.depth >= 3) {
-      layers[3].push(module);
-    } else if (module.depth >= 1) {
-      layers[2].push(module);
-    } else {
-      layers[1].push(module);
-    }
-  });
-
-  return layers;
-}
-
 let modules_by_layer = group_by_layer(module_list);
 let tool_order = construct_tool_order(primary_tool);

@@ -251,112 +177,40 @@ 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);  // Split into groups of 4
+  let batches = batch_modules(modules_by_layer[layer], 4);

  for (let batch of batches) {
-    // Execute batch in parallel (max 4 concurrent)
    let parallel_tasks = batch.map(module => {
      return async () => {
-        let success = false;
        // 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}");
+          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}");
-            success = true;
-            break;
+            report(`✅ ${module.path} (Layer ${layer}) updated with ${tool}`);
+            return true;
          }
        }
-        if (!success) {
-          report("❌ FAILED: ${module.path} (Layer ${layer}) failed all tools");
-        }
+        report(`❌ FAILED: ${module.path} (Layer ${layer}) failed all tools`);
+        return false;
      };
    });

-    await Promise.all(parallel_tasks.map(task => task()));  // Run batch in parallel
+    await Promise.all(parallel_tasks.map(task => task()));
  }
 }
 ```

-**Example execution (7 modules with auto-strategy)**:
-```bash
-# Layer 2 (1 module: depth 2) - auto-selects single-layer strategy
-bash(cd ./core/interfaces && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "gemini")
-# → CONTEXT: @*/CLAUDE.md @*.ts @*.tsx... (direct children + current code)
-# → Success with gemini
+### Phase 3B: Agent Batch Execution (≥20 modules)

-# Layer 2 (5 modules: depth 1 → 2 batches: [4, 1]) - auto-selects single-layer strategy
-# Batch 1 (4 modules in parallel):
-bash(cd ./core && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "gemini") &
-bash(cd ./models && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "gemini") &
-bash(cd ./parametric && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "gemini") &
-bash(cd ./results && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "gemini") &
-wait  # Wait for batch 1 to complete
-
-# Batch 2 (1 module):
-bash(cd ./utils && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "gemini")
-# → Success with gemini
-
-# Layer 1 (1 module: depth 0) - auto-selects single-layer strategy
-bash(cd . && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "gemini")
-# → CONTEXT: @*/CLAUDE.md @*.ts... (direct children + current code)
-# → Success with gemini
-```
-
-**Benefits**:
- No agent startup overhead
- Parallel execution within depth (max 4 concurrent)
- Tool fallback still applies per module
- Faster for small projects (<20 modules)
- Same batching strategy as Phase 3B but without agent layer
-
---
-
-## Phase 3B: Agent Batch Execution (≥20 modules)
-
-### Batching Strategy
+**Strategy**: Batch modules into groups of 4, spawn memory-bridge agents per batch.

 ```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
-// Group modules by LAYER (not depth)
-function group_by_layer(modules) {
-  let layers = {
-    3: [],  // Layer 3: depth ≥3
-    2: [],  // Layer 2: depth 1-2
-    1: []   // Layer 1: depth 0
-  };
-
-  modules.forEach(module => {
-    if (module.depth >= 3) {
-      layers[3].push(module);
-    } else if (module.depth >= 1) {
-      layers[2].push(module);
-    } else {
-      layers[1].push(module);
-    }
-  });
-
-  return layers;
-}
-
+// 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);

-// Process by LAYER (3 → 2 → 1), not by depth
 for (let layer of [3, 2, 1]) {
  if (modules_by_layer[layer].length === 0) continue;

@@ -373,89 +227,35 @@ for (let layer of [3, 2, 1]) {
    );
  }

-  await parallel_execute(worker_tasks);  // Batches run in parallel within layer
+  await parallel_execute(worker_tasks);
 }
 ```

-### Batch Worker Prompt Template
-
+**Batch Worker Prompt Template**:
 ```
 PURPOSE: Update CLAUDE.md for assigned modules with tool fallback and auto-strategy selection

-TASK:
-Update documentation for the following modules. For each module, try tools in order until success.
-Strategy is automatically determined by directory depth.
+TASK: Update documentation for modules with auto-determined strategy based on directory depth.

 MODULES:
 {{module_path_1}} (depth: {{depth_1}}, layer: {{layer_1}})
 {{module_path_2}} (depth: {{depth_2}}, layer: {{layer_2}})
-{{module_path_3}} (depth: {{depth_3}}, layer: {{layer_3}})
-{{module_path_4}} (depth: {{depth_4}}, layer: {{layer_4}})
+...

-TOOLS (try in order):
-1. {{tool_1}}
-2. {{tool_2}}
-3. {{tool_3}}
+TOOLS (try in order): {{tool_1}}, {{tool_2}}, {{tool_3}}

 EXECUTION:
-For each module above:
-  1. cd "{{module_path}}"
-  2. Auto-determine strategy: strategy = (depth >= 3) ? "multi-layer" : "single-layer"
-  3. Try tool 1:
-     bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "${strategy}" "." "{{tool_1}}")
-     → Success: Report "✅ {{module_path}} updated with {{tool_1}}", proceed to next module
-     → Failure: Try tool 2
-  4. Try tool 2:
-     bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "${strategy}" "." "{{tool_2}}")
-     → Success: Report "✅ {{module_path}} updated with {{tool_2}}", proceed to next module
-     → Failure: Try tool 3
-  5. Try tool 3:
-     bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "${strategy}" "." "{{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
+For each module:
+  1. Auto-determine strategy: strategy = (depth >= 3) ? "multi-layer" : "single-layer"
+  2. Try tools in order until success:
+     bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "${strategy}" "." "${tool}")

-CONTEXT SELECTION (automatically handled by script based on strategy):
+CONTEXT SELECTION (automatically handled by script):
 - multi-layer strategy (depth ≥3): @**/* (all files)
 - single-layer strategy (depth 0-2): @*/CLAUDE.md + current code files
-
-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 with layer information
 ```

-### Example Execution
-
-**Layer-based allocation (31 modules total)**:
-```javascript
-// Layer 3: 14 modules (depth ≥3) → 4 agents
-Task(subagent_type="memory-bridge", batch=[mod1, mod2, mod3, mod4])  // Agent 1
-Task(subagent_type="memory-bridge", batch=[mod5, mod6, mod7, mod8])  // Agent 2
-Task(subagent_type="memory-bridge", batch=[mod9, mod10, mod11, mod12])  // Agent 3
-Task(subagent_type="memory-bridge", batch=[mod13, mod14])  // Agent 4
-// All 4 agents run in parallel
-
-// Layer 2: 15 modules (depth 1-2) → 4 agents
-Task(subagent_type="memory-bridge", batch=[mod15, mod16, mod17, mod18])  // Agent 5
-Task(subagent_type="memory-bridge", batch=[mod19, mod20, mod21, mod22])  // Agent 6
-Task(subagent_type="memory-bridge", batch=[mod23, mod24, mod25, mod26])  // Agent 7
-Task(subagent_type="memory-bridge", batch=[mod27, mod28, mod29])  // Agent 8
-// All 4 agents run in parallel
-
-// Layer 1: 2 modules (depth 0) → 1 agent
-Task(subagent_type="memory-bridge", batch=[mod30, mod31])  // Agent 9
-```
-
-**Benefits**:
- 31 modules → 9 agents (71% reduction from sequential)
- Parallel execution within each layer
- Each module gets full fallback chain
- Layer isolation ensures proper dependency order
-
-## Phase 4: Safety Verification
+### Phase 4: Safety Verification

 ```bash
 # Check only CLAUDE.md modified
@@ -465,56 +265,21 @@ bash(git diff --cached --name-only | grep -v "CLAUDE.md" || echo "Only CLAUDE.md
 bash(git status --short)
 ```

-**Aggregate results**:
+**Result Summary**:
 ```
 Update Summary:
  Total: 31 | Success: 29 | Failed: 2
-
-  Tool usage:
-  - gemini: 25 modules
-  - qwen: 4 modules (fallback)
-  - codex: 0 modules
-
-  Failed: FAILED: path1, path2
+  Tool usage: gemini: 25, qwen: 4, codex: 0
+  Failed: path1, path2
 ```

-## Execution Summary
-
-**Module Count Threshold**:
- **<20 modules**: Coordinator executes Phase 3A (Direct Execution)
- **≥20 modules**: Coordinator executes Phase 3B (Agent Batch Execution)
-
-**Agent Hierarchy** (for ≥20 modules):
- **Coordinator**: Handles batch division, spawns worker agents per depth
- **Worker Agents**: Each processes 4 modules with tool fallback
-
 ## Error Handling

-**Batch Worker**:
- Tool fallback per module (auto-retry)
- Batch isolation (failures don't propagate)
- Clear per-module status reporting
+**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

-**Coordinator**:
- Invalid path: Abort with error
- 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  |
-
-## Path Parameter Examples
+## Usage Examples

 ```bash
 # Full project update (auto-strategy selection)
@@ -531,33 +296,8 @@ Update Summary:

 ## Key Advantages

-**Efficiency**: 30 modules → 8 agents (73% reduction)
-**Resilience**: 3-tier fallback per module
-**Performance**: Parallel batches, no concurrency limits
-**Observability**: Per-module tool usage, batch-level metrics
-
-## Coordinator Checklist
-
- Parse `--tool` (default: gemini) and `--path` (default: current dir)
- Git cache + module discovery
- **Smart filter modules** (auto-detect tech stack, skip tests/build/config/docs)
- **Group modules by LAYER** (not depth):
-  - Layer 3: depth ≥3 (auto-select multi-layer strategy)
-  - Layer 2: depth 1-2 (auto-select single-layer strategy)
-  - Layer 1: depth 0 (auto-select single-layer strategy)
- Construct tool fallback order
- **Present filtered plan** with:
-  - Execution strategy (<20: direct, ≥20: agent batch)
-  - Layer groupings with auto-selected strategies
-  - Context strategy per layer
-  - Agent allocation by LAYER
- **Wait for y/n confirmation**
- Determine execution mode:
-  - **<20 modules**: Direct execution (Phase 3A)
-    - For each layer (3→2→1): Parallel module updates within layer (max 4 concurrent) with tool fallback and auto-strategy selection
-  - **≥20 modules**: Agent batch execution (Phase 3B)
-    - For each layer (3→2→1): Batch modules (4 per batch), spawn batch workers in parallel with auto-strategy selection
- Wait for layer completion before moving to next layer
- Aggregate results
- Safety check (only CLAUDE.md modified)
- Display git status + summary with layer statistics
+- **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/workflows/intelligent-tools-strategy.md
+++ b/.claude/workflows/intelligent-tools-strategy.md
@@ -155,11 +155,11 @@ codex --full-auto exec "Write auth tests" resume --last --skip-git-repo-check -s

 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)

 ---

--- 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