claude-mpm 5.6.4__py3-none-any.whl → 5.6.30__py3-none-any.whl

claude_mpm/services/skills/git_skill_source_manager.py

@@ -16,6 +16,7 @@ Trade-offs:
 - Flexibility: Easy to extend with skills-specific features
 """
 
+import os
 from concurrent.futures import ThreadPoolExecutor, as_completed
 from datetime import datetime, timezone
 from pathlib import Path
@@ -32,6 +33,46 @@ from claude_mpm.services.skills.skill_discovery_service import SkillDiscoverySer
 logger = get_logger(__name__)
 
 
+def _get_github_token(source: Optional[SkillSource] = None) -> Optional[str]:
+    """Get GitHub token with source-specific override support.
+
+    Priority: source.token > GITHUB_TOKEN > GH_TOKEN
+
+    Args:
+        source: Optional SkillSource to check for per-source token
+
+    Returns:
+        GitHub token if found, None otherwise
+
+    Token Resolution:
+        1. If source has token starting with "$", resolve as env var
+        2. If source has direct token, use it (not recommended for security)
+        3. Fall back to GITHUB_TOKEN env var
+        4. Fall back to GH_TOKEN env var
+        5. Return None if no token found
+
+    Security Note:
+        Token is never logged or printed to avoid exposure.
+        Direct tokens in config are discouraged - use env var refs ($VAR_NAME).
+
+    Example:
+        >>> source = SkillSource(..., token="$PRIVATE_TOKEN")
+        >>> token = _get_github_token(source)  # Resolves $PRIVATE_TOKEN from env
+        >>> token = _get_github_token()  # Falls back to GITHUB_TOKEN
+    """
+    # Priority 1: Per-source token (env var reference or direct)
+    if source and source.token:
+        if source.token.startswith("$"):
+            # Env var reference: $VAR_NAME -> os.environ.get("VAR_NAME")
+            env_var_name = source.token[1:]
+            return os.environ.get(env_var_name)
+        # Direct token (not recommended but supported)
+        return source.token
+
+    # Priority 2-3: Global environment variables
+    return os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN")
+
+
 class GitSkillSourceManager:
     """Manages multiple Git-based skill sources with priority resolution.
 
@@ -217,9 +258,21 @@ class GitSkillSourceManager:
             )
 
             # Discover skills in cache
+            self.logger.debug(f"Scanning cache path for skills: {cache_path}")
             discovery_service = SkillDiscoveryService(cache_path)
             discovered_skills = discovery_service.discover_skills()
 
+            # Log discovery results
+            if len(discovered_skills) == 0:
+                self.logger.info(
+                    f"No SKILL.md files found in {cache_path}. "
+                    "Ensure your skill source has SKILL.md files with valid frontmatter."
+                )
+            else:
+                self.logger.debug(
+                    f"Successfully parsed {len(discovered_skills)} skills from {cache_path}"
+                )
+
             # Build result
             result = {
                 "synced": True,
@@ -469,7 +522,7 @@ class GitSkillSourceManager:
         # Step 1: Discover all files via GitHub Tree API (single request)
         # This discovers the COMPLETE repository structure (272 files for skills)
         all_files = self._discover_repository_files_via_tree_api(
-            owner_repo, source.branch
+            owner_repo, source.branch, source
         )
 
         if not all_files:
@@ -504,7 +557,7 @@ class GitSkillSourceManager:
                 raw_url = f"https://raw.githubusercontent.com/{owner_repo}/{source.branch}/{file_path}"
                 cache_file = cache_path / file_path
                 future = executor.submit(
-                    self._download_file_with_etag, raw_url, cache_file, force
+                    self._download_file_with_etag, raw_url, cache_file, force, source
                 )
                 future_to_file[future] = file_path
 
@@ -533,7 +586,7 @@ class GitSkillSourceManager:
         return files_updated, files_cached
 
     def _discover_repository_files_via_tree_api(
-        self, owner_repo: str, branch: str
+        self, owner_repo: str, branch: str, source: Optional[SkillSource] = None
     ) -> List[str]:
         """Discover all files in repository using GitHub Git Tree API.
 
@@ -596,9 +649,17 @@ class GitSkillSourceManager:
             )
             self.logger.debug(f"Fetching commit SHA from {refs_url}")
 
-            refs_response = requests.get(
-                refs_url, headers={"Accept": "application/vnd.github+json"}, timeout=30
-            )
+            # Build headers with authentication if token available
+            headers = {"Accept": "application/vnd.github+json"}
+            token = _get_github_token(source)
+            if token:
+                headers["Authorization"] = f"token {token}"
+                if source and source.token:
+                    self.logger.debug(f"Using source-specific token for {source.id}")
+                else:
+                    self.logger.debug("Using GitHub token for authentication")
+
+            refs_response = requests.get(refs_url, headers=headers, timeout=30)
 
             # Check for rate limiting
             if refs_response.status_code == 403:
@@ -621,7 +682,7 @@ class GitSkillSourceManager:
             self.logger.debug(f"Fetching recursive tree from {tree_url}")
             tree_response = requests.get(
                 tree_url,
-                headers={"Accept": "application/vnd.github+json"},
+                headers=headers,  # Reuse headers with auth from Step 1
                 params=params,
                 timeout=30,
             )
@@ -652,7 +713,11 @@ class GitSkillSourceManager:
         return all_files
 
     def _download_file_with_etag(
-        self, url: str, local_path: Path, force: bool = False
+        self,
+        url: str,
+        local_path: Path,
+        force: bool = False,
+        source: Optional[SkillSource] = None,
     ) -> bool:
         """Download file from URL with ETag caching (thread-safe).
 
@@ -660,6 +725,7 @@ class GitSkillSourceManager:
             url: Raw GitHub URL
             local_path: Local file path to save to
             force: Force download even if cached
+            source: Optional SkillSource for token resolution
 
         Returns:
             True if file was updated, False if cached
@@ -692,6 +758,11 @@ class GitSkillSourceManager:
         if cached_etag and not force:
             headers["If-None-Match"] = cached_etag
 
+        # Add GitHub authentication if token available
+        token = _get_github_token(source)
+        if token:
+            headers["Authorization"] = f"token {token}"
+
         try:
             response = requests.get(url, headers=headers, timeout=30)
 

claude_mpm/services/skills/selective_skill_deployer.py

@@ -50,6 +50,22 @@ logger = get_logger(__name__)
 # Deployment tracking index file
 DEPLOYED_INDEX_FILE = ".mpm-deployed-skills.json"
 
+# Core PM skills that should always be deployed
+# These are referenced in PM_INSTRUCTIONS.md with [SKILL: name] markers
+# Without these skills, PM only sees placeholders, not actual content
+PM_CORE_SKILLS = {
+    "mpm-delegation-patterns",
+    "mpm-verification-protocols",
+    "mpm-tool-usage-guide",
+    "mpm-git-file-tracking",
+    "mpm-pr-workflow",
+    "mpm-ticketing-integration",
+    "mpm-teaching-mode",
+    "mpm-bug-reporting",
+    "mpm-circuit-breaker-enforcement",
+    "mpm-session-management",
+}
+
 # Core skills that are universally useful across all projects
 # These are deployed when skill mapping returns too many skills (>60)
 # Target: ~25-30 core skills for balanced functionality
@@ -376,6 +392,18 @@ def get_required_skills_from_agents(agents_dir: Path) -> Set[str]:
             "(converted slashes to dashes)"
         )
 
+    # Always include PM core skills to ensure PM_INSTRUCTIONS.md markers are resolved
+    # These skills are referenced in PM_INSTRUCTIONS.md and must be deployed
+    # for PM to see actual content instead of [SKILL: name] placeholders
+    before_pm_skills = len(normalized_skills)
+    normalized_skills = normalized_skills | PM_CORE_SKILLS
+    pm_skills_added = len(normalized_skills) - before_pm_skills
+
+    if pm_skills_added > 0:
+        logger.info(
+            f"Added {pm_skills_added} PM core skills to ensure PM_INSTRUCTIONS.md markers resolve"
+        )
+
     return normalized_skills
 
 

claude_mpm/services/skills/skill_discovery_service.py

@@ -188,6 +188,15 @@ class SkillDiscoveryService:
             f"and {len(legacy_md_files)} legacy .md files in {self.skills_dir}"
         )
 
+        # Log first few file paths for debugging
+        if all_skill_files:
+            sample_files = [
+                str(f.relative_to(self.skills_dir)) for f in all_skill_files[:5]
+            ]
+            self.logger.debug(f"Sample skill files: {sample_files}")
+        else:
+            self.logger.debug(f"No SKILL.md or .md files found in {self.skills_dir}")
+
         # Track deployment names to detect collisions
         deployment_names = {}
 
@@ -226,7 +235,14 @@ class SkillDiscoveryService:
             except Exception as e:
                 self.logger.warning(f"Failed to parse skill {skill_file}: {e}")
 
-        self.logger.info(f"Discovered {len(skills)} skills from {self.skills_dir.name}")
+        # Summary logging
+        parsed_count = len(skills)
+        failed_count = len(all_skill_files) - parsed_count
+        self.logger.info(
+            f"Discovered {parsed_count} skills from {self.skills_dir.name} "
+            f"({len(all_skill_files)} files found, {failed_count} failed to parse)"
+        )
+
         return skills
 
     def _parse_skill_file(self, skill_file: Path) -> Optional[Dict[str, Any]]:

claude_mpm/services/skills_deployer.py

@@ -28,7 +28,7 @@ References:
 import json
 import platform
 import shutil
-import subprocess
+import subprocess  # nosec B404 - subprocess needed for safe git operations
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
@@ -653,7 +653,7 @@ class SkillsDeployerService(LoggerMixin):
                     f"Updating existing collection '{collection_name}' at {target_dir}"
                 )
                 try:
-                    result = subprocess.run(
+                    result = subprocess.run(  # nosec B603 B607 - Safe: hardcoded git command
                         ["git", "pull"],
                         cwd=target_dir,
                         capture_output=True,
@@ -684,7 +684,7 @@ class SkillsDeployerService(LoggerMixin):
                 f"Installing new collection '{collection_name}' to {target_dir}"
             )
             try:
-                result = subprocess.run(
+                result = subprocess.run(  # nosec B603 B607 - Safe: hardcoded git command
                     ["git", "clone", repo_url, str(target_dir)],
                     capture_output=True,
                     text=True,
@@ -773,6 +773,32 @@ class SkillsDeployerService(LoggerMixin):
         if isinstance(skills_data, dict):
             flat_skills = []
 
+            # Define valid top-level categories
+            VALID_CATEGORIES = {"universal", "toolchains"}
+
+            # Check for unknown categories and warn user
+            unknown_categories = set(skills_data.keys()) - VALID_CATEGORIES
+            if unknown_categories:
+                # Count skills in unknown categories
+                skipped_count = 0
+                for cat in unknown_categories:
+                    cat_data = skills_data.get(cat, [])
+                    if isinstance(cat_data, list):
+                        skipped_count += len(cat_data)
+                    elif isinstance(cat_data, dict):
+                        # If it's a dict like toolchains, count nested skills
+                        for skills_list in cat_data.values():
+                            if isinstance(skills_list, list):
+                                skipped_count += len(skills_list)
+
+                self.logger.warning(
+                    f"Unknown categories in manifest will be skipped: "
+                    f"{', '.join(sorted(unknown_categories))} ({skipped_count} skills)"
+                )
+                self.logger.info(
+                    f"Valid top-level categories: {', '.join(sorted(VALID_CATEGORIES))}"
+                )
+
             # Add universal skills
             universal_skills = skills_data.get("universal", [])
             if isinstance(universal_skills, list):
@@ -1022,12 +1048,12 @@ class SkillsDeployerService(LoggerMixin):
         """
         try:
             if platform.system() == "Windows":
-                result = subprocess.run(
+                result = subprocess.run(  # nosec B603 B607 - Safe: hardcoded tasklist command
                     ["tasklist"], check=False, capture_output=True, text=True, timeout=5
                 )
                 return "claude" in result.stdout.lower()
             # macOS and Linux
-            result = subprocess.run(
+            result = subprocess.run(  # nosec B603 B607 - Safe: hardcoded ps command
                 ["ps", "aux"], check=False, capture_output=True, text=True, timeout=5
             )
             # Look for "Claude Code" or "claude-code" process

claude_mpm/skills/__init__.py

@@ -24,7 +24,7 @@ Legacy System (maintained for compatibility):
 from .agent_skills_injector import AgentSkillsInjector
 
 # Legacy System (maintained for compatibility)
-from .registry import Skill, SkillsRegistry, get_registry
+from .registry import Skill, SkillsRegistry, get_registry, validate_agentskills_spec
 from .skill_manager import SkillManager
 from .skills_registry import SkillsRegistry as SkillsRegistryHelper
 from .skills_service import SkillsService
@@ -39,4 +39,5 @@ __all__ = [
     # New Skills Integration System
     "SkillsService",
     "get_registry",
+    "validate_agentskills_spec",
 ]

claude_mpm/skills/bundled/pm/mpm-session-pause/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: mpm-session-pause
+description: Pause session and save current work state for later resume
+user-invocable: true
+version: "1.0.0"
+category: mpm-command
+tags: [mpm-command, session, pm-recommended]
+---
+
+# /mpm-pause
+
+Pause the current session and save all work state for later resume.
+
+## What This Does
+
+When invoked, this skill:
+1. Captures current work state (todos, git status, context summary)
+2. Creates session file at `.claude-mpm/sessions/session-{timestamp}.md`
+3. Updates `.claude-mpm/sessions/LATEST-SESSION.txt` pointer
+4. Optionally commits session state to git
+5. Shows user the session file path for later resume
+
+## Usage
+
+```
+/mpm-pause [optional message describing current work]
+```
+
+**Examples:**
+```
+/mpm-pause
+/mpm-pause Working on authentication refactor, about to test login flow
+/mpm-pause Need to context switch to urgent bug fix
+```
+
+## Implementation
+
+**Execute the following Python code to pause the session:**
+
+```python
+from pathlib import Path
+from claude_mpm.services.cli.session_pause_manager import SessionPauseManager
+
+# Optional: Get message from user's command
+# If user provided message after /mpm-pause, extract it
+# Otherwise, message = None
+
+# Create session pause manager
+manager = SessionPauseManager(project_path=Path.cwd())
+
+# Create pause session
+session_id = manager.create_pause_session(
+    message=message,  # Optional context message
+    skip_commit=False,  # Will commit to git if in a repo
+    export_path=None,  # No additional export needed
+)
+
+# Report success to user
+print(f"✅ Session paused successfully!")
+print(f"")
+print(f"Session ID: {session_id}")
+print(f"Session files:")
+print(f"  - .claude-mpm/sessions/{session_id}.md (human-readable)")
+print(f"  - .claude-mpm/sessions/{session_id}.json (machine-readable)")
+print(f"  - .claude-mpm/sessions/{session_id}.yaml (config format)")
+print(f"")
+print(f"Quick resume:")
+print(f"  /mpm-resume")
+print(f"")
+print(f"View session context:")
+print(f"  cat .claude-mpm/sessions/LATEST-SESSION.txt")
+print(f"  cat .claude-mpm/sessions/{session_id}.md")
+```
+
+## What Gets Saved
+
+**Session State:**
+- Session ID and timestamp
+- Current working directory
+- Git branch, recent commits, and file status
+- Primary task and current phase
+- Context message (if provided)
+
+**Resume Instructions:**
+- Quick-start commands
+- Validation commands
+- Files to review
+
+**File Formats:**
+- `.md` - Human-readable markdown (for reading)
+- `.json` - Machine-readable (for tooling)
+- `.yaml` - Human-readable config (for editing)
+
+## Session File Location
+
+All session files are stored in:
+```
+.claude-mpm/sessions/
+├── LATEST-SESSION.txt          # Pointer to most recent session
+├── session-YYYYMMDD-HHMMSS.md
+├── session-YYYYMMDD-HHMMSS.json
+└── session-YYYYMMDD-HHMMSS.yaml
+```
+
+## Token Budget
+
+**Token usage:** ~5-10k tokens to execute (2-5% of context budget)
+
+**Benefit:** Saves all remaining context for future resume, allowing you to:
+- Context switch to urgent tasks
+- Take a break and resume later
+- Archive current work state before major changes
+
+## Resume Later
+
+To resume this session:
+```
+/mpm-resume
+```
+
+Or manually:
+```bash
+cat .claude-mpm/sessions/LATEST-SESSION.txt
+cat .claude-mpm/sessions/session-YYYYMMDD-HHMMSS.md
+```
+
+## Git Integration
+
+If in a git repository, the session will be automatically committed with message:
+```
+session: pause at YYYY-MM-DD HH:MM:SS
+
+Session ID: session-YYYYMMDD-HHMMSS
+Context: [your optional message]
+```
+
+## Use Cases
+
+**Context switching:**
+```
+/mpm-pause Switching to urgent production bug
+```
+
+**End of work session:**
+```
+/mpm-pause Completed API refactor, ready for testing tomorrow
+```
+
+**Before major changes:**
+```
+/mpm-pause Saving state before attempting risky refactor
+```
+
+**When approaching context limit:**
+```
+/mpm-pause Hit 150k tokens, starting fresh session
+```
+
+## Related Commands
+
+- `/mpm-resume` - Resume from most recent paused session
+- `/mpm-init resume` - Alternative resume command
+- See `docs/features/session-auto-resume.md` for auto-pause behavior
+
+## Notes
+
+- Session files are project-local (not synced across machines)
+- Git commit is optional (automatically skipped if not a repo)
+- LATEST-SESSION.txt always points to most recent session
+- Session format compatible with auto-pause feature (70% context trigger)