claude-mpm 5.6.1__py3-none-any.whl → 5.6.76__py3-none-any.whl

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)

claude_mpm/skills/registry.py

@@ -14,35 +14,144 @@ logger = get_logger(__name__)
 
 @dataclass
 class Skill:
-    """Represents a skill that can be used by agents."""
-
+    """Represents a skill that can be used by agents.
+
+    Supports agentskills.io specification with backward compatibility for legacy claude-mpm format.
+
+    Spec fields (agentskills.io):
+    - name: Required, 1-64 chars, lowercase alphanumeric + hyphens
+    - description: Required, 1-1024 chars
+    - license: Optional, license name or reference
+    - compatibility: Optional, max 500 chars, environment requirements
+    - metadata: Optional, key-value mapping for arbitrary data
+    - allowed_tools: Optional, list of pre-approved tools
+
+    Internal fields:
+    - path: Path to skill file
+    - content: Skill content (markdown)
+    - source: Origin of skill ('bundled', 'user', 'project', 'pm')
+    - version: Skill version (from metadata.version or top-level)
+    - skill_id: Internal ID (defaults to name)
+    - agent_types: Which agent types can use this skill
+    - updated_at: Last update timestamp (from metadata.updated)
+    - tags: Tags for discovery (from metadata.tags or top-level)
+
+    Claude-mpm extensions (preserved for backward compat):
+    - category: Skill category for organization
+    - toolchain: Associated toolchain (python, javascript, etc.)
+    - progressive_disclosure: Progressive disclosure configuration
+    - user_invocable: Whether skill can be manually invoked
+    """
+
+    # Core spec fields (agentskills.io)
     name: str
-    path: Path
-    content: str
-    source: str  # 'bundled', 'user', or 'project'
-
-    # Version tracking fields
-    version: str = "0.1.0"
-    skill_id: str = ""  # defaults to name if not provided
-
-    # Existing fields
-    description: str = ""
+    description: str
+    license: Optional[str] = None
+    compatibility: Optional[str] = None
+    metadata: Dict[str, Any] = None
+    allowed_tools: List[str] = None
+
+    # Internal fields (not in frontmatter spec)
+    path: Path = None
+    content: str = ""
+    source: str = "bundled"  # 'bundled', 'user', 'project', 'pm'
+
+    # Derived fields (from metadata or fallback)
+    version: str = "0.1.0"  # From metadata.version or top-level
+    skill_id: str = ""  # Internal ID (defaults to name)
     agent_types: List[str] = None  # Which agent types can use this skill
+    updated_at: Optional[str] = None  # From metadata.updated
+    tags: List[str] = None  # From metadata.tags or top-level
 
-    # Optional metadata
-    updated_at: Optional[str] = None
-    tags: List[str] = None
+    # Claude-mpm extensions (preserved for backward compat)
+    category: Optional[str] = None
+    toolchain: Optional[str] = None
+    progressive_disclosure: Optional[Dict[str, Any]] = None
+    user_invocable: bool = False
 
     def __post_init__(self):
         """Initialize default values if not provided."""
+        if self.metadata is None:
+            self.metadata = {}
         if self.agent_types is None:
             self.agent_types = []
         if self.tags is None:
             self.tags = []
+        if self.allowed_tools is None:
+            self.allowed_tools = []
         if not self.skill_id:
             self.skill_id = self.name
 
 
+def validate_agentskills_spec(skill: Skill) -> tuple[bool, List[str]]:
+    """Validate skill against agentskills.io specification.
+
+    Args:
+        skill: Skill object to validate
+
+    Returns:
+        Tuple of (is_valid, list_of_warnings)
+        - is_valid: True if skill meets spec requirements
+        - warnings: List of warning messages for spec violations
+    """
+    warnings = []
+
+    # Validate name (required field)
+    if not skill.name:
+        warnings.append("Missing required field: name")
+        return False, warnings
+
+    # Validate name format: lowercase alphanumeric + hyphens, no leading/trailing hyphens
+    if not re.match(r"^[a-z0-9]+(-[a-z0-9]+)*$", skill.name):
+        warnings.append(
+            f"Invalid name format: '{skill.name}' (must be lowercase alphanumeric with hyphens, "
+            "no leading/trailing hyphens, no consecutive hyphens)"
+        )
+
+    # Validate name length (max 64 chars)
+    if len(skill.name) > 64:
+        warnings.append(
+            f"Name too long: {len(skill.name)} chars (max 64 per agentskills.io spec)"
+        )
+
+    # Validate description (required field)
+    if not skill.description:
+        warnings.append("Missing required field: description")
+        return False, warnings
+
+    # Validate description length (1-1024 chars)
+    desc_len = len(skill.description)
+    if desc_len < 1 or desc_len > 1024:
+        warnings.append(
+            f"Description length {desc_len} chars is outside spec range (1-1024 chars)"
+        )
+
+    # Validate compatibility length (max 500 chars)
+    if skill.compatibility and len(skill.compatibility) > 500:
+        warnings.append(
+            f"Compatibility field too long: {len(skill.compatibility)} chars (max 500)"
+        )
+
+    # Validate metadata is dict
+    if skill.metadata is not None and not isinstance(skill.metadata, dict):
+        warnings.append("Metadata must be a key-value mapping (dict)")
+
+    # Check for spec-compliant metadata structure
+    spec_metadata_fields = ["version", "author", "updated", "tags"]
+    for field in spec_metadata_fields:
+        if hasattr(skill, field):
+            field_value = getattr(skill, field)
+            if field_value and field not in skill.metadata:
+                warnings.append(
+                    f"Field '{field}' should be in metadata block per agentskills.io spec "
+                    f"(found as top-level field)"
+                )
+
+    # Valid if no errors (only warnings allowed)
+    is_valid = len(warnings) == 0 or all("should be in metadata" in w for w in warnings)
+    return is_valid, warnings
+
+
 class SkillsRegistry:
     """Registry for managing skills across all tiers."""
 
@@ -54,7 +163,10 @@ class SkillsRegistry:
         self._load_project_skills()
 
     def _parse_skill_frontmatter(self, content: str) -> Dict[str, Any]:
-        """Parse YAML frontmatter from skill markdown file.
+        """Parse YAML frontmatter from skill markdown file with spec validation.
+
+        Supports both agentskills.io spec format and legacy claude-mpm format
+        with automatic migration.
 
         Returns:
             Dict with frontmatter fields or empty dict if no frontmatter
@@ -70,11 +182,150 @@ class SkillsRegistry:
 
         try:
             frontmatter = yaml.safe_load(match.group(1))
-            return frontmatter or {}
+            if not frontmatter:
+                return {}
+
+            # Apply backward compatibility migration
+            return self._apply_backward_compatibility(frontmatter)
         except yaml.YAMLError as e:
             logger.warning(f"Failed to parse skill frontmatter: {e}")
             return {}
 
+    def _apply_backward_compatibility(
+        self, frontmatter: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """Apply backward compatibility transformations to legacy frontmatter.
+
+        Auto-migrates legacy claude-mpm fields to agentskills.io spec format:
+        - version → metadata.version
+        - author → metadata.author
+        - updated → metadata.updated
+        - tags → metadata.tags (if not already present)
+
+        Args:
+            frontmatter: Parsed frontmatter dict
+
+        Returns:
+            Transformed frontmatter with spec-compliant structure
+        """
+        # Initialize metadata if not present
+        if "metadata" not in frontmatter:
+            frontmatter["metadata"] = {}
+
+        metadata = frontmatter["metadata"]
+
+        # Auto-migrate version (top-level → metadata.version)
+        if "version" in frontmatter and "version" not in metadata:
+            metadata["version"] = frontmatter["version"]
+            logger.debug(
+                f"Auto-migrated 'version' to metadata for skill '{frontmatter.get('name', 'unknown')}'"
+            )
+
+        # Auto-migrate author (top-level → metadata.author)
+        if "author" in frontmatter and "author" not in metadata:
+            metadata["author"] = frontmatter["author"]
+            logger.debug(
+                f"Auto-migrated 'author' to metadata for skill '{frontmatter.get('name', 'unknown')}'"
+            )
+
+        # Auto-migrate updated (top-level → metadata.updated)
+        if "updated" in frontmatter and "updated" not in metadata:
+            metadata["updated"] = frontmatter["updated"]
+            logger.debug(
+                f"Auto-migrated 'updated' to metadata for skill '{frontmatter.get('name', 'unknown')}'"
+            )
+
+        # Auto-migrate tags (top-level → metadata.tags)
+        if "tags" in frontmatter and "tags" not in metadata:
+            metadata["tags"] = frontmatter["tags"]
+            logger.debug(
+                f"Auto-migrated 'tags' to metadata for skill '{frontmatter.get('name', 'unknown')}'"
+            )
+
+        # Parse allowed-tools from space-delimited string to list
+        if "allowed-tools" in frontmatter:
+            allowed_tools = frontmatter["allowed-tools"]
+            if isinstance(allowed_tools, str):
+                frontmatter["allowed-tools"] = allowed_tools.split()
+
+        # Set default compatibility for claude-code if not present
+        if "compatibility" not in frontmatter:
+            frontmatter["compatibility"] = "claude-code"
+
+        return frontmatter
+
+    def _create_skill_from_frontmatter(
+        self, frontmatter: Dict[str, Any], path: Path, content: str, source: str
+    ) -> Optional[Skill]:
+        """Create Skill object from frontmatter with spec compliance.
+
+        Args:
+            frontmatter: Parsed and migrated frontmatter dict
+            path: Path to skill file
+            content: Full skill content
+            source: Source type ('bundled', 'user', 'project', 'pm')
+
+        Returns:
+            Skill object or None if required fields missing
+        """
+        # Extract spec fields (required)
+        name = frontmatter.get("name")
+        description = frontmatter.get("description", "")
+
+        # If name not in frontmatter, use filename stem
+        if not name:
+            name = path.stem
+
+        # If description not in frontmatter, extract from content
+        if not description:
+            description = self._extract_description(content)
+
+        # Validate required fields
+        if not name or not description:
+            logger.warning(
+                f"Skipping skill at {path}: missing required field (name or description)"
+            )
+            return None
+
+        # Extract spec fields (optional)
+        license_field = frontmatter.get("license")
+        compatibility = frontmatter.get("compatibility", "claude-code")
+        metadata = frontmatter.get("metadata", {})
+        allowed_tools = frontmatter.get("allowed-tools", [])
+
+        # Extract derived fields from metadata or top-level
+        version = frontmatter.get("version") or metadata.get("version", "0.1.0")
+        skill_id = frontmatter.get("skill_id", name)
+        updated_at = frontmatter.get("updated_at") or metadata.get("updated")
+        tags = frontmatter.get("tags", []) or metadata.get("tags", [])
+
+        # Extract claude-mpm extensions
+        category = frontmatter.get("category")
+        toolchain = frontmatter.get("toolchain")
+        progressive_disclosure = frontmatter.get("progressive_disclosure")
+        user_invocable = frontmatter.get("user-invocable", False)
+
+        # Create skill object
+        return Skill(
+            name=name,
+            description=description,
+            license=license_field,
+            compatibility=compatibility,
+            metadata=metadata,
+            allowed_tools=allowed_tools,
+            path=path,
+            content=content,
+            source=source,
+            version=version,
+            skill_id=skill_id,
+            updated_at=updated_at,
+            tags=tags,
+            category=category,
+            toolchain=toolchain,
+            progressive_disclosure=progressive_disclosure,
+            user_invocable=user_invocable,
+        )
+
     def _load_bundled_skills(self):
         """Load skills bundled with MPM."""
         bundled_dir = Path(__file__).parent / "bundled"
@@ -88,32 +339,16 @@ class SkillsRegistry:
                 skill_name = skill_file.stem
                 content = skill_file.read_text(encoding="utf-8")
 
-                # Parse frontmatter
+                # Parse frontmatter with backward compatibility
                 frontmatter = self._parse_skill_frontmatter(content)
 
-                # Extract version fields from frontmatter
-                version = frontmatter.get("skill_version", "0.1.0")
-                skill_id = frontmatter.get("skill_id", skill_name)
-                updated_at = frontmatter.get("updated_at")
-                tags = frontmatter.get("tags", [])
-
-                # Extract description (from frontmatter or fallback to content parsing)
-                description = frontmatter.get("description", "")
-                if not description:
-                    description = self._extract_description(content)
-
-                self.skills[skill_name] = Skill(
-                    name=skill_name,
-                    path=skill_file,
-                    content=content,
-                    source="bundled",
-                    version=version,
-                    skill_id=skill_id,
-                    description=description,
-                    updated_at=updated_at,
-                    tags=tags,
+                # Create skill from frontmatter
+                skill = self._create_skill_from_frontmatter(
+                    frontmatter, skill_file, content, "bundled"
                 )
-                skill_count += 1
+                if skill:
+                    self.skills[skill_name] = skill
+                    skill_count += 1
             except Exception as e:
                 logger.error(f"Error loading bundled skill {skill_file}: {e}")
 
@@ -130,36 +365,20 @@ class SkillsRegistry:
         for skill_file in user_skills_dir.glob("*.md"):
             try:
                 skill_name = skill_file.stem
-                # User skills override bundled skills
                 content = skill_file.read_text(encoding="utf-8")
 
-                # Parse frontmatter
+                # Parse frontmatter with backward compatibility
                 frontmatter = self._parse_skill_frontmatter(content)
 
-                # Extract version fields from frontmatter
-                version = frontmatter.get("skill_version", "0.1.0")
-                skill_id = frontmatter.get("skill_id", skill_name)
-                updated_at = frontmatter.get("updated_at")
-                tags = frontmatter.get("tags", [])
-
-                # Extract description (from frontmatter or fallback to content parsing)
-                description = frontmatter.get("description", "")
-                if not description:
-                    description = self._extract_description(content)
-
-                self.skills[skill_name] = Skill(
-                    name=skill_name,
-                    path=skill_file,
-                    content=content,
-                    source="user",
-                    version=version,
-                    skill_id=skill_id,
-                    description=description,
-                    updated_at=updated_at,
-                    tags=tags,
+                # Create skill from frontmatter
+                skill = self._create_skill_from_frontmatter(
+                    frontmatter, skill_file, content, "user"
                 )
-                skill_count += 1
-                logger.debug(f"User skill '{skill_name}' overrides bundled version")
+                if skill:
+                    # User skills override bundled skills
+                    self.skills[skill_name] = skill
+                    skill_count += 1
+                    logger.debug(f"User skill '{skill_name}' overrides bundled version")
             except Exception as e:
                 logger.error(f"Error loading user skill {skill_file}: {e}")
 
@@ -177,36 +396,22 @@ class SkillsRegistry:
         for skill_file in project_skills_dir.glob("*.md"):
             try:
                 skill_name = skill_file.stem
-                # Project skills override both user and bundled skills
                 content = skill_file.read_text(encoding="utf-8")
 
-                # Parse frontmatter
+                # Parse frontmatter with backward compatibility
                 frontmatter = self._parse_skill_frontmatter(content)
 
-                # Extract version fields from frontmatter
-                version = frontmatter.get("skill_version", "0.1.0")
-                skill_id = frontmatter.get("skill_id", skill_name)
-                updated_at = frontmatter.get("updated_at")
-                tags = frontmatter.get("tags", [])
-
-                # Extract description (from frontmatter or fallback to content parsing)
-                description = frontmatter.get("description", "")
-                if not description:
-                    description = self._extract_description(content)
-
-                self.skills[skill_name] = Skill(
-                    name=skill_name,
-                    path=skill_file,
-                    content=content,
-                    source="project",
-                    version=version,
-                    skill_id=skill_id,
-                    description=description,
-                    updated_at=updated_at,
-                    tags=tags,
+                # Create skill from frontmatter
+                skill = self._create_skill_from_frontmatter(
+                    frontmatter, skill_file, content, "project"
                 )
-                skill_count += 1
-                logger.debug(f"Project skill '{skill_name}' overrides other versions")
+                if skill:
+                    # Project skills override both user and bundled skills
+                    self.skills[skill_name] = skill
+                    skill_count += 1
+                    logger.debug(
+                        f"Project skill '{skill_name}' overrides other versions"
+                    )
             except Exception as e:
                 logger.error(f"Error loading project skill {skill_file}: {e}")
 

{claude_mpm-5.6.1.dist-info → claude_mpm-5.6.76.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-mpm
-Version: 5.6.1
+Version: 5.6.76
 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
@@ -23,7 +23,7 @@ License-File: LICENSE
 License-File: LICENSE-FAQ.md
 Requires-Dist: ai-trackdown-pytools>=1.4.0
 Requires-Dist: pyyaml>=6.0
-Requires-Dist: python-dotenv>=0.19.0
+Requires-Dist: python-dotenv>=1.0.0
 Requires-Dist: click>=8.0.0
 Requires-Dist: pexpect>=4.8.0
 Requires-Dist: psutil>=5.9.0
@@ -51,6 +51,10 @@ Requires-Dist: pyee>=13.0.0
 Requires-Dist: pathspec>=0.11.0
 Requires-Dist: fastapi>=0.100.0
 Requires-Dist: uvicorn>=0.20.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: keyring>=24.0.0
+Requires-Dist: cryptography>=41.0.0
+Requires-Dist: mcp>=1.0.0
 Provides-Extra: mcp
 Requires-Dist: mcp>=0.1.0; extra == "mcp"
 Requires-Dist: mcp-vector-search>=0.1.0; extra == "mcp"
@@ -143,9 +147,11 @@ Claude MPM transforms Claude Code into a **multi-agent orchestration platform**
 
 ### Prerequisites
 
-1. **Python 3.10+** (3.11+ recommended)
+1. **Python 3.11+** (required - older versions will install outdated claude-mpm)
 2. **Claude Code CLI v2.1.3+** (required!)
 
+> ⚠️ **Python Version Note**: Claude MPM requires Python 3.11 or higher. If you have Python 3.9 or 3.10, you'll get an old version (4.x) that lacks current features. Check with `python3 --version` before installing.
+
 ```bash
 # Verify Claude Code is installed
 claude --version
@@ -253,6 +259,25 @@ ls ~/.claude/agents/    # Should show 47+ agents
 
 [→ Learn more: MCP Gateway](docs/developer/13-mcp-gateway/README.md)
 
+### 🔐 OAuth & Google Workspace Integration
+- **Browser-Based OAuth** for secure authentication with MCP services
+- **Google Workspace MCP** built-in server for Gmail, Calendar, and Drive
+- **Encrypted Token Storage** using Fernet encryption with system keychain
+- **Automatic Token Refresh** handles expiration seamlessly
+
+```bash
+# Set up Google Workspace OAuth
+claude-mpm oauth setup workspace-mcp
+
+# Check token status
+claude-mpm oauth status workspace-mcp
+
+# List OAuth-capable services
+claude-mpm oauth list
+```
+
+[→ Learn more: OAuth Setup Guide](docs/guides/oauth-setup.md)
+
 ### ⚡ Performance & Security
 - **Simplified Architecture** with ~3,700 lines removed for better performance
 - **Enhanced Security** with comprehensive input validation