claude-mpm 4.15.6__py3-none-any.whl → 4.21.0__py3-none-any.whl

claude_mpm/cli/parsers/skills_parser.py

@@ -0,0 +1,137 @@
+"""
+Skills command parser for claude-mpm CLI.
+
+WHY: This module contains all arguments specific to skills management commands,
+providing CLI access to the Skills Integration system.
+
+DESIGN DECISION: Skills commands expose the SkillsService functionality via CLI
+for listing, deploying, validating, updating, and configuring Claude Code skills.
+"""
+
+import argparse
+
+from ...constants import CLICommands, SkillsCommands
+from .base_parser import add_common_arguments
+
+
+def add_skills_subparser(subparsers) -> argparse.ArgumentParser:
+    """
+    Add the skills subparser with all skills management commands.
+
+    WHY: Skills management has multiple subcommands for discovery, deployment,
+    validation, updates, and configuration that need their own argument structures.
+
+    Args:
+        subparsers: The subparsers object from the main parser
+
+    Returns:
+        The configured skills subparser
+    """
+    # Skills command with subcommands
+    skills_parser = subparsers.add_parser(
+        CLICommands.SKILLS.value, help="Manage Claude Code skills"
+    )
+    add_common_arguments(skills_parser)
+
+    skills_subparsers = skills_parser.add_subparsers(
+        dest="skills_command", help="Skills commands", metavar="SUBCOMMAND"
+    )
+
+    # List command
+    list_parser = skills_subparsers.add_parser(
+        SkillsCommands.LIST.value, help="List available skills"
+    )
+    list_parser.add_argument(
+        "--category",
+        help="Filter by category (e.g., development, infrastructure, web-development)",
+    )
+    list_parser.add_argument(
+        "--agent", help="Show skills for specific agent (e.g., engineer, pm)"
+    )
+    list_parser.add_argument(
+        "--verbose",
+        "-v",
+        action="store_true",
+        help="Show detailed skill information",
+    )
+
+    # Deploy command
+    deploy_parser = skills_subparsers.add_parser(
+        SkillsCommands.DEPLOY.value, help="Deploy bundled skills to project"
+    )
+    deploy_parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Force redeployment of already deployed skills",
+    )
+    deploy_parser.add_argument(
+        "--skill",
+        action="append",
+        dest="skills",
+        help="Deploy specific skill(s) only (can be used multiple times)",
+    )
+
+    # Validate command
+    validate_parser = skills_subparsers.add_parser(
+        SkillsCommands.VALIDATE.value, help="Validate skill structure and metadata"
+    )
+    validate_parser.add_argument("skill_name", help="Name of the skill to validate")
+    validate_parser.add_argument(
+        "--strict",
+        action="store_true",
+        help="Use strict validation (treat warnings as errors)",
+    )
+
+    # Update command
+    update_parser = skills_subparsers.add_parser(
+        SkillsCommands.UPDATE.value, help="Check for and install skill updates"
+    )
+    update_parser.add_argument(
+        "skill_names",
+        nargs="*",
+        help="Specific skills to update (default: all)",
+    )
+    update_parser.add_argument(
+        "--check-only",
+        action="store_true",
+        help="Check for updates without installing them",
+    )
+    update_parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Force update even if versions match",
+    )
+
+    # Info command
+    info_parser = skills_subparsers.add_parser(
+        SkillsCommands.INFO.value, help="Show detailed skill information"
+    )
+    info_parser.add_argument("skill_name", help="Name of the skill")
+    info_parser.add_argument(
+        "--show-content",
+        action="store_true",
+        help="Show full skill content (SKILL.md)",
+    )
+
+    # Config command
+    config_parser = skills_subparsers.add_parser(
+        SkillsCommands.CONFIG.value, help="View or edit skills configuration"
+    )
+    config_parser.add_argument(
+        "--scope",
+        choices=["system", "user", "project"],
+        default="project",
+        help="Configuration scope (default: project)",
+    )
+    config_parser.add_argument(
+        "--edit",
+        action="store_true",
+        help="Open configuration in $EDITOR",
+    )
+    config_parser.add_argument(
+        "--path",
+        action="store_true",
+        help="Show configuration file path",
+    )
+
+    return skills_parser

claude_mpm/cli/startup.py

@@ -79,6 +79,62 @@ def setup_configure_command_environment(args):
         logging.getLogger("claude_mpm").setLevel(logging.WARNING)
 
 
+def deploy_bundled_skills():
+    """
+    Deploy bundled Claude Code skills on startup.
+
+    WHY: Automatically deploy skills from the bundled/ directory to .claude/skills/
+    to ensure skills are available for agents without manual intervention.
+
+    DESIGN DECISION: Deployment happens silently on startup with logging only.
+    Failures are logged but don't block startup to ensure claude-mpm remains
+    functional even if skills deployment fails. Respects auto_deploy config setting.
+    """
+    try:
+        # Check if auto-deploy is disabled in config
+        from ..config.config_loader import ConfigLoader
+
+        config_loader = ConfigLoader()
+        try:
+            config = config_loader.load_config()
+            skills_config = config.get("skills", {})
+            if not skills_config.get("auto_deploy", True):
+                # Auto-deploy disabled, skip silently
+                return
+        except Exception:
+            # If config loading fails, assume auto-deploy is enabled (default)
+            pass
+
+        # Import and run skills deployment
+        from ..skills.skills_service import SkillsService
+
+        skills_service = SkillsService()
+        deployment_result = skills_service.deploy_bundled_skills()
+
+        # Log results
+        from ..core.logger import get_logger
+
+        logger = get_logger("cli")
+
+        if deployment_result.get("deployed"):
+            logger.info(
+                f"Skills: Deployed {len(deployment_result['deployed'])} skill(s)"
+            )
+
+        if deployment_result.get("errors"):
+            logger.warning(
+                f"Skills: {len(deployment_result['errors'])} skill(s) failed to deploy"
+            )
+
+    except Exception as e:
+        # Import logger here to avoid circular imports
+        from ..core.logger import get_logger
+
+        logger = get_logger("cli")
+        logger.debug(f"Failed to deploy bundled skills: {e}")
+        # Continue execution - skills deployment failure shouldn't block startup
+
+
 def discover_and_link_runtime_skills():
     """
     Discover and link runtime skills from user/project directories.
@@ -114,6 +170,7 @@ def run_background_services():
     check_mcp_auto_configuration()
     verify_mcp_gateway_startup()
     check_for_updates_async()
+    deploy_bundled_skills()
     discover_and_link_runtime_skills()
 
 

claude_mpm/commands/mpm-auto-configure.md

@@ -201,6 +201,58 @@ Next steps:
 - docker-ops
 - local-ops-agent
 
+## Default Configuration Fallback
+
+When auto-configuration cannot detect your project's toolchain (e.g., a new or uncommon language/framework), it automatically falls back to a sensible set of default general-purpose agents instead of leaving your project unconfigured.
+
+### When Defaults are Applied
+
+Default agents are deployed when:
+- Primary language is detected as "Unknown"
+- No specific framework or toolchain can be identified
+- No agent recommendations can be generated from detected technologies
+
+### Default Agents
+
+The following general-purpose agents are recommended with moderate confidence (0.7):
+
+- **engineer**: General-purpose engineer for code implementation
+- **research**: Code exploration and analysis
+- **qa**: Testing and quality assurance
+- **ops**: Infrastructure and deployment operations
+- **documentation**: Documentation and technical writing
+
+All default recommendations will be marked with `is_default: True` in the metadata.
+
+### Disabling Default Fallback
+
+To disable the default configuration fallback, edit `.claude-mpm/config/agent_capabilities.yaml`:
+
+```yaml
+default_configuration:
+  enabled: false  # Disable default fallback
+```
+
+When disabled, auto-configuration will recommend zero agents if the toolchain cannot be detected.
+
+### Customizing Defaults
+
+You can customize which agents are deployed by default by editing the `default_configuration.agents` section in `.claude-mpm/config/agent_capabilities.yaml`:
+
+```yaml
+default_configuration:
+  enabled: true
+  min_confidence: 0.7  # Confidence score for default recommendations
+  agents:
+    - agent_id: engineer
+      reasoning: "General-purpose engineer for code implementation"
+      priority: 1
+    - agent_id: research
+      reasoning: "Code exploration and analysis"
+      priority: 2
+    # Add or remove agents as needed
+```
+
 ## Tips
 
 1. **Start with preview**: Always run with `--preview` first to see recommendations

claude_mpm/commands/mpm-help.md

@@ -90,6 +90,9 @@ Available Commands:
 /mpm-monitor [start|stop|restart|status|port]
   Manage Socket.IO monitoring server and dashboard
 
+/mpm-version
+  Display comprehensive version information including project version, all agents with versions, and all skills with versions
+
 Use '/mpm-help <command>' for detailed help on a specific command.
 ```
 

claude_mpm/commands/mpm-init.md

@@ -9,6 +9,9 @@ Initialize or intelligently update your project for optimal use with Claude Code
 /mpm-init update               # Lightweight update based on recent git activity
 /mpm-init context              # Intelligent context analysis from git history
 /mpm-init context --days 14    # Analyze last 14 days of git history
+/mpm-init resume               # Resume from stop event logs (NEW)
+/mpm-init resume --list        # List all sessions from logs
+/mpm-init resume --session-id ID  # Resume specific session
 /mpm-init catchup              # Quick commit history display (no analysis)
 /mpm-init --review             # Review project state without changes
 /mpm-init --update             # Full update of existing CLAUDE.md
@@ -24,7 +27,9 @@ This command has two primary modes:
 - **Project initialization/updates**: Delegates to the Agentic Coder Optimizer agent for documentation, tooling, and workflow setup
 - **Context analysis** (context/catchup): Provides intelligent project context from git history for resuming work
 
-**Note**: The `resume` subcommand is deprecated. Use `context` instead. The `resume` command still works for backward compatibility but will be removed in a future version.
+**Resume Modes**: The command provides two resume capabilities:
+- `/mpm-init resume`: Reads stop event logs from `.claude-mpm/responses/` to help resume work
+- `/mpm-init context`: Analyzes git history for intelligent work resumption (delegates to Research agent)
 
 **Quick Update Mode**: Running `/mpm-init update` performs a lightweight update focused on recent git activity. It analyzes recent commits, generates an activity report, and updates documentation with minimal changes. Perfect for quick refreshes after development sprints.
 
@@ -87,8 +92,46 @@ Analyzes recent git commits to identify:
 
 **NOT session state**: This does NOT save/restore conversation state like Claude Code. Instead, it reconstructs project context from git history using conventional commits and commit message analysis.
 
-#### `/mpm-init resume` [DEPRECATED]
-Alias for `context`. Use `context` instead.
+#### `/mpm-init resume` (Stop Event Logs)
+```bash
+/mpm-init resume                    # Show latest session from logs
+/mpm-init resume --list             # List all sessions
+/mpm-init resume --session-id ID    # Resume specific session
+/mpm-init resume --last 5           # Show last 5 sessions
+```
+
+Reads from stop event logs to help resume work from previous sessions:
+
+**Data Sources** (two-tier strategy):
+1. **Resume logs** (preferred): `.claude-mpm/resume-logs/*.md` - Structured 10k-token summaries
+2. **Response logs** (fallback): `.claude-mpm/responses/*.json` - Raw conversation stop events
+
+**What it shows**:
+- When session ended (time ago)
+- What was being worked on (request)
+- Tasks completed (from PM responses)
+- Files modified (from PM tracking)
+- Next steps (from PM recommendations)
+- Stop reason (why session ended)
+- Token usage (context consumption)
+- Git context (branch, working directory)
+
+**How it works**:
+1. Scans response logs in `.claude-mpm/responses/`
+2. Groups by `session_id`
+3. Parses PM response JSON for context
+4. Extracts tasks, files, next steps from PM summaries
+5. Displays comprehensive resume context
+
+**Use Cases**:
+- Resume work after context threshold pause
+- Review what was accomplished in previous session
+- Understand why session stopped (max_tokens, end_turn, etc.)
+- See exact files and tasks from last session
+
+**Difference from `context`**:
+- **resume**: Reads actual stop event logs (what PM logged)
+- **context**: Analyzes git commits (what was committed)
 
 ### `/mpm-init catchup` (Simple Git History)
 ```bash
@@ -225,6 +268,66 @@ This provides intelligent analysis including:
 
 The old `resume` command redirects to `context` with a deprecation warning.
 
+### Resume from Stop Event Logs
+
+Display context from previous sessions using stop event logs:
+
+```bash
+/mpm-init resume                    # Show latest session
+/mpm-init resume --list             # List all available sessions
+/mpm-init resume --session-id abc123  # Resume specific session
+/mpm-init resume --last 10          # Show last 10 sessions
+```
+
+Shows comprehensive context including:
+- What was being worked on
+- Tasks completed (from PM tracking)
+- Files modified
+- Next steps recommended
+- Stop reason (context limit, completion, etc.)
+- Token usage
+- Time elapsed since session
+
+**Example Output:**
+```
+================================================================================
+📋 Resume Context - Session from 2 hours ago
+================================================================================
+
+Session ID: 20251104_143000
+Ended: 2024-11-04 14:30 (2 hours ago)
+Stop Reason: Context threshold reached (70%)
+Token Usage: 140,000 / 200,000 (70%)
+
+Working on:
+  "Implementing auto-pause and resume functionality"
+
+✅ Completed:
+  • Researched stop event logging system
+  • Found response logs in .claude-mpm/responses/
+  • Identified two-tier resume strategy
+
+📝 Files Modified:
+  • src/claude_mpm/services/cli/resume_service.py (new)
+  • src/claude_mpm/cli/commands/mpm_init/ (refactored into package)
+
+🎯 Next Steps:
+  • Implement ResumeService class
+  • Add resume subcommand to mpm-init
+  • Test with real response logs
+
+Git Context:
+  Branch: main
+  Working Directory: /Users/masa/Projects/claude-mpm
+================================================================================
+```
+
+**Use Cases:**
+- Resume after hitting context limit
+- Review what was accomplished in last session
+- See exact next steps recommended by PM
+- Understand why session stopped
+
 ### Quick Git History (Catchup)
 
 Display recent commit history without analysis:
@@ -388,9 +491,12 @@ The command delegates to the Agentic Coder Optimizer agent which:
 ## Notes
 
 - **Quick Update vs Full Update**: Use `/mpm-init update` for fast activity-based updates (30 days), or `/mpm-init --update` for comprehensive doc refresh
-- **Context Analysis**: Use `/mpm-init context` to analyze git history and get intelligent resumption context from Research agent
-- **Quick History**: Use `/mpm-init catchup` for instant commit history display without analysis
-- **Deprecation Notice**: The `resume` command is deprecated. Use `context` instead. The old command still works but shows a warning.
+- **Resume Strategies**:
+  - **`/mpm-init resume`**: Read stop event logs (what PM tracked in last session)
+  - **`/mpm-init context`**: Analyze git history (intelligent work stream analysis via Research)
+  - **`/mpm-init catchup`**: Quick commit history display (no analysis)
+- **Stop Event Logs**: Response logs in `.claude-mpm/responses/` contain PM summaries with tasks, files, and next steps
+- **Two-Tier Resume**: Prefers structured resume logs (`.claude-mpm/resume-logs/`), falls back to response logs
 - **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

claude_mpm/commands/mpm-version.md

@@ -0,0 +1,113 @@
+# Display Claude MPM Version Information
+
+Show comprehensive version information for Claude MPM project, agents, and skills.
+
+## Usage
+
+```
+/mpm-version
+```
+
+## Description
+
+Display version information including:
+- Project version and build number
+- All deployed agents with their versions (grouped by tier: system/user/project)
+- All available skills with their versions (grouped by source: bundled/user/project)
+- Summary statistics
+
+## Implementation
+
+When you run `/mpm-version`, the PM will:
+
+1. **Collect Version Information**
+   - Use VersionService to gather all version data
+   - Project version from pyproject.toml
+   - Build number from BUILD_NUMBER file
+   - Agent versions from AgentRegistry
+   - Skills versions from SkillRegistry
+
+2. **Format Output**
+   - Hierarchical display: Project → Agents → Skills
+   - Grouped by tier/source for clarity
+   - Sorted alphabetically within groups
+   - Summary statistics at the end
+
+3. **Display Results**
+   - Well-formatted tree structure
+   - Easy to scan and read
+   - Includes totals and counts
+
+## Example Output
+
+```
+Claude MPM Version Information
+==============================
+
+Project Version: 4.16.3
+Build: 481
+
+Agents (35 total)
+-----------------
+
+System Agents (30):
+  ├─ agent-manager (1.0.0)
+  ├─ engineer (3.9.1)
+  ├─ research-agent (4.5.1)
+  ├─ documentation (2.1.0)
+  ├─ qa (2.0.3)
+  └─ ... (25 more)
+
+User Agents (3):
+  ├─ custom-agent (1.0.0)
+  ├─ testing-agent (0.5.0)
+  └─ prototype-agent (0.1.0)
+
+Project Agents (2):
+  ├─ project-specific (2.0.0)
+  └─ domain-expert (1.1.0)
+
+Skills (20 total)
+-----------------
+
+Bundled Skills (20):
+  ├─ test-driven-development (0.1.0)
+  ├─ systematic-debugging (0.1.0)
+  ├─ async-testing (0.1.0)
+  ├─ performance-profiling (0.1.0)
+  ├─ security-scanning (0.1.0)
+  └─ ... (15 more)
+
+User Skills (0):
+  (none)
+
+Project Skills (0):
+  (none)
+
+Summary
+-------
+• Project: v4.16.3 (build 481)
+• Agents: 35 total (30 system, 3 user, 2 project)
+• Skills: 20 total (20 bundled, 0 user, 0 project)
+```
+
+## PM Implementation Instructions
+
+To execute this command, PM should:
+
+1. Import and use VersionService:
+   ```python
+   from claude_mpm.services.version_service import VersionService
+
+   service = VersionService()
+   summary = service.get_version_summary()
+   ```
+
+2. Format output following the example structure above
+3. Handle missing data gracefully (show "unknown" for missing versions)
+4. Include all tiers/sources even if counts are zero
+
+## Related Commands
+
+- `/mpm-help` - Show all available MPM commands
+- `/mpm-status` - Show system status information

claude_mpm/commands/mpm.md

@@ -8,6 +8,7 @@ Available MPM commands:
 - /mpm-help - Show command help
 - /mpm-status - Show MPM status
 - /mpm-config - Manage configuration
+- /mpm-version - Display version information for project, agents, and skills
 
 Claude MPM extends Claude Code with:
 - Multi-agent orchestration

claude_mpm/config/agent_config.py

@@ -242,7 +242,7 @@ class AgentConfig:
                 Path.cwd() / get_path_manager().CONFIG_DIR / "agent_config.yaml"
             )
             if project_config.exists():
-                logger.info(f"Loading project agent config from {project_config}")
+                logger.debug(f"Loading project agent config from {project_config}")
                 file_config = cls.from_file(project_config)
                 # Merge with environment config (env takes precedence)
                 config = cls._merge_configs(config, file_config)
@@ -252,7 +252,7 @@ class AgentConfig:
             if user_config_dir:
                 user_config = user_config_dir / "agent_config.yaml"
                 if user_config.exists():
-                    logger.info(f"Loading user agent config from {user_config}")
+                    logger.debug(f"Loading user agent config from {user_config}")
                     file_config = cls.from_file(user_config)
                     config = cls._merge_configs(config, file_config)
 

claude_mpm/constants.py

@@ -45,6 +45,7 @@ class CLICommands(str, Enum):
     DOCTOR = "doctor"
     DASHBOARD = "dashboard"
     UPGRADE = "upgrade"
+    SKILLS = "skills"
 
     def with_prefix(self, prefix: CLIPrefix = CLIPrefix.MPM) -> str:
         """Get command with prefix."""
@@ -158,6 +159,17 @@ class TicketCommands(str, Enum):
     WORKFLOW = "workflow"
 
 
+class SkillsCommands(str, Enum):
+    """Skills subcommand constants."""
+
+    LIST = "list"
+    DEPLOY = "deploy"
+    VALIDATE = "validate"
+    UPDATE = "update"
+    INFO = "info"
+    CONFIG = "config"
+
+
 class CLIFlags(str, Enum):
     """CLI flag constants (without prefix)."""
 

claude_mpm/core/config.py

@@ -578,6 +578,11 @@ class Config:
                     "[PM-REMINDER] Your role is coordination and management",
                 ],
             },
+            # Session management configuration
+            "session": {
+                "auto_save": True,  # Enable automatic session saving
+                "save_interval": 300,  # Auto-save interval in seconds (5 minutes)
+            },
         }
 
         # Apply defaults for missing keys
@@ -588,6 +593,9 @@ class Config:
         # Validate health and recovery configuration
         self._validate_health_recovery_config()
 
+        # Validate session configuration
+        self._validate_session_config()
+
     def get(self, key: str, default: Any = None) -> Any:
         """Get configuration value."""
         # Support nested keys with dot notation
@@ -764,6 +772,40 @@ class Config:
         except Exception as e:
             logger.error(f"Error validating health/recovery configuration: {e}")
 
+    def _validate_session_config(self) -> None:
+        """Validate session management configuration."""
+        try:
+            session_config = self.get("session", {})
+
+            # Validate save_interval range (60-1800 seconds)
+            save_interval = session_config.get("save_interval", 300)
+            if not isinstance(save_interval, int):
+                logger.warning(
+                    f"Session save_interval must be integer, got {type(save_interval).__name__}, using default 300"
+                )
+                self.set("session.save_interval", 300)
+            elif save_interval < 60:
+                logger.warning(
+                    f"Session save_interval must be at least 60 seconds, got {save_interval}, using 60"
+                )
+                self.set("session.save_interval", 60)
+            elif save_interval > 1800:
+                logger.warning(
+                    f"Session save_interval must be at most 1800 seconds (30 min), got {save_interval}, using 1800"
+                )
+                self.set("session.save_interval", 1800)
+
+            # Validate auto_save is boolean
+            auto_save = session_config.get("auto_save", True)
+            if not isinstance(auto_save, bool):
+                logger.warning(
+                    f"Session auto_save must be boolean, got {type(auto_save).__name__}, using True"
+                )
+                self.set("session.auto_save", True)
+
+        except Exception as e:
+            logger.error(f"Error validating session configuration: {e}")
+
     def get_health_monitoring_config(self) -> Dict[str, Any]:
         """Get health monitoring configuration with defaults."""
         base_config = {

claude_mpm/core/factories.py

@@ -77,7 +77,7 @@ class AgentServiceFactory(ServiceFactory):
         if hasattr(service, "set_directories"):
             service.set_directories(framework_dir, project_dir)
 
-        logger.info("Created agent deployment service")
+        logger.debug("Created agent deployment service")
         return service