claude-mpm 5.4.59__py3-none-any.whl → 5.4.71__py3-none-any.whl

claude_mpm/agents/PM_INSTRUCTIONS.md

@@ -7,6 +7,17 @@
 
 The Project Manager (PM) agent coordinates work across specialized agents in the Claude MPM framework. The PM's responsibility is orchestration and quality assurance, not direct execution.
 
+## 🔴 ABSOLUTE PROHIBITIONS 🔴
+
+**PM must NEVER:**
+1. Read source code files (`.py`, `.js`, `.ts`, `.tsx`, etc.) - DELEGATE to Research
+2. Use Read tool more than ONCE per session - DELEGATE to Research
+3. Investigate, debug, or analyze code directly - DELEGATE to Research
+4. Use Edit/Write tools on any file - DELEGATE to Engineer
+5. Run verification commands (curl, lsof) - DELEGATE to local-ops
+
+**Violation of any prohibition = Circuit Breaker triggered**
+
 ### Why Delegation Matters
 
 The PM delegates all work to specialized agents for three key reasons:
@@ -315,22 +326,31 @@ TodoWrite:
 
 ### Read Tool Usage (Strict Hierarchy)
 
-**DEFAULT**: Zero reads - delegate to Research instead.
+**ABSOLUTE PROHIBITION**: PM must NEVER read source code files directly.
+
+**Source code extensions** (ALWAYS delegate to Research):
+`.py`, `.js`, `.ts`, `.tsx`, `.jsx`, `.go`, `.rs`, `.java`, `.rb`, `.php`, `.swift`, `.kt`, `.c`, `.cpp`, `.h`
 
 **SINGLE EXCEPTION**: ONE config/settings file for delegation context only.
+- Allowed: `package.json`, `pyproject.toml`, `settings.json`, `.env.example`
+- NOT allowed: Any file with source code extensions above
+
+**Pre-Flight Check (MANDATORY before ANY Read call)**:
+1. Is this a source code file? → STOP, delegate to Research
+2. Have I already used Read once this session? → STOP, delegate to Research
+3. Does my task contain investigation keywords? → STOP, delegate to Research
+
+**Investigation Keywords** (trigger delegation, not Read):
+- check, look, see, find, search, analyze, investigate, debug
+- understand, explore, examine, review, inspect, trace
+- "what does", "how does", "why does", "where is"
 
 **Rules**:
 - ✅ Allowed: ONE file (`package.json`, `pyproject.toml`, `settings.json`, `.env.example`)
-- ❌ Forbidden: Source code (`.py`, `.js`, `.ts`, `.tsx`, `.go`, `.rs`)
-- ❌ Forbidden: Multiple files OR investigation keywords ("check", "analyze", "debug", "investigate")
+- ❌ NEVER: Source code (`.py`, `.js`, `.ts`, `.tsx`, `.go`, `.rs`)
+- ❌ NEVER: Multiple files OR investigation keywords ("check", "analyze", "debug", "investigate")
 - **Rationale**: Reading leads to investigating. PM must delegate, not do.
 
-**Before Using Read, Check**:
-1. Investigation keywords present? → Delegate to Research (zero reads)
-2. Source code file? → Delegate to Research
-3. Already used Read once? → Violation - delegate to Research
-4. Purpose is delegation context (not understanding)? → ONE Read allowed
-
 ## Agent Deployment Architecture
 
 ### Cache Structure
@@ -1306,6 +1326,13 @@ PM: *Delegates to Research*         # ✅ CORRECT: If vector search insufficient
 **Action**: BLOCK - Must delegate to Research instead
 **Enforcement**: Violation #1 = Warning, #2 = Session flagged, #3 = Non-compliant
 
+**Proactive Self-Check (PM must ask before EVERY Read call)**:
+1. "Is this file a source code file?" → If yes, DELEGATE
+2. "Have I already used Read this session?" → If yes, DELEGATE
+3. "Am I investigating/debugging?" → If yes, DELEGATE
+
+If ANY answer is YES → Do NOT use Read, delegate to Research instead.
+
 **Allowed Exception:**
 - ONE config file read (package.json, pyproject.toml, settings.json, .env.example)
 - Purpose: Delegation context ONLY (not investigation)

claude_mpm/cli/__init__.py

@@ -91,7 +91,11 @@ def main(argv: Optional[list] = None):
         )
 
         try:
-            run_background_services()
+            # Check for --force-sync flag or environment variable
+            force_sync = getattr(args, "force_sync", False) or os.environ.get(
+                "CLAUDE_MPM_FORCE_SYNC", "0"
+            ) in ("1", "true", "True", "yes")
+            run_background_services(force_sync=force_sync)
             launch_progress.finish(message="Ready")
 
             # Inform user about Claude Code initialization delay (3-5 seconds)

claude_mpm/cli/executor.py

@@ -66,6 +66,7 @@ def ensure_run_attributes(args):
     args.monitor = getattr(args, "monitor", False)
     args.force = getattr(args, "force", False)
     args.reload_agents = getattr(args, "reload_agents", False)
+    args.force_sync = getattr(args, "force_sync", False)
     # Include dependency checking attributes
     args.check_dependencies = getattr(args, "check_dependencies", True)
     args.force_check_dependencies = getattr(args, "force_check_dependencies", False)

claude_mpm/cli/parsers/base_parser.py

@@ -292,6 +292,11 @@ def add_top_level_run_arguments(parser: argparse.ArgumentParser) -> None:
         action="store_true",
         help="Force rebuild of all system agents by deleting local claude-mpm agents",
     )
+    run_group.add_argument(
+        "--force-sync",
+        action="store_true",
+        help="Force refresh agents and skills from remote repos, bypassing ETag cache",
+    )
 
     # Dependency checking options (for backward compatibility at top level)
     dep_group_top = parser.add_argument_group(

claude_mpm/cli/startup.py

@@ -308,12 +308,12 @@ def deploy_output_style_on_startup():
     communication without emojis and exclamation points. Styles are project-specific
     to allow different projects to have different communication styles.
 
-    DESIGN DECISION: This is non-blocking and idempotent. Deploys to project-level
-    directory (.claude/settings/output-styles/) instead of user-level to maintain
-    project isolation.
+    DESIGN DECISION: This is non-blocking and idempotent. Deploys to user-level
+    directory (~/.claude/output-styles/) which is the official Claude Code location
+    for custom output styles.
 
     Deploys two styles:
-    - claude-mpm-style.md (professional mode)
+    - claude-mpm.md (professional mode)
     - claude-mpm-teacher.md (teaching mode)
     """
     try:
@@ -325,24 +325,29 @@ def deploy_output_style_on_startup():
         professional_source = package_dir / "CLAUDE_MPM_OUTPUT_STYLE.md"
         teacher_source = package_dir / "CLAUDE_MPM_TEACHER_OUTPUT_STYLE.md"
 
-        # Target directory (PROJECT-LEVEL, not user-level)
-        project_dir = Path.cwd()
-        output_styles_dir = project_dir / ".claude" / "settings" / "output-styles"
-        professional_target = output_styles_dir / "claude-mpm-style.md"
+        # Target directory (USER-LEVEL for global availability)
+        # Claude Code reads output styles from ~/.claude/output-styles/
+        user_home = Path.home()
+        output_styles_dir = user_home / ".claude" / "output-styles"
+        professional_target = output_styles_dir / "claude-mpm.md"
         teacher_target = output_styles_dir / "claude-mpm-teacher.md"
 
         # Create directory if it doesn't exist
         output_styles_dir.mkdir(parents=True, exist_ok=True)
 
-        # Check if already deployed (both files exist and have content)
-        already_deployed = (
+        # Check if already deployed AND up-to-date (compare sizes to detect changes)
+        professional_up_to_date = (
             professional_target.exists()
-            and teacher_target.exists()
-            and professional_target.stat().st_size > 0
-            and teacher_target.stat().st_size > 0
+            and professional_source.exists()
+            and professional_target.stat().st_size == professional_source.stat().st_size
+        )
+        teacher_up_to_date = (
+            teacher_target.exists()
+            and teacher_source.exists()
+            and teacher_target.stat().st_size == teacher_source.stat().st_size
         )
 
-        if already_deployed:
+        if professional_up_to_date and teacher_up_to_date:
             # Show feedback that output styles are ready
             print("✓ Output styles ready", flush=True)
             return
@@ -453,7 +458,7 @@ def _cleanup_orphaned_agents(deploy_target: Path, deployed_agents: list[str]) ->
     return removed_count
 
 
-def sync_remote_agents_on_startup():
+def sync_remote_agents_on_startup(force_sync: bool = False):
     """
     Synchronize agent templates from remote sources on startup.
 
@@ -466,16 +471,16 @@ def sync_remote_agents_on_startup():
     block startup to ensure claude-mpm remains functional.
 
     Workflow:
-    1. Cleanup legacy agent cache directories (if any)
-    2. Sync all enabled Git sources (download/cache files) - Phase 1 progress bar
-    3. Deploy agents to ~/.claude/agents/ - Phase 2 progress bar
-    4. Cleanup orphaned agents (ours but no longer deployed) - Phase 3
+    1. Sync all enabled Git sources (download/cache files) - Phase 1 progress bar
+    2. Deploy agents to ~/.claude/agents/ - Phase 2 progress bar
+    3. Cleanup orphaned agents (ours but no longer deployed) - Phase 3
+    4. Cleanup legacy agent cache directories (after sync/deployment) - Phase 4
     5. Log deployment results
-    """
-    # Cleanup legacy cache directories first (before syncing)
-    cleanup_legacy_agent_cache()
 
-    # DEPRECATED: Legacy warning - replaced by automatic cleanup above
+    Args:
+        force_sync: Force download even if cache is fresh (bypasses ETag).
+    """
+    # DEPRECATED: Legacy warning - no-op function, kept for compatibility
     check_legacy_cache()
 
     try:
@@ -509,7 +514,7 @@ def sync_remote_agents_on_startup():
                 )
 
         # Phase 1: Sync files from Git sources
-        result = sync_agents_on_startup()
+        result = sync_agents_on_startup(force_refresh=force_sync)
 
         # Only proceed with deployment if sync was enabled and ran
         if result.get("enabled") and result.get("sources_synced", 0) > 0:
@@ -695,7 +700,8 @@ def sync_remote_agents_on_startup():
                     agent_files = [
                         f
                         for f in all_md_files
-                        if (
+                        if
+                        (
                             # Must be in an agent directory
                             # Supports: cache/agents/{category}/... (flat)
                             # Supports: cache/agents/{owner}/{repo}/agents/{category}/... (GitHub sync)
@@ -838,6 +844,11 @@ def sync_remote_agents_on_startup():
                 logger = get_logger("cli")
                 logger.warning(f"Failed to deploy agents from cache: {e}")
 
+        # Phase 4: Cleanup legacy agent cache directories (after sync/deployment)
+        # CRITICAL: This must run AFTER sync completes because sync may recreate
+        # legacy directories. Running cleanup here ensures they're removed.
+        cleanup_legacy_agent_cache()
+
     except Exception as e:
         # Non-critical - log but don't fail startup
         from ..core.logger import get_logger
@@ -846,8 +857,14 @@ def sync_remote_agents_on_startup():
         logger.debug(f"Failed to sync remote agents: {e}")
         # Continue execution - agent sync failure shouldn't block startup
 
+        # Cleanup legacy cache even if sync failed
+        try:
+            cleanup_legacy_agent_cache()
+        except Exception:
+            pass  # Ignore cleanup errors
 
-def sync_remote_skills_on_startup():
+
+def sync_remote_skills_on_startup(force_sync: bool = False):
     """
     Synchronize skill templates from remote sources on startup.
 
@@ -865,6 +882,9 @@ def sync_remote_skills_on_startup():
     4. Apply profile filtering if active
     5. Deploy resolved skills to ~/.claude/skills/ - Phase 2 progress bar
     6. Log deployment results with source indication
+
+    Args:
+        force_sync: Force download even if cache is fresh (bypasses ETag).
     """
     try:
         from pathlib import Path
@@ -970,7 +990,7 @@ def sync_remote_skills_on_startup():
 
         # Sync all sources with progress callback
         results = manager.sync_all_sources(
-            force=False, progress_callback=sync_progress.update
+            force=force_sync, progress_callback=sync_progress.update
         )
 
         # Finish sync progress bar with clear breakdown
@@ -1068,9 +1088,7 @@ def sync_remote_skills_on_startup():
         total_skill_count = len(all_skills)
 
         # Determine skill count based on resolution
-        skill_count = (
-            len(skills_to_deploy) if skills_to_deploy else total_skill_count
-        )
+        skill_count = len(skills_to_deploy) if skills_to_deploy else total_skill_count
 
         if skill_count > 0:
             # Deploy skills with resolved filter
@@ -1081,11 +1099,13 @@ def sync_remote_skills_on_startup():
             # Deploy to project-local directory with cleanup
             deployment_result = manager.deploy_skills(
                 target_dir=Path.cwd() / ".claude" / "skills",
-                force=False,
+                force=force_sync,
                 # CRITICAL FIX: Empty list should mean "deploy no skills", not "deploy all"
                 # When skills_to_deploy is [], we want skill_filter=set() NOT skill_filter=None
                 # None means "no filtering" (deploy all), empty set means "filter to nothing"
-                skill_filter=set(skills_to_deploy) if skills_to_deploy is not None else None,
+                skill_filter=set(skills_to_deploy)
+                if skills_to_deploy is not None
+                else None,
             )
 
             # REMOVED: User-level deployment (lines 1068-1074)
@@ -1423,7 +1443,7 @@ def auto_install_chrome_devtools_on_startup():
         # Continue execution - chrome-devtools installation failure shouldn't block startup
 
 
-def run_background_services():
+def run_background_services(force_sync: bool = False):
     """
     Initialize all background services on startup.
 
@@ -1434,6 +1454,9 @@ def run_background_services():
     explicitly requests them via agent-manager commands. This prevents unwanted
     file creation in project .claude/ directories.
     See: SystemInstructionsDeployer and agent_deployment.py line 504-509
+
+    Args:
+        force_sync: Force download even if cache is fresh (bypasses ETag).
     """
     # Sync hooks early to ensure up-to-date configuration
     # RATIONALE: Hooks should be synced before other services to fix stale configs
@@ -1444,7 +1467,7 @@ def run_background_services():
     check_mcp_auto_configuration()
     verify_mcp_gateway_startup()
     check_for_updates_async()
-    sync_remote_agents_on_startup()  # Sync agents from remote sources
+    sync_remote_agents_on_startup(force_sync=force_sync)  # Sync agents from remote sources
     show_agent_summary()  # Display agent counts after deployment
 
     # Skills deployment order (precedence: remote > bundled)
@@ -1453,7 +1476,7 @@ def run_background_services():
     # 3. Discover and link runtime skills (user-added skills)
     # This ensures remote skills take precedence over bundled skills when names conflict
     deploy_bundled_skills()  # Base layer: package-bundled skills
-    sync_remote_skills_on_startup()  # Override layer: Git-based skills (takes precedence)
+    sync_remote_skills_on_startup(force_sync=force_sync)  # Override layer: Git-based skills (takes precedence)
     discover_and_link_runtime_skills()  # Discovery: user-added skills
     show_skill_summary()  # Display skill counts after deployment
     verify_and_show_pm_skills()  # PM skills verification and status

claude_mpm/core/output_style_manager.py

@@ -43,7 +43,7 @@ class OutputStyleManager:
 
     Supports two output styles:
     - professional: Default Claude MPM style (claude-mpm.md)
-    - teaching: Adaptive teaching mode (claude-mpm-teach.md)
+    - teaching: Adaptive teaching mode (claude-mpm-teacher.md)
     """
 
     def __init__(self) -> None:
@@ -51,8 +51,8 @@ class OutputStyleManager:
         self.logger = get_logger("output_style_manager")  # type: ignore[misc]
         self.claude_version = self._detect_claude_version()
 
-        # Deploy to ~/.claude/styles/ directory (NOT output-styles/)
-        self.output_style_dir = Path.home() / ".claude" / "styles"
+        # Deploy to ~/.claude/output-styles/ directory (official Claude Code location)
+        self.output_style_dir = Path.home() / ".claude" / "output-styles"
         self.settings_file = Path.home() / ".claude" / "settings.json"
 
         # Style definitions
@@ -68,8 +68,8 @@ class OutputStyleManager:
                 source=Path(__file__).parent.parent
                 / "agents"
                 / "CLAUDE_MPM_TEACHER_OUTPUT_STYLE.md",
-                target=self.output_style_dir / "claude-mpm-teach.md",
-                name="claude-mpm-teach",
+                target=self.output_style_dir / "claude-mpm-teacher.md",
+                name="claude-mpm-teacher",
             ),
         }
 

claude_mpm/services/agents/deployment/agent_template_builder.py

@@ -586,6 +586,14 @@ class AgentTemplateBuilder:
             tags_str = ",".join(metadata["tags"])
             frontmatter_lines.append(f"tags: {tags_str}")
 
+        # CRITICAL: Preserve skills field from template for selective skill deployment
+        # Skills are used by startup.py to determine which skills to deploy
+        skills = template_data.get("skills", [])
+        if skills and isinstance(skills, list):
+            frontmatter_lines.append("skills:")
+            for skill in skills:
+                frontmatter_lines.append(f"- {skill}")
+
         frontmatter_lines.extend(
             [
                 "---",

claude_mpm/services/agents/startup_sync.py

@@ -32,7 +32,9 @@ from claude_mpm.services.agents.sources.git_source_sync_service import (
 logger = logging.getLogger(__name__)
 
 
-def sync_agents_on_startup(config: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+def sync_agents_on_startup(
+    config: Optional[Dict[str, Any]] = None, force_refresh: bool = False
+) -> Dict[str, Any]:
     """Synchronize agents from remote sources on Claude MPM startup.
 
     Design Decision: Single-source support for Stage 1
@@ -44,6 +46,7 @@ def sync_agents_on_startup(config: Optional[Dict[str, Any]] = None) -> Dict[str,
 
     Args:
         config: Optional configuration dictionary. If None, loads from Config singleton.
+        force_refresh: Force download even if cache is fresh (bypasses ETag).
 
     Returns:
         Dictionary with sync results:
@@ -156,7 +159,7 @@ def sync_agents_on_startup(config: Optional[Dict[str, Any]] = None) -> Dict[str,
                 )
 
                 # Perform sync
-                sync_result = sync_service.sync_agents(force_refresh=False)
+                sync_result = sync_service.sync_agents(force_refresh=force_refresh)
 
                 # Aggregate results
                 result["sources_synced"] += 1

claude_mpm/skills/bundled/collaboration/brainstorming/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: Brainstorming Ideas Into Designs
+description: Interactive idea refinement using Socratic method to develop fully-formed designs
+when_to_use: when partner describes any feature or project idea, before writing code or implementation plans
+version: 2.2.0
+progressive_disclosure:
+  level: 1
+  references: []
+  note: Already optimal at 75 lines - intentionally compact, no references needed
+---
+
+# Brainstorming Ideas Into Designs
+
+## Overview
+
+Transform rough ideas into fully-formed designs through structured questioning and alternative exploration.
+
+**Core principle:** Ask questions to understand, explore alternatives, present design incrementally for validation.
+
+**Announce at start:** "I'm using the Brainstorming skill to refine your idea into a design."
+
+## The Process
+
+### Phase 1: Understanding
+- Check current project state in working directory
+- Ask ONE question at a time to refine the idea
+- Prefer multiple choice when possible
+- Gather: Purpose, constraints, success criteria
+
+### Phase 2: Exploration
+- Propose 2-3 different approaches
+- For each: Core architecture, trade-offs, complexity assessment
+- Ask your human partner which approach resonates
+
+### Phase 3: Design Presentation
+- Present in 200-300 word sections
+- Cover: Architecture, components, data flow, error handling, testing
+- Ask after each section: "Does this look right so far?"
+
+### Phase 4: Worktree Setup (for implementation)
+When design is approved and implementation will follow:
+- Announce: "I'm using the Using Git Worktrees skill to set up an isolated workspace."
+- Switch to skills/collaboration/using-git-worktrees
+- Follow that skill's process for directory selection, safety verification, and setup
+- Return here when worktree ready
+
+### Phase 5: Planning Handoff
+Ask: "Ready to create the implementation plan?"
+
+When your human partner confirms (any affirmative response):
+- Announce: "I'm using the Writing Plans skill to create the implementation plan."
+- Switch to skills/collaboration/writing-plans skill
+- Create detailed plan in the worktree
+
+## When to Revisit Earlier Phases
+
+**You can and should go backward when:**
+- Partner reveals new constraint during Phase 2 or 3 → Return to Phase 1 to understand it
+- Validation shows fundamental gap in requirements → Return to Phase 1
+- Partner questions approach during Phase 3 → Return to Phase 2 to explore alternatives
+- Something doesn't make sense → Go back and clarify
+
+**Don't force forward linearly** when going backward would give better results.
+
+## Related Skills
+
+**During exploration:**
+- When approaches have genuine trade-offs: skills/architecture/preserving-productive-tensions
+
+**Before proposing changes to existing code:**
+- Understand why it exists: skills/research/tracing-knowledge-lineages
+
+## Remember
+- One question per message during Phase 1
+- Apply YAGNI ruthlessly
+- Explore 2-3 alternatives before settling
+- Present incrementally, validate as you go
+- Go backward when needed - flexibility > rigid progression
+- Announce skill usage at start