claude-mpm 4.20.3__py3-none-any.whl → 4.25.10__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

@@ -2,7 +2,16 @@
 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.1.0
+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
@@ -23,7 +32,7 @@ Dispatch code-reviewer subagent to catch issues before they cascade.
 - Before refactoring (baseline check)
 - After fixing complex bug
 
-## How to Request
+## Quick Start
 
 **1. Get git SHAs:**
 ```bash
@@ -33,9 +42,9 @@ HEAD_SHA=$(git rev-parse HEAD)
 
 **2. Dispatch code-reviewer subagent:**
 
-Use Task tool with code-reviewer type, fill template at `code-reviewer.md`
+Use Task tool with code-reviewer type, fill template at [Code Reviewer Template](references/code-reviewer-template.md)
 
-**Placeholders:**
+**Required placeholders:**
 - `{WHAT_WAS_IMPLEMENTED}` - What you just built
 - `{PLAN_OR_REQUIREMENTS}` - What it should do
 - `{BASE_SHA}` - Starting commit
@@ -43,38 +52,14 @@ Use Task tool with code-reviewer type, fill template at `code-reviewer.md`
 - `{DESCRIPTION}` - Brief summary
 
 **3. Act on feedback:**
-- Fix Critical issues immediately
-- Fix Important issues before proceeding
-- Note Minor issues for later
-- Push back if reviewer is wrong (with reasoning)
-
-## Example
-
-```
-[Just completed Task 2: Add verification function]
 
-You: Let me request code review before proceeding.
+| Severity | Action |
+|----------|--------|
+| **Critical** | Fix immediately, don't proceed |
+| **Important** | Fix before next major task |
+| **Minor** | Note for later, can proceed |
 
-BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')
-HEAD_SHA=$(git rev-parse HEAD)
-
-[Dispatch code-reviewer subagent]
-  WHAT_WAS_IMPLEMENTED: Verification and repair functions for conversation index
-  PLAN_OR_REQUIREMENTS: Task 2 from docs/plans/deployment-plan.md
-  BASE_SHA: a7981ec
-  HEAD_SHA: 3df7661
-  DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types
-
-[Subagent returns]:
-  Strengths: Clean architecture, real tests
-  Issues:
-    Important: Missing progress indicators
-    Minor: Magic number (100) for reporting interval
-  Assessment: Ready to proceed
-
-You: [Fix progress indicators]
-[Continue to Task 3]
-```
+See [severity guidelines](references/review-examples.md#severity-guidelines) for details.
 
 ## Integration with Workflows
 
@@ -91,17 +76,37 @@ You: [Fix progress indicators]
 - Review before merge
 - Review when stuck
 
-## Red Flags
+## 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 with valid technical feedback
+- Argue without technical justification
 
-**If reviewer wrong:**
-- Push back with technical reasoning
-- Show code/tests that prove it works
-- Request clarification
+**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
 
-See template at: skills/collaboration/requesting-code-review/code-reviewer.md
+**Need template?** See [Code Reviewer Template](references/code-reviewer-template.md) for the complete subagent dispatch template.