feat(plugin): reorganize compounding-engineering v2.0.0
Major restructure of the compounding-engineering plugin: ## Agents (24 total, now categorized) - review/ (10): architecture-strategist, code-simplicity-reviewer, data-integrity-guardian, dhh-rails-reviewer, kieran-rails-reviewer, kieran-python-reviewer, kieran-typescript-reviewer, pattern-recognition-specialist, performance-oracle, security-sentinel - research/ (4): best-practices-researcher, framework-docs-researcher, git-history-analyzer, repo-research-analyst - design/ (3): design-implementation-reviewer, design-iterator, figma-design-sync - workflow/ (6): bug-reproduction-validator, every-style-editor, feedback-codifier, lint, pr-comment-resolver, spec-flow-analyzer - docs/ (1): ankane-readme-writer ## Commands (15 total) - Moved workflow commands to commands/workflows/ subdirectory - Added: changelog, create-agent-skill, heal-skill, plan_review, prime, reproduce-bug, resolve_parallel, resolve_pr_parallel ## Skills (11 total) - Added: andrew-kane-gem-writer, codify-docs, create-agent-skills, dhh-ruby-style, dspy-ruby, every-style-editor, file-todos, frontend-design, git-worktree, skill-creator - Kept: gemini-imagegen 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Kieran Klaassen
272
plugins/compounding-engineering/skills/git-worktree/SKILL.md
Normal file
272
plugins/compounding-engineering/skills/git-worktree/SKILL.md
Normal file
@@ -0,0 +1,272 @@
|
||||
---
|
||||
name: git-worktree
|
||||
description: This skill manages Git worktrees for isolated parallel development. It handles creating, listing, switching, and cleaning up worktrees with a simple interactive interface, following KISS principles.
|
||||
---
|
||||
|
||||
# Git Worktree Manager
|
||||
|
||||
This skill provides a unified interface for managing Git worktrees across your development workflow. Whether you're reviewing PRs in isolation or working on features in parallel, this skill handles all the complexity.
|
||||
|
||||
## What This Skill Does
|
||||
|
||||
- **Create worktrees** from main branch with clear branch names
|
||||
- **List worktrees** with current status
|
||||
- **Switch between worktrees** for parallel work
|
||||
- **Clean up completed worktrees** automatically
|
||||
- **Interactive confirmations** at each step
|
||||
- **Automatic .gitignore management** for worktree directory
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Use this skill in these scenarios:
|
||||
|
||||
1. **Code Review (`/workflows:review`)**: If NOT already on the PR branch, offer worktree for isolated review
|
||||
2. **Feature Work (`/workflows:work`)**: Always ask if user wants parallel worktree or live branch work
|
||||
3. **Parallel Development**: When working on multiple features simultaneously
|
||||
4. **Cleanup**: After completing work in a worktree
|
||||
|
||||
## How to Use
|
||||
|
||||
### In Claude Code Workflows
|
||||
|
||||
The skill is automatically called from `/workflows:review` and `/workflows:work` commands:
|
||||
|
||||
```
|
||||
# For review: offers worktree if not on PR branch
|
||||
# For work: always asks - new branch or worktree?
|
||||
```
|
||||
|
||||
### Manual Usage
|
||||
|
||||
You can also invoke the skill directly from bash:
|
||||
|
||||
```bash
|
||||
# Create a new worktree
|
||||
bash .claude/skills/git-worktree/scripts/worktree-manager.sh create feature-login
|
||||
|
||||
# List all worktrees
|
||||
bash .claude/skills/git-worktree/scripts/worktree-manager.sh list
|
||||
|
||||
# Switch to a worktree
|
||||
bash .claude/skills/git-worktree/scripts/worktree-manager.sh switch feature-login
|
||||
|
||||
# Clean up completed worktrees
|
||||
bash .claude/skills/git-worktree/scripts/worktree-manager.sh cleanup
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
### `create <branch-name> [from-branch]`
|
||||
|
||||
Creates a new worktree with the given branch name.
|
||||
|
||||
**Options:**
|
||||
- `branch-name` (required): The name for the new branch and worktree
|
||||
- `from-branch` (optional): Base branch to create from (defaults to `main`)
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
bash .claude/skills/git-worktree/scripts/worktree-manager.sh create feature-login
|
||||
```
|
||||
|
||||
**What happens:**
|
||||
1. Checks if worktree already exists
|
||||
2. Updates the base branch from remote
|
||||
3. Creates new worktree and branch
|
||||
4. Shows path for cd-ing to the worktree
|
||||
|
||||
### `list` or `ls`
|
||||
|
||||
Lists all available worktrees with their branches and current status.
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
bash .claude/skills/git-worktree/scripts/worktree-manager.sh list
|
||||
```
|
||||
|
||||
**Output shows:**
|
||||
- Worktree name
|
||||
- Branch name
|
||||
- Which is current (marked with ✓)
|
||||
- Main repo status
|
||||
|
||||
### `switch <name>` or `go <name>`
|
||||
|
||||
Switches to an existing worktree and cd's into it.
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
bash .claude/skills/git-worktree/scripts/worktree-manager.sh switch feature-login
|
||||
```
|
||||
|
||||
**Optional:**
|
||||
- If name not provided, lists available worktrees and prompts for selection
|
||||
|
||||
### `cleanup` or `clean`
|
||||
|
||||
Interactively cleans up inactive worktrees with confirmation.
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
bash .claude/skills/git-worktree/scripts/worktree-manager.sh cleanup
|
||||
```
|
||||
|
||||
**What happens:**
|
||||
1. Lists all inactive worktrees
|
||||
2. Asks for confirmation
|
||||
3. Removes selected worktrees
|
||||
4. Cleans up empty directories
|
||||
|
||||
## Workflow Examples
|
||||
|
||||
### Code Review with Worktree
|
||||
|
||||
```bash
|
||||
# Claude Code recognizes you're not on the PR branch
|
||||
# Offers: "Use worktree for isolated review? (y/n)"
|
||||
|
||||
# You respond: yes
|
||||
# Script runs:
|
||||
bash .claude/skills/git-worktree/scripts/worktree-manager.sh create pr-123-feature-name
|
||||
|
||||
# You're now in isolated worktree for review
|
||||
cd .worktrees/pr-123-feature-name
|
||||
|
||||
# After review, return to main:
|
||||
cd ../..
|
||||
bash .claude/skills/git-worktree/scripts/worktree-manager.sh cleanup
|
||||
```
|
||||
|
||||
### Parallel Feature Development
|
||||
|
||||
```bash
|
||||
# For first feature:
|
||||
bash .claude/skills/git-worktree/scripts/worktree-manager.sh create feature-login
|
||||
|
||||
# Later, start second feature:
|
||||
bash .claude/skills/git-worktree/scripts/worktree-manager.sh create feature-notifications
|
||||
|
||||
# List what you have:
|
||||
bash .claude/skills/git-worktree/scripts/worktree-manager.sh list
|
||||
|
||||
# Switch between them as needed:
|
||||
bash .claude/skills/git-worktree/scripts/worktree-manager.sh switch feature-login
|
||||
|
||||
# Return to main and cleanup when done:
|
||||
cd .
|
||||
bash .claude/skills/git-worktree/scripts/worktree-manager.sh cleanup
|
||||
```
|
||||
|
||||
## Key Design Principles
|
||||
|
||||
### KISS (Keep It Simple, Stupid)
|
||||
|
||||
- **One manager script** handles all worktree operations
|
||||
- **Simple commands** with sensible defaults
|
||||
- **Interactive prompts** prevent accidental operations
|
||||
- **Clear naming** using branch names directly
|
||||
|
||||
### Opinionated Defaults
|
||||
|
||||
- Worktrees always created from **main** (unless specified)
|
||||
- Worktrees stored in **.worktrees/** directory
|
||||
- Branch name becomes worktree name
|
||||
- **.gitignore** automatically managed
|
||||
|
||||
### Safety First
|
||||
|
||||
- **Confirms before creating** worktrees
|
||||
- **Confirms before cleanup** to prevent accidental removal
|
||||
- **Won't remove current worktree**
|
||||
- **Clear error messages** for issues
|
||||
|
||||
## Integration with Workflows
|
||||
|
||||
### `/workflows:review`
|
||||
|
||||
Instead of always creating a worktree:
|
||||
|
||||
```
|
||||
1. Check current branch
|
||||
2. If ALREADY on PR branch → stay there, no worktree needed
|
||||
3. If DIFFERENT branch → offer worktree:
|
||||
"Use worktree for isolated review? (y/n)"
|
||||
- yes → call git-worktree skill
|
||||
- no → proceed with PR diff on current branch
|
||||
```
|
||||
|
||||
### `/workflows:work`
|
||||
|
||||
Always offer choice:
|
||||
|
||||
```
|
||||
1. Ask: "How do you want to work?
|
||||
1. New branch on current worktree (live work)
|
||||
2. Worktree (parallel work)"
|
||||
|
||||
2. If choice 1 → create new branch normally
|
||||
3. If choice 2 → call git-worktree skill to create from main
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Worktree already exists"
|
||||
|
||||
If you see this, the script will ask if you want to switch to it instead.
|
||||
|
||||
### "Cannot remove worktree: it is the current worktree"
|
||||
|
||||
Switch out of the worktree first, then cleanup:
|
||||
|
||||
```bash
|
||||
cd /Users/kieranklaassen/rails/cora
|
||||
bash .claude/skills/git-worktree/scripts/worktree-manager.sh cleanup
|
||||
```
|
||||
|
||||
### Lost in a worktree?
|
||||
|
||||
See where you are:
|
||||
|
||||
```bash
|
||||
bash .claude/skills/git-worktree/scripts/worktree-manager.sh list
|
||||
```
|
||||
|
||||
Navigate back to main:
|
||||
|
||||
```bash
|
||||
cd $(git rev-parse --show-toplevel)
|
||||
```
|
||||
|
||||
## Technical Details
|
||||
|
||||
### Directory Structure
|
||||
|
||||
```
|
||||
.worktrees/
|
||||
├── feature-login/ # Worktree 1
|
||||
│ ├── .git
|
||||
│ ├── app/
|
||||
│ └── ...
|
||||
├── feature-notifications/ # Worktree 2
|
||||
│ ├── .git
|
||||
│ ├── app/
|
||||
│ └── ...
|
||||
└── ...
|
||||
|
||||
.gitignore (updated to include .worktrees)
|
||||
```
|
||||
|
||||
### How It Works
|
||||
|
||||
- Uses `git worktree add` for isolated environments
|
||||
- Each worktree has its own branch
|
||||
- Changes in one worktree don't affect others
|
||||
- Share git history with main repo
|
||||
- Can push from any worktree
|
||||
|
||||
### Performance
|
||||
|
||||
- Worktrees are lightweight (just file system links)
|
||||
- No repository duplication
|
||||
- Shared git objects for efficiency
|
||||
- Much faster than cloning or stashing/switching
|
||||
Reference in New Issue
Block a user