claude-mpm 5.0.2__py3-none-any.whl → 5.1.9__py3-none-any.whl

claude_mpm/config/skill_presets.py

@@ -0,0 +1,392 @@
+"""Skill preset configurations for common development scenarios.
+
+This module defines preset bundles of skills for typical development workflows.
+Presets enable users to deploy entire skill stacks with a single command like:
+    claude-mpm skills deploy --preset python-min
+    claude-mpm skills deploy --preset python-max
+
+Design Decision: Presets use skill IDs from skill manifest format.
+
+Architecture:
+- MIN presets: Essential skills only (faster startup, lower resource usage)
+- MAX presets: Full skill toolkit with specialized capabilities (comprehensive coverage)
+- All presets include: skill-creator for extending capabilities
+
+Trade-offs:
+- Simplicity: Static lists are easy to maintain
+- Flexibility: Dynamic functions allow auto-detection (future enhancement)
+- Discoverability: Presets shown in CLI help and error messages
+"""
+
+from typing import Any, Callable, Dict, List, Union
+
+# Type for preset resolver (can be static list or dynamic function)
+PresetResolver = Union[List[str], Callable[[], List[str]]]
+
+# Core skills included in ALL presets (MIN and MAX)
+CORE_SKILLS = [
+    "universal-main-skill-creator",  # Skill creation and management
+]
+
+PRESETS: Dict[str, Dict[str, Any]] = {
+    # ========================================
+    # Universal Minimal Preset
+    # ========================================
+    "minimal": {
+        "description": "Core skills only - universal starter kit",
+        "skills": CORE_SKILLS,
+        "use_cases": ["Any project type", "Quick start", "Learning"],
+    },
+    # ========================================
+    # Python Toolchain Presets
+    # ========================================
+    "python-min": {
+        "description": "Python essentials (4 skills)",
+        "skills": CORE_SKILLS
+        + [
+            "toolchains-python-testing-pytest",
+            "toolchains-python-async-asyncio",
+            "toolchains-python-tooling-mypy",
+        ],
+        "use_cases": [
+            "Python scripts",
+            "Small Python projects",
+            "FastAPI microservices",
+        ],
+    },
+    "python-max": {
+        "description": "Full Python skill stack (8+ skills)",
+        "skills": CORE_SKILLS
+        + [
+            "toolchains-python-frameworks-flask",
+            "toolchains-python-testing-pytest",
+            "toolchains-python-async-asyncio",
+            "toolchains-python-tooling-mypy",
+            "universal-testing-testing-anti-patterns",
+            "universal-testing-condition-based-waiting",
+            "universal-debugging-verification-before-completion",
+        ],
+        "use_cases": ["FastAPI production", "Django projects", "Python APIs at scale"],
+    },
+    # ========================================
+    # JavaScript/TypeScript Toolchain Presets
+    # ========================================
+    "javascript-min": {
+        "description": "Node.js essentials (3 skills)",
+        "skills": CORE_SKILLS
+        + [
+            "toolchains-javascript-frameworks-react",
+            "toolchains-javascript-tooling-biome",
+        ],
+        "use_cases": ["Express.js", "Node.js scripts", "Backend microservices"],
+    },
+    "javascript-max": {
+        "description": "Full Node.js skill stack (7+ skills)",
+        "skills": CORE_SKILLS
+        + [
+            "toolchains-javascript-frameworks-react",
+            "toolchains-javascript-frameworks-vue",
+            "toolchains-javascript-tooling-biome",
+            "toolchains-typescript-testing-vitest",
+            "toolchains-typescript-testing-jest",
+            "universal-testing-testing-anti-patterns",
+        ],
+        "use_cases": ["Express.js production", "Fastify", "Koa", "Enterprise Node.js"],
+    },
+    # ========================================
+    # React Toolchain Presets
+    # ========================================
+    "react-min": {
+        "description": "React essentials (3 skills)",
+        "skills": CORE_SKILLS
+        + [
+            "toolchains-javascript-frameworks-react",
+            "toolchains-typescript-core",
+        ],
+        "use_cases": ["React SPAs", "Component libraries", "Quick prototypes"],
+    },
+    "react-max": {
+        "description": "Full React skill stack (8+ skills)",
+        "skills": CORE_SKILLS
+        + [
+            "toolchains-javascript-frameworks-react",
+            "toolchains-javascript-frameworks-react-state-machine",
+            "toolchains-typescript-core",
+            "toolchains-typescript-testing-vitest",
+            "toolchains-ui-components-headlessui",
+            "universal-testing-testing-anti-patterns",
+            "universal-architecture-software-patterns",
+        ],
+        "use_cases": [
+            "React production apps",
+            "Component systems",
+            "Frontend at scale",
+        ],
+    },
+    # ========================================
+    # Next.js Toolchain Presets
+    # ========================================
+    "nextjs-min": {
+        "description": "Next.js essentials (4 skills)",
+        "skills": CORE_SKILLS
+        + [
+            "toolchains-nextjs-core",
+            "toolchains-javascript-frameworks-react",
+            "toolchains-typescript-core",
+        ],
+        "use_cases": ["Next.js apps", "Vercel deployment", "Full-stack TypeScript"],
+    },
+    "nextjs-max": {
+        "description": "Full Next.js skill stack (10+ skills)",
+        "skills": CORE_SKILLS
+        + [
+            "toolchains-nextjs-core",
+            "toolchains-nextjs-v16",
+            "toolchains-javascript-frameworks-react",
+            "toolchains-javascript-frameworks-react-state-machine",
+            "toolchains-typescript-core",
+            "toolchains-typescript-data-prisma",
+            "toolchains-typescript-data-drizzle",
+            "toolchains-typescript-testing-vitest",
+            "universal-architecture-software-patterns",
+        ],
+        "use_cases": ["Next.js production", "Enterprise apps", "Full-stack at scale"],
+    },
+    # ========================================
+    # TypeScript/Data Toolchain Presets
+    # ========================================
+    "typescript-min": {
+        "description": "TypeScript essentials (3 skills)",
+        "skills": CORE_SKILLS
+        + [
+            "toolchains-typescript-core",
+            "toolchains-typescript-testing-vitest",
+        ],
+        "use_cases": ["Type-safe apps", "TypeScript projects", "Node.js with types"],
+    },
+    "typescript-max": {
+        "description": "Full TypeScript skill stack (8+ skills)",
+        "skills": CORE_SKILLS
+        + [
+            "toolchains-typescript-core",
+            "toolchains-typescript-testing-vitest",
+            "toolchains-typescript-testing-jest",
+            "toolchains-typescript-data-prisma",
+            "toolchains-typescript-data-drizzle",
+            "toolchains-typescript-data-kysely",
+            "universal-architecture-software-patterns",
+        ],
+        "use_cases": ["Enterprise TypeScript", "Full-stack apps", "Type-safe APIs"],
+    },
+    # ========================================
+    # Rust Toolchain Presets
+    # ========================================
+    "rust-min": {
+        "description": "Rust essentials (2 skills)",
+        "skills": CORE_SKILLS
+        + [
+            "toolchains-rust-desktop-applications",
+        ],
+        "use_cases": ["Rust CLI tools", "Systems programming", "WebAssembly"],
+    },
+    "rust-max": {
+        "description": "Full Rust skill stack (4+ skills)",
+        "skills": CORE_SKILLS
+        + [
+            "toolchains-rust-desktop-applications",
+            "toolchains-rust-frameworks-tauri",
+            "universal-architecture-software-patterns",
+        ],
+        "use_cases": [
+            "Rust production systems",
+            "Performance-critical apps",
+            "Safe systems",
+        ],
+    },
+    # ========================================
+    # WordPress Toolchain Presets
+    # ========================================
+    "wordpress-min": {
+        "description": "WordPress essentials (2 skills)",
+        "skills": CORE_SKILLS
+        + [
+            "toolchains-php-frameworks-wordpress-plugin-fundamentals",
+        ],
+        "use_cases": [
+            "WordPress plugins",
+            "Theme customization",
+            "Quick WordPress dev",
+        ],
+    },
+    "wordpress-max": {
+        "description": "Full WordPress skill stack (3+ skills)",
+        "skills": CORE_SKILLS
+        + [
+            "toolchains-php-frameworks-wordpress-plugin-fundamentals",
+            "toolchains-php-frameworks-wordpress-block-editor",
+            "toolchains-php-frameworks-espocrm",
+        ],
+        "use_cases": ["WordPress production", "Block themes", "Custom blocks", "FSE"],
+    },
+    # ========================================
+    # AI/MCP Toolchain Presets
+    # ========================================
+    "ai-min": {
+        "description": "AI essentials (2 skills)",
+        "skills": CORE_SKILLS
+        + [
+            "toolchains-ai-protocols-mcp",
+        ],
+        "use_cases": ["MCP servers", "Claude integrations", "AI tools"],
+    },
+    "ai-max": {
+        "description": "Full AI skill stack (3+ skills)",
+        "skills": CORE_SKILLS
+        + [
+            "toolchains-ai-protocols-mcp",
+            "toolchains-ai-services-openrouter",
+            "universal-main-artifacts-builder",
+        ],
+        "use_cases": ["Multi-model AI apps", "Claude Desktop extensions", "AI tooling"],
+    },
+    # ========================================
+    # Svelte Toolchain Presets
+    # ========================================
+    "svelte-min": {
+        "description": "Svelte essentials (2 skills)",
+        "skills": CORE_SKILLS
+        + [
+            "toolchains-javascript-frameworks-svelte",
+        ],
+        "use_cases": ["Svelte apps", "Reactive UIs", "Minimal JavaScript"],
+    },
+    "svelte-max": {
+        "description": "Full Svelte skill stack (3+ skills)",
+        "skills": CORE_SKILLS
+        + [
+            "toolchains-javascript-frameworks-svelte",
+            "toolchains-javascript-frameworks-sveltekit",
+            "toolchains-typescript-core",
+        ],
+        "use_cases": ["SvelteKit production", "Full-stack Svelte", "SSR/SSG apps"],
+    },
+    # ========================================
+    # Universal/Testing Toolchain Presets
+    # ========================================
+    "testing-min": {
+        "description": "Testing essentials (3 skills)",
+        "skills": CORE_SKILLS
+        + [
+            "universal-testing-testing-anti-patterns",
+            "universal-testing-condition-based-waiting",
+        ],
+        "use_cases": ["Test quality", "Async testing", "Test improvement"],
+    },
+    "testing-max": {
+        "description": "Full testing skill stack (6+ skills)",
+        "skills": CORE_SKILLS
+        + [
+            "universal-testing-testing-anti-patterns",
+            "universal-testing-condition-based-waiting",
+            "universal-debugging-verification-before-completion",
+            "toolchains-typescript-testing-vitest",
+            "toolchains-typescript-testing-jest",
+            "toolchains-python-testing-pytest",
+        ],
+        "use_cases": ["Comprehensive testing", "Test automation", "Quality assurance"],
+    },
+    # ========================================
+    # Collaboration Toolchain Presets
+    # ========================================
+    "collaboration-min": {
+        "description": "Collaboration essentials (2 skills)",
+        "skills": CORE_SKILLS
+        + [
+            "universal-collaboration-brainstorming",
+        ],
+        "use_cases": ["Idea refinement", "Design thinking", "Feature planning"],
+    },
+    "collaboration-max": {
+        "description": "Full collaboration skill stack (4+ skills)",
+        "skills": CORE_SKILLS
+        + [
+            "universal-collaboration-brainstorming",
+            "universal-collaboration-writing-plans",
+            "universal-collaboration-requesting-code-review",
+            "universal-collaboration-dispatching-parallel-agents",
+        ],
+        "use_cases": ["Team coordination", "Code reviews", "Planning", "Parallel work"],
+    },
+}
+
+
+def get_preset_names() -> List[str]:
+    """Get list of all available preset names.
+
+    Returns:
+        List of preset names (e.g., ['minimal', 'python-min', 'python-max', ...])
+
+    Example:
+        >>> names = get_preset_names()
+        >>> 'python-min' in names
+        True
+    """
+    return list(PRESETS.keys())
+
+
+def get_preset_info(preset_name: str) -> Dict[str, Any]:
+    """Get preset metadata (description, use cases, skill count).
+
+    Args:
+        preset_name: Name of preset (e.g., 'python-min')
+
+    Returns:
+        Dict with keys:
+        - name: Preset name
+        - description: Human-readable description
+        - skill_count: Number of skills in preset
+        - use_cases: List of use case strings
+
+    Raises:
+        ValueError: If preset name is invalid
+
+    Example:
+        >>> info = get_preset_info('python-min')
+        >>> info['skill_count']
+        4
+    """
+    if preset_name not in PRESETS:
+        raise ValueError(f"Unknown preset: {preset_name}")
+
+    preset = PRESETS[preset_name]
+    return {
+        "name": preset_name,
+        "description": preset["description"],
+        "skill_count": len(preset["skills"]),
+        "use_cases": preset["use_cases"],
+    }
+
+
+def get_preset_skills(preset_name: str) -> List[str]:
+    """Get skill list for preset.
+
+    Args:
+        preset_name: Name of preset (e.g., 'python-min')
+
+    Returns:
+        List of skill IDs (e.g., ["universal-main-skill-creator", ...])
+
+    Raises:
+        ValueError: If preset name is invalid
+
+    Example:
+        >>> skills = get_preset_skills('python-min')
+        >>> len(skills)
+        4
+        >>> 'universal-main-skill-creator' in skills
+        True
+    """
+    if preset_name not in PRESETS:
+        raise ValueError(f"Unknown preset: {preset_name}")
+
+    return PRESETS[preset_name]["skills"]

claude_mpm/constants.py

@@ -168,6 +168,7 @@ class SkillsCommands(str, Enum):
     UPDATE = "update"
     INFO = "info"
     CONFIG = "config"
+    CONFIGURE = "configure"  # Interactive skills selection (like agents configure)
     # GitHub deployment commands
     DEPLOY_FROM_GITHUB = "deploy-github"
     LIST_AVAILABLE = "list-available"

claude_mpm/core/claude_runner.py

@@ -802,31 +802,8 @@ Use these agents to delegate specialized work via the Task tool.
             raise RuntimeError("Subprocess launcher service not available")
 
 
-def create_simple_context() -> str:
-    """Create basic context for Claude."""
-    return """You are Claude Code running in Claude MPM (Multi-Agent Project Manager).
-
-You have access to native subagents via the Task tool with subagent_type parameter:
-- engineer: For coding, implementation, and technical tasks
-- qa: For testing, validation, and quality assurance
-- documentation: For docs, guides, and explanations
-- research: For investigation and analysis
-- security: For security-related tasks
-- ops: For deployment and infrastructure
-- version-control: For git and version management
-- data-engineer: For data processing and APIs
-
-Use these agents by calling: Task(description="task description", subagent_type="agent_name")
-
-IMPORTANT: The Task tool accepts both naming formats:
-- Capitalized format: "Research", "Engineer", "QA", "Version Control", "Data Engineer"
-- Lowercase format: "research", "engineer", "qa", "version-control", "data-engineer"
-
-Both formats work correctly. When you see capitalized names (matching TodoWrite prefixes),
-automatically normalize them to lowercase-hyphenated format for the Task tool.
-
-Work efficiently and delegate appropriately to subagents when needed."""
-
+# Moved to claude_mpm.core.system_context to avoid circular imports
+from claude_mpm.core.system_context import create_simple_context
 
 # Backward compatibility alias
 SimpleClaudeRunner = ClaudeRunner

claude_mpm/core/framework/loaders/file_loader.py

@@ -66,6 +66,53 @@ class FileLoader:
             if "INSTRUCTIONS.md" in str(file_path):
                 self.framework_last_modified = timestamp
 
+    def _load_tier_file(
+        self,
+        filename: str,
+        current_dir: Path,
+        framework_path: Optional[Path] = None,
+        include_system: bool = False,
+    ) -> tuple[Optional[str], Optional[str]]:
+        """Load file with tier precedence: project → user → system.
+
+        Args:
+            filename: Name of file to load (e.g., "INSTRUCTIONS.md")
+            current_dir: Current working directory for project-level
+            framework_path: Path to framework installation for system-level
+            include_system: Whether to check system-level path
+
+        Returns:
+            Tuple of (content, level) where level is 'project', 'user', 'system', or None
+        """
+        # Check project-level (highest priority)
+        project_path = current_dir / ".claude-mpm" / filename
+        if project_path.exists():
+            loaded_content = self.try_load_file(
+                project_path, f"project-specific {filename}"
+            )
+            if loaded_content:
+                self.logger.info(f"Using project-specific {filename} from .claude-mpm/")
+                return loaded_content, "project"
+
+        # Check user-level (medium priority)
+        user_path = Path.home() / ".claude-mpm" / filename
+        if user_path.exists():
+            loaded_content = self.try_load_file(user_path, f"user-specific {filename}")
+            if loaded_content:
+                self.logger.info(f"Using user-specific {filename} from ~/.claude-mpm/")
+                return loaded_content, "user"
+
+        # Check system-level (lowest priority)
+        if include_system and framework_path and framework_path != Path("__PACKAGED__"):
+            system_path = framework_path / "src" / "claude_mpm" / "agents" / filename
+            if system_path.exists():
+                loaded_content = self.try_load_file(system_path, f"system {filename}")
+                if loaded_content:
+                    self.logger.info(f"Using system {filename}")
+                    return loaded_content, "system"
+
+        return None, None
+
     def load_instructions_file(
         self, current_dir: Path
     ) -> tuple[Optional[str], Optional[str]]:
@@ -82,31 +129,7 @@ class FileLoader:
         Returns:
             Tuple of (content, level) where level is 'project', 'user', or None
         """
-        # Check for project-specific INSTRUCTIONS.md first
-        project_instructions_path = current_dir / ".claude-mpm" / "INSTRUCTIONS.md"
-        if project_instructions_path.exists():
-            loaded_content = self.try_load_file(
-                project_instructions_path, "project-specific INSTRUCTIONS.md"
-            )
-            if loaded_content:
-                self.logger.info(
-                    "Using project-specific PM instructions from .claude-mpm/INSTRUCTIONS.md"
-                )
-                return loaded_content, "project"
-
-        # Check for user-specific INSTRUCTIONS.md
-        user_instructions_path = Path.home() / ".claude-mpm" / "INSTRUCTIONS.md"
-        if user_instructions_path.exists():
-            loaded_content = self.try_load_file(
-                user_instructions_path, "user-specific INSTRUCTIONS.md"
-            )
-            if loaded_content:
-                self.logger.info(
-                    "Using user-specific PM instructions from ~/.claude-mpm/INSTRUCTIONS.md"
-                )
-                return loaded_content, "user"
-
-        return None, None
+        return self._load_tier_file("INSTRUCTIONS.md", current_dir)
 
     def load_workflow_file(
         self, current_dir: Path, framework_path: Path
@@ -126,44 +149,9 @@ class FileLoader:
         Returns:
             Tuple of (content, level) where level is 'project', 'user', 'system', or None
         """
-        # Check for project-specific WORKFLOW.md first (highest priority)
-        project_workflow_path = current_dir / ".claude-mpm" / "WORKFLOW.md"
-        if project_workflow_path.exists():
-            loaded_content = self.try_load_file(
-                project_workflow_path, "project-specific WORKFLOW.md"
-            )
-            if loaded_content:
-                self.logger.info(
-                    "Using project-specific workflow instructions from .claude-mpm/WORKFLOW.md"
-                )
-                return loaded_content, "project"
-
-        # Check for user-specific WORKFLOW.md (medium priority)
-        user_workflow_path = Path.home() / ".claude-mpm" / "WORKFLOW.md"
-        if user_workflow_path.exists():
-            loaded_content = self.try_load_file(
-                user_workflow_path, "user-specific WORKFLOW.md"
-            )
-            if loaded_content:
-                self.logger.info(
-                    "Using user-specific workflow instructions from ~/.claude-mpm/WORKFLOW.md"
-                )
-                return loaded_content, "user"
-
-        # Fall back to system workflow (lowest priority)
-        if framework_path and framework_path != Path("__PACKAGED__"):
-            system_workflow_path = (
-                framework_path / "src" / "claude_mpm" / "agents" / "WORKFLOW.md"
-            )
-            if system_workflow_path.exists():
-                loaded_content = self.try_load_file(
-                    system_workflow_path, "system WORKFLOW.md"
-                )
-                if loaded_content:
-                    self.logger.info("Using system workflow instructions")
-                    return loaded_content, "system"
-
-        return None, None
+        return self._load_tier_file(
+            "WORKFLOW.md", current_dir, framework_path, include_system=True
+        )
 
     def load_memory_file(
         self, current_dir: Path, framework_path: Path
@@ -183,41 +171,6 @@ class FileLoader:
         Returns:
             Tuple of (content, level) where level is 'project', 'user', 'system', or None
         """
-        # Check for project-specific MEMORY.md first (highest priority)
-        project_memory_path = current_dir / ".claude-mpm" / "MEMORY.md"
-        if project_memory_path.exists():
-            loaded_content = self.try_load_file(
-                project_memory_path, "project-specific MEMORY.md"
-            )
-            if loaded_content:
-                self.logger.info(
-                    "Using project-specific memory instructions from .claude-mpm/MEMORY.md"
-                )
-                return loaded_content, "project"
-
-        # Check for user-specific MEMORY.md (medium priority)
-        user_memory_path = Path.home() / ".claude-mpm" / "MEMORY.md"
-        if user_memory_path.exists():
-            loaded_content = self.try_load_file(
-                user_memory_path, "user-specific MEMORY.md"
-            )
-            if loaded_content:
-                self.logger.info(
-                    "Using user-specific memory instructions from ~/.claude-mpm/MEMORY.md"
-                )
-                return loaded_content, "user"
-
-        # Fall back to system memory instructions (lowest priority)
-        if framework_path and framework_path != Path("__PACKAGED__"):
-            system_memory_path = (
-                framework_path / "src" / "claude_mpm" / "agents" / "MEMORY.md"
-            )
-            if system_memory_path.exists():
-                loaded_content = self.try_load_file(
-                    system_memory_path, "system MEMORY.md"
-                )
-                if loaded_content:
-                    self.logger.info("Using system memory instructions")
-                    return loaded_content, "system"
-
-        return None, None
+        return self._load_tier_file(
+            "MEMORY.md", current_dir, framework_path, include_system=True
+        )

claude_mpm/core/interactive_session.py

@@ -2,6 +2,12 @@
 
 This module provides the InteractiveSession class that manages Claude's interactive mode
 with proper separation of concerns and reduced complexity.
+
+DEPENDENCY INJECTION:
+This module uses protocol-based dependency injection to break circular imports.
+Instead of importing ClaudeRunner directly, it uses ClaudeRunnerProtocol which
+defines the interface it needs. This allows ClaudeRunner to create instances
+of InteractiveSession without circular dependency issues.
 """
 
 import contextlib
@@ -9,11 +15,18 @@ import os
 import subprocess
 import uuid
 from pathlib import Path
-from typing import Any, Dict, Optional, Tuple
+from typing import TYPE_CHECKING, Any, Dict, Optional, Tuple
 
 from claude_mpm.core.enums import ServiceState
 from claude_mpm.core.logger import get_logger
 
+# Protocol imports for type checking without circular dependencies
+if TYPE_CHECKING:
+    from claude_mpm.core.protocols import ClaudeRunnerProtocol
+else:
+    # At runtime, accept any object with matching interface
+    ClaudeRunnerProtocol = Any
+
 
 class InteractiveSession:
     """
@@ -28,13 +41,14 @@ class InteractiveSession:
     and makes testing easier while preserving all original functionality.
     """
 
-    def __init__(self, runner):
+    def __init__(self, runner: "ClaudeRunnerProtocol"):
         """Initialize interactive session handler.
 
         Args:
-            runner: ClaudeRunner instance with all necessary services
+            runner: ClaudeRunner instance (or any object matching ClaudeRunnerProtocol)
+                    with all necessary services
         """
-        self.runner = runner
+        self.runner: ClaudeRunnerProtocol = runner
         self.logger = get_logger("interactive_session")
         self.session_id = None
         self.original_cwd = Path.cwd()
@@ -397,7 +411,7 @@ class InteractiveSession:
                 self.logger.info("✓ Native agents mode: Using --agents CLI flag")
 
         # Add system instructions with file-based caching
-        from claude_mpm.core.claude_runner import create_simple_context
+        from claude_mpm.core.system_context import create_simple_context
         from claude_mpm.services.instructions.instruction_cache_service import (
             InstructionCacheService,
         )