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

claude_mpm/cli/parsers/agents_parser.py

@@ -444,4 +444,141 @@ Available commands:
         help="Show what would be deployed without actually deploying",
     )
 
+    # ============================================================================
+    # Collection-Based Agent Management Commands
+    # ============================================================================
+    # Purpose: Enable collection-based agent selection and deployment
+    # Commands: list-collections, deploy-collection, list-by-collection
+    # NEW: Enhanced agent matching with collection_id support
+    # ============================================================================
+
+    # list-collections: List all available agent collections
+    agents_subparsers.add_parser(
+        "list-collections",
+        help="List all available agent collections",
+        description="Display all agent collections with agent counts and collection metadata",
+    )
+
+    # deploy-collection: Deploy all agents from a specific collection
+    deploy_collection_parser = agents_subparsers.add_parser(
+        "deploy-collection",
+        help="Deploy all agents from a specific collection",
+        description="Deploy all agents from a named collection (e.g., 'bobmatnyc/claude-mpm-agents')",
+    )
+    deploy_collection_parser.add_argument(
+        "collection_id",
+        help="Collection ID in format 'owner/repo-name' (e.g., 'bobmatnyc/claude-mpm-agents')",
+    )
+    deploy_collection_parser.add_argument(
+        "--force",
+        "-f",
+        action="store_true",
+        help="Force redeployment even if agents are already deployed",
+    )
+    deploy_collection_parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show what would be deployed without actually deploying",
+    )
+
+    # list-by-collection: List agents filtered by collection
+    list_by_collection_parser = agents_subparsers.add_parser(
+        "list-by-collection",
+        help="List agents from a specific collection",
+        description="Display agents from a specific collection with metadata",
+    )
+    list_by_collection_parser.add_argument(
+        "collection_id",
+        help="Collection ID to filter by (e.g., 'bobmatnyc/claude-mpm-agents')",
+    )
+    list_by_collection_parser.add_argument(
+        "--format",
+        choices=["table", "json", "yaml"],
+        default="table",
+        help="Output format (default: table)",
+    )
+
+    # ============================================================================
+    # Cache Git Management Commands (claude-mpm Issue 1M-442 Phase 2)
+    # ============================================================================
+    # Purpose: Enable git workflow for agent cache management
+    # Commands: cache-status, cache-pull, cache-commit, cache-push, cache-sync
+    # Documentation: See docs/research/cache-update-workflow-analysis-2025-12-03.md
+    # ============================================================================
+
+    # cache-status: Show git status of agent cache
+    agents_subparsers.add_parser(
+        "cache-status",
+        help="Show git status of agent cache directory",
+        description="Display git status including branch, uncommitted changes, and unpushed commits",
+    )
+
+    # cache-pull: Pull latest agents from remote
+    cache_pull_parser = agents_subparsers.add_parser(
+        "cache-pull",
+        help="Pull latest agents from remote repository",
+        description="Fetch and merge latest agent changes from GitHub remote repository",
+    )
+    cache_pull_parser.add_argument(
+        "--branch",
+        default="main",
+        help="Branch to pull from (default: main)",
+    )
+
+    # cache-commit: Commit changes to agent cache
+    cache_commit_parser = agents_subparsers.add_parser(
+        "cache-commit",
+        help="Commit changes to agent cache",
+        description="Stage and commit changes to local agent cache git repository",
+    )
+    cache_commit_parser.add_argument(
+        "--message",
+        "-m",
+        help="Commit message (default: 'feat: update agents from local development')",
+    )
+    cache_commit_parser.add_argument(
+        "--files",
+        nargs="+",
+        help="Specific files to commit (default: all modified files)",
+    )
+
+    # cache-push: Push agent changes to remote
+    cache_push_parser = agents_subparsers.add_parser(
+        "cache-push",
+        help="Push agent changes to remote repository",
+        description="Push committed changes from local cache to GitHub remote repository",
+    )
+    cache_push_parser.add_argument(
+        "--branch",
+        default="main",
+        help="Branch to push to (default: main)",
+    )
+    cache_push_parser.add_argument(
+        "--auto-commit",
+        action="store_true",
+        help="Automatically commit uncommitted changes before pushing",
+    )
+
+    # cache-sync: Full cache sync workflow
+    cache_sync_parser = agents_subparsers.add_parser(
+        "cache-sync",
+        help="Full agent cache sync with remote",
+        description="Complete sync workflow: pull latest, commit local changes, push to remote",
+    )
+    cache_sync_parser.add_argument(
+        "--message",
+        "-m",
+        help="Commit message for any uncommitted changes",
+    )
+    cache_sync_parser.add_argument(
+        "--skip-pull",
+        action="store_true",
+        help="Skip pulling from remote before sync",
+    )
+    cache_sync_parser.add_argument(
+        "--skip-push",
+        action="store_true",
+        help="Skip pushing to remote after sync",
+    )
+
     return agents_parser

claude_mpm/cli/parsers/auto_configure_parser.py

@@ -88,6 +88,19 @@ Examples:
         help="Skip confirmation prompts and deploy automatically",
     )
 
+    # Scope selection
+    scope_group = auto_configure_parser.add_mutually_exclusive_group()
+    scope_group.add_argument(
+        "--agents-only",
+        action="store_true",
+        help="Configure agents only (skip skills)",
+    )
+    scope_group.add_argument(
+        "--skills-only",
+        action="store_true",
+        help="Configure skills only (skip agents)",
+    )
+
     # Configuration options
     auto_configure_parser.add_argument(
         "--min-confidence",

claude_mpm/cli/parsers/base_parser.py

@@ -553,6 +553,10 @@ def create_parser(
 
         add_doctor_parser(subparsers)
 
+        from ..commands.postmortem import add_postmortem_parser
+
+        add_postmortem_parser(subparsers)
+
         # Add upgrade command
         from ..commands.upgrade import add_upgrade_parser
 

claude_mpm/cli/parsers/skills_parser.py

@@ -134,6 +134,13 @@ def add_skills_subparser(subparsers) -> argparse.ArgumentParser:
         help="Show configuration file path",
     )
 
+    # Configure command (interactive skills selection)
+    skills_subparsers.add_parser(
+        SkillsCommands.CONFIGURE.value,
+        help="Interactive skills configuration with checkbox selection (like agents configure)",
+    )
+    # No additional arguments needed - purely interactive
+
     # GitHub deployment commands
     # Deploy from GitHub command
     deploy_github_parser = skills_subparsers.add_parser(

claude_mpm/cli/startup.py

@@ -10,6 +10,47 @@ Part of cli/__init__.py refactoring to reduce file size and improve modularity.
 
 import os
 import sys
+import warnings
+from pathlib import Path
+
+
+def check_legacy_cache() -> None:
+    """Check for legacy cache/agents/ directory and warn user.
+
+    WHY: cache/agents/ is deprecated in favor of cache/remote-agents/.
+    Research confirmed that cache/remote-agents/ is the canonical location
+    with 26 active code references, while cache/agents/ has only 7 legacy references.
+
+    DESIGN DECISIONS:
+    - Non-blocking warning: Doesn't stop execution, just informs user
+    - Migration guidance: Provides clear path to migrate
+    - One-time check: Only warns if legacy cache contains files
+    """
+    home = Path.home()
+    legacy_cache = home / ".claude-mpm" / "cache" / "agents"
+    canonical_cache = home / ".claude-mpm" / "cache" / "remote-agents"
+    migration_marker = home / ".claude-mpm" / "cache" / ".migrated_to_remote_agents"
+
+    # Skip if already migrated or no legacy cache
+    if migration_marker.exists() or not legacy_cache.exists():
+        return
+
+    # Check if legacy cache has actual agent files
+    legacy_files = list(legacy_cache.glob("*.md")) + list(legacy_cache.glob("*.json"))
+    if not legacy_files:
+        return
+
+    # Only warn if canonical cache doesn't exist (indicating unmigrated system)
+    if not canonical_cache.exists():
+        warnings.warn(
+            f"\n⚠️  DEPRECATION: Legacy cache directory detected\n"
+            f"   Location: {legacy_cache}\n"
+            f"   Files found: {len(legacy_files)}\n\n"
+            f"The 'cache/agents/' directory is deprecated. Please migrate to 'cache/remote-agents/'.\n"
+            f"Run: python scripts/migrate_cache_to_remote_agents.py\n",
+            DeprecationWarning,
+            stacklevel=2,
+        )
 
 
 def setup_early_environment(argv):
@@ -269,6 +310,9 @@ def sync_remote_agents_on_startup():
     2. Deploy agents to ~/.claude/agents/ - Phase 2 progress bar
     3. Log deployment results
     """
+    # Check for legacy cache and warn user if found
+    check_legacy_cache()
+
     try:
         from ..services.agents.deployment.agent_deployment import AgentDeploymentService
         from ..services.agents.startup_sync import sync_agents_on_startup
@@ -311,8 +355,9 @@ def sync_remote_agents_on_startup():
 
                 if cache_dir.exists():
                     # Count MD files in cache (agent markdown files from Git)
-                    # Only check root directory (avoid counting subdirectory duplicates)
-                    # Exclude PM templates and BASE-AGENT - only count deployable agents
+                    # BUGFIX: Only count files in agent directories, not docs/templates/READMEs
+                    # Valid agent paths must contain "/agents/" or be in root-level category dirs
+                    # Exclude PM templates, BASE-AGENT, and documentation files
                     pm_templates = {
                         "base-agent.md",
                         "circuit_breakers.md",
@@ -324,10 +369,34 @@ def sync_remote_agents_on_startup():
                         "validation_templates.md",
                         "git_file_tracking.md",
                     }
+                    # Documentation files to exclude (by filename)
+                    doc_files = {
+                        "readme.md",
+                        "changelog.md",
+                        "contributing.md",
+                        "implementation-summary.md",
+                        "reorganization-plan.md",
+                        "auto-deploy-index.md",
+                    }
+
+                    # Find all markdown files
+                    all_md_files = list(cache_dir.rglob("*.md"))
+
+                    # Filter to only agent files:
+                    # 1. Must have "/agents/" in path (from git repos)
+                    # 2. Must not be in PM templates or doc files
+                    # 3. Exclude BASE-AGENT.md which is not a deployable agent
                     agent_files = [
                         f
-                        for f in cache_dir.glob("*.md")
-                        if f.name.lower() not in pm_templates
+                        for f in all_md_files
+                        if (
+                            # Must be in an agent directory (from git repos like bobmatnyc/claude-mpm-agents/agents/)
+                            "/agents/" in str(f)
+                            # Exclude PM templates, doc files, and BASE-AGENT
+                            and f.name.lower() not in pm_templates
+                            and f.name.lower() not in doc_files
+                            and f.name.lower() != "base-agent.md"
+                        )
                     ]
                     agent_count = len(agent_files)
 
@@ -719,34 +788,6 @@ def check_mcp_auto_configuration():
         logger = get_logger("cli")
         logger.debug(f"MCP auto-configuration check failed: {e}")
 
-    # Also ensure MCP services are properly configured in ~/.claude.json
-    # This fixes incorrect paths and adds missing services
-    try:
-        from ..core.logger import get_logger
-        from ..services.mcp_config_manager import MCPConfigManager
-
-        logger = get_logger("cli")
-        mcp_manager = MCPConfigManager()
-
-        # Fix any corrupted installations first
-        _fix_success, fix_message = mcp_manager.fix_mcp_service_issues()
-        if fix_message and "Fixed:" in fix_message:
-            logger.info(f"MCP service fixes applied: {fix_message}")
-            print("✓ MCP services fixed", flush=True)
-
-        # Ensure all services are configured correctly
-        _config_success, config_message = mcp_manager.ensure_mcp_services_configured()
-        if config_message and "Added MCP services" in config_message:
-            logger.info(f"MCP services configured: {config_message}")
-            print("✓ MCP services configured", flush=True)
-
-    except Exception as e:
-        # Non-critical - log but don't fail
-        from ..core.logger import get_logger
-
-        logger = get_logger("cli")
-        logger.debug(f"MCP services configuration update failed: {e}")
-
 
 def verify_mcp_gateway_startup():
     """

claude_mpm/commands/mpm-agents-auto-configure.md

@@ -1,10 +1,10 @@
 ---
 namespace: mpm/agents
 command: auto-configure
-aliases: [mpm-agents-auto-configure, mpm-auto-configure]
+aliases: [mpm-agents-auto-configure]
 migration_target: /mpm/agents:auto-configure
 category: agents
-deprecated_aliases: []
+deprecated_aliases: [mpm-auto-configure]
 description: Automatically detect project toolchain and configure appropriate agents
 ---
 # Automatically configure agents based on project detection

claude_mpm/commands/mpm-agents-list.md

@@ -1,10 +1,10 @@
 ---
 namespace: mpm/agents
 command: list
-aliases: [mpm-agents, mpm-agents-list]
+aliases: [mpm-agents-list]
 migration_target: /mpm/agents:list
 category: agents
-deprecated_aliases: []
+deprecated_aliases: [mpm-agents]
 description: List all available Claude MPM agents with versions and deployment status
 ---
 # Show available agents and their versions

claude_mpm/commands/mpm-config-view.md

@@ -1,10 +1,10 @@
 ---
 namespace: mpm/config
 command: view
-aliases: [mpm-config-view, mpm-config]
+aliases: [mpm-config-view]
 migration_target: /mpm/config:view
 category: config
-deprecated_aliases: []
+deprecated_aliases: [mpm-config]
 description: View and validate Claude MPM configuration settings
 ---
 # View and validate claude-mpm configuration

claude_mpm/commands/mpm-help.md

@@ -72,6 +72,9 @@ Available Commands:
 /mpm-doctor [--fix] [--verbose]
   Diagnose and fix common issues
 
+/mpm-postmortem [--auto-fix] [--create-prs]
+  Analyze session errors and suggest improvements
+
 /mpm-agents [list|deploy|remove] [name]
   Manage agent deployment
 

claude_mpm/commands/mpm-postmortem.md

@@ -0,0 +1,123 @@
+---
+namespace: mpm/analysis
+command: postmortem
+aliases: [mpm-postmortem]
+migration_target: /mpm/analysis:postmortem
+category: analysis
+deprecated_aliases: []
+description: Analyze session errors and suggest improvements
+---
+# Analyze session errors and suggest improvements
+
+Perform a comprehensive analysis of errors encountered during the current or previous session and generate actionable improvement suggestions.
+
+## Usage
+
+```
+/mpm-postmortem [options]
+```
+
+## Description
+
+The postmortem command analyzes errors from:
+- Script execution failures
+- Skill execution issues
+- Agent instruction problems
+- User code errors (analysis only)
+
+It categorizes errors, identifies root causes, and generates actionable improvements:
+- **Scripts**: Tests and fixes in place
+- **Skills**: Updates skill files with improvements
+- **MPM Agents**: Prepares PRs with rationale for remote agent repository
+- **User Code**: Provides suggestions without modification
+
+## Options
+
+- `--dry-run`: Preview analysis without making changes (default for destructive operations)
+- `--auto-fix`: Automatically apply fixes to scripts and skills
+- `--create-prs`: Create pull requests for agent improvements
+- `--session-id <id>`: Analyze specific session (default: current session)
+- `--format <format>`: Output format: terminal, json, markdown (default: terminal)
+- `--output <file>`: Save report to file
+- `--verbose`: Include detailed error traces and analysis
+
+## Examples
+
+```bash
+# Analyze current session
+/mpm-postmortem
+
+# Preview changes without applying
+/mpm-postmortem --dry-run
+
+# Auto-fix scripts and skills
+/mpm-postmortem --auto-fix
+
+# Create PRs for agent improvements
+/mpm-postmortem --create-prs
+
+# Analyze specific session
+/mpm-postmortem --session-id 2025-12-03-143000
+
+# Save detailed report
+/mpm-postmortem --verbose --output postmortem-report.md
+```
+
+## Expected Output
+
+```
+📊 Session Postmortem Analysis
+═══════════════════════════════
+
+Session: 2025-12-03-143000
+Duration: 45 minutes
+Errors Found: 3
+
+🔧 Script Errors (1)
+─────────────────────
+• manage_version.py line 42: KeyError 'version'
+  Root Cause: Missing default value handling for optional configuration
+  Fix: Add fallback to default value when key not present
+  Status: Fixed ✓
+
+📚 Skill Errors (0)
+──────────────────
+No skill errors detected
+
+🤖 Agent Improvements (2)
+──────────────────────────
+• ticketing agent: Timeout on large ticket lists
+  Issue: Default timeout too short for projects with 500+ tickets
+  Improvement: Add pagination support and increase timeout threshold
+  PR: Created #123 (awaiting review)
+
+• engineer agent: Type validation missing for tool parameters
+  Issue: Invalid parameters passed to Edit tool causing failures
+  Improvement: Add parameter validation before tool invocation
+  Status: Ready to create PR (use --create-prs)
+
+💡 User Code Suggestions (0)
+────────────────────────────
+No user code issues detected
+
+📈 Summary
+──────────
+Total Errors: 3
+Fixed: 1
+PRs Created: 1
+Suggestions: 1
+```
+
+## Safety Features
+
+- **Dry-run by default**: Preview changes before applying
+- **Confirmation prompts**: Verify before creating PRs
+- **Backup before modifications**: Automatic backup of modified files
+- **Rollback capability**: Restore previous versions if needed
+- **Git integration**: Check for uncommitted changes before modifications
+
+## Related Commands
+
+- `/mpm-doctor`: Diagnose installation and configuration issues
+- `/mpm-session-resume`: Resume previous session with context
+- `/mpm-status`: View current system status

claude_mpm/commands/mpm-session-resume.md

@@ -1,10 +1,10 @@
 ---
 namespace: mpm/session
 command: resume
-aliases: [mpm-session-resume, mpm-resume]
+aliases: [mpm-session-resume]
 migration_target: /mpm/session:resume
 category: session
-deprecated_aliases: []
+deprecated_aliases: [mpm-resume]
 description: Load and display context from most recent paused session to continue work
 ---
 # /mpm-resume - Load Previous Session

claude_mpm/commands/mpm-ticket-organize.md

@@ -1,10 +1,10 @@
 ---
 namespace: mpm/ticket
 command: organize
-aliases: [mpm-ticket-organize, mpm-organize]
+aliases: [mpm-ticket-organize]
 migration_target: /mpm/ticket:organize
 category: tickets
-deprecated_aliases: []
+deprecated_aliases: [mpm-organize]
 description: Organize project files into proper directories with intelligent pattern detection
 ---
 # /mpm-organize

claude_mpm/commands/mpm-ticket-view.md

@@ -1,10 +1,10 @@
 ---
 namespace: mpm/ticket
 command: view
-aliases: [mpm-ticket-view, mpm-ticket]
+aliases: [mpm-ticket-view]
 migration_target: /mpm/ticket:view
 category: tickets
-deprecated_aliases: []
+deprecated_aliases: [mpm-ticket]
 description: Orchestrate ticketing agent for comprehensive project management workflows
 ---
 # /mpm-ticket - Ticketing Workflow Management