catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-11 02:33:51 +08:00
Code Issues Packages Projects Releases Wiki Activity

refactor: improve memory update commands with parallel execution and fix file naming

Browse Source 
- 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>
This commit is contained in:
catlog22
2025-10-21 20:28:11 +08:00
parent c640cfefe8
commit de3dc35c5b
7 changed files with 766 additions and 641 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
.claude/commands/memory/docs.md
View File

@@ -129,9 +129,11 @@ EOF
### Phase 2: Analyze Structure ### 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 #### Step 1: Discover and Classify Folders
```bash ```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) 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 ./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 #### Step 2: Extract Top-Level Directories
```bash ```bash
# Group folders by top-level directory # Group folders by top-level directory

388
.claude/commands/memory/update-full.md Normal file
View File

@@ -0,0 +1,388 @@
---
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 (gemini→qwen→codex).
**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
## Core 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 depth, no agent overhead)
- ≥20 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. **Safety Check**: Verify only CLAUDE.md files modified
## 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: 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 (Node.js/Python/Go/Rust/etc).
## Phase 2: Plan Presentation
**Present filtered plan**:
```
Update Plan:
Tool: gemini (fallback: qwen → codex)
Total: 7 modules
Execution: Direct sequential (< 20 modules threshold)
Will update:
- ./core/interfaces (12 files) - depth 2
- ./core (22 files) - depth 1
- ./models (9 files) - depth 1
- ./parametric (6 files) - depth 1
- ./results (7 files) - depth 1
- ./utils (12 files) - depth 1
- . (5 files) - depth 0
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: .
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)
- ./.claude/commands/cli (6 files)
- ./src/utils (8 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:
- Depth 5 (8 modules): 2 agents [4, 4]
- Depth 4 (7 modules): 2 agents [4, 3]
- Depth 3 (6 modules): 2 agents [3, 3]
Estimated time: ~15-25 minutes
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)
**Strategy**: Parallel execution within depth (max 4 concurrent), no agent overhead, tool fallback per module.
```javascript
let modules_by_depth = group_by_depth(module_list);
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 "." "full" "${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
}
}
```
**Example execution (7 modules)**:
```bash
# Depth 2 (1 module)
bash(cd ./core/interfaces && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini")
# → Success with gemini
# Depth 1 (5 modules → 2 batches: [4, 1])
# Batch 1 (4 modules in parallel):
bash(cd ./core && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini") &
bash(cd ./models && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini") &
bash(cd ./parametric && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini") &
bash(cd ./results && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini") &
wait # Wait for batch 1 to complete
# Batch 2 (1 module):
bash(cd ./utils && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini")
# → Success with gemini
# Depth 0 (1 module)
bash(cd . && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini")
# → 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
```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(module_list);
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)
)
);
}
await parallel_execute(worker_tasks); // Batches run in parallel
}
```
### Batch Worker Prompt Template
```
PURPOSE: Update CLAUDE.md for assigned modules with tool fallback
TASK:
Update documentation for the following modules. 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 "." "full" "{{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 "." "full" "{{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 "." "full" "{{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 5 (8 modules → 2 batches)**:
```javascript
Task(subagent_type="memory-bridge", batch=[mod1, mod2, mod3, mod4]) // Agent 1
Task(subagent_type="memory-bridge", batch=[mod5, mod6, mod7, mod8]) // Agent 2
// Both run in parallel
```
**Benefits**:
- 8 modules → 2 agents (75% reduction)
- Parallel batches, sequential within batch
- Each module gets full fallback chain
## 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)
```
**Aggregate results**:
```
Update Summary:
Total: 31 | Success: 29 | Failed: 2
Tool usage:
- gemini: 25 modules
- qwen: 4 modules (fallback)
- codex: 0 modules
Failed: 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
**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
```bash
# Full project update
/memory:update-full
# Target specific directory
/memory:update-full --path .claude
/memory:update-full --path src/features/auth
# Combine with tool selection
/memory:update-full --path .claude --tool qwen
```
## 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)
- Construct tool fallback order
- **Present filtered plan** with execution strategy (<20: direct, ≥20: agent batch)
- **Wait for y/n confirmation**
- Determine execution mode:
- **<20 modules**: Direct execution (Phase 3A)
- For each depth (N→0): Sequential module updates with tool fallback
- **≥20 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 status + summary

330
.claude/commands/memory/update-memory-full.md
View File

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

306
.claude/commands/memory/update-memory-related.md
View File

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

352
.claude/commands/memory/update-related.md Normal file
View File

@@ -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 "." "related" "${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 "." "related" "{{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 "." "related" "{{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 "." "related" "{{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 |

9
.claude/scripts/update_module_claude.sh
View File

@@ -123,10 +123,11 @@ update_module_claude() {
local base_prompt=" local base_prompt="
⚠️ CRITICAL RULES - MUST FOLLOW: ⚠️ CRITICAL RULES - MUST FOLLOW:
1. ONLY modify CLAUDE.md files 1. Target file: ONLY create/update the file named 'CLAUDE.md' in current directory
2. NEVER modify source code files 2. File name: MUST be exactly 'CLAUDE.md' (not ToolSidebar.CLAUDE.md or any variant)
3. Focus exclusively on updating documentation 3. NEVER modify source code files
4. Follow the template guidelines exactly 4. Focus exclusively on updating documentation
5. Follow the template guidelines exactly
$template_content $template_content

12
.claude/workflows/cli-templates/prompts/memory/claude-module-unified.txt
View File

@@ -1,6 +1,12 @@
Create or update CLAUDE.md documentation using unified module/file template. 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 ⚡ ## CORE CHECKLIST ⚡
□ MUST create/update file named exactly 'CLAUDE.md' (not variants)
□ MUST include all 6 sections: Purpose, Structure, Components, Dependencies, Integration, Implementation □ MUST include all 6 sections: Purpose, Structure, Components, Dependencies, Integration, Implementation
□ For code files: Document all public/exported APIs with complete parameter details □ For code files: Document all public/exported APIs with complete parameter details
□ For folders: Reference subdirectory CLAUDE.md files instead of duplicating □ 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 ## 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 ### Template Structure
```markdown ```markdown
# [Module/File Name] # [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 - Update existing CLAUDE.md files rather than creating duplicate sections
## VERIFICATION CHECKLIST ✓ ## 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 6 required sections included (Purpose, Structure, Components, Dependencies, Integration, Implementation)
□ All public/exported APIs documented with complete signatures □ All public/exported APIs documented with complete signatures
□ Parameters documented with types, descriptions, and defaults □ Parameters documented with types, descriptions, and defaults