mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-05 01:50:27 +08:00
refactor: improve memory update commands with parallel execution and fix file naming
- Renamed update-memory-full.md -> update-full.md for consistency - Renamed update-memory-related.md -> update-related.md for consistency - Added parallel execution support (max 4 concurrent) for both direct and agent modes - Fixed execution strategy: <20 modules direct parallel, ≥20 modules agent batch - Removed misleading "orchestrator agent" section that caused hierarchy confusion - Clarified coordinator always executes, agents only for batching ≥20 modules - Added explicit file naming rules to prevent ToolSidebar.CLAUDE.md errors - Updated template and script with CRITICAL file naming constraints - Removed all emoji symbols from documentation for clean text format - Added smart filtering strategy to docs.md for auto-skip patterns Key improvements: - Phase 3A: Direct parallel execution (max 4 concurrent per depth) - Phase 3B: Agent batch execution (4 modules/agent) - Both modes use same batching strategy, differ only in agent layer - Explicit CLAUDE.md file naming in 3 locations (script, template, checklist) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
catlog22
@@ -129,9 +129,11 @@ EOF
|
||||
|
||||
### Phase 2: Analyze Structure
|
||||
|
||||
**Smart filter**: Auto-detect and skip tests/build/config/vendor based on project tech stack (Node.js/Python/Go/Rust/etc).
|
||||
|
||||
#### Step 1: Discover and Classify Folders
|
||||
```bash
|
||||
# Run analysis pipeline (module discovery + folder classification)
|
||||
# Run analysis pipeline (module discovery + folder classification + smart filtering)
|
||||
bash(~/.claude/scripts/get_modules_by_depth.sh | ~/.claude/scripts/classify-folders.sh > .workflow/WFS-docs-20240120/.process/folder-analysis.txt)
|
||||
```
|
||||
|
||||
@@ -142,6 +144,12 @@ bash(~/.claude/scripts/get_modules_by_depth.sh | ~/.claude/scripts/classify-fold
|
||||
./src/utils|navigation|code:0|dirs:4
|
||||
```
|
||||
|
||||
**Auto-skipped**:
|
||||
- Tests: `**/test/**`, `**/*.test.*`, `**/__tests__/**`
|
||||
- Build: `**/node_modules/**`, `**/dist/**`, `**/build/**`
|
||||
- Config: Root-level config files (package.json, tsconfig.json, etc)
|
||||
- Vendor: Language-specific dependency directories
|
||||
|
||||
#### Step 2: Extract Top-Level Directories
|
||||
```bash
|
||||
# Group folders by top-level directory
|
||||
|
||||
388
.claude/commands/memory/update-full.md
Normal file
388
.claude/commands/memory/update-full.md
Normal 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
|
||||
@@ -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)
|
||||
@@ -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
352
.claude/commands/memory/update-related.md
Normal 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 |
|
||||
@@ -123,10 +123,11 @@ update_module_claude() {
|
||||
|
||||
local base_prompt="
|
||||
⚠️ CRITICAL RULES - MUST FOLLOW:
|
||||
1. ONLY modify CLAUDE.md files
|
||||
2. NEVER modify source code files
|
||||
3. Focus exclusively on updating documentation
|
||||
4. Follow the template guidelines exactly
|
||||
1. Target file: ONLY create/update the file named 'CLAUDE.md' in current directory
|
||||
2. File name: MUST be exactly 'CLAUDE.md' (not ToolSidebar.CLAUDE.md or any variant)
|
||||
3. NEVER modify source code files
|
||||
4. Focus exclusively on updating documentation
|
||||
5. Follow the template guidelines exactly
|
||||
|
||||
$template_content
|
||||
|
||||
|
||||
@@ -1,6 +1,12 @@
|
||||
Create or update CLAUDE.md documentation using unified module/file template.
|
||||
|
||||
## ⚠️ FILE NAMING RULE (CRITICAL)
|
||||
- Target file: MUST be named exactly `CLAUDE.md` in the current directory
|
||||
- NEVER create files like `ToolSidebar.CLAUDE.md` or `[filename].CLAUDE.md`
|
||||
- ALWAYS use the fixed name: `CLAUDE.md`
|
||||
|
||||
## CORE CHECKLIST ⚡
|
||||
□ MUST create/update file named exactly 'CLAUDE.md' (not variants)
|
||||
□ MUST include all 6 sections: Purpose, Structure, Components, Dependencies, Integration, Implementation
|
||||
□ For code files: Document all public/exported APIs with complete parameter details
|
||||
□ For folders: Reference subdirectory CLAUDE.md files instead of duplicating
|
||||
@@ -64,6 +70,11 @@ Create or update CLAUDE.md documentation using unified module/file template.
|
||||
|
||||
## OUTPUT REQUIREMENTS
|
||||
|
||||
### File Naming (CRITICAL)
|
||||
- **Output file**: MUST be named exactly `CLAUDE.md` in the current directory
|
||||
- **Examples of WRONG naming**: `ToolSidebar.CLAUDE.md`, `index.CLAUDE.md`, `utils.CLAUDE.md`
|
||||
- **Correct naming**: `CLAUDE.md` (always, for all directories)
|
||||
|
||||
### Template Structure
|
||||
```markdown
|
||||
# [Module/File Name]
|
||||
@@ -143,6 +154,7 @@ Create or update CLAUDE.md documentation using unified module/file template.
|
||||
- Update existing CLAUDE.md files rather than creating duplicate sections
|
||||
|
||||
## VERIFICATION CHECKLIST ✓
|
||||
□ Output file is named exactly 'CLAUDE.md' (not [filename].CLAUDE.md)
|
||||
□ All 6 required sections included (Purpose, Structure, Components, Dependencies, Integration, Implementation)
|
||||
□ All public/exported APIs documented with complete signatures
|
||||
□ Parameters documented with types, descriptions, and defaults
|
||||
|
||||
Reference in New Issue
Block a user