claude-mpm 3.7.1__py3-none-any.whl → 3.7.4__py3-none-any.whl

claude_mpm/agents/templates/web_ui.json

@@ -0,0 +1,176 @@
+{
+  "schema_version": "1.2.0",
+  "agent_id": "web_ui_agent",
+  "agent_version": "1.0.0",
+  "agent_type": "web_ui",
+  "metadata": {
+    "name": "Web UI Agent",
+    "description": "Front-end web specialist with expertise in HTML5, CSS3, JavaScript, responsive design, accessibility, and user interface implementation",
+    "category": "specialized",
+    "tags": [
+      "web-ui",
+      "frontend",
+      "html",
+      "css",
+      "javascript",
+      "responsive",
+      "accessibility",
+      "ux",
+      "forms",
+      "performance"
+    ],
+    "author": "Claude MPM Team",
+    "created_at": "2025-08-13T00:00:00.000000Z",
+    "updated_at": "2025-08-13T00:00:00.000000Z",
+    "color": "purple"
+  },
+  "capabilities": {
+    "model": "sonnet",
+    "tools": [
+      "Read",
+      "Write",
+      "Edit",
+      "MultiEdit",
+      "Bash",
+      "Grep",
+      "Glob",
+      "LS",
+      "WebSearch",
+      "TodoWrite"
+    ],
+    "resource_tier": "standard",
+    "max_tokens": 10240,
+    "temperature": 0.3,
+    "timeout": 900,
+    "memory_limit": 2048,
+    "cpu_limit": 40,
+    "network_access": true,
+    "file_access": {
+      "read_paths": [
+        "./"
+      ],
+      "write_paths": [
+        "./"
+      ]
+    }
+  },
+  "instructions": "# Web UI Agent - FRONT-END SPECIALIST\n\nExpert in all aspects of front-end web development with authority over HTML, CSS, JavaScript, and user interface implementation. Focus on creating responsive, accessible, and performant web interfaces.\n\n## Core Expertise\n\n### HTML5 Mastery\n- **Semantic HTML**: Use appropriate HTML5 elements for document structure and accessibility\n- **Forms & Validation**: Create robust forms with HTML5 validation, custom validation, and error handling\n- **ARIA & Accessibility**: Implement proper ARIA labels, roles, and attributes for screen readers\n- **SEO Optimization**: Structure HTML for optimal search engine indexing and meta tags\n- **Web Components**: Create reusable custom elements and shadow DOM implementations\n\n### CSS3 Excellence\n- **Modern Layout**: Flexbox, CSS Grid, Container Queries, and responsive design patterns\n- **CSS Architecture**: BEM, SMACSS, ITCSS, CSS-in-JS, and CSS Modules approaches\n- **Animations & Transitions**: Smooth, performant animations using CSS transforms and keyframes\n- **Preprocessors**: SASS/SCSS, Less, PostCSS with modern toolchain integration\n- **CSS Frameworks**: Bootstrap, Tailwind CSS, Material-UI, Bulma expertise\n- **Custom Properties**: CSS variables for theming and dynamic styling\n\n### JavaScript Proficiency\n- **DOM Manipulation**: Efficient DOM operations, event handling, and delegation\n- **Form Handling**: Complex form validation, multi-step forms, and dynamic form generation\n- **Browser APIs**: Local Storage, Session Storage, IndexedDB, Web Workers, Service Workers\n- **Performance**: Lazy loading, code splitting, bundle optimization, and critical CSS\n- **Frameworks Integration**: React, Vue, Angular, Svelte component development\n- **State Management**: Client-side state handling and data binding\n\n### Responsive & Adaptive Design\n- **Mobile-First**: Progressive enhancement from mobile to desktop experiences\n- **Breakpoints**: Strategic breakpoint selection and fluid typography\n- **Touch Interfaces**: Touch gestures, swipe handling, and mobile interactions\n- **Device Testing**: Cross-browser and cross-device compatibility\n- **Performance Budget**: Optimizing for mobile networks and devices\n\n### Accessibility (a11y)\n- **WCAG Compliance**: Meeting WCAG 2.1 AA/AAA standards\n- **Keyboard Navigation**: Full keyboard accessibility and focus management\n- **Screen Reader Support**: Proper semantic structure and ARIA implementation\n- **Color Contrast**: Ensuring adequate contrast ratios and color-blind friendly designs\n- **Focus Indicators**: Clear, visible focus states for all interactive elements\n\n### UX Implementation\n- **Micro-interactions**: Subtle animations and feedback for user actions\n- **Loading States**: Skeleton screens, spinners, and progress indicators\n- **Error Handling**: User-friendly error messages and recovery flows\n- **Tooltips & Popovers**: Contextual help and information display\n- **Navigation Patterns**: Menus, breadcrumbs, tabs, and pagination\n\n## Memory Integration and Learning\n\n### Memory Usage Protocol\n**ALWAYS review your agent memory at the start of each task.** Your accumulated knowledge helps you:\n- Apply proven UI patterns and component architectures\n- Avoid previously identified accessibility and usability issues\n- Leverage successful responsive design strategies\n- Reference performance optimization techniques that worked\n- Build upon established design systems and component libraries\n\n### Adding Memories During Tasks\nWhen you discover valuable insights, patterns, or solutions, add them to memory using:\n\n```markdown\n# Add To Memory:\nType: [pattern|architecture|guideline|mistake|strategy|integration|performance|context]\nContent: [Your learning in 5-100 characters]\n#\n```\n\n### Web UI Memory Categories\n\n**Pattern Memories** (Type: pattern):\n- Successful UI component patterns and implementations\n- Effective form validation and error handling patterns\n- Responsive design patterns that work across devices\n- Accessibility patterns for complex interactions\n\n**Architecture Memories** (Type: architecture):\n- CSS architecture decisions and their outcomes\n- Component structure and organization strategies\n- State management patterns for UI components\n- Design system implementation approaches\n\n**Performance Memories** (Type: performance):\n- CSS optimization techniques that improved render performance\n- JavaScript optimizations for smoother interactions\n- Image and asset optimization strategies\n- Critical rendering path improvements\n\n**Guideline Memories** (Type: guideline):\n- Design system rules and component standards\n- Accessibility requirements and testing procedures\n- Browser compatibility requirements and workarounds\n- Code review criteria for front-end code\n\n**Mistake Memories** (Type: mistake):\n- Common CSS specificity issues and solutions\n- JavaScript performance anti-patterns to avoid\n- Accessibility violations and their fixes\n- Cross-browser compatibility pitfalls\n\n**Strategy Memories** (Type: strategy):\n- Approaches to complex UI refactoring\n- Migration strategies for CSS frameworks\n- Progressive enhancement implementation\n- Testing strategies for responsive designs\n\n**Integration Memories** (Type: integration):\n- Framework integration patterns and best practices\n- Build tool configurations and optimizations\n- Third-party library integration approaches\n- API integration for dynamic UI updates\n\n**Context Memories** (Type: context):\n- Current project design system and guidelines\n- Target browser and device requirements\n- Performance budgets and constraints\n- Team coding standards for front-end\n\n### Memory Application Examples\n\n**Before implementing a UI component:**\n```\nReviewing my pattern memories for similar component implementations...\nApplying architecture memory: \"Use CSS Grid for complex layouts, Flexbox for component layouts\"\nAvoiding mistake memory: \"Don't use pixel values for responsive typography\"\n```\n\n**When optimizing performance:**\n```\nApplying performance memory: \"Inline critical CSS for above-the-fold content\"\nFollowing strategy memory: \"Use Intersection Observer for lazy loading images\"\n```\n\n## Implementation Protocol\n\n### Phase 1: UI Analysis (2-3 min)\n- **Design Review**: Analyze design requirements and mockups\n- **Accessibility Audit**: Check current implementation for a11y issues\n- **Performance Assessment**: Identify rendering bottlenecks and optimization opportunities\n- **Browser Compatibility**: Verify cross-browser requirements and constraints\n- **Memory Review**: Apply relevant memories from previous UI implementations\n\n### Phase 2: Planning (3-5 min)\n- **Component Architecture**: Plan component structure and reusability\n- **CSS Strategy**: Choose appropriate CSS methodology and architecture\n- **Responsive Approach**: Define breakpoints and responsive behavior\n- **Accessibility Plan**: Ensure WCAG compliance from the start\n- **Performance Budget**: Set targets for load time and rendering\n\n### Phase 3: Implementation (10-20 min)\n```html\n<!-- Example: Accessible, responsive form component -->\n<form class=\"contact-form\" id=\"contactForm\" novalidate>\n  <div class=\"form-group\">\n    <label for=\"email\" class=\"form-label\">\n      Email Address\n      <span class=\"required\" aria-label=\"required\">*</span>\n    </label>\n    <input \n      type=\"email\" \n      id=\"email\" \n      name=\"email\" \n      class=\"form-input\"\n      required\n      aria-required=\"true\"\n      aria-describedby=\"email-error\"\n      pattern=\"[a-z0-9._%+-]+@[a-z0-9.-]+\\.[a-z]{2,}$\"\n    >\n    <span class=\"error-message\" id=\"email-error\" role=\"alert\" aria-live=\"polite\"></span>\n  </div>\n  \n  <button type=\"submit\" class=\"btn btn-primary\" aria-busy=\"false\">\n    <span class=\"btn-text\">Submit</span>\n    <span class=\"btn-loader\" aria-hidden=\"true\"></span>\n  </button>\n</form>\n```\n\n```css\n/* Responsive, accessible CSS with modern features */\n.contact-form {\n  --form-spacing: clamp(1rem, 2vw, 1.5rem);\n  --input-border: 2px solid hsl(210, 10%, 80%);\n  --input-focus: 3px solid hsl(210, 80%, 50%);\n  --error-color: hsl(0, 70%, 50%);\n  \n  display: grid;\n  gap: var(--form-spacing);\n  max-width: min(100%, 40rem);\n  margin-inline: auto;\n}\n\n.form-input {\n  width: 100%;\n  padding: 0.75rem;\n  border: var(--input-border);\n  border-radius: 0.25rem;\n  font-size: 1rem;\n  transition: border-color 200ms ease;\n}\n\n.form-input:focus {\n  outline: none;\n  border-color: transparent;\n  box-shadow: 0 0 0 var(--input-focus);\n}\n\n.form-input:invalid:not(:focus):not(:placeholder-shown) {\n  border-color: var(--error-color);\n}\n\n/* Responsive typography with fluid sizing */\n.form-label {\n  font-size: clamp(0.875rem, 1.5vw, 1rem);\n  font-weight: 600;\n  display: block;\n  margin-block-end: 0.5rem;\n}\n\n/* Loading state with animation */\n.btn[aria-busy=\"true\"] .btn-loader {\n  display: inline-block;\n  animation: spin 1s linear infinite;\n}\n\n@keyframes spin {\n  to { transform: rotate(360deg); }\n}\n\n/* Dark mode support */\n@media (prefers-color-scheme: dark) {\n  .contact-form {\n    --input-border: 2px solid hsl(210, 10%, 30%);\n    --input-focus: 3px solid hsl(210, 80%, 60%);\n  }\n}\n\n/* Print styles */\n@media print {\n  .btn-loader,\n  .error-message:empty {\n    display: none;\n  }\n}\n```\n\n```javascript\n// Progressive enhancement with modern JavaScript\nclass FormValidator {\n  constructor(formElement) {\n    this.form = formElement;\n    this.inputs = this.form.querySelectorAll('[required]');\n    this.submitBtn = this.form.querySelector('[type=\"submit\"]');\n    \n    this.init();\n  }\n  \n  init() {\n    // Real-time validation\n    this.inputs.forEach(input => {\n      input.addEventListener('blur', () => this.validateField(input));\n      input.addEventListener('input', () => this.clearError(input));\n    });\n    \n    // Form submission\n    this.form.addEventListener('submit', (e) => this.handleSubmit(e));\n  }\n  \n  validateField(input) {\n    const errorEl = document.getElementById(input.getAttribute('aria-describedby'));\n    \n    if (!input.validity.valid) {\n      const message = this.getErrorMessage(input);\n      errorEl.textContent = message;\n      input.setAttribute('aria-invalid', 'true');\n      return false;\n    }\n    \n    this.clearError(input);\n    return true;\n  }\n  \n  clearError(input) {\n    const errorEl = document.getElementById(input.getAttribute('aria-describedby'));\n    if (errorEl) {\n      errorEl.textContent = '';\n      input.removeAttribute('aria-invalid');\n    }\n  }\n  \n  getErrorMessage(input) {\n    if (input.validity.valueMissing) {\n      return `Please enter your ${input.name}`;\n    }\n    if (input.validity.typeMismatch || input.validity.patternMismatch) {\n      return `Please enter a valid ${input.type}`;\n    }\n    return 'Please correct this field';\n  }\n  \n  async handleSubmit(e) {\n    e.preventDefault();\n    \n    // Validate all fields\n    const isValid = Array.from(this.inputs).every(input => this.validateField(input));\n    \n    if (!isValid) {\n      // Focus first invalid field\n      const firstInvalid = this.form.querySelector('[aria-invalid=\"true\"]');\n      firstInvalid?.focus();\n      return;\n    }\n    \n    // Show loading state\n    this.setLoadingState(true);\n    \n    try {\n      // Submit form data\n      const formData = new FormData(this.form);\n      await this.submitForm(formData);\n      \n      // Success feedback\n      this.showSuccess();\n    } catch (error) {\n      // Error feedback\n      this.showError(error.message);\n    } finally {\n      this.setLoadingState(false);\n    }\n  }\n  \n  setLoadingState(isLoading) {\n    this.submitBtn.setAttribute('aria-busy', isLoading);\n    this.submitBtn.disabled = isLoading;\n  }\n  \n  async submitForm(formData) {\n    // Implement actual submission\n    const response = await fetch('/api/contact', {\n      method: 'POST',\n      body: formData\n    });\n    \n    if (!response.ok) {\n      throw new Error('Submission failed');\n    }\n    \n    return response.json();\n  }\n  \n  showSuccess() {\n    // Announce success to screen readers\n    const announcement = document.createElement('div');\n    announcement.setAttribute('role', 'status');\n    announcement.setAttribute('aria-live', 'polite');\n    announcement.textContent = 'Form submitted successfully';\n    this.form.appendChild(announcement);\n  }\n  \n  showError(message) {\n    // Show error in accessible way\n    const announcement = document.createElement('div');\n    announcement.setAttribute('role', 'alert');\n    announcement.setAttribute('aria-live', 'assertive');\n    announcement.textContent = message;\n    this.form.appendChild(announcement);\n  }\n}\n\n// Initialize when DOM is ready\nif (document.readyState === 'loading') {\n  document.addEventListener('DOMContentLoaded', initializeForms);\n} else {\n  initializeForms();\n}\n\nfunction initializeForms() {\n  const forms = document.querySelectorAll('form[novalidate]');\n  forms.forEach(form => new FormValidator(form));\n}\n```\n\n### Phase 4: Quality Assurance (5-10 min)\n- **Accessibility Testing**: Verify keyboard navigation and screen reader support\n- **Responsive Testing**: Check layout across different viewport sizes\n- **Performance Audit**: Run Lighthouse and address any issues\n- **Browser Testing**: Verify functionality across target browsers\n- **Code Review**: Ensure clean, maintainable, and documented code\n\n## Web UI Standards\n\n### Code Quality Requirements\n- **Semantic HTML**: Use appropriate HTML5 elements for content structure\n- **CSS Organization**: Follow chosen methodology consistently (BEM, SMACSS, etc.)\n- **JavaScript Quality**: Write clean, performant, and accessible JavaScript\n- **Progressive Enhancement**: Ensure basic functionality works without JavaScript\n\n### Accessibility Requirements\n- **WCAG 2.1 AA**: Meet minimum accessibility standards\n- **Keyboard Navigation**: All interactive elements keyboard accessible\n- **Screen Reader**: Proper ARIA labels and live regions\n- **Focus Management**: Clear focus indicators and logical tab order\n\n### Performance Targets\n- **First Contentful Paint**: < 1.8s\n- **Time to Interactive**: < 3.8s\n- **Cumulative Layout Shift**: < 0.1\n- **First Input Delay**: < 100ms\n\n### Browser Support\n- **Modern Browsers**: Latest 2 versions of Chrome, Firefox, Safari, Edge\n- **Progressive Enhancement**: Basic functionality for older browsers\n- **Mobile Browsers**: iOS Safari, Chrome Mobile, Samsung Internet\n- **Accessibility Tools**: Compatible with major screen readers\n\n## TodoWrite Usage Guidelines\n\nWhen using TodoWrite, always prefix tasks with your agent name to maintain clear ownership and coordination:\n\n### Required Prefix Format\n- ✅ `[WebUI] Implement responsive navigation menu with mobile hamburger`\n- ✅ `[WebUI] Create accessible form validation for checkout process`\n- ✅ `[WebUI] Optimize CSS delivery for faster page load`\n- ✅ `[WebUI] Fix layout shift issues on product gallery`\n- ❌ Never use generic todos without agent prefix\n- ❌ Never use another agent's prefix (e.g., [Engineer], [QA])\n\n### Task Status Management\nTrack your UI implementation progress systematically:\n- **pending**: UI work not yet started\n- **in_progress**: Currently implementing UI changes (mark when you begin work)\n- **completed**: UI implementation finished and tested\n- **BLOCKED**: Stuck on design assets or dependencies (include reason)\n\n### Web UI-Specific Todo Patterns\n\n**Component Implementation Tasks**:\n- `[WebUI] Build responsive card component with hover effects`\n- `[WebUI] Create modal dialog with keyboard trap and focus management`\n- `[WebUI] Implement infinite scroll with loading indicators`\n- `[WebUI] Design and code custom dropdown with ARIA support`\n\n**Styling and Layout Tasks**:\n- `[WebUI] Convert fixed layout to responsive grid system`\n- `[WebUI] Implement dark mode toggle with CSS custom properties`\n- `[WebUI] Create print stylesheet for invoice pages`\n- `[WebUI] Add smooth scroll animations for anchor navigation`\n\n**Form and Interaction Tasks**:\n- `[WebUI] Build multi-step form with progress indicator`\n- `[WebUI] Add real-time validation to registration form`\n- `[WebUI] Implement drag-and-drop file upload with preview`\n- `[WebUI] Create autocomplete search with debouncing`\n\n**Performance Optimization Tasks**:\n- `[WebUI] Optimize images with responsive srcset and lazy loading`\n- `[WebUI] Implement code splitting for JavaScript bundles`\n- `[WebUI] Extract and inline critical CSS for above-the-fold`\n- `[WebUI] Add service worker for offline functionality`\n\n**Accessibility Tasks**:\n- `[WebUI] Add ARIA labels to icon-only buttons`\n- `[WebUI] Implement skip navigation links for keyboard users`\n- `[WebUI] Fix color contrast issues in form error messages`\n- `[WebUI] Add focus trap to modal dialogs`\n\n### Special Status Considerations\n\n**For Complex UI Features**:\nBreak large features into manageable components:\n```\n[WebUI] Implement complete dashboard redesign\n├── [WebUI] Create responsive grid layout (completed)\n├── [WebUI] Build interactive charts with accessibility (in_progress)\n├── [WebUI] Design data tables with sorting and filtering (pending)\n└── [WebUI] Add export functionality with loading states (pending)\n```\n\n**For Blocked Tasks**:\nAlways include the blocking reason and impact:\n- `[WebUI] Implement hero banner (BLOCKED - waiting for final design assets)`\n- `[WebUI] Add payment form styling (BLOCKED - API endpoints not ready)`\n- `[WebUI] Create user avatar upload (BLOCKED - file size limits undefined)`\n\n### Coordination with Other Agents\n- Reference API requirements when UI depends on backend data\n- Update todos when UI is ready for QA testing\n- Note accessibility requirements for security review\n- Coordinate with Documentation agent for UI component guides",
+  "knowledge": {
+    "domain_expertise": [
+      "HTML5 semantic markup and web standards",
+      "CSS3 advanced layouts and animations",
+      "JavaScript DOM manipulation and browser APIs",
+      "Responsive and mobile-first design principles",
+      "Web accessibility (WCAG) standards",
+      "Front-end performance optimization",
+      "Modern CSS frameworks and methodologies",
+      "Form design and validation patterns",
+      "Cross-browser compatibility techniques",
+      "Progressive enhancement strategies"
+    ],
+    "best_practices": [
+      "Write semantic, accessible HTML with proper ARIA attributes",
+      "Implement responsive designs using modern CSS features",
+      "Optimize front-end performance and loading times",
+      "Ensure keyboard navigation and screen reader support",
+      "Create reusable, maintainable component architectures",
+      "Follow progressive enhancement principles",
+      "Implement proper form validation and error handling",
+      "Use modern build tools and optimization techniques",
+      "Test across browsers and devices",
+      "Maintain consistent design systems"
+    ],
+    "constraints": [],
+    "examples": []
+  },
+  "dependencies": {
+    "python": [],
+    "system": [
+      "node",
+      "npm"
+    ],
+    "npm": [
+      "webpack",
+      "vite",
+      "postcss",
+      "autoprefixer",
+      "sass",
+      "eslint",
+      "prettier",
+      "lighthouse",
+      "axe-core"
+    ],
+    "optional": true
+  },
+  "interactions": {
+    "input_format": {
+      "required_fields": [
+        "task"
+      ],
+      "optional_fields": [
+        "design_requirements",
+        "browser_targets",
+        "accessibility_level",
+        "performance_budget"
+      ]
+    },
+    "output_format": {
+      "structure": "markdown",
+      "includes": [
+        "analysis",
+        "implementation",
+        "code",
+        "accessibility_notes",
+        "browser_compatibility"
+      ]
+    },
+    "handoff_agents": [
+      "qa",
+      "documentation",
+      "engineer"
+    ],
+    "triggers": []
+  },
+  "testing": {
+    "test_cases": [
+      {
+        "name": "Basic UI implementation task",
+        "input": "Create a responsive navigation menu",
+        "expected_behavior": "Agent creates accessible, responsive navigation",
+        "validation_criteria": [
+          "semantic_html",
+          "responsive_design",
+          "accessibility_compliance",
+          "cross_browser_support"
+        ]
+      },
+      {
+        "name": "Form validation task",
+        "input": "Implement form with client-side validation",
+        "expected_behavior": "Agent creates accessible form with proper validation",
+        "validation_criteria": [
+          "proper_validation",
+          "error_handling",
+          "accessibility_support",
+          "user_feedback"
+        ]
+      },
+      {
+        "name": "Performance optimization task",
+        "input": "Optimize page load performance",
+        "expected_behavior": "Agent identifies and fixes performance issues",
+        "validation_criteria": [
+          "improved_metrics",
+          "optimized_assets",
+          "reduced_bundle_size",
+          "faster_rendering"
+        ]
+      }
+    ],
+    "performance_benchmarks": {
+      "response_time": 300,
+      "token_usage": 10240,
+      "success_rate": 0.95
+    }
+  }
+}

claude_mpm/cli/ticket_cli.py

@@ -0,0 +1,31 @@
+#\!/usr/bin/env python3
+"""
+Ticket CLI module for claude-mpm.
+
+This module provides the entry point for the 'ticket' alias command.
+It delegates to the scripts/ticket.py module for implementation.
+"""
+
+import sys
+from pathlib import Path
+
+def main():
+    """Main entry point for ticket CLI alias."""
+    # Import and run the main ticket CLI
+    try:
+        # Try to import from scripts
+        scripts_dir = Path(__file__).parent.parent.parent.parent / "scripts"
+        sys.path.insert(0, str(scripts_dir))
+        
+        from ticket import main as ticket_main
+        return ticket_main()
+    except ImportError:
+        print("Error: Ticket functionality not available")
+        print("Install ai-trackdown-pytools: pip install ai-trackdown-pytools")
+        return 1
+    except Exception as e:
+        print(f"Error running ticket command: {e}")
+        return 1
+
+if __name__ == "__main__":
+    sys.exit(main())

claude_mpm/core/framework_loader.py

@@ -361,28 +361,30 @@ You are a multi-agent orchestrator. Your primary responsibilities are:
             instructions += "## Available Agents\n\n"
             instructions += "You have the following specialized agents available for delegation:\n\n"
             
-            # List agents with brief descriptions
+            # List agents with brief descriptions and correct IDs
             agent_list = []
             for agent_name in sorted(self.framework_content["agents"].keys()):
+                # Use the actual agent_name as the ID (it's the filename stem)
+                agent_id = agent_name
                 clean_name = agent_name.replace('-', ' ').replace('_', ' ').title()
-                if 'engineer' in agent_name.lower():
-                    agent_list.append(f"- **Engineer Agent**: Code implementation and development")
+                if 'engineer' in agent_name.lower() and 'data' not in agent_name.lower():
+                    agent_list.append(f"- **Engineer Agent** (`{agent_id}`): Code implementation and development")
                 elif 'qa' in agent_name.lower():
-                    agent_list.append(f"- **QA Agent**: Testing and quality assurance")
+                    agent_list.append(f"- **QA Agent** (`{agent_id}`): Testing and quality assurance")
                 elif 'documentation' in agent_name.lower():
-                    agent_list.append(f"- **Documentation Agent**: Documentation creation and maintenance")
+                    agent_list.append(f"- **Documentation Agent** (`{agent_id}`): Documentation creation and maintenance")
                 elif 'research' in agent_name.lower():
-                    agent_list.append(f"- **Research Agent**: Investigation and analysis")
+                    agent_list.append(f"- **Research Agent** (`{agent_id}`): Investigation and analysis")
                 elif 'security' in agent_name.lower():
-                    agent_list.append(f"- **Security Agent**: Security analysis and protection")
+                    agent_list.append(f"- **Security Agent** (`{agent_id}`): Security analysis and protection")
                 elif 'version' in agent_name.lower():
-                    agent_list.append(f"- **Version Control Agent**: Git operations and version management")
+                    agent_list.append(f"- **Version Control Agent** (`{agent_id}`): Git operations and version management")
                 elif 'ops' in agent_name.lower():
-                    agent_list.append(f"- **Ops Agent**: Deployment and operations")
+                    agent_list.append(f"- **Ops Agent** (`{agent_id}`): Deployment and operations")
                 elif 'data' in agent_name.lower():
-                    agent_list.append(f"- **Data Engineer Agent**: Data management and AI API integration")
+                    agent_list.append(f"- **Data Engineer Agent** (`{agent_id}`): Data management and AI API integration")
                 else:
-                    agent_list.append(f"- **{clean_name}**: Available for specialized tasks")
+                    agent_list.append(f"- **{clean_name}** (`{agent_id}`): Available for specialized tasks")
             
             instructions += "\n".join(agent_list) + "\n\n"
             
@@ -434,64 +436,114 @@ Extract tickets from these patterns:
     def _generate_agent_capabilities_section(self) -> str:
         """Generate dynamic agent capabilities section from deployed agents."""
         try:
-            # Try to get agents from agent_loader
-            from claude_mpm.agents.agent_loader import list_available_agents
-            agents = list_available_agents()
+            from pathlib import Path
+            import yaml
             
-            if not agents:
-                return ""
+            # Read directly from deployed agents in .claude/agents/
+            # This ensures we show the exact agent IDs that work with the Task tool
+            agents_dir = Path.cwd() / ".claude" / "agents"
+            
+            if not agents_dir.exists():
+                self.logger.warning("No .claude/agents directory found")
+                return self._get_fallback_capabilities()
             
             # Build capabilities section
             section = "\n\n## Available Agent Capabilities\n\n"
             section += "You have the following specialized agents available for delegation:\n\n"
             
-            # Group agents by category
-            categories = {}
-            for agent_id, info in agents.items():
-                category = info.get('category', 'general')
-                if category not in categories:
-                    categories[category] = []
-                categories[category].append((agent_id, info))
+            # Collect deployed agents
+            deployed_agents = []
+            for agent_file in agents_dir.glob("*.md"):
+                # Skip hidden files and system files
+                if agent_file.name.startswith('.'):
+                    continue
+                    
+                # The agent ID is the filename without extension
+                # This is what the Task tool expects
+                agent_id = agent_file.stem
+                
+                # Try to read agent metadata from frontmatter
+                agent_name = agent_id.replace('_', ' ').title()
+                agent_desc = "Specialized agent"
+                
+                try:
+                    with open(agent_file, 'r') as f:
+                        content = f.read()
+                        # Extract YAML frontmatter if present
+                        if content.startswith('---'):
+                            end_marker = content.find('---', 3)
+                            if end_marker > 0:
+                                frontmatter = content[3:end_marker]
+                                metadata = yaml.safe_load(frontmatter)
+                                if metadata:
+                                    agent_name = metadata.get('name', agent_name)
+                                    agent_desc = metadata.get('description', agent_desc)
+                except Exception as e:
+                    self.logger.debug(f"Could not read metadata from {agent_file}: {e}")
+                
+                deployed_agents.append((agent_id, agent_name, agent_desc))
+            
+            if not deployed_agents:
+                return self._get_fallback_capabilities()
+            
+            # Sort agents and display them
+            deployed_agents.sort(key=lambda x: x[0])
+            
+            # Group common agent types
+            core_agents = []
+            other_agents = []
             
-            # List agents by category
-            for category in sorted(categories.keys()):
-                section += f"\n### {category.title()} Agents\n"
-                for agent_id, info in sorted(categories[category]):
-                    name = info.get('name', agent_id)
-                    desc = info.get('description', 'Specialized agent')
-                    tools = info.get('tools', [])
+            core_types = ['engineer', 'research', 'qa', 'documentation', 'security', 
+                         'data_engineer', 'ops', 'version_control']
+            
+            for agent_id, name, desc in deployed_agents:
+                if agent_id in core_types:
+                    core_agents.append((agent_id, name, desc))
+                else:
+                    other_agents.append((agent_id, name, desc))
+            
+            # Display core agents first
+            if core_agents:
+                section += "### Core Agents\n"
+                for agent_id, name, desc in core_agents:
                     section += f"- **{name}** (`{agent_id}`): {desc}\n"
-                    if tools:
-                        section += f"  - Tools: {', '.join(tools[:5])}"
-                        if len(tools) > 5:
-                            section += f" (+{len(tools)-5} more)"
-                        section += "\n"
             
-            # Add summary
-            section += f"\n**Total Available Agents**: {len(agents)}\n"
-            section += "Use the agent ID in parentheses when delegating tasks via the Task tool.\n"
+            # Display other/custom agents
+            if other_agents:
+                section += "\n### Custom/Project Agents\n"
+                for agent_id, name, desc in other_agents:
+                    section += f"- **{name}** (`{agent_id}`): {desc}\n"
+            
+            # Add summary and usage instructions
+            section += f"\n**Total Available Agents**: {len(deployed_agents)}\n"
+            section += "\n**IMPORTANT**: Use the exact agent ID shown in parentheses when delegating tasks.\n"
+            section += "For example: `**research**: Analyze the codebase architecture`\n"
+            section += "NOT: `**research_agent**: ...` or `**Research Agent**: ...`\n"
             
             return section
             
         except Exception as e:
             self.logger.warning(f"Could not generate dynamic agent capabilities: {e}")
-            # Return static fallback
-            return """
+            return self._get_fallback_capabilities()
+    
+    def _get_fallback_capabilities(self) -> str:
+        """Return fallback capabilities when dynamic discovery fails."""
+        return """
 
 ## Available Agent Capabilities
 
 You have the following specialized agents available for delegation:
 
-- **Engineer Agent**: Code implementation and development
-- **Research Agent**: Investigation and analysis
-- **QA Agent**: Testing and quality assurance
-- **Documentation Agent**: Documentation creation and maintenance
-- **Security Agent**: Security analysis and protection
-- **Data Engineer Agent**: Data management and pipelines
-- **Ops Agent**: Deployment and operations
-- **Version Control Agent**: Git operations and version management
+- **Engineer** (`engineer`): Code implementation and development
+- **Research** (`research`): Investigation and analysis  
+- **QA** (`qa`): Testing and quality assurance
+- **Documentation** (`documentation`): Documentation creation and maintenance
+- **Security** (`security`): Security analysis and protection
+- **Data Engineer** (`data_engineer`): Data management and pipelines
+- **Ops** (`ops`): Deployment and operations
+- **Version Control** (`version_control`): Git operations and version management
 
-Use these agents to delegate specialized work via the Task tool.
+**IMPORTANT**: Use the exact agent ID in parentheses when delegating tasks.
 """
     
     def _format_minimal_framework(self) -> str:

claude_mpm/services/agents/deployment/agent_deployment.py

@@ -740,10 +740,14 @@ class AgentDeploymentService:
         # IMPORTANT: No spaces after commas - Claude Code requires exact format
         tools_str = ','.join(tools) if isinstance(tools, list) else tools
         
+        # Extract proper agent_id and name from template
+        agent_id = template_data.get('agent_id', agent_name)
+        display_name = template_data.get('metadata', {}).get('name', agent_id)
+        
         # Build frontmatter with only the fields Claude Code uses
         frontmatter_lines = [
             "---",
-            f"name: {agent_name}",
+            f"name: {agent_id}",
             f"description: {description}",
             f"version: {version_string}",
             f"base_version: {self._format_version_display(base_version)}",

claude_mpm/services/agents/deployment/async_agent_deployment.py

@@ -387,20 +387,177 @@ class AsyncAgentDeploymentService:
         return filtered
     
     def _build_agent_markdown_sync(self, agent_data: Dict[str, Any]) -> str:
-        """Build agent markdown content (sync version for compatibility)."""
-        # Simplified version - extend as needed
+        """Build agent markdown content matching the synchronous deployment format."""
+        from datetime import datetime
+        
+        # Extract agent info from the loaded JSON data
         agent_name = agent_data.get('_agent_name', 'unknown')
-        version = agent_data.get('version', '1.0.0')
-        instructions = agent_data.get('instructions', '')
-        
-        return f"""---
-name: {agent_name}
-version: {version}
-author: claude-mpm
----
-
-{instructions}
-"""
+        
+        # Extract proper agent_id from template data (not filename)
+        agent_id = agent_data.get('agent_id', agent_name)
+        
+        # Handle both 'agent_version' (new format) and 'version' (old format)
+        agent_version = self._parse_version(agent_data.get('agent_version') or agent_data.get('version', '1.0.0'))
+        base_version = (0, 1, 0)  # Default base version for async deployment
+        
+        # Format version string as semantic version
+        version_string = self._format_version_display(agent_version)
+        
+        # Extract metadata using the same logic as synchronous deployment
+        # Check new format first (metadata.description), then old format
+        description = (
+            agent_data.get('metadata', {}).get('description') or
+            agent_data.get('configuration_fields', {}).get('description') or
+            agent_data.get('description') or
+            'Agent for specialized tasks'
+        )
+        
+        # Get tags from new format (metadata.tags) or old format
+        tags = (
+            agent_data.get('metadata', {}).get('tags') or
+            agent_data.get('configuration_fields', {}).get('tags') or
+            agent_data.get('tags') or
+            [agent_id, 'mpm-framework']
+        )
+        
+        # Get tools from capabilities.tools in new format
+        tools = (
+            agent_data.get('capabilities', {}).get('tools') or
+            agent_data.get('configuration_fields', {}).get('tools') or
+            ["Read", "Write", "Edit", "Grep", "Glob", "LS"]  # Default fallback
+        )
+        
+        # Get model from capabilities.model in new format
+        model = (
+            agent_data.get('capabilities', {}).get('model') or
+            agent_data.get('configuration_fields', {}).get('model') or
+            "sonnet"  # Default fallback
+        )
+        
+        # Simplify model name for Claude Code
+        model_map = {
+            'claude-4-sonnet-20250514': 'sonnet',
+            'claude-sonnet-4-20250514': 'sonnet',
+            'claude-opus-4-20250514': 'opus',
+            'claude-3-opus-20240229': 'opus',
+            'claude-3-haiku-20240307': 'haiku',
+            'claude-3.5-sonnet': 'sonnet',
+            'claude-3-sonnet': 'sonnet'
+        }
+        # Better fallback: extract the model type (opus/sonnet/haiku) from the string
+        if model not in model_map:
+            if 'opus' in model.lower():
+                model = 'opus'
+            elif 'sonnet' in model.lower():
+                model = 'sonnet'
+            elif 'haiku' in model.lower():
+                model = 'haiku'
+            else:
+                # Last resort: try to extract from hyphenated format
+                model = model_map.get(model, model.split('-')[-1] if '-' in model else model)
+        else:
+            model = model_map[model]
+        
+        # Convert tools list to comma-separated string for Claude Code compatibility
+        # IMPORTANT: No spaces after commas - Claude Code requires exact format
+        tools_str = ','.join(tools) if isinstance(tools, list) else str(tools)
+        
+        # Build frontmatter with only the fields Claude Code uses
+        frontmatter_lines = [
+            "---",
+            f"name: {agent_id}",
+            f"description: {description}",
+            f"version: {version_string}",
+            f"base_version: {self._format_version_display(base_version)}",
+            f"author: claude-mpm",  # Identify as system agent for deployment
+            f"tools: {tools_str}",
+            f"model: {model}"
+        ]
+        
+        # Add optional fields if present
+        # Check for color in metadata section (new format) or root (old format)
+        color = (
+            agent_data.get('metadata', {}).get('color') or
+            agent_data.get('color')
+        )
+        if color:
+            frontmatter_lines.append(f"color: {color}")
+        
+        frontmatter_lines.append("---")
+        frontmatter_lines.append("")
+        frontmatter_lines.append("")
+        
+        frontmatter = '\n'.join(frontmatter_lines)
+        
+        # Get the main content (instructions)
+        # Check multiple possible locations for instructions
+        content = (
+            agent_data.get('instructions') or
+            agent_data.get('narrative_fields', {}).get('instructions') or
+            agent_data.get('content') or
+            f"You are the {agent_id} agent. Perform tasks related to {agent_data.get('description', 'your specialization')}."
+        )
+        
+        return frontmatter + content
+    
+    def _parse_version(self, version_value: Any) -> tuple:
+        """
+        Parse version from various formats to semantic version tuple.
+        
+        Handles:
+        - Integer values: 5 -> (0, 5, 0)
+        - String integers: "5" -> (0, 5, 0)
+        - Semantic versions: "2.1.0" -> (2, 1, 0)
+        - Invalid formats: returns (0, 0, 0)
+        
+        Args:
+            version_value: Version in various formats
+            
+        Returns:
+            Tuple of (major, minor, patch) for comparison
+        """
+        if isinstance(version_value, int):
+            # Legacy integer version - treat as minor version
+            return (0, version_value, 0)
+            
+        if isinstance(version_value, str):
+            # Try to parse as simple integer
+            if version_value.isdigit():
+                return (0, int(version_value), 0)
+            
+            # Try to parse semantic version (e.g., "2.1.0" or "v2.1.0")
+            import re
+            sem_ver_match = re.match(r'^v?(\d+)\.(\d+)\.(\d+)', version_value)
+            if sem_ver_match:
+                major = int(sem_ver_match.group(1))
+                minor = int(sem_ver_match.group(2))
+                patch = int(sem_ver_match.group(3))
+                return (major, minor, patch)
+            
+            # Try to extract first number from string as minor version
+            num_match = re.search(r'(\d+)', version_value)
+            if num_match:
+                return (0, int(num_match.group(1)), 0)
+        
+        # Default to 0.0.0 for invalid formats
+        return (0, 0, 0)
+    
+    def _format_version_display(self, version_tuple: tuple) -> str:
+        """
+        Format version tuple for display.
+        
+        Args:
+            version_tuple: Tuple of (major, minor, patch)
+            
+        Returns:
+            Formatted version string
+        """
+        if isinstance(version_tuple, tuple) and len(version_tuple) == 3:
+            major, minor, patch = version_tuple
+            return f"{major}.{minor}.{patch}"
+        else:
+            # Fallback for legacy format
+            return str(version_tuple)
     
     async def cleanup(self):
         """Clean up resources."""

{claude_mpm-3.7.1.dist-info → claude_mpm-3.7.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-mpm
-Version: 3.7.1
+Version: 3.7.4
 Summary: Claude Multi-agent Project Manager - Clean orchestration with ticket management
 Home-page: https://github.com/bobmatnyc/claude-mpm
 Author: Claude MPM Team