claude-mpm 4.24.0__py3-none-any.whl → 5.4.41__py3-none-any.whl

claude_mpm/cli/parsers/agent_source_parser.py

@@ -0,0 +1,171 @@
+"""Agent source command parser for agent repository management.
+
+WHY: This module provides CLI commands for managing agent source repositories
+(Git repositories containing agent markdown files). Parallel to skill source management
+but for the agent deployment system (multi-tier Git-based agents).
+
+DESIGN DECISION: Agent source management is separate from agent deployment to
+maintain clear separation of concerns:
+- agent-source commands: Manage repository configuration
+- agents commands: View and interact with agents themselves
+
+IMPLEMENTATION NOTE: This module is adapted from skill_source_parser.py, following
+the same proven patterns but for agent repositories instead of skills.
+"""
+
+import argparse
+
+from .base_parser import add_common_arguments
+
+
+def add_agent_source_subparser(subparsers) -> argparse.ArgumentParser:
+    """Add the agent-source subparser with all repository management commands.
+
+    WHY: Agent sources (Git repositories) need their own command group
+    for managing repository configuration, priorities, and synchronization.
+
+    Args:
+        subparsers: The subparsers object from the main parser
+
+    Returns:
+        The configured agent-source subparser
+    """
+    # Agent source command with subcommands
+    agent_source_parser = subparsers.add_parser(
+        "agent-source",
+        help="Manage agent source repositories",
+    )
+    add_common_arguments(agent_source_parser)
+
+    agent_source_subparsers = agent_source_parser.add_subparsers(
+        dest="agent_source_command",
+        help="Agent source repository commands",
+        metavar="SUBCOMMAND",
+    )
+
+    # Add repository
+    add_parser = agent_source_subparsers.add_parser(
+        "add",
+        help="Add a new agent source repository",
+    )
+    add_parser.add_argument(
+        "url",
+        help="Git repository URL (e.g., https://github.com/owner/repo)",
+    )
+    add_parser.add_argument(
+        "--subdirectory",
+        help="Subdirectory within repository containing agents (e.g., 'agents')",
+    )
+    add_parser.add_argument(
+        "--priority",
+        type=int,
+        default=100,
+        help="Priority for conflict resolution (lower = higher precedence, default: 100)",
+    )
+    add_parser.add_argument(
+        "--disabled",
+        action="store_true",
+        help="Add repository but keep it disabled",
+    )
+    add_parser.add_argument(
+        "--test",
+        action="store_true",
+        help="Test repository access without saving to configuration",
+    )
+    add_parser.add_argument(
+        "--no-test",
+        action="store_true",
+        dest="skip_test",
+        help="Skip immediate testing (not recommended)",
+    )
+
+    # Remove repository
+    remove_parser = agent_source_subparsers.add_parser(
+        "remove",
+        help="Remove an agent source repository",
+    )
+    remove_parser.add_argument(
+        "source_id",
+        help="Source identifier (e.g., 'owner/repo' or 'owner/repo/subdirectory')",
+    )
+    remove_parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Skip confirmation prompt",
+    )
+
+    # List repositories
+    list_parser = agent_source_subparsers.add_parser(
+        "list",
+        help="List configured agent source repositories",
+    )
+    list_parser.add_argument(
+        "--by-priority",
+        action="store_true",
+        dest="by_priority",
+        help="Sort by priority (lowest first)",
+    )
+    list_parser.add_argument(
+        "--enabled-only",
+        action="store_true",
+        dest="enabled_only",
+        help="Show only enabled repositories",
+    )
+    list_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output as JSON",
+    )
+
+    # Update/sync repositories
+    update_parser = agent_source_subparsers.add_parser(
+        "update",
+        help="Update (sync) agent sources from Git",
+    )
+    update_parser.add_argument(
+        "source_id",
+        nargs="?",
+        help="Optional: Update only this repository (default: update all)",
+    )
+    update_parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Force update even if cache is fresh",
+    )
+
+    # Enable repository
+    enable_parser = agent_source_subparsers.add_parser(
+        "enable",
+        help="Enable a disabled repository",
+    )
+    enable_parser.add_argument(
+        "source_id",
+        help="Source identifier to enable",
+    )
+
+    # Disable repository
+    disable_parser = agent_source_subparsers.add_parser(
+        "disable",
+        help="Disable a repository",
+    )
+    disable_parser.add_argument(
+        "source_id",
+        help="Source identifier to disable",
+    )
+
+    # Show repository details
+    show_parser = agent_source_subparsers.add_parser(
+        "show",
+        help="Show details for an agent source",
+    )
+    show_parser.add_argument(
+        "source_id",
+        help="Source identifier to show",
+    )
+    show_parser.add_argument(
+        "--agents",
+        action="store_true",
+        help="Also list agents from this source",
+    )
+
+    return agent_source_parser

claude_mpm/cli/parsers/agents_parser.py

@@ -31,7 +31,22 @@ def add_agents_subparser(subparsers) -> argparse.ArgumentParser:
     """
     # Agents command with subcommands
     agents_parser = subparsers.add_parser(
-        CLICommands.AGENTS.value, help="Manage agents and deployment"
+        CLICommands.AGENTS.value,
+        help="Manage agents and deployment",
+        description="""
+Manage Claude MPM agents.
+
+NOTE: For interactive agent management, use 'claude-mpm config' instead.
+      The 'agents manage' command has been deprecated in favor of the
+      unified configuration interface.
+
+Available commands:
+  discover    Discover available agents from configured sources
+  deploy      Deploy agents to your project
+  list        List available agents
+  manage      (Deprecated) Use 'claude-mpm config' instead
+""",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
     )
     add_common_arguments(agents_parser)
 
@@ -121,9 +136,17 @@ def add_agents_subparser(subparsers) -> argparse.ArgumentParser:
         "--backup", action="store_true", help="Create backup before deletion"
     )
 
-    # Manage local agents (interactive menu)
-    agents_subparsers.add_parser(
-        "manage", help="Interactive menu for managing local agents"
+    # Manage local agents (interactive menu) - DEPRECATED
+    manage_parser = agents_subparsers.add_parser(
+        "manage",
+        help="(Deprecated) Manage local agents - use 'claude-mpm config' instead",
+        description="Manage locally deployed agents. Note: This command has been deprecated. "
+        "Please use 'claude-mpm config' for the enhanced configuration interface.",
+    )
+    manage_parser.epilog = (
+        "\nDEPRECATION NOTICE:\n"
+        "This command has been deprecated in favor of 'claude-mpm config' which provides\n"
+        "a unified interface for managing agents, skills, templates, and behavior settings.\n"
     )
 
     # Configure agent deployment settings
@@ -193,6 +216,11 @@ def add_agents_subparser(subparsers) -> argparse.ArgumentParser:
         action="store_true",
         help="Show what would be deployed without actually deploying",
     )
+    deploy_agents_parser.add_argument(
+        "--preset",
+        type=str,
+        help="Deploy agents by preset name (minimal, python-dev, nextjs-fullstack, etc.)",
+    )
 
     # Validate agents
     validate_agents_parser = agents_subparsers.add_parser(
@@ -240,6 +268,28 @@ def add_agents_subparser(subparsers) -> argparse.ArgumentParser:
         help="Maximum retry attempts per package (default: 3)",
     )
 
+    # Cleanup: sync, install, and remove old underscore-named agents
+    cleanup_parser = agents_subparsers.add_parser(
+        "cleanup",
+        help="Sync agents, install with new naming, and remove old underscore-named duplicates",
+    )
+    cleanup_parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show what would be done without actually doing it",
+    )
+    cleanup_parser.add_argument(
+        "--target",
+        type=Path,
+        help="Target directory for agent deployment (default: project .claude-mpm/agents/)",
+    )
+    cleanup_parser.add_argument(
+        "--global",
+        dest="global_deployment",
+        action="store_true",
+        help="Deploy to global ~/.claude/agents/ instead of project directory",
+    )
+
     # Cleanup orphaned agents
     cleanup_orphaned_parser = agents_subparsers.add_parser(
         "cleanup-orphaned", help="Clean up orphaned agents that don't have templates"
@@ -266,13 +316,260 @@ def add_agents_subparser(subparsers) -> argparse.ArgumentParser:
         help="Only show summary, not individual agents",
     )
 
-    # Auto-configuration commands (TSK-0054 Phase 5)
-    from .auto_configure_parser import (
-        add_agents_detect_subparser,
-        add_agents_recommend_subparser,
+    # Migrate user-level agents to project-level (DEPRECATION support)
+    migrate_parser = agents_subparsers.add_parser(
+        "migrate-to-project",
+        help="Migrate user-level agents to project-level (user-level is DEPRECATED)",
+    )
+    migrate_parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show what would be migrated without actually doing it",
+    )
+    migrate_parser.add_argument(
+        "--force",
+        "-f",
+        action="store_true",
+        help="Overwrite existing project agents if conflicts",
+    )
+
+    # Deploy all agents from sources (single-tier deployment)
+    deploy_all_parser = agents_subparsers.add_parser(
+        "deploy-all",
+        help="Deploy all agents from configured sources (single-tier deployment)",
+    )
+    deploy_all_parser.add_argument(
+        "--force-sync",
+        action="store_true",
+        help="Force sync repositories before deploying (ignore cache)",
+    )
+    deploy_all_parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show what would be deployed without actually deploying",
+    )
+
+    # List available agents from sources
+    available_parser = agents_subparsers.add_parser(
+        "available",
+        help="List available agents from all configured sources",
+    )
+    available_parser.add_argument(
+        "--source",
+        help="Filter by source repository (e.g., 'owner/repo/subdirectory')",
+    )
+    available_parser.add_argument(
+        "--format",
+        choices=["table", "json", "simple"],
+        default="table",
+        help="Output format (default: table)",
+    )
+
+    # Discover agents with rich filtering (Phase 1: Discovery & Browsing)
+    discover_parser = agents_subparsers.add_parser(
+        "discover",
+        help="Discover available agents from configured sources with rich filtering",
+    )
+    discover_parser.add_argument(
+        "--source",
+        help="Filter by specific source ID (e.g., 'owner/repo')",
+    )
+    discover_parser.add_argument(
+        "--category",
+        help="Filter by category (e.g., 'engineer/backend', 'qa', 'ops/platform')",
+    )
+    discover_parser.add_argument(
+        "--language",
+        help="Filter by programming language (e.g., 'python', 'javascript', 'rust')",
+    )
+    discover_parser.add_argument(
+        "--framework",
+        help="Filter by framework (e.g., 'react', 'nextjs', 'django')",
+    )
+    discover_parser.add_argument(
+        "--platform",
+        help="Filter by platform (e.g., 'vercel', 'gcp', 'docker')",
+    )
+    discover_parser.add_argument(
+        "--specialization",
+        help="Filter by specialization (e.g., 'data', 'security', 'mobile')",
+    )
+    discover_parser.add_argument(
+        "--format",
+        choices=["table", "json", "simple"],
+        default="table",
+        help="Output format (default: table)",
+    )
+    discover_parser.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Show descriptions and metadata for each agent",
     )
 
-    add_agents_detect_subparser(agents_subparsers)
-    add_agents_recommend_subparser(agents_subparsers)
+    # Phase 3: Agent Selection Modes (single-tier deployment)
+    # Minimal configuration - deploy 6 core agents
+    deploy_minimal_parser = agents_subparsers.add_parser(
+        "deploy-minimal",
+        help="Deploy minimal configuration (6 core agents: engineer, documentation, qa, research, ops, ticketing)",
+    )
+    deploy_minimal_parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show what would be deployed without actually deploying",
+    )
+
+    # Auto-configure - detect toolchain and deploy matching agents
+    deploy_auto_parser = agents_subparsers.add_parser(
+        "deploy-auto",
+        help="Auto-detect project toolchain and deploy matching agents",
+    )
+    deploy_auto_parser.add_argument(
+        "--path",
+        type=Path,
+        default=Path.cwd(),
+        help="Project path to scan for toolchain detection (default: current directory)",
+    )
+    deploy_auto_parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        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",
@@ -105,141 +118,3 @@ Examples:
     )
 
     return auto_configure_parser
-
-
-def add_agents_detect_subparser(agents_subparsers) -> argparse.ArgumentParser:
-    """
-    Add the agents detect subparser for toolchain detection.
-
-    WHY: Allows users to see what toolchain is detected without making changes,
-    useful for debugging and verification.
-
-    Args:
-        agents_subparsers: The agents subparsers object
-
-    Returns:
-        The configured detect subparser
-    """
-    detect_parser = agents_subparsers.add_parser(
-        "detect",
-        help="Detect project toolchain without deploying",
-        description="""
-Detect and display project toolchain without making any changes.
-
-This command analyzes your project to detect:
-  • Programming languages and versions
-  • Frameworks and libraries
-  • Deployment targets and platforms
-
-Useful for debugging toolchain detection and verifying what would be
-detected before running auto-configure.
-        """,
-        formatter_class=argparse.RawDescriptionHelpFormatter,
-        epilog="""
-Examples:
-  # Detect toolchain in current directory
-  claude-mpm agents detect
-
-  # Detect with verbose output showing evidence
-  claude-mpm agents detect --verbose
-
-  # JSON output for scripting
-  claude-mpm agents detect --json
-
-  # Detect specific project
-  claude-mpm agents detect --project-path /path/to/project
-        """,
-    )
-    add_common_arguments(detect_parser)
-
-    detect_parser.add_argument(
-        "--project-path",
-        type=Path,
-        metavar="PATH",
-        help="Project path to analyze (default: current directory)",
-    )
-
-    return detect_parser
-
-
-def add_agents_recommend_subparser(
-    agents_subparsers,
-) -> argparse.ArgumentParser:
-    """
-    Add the agents recommend subparser for agent recommendations.
-
-    WHY: Allows users to see what agents would be recommended without deploying,
-    useful for reviewing recommendations before committing to deployment.
-
-    Args:
-        agents_subparsers: The agents subparsers object
-
-    Returns:
-        The configured recommend subparser
-    """
-    recommend_parser = agents_subparsers.add_parser(
-        "recommend",
-        help="Show recommended agents without deploying",
-        description="""
-Show recommended agents based on project toolchain without deploying.
-
-This command analyzes your project toolchain and recommends appropriate
-agents with detailed reasoning for each recommendation. No changes are
-made to your project.
-
-Useful for:
-  • Reviewing recommendations before deployment
-  • Understanding why agents are recommended
-  • Adjusting confidence thresholds
-        """,
-        formatter_class=argparse.RawDescriptionHelpFormatter,
-        epilog="""
-Examples:
-  # Show recommendations with reasoning
-  claude-mpm agents recommend
-
-  # Require 90% confidence for recommendations
-  claude-mpm agents recommend --min-confidence 0.9
-
-  # JSON output for scripting
-  claude-mpm agents recommend --json
-
-  # Hide detailed reasoning
-  claude-mpm agents recommend --no-reasoning
-
-  # Recommend for specific project
-  claude-mpm agents recommend --project-path /path/to/project
-        """,
-    )
-    add_common_arguments(recommend_parser)
-
-    recommend_parser.add_argument(
-        "--project-path",
-        type=Path,
-        metavar="PATH",
-        help="Project path to analyze (default: current directory)",
-    )
-
-    recommend_parser.add_argument(
-        "--min-confidence",
-        type=float,
-        default=0.8,
-        metavar="FLOAT",
-        help="Minimum confidence threshold for recommendations (0.0-1.0, default: 0.8)",
-    )
-
-    recommend_parser.add_argument(
-        "--show-reasoning",
-        action="store_true",
-        default=True,
-        help="Show detailed reasoning for recommendations (default)",
-    )
-
-    recommend_parser.add_argument(
-        "--no-reasoning",
-        dest="show_reasoning",
-        action="store_false",
-        help="Hide detailed reasoning for recommendations",
-    )
-
-    return recommend_parser