From 8e4710389de55eb2ffbaa650cdb7146d36135be7 Mon Sep 17 00:00:00 2001 From: catlog22 Date: Sun, 12 Oct 2025 17:07:26 +0800 Subject: [PATCH] refactor: restructure memory update commands to command-style docs Major improvements to /update-memory-full and /update-memory-related: Structure: - Adopt plan.md command-style format with clear phases - Consolidate redundant sections and examples - Add Coordinator Role and Core Rules sections - Include detailed Coordinator Checklist Features: - Add --path parameter to target specific directories - Update Task() call format to function-style syntax - Merge execution examples into workflow phases - Add Path Parameter Reference section Documentation: - Increase parallel job limit from 4 to 5 - Add comprehensive usage examples - Include tool parameter reference - Add comparison tables and best practices Files changed: - .claude/commands/update-memory-full.md: +285/-100 lines - .claude/commands/update-memory-related.md: +229/-136 lines --- .claude/commands/update-memory-full.md | 395 +++++++++++++++------- .claude/commands/update-memory-related.md | 373 +++++++++++++------- 2 files changed, 523 insertions(+), 245 deletions(-) diff --git a/.claude/commands/update-memory-full.md b/.claude/commands/update-memory-full.md index 67de3b0d..b41fe106 100644 --- a/.claude/commands/update-memory-full.md +++ b/.claude/commands/update-memory-full.md @@ -1,174 +1,329 @@ --- name: update-memory-full description: Complete project-wide CLAUDE.md documentation update -argument-hint: "[--tool gemini|qwen|codex]" +argument-hint: "[--tool gemini|qwen|codex] [--path ]" --- -### πŸš€ Command Overview: `/update-memory-full` +# Full Documentation Update (/update-memory-full) -Complete project-wide documentation update using depth-parallel execution. +## 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**: -- **Gemini (default)**: Documentation generation, pattern recognition, architecture review -- **Qwen**: Architecture analysis, system design documentation -- **Codex**: Implementation validation, code quality analysis +- `--tool gemini` (default): Documentation generation, pattern recognition +- `--tool qwen`: Architecture analysis, system design docs +- `--tool codex`: Implementation validation, code quality analysis -### πŸ“ Execution Template +**Path Parameter**: +- `--path ` (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 + +## Execution Workflow + +### Phase 1: Discovery & Analysis + +**Cache git changes:** ```bash -#!/bin/bash -# Complete project-wide CLAUDE.md documentation update - -# Step 1: Parse tool selection (default: gemini) -tool="gemini" -[[ "$*" == *"--tool qwen"* ]] && tool="qwen" -[[ "$*" == *"--tool codex"* ]] && tool="codex" - -# Step 2: Code Index architecture analysis -mcp__code-index__search_code_advanced(pattern="class|function|interface", file_pattern="**/*.{ts,js,py}") -mcp__code-index__find_files(pattern="**/*.{md,json,yaml,yml}") - -# Step 3: Cache git changes -Bash(git add -A 2>/dev/null || true) - -# Step 4: Get and display project structure -modules=$(Bash(~/.claude/scripts/get_modules_by_depth.sh list)) -count=$(echo "$modules" | wc -l) - -# Step 5: Analysis handover β†’ Model takes control -# BASH_EXECUTION_STOPS β†’ MODEL_ANALYSIS_BEGINS - -# Pseudocode flow: -# IF (module_count > 20 OR complex_project_detected): -# β†’ Task "Complex project full update" subagent_type: "memory-bridge" -# ELSE: -# β†’ Present plan and WAIT FOR USER APPROVAL before execution -# -# Pass tool parameter to update_module_claude.sh: "$tool" +bash(git add -A 2>/dev/null || true) ``` -### 🧠 Model Analysis Phase +**Get module structure:** -After the bash script completes the initial analysis, the model takes control to: +*If no --path parameter:* +```bash +bash(~/.claude/scripts/get_modules_by_depth.sh list) +``` -1. **Analyze Complexity**: Review module count and project context -2. **Parse CLAUDE.md Status**: Extract which modules have/need CLAUDE.md files -3. **Choose Strategy**: - - Simple projects: Present execution plan with CLAUDE.md paths to user - - Complex projects: Delegate to memory-bridge agent -4. **Present Detailed Plan**: Show user exactly which CLAUDE.md files will be created/updated -5. **⚠️ CRITICAL: WAIT FOR USER APPROVAL**: No execution without explicit user consent +*If --path parameter specified:* +```bash +bash(cd && ~/.claude/scripts/get_modules_by_depth.sh list) +``` -### πŸ“‹ Execution Strategies +**Example with path:** +```bash +# Update only .claude directory +bash(cd .claude && ~/.claude/scripts/get_modules_by_depth.sh list) -**For Simple Projects (≀20 modules):** +# Update specific feature directory +bash(cd src/features/auth && ~/.claude/scripts/get_modules_by_depth.sh list) +``` -Model will present detailed plan: +**Parse Output**: +- Extract module paths from `depth:N|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|qwen|codex] (from --tool parameter) + Tool: gemini + Total modules: 31 - NEW CLAUDE.md files (X): - - ./src/components/CLAUDE.md - - ./src/services/CLAUDE.md + 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 (Y): + UPDATE existing CLAUDE.md files (1): - ./CLAUDE.md - - ./src/CLAUDE.md - - ./tests/CLAUDE.md - - Total: N CLAUDE.md files will be processed ⚠️ Confirm execution? (y/n) ``` -```pseudo -# ⚠️ MANDATORY: User confirmation β†’ MUST await explicit approval -IF user_explicitly_confirms(): - continue_execution() -ELSE: - abort_execution() +**User Confirmation Required**: No execution without explicit approval -# Step 4: Organize modules by depth β†’ Prepare execution -depth_modules = organize_by_depth(modules) +--- -# Step 5: Execute depth-parallel updates β†’ Process by depth -FOR depth FROM max_depth DOWN TO 0: - FOR each module IN depth_modules[depth]: - WHILE active_jobs >= 4: wait(0.1) - Bash(~/.claude/scripts/update_module_claude.sh "$module" "full" "$tool" &) - wait_all_jobs() +### Phase 3: Depth-Parallel Execution -# Step 6: Safety check and restore staging state -non_claude=$(Bash(git diff --cached --name-only | grep -v "CLAUDE.md" || true)) -if [ -n "$non_claude" ]; then - Bash(git restore --staged .) - echo "⚠️ Warning: Non-CLAUDE.md files were modified, staging reverted" - echo "Modified files: $non_claude" -else - echo "βœ… Only CLAUDE.md files modified, staging preserved" -fi +**Pattern**: Process highest depth first, parallel within depth, sequential across depths. -# Step 7: Display changes β†’ Final status -Bash(git status --short) +**Command structure:** +```bash +bash(cd && ~/.claude/scripts/update_module_claude.sh "." "full" "" &) ``` -**For Complex Projects (>20 modules):** +**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" &) +``` -The model will delegate to the memory-bridge agent with structured context: +*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:|...` 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 && ~/.claude/scripts/update_module_claude.sh "." "full" "" &) +``` + +**Components**: +- `cd ` - Navigate to module (from `path:` field) +- `&&` - Ensure cd succeeds +- `update_module_claude.sh` - Update script +- `"."` - Current directory +- `"full"` - Full update mode +- `""` - 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 "Complex project full update" -subagent_type: "memory-bridge" -prompt: ` +Task( + subagent_type="memory-bridge", + description="Complex project full update", + prompt=` CONTEXT: - Total modules: ${module_count} -- Tool: ${tool} // from --tool parameter, default: gemini +- Tool: ${tool} - Mode: full -- Existing CLAUDE.md: ${existing_count} -- New CLAUDE.md needed: ${new_count} MODULE LIST: -${modules_output} // Full output from get_modules_by_depth.sh list +${modules_output} REQUIREMENTS: -1. Use TodoWrite to track each depth level before execution -2. Process depths 5β†’0 sequentially, max 4 parallel jobs per depth -3. Command format: update_module_claude.sh "" "full" "${tool}" & -4. Extract exact path from "depth:N|path:|..." format -5. Verify all ${module_count} modules are processed -6. Run safety check after completion +1. Use TodoWrite to track each depth level +2. Process depths Nβ†’0 sequentially, max 4 parallel per depth +3. Command: cd "" && update_module_claude.sh "." "full" "${tool}" & +4. Extract path from "depth:N|path:|..." format +5. Verify all modules processed +6. Run safety check 7. Display git status - -Execute depth-parallel updates for all modules. ` +) ``` -**Agent receives complete context:** -- Module count and tool selection -- Full structured module list -- Clear execution requirements -- Path extraction format -- Success criteria +## 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 -### πŸ“š Usage Examples +## 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 -# Complete project documentation refresh -/update-memory-full - -# After major architectural changes -/update-memory-full +/update-memory-full --path .claude ``` +- Updates only .claude directory and subdirectories +- Useful after workflow or command modifications +- Faster than full project update -### ✨ Features +**Update specific feature module:** +```bash +/update-memory-full --path src/features/auth +``` +- Updates authentication feature and sub-modules +- Ideal for feature-specific documentation +- Isolates scope for targeted updates -- **Separated Commands**: Each bash operation is a discrete, trackable step -- **Intelligent Complexity Detection**: Model analyzes project context for optimal strategy -- **Depth-Parallel Execution**: Same depth modules run in parallel, depths run sequentially -- **Git Integration**: Auto-cache changes before, safety check and show status after -- **Safety Protection**: Automatic detection and revert of unintended source code modifications -- **Module Detection**: Uses get_modules_by_depth.sh for structure discovery -- **User Confirmation**: Clear plan presentation with approval step -- **CLAUDE.md Only**: Only updates documentation, never source code \ No newline at end of file +**Update nested structure:** +```bash +/update-memory-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) diff --git a/.claude/commands/update-memory-related.md b/.claude/commands/update-memory-related.md index c1c21ffb..d0aaf8b3 100644 --- a/.claude/commands/update-memory-related.md +++ b/.claude/commands/update-memory-related.md @@ -4,179 +4,302 @@ description: Context-aware CLAUDE.md documentation updates based on recent chang argument-hint: "[--tool gemini|qwen|codex]" --- -### πŸš€ Command Overview: `/update-memory-related` +# Related Documentation Update (/update-memory-related) -Context-aware documentation update for modules affected by recent changes. +## 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**: -- **Gemini (default)**: Documentation generation, pattern recognition, architecture review -- **Qwen**: Architecture analysis, system design documentation -- **Codex**: Implementation validation, code quality analysis +- `--tool gemini` (default): Documentation generation, pattern recognition +- `--tool qwen`: Architecture analysis, system design docs +- `--tool codex`: Implementation validation, code quality analysis +## Core Rules -### πŸ“ Execution Template +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 +## Execution Workflow + +### Phase 1: Change Detection & Analysis + +**Refresh code index:** ```bash -#!/bin/bash -# Context-aware CLAUDE.md documentation update - -# Step 1: Parse tool selection (default: gemini) -tool="gemini" -[[ "$*" == *"--tool qwen"* ]] && tool="qwen" -[[ "$*" == *"--tool codex"* ]] && tool="codex" - -# Step 2: Code Index refresh and architecture analysis -mcp__code-index__refresh_index() -mcp__code-index__search_code_advanced(pattern="class|function|interface", file_pattern="**/*.{ts,js,py}") - -# Step 3: Detect changed modules (before staging) -changed=$(Bash(~/.claude/scripts/detect_changed_modules.sh list)) - -# Step 4: Cache git changes (protect current state) -Bash(git add -A 2>/dev/null || true) - -# Step 5: Use detected changes or fallback -if [ -z "$changed" ]; then - changed=$(Bash(~/.claude/scripts/get_modules_by_depth.sh list | head -10)) -fi -count=$(echo "$changed" | wc -l) - -# Step 6: Analysis handover β†’ Model takes control -# BASH_EXECUTION_STOPS β†’ MODEL_ANALYSIS_BEGINS - -# Pseudocode flow: -# IF (change_count > 15 OR complex_changes_detected): -# β†’ Task "Complex project related update" subagent_type: "memory-bridge" -# ELSE: -# β†’ Present plan and WAIT FOR USER APPROVAL before execution -# -# Pass tool parameter to update_module_claude.sh: "$tool" +bash(mcp__code-index__refresh_index) ``` -### 🧠 Model Analysis Phase +**Detect changed modules:** +```bash +bash(~/.claude/scripts/detect_changed_modules.sh list) +``` -After the bash script completes change detection, the model takes control to: +**Cache git changes:** +```bash +bash(git add -A 2>/dev/null || true) +``` -1. **Analyze Changes**: Review change count and complexity -2. **Parse CLAUDE.md Status**: Extract which changed modules have/need CLAUDE.md files -3. **Choose Strategy**: - - Simple changes: Present execution plan with CLAUDE.md paths to user - - Complex changes: Delegate to memory-bridge agent -4. **Present Detailed Plan**: Show user exactly which CLAUDE.md files will be created/updated for changed modules -5. **⚠️ CRITICAL: WAIT FOR USER APPROVAL**: No execution without explicit user consent +**Parse Output**: +- Extract changed module paths from `depth:N|path:|...` format +- Count affected modules +- Identify which modules have/need CLAUDE.md updates -### πŸ“‹ Execution Strategies +**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 +``` -**For Simple Changes (≀15 modules):** +**Fallback behavior**: +- If no git changes detected, use recent modules (first 10 by depth) -Model will present detailed plan for affected modules: +**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|qwen|codex] (from --tool parameter) + Tool: gemini + Changed modules: 4 - CHANGED modules affecting CLAUDE.md: + NEW CLAUDE.md files (1): + - ./src/api/auth/CLAUDE.md [new module] - NEW CLAUDE.md files (X): - - ./src/api/auth/CLAUDE.md [new module] - - ./src/utils/helpers/CLAUDE.md [new module] - - UPDATE existing CLAUDE.md files (Y): - - ./src/api/CLAUDE.md [parent of changed auth/] - - ./src/CLAUDE.md [root level] - - Total: N CLAUDE.md files will be processed for recent changes + 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) ``` -```pseudo -# ⚠️ MANDATORY: User confirmation β†’ MUST await explicit approval -IF user_explicitly_confirms(): - continue_execution() -ELSE: - abort_execution() +**User Confirmation Required**: No execution without explicit approval -# Step 4: Organize modules by depth β†’ Prepare execution -depth_modules = organize_by_depth(changed_modules) +--- -# Step 5: Execute depth-parallel updates β†’ Process by depth -FOR depth FROM max_depth DOWN TO 0: - FOR each module IN depth_modules[depth]: - WHILE active_jobs >= 4: wait(0.1) - Bash(~/.claude/scripts/update_module_claude.sh "$module" "related" "$tool" &) - wait_all_jobs() +### Phase 3: Depth-Parallel Execution -# Step 6: Safety check and restore staging state -non_claude=$(Bash(git diff --cached --name-only | grep -v "CLAUDE.md" || true)) -if [ -n "$non_claude" ]; then - Bash(git restore --staged .) - echo "⚠️ Warning: Non-CLAUDE.md files were modified, staging reverted" - echo "Modified files: $non_claude" -else - echo "βœ… Only CLAUDE.md files modified, staging preserved" -fi +**Pattern**: Process highest depth first, parallel within depth, sequential across depths. -# Step 7: Display changes β†’ Final status -Bash(git diff --stat) +**Command structure:** +```bash +bash(cd && ~/.claude/scripts/update_module_claude.sh "." "related" "" &) ``` -**For Complex Changes (>15 modules):** +**Example - Depth 3 (new module):** +```bash +bash(cd ./src/api/auth && ~/.claude/scripts/update_module_claude.sh "." "related" "gemini" &) +``` -The model will delegate to the memory-bridge agent with structured context: +*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:|...` 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 && ~/.claude/scripts/update_module_claude.sh "." "related" "" &) +``` + +**Components**: +- `cd ` - Navigate to module (from `path:` field) +- `&&` - Ensure cd succeeds +- `update_module_claude.sh` - Update script +- `"."` - Current directory +- `"related"` - Related mode (context-aware, change-based) +- `""` - 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 "Complex project related update" -subagent_type: "memory-bridge" -prompt: ` +Task( + subagent_type="memory-bridge", + description="Complex project related update", + prompt=` CONTEXT: - Total modules: ${change_count} -- Tool: ${tool} // from --tool parameter, default: gemini +- Tool: ${tool} - Mode: related -- Changed modules detected via: detect_changed_modules.sh -- Existing CLAUDE.md: ${existing_count} -- New CLAUDE.md needed: ${new_count} MODULE LIST: -${changed_modules_output} // Full output from detect_changed_modules.sh list +${changed_modules_output} REQUIREMENTS: -1. Use TodoWrite to track each depth level before execution -2. Process depths sequentially (deepestβ†’shallowest), max 4 parallel jobs per depth -3. Command format: update_module_claude.sh "" "related" "${tool}" & -4. Extract exact path from "depth:N|path:|..." format -5. Verify all ${change_count} modules are processed -6. Run safety check after completion +1. Use TodoWrite to track each depth level +2. Process depths Nβ†’0 sequentially, max 4 parallel per depth +3. Command: cd "" && update_module_claude.sh "." "related" "${tool}" & +4. Extract path from "depth:N|path:|..." format +5. Verify all ${change_count} modules processed +6. Run safety check 7. Display git diff --stat - -Execute depth-parallel updates for changed modules only. ` +) ``` -**Agent receives complete context:** -- Changed module count and tool selection -- Full structured module list (changed only) -- Clear execution requirements with "related" mode -- Path extraction format -- Success criteria +## 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 -### πŸ“š Usage Examples +## 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 +# Daily development update (default: gemini) /update-memory-related -# After feature work -/update-memory-related +# After feature work with specific tool +/update-memory-related --tool qwen + +# Code quality review after implementation +/update-memory-related --tool codex ``` -### ✨ Features +## Tool Parameter Reference -- **Separated Commands**: Each bash operation is a discrete, trackable step -- **Intelligent Change Analysis**: Model analyzes change complexity for optimal strategy -- **Change Detection**: Automatically finds affected modules using git diff -- **Depth-Parallel Execution**: Same depth modules run in parallel, depths run sequentially -- **Git Integration**: Auto-cache changes, show diff statistics after -- **Fallback Mode**: Updates recent files when no git changes found -- **User Confirmation**: Clear plan presentation with approval step -- **CLAUDE.md Only**: Only updates documentation, never source code \ No newline at end of file +**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 |