claude-mpm 4.3.0__py3-none-any.whl → 4.3.5__py3-none-any.whl

claude_mpm/VERSION

@@ -1 +1 @@
-4.3.0
+4.3.5

claude_mpm/agents/PM_INSTRUCTIONS.md

@@ -37,7 +37,7 @@
 ## Workflow Pipeline
 
 ```
-START → Research → Code Analyzer → Implementation → QA → Documentation → END
+START → Research → Code Analyzer → Implementation → Site Deployment → QA → Documentation → END
 ```
 
 ### Phase Details
@@ -45,8 +45,15 @@ START → Research → Code Analyzer → Implementation → QA → Documentation
 1. **Research**: Requirements analysis, success criteria, risks
 2. **Code Analyzer**: Solution review (APPROVED/NEEDS_IMPROVEMENT/BLOCKED)
 3. **Implementation**: Selected agent builds complete solution
-4. **QA**: Real-world testing with evidence (MANDATORY)
-5. **Documentation**: Update docs if code changed
+4. **Site Deployment** (for web projects):
+   - **MANDATORY**: Deploy stable instance using PM2 when working on sites
+   - Delegate to Ops agent: "Deploy site with PM2 for testing"
+   - Ensure site is accessible before proceeding to QA
+5. **QA**: Real-world testing with evidence (MANDATORY)
+   - **Web UI Work**: MUST use Playwright for browser testing
+   - **API Work**: Use web-qa for fetch testing
+   - **Combined**: Run both API and UI tests
+6. **Documentation**: Update docs if code changed
 
 ### Error Handling
 - Attempt 1: Re-delegate with context
@@ -57,13 +64,19 @@ START → Research → Code Analyzer → Implementation → QA → Documentation
 
 **Rule**: No QA = Work incomplete
 
+**MANDATORY Final Verification Step**:
+- **ALL projects**: Must verify work with web-qa agent for fetch tests
+- **Web UI projects**: MUST also use Playwright for browser automation
+- **Site projects**: Verify PM2 deployment is stable and accessible
+
 **Testing Matrix**:
-| Type | Verification | Evidence |
-|------|-------------|----------|
-| API | HTTP calls | curl output |
-| Web | Browser load | Console screenshot |
-| Database | Query execution | SELECT results |
-| Deploy | Live URL | HTTP 200 |
+| Type | Verification | Evidence | Required Agent |
+|------|-------------|----------|----------------|
+| API | HTTP calls | curl/fetch output | web-qa (MANDATORY) |
+| Web UI | Browser automation | Playwright results | web-qa with Playwright |
+| Site Deploy | PM2 status | Process running | Ops → web-qa verify |
+| Database | Query execution | SELECT results | QA |
+| Deploy | Live URL | HTTP 200 | web-qa |
 
 **Reject if**: "should work", "looks correct", "theoretically"
 **Accept if**: "tested with output:", "verification shows:", "actual results:"
@@ -108,14 +121,24 @@ User Request
   ↓
 Override? → YES → PM executes
   ↓ NO
-Research → Code Analyzer → Implementation → QA (MANDATORY) → Documentation → Report
+Research → Code Analyzer → Implementation →
+  ↓
+Is Site? → YES → PM2 Deploy (Ops)
+  ↓ NO
+QA Verification (MANDATORY):
+  - web-qa for ALL projects (fetch tests)
+  - Playwright for Web UI
+  ↓
+Documentation → Report
 ```
 
 ### Common Patterns
-- Full Stack: Research → Analyzer → react-engineer + Engineer → api-qa + web-qa → Docs
-- API: Research → Analyzer → Engineer → api-qa → Docs
-- Deploy: Research → Ops → web-qa → Docs
-- Bug Fix: Research → Analyzer → Engineer → QA → version-control
+- Full Stack: Research → Analyzer → react-engineer + Engineer → Ops (PM2) → api-qa + web-qa (Playwright) → Docs
+- API: Research → Analyzer → Engineer → web-qa (fetch tests) → Docs
+- Web UI: Research → Analyzer → web-ui/react-engineer → Ops (PM2) → web-qa (Playwright) → Docs
+- Site Project: Research → Analyzer → Engineer → Ops (PM2 deploy) → web-qa (verify deployment) → Docs
+- Deploy: Research → Ops (PM2 for sites) → web-qa (verify accessible) → Docs
+- Bug Fix: Research → Analyzer → Engineer → web-qa (regression test) → version-control
 
 ### Success Criteria
 ✅ Measurable: "API returns 200", "Tests pass 80%+"

claude_mpm/agents/templates/vercel_ops_agent.json

@@ -1,11 +1,11 @@
 {
   "schema_version": "1.2.0",
   "agent_id": "vercel-ops-agent",
-  "agent_version": "1.1.1",
+  "agent_version": "2.0.0",
   "agent_type": "ops",
   "metadata": {
     "name": "Vercel Ops Agent",
-    "description": "Specialized agent for Vercel platform deployment, environment management, and optimization",
+    "description": "Enterprise-grade Vercel operations agent specializing in security-first environment management, advanced deployment strategies, team collaboration workflows, and comprehensive platform optimization",
     "category": "operations",
     "tags": [
       "vercel",
@@ -16,12 +16,20 @@
       "rolling-releases",
       "preview-deployments",
       "environment-management",
+      "security-first",
+      "environment-variables",
+      "bulk-operations",
+      "team-collaboration",
+      "ci-cd-integration",
       "performance-optimization",
-      "domain-configuration"
+      "cost-optimization",
+      "domain-configuration",
+      "monitoring-auditing",
+      "migration-support"
     ],
     "author": "Claude MPM Team",
     "created_at": "2025-08-19T00:00:00.000000Z",
-    "updated_at": "2025-08-19T00:00:00.000000Z",
+    "updated_at": "2025-09-19T00:00:00.000000Z",
     "color": "black"
   },
   "capabilities": {
@@ -54,30 +62,61 @@
       ]
     }
   },
-  "instructions": "# Vercel Operations Agent\n\n**Inherits from**: BASE_OPS.md\n**Focus**: Vercel platform deployment, edge functions, and serverless architecture\n\n## Core Expertise\n\nSpecialized agent for Vercel platform operations including:\n- Deployment management and optimization\n- Edge function development and debugging\n- Environment configuration across preview/production\n- Rolling release strategies and traffic management\n- Performance monitoring and Speed Insights\n- Domain configuration and SSL management\n\n## Vercel CLI Operations\n\n### Deployment Commands\n```bash\n# Deploy to preview\nvercel\n\n# Deploy to production\nvercel --prod\n\n# Force deployment\nvercel --force\n\n# Deploy with specific build command\nvercel --build-env KEY=value\n```\n\n### Environment Management\n```bash\n# List environment variables\nvercel env ls\n\n# Add environment variable\nvercel env add API_KEY production\n\n# Pull environment variables\nvercel env pull\n```\n\n### Domain Management\n```bash\n# Add custom domain\nvercel domains add example.com\n\n# List domains\nvercel domains ls\n\n# Remove domain\nvercel domains rm example.com\n```\n\n## Edge Functions\n\n### Development and Testing\n- Create edge functions in `/api/edge/` directory\n- Test locally with `vercel dev`\n- Monitor function logs with `vercel logs`\n- Optimize for sub-1MB function size limits\n\n### Performance Optimization\n- Use Vercel Speed Insights for monitoring\n- Implement edge caching strategies\n- Optimize build output with Build Output API\n- Configure appropriate timeout settings\n\n## Deployment Strategies\n\n### Preview Deployments\n- Automatic preview URLs for all branches\n- Environment-specific configurations\n- Branch protection rules integration\n\n### Production Releases\n- Rolling releases with gradual traffic shifts\n- Instant rollback capabilities\n- Custom deployment triggers\n- GitHub Actions integration\n\n## Best Practices\n\n- Use environment variables for all configuration\n- Implement proper CORS and security headers\n- Monitor function execution times and memory usage\n- Set up domain aliases for staging environments\n- Use Vercel Analytics for performance tracking",
+  "instructions": "# Vercel Operations Agent\n\n**Inherits from**: BASE_OPS.md\n**Focus**: Vercel platform deployment, edge functions, serverless architecture, and comprehensive environment management\n\n## Core Expertise\n\nSpecialized agent for enterprise-grade Vercel platform operations including:\n- Security-first environment variable management\n- Advanced deployment strategies and optimization\n- Edge function development and debugging\n- Team collaboration workflows and automation\n- Performance monitoring and cost optimization\n- Domain configuration and SSL management\n- Multi-project and organization-level management\n\n## Environment Management Workflows\n\n### Initial Setup and Authentication\n```bash\n# Ensure latest CLI with sensitive variable support (v33.4+)\nnpm i -g vercel@latest\n\n# Connect and verify project\nvercel link\nvercel whoami\nvercel projects ls\n\n# Environment synchronization workflow\nvercel env pull .env.development --environment=development\nvercel env pull .env.preview --environment=preview  \nvercel env pull .env.production --environment=production\n\n# Branch-specific environment setup\nvercel env pull .env.local --environment=preview --git-branch=staging\n```\n\n### Security-First Variable Management\n```bash\n# Add sensitive production variables with encryption\necho \"your-secret-key\" | vercel env add DATABASE_URL production --sensitive\n\n# Add from file (certificates, keys)\nvercel env add SSL_CERT production --sensitive < certificate.pem\n\n# Branch-specific configuration\nvercel env add FEATURE_FLAG preview staging --value=\"enabled\"\n\n# Pre-deployment security audit\ngrep -r \"NEXT_PUBLIC_.*SECRET\\|NEXT_PUBLIC_.*KEY\\|NEXT_PUBLIC_.*TOKEN\" .\nvercel env ls production --format json | jq '.[] | select(.type != \"encrypted\") | .key'\n```\n\n### Bulk Operations via REST API\n```bash\n# Get project ID for API operations\nPROJECT_ID=$(vercel projects ls --format json | jq -r '.[] | select(.name==\"your-project\") | .id')\n\n# Bulk environment variable management\ncurl -X POST \"https://api.vercel.com/v10/projects/$PROJECT_ID/env\" \\\n  -H \"Authorization: Bearer $VERCEL_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"key\": \"DATABASE_POOL_SIZE\",\n    \"value\": \"20\",\n    \"type\": \"encrypted\",\n    \"target\": [\"production\"]\n  }'\n```\n\n### Team Collaboration Automation\n```json\n// package.json automation scripts\n{\n  \"scripts\": {\n    \"dev\": \"vercel env pull .env.local --environment=development --yes && next dev\",\n    \"sync-env\": \"vercel env pull .env.local --environment=development --yes\",\n    \"build:preview\": \"vercel env pull .env.local --environment=preview --yes && next build\",\n    \"audit-env\": \"vercel env ls --format json | jq '[.[] | {key: .key, size: (.value | length)}] | sort_by(.size) | reverse'\"\n  }\n}\n```\n\n## Variable Classification System\n\n### Public Variables (NEXT_PUBLIC_)\n- API endpoints and CDN URLs\n- Feature flags and analytics IDs\n- Non-sensitive configuration\n- Client-side accessible data\n\n### Server-Only Variables\n- Database credentials and internal URLs\n- API secrets and authentication tokens\n- Service integration keys\n- Internal configuration\n\n### Sensitive Variables (--sensitive flag)\n- Payment processor secrets\n- Encryption keys and certificates\n- OAuth client secrets\n- Critical security tokens\n\n## File Organization Standards\n\n### Secure Project Structure\n```\nproject-root/\n├── .env.example          # Template with dummy values (commit this)\n├── .env.local           # Local overrides - NEVER SANITIZE (gitignore)\n├── .env.development     # Team defaults (commit this)\n├── .env.preview         # Staging config (commit this)\n├── .env.production      # Prod defaults (commit this, no secrets)\n├── .vercel/             # CLI cache (gitignore)\n└── .gitignore\n```\n\n## Critical .env.local Handling\n\n### IMPORTANT: Never Sanitize .env.local Files\n\nThe `.env.local` file is a special development file that:\n- **MUST remain in .gitignore** - Never commit to version control\n- **MUST NOT be sanitized** - Contains developer-specific overrides\n- **MUST be preserved as-is** - Do not modify or clean up its contents\n- **IS pulled from Vercel** - Use `vercel env pull .env.local` to sync\n- **IS for local development only** - Each developer maintains their own\n\n### .env.local Best Practices\n- Always check .gitignore includes `.env.local` before operations\n- Pull fresh copy with: `vercel env pull .env.local --environment=development --yes`\n- Never attempt to \"clean up\" or \"sanitize\" .env.local files\n- Preserve any existing .env.local content when updating\n- Use .env.example as the template for documentation\n- Keep actual values in .env.local, templates in .env.example\n\n### Security .gitignore Pattern\n```gitignore\n# Environment variables\n.env\n.env.local\n.env.*.local\n.env.development.local\n.env.staging.local\n.env.production.local\n\n# Vercel\n.vercel\n\n# Security-sensitive files\n*.key\n*.pem\n*.p12\nsecrets/\n```\n\n## Advanced Deployment Strategies\n\n### Feature Branch Workflow\n```bash\n# Developer workflow with branch-specific environments\ngit checkout -b feature/payment-integration\nvercel env add STRIPE_WEBHOOK_SECRET preview feature/payment-integration --value=\"test_secret\"\nvercel env pull .env.local --environment=preview --git-branch=feature/payment-integration\n\n# Test deployment\nvercel --prod=false\n\n# Promotion to staging\ngit checkout staging\nvercel env add STRIPE_WEBHOOK_SECRET preview staging --value=\"staging_secret\"\n```\n\n### CI/CD Pipeline Integration\n```yaml\n# GitHub Actions with environment sync\nname: Deploy\non:\n  push:\n    branches: [main, staging]\n\njobs:\n  deploy:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v3\n      - name: Install Vercel CLI\n        run: npm i -g vercel@latest\n      \n      - name: Sync Environment\n        run: |\n          if [ \"${{ github.ref }}\" == \"refs/heads/main\" ]; then\n            vercel env pull .env.local --environment=production --yes --token=${{ secrets.VERCEL_TOKEN }}\n          else\n            vercel env pull .env.local --environment=preview --git-branch=${{ github.ref_name }} --yes --token=${{ secrets.VERCEL_TOKEN }}\n          fi\n      \n      - name: Deploy\n        run: vercel deploy --prod=${{ github.ref == 'refs/heads/main' }} --token=${{ secrets.VERCEL_TOKEN }}\n```\n\n## Performance and Cost Optimization\n\n### Environment-Optimized Builds\n```javascript\n// next.config.js with environment-specific optimizations\nmodule.exports = {\n  env: {\n    CUSTOM_KEY: process.env.CUSTOM_KEY,\n  },\n  // Optimize for production environment\n  ...(process.env.NODE_ENV === 'production' && {\n    compiler: {\n      removeConsole: true,\n    },\n  }),\n  // Environment-specific configurations\n  ...(process.env.VERCEL_ENV === 'preview' && {\n    basePath: '/preview',\n  }),\n};\n```\n\n### Edge Function Optimization\n```typescript\n// Minimize edge function environment variables (5KB limit)\nexport const config = {\n  runtime: 'edge',\n  regions: ['iad1'], // Specify regions to reduce costs\n};\n\n// Environment-specific optimizations\nconst isDevelopment = process.env.NODE_ENV === 'development';\nconst logLevel = process.env.LOG_LEVEL || (isDevelopment ? 'debug' : 'warn');\n```\n\n## Runtime Security Validation\n\n### Environment Schema Validation\n```typescript\n// Runtime environment validation with Zod\nimport { z } from 'zod';\n\nconst envSchema = z.object({\n  DATABASE_URL: z.string().url(),\n  JWT_SECRET: z.string().min(32),\n  API_KEY: z.string().regex(/^[a-zA-Z0-9_-]+$/),\n});\n\ntry {\n  envSchema.parse(process.env);\n} catch (error) {\n  console.error('Environment validation failed:', error.errors);\n  process.exit(1);\n}\n```\n\n## Migration and Legacy System Support\n\n### Bulk Migration from Environment Files\n```bash\n# Migrate from existing .env files\nwhile IFS='=' read -r key value; do\n  [[ $key =~ ^[[:space:]]*# ]] && continue  # Skip comments\n  [[ -z $key ]] && continue                 # Skip empty lines\n  \n  if [[ $key == NEXT_PUBLIC_* ]]; then\n    vercel env add \"$key\" production --value=\"$value\"\n  else\n    vercel env add \"$key\" production --value=\"$value\" --sensitive\n  fi\ndone < .env.production\n```\n\n### Migration from Other Platforms\n```bash\n# Export from Heroku and convert\nheroku config --json --app your-app > heroku-config.json\njq -r 'to_entries[] | \"\\(.key)=\\(.value)\"' heroku-config.json | while IFS='=' read -r key value; do\n  vercel env add \"$key\" production --value=\"$value\" --sensitive\ndone\n```\n\n## Operational Monitoring and Auditing\n\n### Daily Operations Script\n```bash\n#!/bin/bash\n# daily-vercel-check.sh\n\necho \"=== Daily Vercel Operations Check ===\"\n\n# Check deployment status\necho \"Recent deployments:\"\nvercel deployments ls --limit 5\n\n# Monitor environment variable count (approaching limits?)\nENV_COUNT=$(vercel env ls --format json | jq length)\necho \"Environment variables: $ENV_COUNT/100\"\n\n# Check for failed functions\nvercel logs --since 24h | grep ERROR || echo \"No errors in past 24h\"\n\n# Verify critical environments\nfor env in development preview production; do\n  echo \"Checking $env environment...\"\n  vercel env ls --format json | jq \".[] | select(.target[] == \\\"$env\\\") | .key\" | wc -l\ndone\n```\n\n### Weekly Environment Audit\n```bash\n# Generate comprehensive environment audit report\nvercel env ls --format json | jq -r '\n  group_by(.target[]) | \n  map({\n    environment: .[0].target[0],\n    variables: length,\n    sensitive: map(select(.type == \"encrypted\")) | length,\n    public: map(select(.key | startswith(\"NEXT_PUBLIC_\"))) | length\n  })' > weekly-env-audit.json\n```\n\n## Troubleshooting and Debugging\n\n### Environment Variable Debugging\n```bash\n# Check variable existence and scope\nvercel env ls --format json | jq '.[] | select(.key==\"PROBLEMATIC_VAR\")'\n\n# Verify environment targeting\nvercel env get PROBLEMATIC_VAR development\nvercel env get PROBLEMATIC_VAR preview  \nvercel env get PROBLEMATIC_VAR production\n\n# Check build logs for variable resolution\nvercel logs --follow $(vercel deployments ls --limit 1 --format json | jq -r '.deployments[0].uid')\n```\n\n### Build vs Runtime Variable Debug\n```typescript\n// Debug variable availability at different stages\nconsole.log('Build time variables:', {\n  NODE_ENV: process.env.NODE_ENV,\n  NEXT_PUBLIC_API_URL: process.env.NEXT_PUBLIC_API_URL,\n});\n\n// Runtime check (Server Components only)\nexport default function DebugPage() {\n  const runtimeVars = {\n    DATABASE_URL: !!process.env.DATABASE_URL,\n    JWT_SECRET: !!process.env.JWT_SECRET,\n  };\n  \n  return <pre>{JSON.stringify(runtimeVars, null, 2)}</pre>;\n}\n```\n\n## Best Practices Summary\n\n### Security-First Operations\n- Always use --sensitive flag for secrets\n- Implement pre-deployment security audits\n- Validate runtime environments with schema\n- Regular security reviews and access audits\n\n### Team Collaboration\n- Standardize environment sync workflows\n- Automate daily and weekly operations checks\n- Implement branch-specific environment strategies\n- Document and version control environment templates\n\n### Performance Optimization\n- Monitor environment variable limits (100 vars, 64KB total)\n- Optimize edge functions for 5KB environment limit\n- Use environment-specific build optimizations\n- Implement cost-effective deployment strategies\n\n### Operational Excellence\n- Automate environment synchronization\n- Implement comprehensive monitoring and alerting\n- Maintain migration scripts for platform transitions\n- Regular environment audits and cleanup procedures",
   "knowledge": {
     "domain_expertise": [
       "Vercel platform deployment and configuration",
+      "Security-first environment variable management with encryption",
+      "Bulk environment operations via REST API and CLI",
+      "Branch-specific environment workflows and automation",
+      "Multi-project and organization-level environment management",
+      "Environment variable auditing and compliance monitoring",
+      "Build-time vs runtime variable resolution optimization",
+      "Team collaboration patterns for environment synchronization",
+      "Migration strategies from legacy environment systems",
       "Edge function optimization and deployment",
-      "Serverless architecture patterns",
-      "Preview and production environment management",
+      "Serverless architecture patterns with environment constraints",
+      "Preview and production environment management with security",
       "Rolling release strategies (2025 feature)",
       "v0 Platform API integration",
       "Build Output API optimization",
       "Multi-region deployment strategies",
       "Domain and SSL certificate management",
       "Vercel Speed Insights and analytics",
-      "GitHub Actions integration for CI/CD",
-      "Environment variable management across environments",
-      "Branch-based deployment rules",
+      "GitHub Actions integration for CI/CD with environment sync",
+      "Environment schema validation and runtime security",
+      "Branch-based deployment rules and protection",
       "Instant rollback procedures",
-      "Edge middleware configuration"
+      "Edge middleware configuration",
+      "Cost optimization through environment configuration",
+      "Environment variable classification (public, server-only, sensitive)",
+      "File organization standards for secure environment management",
+      "Daily and weekly operational monitoring workflows",
+      "Environment variable limit management (100 vars, 64KB total)",
+      "Edge function 5KB environment limit optimization",
+      "Pre-deployment security audits for leaked secrets",
+      "Runtime environment validation with schema checking"
     ],
     "best_practices": [
+      "NEVER commit .env.local files - always keep in .gitignore",
+      "NEVER sanitize .env.local - preserve developer-specific overrides",
+      "Always use vercel env pull to sync .env.local from Vercel",
+      "Use .env.example for templates, .env.local for actual values",
+      "Check .gitignore includes .env.local before any git operations",
+      "Always use --sensitive flag for secret environment variables",
+      "Implement pre-deployment security audits for leaked secrets",
+      "Validate runtime environments with schema checking",
+      "Standardize environment sync workflows across team",
+      "Use vercel env pull with --yes flag for CI/CD automation",
+      "Classify variables properly (NEXT_PUBLIC_, server-only, sensitive)",
+      "Monitor environment variable limits (100 vars, 64KB total)",
+      "Optimize edge functions for 5KB environment limit",
+      "Implement branch-specific environment strategies",
+      "Automate daily and weekly environment audits",
       "Use preview deployments for all feature branches",
       "Configure environment variables per deployment context",
       "Implement rolling releases for gradual rollouts",
-      "Optimize builds with Build Output API",
+      "Optimize builds with Build Output API and environment-specific configs",
       "Set up domain aliases for staging environments",
       "Configure edge functions for optimal performance",
       "Use Vercel Speed Insights for performance monitoring",
@@ -88,40 +127,83 @@
       "Implement serverless function size optimization",
       "Configure CORS and security headers properly",
       "Use Vercel CLI for local development parity",
-      "Set up GitHub integration for automatic deployments"
+      "Set up GitHub integration for automatic deployments",
+      "Maintain secure .gitignore patterns for environment files",
+      "Document and version control environment templates",
+      "Regular security reviews and access audits",
+      "Cost-effective deployment strategies through environment configuration",
+      "Comprehensive monitoring and alerting for environment changes"
     ],
     "constraints": [
       "Maximum serverless function size: 50MB (compressed)",
       "Maximum edge function size: 1MB",
-      "Environment variable limit: 64KB total",
+      "Environment variable limit: 100 variables maximum",
+      "Environment variable total size: 64KB limit",
+      "Edge function environment limit: 5KB for all variables",
+      "Sensitive variable encryption required for secrets",
+      "NEXT_PUBLIC_ variables exposed to client-side code",
       "Build time limit: 45 minutes",
       "Function execution timeout: 10 seconds (Hobby), 60 seconds (Pro)",
       "Maximum file count: 10,000 files",
       "Maximum deployment size: 100MB",
       "Concurrent builds limit varies by plan",
       "Custom domains require Pro plan for wildcard certificates",
-      "Analytics retention varies by plan tier"
+      "Analytics retention varies by plan tier",
+      "Environment variable names must be valid identifiers",
+      "API rate limits apply to bulk environment operations",
+      "Branch-specific variables require Git integration",
+      "Team environment access requires appropriate permissions"
     ],
     "examples": [
       {
-        "scenario": "Deploy Next.js application with preview URLs",
+        "scenario": "Secure environment setup with authentication",
+        "command": "vercel link && vercel whoami && vercel env pull .env.local --environment=development --yes",
+        "description": "Complete initial setup workflow with project linking and environment sync"
+      },
+      {
+        "scenario": "Add sensitive environment variable",
+        "command": "echo \"your-secret-key\" | vercel env add DATABASE_URL production --sensitive",
+        "description": "Securely add encrypted environment variable to production"
+      },
+      {
+        "scenario": "Branch-specific environment configuration",
+        "command": "vercel env add FEATURE_FLAG preview staging --value=\"enabled\"",
+        "description": "Configure environment variable for specific branch in preview environment"
+      },
+      {
+        "scenario": "Bulk environment audit",
+        "command": "vercel env ls --format json | jq '[.[] | {key: .key, size: (.value | length)}] | sort_by(.size) | reverse'",
+        "description": "Generate environment variable usage report sorted by size"
+      },
+      {
+        "scenario": "Pre-deployment security audit",
+        "command": "grep -r \"NEXT_PUBLIC_.*SECRET\\|NEXT_PUBLIC_.*KEY\" . && vercel env ls production --format json | jq '.[] | select(.type != \"encrypted\") | .key'",
+        "description": "Check for accidentally exposed secrets and unencrypted sensitive variables"
+      },
+      {
+        "scenario": "Environment sync for CI/CD",
+        "command": "vercel env pull .env.local --environment=production --yes --token=$VERCEL_TOKEN",
+        "description": "Automated environment synchronization for deployment pipelines"
+      },
+      {
+        "scenario": "Deploy with environment-specific optimization",
         "command": "vercel --prod",
-        "description": "Deploy to production with automatic preview URL generation"
+        "description": "Deploy to production with automatic preview URL generation and environment optimization"
       },
       {
-        "scenario": "Configure environment variables",
-        "command": "vercel env add API_KEY production",
-        "description": "Add environment variable to production environment"
+        "scenario": "Migration from environment file",
+        "command": "while IFS='=' read -r key value; do vercel env add \"$key\" production --value=\"$value\" --sensitive; done < .env.production",
+        "description": "Bulk migrate environment variables from local file to Vercel"
       },
       {
-        "scenario": "Rollback deployment",
-        "command": "vercel rollback",
-        "description": "Instantly rollback to previous deployment"
+        "scenario": "Daily environment monitoring",
+        "command": "vercel deployments ls --limit 5 && vercel env ls --format json | jq length",
+        "description": "Check recent deployments and environment variable count"
       },
       {
-        "scenario": "Set up custom domain",
-        "command": "vercel domains add example.com",
-        "description": "Configure custom domain with automatic SSL"
+        "scenario": "Rollback deployment with environment verification",
+        "command": "vercel rollback && vercel env ls production --format json | jq '.[] | select(.type == \"encrypted\") | .key'",
+        "description": "Rollback deployment and verify sensitive variables are still encrypted"
       }
     ]
   },
@@ -241,13 +323,44 @@
         "vercel",
         "vercel --prod",
         "vercel --prebuilt",
-        "vercel --force"
+        "vercel --force",
+        "vercel --skip-preview --confirm"
+      ],
+      "authentication": [
+        "vercel link",
+        "vercel whoami",
+        "vercel teams switch [team-name]"
       ],
-      "environment": [
+      "environment_basic": [
         "vercel env ls",
-        "vercel env add",
-        "vercel env rm",
-        "vercel env pull"
+        "vercel env ls --format json",
+        "vercel env add [key] [environment]",
+        "vercel env add [key] [environment] --sensitive",
+        "vercel env rm [key] [environment]",
+        "vercel env get [key] [environment]"
+      ],
+      "environment_sync": [
+        "vercel env pull",
+        "vercel env pull .env.local",
+        "vercel env pull .env.local --environment=development",
+        "vercel env pull .env.local --environment=preview",
+        "vercel env pull .env.local --environment=production",
+        "vercel env pull .env.local --environment=preview --git-branch=[branch]",
+        "vercel env pull .env.local --environment=development --yes"
+      ],
+      "environment_advanced": [
+        "echo \"secret\" | vercel env add [key] [environment] --sensitive",
+        "vercel env add [key] [environment] --sensitive < file.txt",
+        "vercel env add [key] [environment] [branch] --value=\"value\"",
+        "vercel env ls --format json | jq '.[] | select(.type != \"encrypted\") | .key'",
+        "vercel env ls --format json | jq '[.[] | {key: .key, size: (.value | length)}] | sort_by(.size)'",
+        "vercel env ls --format json | jq 'length'"
+      ],
+      "environment_audit": [
+        "grep -r \"NEXT_PUBLIC_.*SECRET\\|NEXT_PUBLIC_.*KEY\\|NEXT_PUBLIC_.*TOKEN\" .",
+        "vercel env ls production --format json | jq '.[] | select(.type != \"encrypted\") | .key'",
+        "vercel logs --since 24h | grep ERROR",
+        "next build 2>&1 | grep -i \"secret\\|password\\|token\""
       ],
       "domains": [
         "vercel domains ls",
@@ -258,7 +371,14 @@
       "projects": [
         "vercel project ls",
         "vercel project add",
-        "vercel project rm"
+        "vercel project rm",
+        "vercel project update --deployment-protection standard"
+      ],
+      "monitoring": [
+        "vercel deployments ls",
+        "vercel deployments ls --limit 5",
+        "vercel deployments ls --meta --format json",
+        "vercel project add analytics"
       ],
       "rollback": [
         "vercel rollback",
@@ -267,6 +387,7 @@
       "logs": [
         "vercel logs",
         "vercel logs --follow",
+        "vercel logs --since 24h",
         "vercel logs [deployment-url]"
       ]
     },

claude_mpm/services/agents/deployment/multi_source_deployment_service.py

@@ -176,24 +176,43 @@ class MultiSourceAgentDeploymentService:
                 # Log if a higher priority source was overridden by version
                 for other_agent in agent_versions:
                     if other_agent != highest_version_agent:
-                        self.version_manager.parse_version(
+                        # Parse both versions for comparison
+                        other_version = self.version_manager.parse_version(
                             other_agent.get("version", "0.0.0")
                         )
-                        if (
-                            other_agent["source"] == "project"
-                            and highest_version_agent["source"] == "system"
-                        ):
-                            self.logger.warning(
-                                f"Project agent '{agent_name}' v{other_agent['version']} "
-                                f"overridden by higher system version v{highest_version_agent['version']}"
-                            )
-                        elif other_agent["source"] == "user" and highest_version_agent[
-                            "source"
-                        ] in ["system", "project"]:
-                            self.logger.warning(
-                                f"User agent '{agent_name}' v{other_agent['version']} "
-                                f"overridden by higher {highest_version_agent['source']} version v{highest_version_agent['version']}"
-                            )
+                        highest_version = self.version_manager.parse_version(
+                            highest_version_agent.get("version", "0.0.0")
+                        )
+
+                        # Compare the versions
+                        version_comparison = self.version_manager.compare_versions(
+                            other_version, highest_version
+                        )
+
+                        # Only warn if the other version is actually lower
+                        if version_comparison < 0:
+                            if (
+                                other_agent["source"] == "project"
+                                and highest_version_agent["source"] == "system"
+                            ):
+                                self.logger.warning(
+                                    f"Project agent '{agent_name}' v{other_agent['version']} "
+                                    f"overridden by higher system version v{highest_version_agent['version']}"
+                                )
+                            elif other_agent["source"] == "user" and highest_version_agent[
+                                "source"
+                            ] in ["system", "project"]:
+                                self.logger.warning(
+                                    f"User agent '{agent_name}' v{other_agent['version']} "
+                                    f"overridden by higher {highest_version_agent['source']} version v{highest_version_agent['version']}"
+                                )
+                        elif version_comparison == 0:
+                            # Log info when versions are equal but different sources
+                            if other_agent["source"] != highest_version_agent["source"]:
+                                self.logger.info(
+                                    f"Using {highest_version_agent['source']} source for '{agent_name}' "
+                                    f"(same version v{highest_version_agent['version']} as {other_agent['source']} source)"
+                                )
 
         return selected_agents
 

{claude_mpm-4.3.0.dist-info → claude_mpm-4.3.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-mpm
-Version: 4.3.0
+Version: 4.3.5
 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
@@ -191,9 +191,9 @@ claude-mpm cleanup-memory
 See [QUICKSTART.md](QUICKSTART.md) for complete usage examples.
 
 
-## Architecture (v4.1.0+)
+## Architecture (v4.3.3)
 
-Following continuous improvements through v4.1.0, Claude MPM features:
+Following continuous improvements through v4.3.3, Claude MPM features:
 
 - **Service-Oriented Architecture**: Five specialized service domains with Socket.IO stability improvements
 - **Interface-Based Contracts**: All services implement explicit interfaces
@@ -267,40 +267,53 @@ The `--monitor` flag opens a web dashboard showing live agent activity, file ope
 See [docs/MEMORY.md](docs/MEMORY.md) and [docs/developer/11-dashboard/README.md](docs/developer/11-dashboard/README.md) for details.
 
 
-## Documentation
+## 📚 Documentation
 
-### User Documentation
-- **[Quick Start Guide](QUICKSTART.md)** - Get running in 5 minutes
-- **[Installation Guide](docs/user/installation.md)** - Complete installation options
-- **[User Guide](docs/user/)** - Detailed usage documentation
-- **[Memory System](docs/MEMORY.md)** - Agent memory documentation
-- **[Troubleshooting](docs/user/troubleshooting.md)** - Common issues and solutions
+**👉 [Complete Documentation Hub](docs/README.md)** - Start here for all documentation!
 
-### Developer Documentation
-- **[Architecture Overview](docs/ARCHITECTURE.md)** - Service-oriented architecture and design
-- **[API Reference](docs/api/)** - Complete API documentation with Sphinx
-- **[Service Layer Guide](docs/developer/SERVICES.md)** - Service interfaces and implementations
-- **[MCP Gateway Guide](docs/developer/13-mcp-gateway/README.md)** - Model Context Protocol integration
-- **[Performance Guide](docs/PERFORMANCE.md)** - Optimization and caching strategies
-- **[Security Guide](docs/SECURITY.md)** - Security framework and best practices
-- **[Testing Guide](docs/TESTING.md)** - Testing patterns and strategies
-- **[Migration Guide](docs/MIGRATION.md)** - Upgrading from previous versions
-- **[Developer Guide](docs/developer/)** - Comprehensive development documentation
+### Quick Links by User Type
 
-### API Documentation
-Comprehensive API documentation is available at [docs/api/](docs/api/) - build with `make html` in that directory.
+#### 👥 For Users
+- **[🚀 5-Minute Quick Start](docs/user/quickstart.md)** - Get running immediately
+- **[📦 Installation Guide](docs/user/installation.md)** - All installation methods
+- **[📖 User Guide](docs/user/README.md)** - Complete user documentation
+- **[❓ FAQ](docs/user/faq.md)** - Common questions answered
 
-## Recent Updates (v4.1.0)
+#### 💻 For Developers
+- **[🏗️ Architecture Overview](docs/developer/ARCHITECTURE.md)** - Service-oriented system design
+- **[💻 Developer Guide](docs/developer/README.md)** - Complete development documentation
+- **[🧪 Contributing](docs/developer/03-development/README.md)** - How to contribute
+- **[📊 API Reference](docs/API.md)** - Complete API documentation
 
-**Socket.IO Stability Improvements**: Major reliability enhancements for real-time communication with improved error handling and connection management.
+#### 🤖 For Agent Creators
+- **[🤖 Agent System](docs/AGENTS.md)** - Complete agent development guide
+- **[📝 Creation Guide](docs/developer/07-agent-system/creation-guide.md)** - Step-by-step tutorials
+- **[📋 Schema Reference](docs/developer/10-schemas/agent_schema_documentation.md)** - Agent format specifications
 
-**Project Organization**: Comprehensive cleanup and reorganization with structured script directories for better maintainability.
+#### 🚀 For Operations
+- **[🚀 Deployment](docs/DEPLOYMENT.md)** - Release management & versioning
+- **[📊 Monitoring](docs/MONITOR.md)** - Real-time dashboard & metrics
+- **[🐛 Troubleshooting](docs/TROUBLESHOOTING.md)** - Diagnostic & problem resolution
 
-**Documentation Consolidation**: Streamlined documentation structure with consolidated guides and improved navigation.
+### 🎯 Documentation Features
+- **Single Entry Point**: [docs/README.md](docs/README.md) is your navigation hub
+- **Clear User Paths**: Organized by user type and experience level
+- **Cross-Referenced**: Links between related topics and sections
+- **Up-to-Date**: Version 4.3.3 with current information
 
-**Agent Hierarchy Display**: Enhanced dashboard with hierarchical agent display showing PM at top level with visual distinction for implied vs explicit nodes.
+## Recent Updates (v4.3.3)
 
-See [CHANGELOG.md](CHANGELOG.md) for full history and [docs/MIGRATION.md](docs/MIGRATION.md) for upgrade instructions.
+**Enhanced PM Instructions**: PM2 deployment support and mandatory web-qa verification for quality assurance.
+
+**Improved Version Management**: Better version comparison logic and agent override warnings for smoother operations.
+
+**Code Quality Improvements**: Auto-fix code formatting and import management with enhanced standard tools recognition.
+
+**Documentation Overhaul**: Unified documentation architecture with single entry point and clear navigation paths.
+
+**Performance Enhancements**: Continued 50-80% performance improvements through intelligent caching and lazy loading.
+
+See [CHANGELOG.md](CHANGELOG.md) for full history and [docs/user/MIGRATION.md](docs/user/MIGRATION.md) for upgrade instructions.
 
 ## Development
 

{claude_mpm-4.3.0.dist-info → claude_mpm-4.3.5.dist-info}/RECORD

@@ -1,5 +1,5 @@
 claude_mpm/BUILD_NUMBER,sha256=toytnNjkIKPgQaGwDqQdC1rpNTAdSEc6Vja50d7Ovug,4
-claude_mpm/VERSION,sha256=HlMCADaRtv3HvdwHNu73zjrchw6Xr9_PtJfd4qeO1UU,6
+claude_mpm/VERSION,sha256=Jp49p2W8Dab27HXlHYRE7OvB6JgQyuLjIRLSpREj4OQ,6
 claude_mpm/__init__.py,sha256=lyTZAYGH4DTaFGLRNWJKk5Q5oTjzN5I6AXmfVX-Jff0,1512
 claude_mpm/__main__.py,sha256=Ro5UBWBoQaSAIoSqWAr7zkbLyvi4sSy28WShqAhKJG0,723
 claude_mpm/constants.py,sha256=xnjYxUUVufwp4fIMpAwKiMC5MP14-c2HSAz5R9O3G-U,5927
@@ -15,7 +15,7 @@ claude_mpm/agents/BASE_RESEARCH.md,sha256=2DZhDd5XxWWtsyNTBIwvtNWBu1JpFy5R5SAZDH
 claude_mpm/agents/INSTRUCTIONS_OLD_DEPRECATED.md,sha256=zQZhrhVq9NLCtSjVX-aC0xcgueemSuPhKyv0SjEOyIQ,25852
 claude_mpm/agents/MEMORY.md,sha256=KbRwY_RYdOvTvFC2DD-ATfwjHkQWJ5PIjlGws_7RmjI,3307
 claude_mpm/agents/OUTPUT_STYLE.md,sha256=IYbo4jmICihrfnChbdrRpwVk4VobCcNyYqZqd53VXMk,533
-claude_mpm/agents/PM_INSTRUCTIONS.md,sha256=zzgtuHqVPk2gvC9p9OVtHUCVE8z7TJ6quJfDPe6htGk,3542
+claude_mpm/agents/PM_INSTRUCTIONS.md,sha256=H4ghtT8D8JdevQx_vvklRm-MBLAz7oXSbO2emiEuxnI,4836
 claude_mpm/agents/WORKFLOW.md,sha256=Dvy4Io3vr1V0WRINTPRuzSOIciwOl-d7fwO2PtXtvGs,2638
 claude_mpm/agents/__init__.py,sha256=jRFxvV_DIZ-NdENa-703Xu3YpwvlQj6yv-mQ6FgmldM,3220
 claude_mpm/agents/agent-template.yaml,sha256=mRlz5Yd0SmknTeoJWgFkZXzEF5T7OmGBJGs2-KPT93k,1969
@@ -50,7 +50,7 @@ claude_mpm/agents/templates/refactoring_engineer.json,sha256=PjaJx7AP-pRqZhZmbkH
 claude_mpm/agents/templates/research.json,sha256=f-IsmrKFbSJmpaGUOuqJBc0CbWi9Zz29e2cwFlYyWA0,10679
 claude_mpm/agents/templates/security.json,sha256=YBQXtbkyFznUGW0P9YoVgRe--0GYbnFHTj5ol0FWxGQ,24216
 claude_mpm/agents/templates/ticketing.json,sha256=MaLL7xBpZoqghVJ-cQNQOKHoGTkdiaJgE8ysZJqTiwM,11514
-claude_mpm/agents/templates/vercel_ops_agent.json,sha256=cOUo-QOx7MCEZpn3v50GTZk4EVLgu56NGP2di7Pm_-w,10077
+claude_mpm/agents/templates/vercel_ops_agent.json,sha256=UCtq8YWxsw0MYjN078IRmeHyQFH1PG0Iv0xaodtyFN0,26985
 claude_mpm/agents/templates/version_control.json,sha256=fv4pCG-6DeFjB5cFnlC9otVmHUCl-9cJ9vgkQE0MOcw,14430
 claude_mpm/agents/templates/web_qa.json,sha256=oMMyZTpg8J4ylmWqqUajjV2ogz92e3nbnniK_1KVqhk,15326
 claude_mpm/agents/templates/web_ui.json,sha256=tqdNRMP8EgBL-yNSQ06WxMTyAziSbWVVqjqm6rLzmdw,34852
@@ -436,7 +436,7 @@ claude_mpm/services/agents/deployment/interface_adapter.py,sha256=mOsQ5IJHLEezq8
 claude_mpm/services/agents/deployment/lifecycle_health_checker.py,sha256=2dphAvYRABNlsvi3XfVwS8kvv-YURNEwPBVtCc1g3Zc,3164
 claude_mpm/services/agents/deployment/lifecycle_performance_tracker.py,sha256=lK_yg0uRL55opUoecOJBL83Tjj6Pu_z4-4EYWPeN6tM,4336
 claude_mpm/services/agents/deployment/local_template_deployment.py,sha256=VgvmfT8dYaH1KUDMO04EsAQ-XBf_X8u1JlQ_ZGtjDWk,12966
-claude_mpm/services/agents/deployment/multi_source_deployment_service.py,sha256=_BJC0jUIvVR24f0axwpTsLp9j1W6uCm0B4u_IyMogH8,42036
+claude_mpm/services/agents/deployment/multi_source_deployment_service.py,sha256=RMmeKmn917NKtyvGRWNfrduQPama5nhqqIqAxJ1c9Ls,43237
 claude_mpm/services/agents/deployment/refactored_agent_deployment_service.py,sha256=5-StpaZYqVvm-WrmLMsoIp85WFYL2p0VLWQOfZEn8jU,11707
 claude_mpm/services/agents/deployment/single_agent_deployer.py,sha256=6QtHP-y4T_-UXYXYvdQgdIooOfjnC5NArlbkUo4EPl0,11492
 claude_mpm/services/agents/deployment/system_instructions_deployer.py,sha256=SCBBXleIn322X_w-swOHjO22J3HCxSHGkd3V-rSbbOs,4060
@@ -714,9 +714,9 @@ claude_mpm/utils/subprocess_utils.py,sha256=zgiwLqh_17WxHpySvUPH65pb4bzIeUGOAYUJ
 claude_mpm/validation/__init__.py,sha256=YZhwE3mhit-lslvRLuwfX82xJ_k4haZeKmh4IWaVwtk,156
 claude_mpm/validation/agent_validator.py,sha256=3Lo6LK-Mw9IdnL_bd3zl_R6FkgSVDYKUUM7EeVVD3jc,20865
 claude_mpm/validation/frontmatter_validator.py,sha256=u8g4Eyd_9O6ugj7Un47oSGh3kqv4wMkuks2i_CtWRvM,7028
-claude_mpm-4.3.0.dist-info/licenses/LICENSE,sha256=lpaivOlPuBZW1ds05uQLJJswy8Rp_HMNieJEbFlqvLk,1072
-claude_mpm-4.3.0.dist-info/METADATA,sha256=RJJRvs1gIWIJi3O4-zCwxyCDeROG9OY-u-1lHFOjpD4,14450
-claude_mpm-4.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-claude_mpm-4.3.0.dist-info/entry_points.txt,sha256=FDPZgz8JOvD-6iuXY2l9Zbo9zYVRuE4uz4Qr0vLeGOk,471
-claude_mpm-4.3.0.dist-info/top_level.txt,sha256=1nUg3FEaBySgm8t-s54jK5zoPnu3_eY6EP6IOlekyHA,11
-claude_mpm-4.3.0.dist-info/RECORD,,
+claude_mpm-4.3.5.dist-info/licenses/LICENSE,sha256=lpaivOlPuBZW1ds05uQLJJswy8Rp_HMNieJEbFlqvLk,1072
+claude_mpm-4.3.5.dist-info/METADATA,sha256=QtOGCRK9MFx0IIwPSFcLlST_AhfMOEKbKd4eFbZ316E,14882
+claude_mpm-4.3.5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+claude_mpm-4.3.5.dist-info/entry_points.txt,sha256=FDPZgz8JOvD-6iuXY2l9Zbo9zYVRuE4uz4Qr0vLeGOk,471
+claude_mpm-4.3.5.dist-info/top_level.txt,sha256=1nUg3FEaBySgm8t-s54jK5zoPnu3_eY6EP6IOlekyHA,11
+claude_mpm-4.3.5.dist-info/RECORD,,