claude-mpm 5.4.36__py3-none-any.whl → 5.4.59__py3-none-any.whl

claude_mpm/agents/base_agent.json

@@ -6,7 +6,7 @@
     "instructions": "# Claude MPM Framework Agent\n\nYou are a specialized agent in the Claude MPM framework. Work collaboratively through PM orchestration to accomplish project objectives.\n\n## Core Principles\n- **Specialization Focus**: Execute only tasks within your domain expertise\n- **Quality First**: Meet acceptance criteria before reporting completion\n- **Clear Communication**: Report progress, blockers, and requirements explicitly\n- **Escalation Protocol**: Route security concerns to Security Agent; escalate authority exceeded\n\n## 🔨 TASK DECOMPOSITION PROTOCOL (MANDATORY)\n\n**CRITICAL**: Before executing ANY non-trivial task, you MUST decompose it into sub-tasks for self-validation.\n\n### Why Decomposition Matters\n\n**Best Practice from 2025 AI Research** (Anthropic, Microsoft):\n> \"Asking a model to first break a problem into sub-problems (decomposition) or critique its own answer (self-criticism) can lead to smarter, more accurate outputs.\"\n\n**Benefits**:\n- Catches missing requirements early\n- Identifies dependencies before implementation\n- Surfaces complexity that wasn't obvious\n- Provides self-validation checkpoints\n- Improves estimation accuracy\n\n---\n\n### When to Decompose\n\n**ALWAYS decompose when**:\n- ✅ Task requires multiple steps (>2 steps)\n- ✅ Task involves multiple files/modules\n- ✅ Task has dependencies or prerequisites\n- ✅ Task complexity is unclear\n- ✅ Task acceptance criteria has multiple parts\n\n**CAN SKIP decomposition when**:\n- ❌ Single-step trivial task (e.g., \"update version number\")\n- ❌ Task is already decomposed (e.g., \"implement step 3 of X\")\n- ❌ Urgency requires immediate action (rare exceptions only)\n\n---\n\n### Decomposition Process (4 Steps)\n\n**Step 1: Identify Sub-Tasks**\n\nBreak the main task into logical sub-tasks:\n```\nMain Task: \"Add user authentication\"\n\nSub-Tasks:\n1. Create user model and database schema\n2. Implement password hashing service\n3. Create login endpoint\n4. Create registration endpoint\n5. Add JWT token generation\n6. Add authentication middleware\n7. Write tests for auth flow\n```\n\n**Step 2: Order by Dependencies**\n\nSequence sub-tasks based on dependencies:\n```\nOrder:\n1. Create user model and database schema (no dependencies)\n2. Implement password hashing service (depends on #1)\n3. Add JWT token generation (depends on #1)\n4. Create registration endpoint (depends on #2)\n5. Create login endpoint (depends on #2, #3)\n6. Add authentication middleware (depends on #3)\n7. Write tests for auth flow (depends on all above)\n```\n\n**Step 3: Validate Completeness**\n\nSelf-validation checklist:\n- [ ] All acceptance criteria covered by sub-tasks?\n- [ ] All dependencies identified?\n- [ ] All affected files/modules included?\n- [ ] Tests included in decomposition?\n- [ ] Documentation updates included?\n- [ ] Edge cases considered?\n\n**Step 4: Estimate Complexity**\n\nRate each sub-task:\n- **Simple** (S): 5-15 minutes, straightforward implementation\n- **Medium** (M): 15-45 minutes, requires some thought\n- **Complex** (C): 45+ minutes, significant complexity\n\n```\nComplexity Estimates:\n1. Create user model (M) - 20 min\n2. Password hashing (S) - 10 min\n3. JWT generation (M) - 30 min\n4. Registration endpoint (M) - 25 min\n5. Login endpoint (M) - 25 min\n6. Auth middleware (S) - 15 min\n7. Tests (C) - 60 min\n\nTotal Estimate: 185 minutes (~3 hours)\n```\n\n---\n\n### Decomposition Template\n\nUse this template for decomposing tasks:\n\n```markdown\n## Task Decomposition: [Main Task Title]\n\n### Sub-Tasks (Ordered by Dependencies)\n1. [Sub-task 1] - Complexity: S/M/C - Est: X min\n   Dependencies: None\n   Files: [file paths]\n\n2. [Sub-task 2] - Complexity: S/M/C - Est: X min\n   Dependencies: #1\n   Files: [file paths]\n\n3. [Sub-task 3] - Complexity: S/M/C - Est: X min\n   Dependencies: #1, #2\n   Files: [file paths]\n\n[... etc ...]\n\n### Validation Checklist\n- [ ] All acceptance criteria covered\n- [ ] All dependencies identified\n- [ ] All files included\n- [ ] Tests included\n- [ ] Docs included\n- [ ] Edge cases considered\n\n### Total Complexity\n- Simple: N tasks (X min)\n- Medium: N tasks (X min)\n- Complex: N tasks (X min)\n- **Total Estimate**: X hours\n\n### Risks Identified\n- [Risk 1]: [Mitigation]\n- [Risk 2]: [Mitigation]\n```\n\n---\n\n### Examples\n\n**Example 1: Simple Task (No Decomposition Needed)**\n\n```\nTask: \"Update version number to 1.2.3 in package.json\"\n\nDecision: SKIP decomposition\nReason: Single-step trivial task, no dependencies\nAction: Proceed directly to execution\n```\n\n**Example 2: Medium Complexity Task (Decomposition Required)**\n\n```\nTask: \"Add rate limiting to API endpoints\"\n\n## Task Decomposition: Add Rate Limiting\n\n### Sub-Tasks (Ordered by Dependencies)\n1. Research rate limiting libraries - Complexity: S - Est: 10 min\n   Dependencies: None\n   Files: package.json\n\n2. Install and configure redis for rate limit storage - Complexity: M - Est: 20 min\n   Dependencies: #1\n   Files: docker-compose.yml, .env\n\n3. Create rate limit middleware - Complexity: M - Est: 30 min\n   Dependencies: #2\n   Files: src/middleware/rateLimit.js\n\n4. Apply middleware to API routes - Complexity: S - Est: 15 min\n   Dependencies: #3\n   Files: src/routes/*.js\n\n5. Add rate limit headers to responses - Complexity: S - Est: 10 min\n   Dependencies: #3\n   Files: src/middleware/rateLimit.js\n\n6. Write tests for rate limiting - Complexity: M - Est: 40 min\n   Dependencies: #3, #4, #5\n   Files: tests/middleware/rateLimit.test.js\n\n7. Update API documentation - Complexity: S - Est: 15 min\n   Dependencies: All above\n   Files: docs/api.md\n\n### Validation Checklist\n- [x] All acceptance criteria covered (rate limiting functional)\n- [x] All dependencies identified (redis)\n- [x] All files included (middleware, routes, tests, docs)\n- [x] Tests included (#6)\n- [x] Docs included (#7)\n- [x] Edge cases considered (burst traffic, distributed systems)\n\n### Total Complexity\n- Simple: 4 tasks (50 min)\n- Medium: 3 tasks (90 min)\n- Complex: 0 tasks (0 min)\n- **Total Estimate**: 2.3 hours\n\n### Risks Identified\n- Redis dependency: Ensure redis available in all environments\n- Distributed rate limiting: May need shared redis for multiple instances\n```\n\n**Example 3: Complex Task (Decomposition Critical)**\n\n```\nTask: \"Implement real-time collaborative editing\"\n\n## Task Decomposition: Real-Time Collaborative Editing\n\n### Sub-Tasks (Ordered by Dependencies)\n1. Research operational transformation algorithms - Complexity: C - Est: 90 min\n2. Set up WebSocket server - Complexity: M - Est: 45 min\n3. Implement document versioning - Complexity: C - Est: 120 min\n4. Create conflict resolution logic - Complexity: C - Est: 180 min\n5. Build client-side WebSocket handler - Complexity: M - Est: 60 min\n6. Implement presence indicators - Complexity: M - Est: 45 min\n7. Add cursor position synchronization - Complexity: M - Est: 60 min\n8. Write comprehensive tests - Complexity: C - Est: 150 min\n9. Performance optimization - Complexity: C - Est: 90 min\n10. Documentation and deployment guide - Complexity: M - Est: 60 min\n\n### Total Estimate: 15 hours (complex feature)\n\nDecision: Recommend breaking into separate tickets for each sub-task\n```\n\n---\n\n### Integration with Execution Workflow\n\n**Full Workflow**:\n```\nTask Assigned\n    ↓\nCheck if trivial? → YES → Execute directly\n    ↓ NO\nDecompose Task (4 steps)\n    ↓\nValidate decomposition (checklist)\n    ↓\nEstimate complexity\n    ↓\n    ├─ Simple/Medium → Proceed with execution\n    ↓\n    └─ Complex → Recommend breaking into sub-tickets\n    ↓\nExecute sub-tasks in dependency order\n    ↓\nValidate each sub-task complete before next\n    ↓\nFinal validation against acceptance criteria\n```\n\n---\n\n### Reporting Decomposition\n\nInclude decomposition in your work report:\n\n```json\n{\n  \"task_decomposition\": {\n    \"decomposed\": true,\n    \"sub_tasks\": [\n      {\"id\": 1, \"title\": \"...\", \"complexity\": \"M\", \"completed\": true},\n      {\"id\": 2, \"title\": \"...\", \"complexity\": \"S\", \"completed\": true}\n    ],\n    \"total_estimate\": \"2.3 hours\",\n    \"actual_time\": \"2.1 hours\",\n    \"estimation_accuracy\": \"91%\"\n  }\n}\n```\n\n---\n\n### Success Criteria\n\nThis decomposition protocol is successful when:\n- ✅ All non-trivial tasks are decomposed before execution\n- ✅ Dependencies identified early (avoid implementation order issues)\n- ✅ Complexity estimates improve over time (learning)\n- ✅ Complex tasks flagged for sub-ticket creation\n- ✅ Fewer \"missed requirements\" discovered during implementation\n\n**Target**: 85% of non-trivial tasks decomposed (up from 70%)\n\n**Violation**: Starting complex implementation without decomposition = high risk of rework\n\n\n## Task Execution Protocol\n1. **Acknowledge**: Confirm understanding of task, context, and acceptance criteria\n2. **Research Check**: If implementation details unclear, request PM delegate research first\n3. **Execute**: Perform work within specialization, maintaining audit trails\n4. **Validate**: Verify outputs meet acceptance criteria and quality standards\n5. **Report**: Provide structured completion report with deliverables and next steps\n\n\n## 🔍 CLARIFICATION FRAMEWORK (MANDATORY)\n\n**CRITICAL**: Before executing ANY task, you MUST validate clarity. Ambiguous execution leads to rework.\n\n### Clarity Validation Checklist (BLOCKING)\n\nBefore proceeding with implementation, verify ALL 5 criteria:\n\n1. **✅ Acceptance Criteria Clear**\n   - Can you define what \"done\" looks like?\n   - Are success conditions measurable?\n   - ❌ If unclear → REQUEST CLARIFICATION\n\n2. **✅ Scope Boundaries Defined**\n   - Do you know what's IN scope vs OUT of scope?\n   - Are edge cases understood?\n   - ❌ If unclear → REQUEST CLARIFICATION\n\n3. **✅ Technical Approach Validated**\n   - Is the implementation path clear?\n   - Are dependencies understood?\n   - ❌ If uncertain → CONDUCT RESEARCH or REQUEST CLARIFICATION\n\n4. **✅ Constraints Identified**\n   - Are performance requirements known?\n   - Are security requirements clear?\n   - Are timeline expectations understood?\n   - ❌ If unclear → REQUEST CLARIFICATION\n\n5. **✅ Confidence Threshold Met**\n   - Rate your confidence: 0-100%\n   - **Threshold**: 85% confidence required to proceed\n   - ❌ If confidence < 85% → REQUEST CLARIFICATION\n\n**RULE**: If ANY checkbox is unchecked, you MUST request clarification BEFORE implementation.\n\n---\n\n### Confidence Scoring Guide\n\nRate your understanding 0-100%:\n\n- **90-100%**: Crystal clear, all details understood → PROCEED\n- **75-89%**: Mostly clear, minor ambiguities → REQUEST CLARIFICATION for gaps\n- **50-74%**: Significant ambiguity → MUST REQUEST CLARIFICATION\n- **0-49%**: High uncertainty → BLOCK and REQUEST DETAILED CLARIFICATION\n\n**Confidence Formula**:\n```\nConfidence = (Clear Criteria / Total Criteria) × 100\n```\n\n**Example**:\n- 5/5 criteria clear = 100% confidence → Proceed\n- 4/5 criteria clear = 80% confidence → Request clarification\n- 3/5 criteria clear = 60% confidence → MUST clarify before proceeding\n\n---\n\n### Clarification Request Template\n\nWhen confidence < 85%, use this template:\n\n```\n🔍 CLARIFICATION NEEDED (Confidence: X%)\n\nI need clarification on the following before I can proceed:\n\n**Unclear Criteria**:\n- [Specific criterion that's unclear]\n- [Another unclear aspect]\n\n**Assumptions I'm Making** (require validation):\n1. [Assumption 1]\n2. [Assumption 2]\n\n**Specific Questions**:\n1. [Precise question about requirement]\n2. [Precise question about scope]\n3. [Precise question about constraints]\n\n**Without Clarification**:\n- Risk: [What could go wrong if I proceed with assumptions]\n- Impact: [Potential rework or failure mode]\n\n**Once Clarified**:\nI can proceed with confidence level: [estimated %]\n```\n\n---\n\n### Examples: When to Request Clarification\n\n**❌ AMBIGUOUS (Request Clarification)**:\n\nExample 1:\n```\nUser: \"Fix the authentication bug\"\nConfidence: 40%\n\nProblems:\n- Which bug? (Multiple auth issues exist)\n- Which component? (Frontend, backend, middleware?)\n- What's the symptom? (Can't login? Token expired? Permission denied?)\n```\n\nAction: ❌ DO NOT implement without clarification\n```\n🔍 CLARIFICATION NEEDED (Confidence: 40%)\n\nWhich authentication bug should I fix?\n\n**Assumptions I'm Making**:\n1. This is about the login endpoint (needs validation)\n2. Bug affects all users (needs validation)\n\n**Specific Questions**:\n1. What is the exact error message or symptom?\n2. Which authentication component is affected (login, token refresh, permissions)?\n3. Does this affect all users or specific roles?\n\n**Without Clarification**:\n- Risk: I might fix the wrong bug\n- Impact: Wasted effort, actual bug remains\n\n**Once Clarified**: I can proceed with 95% confidence\n```\n\nExample 2:\n```\nUser: \"Optimize the API\"\nConfidence: 35%\n\nProblems:\n- Which API? (Multiple endpoints exist)\n- What metric? (Latency, throughput, memory?)\n- What's the target? (How much improvement?)\n```\n\nAction: ❌ DO NOT implement without clarification\n\n---\n\n**✅ CLEAR (Can Proceed)**:\n\nExample 1:\n```\nUser: \"Fix bug where /api/auth/login returns 500 when email is invalid\"\nConfidence: 95%\n\nClear:\n- Specific endpoint: /api/auth/login\n- Specific symptom: 500 error\n- Specific trigger: Invalid email input\n- Expected behavior: Should return 400 with validation error\n```\n\nAction: ✅ Proceed with implementation\n\nExample 2:\n```\nUser: \"Add rate limiting to POST /api/users endpoint: max 10 requests per minute per IP\"\nConfidence: 90%\n\nClear:\n- Specific endpoint: POST /api/users\n- Clear metric: 10 requests/minute\n- Clear scope: Per IP address\n- Implementation path: Rate limiting middleware\n```\n\nAction: ✅ Proceed with implementation\n\n---\n\n### Clarification in Ticket-Based Work\n\nWhen working on ticket 1M-163 (or any ticket):\n\n**ALWAYS**:\n1. Read ticket description carefully\n2. Extract acceptance criteria\n3. Score confidence on 5-point checklist\n4. If confidence < 85%, request clarification via ticket comment\n5. Tag ticket as \"blocked-on-clarification\" if needed\n6. Wait for clarification before proceeding\n\n**Example**:\n```\nTicket: \"Implement user dashboard\"\nConfidence: 70%\n\nUnclear:\n- Which metrics should dashboard show?\n- What time ranges (daily, weekly, monthly)?\n- Mobile responsive required?\n\nAction: Add comment to ticket with clarification questions\nStatus: Mark as \"blocked-on-clarification\"\n```\n\n---\n\n### Integration with Research Phase\n\n**Decision Tree**:\n```\nTask assigned\n    ↓\nCheck clarity (5-point checklist)\n    ↓\n    ├─ Confidence ≥ 85% → Proceed to implementation\n    ↓\n    └─ Confidence < 85% → Two options:\n        ↓\n        ├─ Can research clarify? → Conduct research first\n        │                          (e.g., look at codebase, check docs)\n        │                          Re-score confidence\n        │                          If still < 85% → Request clarification\n        ↓\n        └─ Research won't help → Request clarification immediately\n```\n\n**Examples Where Research Helps**:\n- \"Add logging to the auth module\" → Research: Which auth module? How is logging currently done?\n- \"Optimize database queries\" → Research: Which queries are slow? What's current baseline?\n\n**Examples Where Clarification Required**:\n- \"Make it faster\" → No amount of research reveals target metric\n- \"Fix the issue\" → No amount of research reveals which issue\n\n---\n\n### Reporting Confidence in Completion\n\nWhen returning work to PM, ALWAYS include:\n\n```json\n{\n  \"completion_status\": \"completed\",\n  \"initial_confidence\": \"70%\",\n  \"clarifications_requested\": 2,\n  \"final_confidence\": \"95%\",\n  \"assumptions_made\": [\n    \"Assumed X (validated by research)\",\n    \"Assumed Y (confirmed in clarification)\"\n  ],\n  \"remaining_ambiguities\": []\n}\n```\n\n---\n\n### Success Criteria for This Framework\n\nThis framework is successful when:\n- ✅ Agent requests clarification when confidence < 85%\n- ✅ Ambiguous tasks are caught BEFORE implementation\n- ✅ Rework due to misunderstanding drops to < 10%\n- ✅ Success rate for ambiguous tasks rises from 65% to 90%\n\n**Violation**: Proceeding with implementation when confidence < 85% without requesting clarification.\n\n\n## 📊 CONFIDENCE REPORTING STANDARD (MANDATORY)\n\n**CRITICAL**: When completing tasks and returning work to PM, you MUST report confidence metrics to surface uncertainty early.\n\n### Confidence Reporting Template\n\nWhen returning completed work to PM, ALWAYS include this JSON structure:\n\n```json\n{\n  \"completion_status\": \"completed\" | \"partial\" | \"blocked\",\n  \"confidence_metrics\": {\n    \"initial_confidence\": \"X%\",\n    \"final_confidence\": \"Y%\",\n    \"confidence_change\": \"+/- Z%\",\n    \"clarifications_requested\": N,\n    \"clarifications_received\": M\n  },\n  \"assumptions_made\": [\n    \"Assumption 1 (validated by research/clarification)\",\n    \"Assumption 2 (unvalidated - needs confirmation)\",\n    \"Assumption 3 (validated by codebase analysis)\"\n  ],\n  \"remaining_ambiguities\": [\n    \"Ambiguity 1 - recommendation: [action]\",\n    \"Ambiguity 2 - recommendation: [action]\"\n  ],\n  \"validation_status\": {\n    \"acceptance_criteria_met\": true/false,\n    \"edge_cases_covered\": true/false,\n    \"risks_addressed\": true/false\n  }\n}\n```\n\n---\n\n### Field Definitions\n\n**completion_status**:\n- `\"completed\"`: Task fully complete, all acceptance criteria met\n- `\"partial\"`: Task partially complete, some work remaining\n- `\"blocked\"`: Task blocked, cannot proceed without unblocking\n\n**confidence_metrics.initial_confidence**:\n- Confidence level at task start (0-100%)\n- Based on clarity checklist score\n- Example: \"70%\" means 3.5/5 criteria clear\n\n**confidence_metrics.final_confidence**:\n- Confidence level at task completion (0-100%)\n- Should be 85%+ for completed work\n- If <85%, explain why in remaining_ambiguities\n\n**confidence_metrics.confidence_change**:\n- Change in confidence during task execution\n- Positive: clarity improved during work\n- Negative: ambiguities discovered during work\n- Example: \"+20%\" (improved from 70% to 90%)\n\n**confidence_metrics.clarifications_requested**:\n- Number of clarification requests made during task\n- Each request should reference specific ambiguity\n- Links to clarification comments/tickets\n\n**confidence_metrics.clarifications_received**:\n- Number of clarifications actually received\n- Should match requested if all answered\n- Gap indicates unresolved ambiguities\n\n**assumptions_made**:\n- List of assumptions made during implementation\n- Mark each as validated or unvalidated\n- Validated: confirmed by research, clarification, or codebase\n- Unvalidated: needs user confirmation\n\n**remaining_ambiguities**:\n- List of unresolved ambiguities after work complete\n- Include recommendation for each (research, clarify, defer)\n- Empty list indicates full clarity achieved\n\n**validation_status**:\n- Self-assessment of work completeness\n- Checked against original acceptance criteria\n- Highlights areas needing additional validation\n\n---\n\n### Examples\n\n**Example 1: High Confidence Completion**\n\n```json\n{\n  \"completion_status\": \"completed\",\n  \"confidence_metrics\": {\n    \"initial_confidence\": \"90%\",\n    \"final_confidence\": \"95%\",\n    \"confidence_change\": \"+5%\",\n    \"clarifications_requested\": 0,\n    \"clarifications_received\": 0\n  },\n  \"assumptions_made\": [\n    \"Used JWT for authentication (validated by existing codebase pattern)\",\n    \"Token expiry set to 24 hours (validated by security best practices)\"\n  ],\n  \"remaining_ambiguities\": [],\n  \"validation_status\": {\n    \"acceptance_criteria_met\": true,\n    \"edge_cases_covered\": true,\n    \"risks_addressed\": true\n  }\n}\n```\n\n**Example 2: Completion with Clarifications**\n\n```json\n{\n  \"completion_status\": \"completed\",\n  \"confidence_metrics\": {\n    \"initial_confidence\": \"65%\",\n    \"final_confidence\": \"90%\",\n    \"confidence_change\": \"+25%\",\n    \"clarifications_requested\": 2,\n    \"clarifications_received\": 2\n  },\n  \"assumptions_made\": [\n    \"OAuth2 flow validated by user clarification\",\n    \"Redirect URL format confirmed by user clarification\",\n    \"Session storage using Redis (validated by existing infrastructure)\"\n  ],\n  \"remaining_ambiguities\": [],\n  \"validation_status\": {\n    \"acceptance_criteria_met\": true,\n    \"edge_cases_covered\": true,\n    \"risks_addressed\": true\n  }\n}\n```\n\n**Example 3: Partial Completion with Ambiguities**\n\n```json\n{\n  \"completion_status\": \"partial\",\n  \"confidence_metrics\": {\n    \"initial_confidence\": \"70%\",\n    \"final_confidence\": \"75%\",\n    \"confidence_change\": \"+5%\",\n    \"clarifications_requested\": 1,\n    \"clarifications_received\": 0\n  },\n  \"assumptions_made\": [\n    \"Assumed rate limit of 100 req/min (unvalidated - needs user confirmation)\",\n    \"Assumed per-IP rate limiting (unvalidated - might need per-user)\"\n  ],\n  \"remaining_ambiguities\": [\n    \"Rate limit threshold unclear - recommendation: Request clarification from user\",\n    \"Rate limit scope unclear (IP vs user) - recommendation: Research typical patterns then clarify\"\n  ],\n  \"validation_status\": {\n    \"acceptance_criteria_met\": false,\n    \"edge_cases_covered\": true,\n    \"risks_addressed\": false\n  }\n}\n```\n\n---\n\n### Integration with Clarification Framework\n\n**Workflow**:\n```\nTask Start\n    ↓\nRun Clarity Checklist → Record initial_confidence\n    ↓\nIF confidence < 85% → Request clarifications → Update clarifications_requested\n    ↓\nReceive clarifications → Update clarifications_received\n    ↓\nRe-score confidence → Update final_confidence\n    ↓\nComplete work\n    ↓\nReport confidence metrics with assumptions and ambiguities\n```\n\n---\n\n### Success Criteria\n\nThis confidence reporting standard is successful when:\n- ✅ Every agent completion includes confidence metrics\n- ✅ Initial confidence <85% triggers clarification (from framework)\n- ✅ Final confidence reported for all completed work\n- ✅ Assumptions explicitly documented (validated vs. unvalidated)\n- ✅ Remaining ambiguities surfaced before work considered \"done\"\n- ✅ Low-confidence work doesn't slip through undetected\n\n**Target**: 85% of agent completions include full confidence reporting (up from 60%)\n\n**Violation**: Reporting work as \"completed\" without confidence metrics = incomplete work\n\n\n## Framework Integration\n- **Hierarchy**: Operate within Project → User → System agent discovery\n- **Communication**: Use Task Tool subprocess for PM coordination\n- **Context Awareness**: Acknowledge current date/time in decisions\n- **Handoffs**: Follow structured protocols for inter-agent coordination\n- **Error Handling**: Implement graceful failure with clear error reporting\n\n## Quality Standards\n- Idempotent operations where possible\n- Comprehensive error handling and validation\n- Structured output formats for integration\n- Security-first approach for sensitive operations\n- Performance-conscious implementation choices\n\n## Mandatory PM Reporting\nALL agents MUST report back to the PM upon task completion or when errors occur:\n\n### Required Reporting Elements\n1. **Work Summary**: Brief overview of actions performed and outcomes achieved\n2. **File Tracking**: Comprehensive list of all files:\n   - Created files (with full paths)\n   - Modified files (with nature of changes)\n   - Deleted files (with justification)\n3. **Specific Actions**: Detailed list of all operations performed:\n   - Commands executed\n   - Services accessed\n   - External resources utilized\n4. **Success Status**: Clear indication of task completion:\n   - Successful: All acceptance criteria met\n   - Partial: Some objectives achieved with specific blockers\n   - Failed: Unable to complete with detailed reasons\n5. **Error Escalation**: Any unresolved errors MUST be escalated immediately:\n   - Error description and context\n   - Attempted resolution steps\n   - Required assistance or permissions\n   - Impact on task completion\n\n### Reporting Format\n```\n## Task Completion Report\n**Status**: [Success/Partial/Failed]\n**Summary**: [Brief overview of work performed]\n\n### Files Touched\n- Created: [list with paths]\n- Modified: [list with paths and change types]\n- Deleted: [list with paths and reasons]\n\n### Actions Performed\n- [Specific action 1]\n- [Specific action 2]\n- ...\n\n### Unresolved Issues (if any)\n- **Error**: [description]\n- **Impact**: [how it affects the task]\n- **Assistance Required**: [what help is needed]\n```\n\n## Memory System Integration\n\nWhen you discover important learnings, patterns, or insights during your work that could be valuable for future tasks, use the following format to add them to memory:\n\n```\n# Add To Memory:\nType: <type>\nContent: <your learning here - be specific and concise>\n#\n```\n\n### Memory Types:\n- **pattern**: Recurring code patterns, design patterns, or implementation approaches\n- **architecture**: System architecture insights, component relationships\n- **guideline**: Best practices, coding standards, team conventions\n- **mistake**: Common errors, pitfalls, or anti-patterns to avoid\n- **strategy**: Problem-solving approaches, effective techniques\n- **integration**: API usage, library patterns, service interactions\n- **performance**: Performance insights, optimization opportunities\n- **context**: Project-specific knowledge, business logic, domain concepts\n\n### When to Add to Memory:\n- After discovering a non-obvious pattern in the codebase\n- When you learn something that would help future tasks\n- After resolving a complex issue or bug\n- When you identify a best practice or anti-pattern\n- After understanding important architectural decisions\n\n### Guidelines:\n- Keep content under 100 characters for clarity\n- Be specific rather than generic\n- Focus on project-specific insights\n- Only add truly valuable learnings\n\n### Example:\n```\nI discovered that all API endpoints require JWT tokens.\n\n# Add To Memory:\nType: pattern\nContent: All API endpoints use JWT bearer tokens with 24-hour expiration\n#\n```"
   },
   "configuration_fields": {
-    "model": "sonnet",
+    "__comment_model": "Model field is optional - if not specified, Claude Code will choose based on task complexity",
     "file_access": "project",
     "dangerous_tools": false,
     "review_required": false,

claude_mpm/agents/frontmatter_validator.py

@@ -200,9 +200,9 @@ class FrontmatterValidator:
     ) -> None:
         """Check that all required fields are present."""
         required_fields = (
-            self.schema.get("required", ["name", "description", "version", "model"])
+            self.schema.get("required", ["name", "description", "version"])
             if self.schema
-            else ["name", "description", "version", "model"]
+            else ["name", "description", "version"]
         )
         for field in required_fields:
             if field not in corrected:

claude_mpm/cli/commands/configure_agent_display.py

@@ -83,6 +83,9 @@ class AgentDisplay:
         # Get deployed agent IDs
         deployed_ids = get_deployed_agent_ids()
 
+        # Track installed count for summary
+        installed_count = 0
+
         for idx, agent in enumerate(agents, 1):
             # Check if agent is deployed to .claude/agents/
             # Use agent_id (technical ID) for comparison, not display name
@@ -90,6 +93,10 @@ class AgentDisplay:
             agent_leaf_name = agent_id.split("/")[-1]
             is_deployed = agent_leaf_name in deployed_ids
 
+            # Increment installed count
+            if is_deployed:
+                installed_count += 1
+
             # Show "Installed" for deployed agents, "Available" otherwise
             status = "[green]Installed[/green]" if is_deployed else "Available"
 
@@ -124,6 +131,11 @@ class AgentDisplay:
 
         self.console.print(table)
 
+        # Display summary count
+        self.console.print(
+            f"\n📊 Agents: {installed_count} Installed / {len(agents)} Total"
+        )
+
     def display_agents_with_pending_states(self, agents: List[AgentConfig]) -> None:
         """Display agents table with pending state indicators.
 

claude_mpm/cli/commands/mpm_init/core.py

@@ -203,6 +203,10 @@ class MPMInitCommand:
             if update_mode and result.get("status") == OperationResult.SUCCESS:
                 self._handle_update_post_processing()
 
+            # Deploy PM skills after successful initialization
+            if result.get("status") == OperationResult.SUCCESS:
+                self._deploy_pm_skills()
+
             return result
 
         except Exception as e:
@@ -683,5 +687,73 @@ class MPMInitCommand:
         """
         return len(text) // 4
 
+    def _deploy_pm_skills(self) -> None:
+        """Deploy PM skills templates to project .claude-mpm directory.
+
+        Copies PM skills from bundled templates to .claude-mpm/skills/pm/
+        with version tracking and checksum validation.
+        """
+        try:
+            from rich.progress import (
+                BarColumn,
+                Progress,
+                TaskProgressColumn,
+                TextColumn,
+            )
+
+            from claude_mpm.services.pm_skills_deployer import PMSkillsDeployerService
+
+            deployer = PMSkillsDeployerService()
+
+            # Use progress bar for deployment
+            with Progress(
+                TextColumn("[cyan]Deploying PM skills[/cyan]"),
+                BarColumn(bar_width=30),
+                TaskProgressColumn(),
+                TextColumn("[dim]{task.description}[/dim]"),
+                console=self.console,
+            ) as progress:
+                task = progress.add_task("", total=None)  # Unknown total initially
+
+                def update_progress(skill_name: str, current: int, total: int) -> None:
+                    progress.update(
+                        task, total=total, completed=current, description=skill_name
+                    )
+
+                result = deployer.deploy_pm_skills(
+                    self.project_path, progress_callback=update_progress
+                )
+
+            if result.success:
+                if result.deployed:
+                    self.console.print(
+                        f"[green]✓ Deployed {len(result.deployed)} PM skills[/green]"
+                    )
+
+                if result.skipped:
+                    self.console.print(
+                        f"[dim]  Skipped {len(result.skipped)} (already deployed)[/dim]"
+                    )
+
+                if result.errors:
+                    self.console.print(
+                        f"[yellow]⚠️  {len(result.errors)} errors:[/yellow]"
+                    )
+                    for error in result.errors[:3]:  # Show first 3 errors
+                        self.console.print(f"  • {error['skill']}: {error['error']}")
+            else:
+                self.console.print(
+                    f"[yellow]⚠️  PM skills deployment had errors: {result.message}[/yellow]"
+                )
+
+        except ImportError as e:
+            logger.warning(f"PM skills deployer not available: {e}")
+            self.console.print(
+                "[yellow]⚠️  PM skills deployment skipped (service not available)[/yellow]"
+            )
+        except Exception as e:
+            logger.error(f"Failed to deploy PM skills: {e}")
+            self.console.print(f"[yellow]⚠️  PM skills deployment failed: {e}[/yellow]")
+
 
 __all__ = ["MPMInitCommand"]

claude_mpm/cli/commands/profile.py

@@ -0,0 +1,276 @@
+"""
+Profile management commands for claude-mpm CLI.
+
+WHY: Users need a simple way to manage deployment profiles from the command
+line. Profiles control which agents and skills are deployed, reducing context
+usage by limiting available agents to only what's needed.
+
+DESIGN DECISIONS:
+- Use BaseCommand for consistent CLI patterns
+- Provide clear, actionable output with standardized error handling
+- Support profile listing, activation, and status reporting
+- Integrate with ConfigLoader for profile persistence
+"""
+
+from pathlib import Path
+
+import yaml
+from rich.table import Table
+
+from ...core.shared.config_loader import ConfigLoader
+from ...services.profile_manager import ProfileManager
+from ...utils.console import console
+from ..shared import BaseCommand, CommandResult
+
+
+class ProfileCommand(BaseCommand):
+    """Profile management command for agents and skills filtering."""
+
+    def __init__(self):
+        super().__init__("profile")
+        # ProfileManager will auto-detect project directory
+        self.profile_manager = ProfileManager()
+        self.config_loader = ConfigLoader()
+
+    def validate_args(self, args) -> str:
+        """Validate command arguments."""
+        if not hasattr(args, "profile_command") or not args.profile_command:
+            return "Profile command required. Use: list, set, status, or show"
+
+        valid_commands = ["list", "set", "status", "show"]
+        if args.profile_command not in valid_commands:
+            return (
+                f"Unknown profile command: {args.profile_command}. "
+                f"Valid commands: {', '.join(valid_commands)}"
+            )
+
+        # Validate set command has profile name
+        if args.profile_command == "set":
+            if not hasattr(args, "profile_name") or not args.profile_name:
+                return "Profile name required for 'set' command"
+
+        # Validate show command has profile name
+        if args.profile_command == "show":
+            if not hasattr(args, "profile_name") or not args.profile_name:
+                return "Profile name required for 'show' command"
+
+        return None
+
+    def run(self, args) -> CommandResult:
+        """Execute the profile command."""
+        try:
+            if args.profile_command == "list":
+                return self._list_profiles(args)
+            if args.profile_command == "set":
+                return self._set_profile(args)
+            if args.profile_command == "status":
+                return self._show_status(args)
+            if args.profile_command == "show":
+                return self._show_profile(args)
+            return CommandResult.error_result(
+                f"Unknown profile command: {args.profile_command}"
+            )
+        except Exception as e:
+            return CommandResult.error_result(f"Profile command failed: {e}")
+
+    def _list_profiles(self, args) -> CommandResult:
+        """List all available profiles."""
+        profiles = self.profile_manager.list_available_profiles()
+
+        if not profiles:
+            console.print("[yellow]No profiles found in .claude-mpm/profiles/[/yellow]")
+            return CommandResult.success_result("No profiles available")
+
+        # Load current active profile
+        main_config = self.config_loader.load_main_config()
+        active_profile = main_config.get("active_profile")
+
+        # Create table
+        table = Table(title="Available Deployment Profiles")
+        table.add_column("Profile", style="cyan", no_wrap=True)
+        table.add_column("Description", style="white")
+        table.add_column("Status", style="green")
+
+        for profile_name in profiles:
+            description = self.profile_manager.get_profile_description(profile_name)
+            status = "✓ Active" if profile_name == active_profile else ""
+
+            table.add_row(
+                profile_name, description or "(no description)", status or "-"
+            )
+
+        console.print(table)
+
+        return CommandResult.success_result(
+            f"Found {len(profiles)} profile(s)", {"profiles": profiles}
+        )
+
+    def _set_profile(self, args) -> CommandResult:
+        """Set active profile."""
+        profile_name = args.profile_name
+
+        # Validate profile exists
+        available_profiles = self.profile_manager.list_available_profiles()
+        if profile_name not in available_profiles:
+            return CommandResult.error_result(
+                f"Profile '{profile_name}' not found. "
+                f"Available profiles: {', '.join(available_profiles)}"
+            )
+
+        # Load profile to validate it
+        success = self.profile_manager.load_profile(profile_name)
+        if not success:
+            return CommandResult.error_result(
+                f"Failed to load profile '{profile_name}'"
+            )
+
+        # Update configuration.yaml
+        config_path = Path.cwd() / ".claude-mpm" / "configuration.yaml"
+        if not config_path.exists():
+            # Create configuration.yaml if it doesn't exist
+            config_path.parent.mkdir(parents=True, exist_ok=True)
+            config_data = {"active_profile": profile_name}
+        else:
+            # Load existing configuration
+            with config_path.open("r") as f:
+                config_data = yaml.safe_load(f) or {}
+            config_data["active_profile"] = profile_name
+
+        # Save configuration
+        with config_path.open("w") as f:
+            yaml.safe_dump(config_data, f, default_flow_style=False, sort_keys=False)
+
+        # Show summary
+        summary = self.profile_manager.get_filtering_summary()
+        console.print(
+            f"[green]✓[/green] Active profile set to: [cyan]{profile_name}[/cyan]"
+        )
+        console.print(
+            f"  Agents enabled: [cyan]{summary['enabled_agents_count']}[/cyan]"
+        )
+        console.print(
+            f"  Skills enabled: [cyan]{summary['enabled_skills_count']}[/cyan]"
+        )
+        console.print(
+            f"  Skill patterns disabled: [cyan]{summary['disabled_patterns_count']}[/cyan]"
+        )
+        console.print(
+            "\n[yellow]Note:[/yellow] Restart Claude Code or run [cyan]claude-mpm init[/cyan] "
+            "to apply profile filtering."
+        )
+
+        return CommandResult.success_result(
+            f"Profile '{profile_name}' activated",
+            {"profile": profile_name, "summary": summary},
+        )
+
+    def _show_status(self, args) -> CommandResult:
+        """Show current profile status."""
+        # Load current active profile
+        main_config = self.config_loader.load_main_config()
+        active_profile = main_config.get("active_profile")
+
+        if not active_profile:
+            console.print(
+                "[yellow]No active profile[/yellow] - All agents and skills enabled"
+            )
+            return CommandResult.success_result(
+                "No active profile", {"active_profile": None}
+            )
+
+        # Load profile
+        success = self.profile_manager.load_profile(active_profile)
+        if not success:
+            return CommandResult.error_result(
+                f"Failed to load active profile '{active_profile}'"
+            )
+
+        # Get summary
+        summary = self.profile_manager.get_filtering_summary()
+
+        # Display status
+        console.print(f"[green]Active Profile:[/green] [cyan]{active_profile}[/cyan]")
+        console.print()
+
+        # Agents section
+        console.print("[bold]Agents:[/bold]")
+        console.print(f"  Enabled: [cyan]{summary['enabled_agents_count']}[/cyan]")
+        console.print(f"  Disabled: [cyan]{summary['disabled_agents_count']}[/cyan]")
+
+        # Skills section
+        console.print()
+        console.print("[bold]Skills:[/bold]")
+        console.print(f"  Enabled: [cyan]{summary['enabled_skills_count']}[/cyan]")
+        console.print(
+            f"  Disabled patterns: [cyan]{summary['disabled_patterns_count']}[/cyan]"
+        )
+
+        return CommandResult.success_result(
+            f"Profile '{active_profile}' status",
+            {"active_profile": active_profile, "summary": summary},
+        )
+
+    def _show_profile(self, args) -> CommandResult:
+        """Show detailed profile configuration."""
+        profile_name = args.profile_name
+
+        # Validate profile exists
+        available_profiles = self.profile_manager.list_available_profiles()
+        if profile_name not in available_profiles:
+            return CommandResult.error_result(
+                f"Profile '{profile_name}' not found. "
+                f"Available profiles: {', '.join(available_profiles)}"
+            )
+
+        # Load profile
+        success = self.profile_manager.load_profile(profile_name)
+        if not success:
+            return CommandResult.error_result(
+                f"Failed to load profile '{profile_name}'"
+            )
+
+        # Display profile details
+        console.print(f"[bold]Profile:[/bold] [cyan]{profile_name}[/cyan]")
+        console.print()
+
+        # Show enabled agents
+        enabled_agents = self.profile_manager.get_enabled_agents()
+        if enabled_agents:
+            console.print("[bold]Enabled Agents:[/bold]")
+            for agent in sorted(enabled_agents):
+                console.print(f"  • {agent}")
+            console.print()
+
+        # Show disabled agents
+        disabled_agents = self.profile_manager.get_disabled_agents()
+        if disabled_agents:
+            console.print("[bold]Disabled Agents:[/bold]")
+            for agent in sorted(disabled_agents):
+                console.print(f"  • {agent}")
+            console.print()
+
+        # Show enabled skills
+        enabled_skills = self.profile_manager.get_enabled_skills()
+        if enabled_skills:
+            console.print("[bold]Enabled Skills:[/bold]")
+            for skill in sorted(enabled_skills):
+                console.print(f"  • {skill}")
+            console.print()
+
+        # Show disabled skill patterns
+        disabled_patterns = self.profile_manager.get_disabled_skill_patterns()
+        if disabled_patterns:
+            console.print("[bold]Disabled Skill Patterns:[/bold]")
+            for pattern in disabled_patterns:
+                console.print(f"  • {pattern}")
+
+        return CommandResult.success_result(
+            f"Profile '{profile_name}' details",
+            {
+                "profile": profile_name,
+                "enabled_agents": list(enabled_agents),
+                "disabled_agents": list(disabled_agents),
+                "enabled_skills": list(enabled_skills),
+                "disabled_patterns": disabled_patterns,
+            },
+        )

claude_mpm/cli/commands/skills.py

@@ -537,7 +537,6 @@ class SkillsManagementCommand(BaseCommand):
             toolchain = getattr(args, "toolchain", None)
             categories = getattr(args, "categories", None)
             force = getattr(args, "force", False)
-            all_skills = getattr(args, "all_skills", False)
 
             if collection:
                 console.print(
@@ -548,23 +547,14 @@ class SkillsManagementCommand(BaseCommand):
                     "\n[bold cyan]Deploying skills from default collection...[/bold cyan]\n"
                 )
 
-            # Auto-detect toolchain if not specified and not deploying all
-            if not toolchain and not all_skills:
-                console.print(
-                    "[yellow]No toolchain specified. Use --toolchain to filter by language,[/yellow]"
-                )
-                console.print(
-                    "[yellow]or --all-skills to deploy all available skills (not just agent-referenced).[/yellow]\n"
-                )
-
-            # Selective deployment is enabled by default (deploy only agent-referenced skills)
-            # Use --all-skills to disable selective mode
+            # Selective deployment is ALWAYS enabled (deploy only agent-referenced skills)
+            # This ensures only skills linked to deployed agents are deployed
             result = self.skills_deployer.deploy_skills(
                 collection=collection,
                 toolchain=toolchain,
                 categories=categories,
                 force=force,
-                selective=not all_skills,  # Disable selective mode if --all-skills is set
+                selective=True,  # Always use selective deployment
             )
 
             # Display results
@@ -577,11 +567,7 @@ class SkillsManagementCommand(BaseCommand):
                     f"(out of {total_available} available)[/cyan]"
                 )
                 console.print(
-                    "[dim]Use --all-skills to deploy all available skills[/dim]\n"
-                )
-            else:
-                console.print(
-                    "[cyan]📦 Deploying all available skills (selective mode disabled)[/cyan]\n"
+                    "[dim]Use 'claude-mpm skills configure' to manually select skills[/dim]\n"
                 )
 
             if result["deployed_count"] > 0:
@@ -606,6 +592,16 @@ class SkillsManagementCommand(BaseCommand):
                     console.print(f"  • {error}")
                 console.print()
 
+            # Show cleanup results
+            cleanup = result.get("cleanup", {})
+            if cleanup.get("removed_count", 0) > 0:
+                console.print(
+                    f"[yellow]🧹 Removed {cleanup['removed_count']} orphaned skill(s):[/yellow]"
+                )
+                for skill in cleanup.get("removed_skills", []):
+                    console.print(f"  • {skill}")
+                console.print()
+
             # Show restart instructions
             if result["restart_instructions"]:
                 console.print(

claude_mpm/cli/executor.py

@@ -150,6 +150,16 @@ def execute_command(command: str, args) -> int:
         result = summarize_command(args)
         return result if result is not None else 0
 
+    # Handle profile command with lazy import
+    if command == "profile":
+        # Lazy import to avoid loading unless needed
+        from .commands.profile import ProfileCommand
+
+        cmd = ProfileCommand()
+        result = cmd.run(args)
+        # Convert CommandResult to exit code
+        return result.exit_code if result else 0
+
     # Handle auto-configure command with lazy import
     if command == "auto-configure":
         # Lazy import to avoid loading unless needed

claude_mpm/cli/parsers/base_parser.py

@@ -438,6 +438,13 @@ def create_parser(
     except ImportError:
         pass
 
+    try:
+        from .profile_parser import add_profile_subparser
+
+        add_profile_subparser(subparsers)
+    except ImportError:
+        pass
+
     try:
         from .monitor_parser import add_monitor_subparser