claude-mpm 4.0.31__tar.gz → 4.0.32__tar.gz

claude_mpm-4.0.32/BUILD_NUMBER

@@ -0,0 +1 @@
+294

{claude_mpm-4.0.31 → claude_mpm-4.0.32}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-mpm
-Version: 4.0.31
+Version: 4.0.32
 Summary: Claude Multi-Agent Project Manager - Orchestrate Claude with agent delegation and ticket tracking
 Author-email: Bob Matsuoka <bob@matsuoka.com>
 Maintainer: Claude MPM Team

claude_mpm-4.0.32/VERSION

@@ -0,0 +1 @@
+4.0.32

{claude_mpm-4.0.31 → claude_mpm-4.0.32}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "claude-mpm"
-version = "4.0.31"
+version = "4.0.32"
 description = "Claude Multi-Agent Project Manager - Orchestrate Claude with agent delegation and ticket tracking"
 readme = "README.md"
 requires-python = ">=3.8"
@@ -183,7 +183,7 @@ asyncio_mode = "auto"
 
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "4.0.31"
+version = "4.0.32"
 version_files = [
     "VERSION",
     "src/claude_mpm/VERSION",

{claude_mpm-4.0.31 → claude_mpm-4.0.32}/src/claude_mpm/agents/BASE_AGENT_TEMPLATE.md

@@ -76,23 +76,26 @@ End every response with this structured data:
 
 **Memory Guidelines:**
 - The `remember` field should contain a list of strings or `null`
-- Only include memories when you learn something NEW about THIS project
-- Memories are automatically extracted and added to your agent memory file
-- Each memory item should be a concise, specific fact (under 100 characters)
-- Memories accumulate over time - you don't need to repeat previous learnings
-
-**Good memory examples:**
-- "Memory system uses .claude-mpm/memories/ for storage"
-- "Service layer has 5 domains: core, agent, communication, project, infra"
-- "All services implement explicit interfaces for DI"
-- "Agent templates stored as JSON in src/claude_mpm/agents/templates/"
-- "Project uses lazy loading for performance optimization"
-
-**Bad memory examples (too generic or obvious):**
-- "Python uses indentation" (generic programming knowledge)
-- "Always test code" (general best practice)
-- "Files should have docstrings" (not project-specific)
-- "This is a Python project" (too obvious)
+- Only capture memories when:
+  - You discover SPECIFIC facts, files, or code patterns not easily determined from codebase/docs
+  - User explicitly instructs you to remember ("remember", "don't forget", "memorize")
+- Memories should be PROJECT-based only, never user-specific
+- Each memory should be concise and specific (under 100 characters)
+- When memories change, include MEMORIES section in response with complete optimized set
+
+**What to capture:**
+- Undocumented configuration details or requirements
+- Non-obvious project conventions or patterns
+- Critical integration points or dependencies
+- Specific version requirements or constraints
+- Hidden or hard-to-find implementation details
+
+**What NOT to capture:**
+- Information easily found in documentation
+- Standard programming practices
+- Obvious project structure or file locations
+- Temporary task-specific details
+- User preferences or personal information
 
 ## Quick Reference
 
@@ -153,17 +156,22 @@ Always prefix tasks with your agent name:
 - **completed**: Finished successfully
 - **BLOCKED**: Include reason for blockage
 
-## Memory Protocol
+## Memory Response Protocol
 
-Review memory at task start. Add valuable learnings using:
-```
-# Add To Memory:
-Type: [pattern|architecture|guideline|mistake|strategy|integration|performance|context]
-Content: [5-100 characters]
-#
+When you update memories, include a MEMORIES section in your response:
+```json
+{
+  "task": "Description of task",
+  "results": "What was accomplished",
+  "MEMORIES": [
+    "Complete list of all memories including new ones",
+    "Each memory as a separate string",
+    "Optimized and deduplicated"
+  ]
+}
 ```
 
-Focus on universal learnings, not task-specific details.
+Only include MEMORIES section when memories actually change.
 
 ## Remember
 You're a specialist in your domain. Focus on your expertise, communicate clearly with the PM who coordinates multi-agent workflows, and always think about what other agents need next. Your accumulated memories help you become more effective over time.

{claude_mpm-4.0.31 → claude_mpm-4.0.32}/src/claude_mpm/agents/INSTRUCTIONS.md

@@ -108,18 +108,22 @@ When completing tasks, all agents should structure their responses with:
 **Key Changes**: 
   - <change 1>
   - <change 2>
-**Remember**: <list of universal learnings, or null if none>
+**Remember**: <list of project-specific learnings, or null if none>
   - Format: ["Learning 1", "Learning 2"] or null
-  - ONLY include information that should be remembered for ALL future requests
-  - Most tasks won't generate universal memories
+  - Only capture when discovering SPECIFIC facts not easily found in docs
+  - Or when user explicitly says "remember", "don't forget", "memorize"
   - Examples of valid memories:
-    - "This project uses Python 3.11 with strict type checking"
-    - "All API endpoints require JWT authentication"
-    - "Database queries must use parameterized statements"
-  - Not valid for memory (too specific/temporary):
-    - "Fixed bug in user.py line 42"
-    - "Added login endpoint"
-    - "Refactored payment module"
+    - "Database connection pool size must be exactly 10 for stability"
+    - "API rate limit is 100/min (undocumented)"
+    - "Legacy auth system requires MD5 hash for backwards compatibility"
+  - Not valid for memory (easily discoverable):
+    - "This project uses Python 3.11"
+    - "API endpoints are in /api directory"
+    - "Tests use pytest framework"
+**MEMORIES**: <complete optimized memory list when memories change>
+  - Include this field ONLY when memories are updated
+  - List ALL memories (existing + new), deduplicated and optimized
+  - Format: ["Memory 1", "Memory 2", ...]
 **Issues/Notes**: <any problems encountered or important observations>
 ```
 

{claude_mpm-4.0.31 → claude_mpm-4.0.32}/src/claude_mpm/core/framework_loader.py

@@ -34,9 +34,41 @@ class FrameworkLoader:
 
     This component handles:
     1. Finding the framework (claude-multiagent-pm)
-    2. Loading INSTRUCTIONS.md instructions
+    2. Loading custom instructions from .claude-mpm/ directories
     3. Preparing agent definitions
     4. Formatting for injection
+    
+    Custom Instructions Loading:
+    The framework loader supports custom instructions through .claude-mpm/ directories.
+    It NEVER reads from .claude/ directories to avoid conflicts with Claude Code.
+    
+    File Loading Precedence (highest to lowest):
+    
+    INSTRUCTIONS.md:
+      1. Project: ./.claude-mpm/INSTRUCTIONS.md
+      2. User: ~/.claude-mpm/INSTRUCTIONS.md
+      3. System: (built-in framework instructions)
+    
+    WORKFLOW.md:
+      1. Project: ./.claude-mpm/WORKFLOW.md
+      2. User: ~/.claude-mpm/WORKFLOW.md
+      3. System: src/claude_mpm/agents/WORKFLOW.md
+    
+    MEMORY.md:
+      1. Project: ./.claude-mpm/MEMORY.md
+      2. User: ~/.claude-mpm/MEMORY.md
+      3. System: src/claude_mpm/agents/MEMORY.md
+    
+    Actual Memories:
+      - User: ~/.claude-mpm/memories/PM_memories.md
+      - Project: ./.claude-mpm/memories/PM_memories.md (overrides user)
+      - Agent memories: *_memories.md files (only loaded if agent is deployed)
+    
+    Important Notes:
+    - Project-level files always override user-level files
+    - User-level files always override system defaults
+    - The framework NEVER reads from .claude/ directories
+    - Custom instructions are clearly labeled with their source level
     """
 
     def __init__(
@@ -349,28 +381,43 @@ class FrameworkLoader:
 
     def _load_workflow_instructions(self, content: Dict[str, Any]) -> None:
         """
-        Load WORKFLOW.md with project-specific override support.
+        Load WORKFLOW.md from .claude-mpm directories.
 
-        Precedence:
-        1. Project-specific: .claude-mpm/agents/WORKFLOW.md
-        2. System default: src/claude_mpm/agents/WORKFLOW.md or packaged
+        Precedence (highest to lowest):
+        1. Project-specific: ./.claude-mpm/WORKFLOW.md
+        2. User-specific: ~/.claude-mpm/WORKFLOW.md
+        3. System default: src/claude_mpm/agents/WORKFLOW.md or packaged
+        
+        NOTE: We do NOT load from .claude/ directories to avoid conflicts.
 
         Args:
             content: Dictionary to update with workflow instructions
         """
-        # Check for project-specific workflow first
-        project_workflow_path = Path.cwd() / ".claude-mpm" / "agents" / "WORKFLOW.md"
+        # Check for project-specific WORKFLOW.md first (highest priority)
+        project_workflow_path = Path.cwd() / ".claude-mpm" / "WORKFLOW.md"
         if project_workflow_path.exists():
             loaded_content = self._try_load_file(
                 project_workflow_path, "project-specific WORKFLOW.md"
             )
             if loaded_content:
                 content["workflow_instructions"] = loaded_content
-                content["project_workflow"] = "project"
-                self.logger.info("Using project-specific WORKFLOW.md")
+                content["workflow_instructions_level"] = "project"
+                self.logger.info("Using project-specific workflow instructions from .claude-mpm/WORKFLOW.md")
+                return
+        
+        # Check for user-specific WORKFLOW.md (medium priority)
+        user_workflow_path = Path.home() / ".claude-mpm" / "WORKFLOW.md"
+        if user_workflow_path.exists():
+            loaded_content = self._try_load_file(
+                user_workflow_path, "user-specific WORKFLOW.md"
+            )
+            if loaded_content:
+                content["workflow_instructions"] = loaded_content
+                content["workflow_instructions_level"] = "user"
+                self.logger.info("Using user-specific workflow instructions from ~/.claude-mpm/WORKFLOW.md")
                 return
 
-        # Fall back to system workflow
+        # Fall back to system workflow (lowest priority)
         if self.framework_path and self.framework_path != Path("__PACKAGED__"):
             system_workflow_path = (
                 self.framework_path / "src" / "claude_mpm" / "agents" / "WORKFLOW.md"
@@ -381,33 +428,48 @@ class FrameworkLoader:
                 )
                 if loaded_content:
                     content["workflow_instructions"] = loaded_content
-                    content["project_workflow"] = "system"
-                    self.logger.info("Using system WORKFLOW.md")
+                    content["workflow_instructions_level"] = "system"
+                    self.logger.info("Using system workflow instructions")
 
     def _load_memory_instructions(self, content: Dict[str, Any]) -> None:
         """
-        Load MEMORY.md with project-specific override support.
+        Load MEMORY.md from .claude-mpm directories.
 
-        Precedence:
-        1. Project-specific: .claude-mpm/agents/MEMORY.md
-        2. System default: src/claude_mpm/agents/MEMORY.md or packaged
+        Precedence (highest to lowest):
+        1. Project-specific: ./.claude-mpm/MEMORY.md
+        2. User-specific: ~/.claude-mpm/MEMORY.md
+        3. System default: src/claude_mpm/agents/MEMORY.md or packaged
+        
+        NOTE: We do NOT load from .claude/ directories to avoid conflicts.
 
         Args:
             content: Dictionary to update with memory instructions
         """
-        # Check for project-specific memory instructions first
-        project_memory_path = Path.cwd() / ".claude-mpm" / "agents" / "MEMORY.md"
+        # Check for project-specific MEMORY.md first (highest priority)
+        project_memory_path = Path.cwd() / ".claude-mpm" / "MEMORY.md"
         if project_memory_path.exists():
             loaded_content = self._try_load_file(
                 project_memory_path, "project-specific MEMORY.md"
             )
             if loaded_content:
                 content["memory_instructions"] = loaded_content
-                content["project_memory"] = "project"
-                self.logger.info("Using project-specific MEMORY.md")
+                content["memory_instructions_level"] = "project"
+                self.logger.info("Using project-specific memory instructions from .claude-mpm/MEMORY.md")
+                return
+        
+        # Check for user-specific MEMORY.md (medium priority)
+        user_memory_path = Path.home() / ".claude-mpm" / "MEMORY.md"
+        if user_memory_path.exists():
+            loaded_content = self._try_load_file(
+                user_memory_path, "user-specific MEMORY.md"
+            )
+            if loaded_content:
+                content["memory_instructions"] = loaded_content
+                content["memory_instructions_level"] = "user"
+                self.logger.info("Using user-specific memory instructions from ~/.claude-mpm/MEMORY.md")
                 return
 
-        # Fall back to system memory instructions
+        # Fall back to system memory instructions (lowest priority)
         if self.framework_path and self.framework_path != Path("__PACKAGED__"):
             system_memory_path = (
                 self.framework_path / "src" / "claude_mpm" / "agents" / "MEMORY.md"
@@ -418,8 +480,8 @@ class FrameworkLoader:
                 )
                 if loaded_content:
                     content["memory_instructions"] = loaded_content
-                    content["project_memory"] = "system"
-                    self.logger.info("Using system MEMORY.md")
+                    content["memory_instructions_level"] = "system"
+                    self.logger.info("Using system memory instructions")
     
     def _get_deployed_agents(self) -> set:
         """
@@ -859,9 +921,11 @@ class FrameworkLoader:
             "working_claude_md": "",
             "framework_instructions": "",
             "workflow_instructions": "",
-            "project_workflow": "",
+            "workflow_instructions_level": "",  # Track source level
             "memory_instructions": "",
-            "project_memory": "",
+            "memory_instructions_level": "",  # Track source level
+            "project_workflow": "",  # Deprecated, use workflow_instructions_level
+            "project_memory": "",  # Deprecated, use memory_instructions_level
             "actual_memories": "",  # Add field for actual memories from PM_memories.md
         }
 
@@ -1141,16 +1205,22 @@ class FrameworkLoader:
                 workflow_content = self._strip_metadata_comments(
                     self.framework_content["workflow_instructions"]
                 )
-                instructions += f"\n\n{workflow_content}\n"
-                # Note: project-specific workflow is being used (logged elsewhere)
+                level = self.framework_content.get("workflow_instructions_level", "system")
+                if level != "system":
+                    instructions += f"\n\n## Workflow Instructions ({level} level)\n\n"
+                    instructions += "**The following workflow instructions override system defaults:**\n\n"
+                instructions += f"{workflow_content}\n"
 
             # Add MEMORY.md after workflow instructions
             if self.framework_content.get("memory_instructions"):
                 memory_content = self._strip_metadata_comments(
                     self.framework_content["memory_instructions"]
                 )
-                instructions += f"\n\n{memory_content}\n"
-                # Note: project-specific memory instructions being used (logged elsewhere)
+                level = self.framework_content.get("memory_instructions_level", "system")
+                if level != "system":
+                    instructions += f"\n\n## Memory Instructions ({level} level)\n\n"
+                    instructions += "**The following memory instructions override system defaults:**\n\n"
+                instructions += f"{memory_content}\n"
             
             # Add actual PM memories after memory instructions
             if self.framework_content.get("actual_memories"):

{claude_mpm-4.0.31 → claude_mpm-4.0.32}/src/claude_mpm/services/agents/deployment/agent_deployment.py

@@ -416,8 +416,12 @@ class AgentDeploymentService(ConfigServiceBase, AgentDeploymentInterface):
                     source_info=source_info,
                 )
 
-            # Deploy system instructions and framework files
-            self._deploy_system_instructions(agents_dir, force_rebuild, results)
+            # CRITICAL: System instructions deployment disabled to prevent automatic file creation
+            # The system should NEVER automatically write INSTRUCTIONS.md, MEMORY.md, WORKFLOW.md
+            # to .claude/ directory. These files should only be created when explicitly requested
+            # by the user through agent-manager commands.
+            # See deploy_system_instructions_explicit() for manual deployment.
+            # self._deploy_system_instructions(agents_dir, force_rebuild, results)
 
             self.logger.info(
                 f"Deployed {len(results['deployed'])} agents, "
@@ -617,6 +621,65 @@ class AgentDeploymentService(ConfigServiceBase, AgentDeploymentInterface):
             target_dir, force_rebuild, results, self._is_project_specific_deployment()
         )
 
+    def deploy_system_instructions_explicit(
+        self, target_dir: Optional[Path] = None, force_rebuild: bool = False
+    ) -> Dict[str, Any]:
+        """
+        Explicitly deploy system instructions when requested by user.
+        
+        This method should ONLY be called when the user explicitly requests
+        deployment of system instructions through agent-manager commands.
+        It will deploy INSTRUCTIONS.md, MEMORY.md, and WORKFLOW.md to .claude-mpm/
+        directory (not .claude/).
+        
+        Args:
+            target_dir: Target directory for deployment (defaults to .claude-mpm/)
+            force_rebuild: Force rebuild even if files exist
+            
+        Returns:
+            Dict with deployment results
+        """
+        results = {
+            "deployed": [],
+            "updated": [],
+            "skipped": [],
+            "errors": [],
+        }
+        
+        try:
+            # Use .claude-mpm/ instead of .claude/
+            if target_dir is None:
+                if self._is_project_specific_deployment():
+                    target_dir = self.working_directory / ".claude-mpm"
+                else:
+                    target_dir = Path.home() / ".claude-mpm"
+            
+            # Ensure directory exists
+            target_dir.mkdir(parents=True, exist_ok=True)
+            
+            # Deploy using the modified deployer (targeting .claude-mpm/)
+            from .system_instructions_deployer import SystemInstructionsDeployer
+            deployer = SystemInstructionsDeployer(self.logger, self.working_directory)
+            
+            # We'll need to pass .claude-mpm as the target
+            deployer.deploy_system_instructions_to_claude_mpm(
+                target_dir, force_rebuild, results, self._is_project_specific_deployment()
+            )
+            
+            self.logger.info(
+                f"Explicitly deployed system instructions to {target_dir}: "
+                f"deployed={len(results['deployed'])}, "
+                f"updated={len(results['updated'])}, "
+                f"skipped={len(results['skipped'])}"
+            )
+            
+        except Exception as e:
+            error_msg = f"Failed to deploy system instructions: {e}"
+            self.logger.error(error_msg)
+            results["errors"].append(error_msg)
+        
+        return results
+
     def _convert_yaml_to_md(self, target_dir: Path) -> Dict[str, Any]:
         """Convert existing YAML agent files to MD format with YAML frontmatter."""
         return self.format_converter.convert_yaml_to_md(target_dir)

{claude_mpm-4.0.31 → claude_mpm-4.0.32}/src/claude_mpm/services/agents/deployment/system_instructions_deployer.py

@@ -17,6 +17,78 @@ class SystemInstructionsDeployer:
         self.logger = logger
         self.working_directory = working_directory
 
+    def deploy_system_instructions_to_claude_mpm(
+        self,
+        target_dir: Path,
+        force_rebuild: bool,
+        results: Dict[str, Any],
+        is_project_specific: bool,
+    ) -> None:
+        """
+        Deploy system instructions to .claude-mpm/ directory (not .claude/).
+        
+        This method should ONLY be called when explicitly requested by the user.
+        It deploys INSTRUCTIONS.md, WORKFLOW.md, and MEMORY.md files to .claude-mpm/
+        
+        Args:
+            target_dir: Target directory (should be .claude-mpm/)
+            force_rebuild: Force rebuild even if exists
+            results: Results dictionary to update
+            is_project_specific: Whether this is a project-specific deployment
+        """
+        try:
+            # Framework files to deploy
+            framework_files = [
+                ("INSTRUCTIONS.md", "INSTRUCTIONS.md"),
+                ("WORKFLOW.md", "WORKFLOW.md"),
+                ("MEMORY.md", "MEMORY.md"),
+            ]
+            
+            # Find the agents directory with framework files
+            from claude_mpm.config.paths import paths
+            agents_path = paths.agents_dir
+            
+            for source_name, target_name in framework_files:
+                source_path = agents_path / source_name
+                
+                if not source_path.exists():
+                    self.logger.warning(f"Framework file not found: {source_path}")
+                    continue
+                
+                target_file = target_dir / target_name
+                
+                # Check if update needed
+                if not force_rebuild and target_file.exists():
+                    # Compare modification times
+                    if target_file.stat().st_mtime >= source_path.stat().st_mtime:
+                        results["skipped"].append(target_name)
+                        self.logger.debug(f"Framework file {target_name} up to date")
+                        continue
+                
+                # Read and deploy framework file
+                file_content = source_path.read_text()
+                target_file.write_text(file_content)
+                
+                # Track deployment
+                file_existed = target_file.exists()
+                deployment_info = {
+                    "name": target_name,
+                    "template": str(source_path),
+                    "target": str(target_file),
+                }
+                
+                if file_existed:
+                    results["updated"].append(deployment_info)
+                    self.logger.info(f"Updated framework file in .claude-mpm: {target_name}")
+                else:
+                    results["deployed"].append(deployment_info)
+                    self.logger.info(f"Deployed framework file to .claude-mpm: {target_name}")
+                    
+        except Exception as e:
+            error_msg = f"Failed to deploy system instructions to .claude-mpm: {e}"
+            self.logger.error(error_msg)
+            results["errors"].append(error_msg)
+
     def deploy_system_instructions(
         self,
         target_dir: Path,