feat: Add /parallel-work command for multi-PR development

[evansenter]

Summary

• Add new /parallel-work command with start, list, cleanup subcommands for managing git worktrees
• Enable multiple Claude sessions to work on different features simultaneously with context handoff
• Enhance /status-report to show active worktrees with PR/CI status and stacked PR detection

Changes

New command: /parallel-work

• start <branch> [base] - Create worktree, gather context from conversation, write .parallel-context.md for new session
• list - Show all worktrees with branch, PR#, CI status, dirty/clean state
• cleanup - Remove worktrees for merged/closed PRs with category-based confirmation

Enhanced /status-report

• Added "Active Worktrees" section showing worktree status table
• Added "Stacked PRs" detection for PRs targeting non-main branches
• Added worktree-related recommendations (dirty, failed CI, orphaned)

Other changes

• .gitignore - Added .worktrees/ and .parallel-context.md
• CLAUDE.md - Documented new command

Related

• Issue Enhancement: Tmux integration for /parallel-work #37: Future tmux integration enhancement

Test plan

• Run /parallel-work start test-branch and verify worktree creation
• Run /parallel-work list and verify table output
• Run /parallel-work cleanup with mixed worktree states
• Run /status-report and verify worktree section appears
• Run ./bootstrap.sh -f to sync changes

🤖 Generated with Claude Code

[claude]

PR Review: /parallel-work Command for Multi-PR Development

This is a well-designed feature that adds sophisticated git worktree management to Claude Code. The implementation is thorough and follows the repository's conventions. Here's my detailed feedback:

---

✅ Strengths

1. Excellent Documentation: The command file is extremely comprehensive with clear usage examples, step-by-step instructions, and helpful user-facing output templates.

2. Smart Context Handoff: The "Context from Parent Session" feature (step 4 in start) is innovative - extracting decisions, constraints, and code locations from the current conversation to pass to the new session.

3. Safety First: The cleanup command has good safety measures:

   • Categorizes worktrees before deletion
   • Only asks confirmation for non-empty categories
   • Uses git branch -d (not -D) to prevent deleting unmerged work
   • Tracks and reports whether branch deletion succeeded

4. Good UX: Integration with /status-report provides visibility into all active work, and the table-based output is clean and actionable.

5. Follows Conventions: Adheres to the command file format from CLAUDE.md with proper frontmatter, argument hints, and structured instructions.

---

🐛 Potential Issues

1. Race Condition in Worktree Creation (parallel-work.md:66-81)

The check for existing worktrees uses ls before git worktree add, but doesn't verify the branch name conflicts. If a branch already exists in the repo, git worktree add -b will fail.

Recommendation: Check for existing branch first with git show-ref --verify before creating the worktree.

2. Hardcoded Main Branch Detection (status-report.md:87)

The instructions mention checking for main/master, but the actual check logic isn't fully specified. Different repos may use main, master, develop, or custom default branches.

Recommendation: Use git rev-parse --abbrev-ref origin/HEAD or gh repo view --json defaultBranchRef to dynamically determine the default branch.

3. Incomplete Error Handling for git worktree add (parallel-work.md:78-81)

The git fetch origin "$BASE_BRANCH" might fail if the base branch doesn't exist, network is unavailable, or the remote is not named origin.

Recommendation: Add error handling with fallback to local branch refs.

4. Context File Date Command Syntax (parallel-work.md:145)

The template literally includes $(date ...). The instructions should clarify that Claude should execute this command when writing the file, not include it as literal text.

5. Missing Dirty Check Before Cleanup (parallel-work.md:289-290)

The cleanup command checks for uncommitted changes but the actual removal uses git worktree remove --force, which will delete even if dirty.

Recommendation: Either refuse to delete dirty worktrees, add an additional confirmation, or document that --force will delete uncommitted work.

6. Potential PR Listing Performance Issue (parallel-work.md:203, 277)

For repos with many open PRs, fetching all PR data could be slow.

Recommendation: Consider adding --limit flag for large repos.

---

🔒 Security Considerations

1. Path Injection Risk (LOW severity)

User-provided $BRANCH_NAME is used directly in file paths. While git branch names have restrictions, malicious input like ../../etc/passwd could theoretically cause issues.

Recommendation: Validate branch name format with regex.

2. Command Injection in git -C (LOW severity)

Paths are properly quoted in the instructions, which is good. Just emphasizing this should be maintained.

---

⚡ Performance Considerations

1. Parallel Command Execution: The list command correctly suggests running multiple git commands in parallel. Good optimization!

2. Git Worktree List Parsing: Using git worktree list --porcelain is the right approach for machine parsing.

3. CI Status Fetching: Fetching statusCheckRollup for all open PRs might be slow for repos with many PRs.

---

📝 Code Quality & Best Practices

✅ Well Done:

• Clear separation of concerns
• Consistent markdown formatting
• Helpful legends and quick action sections
• Good use of AskUserQuestion for confirmations
• Proper gitignore entries

🔧 Minor Improvements:

1. Missing Edge Case: What happens if .worktrees/ exists but isn't tracked by git?

2. Inconsistent PR State Display: The "Open" in the PR column is redundant since cleanup already filters out merged/closed.

3. Missing Recommendation: Consider adding to CLAUDE.md about when to use /parallel-work vs. regular branching.

---

🧪 Test Coverage

The test plan in the PR body is good, but consider adding:

• Test with non-main base branches
• Test behavior when .worktrees/ contains non-git directories
• Test with branch names containing special characters
• Test running /parallel-work from within a worktree
• Test cleanup with dirty worktrees

---

💡 Enhancement Suggestions (Future Work)

1. Worktree Status in PS1: Show "(worktree: branch-name)" in prompt
2. Auto-cleanup on PR Merge: Git hook or GitHub Action
3. Worktree Naming Convention: Auto-generate names
4. Context File Templates: Custom templates in ~/.claude/templates/
5. Integration with tmux: Per issue Enhancement: Tmux integration for /parallel-work #37

---

📊 Final Assessment

Overall: This is production-ready code with excellent documentation. The issues I've identified are mostly edge cases and defensive improvements.

Recommendation: ✅ Approve with minor suggestions

Priority Fixes:

1. 🔴 Add branch existence check before worktree creation
2. 🟡 Clarify behavior of force removal in cleanup
3. 🟡 Add error handling for git fetch failures

Nice-to-haves:

• Dynamic default branch detection
• Branch name validation
• Performance optimizations for large repos

Great work on this feature! 🚀

[claude]

PR Review: /parallel-work Command for Multi-PR Development

This is an excellent addition to the dotfiles that enables sophisticated parallel workflow management. The implementation is well-designed and thoughtfully integrates with existing commands. Here's my detailed feedback:

✅ Strengths

1. Excellent Design

• Clean subcommand architecture (start, list, cleanup) follows Unix philosophy
• Context handoff mechanism is innovative - passing conversation state between Claude sessions is a powerful workflow enhancement
• Graceful degradation strategy (safe defaults, confirmation prompts) prevents data loss

2. Strong Integration

• Seamlessly integrates with existing /status-report command
• Properly updates .gitignore to prevent tracking temporary files
• Follows repository conventions (command file format, bash snippets, detailed instructions)

3. User Safety

• Multiple safety checks: branch existence, dirty worktree warnings, explicit confirmations for destructive actions
• Category-based cleanup with clear warnings for uncommitted changes
• Idempotent operations (worktree creation checks)

4. Documentation Quality

• Comprehensive inline documentation in command file
• Clear usage examples and output format specifications
• Updated CLAUDE.md with command listing

🔍 Code Quality Observations

1. Hardcoded Default Branch (parallel-work.md:54)

Issue: Hardcodes 'main' as default branch with BASE_BRANCH parameter defaulting to main, but repository could use master, develop, etc.

Recommendation: Use dynamic detection like /status-report does with gh repo view to get defaultBranchRef, or fall back to git rev-parse --abbrev-ref origin/HEAD

2. Context Extraction Logic (parallel-work.md:88-97)

The instruction to analyze the current conversation is clever but relies on Claude's conversation memory. This could be fragile if conversation is very long, session is resumed after interruption, or multiple context switches have occurred.

Suggestion: Consider adding explicit user confirmation to review extracted context before writing to file.

3. Error Handling

The commands generally assume success. Consider edge cases:

• git fetch origin BASE_BRANCH - What if remote branch doesn't exist?
• git worktree add - What if disk space is full or permissions denied?
• git worktree remove --force - The --force flag bypasses safety checks

Recommendation: Add error handling instructions to check command exit codes and provide helpful error messages.

4. CI Status Parsing (parallel-work.md:230)

The statusCheckRollup structure can be complex. Consider edge cases: no CI configured, multiple check suites with different statuses, pending checks vs waiting for approval.

Suggestion: Add explicit parsing logic in instructions for handling null/empty CI status.

🐛 Potential Bugs

1. Race Condition in cleanup (parallel-work.md:278-281)

If worktree is removed between ls and status check, command could fail. Use -e checks for existence before operations.

2. Worktree Detection Logic (status-report.md:52-55)

Comparing pwd to paths may fail if symlinks are involved, path is relative vs absolute, or user has cd'd to subdirectory within worktree.

Fix: Use git rev-parse --show-toplevel for absolute worktree root comparison.

📊 Performance Considerations

1. Sequential Git Operations (parallel-work.md:215-223)

For many worktrees, sequential git -C calls could be slow. Since these are independent, suggest running in parallel using background jobs or xargs.

2. API Rate Limiting

Multiple gh pr list calls in cleanup could hit rate limits with many worktrees. Consider batching: get all PRs once with state=all, then filter in memory.

🔒 Security Concerns

1. Branch Name Injection

User-provided BRANCH_NAME is used in paths and git commands. Malicious names with .. could escape .worktrees/ directory, or special chars could break scripts.

Recommendation: Add validation to reject branch names with dangerous characters - only allow alphanumeric, dash, underscore, and forward slash.

2. Context File Contains User Data (parallel-work.md:140-166)

.parallel-context.md may contain sensitive information from conversation. Already in .gitignore, but consider warning users not to commit it or adding to .git/info/exclude automatically.

✨ Enhancement Opportunities

1. Workspace Validation

Add health check for worktrees to detect orphaned entries where path no longer exists or is not a valid git repo.

2. Interactive Mode for start

For users who prefer interactive prompts over positional args, add --interactive flag.

3. Template Support

Allow users to customize .parallel-context.md template by checking for ~/.claude/templates/parallel-context.md

🧪 Test Coverage

The test plan in PR description is good, but consider edge cases:

Additional test scenarios:

• Start worktree when base branch doesn't exist remotely
• Cleanup when .worktrees/ contains non-git directories
• List when a worktree path no longer exists (orphaned entry)
• Start with branch name containing special characters
• Cleanup with no internet connection (gh commands fail)
• Run from within a worktree (nested operations)

📝 Documentation Suggestions

1. Add Troubleshooting Section

Add section covering common issues like worktree already exists, permission denied, and how to clean up orphaned worktrees with git worktree prune.

2. Add Examples to CLAUDE.md

Show common workflows with concrete examples of starting work on new feature, reviewing all active work, and cleaning up after merging PRs.

🎯 Final Recommendations

Priority fixes:

1. High: Add dynamic default branch detection (parallel-work.md:54)
2. High: Add branch name validation for security
3. Medium: Improve error handling for git operations
4. Medium: Add worktree path validation in detection logic
5. Low: Consider batching API calls for performance

Overall Assessment:

This is a high-quality, production-ready feature. The command is well-designed, safe by default, and fills a real workflow need. With the suggested fixes (particularly dynamic branch detection and input validation), this will be an excellent addition to the dotfiles.

The integration with /status-report is particularly clever - it creates a cohesive workflow management system. Great work on the comprehensive documentation and user safety measures.

Verdict: ✅ Approve with minor suggestions

---

Review conducted following repository CLAUDE.md guidelines