claude-mpm 4.15.6__py3-none-any.whl → 4.21.3__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

@@ -87,9 +87,15 @@ Available Commands:
 /mpm-init [update]
   Initialize or update project documentation
 
+/mpm-resume
+  Create session resume files for easy work resumption
+
 /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