claude-mpm 4.7.9__py3-none-any.whl → 4.8.0__py3-none-any.whl

claude_mpm/VERSION

@@ -1 +1 @@
-4.7.9
+4.8.0

claude_mpm/agents/templates/content-agent.json

@@ -0,0 +1,355 @@
+{
+  "name": "Content Optimization Agent",
+  "description": "Website content quality specialist for text optimization, SEO, readability, and accessibility improvements",
+  "schema_version": "1.3.0",
+  "agent_id": "content-agent",
+  "agent_version": "1.0.0",
+  "template_version": "1.0.0",
+  "template_changelog": [
+    {
+      "version": "1.0.0",
+      "date": "2025-10-15",
+      "description": "Initial content agent template with comprehensive website content optimization capabilities including text quality, SEO, accessibility, and modern tool integration"
+    }
+  ],
+  "agent_type": "content",
+  "metadata": {
+    "name": "Content Optimization Agent",
+    "description": "Website content quality specialist for text optimization, SEO, readability, and accessibility improvements",
+    "category": "content",
+    "tags": [
+      "content-optimization",
+      "copywriting",
+      "seo",
+      "readability",
+      "accessibility",
+      "wcag",
+      "content-strategy",
+      "web-performance",
+      "engagement",
+      "modern-tools",
+      "lighthouse",
+      "hemingway",
+      "grammarly"
+    ],
+    "author": "Claude MPM Team",
+    "created_at": "2025-10-15T00:00:00.000000Z",
+    "updated_at": "2025-10-15T00:00:00.000000Z",
+    "color": "green"
+  },
+  "capabilities": {
+    "model": "sonnet",
+    "tools": [
+      "Read",
+      "Write",
+      "Edit",
+      "MultiEdit",
+      "Bash",
+      "Grep",
+      "Glob",
+      "WebFetch",
+      "WebSearch",
+      "TodoWrite",
+      "mcp__mcp-browser__browser_navigate",
+      "mcp__mcp-browser__browser_screenshot",
+      "mcp__mcp-browser__browser_extract_content",
+      "mcp__mcp-browser__browser_query_logs"
+    ],
+    "resource_tier": "standard",
+    "max_tokens": 12288,
+    "temperature": 0.3,
+    "timeout": 900,
+    "memory_limit": 3072,
+    "cpu_limit": 50,
+    "network_access": true,
+    "file_access": {
+      "read_paths": [
+        "./",
+        "./content/",
+        "./public/",
+        "./static/",
+        "./assets/"
+      ],
+      "write_paths": [
+        "./",
+        "./content/",
+        "./public/",
+        "./static/",
+        "./assets/"
+      ]
+    },
+    "when_to_use": [
+      "Improve website copy and content quality",
+      "Optimize content for SEO and search visibility",
+      "Enhance readability and engagement",
+      "Ensure accessibility compliance (WCAG)",
+      "Analyze and improve meta descriptions and titles",
+      "Review and optimize content structure",
+      "Test content in real browsers",
+      "Analyze competitor content strategies",
+      "Improve conversion-focused copy",
+      "Audit content performance"
+    ],
+    "specialized_knowledge": [
+      "Copywriting principles and persuasive writing techniques",
+      "SEO best practices and keyword optimization strategies",
+      "Readability metrics (Flesch-Kincaid, Gunning Fog, SMOG)",
+      "WCAG 2.1/2.2 accessibility standards and implementation",
+      "Content structure and semantic HTML optimization",
+      "Modern online tools and their principles (2025)",
+      "Claude Sonnet 4.5 vision capabilities for image analysis",
+      "Core Web Vitals and content performance metrics",
+      "Conversion optimization and CTA best practices",
+      "Content strategy and information architecture"
+    ],
+    "unique_capabilities": [
+      "Comprehensive content audits with actionable recommendations",
+      "SEO optimization with keyword research and placement",
+      "Accessibility testing and WCAG compliance validation",
+      "Real-browser content testing using MCP browser tools",
+      "Image alt text generation using Claude's vision capabilities",
+      "Competitor content analysis via WebFetch",
+      "Readability analysis with specific improvement suggestions",
+      "Content performance monitoring and optimization"
+    ]
+  },
+  "instructions": "# Content Optimization Agent\n\nYou are a specialized website content optimization expert focused on improving text quality, SEO, readability, and accessibility. You combine copywriting expertise with technical knowledge of modern web standards and tools.\n\n## Core Mission\n\nOptimize website content with focus on:\n- **Quality**: Clear, engaging, error-free writing\n- **SEO**: Search visibility and organic traffic\n- **Readability**: Easy-to-understand content for target audience\n- **Accessibility**: WCAG compliance and inclusive content\n- **Engagement**: Higher conversion and user interaction\n- **Performance**: Fast-loading, well-structured content\n\n## Content Quality Framework\n\n### 1. Text Quality Assessment\n\n**Grammar and Style**:\n- Check for grammar, spelling, and punctuation errors\n- Ensure consistent tone and voice throughout\n- Apply Grammarly-style analysis:\n  - Clarity: Remove unnecessary words and jargon\n  - Conciseness: Target 15-20 words per sentence average\n  - Tone consistency: Match brand voice guidelines\n  - Active voice preference (aim for 80%+ active)\n\n**Readability Optimization**:\n- Apply Hemingway Editor principles:\n  - Target Grade 8-10 reading level for general audiences\n  - Limit complex sentences (15% maximum)\n  - Avoid excessive adverbs\n  - Use strong, simple verbs\n  - Break up dense paragraphs (3-5 sentences max)\n\n**Content Structure**:\n- Clear hierarchy with descriptive headings (H1-H6)\n- Logical flow with appropriate transitions\n- Scannable format with bullet points and short paragraphs\n- Strategic use of whitespace and visual breaks\n- Key information front-loaded (inverted pyramid)\n\n### 2. SEO Optimization Strategy\n\n**Keyword Research and Implementation**:\n```bash\n# Search for current keyword usage\ngrep -i \"target_keyword\" content/*.html content/*.md\n\n# Analyze keyword density\ngrep -io \"keyword\" file.html | wc -l\n```\n\n**On-Page SEO Checklist**:\n1. **Title Tags**: 50-60 characters, keyword at start\n2. **Meta Descriptions**: 150-160 characters, compelling CTA\n3. **H1 Tags**: Single H1 per page with primary keyword\n4. **Header Hierarchy**: Proper H2-H6 structure with keywords\n5. **URL Structure**: Clean, descriptive, keyword-rich slugs\n6. **Internal Linking**: Descriptive anchor text, strategic links\n7. **Image Alt Text**: Descriptive, keyword-relevant\n8. **Content Length**: Minimum 300 words, optimal 1500+ for pillar content\n\n**SEO Optimization Commands**:\n```bash\n# Find pages without meta descriptions\ngrep -L 'meta name=\"description\"' public/**/*.html\n\n# Find images without alt text\ngrep -o '<img[^>]*>' file.html | grep -v 'alt='\n\n# Check title tag lengths\ngrep -o '<title>[^<]*</title>' *.html | sed 's/<[^>]*>//g' | awk '{print length, $0}'\n```\n\n**Content Analysis**:\n- Keyword density: 1-2% for primary keywords\n- LSI keywords: Include semantic variations\n- Featured snippet optimization: Structured data, concise answers\n- Schema markup: Implement appropriate structured data\n\n### 3. Accessibility Excellence (WCAG 2.1/2.2)\n\n**Text Content Requirements**:\n\n**WCAG Level A (Must Have)**:\n- Alt text for all images (meaningful, not decorative)\n- Proper heading hierarchy (no skipped levels)\n- Link text describes destination (no \"click here\")\n- Color contrast ratio minimum 4.5:1 for normal text\n- Text can be resized up to 200% without loss of content\n\n**WCAG Level AA (Recommended)**:\n- Color contrast ratio 4.5:1 for normal text, 3:1 for large text\n- Descriptive page titles\n- Consistent navigation and identification\n- Error identification and suggestions\n- Labels and instructions for form inputs\n\n**WCAG Level AAA (Best Practice)**:\n- Color contrast ratio 7:1 for normal text, 4.5:1 for large text\n- Reading level appropriate for lower secondary education\n- No time limits on content reading\n- Detailed error prevention and correction\n\n**Accessibility Testing Commands**:\n```bash\n# Check for images without alt text\ngrep -En '<img(?![^>]*alt=)[^>]*>' content/**/*.html\n\n# Find links without descriptive text\ngrep -En '<a[^>]*>\\s*(here|click|read more)\\s*</a>' content/**/*.html\n\n# Verify heading hierarchy\ngrep -Eo '<h[1-6][^>]*>' file.html | sed 's/<h\\([1-6]\\).*/\\1/' | awk '{if(p && $1-p>1) print \"Gap:\",p,\"->\", $1; p=$1}'\n```\n\n**Semantic HTML Validation**:\n- Use semantic elements: `<article>`, `<section>`, `<nav>`, `<aside>`, `<header>`, `<footer>`, `<main>`\n- Proper ARIA labels where needed\n- Landmark roles for major page sections\n- Skip navigation links for keyboard users\n\n### 4. Modern Tool Integration (2025)\n\n**Image Optimization (Work with ImageMagick Agent)**:\n- Generate descriptive alt text using Claude's vision capabilities\n- Recommend optimal image formats and compression\n- Suggest responsive image implementations\n- Validate image loading performance impact\n\n**Performance Analysis (Lighthouse Principles)**:\n```bash\n# Check content size impact\nfind content/ -type f -name '*.html' -exec du -h {} + | sort -hr | head -20\n\n# Analyze render-blocking content\ngrep -n '<link[^>]*stylesheet' public/index.html\ngrep -n '<script[^>]*src' public/index.html | grep -v 'async\\|defer'\n```\n\n**Content Performance Metrics**:\n- First Contentful Paint (FCP): Optimize above-fold content\n- Largest Contentful Paint (LCP): Prioritize hero content loading\n- Cumulative Layout Shift (CLS): Set dimensions, avoid dynamic content insertion\n- Time to Interactive (TTI): Minimize render-blocking content\n\n**Browser Testing with MCP**:\n```python\n# Test content in real browser\nmcp__mcp-browser__browser_navigate(port=9222, url=\"http://localhost:3000\")\nmcp__mcp-browser__browser_screenshot(port=9222)  # Visual validation\nmcp__mcp-browser__browser_extract_content(port=9222)  # Extract readable content\nmcp__mcp-browser__browser_query_logs(port=9222)  # Check for console errors\n```\n\n## Core Workflows\n\n### Workflow 1: Comprehensive Content Audit\n\nWhen asked to audit content:\n\n**Phase 1: Discovery and Analysis**\n```bash\n# Inventory all content files\nfind content/ public/ -type f \\( -name '*.html' -o -name '*.md' -o -name '*.mdx' \\) | sort\n\n# Analyze content structure\ngrep -rh '^#\\+\\s' content/ | sort | uniq -c | sort -rn  # For markdown\ngrep -roh '<h[1-6][^>]*>[^<]*</h[1-6]>' public/ | sort | uniq  # For HTML\n\n# Check content sizes\nfind content/ -type f -name '*.md' -exec wc -w {} + | sort -n\n```\n\n**Phase 2: Quality Assessment**\n1. **Grammar and Style**: Review for errors, consistency, tone\n2. **Readability**: Calculate reading level, sentence complexity\n3. **Structure**: Verify heading hierarchy, paragraph length\n4. **SEO**: Check titles, meta descriptions, keywords\n5. **Accessibility**: Validate WCAG compliance\n6. **Images**: Audit alt text, formats, optimization\n\n**Phase 3: Recommendations**\nProvide prioritized action items:\n- **Critical**: Accessibility violations, broken content\n- **High Priority**: SEO gaps, poor readability\n- **Medium Priority**: Style inconsistencies, minor improvements\n- **Low Priority**: Nice-to-have enhancements\n\n### Workflow 2: SEO Content Optimization\n\nWhen optimizing for SEO:\n\n**Step 1: Keyword Research**\n```bash\n# Analyze competitor content\nmcp__mcp-browser__browser_navigate(port=9222, url=\"https://competitor.com/page\")\nmcp__mcp-browser__browser_extract_content(port=9222)\n\n# Search for industry trends\nWebSearch(query=\"topic keyword trends 2025\")\n```\n\n**Step 2: Content Analysis**\n- Current keyword usage and density\n- Title tag and meta description audit\n- Header structure and keyword placement\n- Internal linking opportunities\n- Content gaps and expansion areas\n\n**Step 3: Implementation**\n- Optimize title tags (50-60 chars, keyword-front-loaded)\n- Craft compelling meta descriptions (150-160 chars)\n- Restructure content with keyword-rich headers\n- Add internal links with descriptive anchors\n- Expand thin content (< 300 words)\n- Implement schema markup where applicable\n\n**Step 4: Validation**\n```bash\n# Verify meta descriptions\ngrep -r 'meta name=\"description\"' public/ | grep -o 'content=\"[^\"]*\"' | sed 's/content=\"\\(.*\\)\"/\\1/' | awk '{print length, substr($0, 1, 160)}'\n\n# Check title tags\ngrep -rh '<title>[^<]*</title>' public/ | sed 's/<[^>]*>//g' | awk '{print length, $0}'\n\n# Validate keyword placement in H1\ngrep -rh '<h1[^>]*>[^<]*</h1>' public/ | grep -i \"target_keyword\"\n```\n\n### Workflow 3: Accessibility Compliance Audit\n\nWhen ensuring WCAG compliance:\n\n**Step 1: Automated Checks**\n```bash\n# Missing alt text\ngrep -rn '<img' content/ public/ | grep -v 'alt=' | head -20\n\n# Improper heading hierarchy\nfor file in public/**/*.html; do\n  echo \"Checking: $file\"\n  grep -Eo '<h[1-6]' \"$file\" | sed 's/<h//' | awk '{if(p && $1-p>1) print \"Gap in '$file':\",p,\"->\", $1; p=$1}'\ndone\n\n# Non-descriptive link text\ngrep -rn '<a[^>]*>\\s*\\(here\\|click\\|more\\)\\s*</a>' content/ public/\n\n# Color contrast issues (requires manual review)\ngrep -r 'color:' public/**/*.css | grep -E '#[0-9a-fA-F]{3,6}'\n```\n\n**Step 2: Manual Review**\n- Keyboard navigation testing\n- Screen reader simulation\n- Color contrast validation\n- Form label verification\n- Focus indicator visibility\n\n**Step 3: Remediation**\n1. Add missing alt text (descriptive, not redundant)\n2. Fix heading hierarchy (no skipped levels)\n3. Improve link text (describe destination)\n4. Enhance color contrast (meet WCAG AA minimum)\n5. Add ARIA labels where semantic HTML insufficient\n6. Ensure keyboard accessibility\n\n### Workflow 4: Readability Improvement\n\nWhen improving readability:\n\n**Step 1: Analysis**\n- Calculate reading level (target Grade 8-10)\n- Identify complex sentences (>25 words)\n- Find passive voice instances\n- Locate jargon and technical terms\n- Measure paragraph length (target 3-5 sentences)\n\n**Step 2: Simplification**\n- Break up long sentences\n- Convert passive to active voice\n- Replace jargon with plain language\n- Add definitions for necessary technical terms\n- Split dense paragraphs\n- Use bullet points for lists\n\n**Step 3: Enhancement**\n- Add subheadings for scannability\n- Include visual elements (images, diagrams)\n- Use transition words for flow\n- Front-load important information\n- Add examples and analogies\n\n### Workflow 5: Image Alt Text Generation\n\nWhen analyzing images for alt text:\n\n**Step 1: Image Analysis**\nUse Read tool to analyze images with Claude's vision:\n```python\n# Read image to analyze with vision capabilities\nimage_content = Read(file_path=\"/path/to/image.jpg\")\n```\n\n**Step 2: Alt Text Generation**\nCreate descriptive alt text that:\n- Describes image content and context\n- Includes relevant keywords naturally\n- Keeps length under 125 characters\n- Avoids redundancy (\"image of\", \"picture of\")\n- Provides context for decorative vs. informative images\n\n**Step 3: Implementation**\n```bash\n# Update alt text in HTML\nEdit(file_path=\"page.html\", \n     old_string='<img src=\"hero.jpg\" alt=\"\">',\n     new_string='<img src=\"hero.jpg\" alt=\"Modern office workspace with natural lighting and collaborative environment\">')\n\n# Update alt text in markdown\nEdit(file_path=\"content.md\",\n     old_string='![](image.jpg)',\n     new_string='![Team collaboration session with digital whiteboard and sticky notes](image.jpg)')\n```\n\n## Content Optimization Principles\n\n### Copywriting Best Practices\n\n1. **Clarity Over Cleverness**: Clear, direct language beats clever wordplay\n2. **Benefits Over Features**: Focus on user value, not technical specs\n3. **Specificity**: Use concrete numbers and examples\n4. **Social Proof**: Include testimonials, case studies, statistics\n5. **Urgency and Scarcity**: Create appropriate FOMO\n6. **Strong CTAs**: Action-oriented, specific, visible\n7. **Storytelling**: Connect emotionally with narrative\n8. **Scannability**: Use formatting for quick comprehension\n\n### SEO Content Strategy\n\n1. **E-E-A-T Optimization** (Experience, Expertise, Authoritativeness, Trustworthiness):\n   - Author credentials and expertise\n   - Original research and insights\n   - Citations and external links\n   - Regular content updates\n\n2. **Topic Clusters and Pillar Content**:\n   - Comprehensive pillar pages (2000+ words)\n   - Cluster content linking to pillars\n   - Internal linking structure\n   - Semantic keyword coverage\n\n3. **User Intent Optimization**:\n   - Informational: Answer questions thoroughly\n   - Navigational: Clear site structure\n   - Transactional: Clear conversion paths\n   - Commercial: Comparison and review content\n\n### Accessibility Content Guidelines\n\n1. **Plain Language**: Write for 8th-grade reading level\n2. **Descriptive Links**: \"Read our accessibility guide\" not \"Click here\"\n3. **Alt Text Standards**:\n   - Informative images: Describe content and function\n   - Decorative images: Use empty alt (`alt=\"\"`)\n   - Complex images: Provide long description\n   - Text in images: Include text in alt\n\n4. **Color Independence**: Never rely on color alone to convey information\n5. **Consistent Navigation**: Predictable structure and labeling\n6. **Error Prevention**: Clear instructions and validation\n\n## Quality Assurance Checks\n\n### Pre-Publication Checklist\n\n**Content Quality**:\n- [ ] Grammar and spelling checked\n- [ ] Tone consistent with brand voice\n- [ ] Reading level appropriate (Grade 8-10)\n- [ ] Sentences average 15-20 words\n- [ ] Paragraphs 3-5 sentences\n- [ ] Active voice used predominantly\n- [ ] No jargon without explanation\n\n**SEO Optimization**:\n- [ ] Title tag 50-60 characters with primary keyword\n- [ ] Meta description 150-160 characters with CTA\n- [ ] H1 includes primary keyword\n- [ ] Headers (H2-H6) use secondary keywords\n- [ ] URL slug is clean and descriptive\n- [ ] Internal links with descriptive anchors\n- [ ] Images have keyword-relevant alt text\n- [ ] Content length meets minimum (300+ words)\n- [ ] Schema markup implemented (if applicable)\n\n**Accessibility**:\n- [ ] All images have appropriate alt text\n- [ ] Heading hierarchy is proper (no gaps)\n- [ ] Link text is descriptive\n- [ ] Color contrast meets WCAG AA (4.5:1)\n- [ ] Text can resize to 200%\n- [ ] Forms have proper labels\n- [ ] Semantic HTML used throughout\n- [ ] ARIA labels where needed\n\n**Performance**:\n- [ ] Content under 100KB uncompressed\n- [ ] No render-blocking content\n- [ ] Images optimized (coordinate with imagemagick agent)\n- [ ] Critical CSS inlined\n- [ ] Defer non-critical resources\n\n## Output Standards\n\nAlways provide:\n\n1. **Analysis Summary**: What was reviewed and key findings\n2. **Priority Issues**: Critical, high, medium, low categorization\n3. **Specific Recommendations**: Actionable improvements with examples\n4. **Before/After Examples**: Show improvements clearly\n5. **Implementation Guide**: Step-by-step fixes\n6. **Validation Steps**: How to verify improvements\n7. **Performance Impact**: Expected improvements to metrics\n8. **Next Steps**: Ongoing optimization recommendations\n\n## Tool Integration\n\n### MCP Browser Tools\n\nUse browser tools for real-world testing:\n\n```python\n# Navigate to page for testing\nmcp__mcp-browser__browser_navigate(port=9222, url=\"http://localhost:3000\")\n\n# Capture screenshot for visual review\nscreenshot = mcp__mcp-browser__browser_screenshot(port=9222)\n\n# Extract readable content for analysis\ncontent = mcp__mcp-browser__browser_extract_content(port=9222)\n\n# Check console for errors\nlogs = mcp__mcp-browser__browser_query_logs(port=9222, level_filter=[\"error\", \"warn\"])\n```\n\n### WebFetch for Competitor Analysis\n\n```python\n# Analyze competitor content\ncompetitor_content = WebFetch(\n    url=\"https://competitor.com/blog/topic\",\n    prompt=\"Analyze the content structure, keywords, and SEO optimization\"\n)\n\n# Research best practices\nindustry_trends = WebSearch(\n    query=\"content optimization best practices 2025\"\n)\n```\n\n### File Operations\n\n```bash\n# Find all content files\nfind content/ -type f \\( -name '*.html' -o -name '*.md' \\)\n\n# Search for specific content issues\ngrep -rn 'click here' content/  # Non-descriptive links\ngrep -rn '<img[^>]*>' content/ | grep -v 'alt='  # Missing alt text\n\n# Analyze content structure\ngrep -rh '^#' content/*.md | sort | uniq -c  # Markdown headers\n```\n\n## Success Metrics\n\nTrack and report improvements in:\n\n**Content Quality**:\n- Reading level (target Grade 8-10)\n- Average sentence length (15-20 words)\n- Active voice percentage (80%+)\n- Paragraph length (3-5 sentences)\n\n**SEO Performance**:\n- Keyword density (1-2%)\n- Internal link count\n- Content length (300+ words minimum)\n- Meta description completion (100%)\n- Schema markup implementation\n\n**Accessibility**:\n- WCAG compliance level (A, AA, AAA)\n- Alt text coverage (100% for informative images)\n- Color contrast ratio (4.5:1+ for AA)\n- Heading hierarchy errors (0)\n\n**Engagement**:\n- Time on page\n- Bounce rate\n- Scroll depth\n- Conversion rate\n- Social shares\n\n## Best Practices\n\n1. **Always** analyze existing content before making changes\n2. **Always** test in real browsers when possible (use MCP browser tools)\n3. **Always** validate accessibility improvements\n4. **Always** check SEO impact before and after\n5. **Always** maintain brand voice and style consistency\n6. **Never** sacrifice clarity for SEO keyword stuffing\n7. **Never** use generic alt text like \"image\" or \"photo\"\n8. **Never** skip accessibility checks\n9. **Never** ignore readability in favor of technical accuracy\n10. **Always** provide specific, actionable recommendations\n\nFocus on delivering practical, user-focused content improvements that enhance both search visibility and user experience while maintaining accessibility and performance standards.",
+  "knowledge": {
+    "domain_expertise": [
+      "Professional copywriting and content strategy",
+      "Advanced SEO optimization and keyword research",
+      "Readability analysis and plain language writing",
+      "WCAG 2.1/2.2 accessibility standards and testing",
+      "Semantic HTML and content structure optimization",
+      "Hemingway Editor readability principles",
+      "Grammarly-style grammar and tone analysis",
+      "Lighthouse performance insights for content",
+      "Claude Sonnet 4.5 vision capabilities for image analysis",
+      "Modern content marketing and engagement strategies",
+      "Conversion rate optimization (CRO) techniques",
+      "Content performance metrics and analytics"
+    ],
+    "best_practices": [
+      "ALWAYS audit existing content before optimization",
+      "Use MCP browser tools to test content in real browsers",
+      "Apply Hemingway principles: Grade 8-10 reading level, 15-20 word sentences",
+      "Follow Grammarly-style checks: clarity, conciseness, tone, active voice",
+      "Ensure WCAG AA compliance minimum (4.5:1 contrast, proper alt text, heading hierarchy)",
+      "Front-load SEO keywords in titles, H1s, and first paragraph",
+      "Generate descriptive alt text using Claude's vision capabilities",
+      "Test color contrast ratios and provide specific hex codes for fixes",
+      "Use WebFetch to analyze competitor content strategies",
+      "Prioritize user experience over keyword density",
+      "Maintain consistent brand voice across all content",
+      "Validate all recommendations with specific examples"
+    ],
+    "constraints": [
+      "Never sacrifice readability for SEO keyword stuffing",
+      "Always maintain WCAG AA minimum (preferably AAA where possible)",
+      "Ensure alt text stays under 125 characters for optimal screen reader experience",
+      "Keep meta descriptions between 150-160 characters",
+      "Maintain title tags between 50-60 characters",
+      "Target Grade 8-10 reading level for general audiences",
+      "Preserve brand voice and style guidelines",
+      "Avoid making content changes without user approval",
+      "Always provide rationale for recommendations"
+    ],
+    "examples": [
+      {
+        "name": "SEO Content Audit",
+        "description": "Comprehensive SEO audit of website content",
+        "input": "Audit website content for SEO optimization",
+        "process": "Analyze titles, meta descriptions, headers, keywords, internal links, and provide prioritized recommendations",
+        "output": "Detailed report with specific improvements and implementation guide"
+      },
+      {
+        "name": "Accessibility Compliance Review",
+        "description": "WCAG 2.1 Level AA compliance audit",
+        "input": "Review content for accessibility compliance",
+        "process": "Check alt text, heading hierarchy, link text, color contrast, semantic HTML, and provide remediation steps",
+        "output": "Compliance report with specific fixes and validation steps"
+      },
+      {
+        "name": "Readability Improvement",
+        "description": "Improve content readability and engagement",
+        "input": "Make this content more readable for general audiences",
+        "process": "Analyze reading level, sentence complexity, paragraph structure, and rewrite for clarity",
+        "output": "Before/after comparison with specific improvements and metrics"
+      },
+      {
+        "name": "Image Alt Text Generation",
+        "description": "Generate descriptive alt text for images",
+        "input": "Create alt text for images in /assets/images/",
+        "process": "Analyze images with vision capabilities, generate keyword-relevant descriptive alt text",
+        "output": "Alt text for each image with implementation code"
+      }
+    ]
+  },
+  "dependencies": {
+    "system": [
+      "python3",
+      "bash",
+      "grep",
+      "find"
+    ],
+    "python": [],
+    "optional": true
+  },
+  "memory_routing": {
+    "description": "Stores content strategies, SEO optimization patterns, accessibility guidelines, and brand voice consistency",
+    "categories": [
+      "Content optimization strategies and patterns",
+      "SEO keyword research and implementation",
+      "Accessibility compliance guidelines and fixes",
+      "Brand voice and style consistency",
+      "Readability improvement techniques",
+      "Conversion optimization patterns",
+      "Content performance insights"
+    ],
+    "keywords": [
+      "content",
+      "copywriting",
+      "seo",
+      "optimization",
+      "readability",
+      "accessibility",
+      "wcag",
+      "alt text",
+      "meta description",
+      "title tag",
+      "keywords",
+      "heading",
+      "structure",
+      "engagement",
+      "conversion",
+      "cta",
+      "call to action",
+      "copy",
+      "writing",
+      "grammar",
+      "style",
+      "tone",
+      "voice",
+      "lighthouse",
+      "performance",
+      "semantic html"
+    ],
+    "routing_paths": [
+      "/content/",
+      "/public/",
+      "/static/",
+      "/assets/",
+      "/blog/",
+      "/pages/",
+      "/posts/"
+    ]
+  },
+  "interactions": {
+    "input_format": {
+      "required_fields": [
+        "task"
+      ],
+      "optional_fields": [
+        "target_audience",
+        "brand_guidelines",
+        "content_paths",
+        "optimization_goals",
+        "accessibility_level"
+      ]
+    },
+    "output_format": {
+      "structure": "markdown",
+      "includes": [
+        "analysis_summary",
+        "priority_issues",
+        "specific_recommendations",
+        "before_after_examples",
+        "implementation_guide",
+        "validation_steps",
+        "performance_impact",
+        "next_steps"
+      ]
+    },
+    "handoff_agents": [
+      "imagemagick",
+      "engineer",
+      "documentation",
+      "qa"
+    ],
+    "triggers": [
+      {
+        "pattern": "content.*optimi[zs]ation",
+        "confidence": 0.9
+      },
+      {
+        "pattern": "seo|search.*optimi[zs]ation",
+        "confidence": 0.85
+      },
+      {
+        "pattern": "readability|accessibility|wcag",
+        "confidence": 0.85
+      },
+      {
+        "pattern": "alt.*text|meta.*description",
+        "confidence": 0.8
+      },
+      {
+        "pattern": "copywriting|copy.*improvement",
+        "confidence": 0.8
+      }
+    ]
+  },
+  "testing": {
+    "test_cases": [
+      {
+        "name": "Content Quality Audit",
+        "input": "Audit the content quality of our homepage",
+        "expected_behavior": "Analyze grammar, readability, structure, and provide specific improvements",
+        "validation_criteria": [
+          "identifies_quality_issues",
+          "provides_specific_fixes",
+          "includes_readability_metrics",
+          "offers_before_after_examples"
+        ]
+      },
+      {
+        "name": "SEO Optimization",
+        "input": "Optimize this blog post for SEO",
+        "expected_behavior": "Analyze and improve titles, meta descriptions, headers, keywords, and internal links",
+        "validation_criteria": [
+          "optimizes_title_tags",
+          "improves_meta_descriptions",
+          "enhances_header_structure",
+          "recommends_keyword_placement"
+        ]
+      },
+      {
+        "name": "Accessibility Compliance",
+        "input": "Check accessibility compliance for our content",
+        "expected_behavior": "Audit WCAG compliance and provide remediation steps",
+        "validation_criteria": [
+          "identifies_accessibility_issues",
+          "provides_wcag_compliance_level",
+          "offers_specific_fixes",
+          "includes_validation_steps"
+        ]
+      },
+      {
+        "name": "Alt Text Generation",
+        "input": "Generate alt text for images in /assets/products/",
+        "expected_behavior": "Analyze images and create descriptive, keyword-relevant alt text",
+        "validation_criteria": [
+          "uses_vision_capabilities",
+          "generates_descriptive_text",
+          "includes_relevant_keywords",
+          "keeps_under_125_characters"
+        ]
+      }
+    ],
+    "performance_benchmarks": {
+      "response_time": 300,
+      "token_usage": 10240,
+      "success_rate": 0.93
+    }
+  }
+}

claude_mpm/cli/__init__.py

@@ -36,6 +36,7 @@ from .commands import (  # run_guarded_session is imported lazily to avoid loadi
 )
 from .commands.analyze_code import manage_analyze_code
 from .commands.dashboard import manage_dashboard
+from .commands.upgrade import upgrade
 from .parser import create_parser, preprocess_args
 from .utils import ensure_directories, setup_logging
 
@@ -232,6 +233,9 @@ def main(argv: Optional[list] = None):
         # Re-enabled: MCP pre-warming is safe with subprocess daemon (v4.2.40)
         # The subprocess approach avoids fork() issues entirely
         _verify_mcp_gateway_startup()
+
+        # Check for updates (non-blocking, async)
+        _check_for_updates_async()
     else:
         # Still need directories for configure command to work
         ensure_directories()
@@ -544,6 +548,83 @@ def _verify_mcp_gateway_startup():
         # Continue execution - MCP gateway issues shouldn't block startup
 
 
+def _check_for_updates_async():
+    """
+    Check for updates in background thread (non-blocking).
+
+    WHY: Users should be notified of new versions and have an easy way to upgrade
+    without manually checking PyPI/npm. This runs asynchronously on startup to avoid
+    blocking the CLI.
+
+    DESIGN DECISION: This is non-blocking and non-critical - failures are logged
+    but don't prevent startup. Only runs for pip/pipx/npm installations, skips
+    editable/development installations.
+    """
+
+    def run_update_check():
+        """Inner function to run in background thread."""
+        loop = None
+        try:
+            import asyncio
+
+            from ..core.logger import get_logger
+            from ..services.self_upgrade_service import SelfUpgradeService
+
+            logger = get_logger("upgrade_check")
+
+            # Create new event loop for this thread
+            loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(loop)
+
+            # Create upgrade service and check for updates
+            upgrade_service = SelfUpgradeService()
+
+            # Skip for editable installs (development mode)
+            from ..services.self_upgrade_service import InstallationMethod
+
+            if upgrade_service.installation_method == InstallationMethod.EDITABLE:
+                logger.debug("Skipping version check for editable installation")
+                return
+
+            # Check and prompt for upgrade if available (non-blocking)
+            loop.run_until_complete(upgrade_service.check_and_prompt_on_startup())
+
+        except Exception as e:
+            # Non-critical - log but don't fail startup
+            try:
+                from ..core.logger import get_logger
+
+                logger = get_logger("upgrade_check")
+                logger.debug(f"Update check failed (non-critical): {e}")
+            except Exception:
+                pass  # Avoid any errors in error handling
+        finally:
+            # Properly clean up event loop
+            if loop is not None:
+                try:
+                    # Cancel all running tasks
+                    pending = asyncio.all_tasks(loop)
+                    for task in pending:
+                        task.cancel()
+                    # Wait for tasks to complete cancellation
+                    if pending:
+                        loop.run_until_complete(
+                            asyncio.gather(*pending, return_exceptions=True)
+                        )
+                except Exception:
+                    pass  # Ignore cleanup errors
+                finally:
+                    loop.close()
+                    # Clear the event loop reference to help with cleanup
+                    asyncio.set_event_loop(None)
+
+    # Run update check in background thread to avoid blocking startup
+    import threading
+
+    update_check_thread = threading.Thread(target=run_update_check, daemon=True)
+    update_check_thread.start()
+
+
 def _ensure_run_attributes(args):
     """
     Ensure run command attributes exist when defaulting to run.
@@ -657,6 +738,7 @@ def _execute_command(command: str, args) -> int:
         CLICommands.CLEANUP.value: cleanup_memory,
         CLICommands.MCP.value: manage_mcp,
         CLICommands.DOCTOR.value: run_doctor,
+        CLICommands.UPGRADE.value: upgrade,
         "debug": manage_debug,  # Add debug command
         "mpm-init": None,  # Will be handled separately with lazy import
     }

claude_mpm/cli/commands/mpm_init.py

@@ -54,7 +54,6 @@ class MPMInitCommand:
         framework: Optional[str] = None,
         force: bool = False,
         verbose: bool = False,
-        use_venv: bool = False,
         ast_analysis: bool = True,
         update_mode: bool = False,
         review_only: bool = False,
@@ -76,7 +75,6 @@ class MPMInitCommand:
             framework: Specific framework if applicable
             force: Force initialization even if project already configured
             verbose: Show detailed output
-            use_venv: Force use of venv instead of mamba
             ast_analysis: Enable AST analysis for enhanced documentation
             update_mode: Update existing CLAUDE.md instead of recreating
             review_only: Review project state without making changes
@@ -187,9 +185,7 @@ class MPMInitCommand:
                 task = progress.add_task(task_desc, total=None)
 
                 # Run the initialization through subprocess
-                result = self._run_initialization(
-                    prompt, verbose, use_venv, update_mode
-                )
+                result = self._run_initialization(prompt, verbose, update_mode)
 
                 complete_desc = (
                     "[green]✓ Update complete"
@@ -405,17 +401,10 @@ The final CLAUDE.md should be a comprehensive, well-organized guide that any AI
 
         return base_prompt
 
-    def _build_claude_mpm_command(
-        self, verbose: bool, use_venv: bool = False
-    ) -> List[str]:
+    def _build_claude_mpm_command(self, verbose: bool) -> List[str]:
         """Build the claude-mpm run command with appropriate arguments."""
         cmd = [str(self.claude_mpm_script)]
 
-        # Add venv flag if requested or if mamba issues detected
-        # This goes BEFORE the subcommand
-        if use_venv:
-            cmd.append("--use-venv")
-
         # Add top-level flags that go before 'run' subcommand
         cmd.append("--no-check-dependencies")
 
@@ -1376,7 +1365,6 @@ preserving valuable project-specific information while refreshing standard secti
         self,
         prompt: str,
         verbose: bool,
-        use_venv: bool = False,
         update_mode: bool = False,
     ) -> Dict:
         """Run the initialization through subprocess calling claude-mpm."""
@@ -1392,7 +1380,7 @@ preserving valuable project-specific information while refreshing standard secti
 
             try:
                 # Build the command
-                cmd = self._build_claude_mpm_command(verbose, use_venv)
+                cmd = self._build_claude_mpm_command(verbose)
                 # Add the input file flag
                 cmd.extend(["-i", prompt_file])
 
@@ -1409,30 +1397,6 @@ preserving valuable project-specific information while refreshing standard secti
                     cwd=str(self.project_path),
                     check=False,
                 )
-
-                # Check for environment-specific errors
-                if "libmamba" in result.stderr or "tree-sitter" in result.stderr:
-                    console.print(
-                        "\n[yellow]⚠️  Environment dependency issue detected.[/yellow]"
-                    )
-                    console.print(
-                        "[yellow]Attempting alternative initialization method...[/yellow]\n"
-                    )
-
-                    # Try again with venv flag to bypass mamba
-                    cmd_venv = self._build_claude_mpm_command(verbose, use_venv=True)
-                    cmd_venv.extend(["-i", prompt_file])
-
-                    if verbose:
-                        console.print(f"[dim]Retrying with: {' '.join(cmd_venv)}[/dim]")
-
-                    result = subprocess.run(
-                        cmd_venv,
-                        capture_output=not verbose,
-                        text=True,
-                        cwd=str(self.project_path),
-                        check=False,
-                    )
             finally:
                 # Clean up temporary file
 
@@ -1483,15 +1447,6 @@ preserving valuable project-specific information while refreshing standard secti
                 if result.stderr
                 else result.stdout if result.stdout else "Unknown error occurred"
             )
-            # Clean up mamba warnings from error message
-            if "libmamba" in error_msg:
-                lines = error_msg.split("\n")
-                error_lines = [
-                    line
-                    for line in lines
-                    if not line.startswith("warning") and line.strip()
-                ]
-                error_msg = "\n".join(error_lines) if error_lines else error_msg
 
             logger.error(f"claude-mpm run failed: {error_msg}")
             return {

claude_mpm/cli/commands/upgrade.py

@@ -0,0 +1,152 @@
+"""
+Upgrade command implementation for claude-mpm.
+
+WHY: This module provides a manual upgrade command that allows users to check
+for and install the latest version of claude-mpm without waiting for the
+automatic startup check.
+
+DESIGN DECISIONS:
+- Use BaseCommand for consistent CLI patterns
+- Leverage SelfUpgradeService for upgrade functionality
+- Support multiple installation methods (pip, pipx, npm)
+- Skip editable/development installations (must upgrade manually)
+- Provide clear feedback on available updates and upgrade progress
+"""
+
+import asyncio
+
+from ..shared import BaseCommand, CommandResult
+
+
+class UpgradeCommand(BaseCommand):
+    """Upgrade command using shared utilities."""
+
+    def __init__(self):
+        super().__init__("upgrade")
+
+    def validate_args(self, args) -> str:
+        """Validate command arguments."""
+        # Upgrade command doesn't require specific validation
+        return None
+
+    def run(self, args) -> CommandResult:
+        """Execute the upgrade command."""
+        try:
+            from ...services.self_upgrade_service import (
+                InstallationMethod,
+                SelfUpgradeService,
+            )
+
+            # Create upgrade service
+            upgrade_service = SelfUpgradeService()
+
+            # Check installation method
+            if upgrade_service.installation_method == InstallationMethod.EDITABLE:
+                self.logger.info(
+                    "Editable installation detected - upgrade must be done manually"
+                )
+                print("\n⚠️  Editable Installation Detected")
+                print(
+                    "\nYou are running claude-mpm from an editable installation (development mode)."
+                )
+                print("To upgrade, run:")
+                print("  cd /path/to/claude-mpm")
+                print("  git pull")
+                print("  pip install -e .")
+                return CommandResult.success_result(
+                    "Upgrade information provided for editable installation"
+                )
+
+            # Check for updates
+            print("\n🔍 Checking for updates...")
+            loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(loop)
+            try:
+                update_info = loop.run_until_complete(
+                    upgrade_service.check_for_update()
+                )
+            finally:
+                loop.close()
+
+            if not update_info or not update_info.get("update_available"):
+                print(
+                    f"\n✅ You are already on the latest version (v{upgrade_service.current_version})"
+                )
+                return CommandResult.success_result("Already on latest version")
+
+            # Display update information
+            current = update_info["current"]
+            latest = update_info["latest"]
+            method = update_info.get("installation_method", "unknown")
+
+            print("\n🎉 New version available!")
+            print(f"   Current: v{current}")
+            print(f"   Latest:  v{latest}")
+            print(f"   Installation method: {method}")
+
+            # Check if --yes flag is set for non-interactive upgrade
+            force_upgrade = getattr(args, "yes", False) or getattr(args, "force", False)
+
+            if not force_upgrade:
+                # Prompt user for confirmation
+                if not upgrade_service.prompt_for_upgrade(update_info):
+                    print("\n⏸️  Upgrade cancelled by user")
+                    return CommandResult.success_result("Upgrade cancelled by user")
+
+            # Perform upgrade
+            success, message = upgrade_service.perform_upgrade(update_info)
+            print(f"\n{message}")
+
+            if success:
+                # Restart after successful upgrade
+                upgrade_service.restart_after_upgrade()
+                # Note: This line won't be reached as restart replaces process
+                return CommandResult.success_result(f"Upgraded to v{latest}")
+            return CommandResult.error_result("Upgrade failed")
+
+        except Exception as e:
+            self.logger.error(f"Error during upgrade: {e}", exc_info=True)
+            return CommandResult.error_result(f"Error during upgrade: {e}")
+
+
+def add_upgrade_parser(subparsers):
+    """
+    Add upgrade command parser.
+
+    WHY: This command helps users check for and install the latest version of
+    claude-mpm without waiting for the automatic startup check.
+
+    Args:
+        subparsers: The subparser action object to add the upgrade command to
+    """
+    parser = subparsers.add_parser(
+        "upgrade",
+        help="Check for and install latest claude-mpm version",
+        description="Check for updates and upgrade claude-mpm to the latest version from PyPI/npm",
+    )
+
+    parser.add_argument(
+        "-y",
+        "--yes",
+        action="store_true",
+        help="Skip confirmation prompt and upgrade immediately if available",
+    )
+
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Force upgrade even if already on latest version (alias for --yes)",
+    )
+
+    return parser
+
+
+def upgrade(args):
+    """
+    Main entry point for upgrade command.
+
+    This function maintains backward compatibility while using the new BaseCommand pattern.
+    """
+    command = UpgradeCommand()
+    result = command.execute(args)
+    return result.exit_code

claude_mpm/cli/parsers/base_parser.py

@@ -423,6 +423,11 @@ def create_parser(
 
         add_doctor_parser(subparsers)
 
+        # Add upgrade command
+        from ..commands.upgrade import add_upgrade_parser
+
+        add_upgrade_parser(subparsers)
+
         # Add verify command for MCP service verification
         from ..commands.verify import add_parser as add_verify_parser
 

claude_mpm/cli/parsers/mpm_init_parser.py

@@ -131,11 +131,6 @@ def add_mpm_init_subparser(subparsers: Any) -> None:
         action="store_true",
         help="Create comprehensive setup including CI/CD, testing, and deployment configs",
     )
-    init_group.add_argument(
-        "--use-venv",
-        action="store_true",
-        help="Use traditional Python venv instead of mamba/conda environment",
-    )
     init_group.add_argument(
         "--ast-analysis",
         action="store_true",

claude_mpm/constants.py

@@ -44,6 +44,7 @@ class CLICommands(str, Enum):
     MCP = "mcp"
     DOCTOR = "doctor"
     DASHBOARD = "dashboard"
+    UPGRADE = "upgrade"
 
     def with_prefix(self, prefix: CLIPrefix = CLIPrefix.MPM) -> str:
         """Get command with prefix."""

claude_mpm/services/core/memory_manager.py

@@ -40,9 +40,11 @@ class MemoryManager(IMemoryManager):
     4. Legacy format migration (e.g., PM.md -> PM_memories.md)
     5. Memory caching for performance
 
-    Memory Loading Order:
-    - User-level memories: ~/.claude-mpm/memories/ (global defaults)
-    - Project-level memories: ./.claude-mpm/memories/ (overrides user)
+    Memory Scope:
+    - Project-level ONLY: ./.claude-mpm/memories/ (project-scoped isolation)
+    - User-level memories are NOT loaded to prevent cross-project contamination
+
+    Note: As of v4.7.10+, memories are strictly project-scoped for complete isolation.
     """
 
     def __init__(
@@ -279,7 +281,10 @@ class MemoryManager(IMemoryManager):
 
     def _load_actual_memories(self, deployed_agents: Set[str]) -> Dict[str, Any]:
         """
-        Load actual memories from both user and project directories.
+        Load actual memories from project directory only.
+
+        Memories are project-scoped to ensure complete isolation between projects.
+        User-level memories are no longer supported to prevent cross-project contamination.
 
         Args:
             deployed_agents: Set of deployed agent names
@@ -287,32 +292,14 @@ class MemoryManager(IMemoryManager):
         Returns:
             Dictionary with actual_memories and agent_memories
         """
-        # Define memory directories in priority order
-        user_memories_dir = Path.home() / ".claude-mpm" / "memories"
+        # Define project memory directory (project-scoped only)
         project_memories_dir = Path.cwd() / ".claude-mpm" / "memories"
 
         # Dictionary to store aggregated memories
         pm_memories = []
         agent_memories_dict = {}
 
-        # Load memories from user directory first
-        if user_memories_dir.exists():
-            self.logger.info(
-                f"Loading user-level memory files from: {user_memories_dir}"
-            )
-            self._load_memories_from_directory(
-                user_memories_dir,
-                deployed_agents,
-                pm_memories,
-                agent_memories_dict,
-                "user",
-            )
-        else:
-            self.logger.debug(
-                f"No user memories directory found at: {user_memories_dir}"
-            )
-
-        # Load memories from project directory (overrides user memories)
+        # Load memories from project directory only
         if project_memories_dir.exists():
             self.logger.info(
                 f"Loading project-level memory files from: {project_memories_dir}"

claude_mpm/services/self_upgrade_service.py

@@ -0,0 +1,342 @@
+"""
+Self-Upgrade Service
+====================
+
+Handles version checking and self-upgrade functionality for claude-mpm.
+Supports pip, pipx, and npm installations with automatic detection.
+
+WHY: Users should be notified of updates and have an easy way to upgrade
+without manually running installation commands.
+
+DESIGN DECISIONS:
+- Detects installation method (pip/pipx/npm/editable)
+- Non-blocking version checks with caching
+- Interactive upgrade prompts with confirmation
+- Automatic restart after upgrade
+- Graceful failure handling (never breaks existing installation)
+"""
+
+import os
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Dict, Optional, Tuple
+
+from packaging import version
+
+from ..core.logger import get_logger
+from ..core.unified_paths import PathContext
+from .mcp_gateway.utils.package_version_checker import PackageVersionChecker
+
+
+class InstallationMethod:
+    """Installation method enumeration."""
+
+    PIP = "pip"
+    PIPX = "pipx"
+    NPM = "npm"
+    EDITABLE = "editable"
+    UNKNOWN = "unknown"
+
+
+class SelfUpgradeService:
+    """
+    Service for checking and performing self-upgrades.
+
+    Capabilities:
+    - Detect current installation method
+    - Check PyPI/npm for latest version
+    - Prompt user for upgrade confirmation
+    - Execute upgrade command
+    - Restart after upgrade
+    """
+
+    def __init__(self):
+        """Initialize the self-upgrade service."""
+        self.logger = get_logger("SelfUpgradeService")
+        self.version_checker = PackageVersionChecker()
+        self.current_version = self._get_current_version()
+        self.installation_method = self._detect_installation_method()
+
+    def _get_current_version(self) -> str:
+        """
+        Get the current installed version.
+
+        Returns:
+            Version string (e.g., "4.7.10")
+        """
+        try:
+            from .. import __version__
+
+            return __version__
+        except ImportError:
+            # Fallback to VERSION file
+            try:
+                version_file = Path(__file__).parent.parent / "VERSION"
+                if version_file.exists():
+                    return version_file.read_text().strip()
+            except Exception:
+                pass
+
+        return "unknown"
+
+    def _detect_installation_method(self) -> str:
+        """
+        Detect how claude-mpm was installed.
+
+        Returns:
+            Installation method constant
+        """
+        # Check for editable install
+        if PathContext.detect_deployment_context().name in [
+            "DEVELOPMENT",
+            "EDITABLE_INSTALL",
+        ]:
+            return InstallationMethod.EDITABLE
+
+        # Check for pipx by looking at executable path
+        executable = sys.executable
+        if "pipx" in executable:
+            return InstallationMethod.PIPX
+
+        # Check if npm wrapper is present
+        try:
+            result = subprocess.run(
+                ["npm", "list", "-g", "claude-mpm"],
+                check=False,
+                capture_output=True,
+                text=True,
+                timeout=5,
+            )
+            if result.returncode == 0 and "claude-mpm" in result.stdout:
+                return InstallationMethod.NPM
+        except Exception:
+            pass
+
+        # Default to pip
+        return InstallationMethod.PIP
+
+    async def check_for_update(
+        self, cache_ttl: Optional[int] = None
+    ) -> Optional[Dict[str, any]]:
+        """
+        Check if an update is available.
+
+        Args:
+            cache_ttl: Cache time-to-live in seconds (default: 24 hours)
+
+        Returns:
+            Dict with update info or None:
+            {
+                "current": "4.7.10",
+                "latest": "4.7.11",
+                "update_available": True,
+                "installation_method": "pipx",
+                "upgrade_command": "pipx upgrade claude-mpm"
+            }
+        """
+        if self.current_version == "unknown":
+            self.logger.warning("Cannot check for updates: version unknown")
+            return None
+
+        # Check PyPI for Python installations
+        if self.installation_method in [
+            InstallationMethod.PIP,
+            InstallationMethod.PIPX,
+        ]:
+            result = await self.version_checker.check_for_update(
+                "claude-mpm", self.current_version, cache_ttl
+            )
+            if result and result.get("update_available"):
+                result["installation_method"] = self.installation_method
+                result["upgrade_command"] = self._get_upgrade_command()
+                return result
+
+        # Check npm for npm installations
+        elif self.installation_method == InstallationMethod.NPM:
+            npm_version = await self._check_npm_version()
+            if npm_version:
+                current_ver = version.parse(self.current_version)
+                latest_ver = version.parse(npm_version)
+                if latest_ver > current_ver:
+                    return {
+                        "current": self.current_version,
+                        "latest": npm_version,
+                        "update_available": True,
+                        "installation_method": InstallationMethod.NPM,
+                        "upgrade_command": self._get_upgrade_command(),
+                        "checked_at": datetime.now(timezone.utc).isoformat(),
+                    }
+
+        return None
+
+    async def _check_npm_version(self) -> Optional[str]:
+        """
+        Check npm registry for latest version.
+
+        Returns:
+            Latest version string or None
+        """
+        try:
+            result = subprocess.run(
+                ["npm", "view", "claude-mpm", "version"],
+                check=False,
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+            if result.returncode == 0:
+                return result.stdout.strip()
+        except Exception as e:
+            self.logger.debug(f"npm version check failed: {e}")
+
+        return None
+
+    def _get_upgrade_command(self) -> str:
+        """
+        Get the appropriate upgrade command for current installation method.
+
+        Returns:
+            Shell command string to upgrade claude-mpm
+        """
+        if self.installation_method == InstallationMethod.PIPX:
+            return "pipx upgrade claude-mpm"
+        if self.installation_method == InstallationMethod.NPM:
+            return "npm update -g claude-mpm"
+        if self.installation_method == InstallationMethod.PIP:
+            return f"{sys.executable} -m pip install --upgrade claude-mpm"
+        if self.installation_method == InstallationMethod.EDITABLE:
+            return "git pull && pip install -e ."
+        return "pip install --upgrade claude-mpm"
+
+    def prompt_for_upgrade(self, update_info: Dict[str, any]) -> bool:
+        """
+        Prompt user to upgrade.
+
+        Args:
+            update_info: Update information dict
+
+        Returns:
+            True if user confirms upgrade, False otherwise
+        """
+        current = update_info["current"]
+        latest = update_info["latest"]
+        method = update_info.get("installation_method", "unknown")
+
+        print("\n🎉 New version available!")
+        print(f"   Current: v{current}")
+        print(f"   Latest:  v{latest}")
+        print(f"   Installation method: {method}")
+        print(f"\nTo upgrade, run: {update_info['upgrade_command']}")
+
+        try:
+            response = input("\nWould you like to upgrade now? [y/N]: ").strip().lower()
+            return response in ["y", "yes"]
+        except (KeyboardInterrupt, EOFError):
+            print("\n")
+            return False
+
+    def perform_upgrade(self, update_info: Dict[str, any]) -> Tuple[bool, str]:
+        """
+        Perform the upgrade.
+
+        Args:
+            update_info: Update information dict
+
+        Returns:
+            Tuple of (success: bool, message: str)
+        """
+        command = update_info["upgrade_command"]
+
+        # Don't upgrade editable installs automatically
+        if self.installation_method == InstallationMethod.EDITABLE:
+            return (
+                False,
+                "Editable installation detected. Please update manually with: git pull && pip install -e .",
+            )
+
+        print("\n⏳ Upgrading claude-mpm...")
+        print(f"   Running: {command}")
+
+        try:
+            # Execute upgrade command
+            result = subprocess.run(
+                command,
+                check=False,
+                shell=True,
+                capture_output=True,
+                text=True,
+                timeout=300,  # 5 minutes
+            )
+
+            if result.returncode == 0:
+                return (True, f"✅ Successfully upgraded to v{update_info['latest']}")
+            error_msg = result.stderr or result.stdout or "Unknown error"
+            return (False, f"❌ Upgrade failed: {error_msg}")
+
+        except subprocess.TimeoutExpired:
+            return (False, "❌ Upgrade timed out")
+        except Exception as e:
+            return (False, f"❌ Upgrade failed: {e!s}")
+
+    def restart_after_upgrade(self) -> None:
+        """
+        Restart claude-mpm after a successful upgrade.
+
+        Preserves original command line arguments.
+        """
+        print("\n🔄 Restarting claude-mpm...")
+
+        try:
+            # Get current command line arguments
+            args = sys.argv[:]
+
+            # Replace current process with new one
+            if self.installation_method == InstallationMethod.PIPX:
+                # Use pipx run
+                os.execvp("pipx", ["pipx", "run", "claude-mpm", *args[1:]])
+            elif self.installation_method == InstallationMethod.NPM:
+                # Use npm executable
+                os.execvp("claude-mpm", args)
+            else:
+                # Use Python executable
+                os.execvp(sys.executable, [sys.executable, *args])
+
+        except Exception as e:
+            self.logger.error(f"Failed to restart: {e}")
+            print(f"\n⚠️  Restart failed: {e}")
+            print("Please restart claude-mpm manually.")
+
+    async def check_and_prompt_on_startup(
+        self, auto_upgrade: bool = False
+    ) -> Optional[Dict[str, any]]:
+        """
+        Check for updates on startup and optionally prompt user.
+
+        Args:
+            auto_upgrade: If True, upgrade without prompting (use with caution)
+
+        Returns:
+            Update info if available, None otherwise
+        """
+        # Skip for editable installs
+        if self.installation_method == InstallationMethod.EDITABLE:
+            return None
+
+        try:
+            update_info = await self.check_for_update()
+
+            if update_info and update_info.get("update_available"):
+                if auto_upgrade or self.prompt_for_upgrade(update_info):
+                    success, message = self.perform_upgrade(update_info)
+                    print(message)
+                    if success:
+                        self.restart_after_upgrade()
+
+                return update_info
+
+        except Exception as e:
+            self.logger.debug(f"Startup version check failed: {e}")
+
+        return None

{claude_mpm-4.7.9.dist-info → claude_mpm-4.8.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-mpm
-Version: 4.7.9
+Version: 4.8.0
 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.7.9.dist-info → claude_mpm-4.8.0.dist-info}/RECORD

@@ -1,8 +1,8 @@
 claude_mpm/BUILD_NUMBER,sha256=9JfxhnDtr-8l3kCP2U5TVXSErptHoga8m7XA8zqgGOc,4
-claude_mpm/VERSION,sha256=7-IAGCtmvIwdixVQJDoq-zKnNOnvOHQb0ZEINbbBPJ4,6
+claude_mpm/VERSION,sha256=STjviM123X9il6PR0MV6-cjkIOk1nnePP8NyWoeBrwo,6
 claude_mpm/__init__.py,sha256=UCw6j9e_tZQ3kJtTqmdfNv7MHyw9nD1jkj80WurwM2g,2064
 claude_mpm/__main__.py,sha256=Ro5UBWBoQaSAIoSqWAr7zkbLyvi4sSy28WShqAhKJG0,723
-claude_mpm/constants.py,sha256=cChN3myrAcF3jC-6DvHnBFTEnwlDk-TAsIXPvUZr_yw,5953
+claude_mpm/constants.py,sha256=sLjJF6Kw7H4V9WWeaEYltM-77TgXqzEMX5vx4ukM5-0,5977
 claude_mpm/init.py,sha256=HFJR_JmTHa53FAhbGusm3P1iXT6VR6V7S-YJz4pOZ1Q,15967
 claude_mpm/ticket_wrapper.py,sha256=qe5xY579t7_7fK5nyeAfHN_fr7CXdeOD3jfXEc8-7yo,828
 claude_mpm/agents/BASE_AGENT_TEMPLATE.md,sha256=aK9qxS1FRpm_8VaB5GI2I6YA9Wr8dGHuea_txMFe44M,5524
@@ -34,6 +34,7 @@ claude_mpm/agents/templates/agentic-coder-optimizer.json,sha256=injWgR0aHjFh88wL
 claude_mpm/agents/templates/api_qa.json,sha256=FxDFIDsihrw8acBugsiY9RtkNtKF0fUT20f9ox6jihU,5786
 claude_mpm/agents/templates/clerk-ops.json,sha256=4xB-ndC-hpOvrjJTeVLZeSrN1hTyrDf3RbaiamZQvTU,17116
 claude_mpm/agents/templates/code_analyzer.json,sha256=5t5a9gzKW8BDv9-GgZx2dhEJ0dPlu5YO3zuoOJIuWHQ,7417
+claude_mpm/agents/templates/content-agent.json,sha256=xLgZdtYTab-BM8a9L0szJap6_6tM_xxCZxOdR5wfp1I,29956
 claude_mpm/agents/templates/dart_engineer.json,sha256=-GSr98Ut_raIZdL73Wcv5lMK2JG4mGhzAVnPjVYIxX4,22219
 claude_mpm/agents/templates/data_engineer.json,sha256=FdjmqOB1cc-cDDOV7IYjOoiavnGNxXT0_7ICkRApey4,19562
 claude_mpm/agents/templates/documentation.json,sha256=3rk1hZmqG65CKOZ8RwVAPfQe2a4b5xu_K29RS4tGeK8,10026
@@ -64,7 +65,7 @@ claude_mpm/agents/templates/.claude-mpm/memories/README.md,sha256=vEiG7cPjHRZfwX
 claude_mpm/agents/templates/.claude-mpm/memories/engineer_memories.md,sha256=KMZSJrQi-wHOwfl2C0m3A4PpC4QuBtDolAtVybGahKc,77
 claude_mpm/agents/templates/logs/prompts/agent_engineer_20250826_014258_728.md,sha256=UBm4BycXtdaa-_l1VCh0alTGGOUSsnCbpKwbFuI-mUY,2219
 claude_mpm/agents/templates/logs/prompts/agent_engineer_20250901_010124_142.md,sha256=oPvFSYFnmJ4TkbTe4AZnNHWaJMJ-xqZP2WM6scUKQKo,13089
-claude_mpm/cli/__init__.py,sha256=0qyZe1R_9I_GJdyIfF6GatbZUVcaclxtvglPjN7dAIA,26270
+claude_mpm/cli/__init__.py,sha256=Ed8uPUqS5FmIAMxxIPxpo5JJX2ZWXIe5v-vx8K9jBEE,29373
 claude_mpm/cli/__main__.py,sha256=WnVGBwe10InxuZjJRFdwuMF6Gh16aXox6zFgxr0sRXk,847
 claude_mpm/cli/parser.py,sha256=Vqx9n-6Xo1uNhXR4rThmgWpZXTr0nOtkgDf3oMS9b0g,5855
 claude_mpm/cli/startup_logging.py,sha256=RTuyd6CbhiFQz7Z07LDDhK_ZAnZfuJ9B0NghVSntHFI,29390
@@ -96,12 +97,13 @@ claude_mpm/cli/commands/mcp_setup_external.py,sha256=hfBHkaioNa0JRDhahNEc8agyrUw
 claude_mpm/cli/commands/mcp_tool_commands.py,sha256=q17GzlFT3JiLTrDqwPO2tz1-fKmPO5QU449syTnKTz4,1283
 claude_mpm/cli/commands/memory.py,sha256=O4T5HGL-Ob_QPt2dZHQvoOrVohnaDKrBjyngq1Mcv1w,26185
 claude_mpm/cli/commands/monitor.py,sha256=Fjb68hf3dEwTFek2LV8Nh6iU0qEkY7qYlOn32IwNaNg,9566
-claude_mpm/cli/commands/mpm_init.py,sha256=njopKyRBzBT_FL-3LrqishRSeKtIESehzWinhUqmRpM,65724
+claude_mpm/cli/commands/mpm_init.py,sha256=OtdJMsFn7E9Ck56wWPrCvqw6j5dsN_VI098C3bteitc,63888
 claude_mpm/cli/commands/mpm_init_handler.py,sha256=b1CSwZYJ89wMorKzPOKS-RVxOKR2kT9yv9KQLvKkd2U,3532
 claude_mpm/cli/commands/run.py,sha256=PB2H55piOPTy4yo4OBgbUCjMlcz9K79wbwpxQVc9m5Q,48225
 claude_mpm/cli/commands/search.py,sha256=_0qbUnop8v758MHsB0fAop8FVxwygD59tec_-iN7pLE,9806
 claude_mpm/cli/commands/tickets.py,sha256=kl2dklTBnG3Y4jUUJ_PcEVsTx4CtVJfkGWboWBx_mQM,21234
 claude_mpm/cli/commands/uninstall.py,sha256=KGlVG6veEs1efLVjrZ3wSty7e1zVR9wpt-VXQA1RzWw,5945
+claude_mpm/cli/commands/upgrade.py,sha256=NYMVONNlj78WHoQ6eyVInroE95AeQxUY2_TpjYFTdYE,5409
 claude_mpm/cli/commands/verify.py,sha256=wmu2UYINK15q2e34TdlTyamvtLDE7r3Oj_XT9zpT5Kk,3687
 claude_mpm/cli/interactive/__init__.py,sha256=vQqUCgPFvLYA1Vkq-5pnY7Ow3A-IgdM0SByfNL1ZLTk,433
 claude_mpm/cli/interactive/agent_wizard.py,sha256=v3nKcLusU49ewjCqvgUWsG35UGc82pC7_Uv-ZzAHZ-c,36201
@@ -110,7 +112,7 @@ claude_mpm/cli/parsers/agent_manager_parser.py,sha256=TQEIm638ELM4X_AAGcn6WrJxlt
 claude_mpm/cli/parsers/agents_parser.py,sha256=R-9ESNXdjqr5iCEIcmbb2EPvcswW9UfJzMj5bAkgI4U,9042
 claude_mpm/cli/parsers/analyze_code_parser.py,sha256=cpJSMFbc3mqB4qrMBIEZiikzPekC2IQX-cjt9U2fHW4,5356
 claude_mpm/cli/parsers/analyze_parser.py,sha256=E00Ao0zwzbJPchs_AJt-aoQ7LQEtJPXRCNQ6Piivb4o,3908
-claude_mpm/cli/parsers/base_parser.py,sha256=Wejn4lAo-rMUQVP13PAehE6NoqmH2AD50HLKDf3QAKM,14169
+claude_mpm/cli/parsers/base_parser.py,sha256=iGYJ_-wIXkL4iVclJgrzQ2kz_of3CIqCwIM-FnFKEQI,14298
 claude_mpm/cli/parsers/config_parser.py,sha256=wp6NbV8_p9txP28MXFcQrri0JDIfGFM7u4aJbYJXcYQ,2699
 claude_mpm/cli/parsers/configure_parser.py,sha256=t3cwAQX3BfljDDRJH3i0LplpRprw5jdKcI9Uy3M8xtE,4382
 claude_mpm/cli/parsers/dashboard_parser.py,sha256=JBCM6v_iZhADr_Fwtk_d3up9AOod1avMab-vkNE61gE,3460
@@ -118,7 +120,7 @@ claude_mpm/cli/parsers/debug_parser.py,sha256=F7MZdmiXiPfiIPMv21ZUqB2cMT8Ho1LDmp
 claude_mpm/cli/parsers/mcp_parser.py,sha256=2j6ULhdu55Z2k_-Gu2QxIsFoTQFbDCEMSGePXSuPoQQ,6532
 claude_mpm/cli/parsers/memory_parser.py,sha256=ZwCDxJEgp-w03L-1tZsWTgisiwamP42s424bA5bvDJc,4760
 claude_mpm/cli/parsers/monitor_parser.py,sha256=PeoznSi_5Bw6THK_Espl8M20o6dKvvBSmFzAbovkaFQ,4920
-claude_mpm/cli/parsers/mpm_init_parser.py,sha256=iTMd3RjnHzz89Q0O5Lr0MYI_vOUuXQOHHI6D-Zy8PUE,7823
+claude_mpm/cli/parsers/mpm_init_parser.py,sha256=aGMwrHs7acB61sNDI0M7gf23yGDV4Q7b7iX7XnWC0yQ,7658
 claude_mpm/cli/parsers/run_parser.py,sha256=cs34qNonFZG8uYxTYEt0rXi2LcPz3pw8D8hxiywih6w,4927
 claude_mpm/cli/parsers/search_parser.py,sha256=L8-65kndg-zutSKpzj-eCvTNkeySCZ-WlSHdhk7pEak,6916
 claude_mpm/cli/parsers/tickets_parser.py,sha256=FYl-VNH7PrZzfZUCcjnf6F7g6JXnL8YDxwrmR5svIcg,6966
@@ -427,6 +429,7 @@ claude_mpm/services/project_port_allocator.py,sha256=L_EPuX_vGdv8vWWRVTpRk7F-v7u
 claude_mpm/services/recovery_manager.py,sha256=ptUYsguF6oKWnJnzPRSBuzUFVDXIcvsS3svT6MBTqCQ,25686
 claude_mpm/services/response_tracker.py,sha256=wBPgI5fH40xc7NHcCXQFOTPFTPSVbAZPqXIauXOJA5g,9575
 claude_mpm/services/runner_configuration_service.py,sha256=Qs84yrZfQv-DC0I2Xah1Qt9eunH4gS7LNMZ0mmymcqA,21311
+claude_mpm/services/self_upgrade_service.py,sha256=PuzHFQ3fQx7I9rmINLWs86o2KVyr-1StolLR-xnkOrQ,11246
 claude_mpm/services/session_management_service.py,sha256=axGZXpexWcYGnOMt5o8UQnFJUN3aVyjXRpFAcFrNKeg,10060
 claude_mpm/services/session_manager.py,sha256=ElguSoiy725VWS2iEqtcn0dUPIRrQrrON74aUzrWjRE,5147
 claude_mpm/services/socketio_client_manager.py,sha256=cZjIsnoi2VPXFA-5pNhoz5Vv3qv0iuSTy510TgAJU4U,18179
@@ -546,7 +549,7 @@ claude_mpm/services/core/__init__.py,sha256=evEayLlBqJvxMZhrhuK6aagXmNrKGSj8Jm9O
 claude_mpm/services/core/base.py,sha256=iA-F7DgGp-FJIMvQTiHQ68RkG_k-AtUWlArJPMw6ZPk,7297
 claude_mpm/services/core/cache_manager.py,sha256=dBHvvI6M67kaxFtAubi4IsWfbDZSct1siyKHTmCIrW8,11567
 claude_mpm/services/core/interfaces.py,sha256=FbLhWiOUMlvBfqjYBCeoWgsmRscQGBKteRMW-BGz4hQ,1261
-claude_mpm/services/core/memory_manager.py,sha256=2m-BYrNwh1yFjvz1VGB_Ndl_dtSp1xhpBcATaBiJQu0,26642
+claude_mpm/services/core/memory_manager.py,sha256=aajBuvBzTq0-EZrjnBjGRdUSaa6MpbfqHAtCePnn7aQ,26258
 claude_mpm/services/core/path_resolver.py,sha256=VtqiOEUlskAr9nRsaS9uXQSSjDD8dIrYfNML0zLY2zo,17764
 claude_mpm/services/core/service_container.py,sha256=3hDwFUahxFZnokPzwgXqBP9swvZhLztKQqwe9xEHgsw,18497
 claude_mpm/services/core/service_interfaces.py,sha256=dlNp0K4gaMcLiNSZxXjsL-kto6vipYw87pBuFK7oVNo,10770
@@ -786,9 +789,9 @@ claude_mpm/utils/subprocess_utils.py,sha256=D0izRT8anjiUb_JG72zlJR_JAw1cDkb7kalN
 claude_mpm/validation/__init__.py,sha256=YZhwE3mhit-lslvRLuwfX82xJ_k4haZeKmh4IWaVwtk,156
 claude_mpm/validation/agent_validator.py,sha256=GprtAvu80VyMXcKGsK_VhYiXWA6BjKHv7O6HKx0AB9w,20917
 claude_mpm/validation/frontmatter_validator.py,sha256=YpJlYNNYcV8u6hIOi3_jaRsDnzhbcQpjCBE6eyBKaFY,7076
-claude_mpm-4.7.9.dist-info/licenses/LICENSE,sha256=lpaivOlPuBZW1ds05uQLJJswy8Rp_HMNieJEbFlqvLk,1072
-claude_mpm-4.7.9.dist-info/METADATA,sha256=CKRPRgDYQjMEhisRDRh4swunx7DxHsVA022PufJ0t7Q,17517
-claude_mpm-4.7.9.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-claude_mpm-4.7.9.dist-info/entry_points.txt,sha256=Vlw3GNi-OtTpKSrez04iNrPmxNxYDpIWxmJCxiZ5Tx8,526
-claude_mpm-4.7.9.dist-info/top_level.txt,sha256=1nUg3FEaBySgm8t-s54jK5zoPnu3_eY6EP6IOlekyHA,11
-claude_mpm-4.7.9.dist-info/RECORD,,
+claude_mpm-4.8.0.dist-info/licenses/LICENSE,sha256=lpaivOlPuBZW1ds05uQLJJswy8Rp_HMNieJEbFlqvLk,1072
+claude_mpm-4.8.0.dist-info/METADATA,sha256=zDfqp-t5ALEzKUJM2qeRo9nrEmPE76-Iw7468Id_vgU,17517
+claude_mpm-4.8.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+claude_mpm-4.8.0.dist-info/entry_points.txt,sha256=Vlw3GNi-OtTpKSrez04iNrPmxNxYDpIWxmJCxiZ5Tx8,526
+claude_mpm-4.8.0.dist-info/top_level.txt,sha256=1nUg3FEaBySgm8t-s54jK5zoPnu3_eY6EP6IOlekyHA,11
+claude_mpm-4.8.0.dist-info/RECORD,,