claude-mpm 5.4.55__py3-none-any.whl → 5.6.1__py3-none-any.whl

claude_mpm/skills/bundled/collaboration/git-worktrees.md

@@ -0,0 +1,317 @@
+---
+skill_id: git-worktrees
+skill_version: 1.0.0
+description: Use git worktrees for parallel development on multiple branches simultaneously
+tags: [git, worktrees, parallel-development, productivity]
+related_agents: [version-control, engineer]
+---
+
+# Git Worktrees
+
+## Overview
+
+Git worktrees allow you to have multiple working directories from the same repository, each with a different branch checked out. Work on multiple branches simultaneously without switching.
+
+## When to Use Worktrees
+
+### ✅ Perfect For:
+- Stacked PR development (one worktree per PR)
+- Urgent hotfix while working on feature
+- Parallel development on multiple features
+- Code review in isolation
+- Testing cross-branch interactions
+- Running multiple dev servers simultaneously
+
+### ⚠️ Consider Alternatives When:
+- Limited disk space (worktrees duplicate working directory)
+- Simple branch switching is sufficient
+- Only working on one branch at a time
+
+## Basic Workflow
+
+### Create Worktree
+
+**New Branch:**
+```bash
+# Create worktree with new branch
+git worktree add ../worktrees/feature-auth -b feature/authentication
+
+# Navigate to worktree
+cd ../worktrees/feature-auth
+```
+
+**Existing Branch:**
+```bash
+# Create worktree from existing remote branch
+git worktree add ../worktrees/feature-profile feature/user-profile
+
+# Or from origin
+git worktree add ../worktrees/review origin/feature/pr-to-review
+```
+
+### List Worktrees
+
+```bash
+git worktree list
+
+# Output:
+# /Users/dev/project              abc123 [main]
+# /Users/dev/worktrees/f-auth     def456 [feature/authentication]
+# /Users/dev/worktrees/f-profile  ghi789 [feature/user-profile]
+```
+
+### Remove Worktree
+
+```bash
+# Remove worktree (deletes directory)
+git worktree remove ../worktrees/feature-auth
+
+# Or manually delete directory and prune
+rm -rf ../worktrees/feature-auth
+git worktree prune
+```
+
+## Directory Structure
+
+Recommended layout:
+
+```
+/Users/dev/
+├── my-project/              # Main repository
+│   ├── .git/               # Git database
+│   ├── src/
+│   └── ...
+└── my-project-worktrees/    # All worktrees here
+    ├── feature-auth/       # feature/authentication branch
+    ├── feature-profile/    # feature/user-profile branch
+    ├── hotfix-urgent/      # hotfix/urgent-fix branch
+    └── review-pr-123/      # Reviewing PR #123
+```
+
+## Use Case: Stacked PRs
+
+Perfect for stacked PR workflow - one worktree per PR:
+
+```bash
+# Create worktree for each PR in stack
+git worktree add ../stack/pr-001 -b feature/001-base-auth
+git worktree add ../stack/pr-002 -b feature/002-user-profile
+git worktree add ../stack/pr-003 -b feature/003-admin-panel
+
+# Work in each independently
+cd ../stack/pr-001
+# Implement base auth
+git commit -am "feat: base authentication"
+git push -u origin feature/001-base-auth
+
+cd ../stack/pr-002
+# Already on feature/002-user-profile branch
+# Implement user profile (depends on pr-001)
+git commit -am "feat: user profile with auth"
+git push -u origin feature/002-user-profile
+
+cd ../stack/pr-003
+# Implement admin panel (depends on pr-002)
+git commit -am "feat: admin panel"
+git push -u origin feature/003-admin-panel
+```
+
+## Use Case: Parallel Development
+
+Run multiple dev servers simultaneously:
+
+```bash
+# Terminal 1: Main feature development
+cd /project-worktrees/feature-new-ui
+npm install
+npm run dev  # Server on port 3000
+
+# Terminal 2: Urgent hotfix (different branch)
+cd /project-worktrees/hotfix-critical
+npm install
+npm run dev -- --port 3001  # Server on port 3001
+
+# Both running simultaneously without branch switching
+```
+
+## Use Case: Code Review
+
+Review PRs in isolation:
+
+```bash
+# Create worktree for PR review
+git worktree add ../review/pr-456 origin/feature/user-auth
+
+cd ../review/pr-456
+npm install
+npm test
+npm run dev
+
+# Review code, test functionality
+# When done, remove worktree
+cd /main-project
+git worktree remove ../review/pr-456
+```
+
+## Updating Stacked PRs with Worktrees
+
+When base PR changes, update chain across worktrees:
+
+```bash
+# PR-001 got feedback
+cd /stack/pr-001
+git pull origin feature/001-base-auth
+# Make changes, push
+
+# Update PR-002 (in separate worktree)
+cd /stack/pr-002
+git rebase feature/001-base-auth
+git push --force-with-lease origin feature/002-user-profile
+
+# Update PR-003 (in separate worktree)
+cd /stack/pr-003
+git rebase feature/002-user-profile
+git push --force-with-lease origin feature/003-admin-panel
+```
+
+## Managing Dependencies
+
+### Shared node_modules (Save Disk Space)
+
+**Option 1: Symlink**
+```bash
+cd /worktrees/feature-auth
+ln -s /main-project/node_modules node_modules
+```
+
+**Option 2: Separate Install**
+```bash
+cd /worktrees/feature-auth
+npm install  # Independent node_modules
+```
+
+Trade-off:
+- Symlink: Less disk space, may have version conflicts
+- Separate: More disk space, guaranteed isolation
+
+## Best Practices
+
+### 1. Naming Convention
+```bash
+# Use descriptive, consistent names
+git worktree add ../worktrees/feature-authentication feature/authentication
+git worktree add ../worktrees/hotfix-security hotfix/security-patch
+```
+
+### 2. Location Strategy
+```bash
+# Keep worktrees outside main repo
+/Users/dev/project/              # Main repo (never delete)
+/Users/dev/project-worktrees/    # All worktrees here (safe to delete)
+```
+
+### 3. Cleanup Discipline
+```bash
+# When PR merged, remove worktree immediately
+git worktree remove path/to/worktree
+
+# Periodically check for stale worktrees
+git worktree prune
+
+# Delete merged branches
+git branch -d feature/old-branch
+git push origin --delete feature/old-branch
+```
+
+### 4. One Branch Per Worktree
+```
+❌ WRONG: Switching branches in worktree defeats the purpose
+✅ CORRECT: Each worktree permanently on one branch
+```
+
+## Common Commands
+
+```bash
+# Create worktree with new branch
+git worktree add <path> -b <branch>
+
+# Create worktree from existing branch
+git worktree add <path> <branch>
+
+# List all worktrees
+git worktree list
+
+# Remove worktree
+git worktree remove <path>
+
+# Clean up stale references
+git worktree prune
+
+# Move worktree to different location
+git worktree move <old-path> <new-path>
+```
+
+## Troubleshooting
+
+### Issue: "fatal: '<branch>' is already checked out"
+
+**Cause:** Branch is checked out in another worktree
+
+**Solution:**
+```bash
+# List worktrees to find where branch is checked out
+git worktree list
+
+# Either work in existing worktree or remove it first
+git worktree remove <path-to-old-worktree>
+```
+
+### Issue: Disk space concerns
+
+**Solution:**
+- Use symlinks for node_modules
+- Remove worktrees when PRs merged
+- Run `git worktree prune` regularly
+- Consider using sparse-checkout for large repos
+
+### Issue: IDE confusion with multiple worktrees
+
+**Solution:**
+- Open each worktree as separate workspace
+- Use IDE's multi-window/split-workspace features
+- Name worktrees descriptively for easy identification
+
+## Agent Instructions
+
+When delegating worktree setup to version-control agent:
+
+```
+Task: Create worktrees for stacked PR development
+
+Requirements:
+- Create 3 worktrees in /project-worktrees/
+- Worktree 1: pr-001 with branch feature/001-base-auth
+- Worktree 2: pr-002 with branch feature/002-user-profile
+- Worktree 3: pr-003 with branch feature/003-admin-panel
+
+Commands:
+git worktree add ../project-worktrees/pr-001 -b feature/001-base-auth
+git worktree add ../project-worktrees/pr-002 -b feature/002-user-profile
+git worktree add ../project-worktrees/pr-003 -b feature/003-admin-panel
+
+Verification: git worktree list should show all 3 worktrees
+```
+
+## Benefits
+
+✅ **No Branch Switching:** Work on multiple branches without `git checkout`
+✅ **Parallel Servers:** Run multiple dev environments simultaneously
+✅ **Preserve State:** Build artifacts and node_modules stay per-branch
+✅ **Safer Reviews:** Test PRs without affecting main working directory
+✅ **Faster Context Switch:** Jump between worktrees instead of rebasing
+
+## Related Skills
+
+- `stacked-prs` - Combine worktrees with stacked PR workflow
+- `git-workflow` - General git branching patterns
+- `code-review` - Review code in isolated worktrees

claude_mpm/skills/bundled/collaboration/requesting-code-review/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: Requesting Code Review
+description: Dispatch code-reviewer subagent to review implementation against plan or requirements before proceeding
+when_to_use: when completing tasks, implementing major features, or before merging, to verify work meets requirements
+version: 1.2.0
+progressive_disclosure:
+  level: 1
+  references:
+    - path: references/code-reviewer-template.md
+      title: Code Reviewer Template
+      description: Complete subagent template with placeholders and review checklist
+    - path: references/review-examples.md
+      title: Review Examples & Workflows
+      description: Good vs bad reviews, severity guidelines, complete workflow examples
+---
+
+# Requesting Code Review
+
+Dispatch code-reviewer subagent to catch issues before they cascade.
+
+**Core principle:** Review early, review often.
+
+## When to Request Review
+
+**Mandatory:**
+- After each task in subagent-driven development
+- After completing major feature
+- Before merge to main
+
+**Optional but valuable:**
+- When stuck (fresh perspective)
+- Before refactoring (baseline check)
+- After fixing complex bug
+
+## Quick Start
+
+**1. Get git SHAs:**
+```bash
+BASE_SHA=$(git rev-parse HEAD~1)  # or origin/main
+HEAD_SHA=$(git rev-parse HEAD)
+```
+
+**2. Dispatch code-reviewer subagent:**
+
+Use Task tool with code-reviewer type, fill template at [Code Reviewer Template](references/code-reviewer-template.md)
+
+**Required placeholders:**
+- `{WHAT_WAS_IMPLEMENTED}` - What you just built
+- `{PLAN_OR_REQUIREMENTS}` - What it should do
+- `{BASE_SHA}` - Starting commit
+- `{HEAD_SHA}` - Ending commit
+- `{DESCRIPTION}` - Brief summary
+
+**3. Act on feedback:**
+
+| Severity | Action |
+|----------|--------|
+| **Critical** | Fix immediately, don't proceed |
+| **Important** | Fix before next major task |
+| **Minor** | Note for later, can proceed |
+
+See [severity guidelines](references/review-examples.md#severity-guidelines) for details.
+
+## Integration with Workflows
+
+**Subagent-Driven Development:**
+- Review after EACH task
+- Catch issues before they compound
+- Fix before moving to next task
+
+**Executing Plans:**
+- Review after each batch (3 tasks)
+- Get feedback, apply, continue
+
+**Ad-Hoc Development:**
+- Review before merge
+- Review when stuck
+
+## Pushing Back on Reviews
+
+**If reviewer wrong:**
+- Push back with technical reasoning
+- Show code/tests that prove it works
+- Reference plan requirements
+- Request clarification
+
+See [pushing back examples](references/review-examples.md#pushing-back-on-reviews)
+
+## Common Mistakes
+
+**Never:**
+- Skip review because "it's simple"
+- Ignore Critical issues
+- Proceed with unfixed Important issues
+- Argue without technical justification
+
+**Always:**
+- Provide full context in review request
+- Fix Critical issues immediately
+- Document why you disagree (if you do)
+- Re-review after fixing Critical issues
+
+## Examples
+
+**Need examples?** See [Review Examples & Workflows](references/review-examples.md) for:
+- Complete review output examples
+- Good vs bad review requests
+- Review workflows for different scenarios
+- How to act on different severity levels
+- When and how to push back
+
+**Need template?** See [Code Reviewer Template](references/code-reviewer-template.md) for the complete subagent dispatch template.

claude_mpm/skills/bundled/collaboration/requesting-code-review/references/code-reviewer-template.md

@@ -0,0 +1,146 @@
+# Code Review Agent
+
+You are reviewing code changes for production readiness.
+
+**Your task:**
+1. Review {WHAT_WAS_IMPLEMENTED}
+2. Compare against {PLAN_OR_REQUIREMENTS}
+3. Check code quality, architecture, testing
+4. Categorize issues by severity
+5. Assess production readiness
+
+## What Was Implemented
+
+{DESCRIPTION}
+
+## Requirements/Plan
+
+{PLAN_REFERENCE}
+
+## Git Range to Review
+
+**Base:** {BASE_SHA}
+**Head:** {HEAD_SHA}
+
+```bash
+git diff --stat {BASE_SHA}..{HEAD_SHA}
+git diff {BASE_SHA}..{HEAD_SHA}
+```
+
+## Review Checklist
+
+**Code Quality:**
+- Clean separation of concerns?
+- Proper error handling?
+- Type safety (if applicable)?
+- DRY principle followed?
+- Edge cases handled?
+
+**Architecture:**
+- Sound design decisions?
+- Scalability considerations?
+- Performance implications?
+- Security concerns?
+
+**Testing:**
+- Tests actually test logic (not mocks)?
+- Edge cases covered?
+- Integration tests where needed?
+- All tests passing?
+
+**Requirements:**
+- All plan requirements met?
+- Implementation matches spec?
+- No scope creep?
+- Breaking changes documented?
+
+**Production Readiness:**
+- Migration strategy (if schema changes)?
+- Backward compatibility considered?
+- Documentation complete?
+- No obvious bugs?
+
+## Output Format
+
+### Strengths
+[What's well done? Be specific.]
+
+### Issues
+
+#### Critical (Must Fix)
+[Bugs, security issues, data loss risks, broken functionality]
+
+#### Important (Should Fix)
+[Architecture problems, missing features, poor error handling, test gaps]
+
+#### Minor (Nice to Have)
+[Code style, optimization opportunities, documentation improvements]
+
+**For each issue:**
+- File:line reference
+- What's wrong
+- Why it matters
+- How to fix (if not obvious)
+
+### Recommendations
+[Improvements for code quality, architecture, or process]
+
+### Assessment
+
+**Ready to merge?** [Yes/No/With fixes]
+
+**Reasoning:** [Technical assessment in 1-2 sentences]
+
+## Critical Rules
+
+**DO:**
+- Categorize by actual severity (not everything is Critical)
+- Be specific (file:line, not vague)
+- Explain WHY issues matter
+- Acknowledge strengths
+- Give clear verdict
+
+**DON'T:**
+- Say "looks good" without checking
+- Mark nitpicks as Critical
+- Give feedback on code you didn't review
+- Be vague ("improve error handling")
+- Avoid giving a clear verdict
+
+## Example Output
+
+```
+### Strengths
+- Clean database schema with proper migrations (db.ts:15-42)
+- Comprehensive test coverage (18 tests, all edge cases)
+- Good error handling with fallbacks (summarizer.ts:85-92)
+
+### Issues
+
+#### Important
+1. **Missing help text in CLI wrapper**
+   - File: index-conversations:1-31
+   - Issue: No --help flag, users won't discover --concurrency
+   - Fix: Add --help case with usage examples
+
+2. **Date validation missing**
+   - File: search.ts:25-27
+   - Issue: Invalid dates silently return no results
+   - Fix: Validate ISO format, throw error with example
+
+#### Minor
+1. **Progress indicators**
+   - File: indexer.ts:130
+   - Issue: No "X of Y" counter for long operations
+   - Impact: Users don't know how long to wait
+
+### Recommendations
+- Add progress reporting for user experience
+- Consider config file for excluded projects (portability)
+
+### Assessment
+
+**Ready to merge: With fixes**
+
+**Reasoning:** Core implementation is solid with good architecture and tests. Important issues (help text, date validation) are easily fixed and don't affect core functionality.
+```