claude-mpm 4.16.3__py3-none-any.whl → 4.17.1__py3-none-any.whl

claude_mpm/VERSION

@@ -1 +1 @@
-4.16.3
+4.17.1

claude_mpm/commands/mpm-help.md

@@ -90,6 +90,9 @@ Available Commands:
 /mpm-monitor [start|stop|restart|status|port]
   Manage Socket.IO monitoring server and dashboard
 
+/mpm-version
+  Display comprehensive version information including project version, all agents with versions, and all skills with versions
+
 Use '/mpm-help <command>' for detailed help on a specific command.
 ```
 

claude_mpm/commands/mpm-version.md

@@ -0,0 +1,113 @@
+# Display Claude MPM Version Information
+
+Show comprehensive version information for Claude MPM project, agents, and skills.
+
+## Usage
+
+```
+/mpm-version
+```
+
+## Description
+
+Display version information including:
+- Project version and build number
+- All deployed agents with their versions (grouped by tier: system/user/project)
+- All available skills with their versions (grouped by source: bundled/user/project)
+- Summary statistics
+
+## Implementation
+
+When you run `/mpm-version`, the PM will:
+
+1. **Collect Version Information**
+   - Use VersionService to gather all version data
+   - Project version from pyproject.toml
+   - Build number from BUILD_NUMBER file
+   - Agent versions from AgentRegistry
+   - Skills versions from SkillRegistry
+
+2. **Format Output**
+   - Hierarchical display: Project → Agents → Skills
+   - Grouped by tier/source for clarity
+   - Sorted alphabetically within groups
+   - Summary statistics at the end
+
+3. **Display Results**
+   - Well-formatted tree structure
+   - Easy to scan and read
+   - Includes totals and counts
+
+## Example Output
+
+```
+Claude MPM Version Information
+==============================
+
+Project Version: 4.16.3
+Build: 481
+
+Agents (35 total)
+-----------------
+
+System Agents (30):
+  ├─ agent-manager (1.0.0)
+  ├─ engineer (3.9.1)
+  ├─ research-agent (4.5.1)
+  ├─ documentation (2.1.0)
+  ├─ qa (2.0.3)
+  └─ ... (25 more)
+
+User Agents (3):
+  ├─ custom-agent (1.0.0)
+  ├─ testing-agent (0.5.0)
+  └─ prototype-agent (0.1.0)
+
+Project Agents (2):
+  ├─ project-specific (2.0.0)
+  └─ domain-expert (1.1.0)
+
+Skills (20 total)
+-----------------
+
+Bundled Skills (20):
+  ├─ test-driven-development (0.1.0)
+  ├─ systematic-debugging (0.1.0)
+  ├─ async-testing (0.1.0)
+  ├─ performance-profiling (0.1.0)
+  ├─ security-scanning (0.1.0)
+  └─ ... (15 more)
+
+User Skills (0):
+  (none)
+
+Project Skills (0):
+  (none)
+
+Summary
+-------
+• Project: v4.16.3 (build 481)
+• Agents: 35 total (30 system, 3 user, 2 project)
+• Skills: 20 total (20 bundled, 0 user, 0 project)
+```
+
+## PM Implementation Instructions
+
+To execute this command, PM should:
+
+1. Import and use VersionService:
+   ```python
+   from claude_mpm.services.version_service import VersionService
+
+   service = VersionService()
+   summary = service.get_version_summary()
+   ```
+
+2. Format output following the example structure above
+3. Handle missing data gracefully (show "unknown" for missing versions)
+4. Include all tiers/sources even if counts are zero
+
+## Related Commands
+
+- `/mpm-help` - Show all available MPM commands
+- `/mpm-status` - Show system status information

claude_mpm/commands/mpm.md

@@ -8,6 +8,7 @@ Available MPM commands:
 - /mpm-help - Show command help
 - /mpm-status - Show MPM status
 - /mpm-config - Manage configuration
+- /mpm-version - Display version information for project, agents, and skills
 
 Claude MPM extends Claude Code with:
 - Multi-agent orchestration

claude_mpm/services/version_service.py

@@ -9,7 +9,7 @@ Extracted from ClaudeRunner to follow Single Responsibility Principle.
 """
 
 from pathlib import Path
-from typing import Any, Dict, Optional
+from typing import Any, Dict, List, Optional
 
 from claude_mpm.config.paths import paths
 from claude_mpm.core.base_service import BaseService
@@ -274,3 +274,106 @@ class VersionService(BaseService, VersionServiceInterface):
             "message": "Update checking not implemented",
             "checked_at": None,
         }
+
+    def get_agents_versions(self) -> Dict[str, List[Dict[str, str]]]:
+        """Get all agents grouped by tier with versions.
+
+        Returns:
+            Dict with keys: system, user, project
+            Each value is list of agent dicts with: name, version, id
+        """
+        from claude_mpm.core.unified_agent_registry import get_agent_registry
+
+        agents_by_tier = {"system": [], "user": [], "project": []}
+
+        try:
+            registry = get_agent_registry()
+            all_agents = registry.list_agents()
+
+            for agent in all_agents:
+                agent_info = {
+                    "name": agent.name,
+                    "version": agent.version,
+                    "id": agent.name,  # Use name as ID since agent_id doesn't exist
+                }
+                tier = (
+                    agent.tier.value
+                    if hasattr(agent.tier, "value")
+                    else str(agent.tier)
+                )
+                if tier in agents_by_tier:
+                    agents_by_tier[tier].append(agent_info)
+                else:
+                    agents_by_tier["system"].append(agent_info)
+
+            # Sort each tier alphabetically by name
+            for tier, agents in agents_by_tier.items():
+                agents.sort(key=lambda x: x["name"])
+
+        except Exception as e:
+            self.logger.error(f"Failed to get agent versions: {e}")
+
+        return agents_by_tier
+
+    def get_skills_versions(self) -> Dict[str, List[Dict[str, str]]]:
+        """Get all skills grouped by source with versions.
+
+        Returns:
+            Dict with keys: bundled, user, project
+            Each value is list of skill dicts with: name, version, description
+        """
+        from claude_mpm.skills.registry import get_registry
+
+        skills_by_source = {"bundled": [], "user": [], "project": []}
+
+        try:
+            registry = get_registry()
+
+            for skill in registry.list_skills():
+                skill_info = {
+                    "name": skill.name,
+                    "version": skill.version,
+                    "description": (
+                        skill.description[:60] + "..."
+                        if len(skill.description) > 60
+                        else skill.description
+                    ),
+                }
+                source = skill.source if skill.source in skills_by_source else "bundled"
+                skills_by_source[source].append(skill_info)
+
+            # Sort each source alphabetically by name
+            for source, skills in skills_by_source.items():
+                skills.sort(key=lambda x: x["name"])
+
+        except Exception as e:
+            self.logger.error(f"Failed to get skill versions: {e}")
+
+        return skills_by_source
+
+    def get_version_summary(self) -> Dict:
+        """Get complete version summary.
+
+        Returns:
+            Dict with project_version, build, agents, skills, and counts
+        """
+        agents = self.get_agents_versions()
+        skills = self.get_skills_versions()
+        build = self.get_build_number()
+
+        return {
+            "project_version": self.get_base_version(),
+            "build": build,
+            "agents": agents,
+            "skills": skills,
+            "counts": {
+                "agents_total": sum(len(v) for v in agents.values()),
+                "agents_system": len(agents.get("system", [])),
+                "agents_user": len(agents.get("user", [])),
+                "agents_project": len(agents.get("project", [])),
+                "skills_total": sum(len(v) for v in skills.values()),
+                "skills_bundled": len(skills.get("bundled", [])),
+                "skills_user": len(skills.get("user", [])),
+                "skills_project": len(skills.get("project", [])),
+            },
+        }

claude_mpm/skills/bundled/api-documentation.md

@@ -0,0 +1,393 @@
+---
+skill_id: api-documentation
+skill_version: 0.1.0
+description: Best practices for documenting APIs and code interfaces, eliminating redundant documentation guidance per agent.
+updated_at: 2025-10-30T17:00:00Z
+tags: [api, documentation, best-practices, interfaces]
+---
+
+# API Documentation
+
+Best practices for documenting APIs and code interfaces. Eliminates ~100-150 lines of redundant documentation guidance per agent.
+
+## Core Documentation Principles
+
+1. **Document the why, not just the what** - Explain intent and rationale
+2. **Keep docs close to code** - Inline documentation stays synchronized
+3. **Document contracts, not implementation** - Focus on behavior
+4. **Examples are essential** - Show real usage
+5. **Update docs with code** - Outdated docs are worse than no docs
+
+## Function/Method Documentation
+
+### Python (Docstrings)
+
+```python
+def calculate_discount(price: float, discount_percent: float) -> float:
+    """
+    Calculate discounted price with percentage off.
+
+    Args:
+        price: Original price in dollars (must be positive)
+        discount_percent: Discount percentage (0-100)
+
+    Returns:
+        Final price after discount, rounded to 2 decimals
+
+    Raises:
+        ValueError: If price is negative or discount > 100
+
+    Examples:
+        >>> calculate_discount(100.0, 20.0)
+        80.0
+        >>> calculate_discount(50.0, 50.0)
+        25.0
+
+    Note:
+        Discount percent is capped at 100% (minimum price of 0)
+    """
+    if price < 0:
+        raise ValueError("Price cannot be negative")
+    if discount_percent > 100:
+        raise ValueError("Discount cannot exceed 100%")
+
+    discount_amount = price * (discount_percent / 100)
+    return round(price - discount_amount, 2)
+```
+
+### JavaScript (JSDoc)
+
+```javascript
+/**
+ * Calculate discounted price with percentage off
+ *
+ * @param {number} price - Original price in dollars (must be positive)
+ * @param {number} discountPercent - Discount percentage (0-100)
+ * @returns {number} Final price after discount, rounded to 2 decimals
+ * @throws {Error} If price is negative or discount > 100
+ *
+ * @example
+ * calculateDiscount(100.0, 20.0)
+ * // returns 80.0
+ *
+ * @example
+ * calculateDiscount(50.0, 50.0)
+ * // returns 25.0
+ */
+function calculateDiscount(price, discountPercent) {
+  if (price < 0) {
+    throw new Error('Price cannot be negative');
+  }
+  if (discountPercent > 100) {
+    throw new Error('Discount cannot exceed 100%');
+  }
+
+  const discountAmount = price * (discountPercent / 100);
+  return Math.round((price - discountAmount) * 100) / 100;
+}
+```
+
+### Go (Godoc)
+
+```go
+// CalculateDiscount calculates discounted price with percentage off.
+//
+// The function applies the given discount percentage to the original price
+// and returns the final price rounded to 2 decimal places.
+//
+// Parameters:
+//   - price: Original price in dollars (must be positive)
+//   - discountPercent: Discount percentage (0-100)
+//
+// Returns the final price after discount.
+//
+// Returns an error if price is negative or discount exceeds 100%.
+//
+// Example:
+//
+//	finalPrice, err := CalculateDiscount(100.0, 20.0)
+//	// finalPrice = 80.0
+func CalculateDiscount(price, discountPercent float64) (float64, error) {
+    if price < 0 {
+        return 0, errors.New("price cannot be negative")
+    }
+    if discountPercent > 100 {
+        return 0, errors.New("discount cannot exceed 100%")
+    }
+
+    discountAmount := price * (discountPercent / 100)
+    return math.Round((price-discountAmount)*100) / 100, nil
+}
+```
+
+## API Endpoint Documentation
+
+### REST API (OpenAPI/Swagger)
+
+```yaml
+openapi: 3.0.0
+info:
+  title: User Management API
+  version: 1.0.0
+
+paths:
+  /users/{userId}:
+    get:
+      summary: Get user by ID
+      description: Retrieves detailed information for a specific user
+      parameters:
+        - name: userId
+          in: path
+          required: true
+          schema:
+            type: integer
+            minimum: 1
+          description: Unique user identifier
+      responses:
+        '200':
+          description: User found successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/User'
+              example:
+                id: 123
+                name: "John Doe"
+                email: "john@example.com"
+        '404':
+          description: User not found
+        '401':
+          description: Unauthorized - authentication required
+```
+
+### GraphQL
+
+```graphql
+"""
+Represents a user in the system
+"""
+type User {
+  """Unique identifier for the user"""
+  id: ID!
+
+  """User's full name"""
+  name: String!
+
+  """User's email address (validated)"""
+  email: String!
+
+  """User's posts (paginated)"""
+  posts(limit: Int = 10, offset: Int = 0): [Post!]!
+}
+
+"""
+Query a specific user by ID
+"""
+type Query {
+  """
+  Get user by unique identifier
+
+  Returns null if user not found
+  """
+  user(id: ID!): User
+}
+```
+
+## Class/Module Documentation
+
+```python
+class UserManager:
+    """
+    Manages user accounts and authentication.
+
+    This class provides a high-level interface for user management
+    operations including creation, authentication, and profile updates.
+
+    Attributes:
+        db: Database connection instance
+        cache: Redis cache for session management
+
+    Example:
+        >>> manager = UserManager(db=get_db(), cache=get_cache())
+        >>> user = manager.create_user("john@example.com", "password")
+        >>> authenticated = manager.authenticate("john@example.com", "password")
+        >>> authenticated is not None
+        True
+
+    Thread Safety:
+        This class is thread-safe. Multiple threads can safely call
+        methods concurrently.
+
+    Note:
+        All passwords are automatically hashed using bcrypt before
+        storage. Never pass pre-hashed passwords to methods.
+    """
+
+    def __init__(self, db: Database, cache: Cache):
+        """
+        Initialize UserManager with database and cache.
+
+        Args:
+            db: Database connection for persistent storage
+            cache: Redis cache for session management
+
+        Raises:
+            ConnectionError: If unable to connect to database or cache
+        """
+        self.db = db
+        self.cache = cache
+```
+
+## README Documentation Structure
+
+```markdown
+# Project Name
+
+Brief description of what the project does (1-2 sentences).
+
+## Features
+
+- Key feature 1
+- Key feature 2
+- Key feature 3
+
+## Installation
+
+```bash
+pip install project-name
+```
+
+## Quick Start
+
+```python
+from project import MainClass
+
+# Simple usage example
+client = MainClass(api_key="your-key")
+result = client.do_something()
+print(result)
+```
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `api_key` | str | None | API authentication key |
+| `timeout` | int | 30 | Request timeout in seconds |
+
+## API Reference
+
+See full [API Documentation](docs/api.md)
+
+### Main Methods
+
+#### `do_something(param1, param2)`
+
+Description of what this does.
+
+**Parameters:**
+- `param1` (str): Description of param1
+- `param2` (int): Description of param2
+
+**Returns:** Description of return value
+
+**Example:**
+```python
+result = client.do_something("value", 42)
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md)
+
+## License
+
+MIT License - see [LICENSE](LICENSE)
+```
+
+## Documentation Anti-Patterns
+
+### ❌ Redundant Comments
+
+```python
+# Bad: Obvious comment adds no value
+i = i + 1  # Increment i
+
+# Good: Comment explains WHY
+i = i + 1  # Skip header row
+```
+
+### ❌ Outdated Documentation
+
+```python
+# Bad: Comment doesn't match code
+def get_users(limit=10):  # Comment says: Returns all users
+    """Returns all users in the system."""  # But limit is 10!
+    return User.query.limit(limit).all()
+
+# Good: Keep docs synchronized
+def get_users(limit=10):
+    """
+    Returns up to 'limit' users from the system.
+
+    Args:
+        limit: Maximum number of users to return (default: 10)
+    """
+    return User.query.limit(limit).all()
+```
+
+### ❌ Implementation Documentation
+
+```python
+# Bad: Documents HOW (implementation)
+def sort_users(users):
+    """Uses bubble sort algorithm to sort users."""  # Don't care!
+    ...
+
+# Good: Documents WHAT (contract)
+def sort_users(users):
+    """Returns users sorted alphabetically by name."""
+    ...
+```
+
+## Documentation Tools
+
+### Python
+- **Sphinx**: Generate HTML docs from docstrings
+- **pdoc**: Simpler alternative to Sphinx
+- **MkDocs**: Markdown-based documentation
+
+### JavaScript
+- **JSDoc**: Generate HTML from JSDoc comments
+- **TypeDoc**: For TypeScript projects
+- **Docusaurus**: Full documentation websites
+
+### Go
+- **godoc**: Built-in documentation tool
+- **pkgsite**: Go package documentation
+
+### Rust
+- **rustdoc**: Built-in documentation with `cargo doc`
+
+## Quick Documentation Checklist
+
+```
+□ Public APIs have docstrings/comments
+□ Parameters and return values documented
+□ Exceptions/errors documented
+□ Usage examples provided
+□ Edge cases and limitations noted
+□ README includes quick start
+□ API reference available
+□ Configuration options documented
+□ Docs are up to date with code
+□ Breaking changes documented
+```
+
+## Remember
+
+- **Code is read more than written** - Good docs save time
+- **Examples speak louder than descriptions** - Show, don't just tell
+- **The best docs are no docs** - Write self-documenting code
+- **Keep it DRY** - Don't repeat what the code already says
+- **Update docs with code** - Outdated docs mislead developers