claude-mpm 4.1.26__py3-none-any.whl → 5.0.9__py3-none-any.whl

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)
 
@@ -68,6 +83,121 @@ def add_agents_subparser(subparsers) -> argparse.ArgumentParser:
         "--show-config", action="store_true", help="Show agent configuration"
     )
 
+    # Create local agent
+    create_agent_parser = agents_subparsers.add_parser(
+        "create", help="Create a new local agent template"
+    )
+    create_agent_parser.add_argument(
+        "--interactive",
+        "-i",
+        action="store_true",
+        help="Launch interactive agent creation wizard",
+    )
+    create_agent_parser.add_argument("--agent-id", help="Agent ID (lowercase, hyphens)")
+    create_agent_parser.add_argument("--name", help="Agent display name")
+    create_agent_parser.add_argument(
+        "--model",
+        choices=["sonnet", "opus", "haiku"],
+        default="sonnet",
+        help="Model to use",
+    )
+    create_agent_parser.add_argument(
+        "--inherit-from", help="System agent to inherit from"
+    )
+
+    # Edit local agent
+    edit_agent_parser = agents_subparsers.add_parser(
+        "edit", help="Edit a local agent template"
+    )
+    edit_agent_parser.add_argument("agent_id", help="Agent ID to edit")
+    edit_agent_parser.add_argument(
+        "--interactive", "-i", action="store_true", help="Use interactive editor"
+    )
+    edit_agent_parser.add_argument(
+        "--editor", help="Editor to use (default: $EDITOR or nano)"
+    )
+
+    # Delete local agent
+    delete_agent_parser = agents_subparsers.add_parser(
+        "delete", help="Delete a local agent template"
+    )
+    delete_agent_parser.add_argument(
+        "agent_ids", nargs="+", help="Agent ID(s) to delete"
+    )
+    delete_agent_parser.add_argument(
+        "--force", "-f", action="store_true", help="Skip confirmation prompts"
+    )
+    delete_agent_parser.add_argument(
+        "--keep-deployment",
+        action="store_true",
+        help="Keep Claude Code deployment, only delete template",
+    )
+    delete_agent_parser.add_argument(
+        "--backup", action="store_true", help="Create backup before deletion"
+    )
+
+    # 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
+    configure_agents_parser = agents_subparsers.add_parser(
+        "configure", help="Configure which agents are deployed"
+    )
+    configure_agents_parser.add_argument(
+        "--enable",
+        nargs="+",
+        metavar="AGENT_ID",
+        help="Enable specific agents for deployment",
+    )
+    configure_agents_parser.add_argument(
+        "--disable",
+        nargs="+",
+        metavar="AGENT_ID",
+        help="Disable specific agents from deployment",
+    )
+    configure_agents_parser.add_argument(
+        "--enable-all", action="store_true", help="Enable all agents for deployment"
+    )
+    configure_agents_parser.add_argument(
+        "--disable-system",
+        action="store_true",
+        help="Disable all system agents from deployment",
+    )
+    configure_agents_parser.add_argument(
+        "--enable-system",
+        action="store_true",
+        help="Enable system agents for deployment",
+    )
+    configure_agents_parser.add_argument(
+        "--disable-local",
+        action="store_true",
+        help="Disable local project agents from deployment",
+    )
+    configure_agents_parser.add_argument(
+        "--enable-local",
+        action="store_true",
+        help="Enable local project agents for deployment",
+    )
+    configure_agents_parser.add_argument(
+        "--show", action="store_true", help="Show current deployment configuration"
+    )
+    configure_agents_parser.add_argument(
+        "--interactive",
+        "-i",
+        action="store_true",
+        help="Interactive configuration mode",
+    )
+
     # Deploy agents
     deploy_agents_parser = agents_subparsers.add_parser(
         AgentCommands.DEPLOY.value, help="Deploy agents to target directory"
@@ -86,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(
@@ -133,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"
@@ -159,4 +316,215 @@ def add_agents_subparser(subparsers) -> argparse.ArgumentParser:
         help="Only show summary, not individual agents",
     )
 
+    # 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",
+    )
+
+    # Auto-configuration commands (TSK-0054 Phase 5)
+    from .auto_configure_parser import (
+        add_agents_detect_subparser,
+        add_agents_recommend_subparser,
+    )
+
+    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",
+    )
+
+    # ============================================================================
+    # 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

@@ -0,0 +1,245 @@
+"""
+Auto-Configuration Parser for Claude MPM CLI
+============================================
+
+WHY: This module provides argument parsing for auto-configuration commands,
+enabling users to customize detection, recommendation, and deployment behavior.
+
+DESIGN DECISION: Follows existing parser patterns in the codebase, using
+add_common_arguments for consistency. Provides sensible defaults while
+allowing full customization.
+
+Part of TSK-0054: Auto-Configuration Feature - Phase 5
+"""
+
+import argparse
+from pathlib import Path
+
+from .base_parser import add_common_arguments
+
+
+def add_auto_configure_subparser(subparsers) -> argparse.ArgumentParser:
+    """
+    Add the auto-configure subparser for automated agent configuration.
+
+    WHY: Auto-configuration simplifies onboarding by detecting project toolchain
+    and deploying appropriate agents automatically.
+
+    Args:
+        subparsers: The subparsers object from the main parser
+
+    Returns:
+        The configured auto-configure subparser
+    """
+    # Auto-configure command
+    auto_configure_parser = subparsers.add_parser(
+        "auto-configure",
+        help="Auto-configure agents based on project toolchain detection",
+        description="""
+Auto-configure agents for your project based on detected toolchain.
+
+This command analyzes your project to detect languages, frameworks, and
+deployment targets, then recommends and deploys appropriate specialized
+agents automatically.
+
+The command provides safety features including:
+  • Preview mode to see changes before applying
+  • Confidence thresholds to ensure quality matches
+  • Validation gates to block invalid configurations
+  • Rollback on failure to maintain consistency
+        """,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Interactive configuration with confirmation
+  claude-mpm auto-configure
+
+  # Preview configuration without deploying
+  claude-mpm auto-configure --preview
+
+  # Auto-approve deployment (for scripts)
+  claude-mpm auto-configure --yes
+
+  # Require 90% confidence for recommendations
+  claude-mpm auto-configure --min-confidence 0.9
+
+  # JSON output for scripting
+  claude-mpm auto-configure --json
+
+  # Configure specific project directory
+  claude-mpm auto-configure --project-path /path/to/project
+        """,
+    )
+    add_common_arguments(auto_configure_parser)
+
+    # Configuration mode
+    mode_group = auto_configure_parser.add_mutually_exclusive_group()
+    mode_group.add_argument(
+        "--preview",
+        "--dry-run",
+        dest="preview",
+        action="store_true",
+        help="Show what would be configured without deploying (preview mode)",
+    )
+    mode_group.add_argument(
+        "--yes",
+        "-y",
+        action="store_true",
+        help="Skip confirmation prompts and deploy automatically",
+    )
+
+    # Configuration options
+    auto_configure_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)",
+    )
+
+    auto_configure_parser.add_argument(
+        "--project-path",
+        type=Path,
+        metavar="PATH",
+        help="Project path to analyze (default: current directory)",
+    )
+
+    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