Claude-Code-Workflow/.claude/commands/update_dms.md

name: update_dms description: Distributed Memory System management with intelligent classification usage: /update_dms [mode] [target] argument-hint: [full|fast|deep] [path or scope] examples: - /update_dms # Fast mode on current directory - /update_dms full # Complete initialization - /update_dms fast src/api/ # Quick update on specific path - /update_dms deep auth-system # Deep analysis on scope

🚀 Command Overview: /update_dms

• Type: Distributed Memory System (DMS) Management.
• Purpose: Manages a hierarchical CLAUDE.md documentation system using intelligent project classification and agent-based task integration.
• Features: Supports multiple operation modes, automatic complexity detection, and parallel execution for high performance.

⚙️ Processing Modes

• fast (Default)
  • Purpose: Targeted content updates based on current context or a specific path.
  • Scope: Single module or file, no cross-module analysis.
• deep
  • Purpose: Analyze relational impacts and update all associated files across modules.
  • Scope: A specific feature or scope that touches multiple modules (e.g., auth-system).
• full
  • Purpose: Complete, project-wide documentation reconstruction and overhaul.
  • Scope: The entire project, executed via modular, bottom-up task orchestration.

🤔 When to Use Each Mode

• ⚡ Fast Mode: Use for daily development, quick updates, and single-module changes or bug fixes.
• 🔬 Deep Mode: Use for multi-module features, integration work, or complex refactoring with cross-module impacts.
• 🚀 Full Mode: Use for new project setup, major architectural changes, or a comprehensive documentation overhaul.

🔄 Mode-Specific Workflows

• ⚡ Fast Mode Flow Execute 3-step scan -> Identify target scope -> Invoke single agent -> Update specific CLAUDE.md -> Validate & cleanup

• 🔬 Deep Mode Flow Project structure scan -> Impact analysis -> Multi-module detection -> Decide on parallel execution -> Orchestrate agent(s) -> Synchronize updates -> Cross-module validation

• 🚀 Full Mode Flow Project analysis -> Module discovery -> Task decomposition & dependency sorting -> Create parallel batches -> Execute Batch 1 (Base modules) -> ... -> Execute Batch N (Top-level) -> Invoke global summary agent -> Generate root CLAUDE.md

🧠 Parallel Execution Logic

This describes the command's internal logic for selecting an execution strategy. It is handled automatically by /update_dms.

FUNCTION select_execution_strategy(project_structure):
  file_count = analyze_file_count(project_structure)
  module_count = analyze_module_count(project_structure)

  // Based on the 'Parallel Execution Decision Matrix'
  IF file_count < 20:
    RETURN "single_agent_fast_mode"
  ELSE IF file_count >= 20 AND file_count <= 100:
    RETURN "directory_based_parallel" // Use 2-3 agents
  ELSE IF file_count > 100 AND file_count <= 500:
    RETURN "hybrid_parallel" // Use 3-5 agents
  ELSE IF file_count > 500:
    RETURN "dependency_aware_batching" // Use 5+ agents
  END IF
END FUNCTION

FUNCTION orchestrate_full_mode(project_structure):
  // 1. Decompose project into modules and dependencies
  tasks = create_task_list(project_structure) // Corresponds to JSON Task Instructions

  // 2. Group tasks into batches for parallel execution
  batches = create_dependency_batches(tasks)

  // 3. Execute batches sequentially, with parallel agents within each batch
  FOR each batch in batches:
    // This action corresponds to the orchestration script example.
    // e.g., Task(memory-gemini-bridge, "task for module A") &
    execute_batch_in_parallel(batch) 
    wait_for_batch_completion() // Barrier synchronization

  // 4. Final summary step
  // e.g., Task(memory-gemini-bridge, "global_summary task")
  execute_global_summary_task()
END FUNCTION

📂 Distributed Memory System (DMS) Structure

The command assumes and manages a hierarchical CLAUDE.md file structure.

project/
├── CLAUDE.md                   # Project overview and architecture
├── src/                  
│   ├── CLAUDE.md              # Core implementation guidelines
│   ├── components/
│   │   └── CLAUDE.md          # Component-specific patterns
│   └── api/
│       └── CLAUDE.md          # API implementation details
├── tests/
│   └── CLAUDE.md              # Testing guidelines (if needed)
└── docs/
    └── CLAUDE.md              # Documentation standards (if needed)

📜 Documentation Hierarchy Rules

• Root Level (./CLAUDE.md): Focus on project architecture, technology stack, and global standards.
• Module Level (./src/CLAUDE.md): Focus on core implementation guidelines, module responsibilities, and patterns.
• Sub-Module Level (./src/api/CLAUDE.md): Focus on detailed technical specifications and component-specific patterns.

🛠️ Pre-defined Analysis Commands

This 3-step script is used for initial project structure analysis.

# Step 1: Get project directory structure
tree -L 3 -d 2>/dev/null || find . -type d -maxdepth 3

# Step 2: Find existing CLAUDE.md files
find . -name "CLAUDE.md" -o -name "*CLAUDE.md" | sort

# Step 3: Generate context-aware file list (adapts to target scope)
# If target specified: focus on target-related files
# If no target: analyze current context and recent changes
find . -type f \( -name "*.js" -o -name "*.ts" -o -name "*.py" -o -name "*.md" \) | head -50

📝 Task Instructions Format (Full Mode)

In full mode, the orchestrator generates tasks for agents in this JSON format.

{
  "task_type": "module_update" | "global_summary",
  "target_module": "src/api" | "tests" | "root",
  "analysis_commands": [
    "find ./src/api -type f \\( -name '*.js' -o -name '*.ts' \\) | head -30",
    "find ./src/api -name 'CLAUDE.md'"
  ],
  "dependencies": ["src/utils", "src/core"],
  "priority": 1,
  "context": {
    "module_purpose": "API endpoint implementations",
    "existing_files": ["./src/api/CLAUDE.md"],
    "focus_areas": ["implementation patterns", "error handling", "integration points"]
  }
}

🤖 Agent Integration Examples

The /update_dms command orchestrates memory-gemini-bridge agents using tasks formatted like this.

Single Agent (Fast/Deep Mode)

Task:
  description: "Module analysis with Gemini CLI"
  subagent_type: "memory-gemini-bridge"
  prompt: |
    Task Type: module_update
    Target Module: src/api/auth
  
    Analysis Commands:
    1. find ./src/api/auth -type f \( -name "*.js" -o -name "*.ts" \) | head -30
    2. cd src/api/auth && gemini --all-files -p "analyze authentication patterns"
    3. Generate module-level CLAUDE.md for auth subsystem
  
    Context:
    - Module Purpose: Authentication service implementation
    - Focus Areas: ["security patterns", "JWT handling", "middleware integration"]
    - Dependencies: ["src/utils", "src/core"]
  
    Success Criteria: Generate complete module CLAUDE.md with security patterns

Multiple Parallel Agents (Full Mode)

# Agent 1: API Module
Task:
  description: "API Module Analysis"
  subagent_type: "memory-gemini-bridge"
  prompt: |
    Task Type: module_update
    Target Module: src/api
    Parallel Config: { batch_id: 1, partition_id: 1, max_concurrent: 3 }
    Generate: ./src/api/CLAUDE.md
    Sync Point: batch_complete

# Agent 2: Components Module (Parallel)
Task:
  description: "Components Module Analysis"
  subagent_type: "memory-gemini-bridge"
  prompt: |
    Task Type: module_update
    Target Module: src/components
    Parallel Config: { batch_id: 1, partition_id: 2, max_concurrent: 3 }
    Generate: ./src/components/CLAUDE.md
    Sync Point: batch_complete

Global Summary Agent (Full Mode - Final Step)

Task:
  description: "Project Global Summary"
  subagent_type: "memory-gemini-bridge" 
  prompt: |
    Task Type: global_summary
    Wait For: All module updates complete (batch_complete barrier)
  
    Analysis Commands:
    1. find . -name "CLAUDE.md" | grep -E "(src|lib)/" | sort
    2. Read all module CLAUDE.md files
    3. gemini -p "@./src/*/CLAUDE.md synthesize project architecture"
  
    Generate: Root ./CLAUDE.md

🌐 Advanced Parallel Execution Strategies

The command auto-selects the optimal strategy. Below are the patterns it uses.

Strategy 1: Directory-Based Partitioning

• Best For: Well-organized projects with clear module boundaries.
• Example Command: Agent-1: cd src/components && gemini --all-files -p "analyze React components"

Strategy 2: File Reference Partitioning

• Best For: Feature-based or cross-cutting concerns (e.g., authentication).
• Example Command: Agent-1: gemini -p "@src/**/*auth* analyze authentication patterns"

Strategy 3: Hybrid Approach

• Best For: Complex projects with mixed organization patterns.
• Example Command: Mixes directory-based (cd src/components) and pattern-based (@src/**/*{auth,security}*) analysis.

Strategy 4: Dependency-Aware Batching

• Best For: Large enterprise projects with complex interdependencies.
• Example Flow:
  1. Batch 1: Analyze foundation modules (e.g., types, utils). wait
  2. Batch 2: Analyze service modules that depend on Batch 1 (e.g., api, database). wait
  3. Batch 3: Analyze application modules that depend on Batch 2 (e.g., components).

Strategy	Best For	Scaling	Complexity	Performance
Directory-Based	Modular projects	Excellent	Low	High
File Pattern	Feature-focused	Good	Medium	Medium
Hybrid	Mixed structures	Very Good	High	High
Dependency-Aware	Large enterprise	Excellent	Very High	Maximum

🧹 Automatic Content Management

• Cleanup: Removes duplicate content, outdated references, and deprecated patterns across the hierarchy.
• Validation: Ensures content is relevant to the current state of the project.
• Focus:
  • Fast Mode: Quick relevance validation and dead reference removal.
  • Deep Mode: Comprehensive redundancy elimination across affected modules.
  • Full Mode: Complete project-wide cleanup and hierarchy optimization.

⏱️ Performance & Time Investment

• ⚡ Fast Mode: Minutes (Ideal for daily use).
• 🔬 Deep Mode: ~10-30 minutes with parallel execution.
• 🚀 Full Mode: ~30-45 minutes with parallel execution.
• Benefit: Parallel execution provides a massive speedup, offsetting a small coordination overhead.