claude-mpm 4.3.19__py3-none-any.whl → 4.3.22__py3-none-any.whl

claude_mpm/cli/commands/mpm_init_handler.py

@@ -57,6 +57,12 @@ def manage_mpm_init(args):  # noqa: PLR0911
             "verbose": getattr(args, "verbose", False),
             "use_venv": getattr(args, "use_venv", False),
             "ast_analysis": getattr(args, "ast_analysis", True),
+            "update_mode": getattr(args, "update", False),
+            "review_only": getattr(args, "review", False),
+            "organize_files": getattr(args, "organize", False),
+            "preserve_custom": getattr(args, "preserve_custom", True),
+            "skip_archive": getattr(args, "skip_archive", False),
+            "dry_run": getattr(args, "dry_run", False),
         }
 
         # Execute initialization (now synchronous)

claude_mpm/cli/parsers/mpm_init_parser.py

@@ -30,7 +30,10 @@ def add_mpm_init_subparser(subparsers: Any) -> None:
         ),
         epilog=(
             "Examples:\n"
-            "  claude-mpm mpm-init                          # Initialize current directory\n"
+            "  claude-mpm mpm-init                          # Initialize/update current directory\n"
+            "  claude-mpm mpm-init --review                 # Review project state without changes\n"
+            "  claude-mpm mpm-init --update                 # Update existing CLAUDE.md\n"
+            "  claude-mpm mpm-init --organize               # Organize project structure\n"
             "  claude-mpm mpm-init --project-type web       # Initialize as web project\n"
             "  claude-mpm mpm-init --framework react        # Initialize with React framework\n"
             "  claude-mpm mpm-init /path/to/project --force # Force reinitialize project"
@@ -73,6 +76,16 @@ def add_mpm_init_subparser(subparsers: Any) -> None:
         action="store_true",
         help="Force reinitialization even if project is already configured",
     )
+    init_group.add_argument(
+        "--update",
+        action="store_true",
+        help="Update existing CLAUDE.md instead of recreating (smart merge)",
+    )
+    init_group.add_argument(
+        "--review",
+        action="store_true",
+        help="Review project state without making changes (analysis only)",
+    )
     init_group.add_argument(
         "--minimal",
         action="store_true",
@@ -113,6 +126,31 @@ def add_mpm_init_subparser(subparsers: Any) -> None:
         "--list-templates", action="store_true", help="List available project templates"
     )
 
+    # Project organization options
+    org_group = mpm_init_parser.add_argument_group("organization options")
+    org_group.add_argument(
+        "--organize",
+        action="store_true",
+        help="Organize misplaced files into proper directories",
+    )
+    org_group.add_argument(
+        "--preserve-custom/--no-preserve-custom",
+        default=True,
+        dest="preserve_custom",
+        help="Preserve custom sections when updating (default: preserve)",
+    )
+    org_group.add_argument(
+        "--skip-archive",
+        action="store_true",
+        help="Skip archiving existing files before updating",
+    )
+    org_group.add_argument(
+        "--archive-dir",
+        type=str,
+        default="docs/_archive",
+        help="Directory for archiving old documentation (default: docs/_archive)",
+    )
+
     # Output options
     output_group = mpm_init_parser.add_argument_group("output options")
     output_group.add_argument(

claude_mpm/cli/startup_logging.py

@@ -685,11 +685,15 @@ async def trigger_vector_search_indexing(project_root: Optional[Path] = None) ->
             cwd=str(project_root),
         )
 
-        # Don't wait for completion - let it run in the background
+        # Store PID for logging
+        pid = process.pid
         logger.debug(
-            f"MCP Vector Search: Indexing process started (PID: {process.pid})"
+            f"MCP Vector Search: Indexing process started (PID: {pid})"
         )
 
+        # Don't wait for completion - let it run independently in the background
+        # We don't need to track its completion, so we can safely detach
+
     except ImportError:
         logger.debug(
             "MCP config manager not available, skipping vector search indexing"
@@ -718,13 +722,11 @@ def start_vector_search_indexing(project_root: Optional[Path] = None) -> None:
         # Store reference to avoid RUF006 warning
         _ = loop.create_task(trigger_vector_search_indexing(project_root))
     except RuntimeError:
-        # No event loop running, try async approach first
-        try:
-            asyncio.run(trigger_vector_search_indexing(project_root))
-        except Exception as e:
-            # Fallback to simple subprocess approach
-            logger.debug(f"Async indexing failed, trying subprocess: {e}")
-            _start_vector_search_subprocess(project_root)
+        # No event loop running - use subprocess directly to avoid event loop lifecycle issues
+        # The async approach with asyncio.run() creates and closes a loop which causes
+        # warnings when subprocesses are still running
+        logger.debug("No event loop running, using subprocess approach")
+        _start_vector_search_subprocess(project_root)
 
 
 def _start_vector_search_subprocess(project_root: Optional[Path] = None) -> None:

claude_mpm/commands/mpm-init.md

@@ -1,20 +1,24 @@
 # /mpm-init
 
-Initialize your project for optimal use with Claude Code and Claude MPM using the Agentic Coder Optimizer agent.
+Initialize or intelligently update your project for optimal use with Claude Code and Claude MPM using the Agentic Coder Optimizer agent.
 
 ## Usage
 
 ```
-/mpm-init
+/mpm-init                      # Auto-detects and offers update or create
+/mpm-init --review             # Review project state without changes
+/mpm-init --update             # Update existing CLAUDE.md
+/mpm-init --organize           # Organize project structure
+/mpm-init --force              # Force recreate from scratch
 /mpm-init --project-type web --framework react
-/mpm-init --force
-/mpm-init --ast-analysis
-/mpm-init --comprehensive
+/mpm-init --ast-analysis --comprehensive
 ```
 
 ## Description
 
-This command delegates to the Agentic Coder Optimizer agent to establish clear, single-path project standards for documentation, tooling, and workflows. It creates comprehensive documentation optimized for AI agents.
+This command delegates to the Agentic Coder Optimizer agent to establish clear, single-path project standards for documentation, tooling, and workflows.
+
+**Smart Update Mode**: When CLAUDE.md exists, the command automatically offers to update rather than recreate, preserving your custom content while refreshing standard sections. Previous versions are archived in `docs/_archive/` for safety.
 
 ## Features
 
@@ -28,16 +32,37 @@ This command delegates to the Agentic Coder Optimizer agent to establish clear,
 
 ## Options
 
+### Mode Options
+- `--review`: Review project state without making changes
+- `--update`: Update existing CLAUDE.md instead of recreating
+- `--force`: Force reinitialization even if project is already configured
+
+### Configuration Options
 - `--project-type [type]`: Specify project type (web, api, cli, library, etc.)
 - `--framework [name]`: Specify framework (react, vue, django, fastapi, etc.)
-- `--force`: Force reinitialization even if project is already configured
 - `--ast-analysis`: Enable AST analysis for enhanced documentation (default: enabled)
 - `--no-ast-analysis`: Disable AST analysis for faster initialization
 - `--comprehensive`: Create comprehensive setup including CI/CD and deployment
 - `--minimal`: Create minimal configuration (CLAUDE.md only)
 
+### Organization Options
+- `--organize`: Organize misplaced files into proper directories
+- `--preserve-custom`: Preserve custom sections when updating (default)
+- `--no-preserve-custom`: Don't preserve custom sections
+- `--skip-archive`: Skip archiving existing files before updating
+
 ## What This Command Does
 
+### Auto-Detection (NEW)
+When run without flags and CLAUDE.md exists:
+1. Analyzes existing documentation
+2. Shows current status (size, sections, priority markers)
+3. Offers options:
+   - Update (smart merge)
+   - Recreate (fresh start)
+   - Review (analysis only)
+   - Cancel
+
 ### 1. Project Analysis
 - Scans project structure and existing configurations
 - Identifies project type, language, and frameworks
@@ -94,13 +119,39 @@ After all tasks, performs a comprehensive review:
 - Ensures single-path principle
 - Adds meta-instructions for maintenance
 
+### 8. Update Mode Features (NEW)
+When updating existing documentation:
+- **Smart Merging**: Intelligently merges new content with existing
+- **Custom Preservation**: Keeps your project-specific sections
+- **Automatic Archival**: Backs up previous version to `docs/_archive/`
+- **Conflict Resolution**: Removes duplicate or contradictory information
+- **Change Tracking**: Shows what was updated after completion
+
 ## Examples
 
-### Basic Initialization
+### Smart Auto-Detection (Recommended)
 ```bash
 /mpm-init
 ```
-Analyzes current directory and creates optimal setup.
+Analyzes project and offers appropriate action (create/update/review).
+
+### Review Project State
+```bash
+/mpm-init --review
+```
+Analyzes project structure, documentation, and git history without changes.
+
+### Update Existing Documentation
+```bash
+/mpm-init --update
+```
+Updates CLAUDE.md while preserving custom sections.
+
+### Organize Project Structure
+```bash
+/mpm-init --organize --update
+```
+Organizes misplaced files AND updates documentation.
 
 ### Web Project with React
 ```bash
@@ -108,11 +159,11 @@ Analyzes current directory and creates optimal setup.
 ```
 Initializes with web-specific configurations and React patterns.
 
-### Force Reinitialization
+### Force Fresh Start
 ```bash
 /mpm-init --force --comprehensive
 ```
-Overwrites existing configuration with comprehensive setup.
+Overwrites everything with comprehensive setup.
 
 ### Fast Mode (No AST)
 ```bash
@@ -138,16 +189,29 @@ The command delegates to the Agentic Coder Optimizer agent which:
 
 ## Expected Output
 
-After successful execution:
+### For New Projects
 - ✅ **CLAUDE.md**: Main AI agent documentation with priority rankings
+- ✅ **Project structure**: Standard directories created (tmp/, scripts/, docs/)
 - ✅ **Single-path workflows**: Clear commands for all operations
 - ✅ **Tool configurations**: Linting, formatting, testing setup
 - ✅ **Memory system**: Initialized for knowledge retention
 - ✅ **Developer docs**: Technical documentation (with AST analysis)
 - ✅ **Priority organization**: Instructions ranked by importance
 
+### For Existing Projects (Update Mode)
+- ✅ **Updated CLAUDE.md**: Refreshed with latest standards
+- ✅ **Preserved content**: Your custom sections maintained
+- ✅ **Archive created**: Previous version in `docs/_archive/`
+- ✅ **Structure verified**: Missing directories created
+- ✅ **Files organized**: Misplaced files moved (if --organize)
+- ✅ **Change summary**: Report of what was updated
+
 ## Notes
 
+- **Smart Mode**: Automatically detects existing CLAUDE.md and offers update vs recreate
+- **Safe Updates**: Previous versions always archived before updating
+- **Custom Content**: Your project-specific sections are preserved by default
+- **Git Integration**: Analyzes recent commits to understand project evolution
 - The command uses the Agentic Coder Optimizer agent for implementation
 - AST analysis is enabled by default for comprehensive documentation
 - Priority rankings help AI agents focus on critical instructions first

claude_mpm/config/agent_config.py

@@ -14,7 +14,6 @@ This module handles:
 UPDATED: Migrated to use shared ConfigLoader pattern (TSK-0141)
 """
 
-import logging
 import os
 from dataclasses import dataclass, field
 from enum import Enum
@@ -24,7 +23,8 @@ from typing import Any, Dict, List, Optional
 from claude_mpm.core.shared.config_loader import ConfigLoader, ConfigPattern
 from claude_mpm.core.unified_paths import get_path_manager
 
-logger = logging.getLogger(__name__)
+from claude_mpm.core.logging_utils import get_logger
+logger = get_logger(__name__)
 
 
 class AgentPrecedenceMode(Enum):

claude_mpm/config/paths.py

@@ -8,14 +8,14 @@ This module provides a consistent, reliable way to access project paths
 without fragile parent.parent.parent patterns.
 """
 
-import logging
 from pathlib import Path
 from typing import Optional, Union
 
 # Import from the unified path management system
 from ..core.unified_paths import get_path_manager
 
-logger = logging.getLogger(__name__)
+from claude_mpm.core.logging_utils import get_logger
+logger = get_logger(__name__)
 
 
 class ClaudeMPMPaths:

claude_mpm/core/agent_name_normalizer.py

@@ -1,9 +1,9 @@
 """Agent name normalization utilities for consistent naming across the system."""
 
-import logging
 from typing import Optional
 
-logger = logging.getLogger(__name__)
+from claude_mpm.core.logging_utils import get_logger
+logger = get_logger(__name__)
 
 
 class AgentNameNormalizer:

claude_mpm/core/config.py

@@ -18,7 +18,8 @@ from ..utils.config_manager import ConfigurationManager
 from .exceptions import ConfigurationError, FileOperationError
 from .unified_paths import get_path_manager
 
-logger = logging.getLogger(__name__)
+from claude_mpm.core.logging_utils import get_logger
+logger = get_logger(__name__)
 
 
 class Config:

claude_mpm/core/config_aliases.py

@@ -14,13 +14,13 @@ Aliases are stored in ~/.claude-mpm/config_aliases.json
 """
 
 import json
-import logging
 from typing import Dict, List, Optional, Tuple
 
 from ..utils.config_manager import ConfigurationManager
 from .unified_paths import get_path_manager
 
-logger = logging.getLogger(__name__)
+from claude_mpm.core.logging_utils import get_logger
+logger = get_logger(__name__)
 
 
 class ConfigAliasError(Exception):

claude_mpm/core/file_utils.py

@@ -22,6 +22,7 @@ from claude_mpm.core.logging_utils import get_logger
 logger = get_logger(__name__)
 
 
+
 # ==============================================================================
 # PATH UTILITIES
 # ==============================================================================

claude_mpm/core/log_manager.py

@@ -16,7 +16,6 @@ DESIGN DECISIONS:
 
 import asyncio
 import json
-import logging
 import os
 from datetime import datetime, timedelta, timezone
 from pathlib import Path
@@ -27,7 +26,8 @@ from typing import Any, Dict, Optional
 from ..core.config import Config
 from ..core.constants import SystemLimits
 
-logger = logging.getLogger(__name__)
+from claude_mpm.core.logging_utils import get_logger
+logger = get_logger(__name__)
 
 # Import cleanup utility for automatic cleanup
 try:

claude_mpm/core/tool_access_control.py

@@ -1,9 +1,9 @@
 """Tool access control system for managing which tools agents can use."""
 
-import logging
 from typing import Dict, List, Set
 
-logger = logging.getLogger(__name__)
+from claude_mpm.core.logging_utils import get_logger
+logger = get_logger(__name__)
 
 
 class ToolAccessControl:

claude_mpm/core/unified_agent_registry.py

@@ -27,7 +27,6 @@ Architecture:
 
 import contextlib
 import json
-import logging
 import time
 from dataclasses import asdict, dataclass
 from datetime import datetime, timezone
@@ -37,7 +36,8 @@ from typing import Any, Dict, List, Optional, Set, Union
 
 from .unified_paths import get_path_manager
 
-logger = logging.getLogger(__name__)
+from claude_mpm.core.logging_utils import get_logger
+logger = get_logger(__name__)
 
 
 class AgentTier(Enum):

claude_mpm/core/unified_paths.py

@@ -24,7 +24,6 @@ Architecture:
 - Cached properties with smart invalidation
 """
 
-import logging
 import os
 import sys
 from enum import Enum
@@ -32,7 +31,8 @@ from functools import lru_cache
 from pathlib import Path
 from typing import Optional, Union
 
-logger = logging.getLogger(__name__)
+from claude_mpm.core.logging_utils import get_logger
+logger = get_logger(__name__)
 
 
 class PathType(Enum):

claude_mpm/experimental/cli_enhancements.py

@@ -25,11 +25,11 @@ integrate selected features into the main CLI.
 Implements error handling and user guidance patterns from awesome-claude-code.
 """
 
-import logging
 import sys
 
 import click
 
+from claude_mpm.core.logging_utils import get_logger
 from claude_mpm.hooks.validation_hooks import ValidationHooks
 from claude_mpm.utils.error_handler import (
     ErrorContext,
@@ -38,7 +38,7 @@ from claude_mpm.utils.error_handler import (
 )
 from claude_mpm.validation import AgentValidator, ValidationResult
 
-logger = logging.getLogger(__name__)
+logger = get_logger(__name__)
 
 
 class CLIContext:
@@ -53,6 +53,7 @@ class CLIContext:
 
     def setup_logging(self, debug: bool = False) -> None:
         """Setup logging based on debug flag."""
+        import logging
         level = logging.DEBUG if debug else logging.INFO
         format_str = (
             "%(asctime)s - %(name)s - %(levelname)s - %(message)s"

claude_mpm/hooks/base_hook.py

@@ -1,14 +1,14 @@
 """Base hook class and types for claude-mpm hook system."""
 
 import asyncio
-import logging
 from abc import ABC, abstractmethod
 from dataclasses import dataclass
 from datetime import datetime, timezone
 from enum import Enum
 from typing import Any, Dict, Optional
 
-logger = logging.getLogger(__name__)
+from claude_mpm.core.logging_utils import get_logger
+logger = get_logger(__name__)
 
 
 class HookType(Enum):

claude_mpm/hooks/instruction_reinforcement.py

@@ -5,13 +5,13 @@ This hook monitors PM behavior for delegation violations and provides
 escalating warnings when the PM attempts to implement instead of delegate.
 """
 
-import logging
 import re
 from dataclasses import dataclass
 from enum import Enum
 from typing import Dict, List, Optional, Tuple
 
-logger = logging.getLogger(__name__)
+from claude_mpm.core.logging_utils import get_logger
+logger = get_logger(__name__)
 
 
 class ViolationType(Enum):

claude_mpm/hooks/validation_hooks.py

@@ -6,14 +6,14 @@ Validation hooks for claude-mpm operations.
 Inspired by awesome-claude-code's pre-push validation approach.
 """
 
-import logging
 from typing import Any, Callable, Dict, List, Optional
 
 import yaml
 
 from claude_mpm.validation import AgentValidator, ValidationResult
 
-logger = logging.getLogger(__name__)
+from claude_mpm.core.logging_utils import get_logger
+logger = get_logger(__name__)
 
 
 class ValidationHooks:

claude_mpm/scripts/mpm_doctor.py

@@ -14,7 +14,6 @@ DESIGN DECISIONS:
 """
 
 import argparse
-import logging
 import sys
 from pathlib import Path
 from typing import Any, Dict, List, Optional
@@ -52,7 +51,8 @@ def run_diagnostics(
         - warning_count: int - number of warnings found
         - message: str - optional error message if failed
     """
-    logger = logging.getLogger(__name__)
+from claude_mpm.core.logging_utils import get_logger
+logger = get_logger(__name__)
 
     # Create diagnostic runner
     runner = DiagnosticRunner(verbose=verbose, fix=fix)

claude_mpm/services/agents/loading/agent_profile_loader.py

@@ -21,7 +21,6 @@ multi-file implementation for better maintainability.
 
 import asyncio
 import json
-import logging
 import os
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
@@ -37,7 +36,8 @@ from claude_mpm.core.unified_paths import get_path_manager
 from claude_mpm.services.agents.registry import AgentRegistry
 from claude_mpm.services.memory.cache.shared_prompt_cache import SharedPromptCache
 
-logger = logging.getLogger(__name__)
+from claude_mpm.core.logging_utils import get_logger
+logger = get_logger(__name__)
 
 # ============================================================================
 # Data Models

claude_mpm/services/agents/loading/base_agent_manager.py

@@ -7,7 +7,6 @@ Specialized manager for base_agent.md with structured update capabilities.
 Enforces template structure and provides section-specific update methods.
 """
 
-import logging
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from enum import Enum
@@ -18,7 +17,8 @@ from claude_mpm.agents.base_agent_loader import clear_base_agent_cache
 from claude_mpm.services.memory.cache.shared_prompt_cache import SharedPromptCache
 from claude_mpm.services.shared import ConfigServiceBase
 
-logger = logging.getLogger(__name__)
+from claude_mpm.core.logging_utils import get_logger
+logger = get_logger(__name__)
 
 
 class BaseAgentSection(str, Enum):

claude_mpm/services/agents/loading/framework_agent_loader.py

@@ -12,7 +12,6 @@ This service integrates with the main agent_loader.py to provide
 markdown-based agent profiles alongside JSON-based templates.
 """
 
-import logging
 from pathlib import Path
 from typing import Any, Dict, Optional
 
@@ -22,7 +21,8 @@ from claude_mpm.agents.agent_loader import (
 )
 from claude_mpm.core.unified_paths import get_path_manager
 
-logger = logging.getLogger(__name__)
+from claude_mpm.core.logging_utils import get_logger
+logger = get_logger(__name__)
 
 
 class FrameworkAgentLoader:

claude_mpm/services/agents/management/agent_capabilities_generator.py

@@ -4,12 +4,12 @@ This service generates markdown content for agent capabilities section
 from discovered deployed agents.
 """
 
-import logging
 from typing import Any, Dict, List
 
 from jinja2 import Template
 
-logger = logging.getLogger(__name__)
+from claude_mpm.core.logging_utils import get_logger
+logger = get_logger(__name__)
 
 
 class AgentCapabilitiesGenerator:

claude_mpm/services/agents/management/agent_management_service.py

@@ -11,7 +11,6 @@ section extraction/updates, and version management.
 Uses python-frontmatter and mistune for markdown parsing as recommended.
 """
 
-import logging
 import re
 from datetime import datetime, timezone
 from typing import Any, Dict, List, Optional
@@ -33,7 +32,8 @@ from claude_mpm.services.memory.cache.shared_prompt_cache import SharedPromptCac
 
 from ..deployment.agent_versioning import AgentVersionManager
 
-logger = logging.getLogger(__name__)
+from claude_mpm.core.logging_utils import get_logger
+logger = get_logger(__name__)
 
 
 class AgentManager:

claude_mpm/services/agents/memory/memory_categorization_service.py

@@ -1,9 +1,12 @@
 #!/usr/bin/env python3
 """Memory Categorization Service - Categorizes learnings into appropriate sections."""
 
-import logging
 from typing import List
 
+from claude_mpm.core.logging_utils import get_logger
+
+logger = get_logger(__name__)
+
 
 class MemoryCategorizationService:
     """Service for categorizing memory learnings."""
@@ -82,7 +85,7 @@ class MemoryCategorizationService:
 
     def __init__(self):
         """Initialize the categorization service."""
-        self.logger = logging.getLogger(__name__)
+        pass
 
     def categorize_learning(self, learning: str) -> str:
         """Categorize a learning item based on its content.