chore: move agents and skills to old2 folder
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
229
old2/skills/worktrees/SKILL.md
Normal file
229
old2/skills/worktrees/SKILL.md
Normal file
@@ -0,0 +1,229 @@
|
||||
---
|
||||
name: worktrees
|
||||
description: >
|
||||
Git worktree patterns for parallel development workflows. Use when managing
|
||||
multiple concurrent branches, implementing issues in parallel, or isolating
|
||||
work contexts.
|
||||
user-invocable: false
|
||||
---
|
||||
|
||||
# Git Worktrees
|
||||
|
||||
Patterns and scripts for managing git worktrees in parallel development workflows.
|
||||
|
||||
## What are Worktrees?
|
||||
|
||||
Git worktrees allow multiple working directories from a single repository. Each worktree can have a different branch checked out, enabling true parallel development.
|
||||
|
||||
**Use cases:**
|
||||
- Implementing multiple issues simultaneously
|
||||
- Isolated review environments for PRs
|
||||
- Switching contexts without stashing
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
**Directory structure:**
|
||||
```
|
||||
project/
|
||||
├── .git/ # Main repo
|
||||
├── src/ # Main working tree
|
||||
└── ../worktrees/ # Sibling worktrees directory
|
||||
├── project-issue-42/ # Issue implementation
|
||||
├── project-issue-43/ # Another issue
|
||||
└── project-review-55/ # PR review
|
||||
```
|
||||
|
||||
**Naming patterns:**
|
||||
- Issue work: `${REPO_NAME}-issue-${ISSUE_NUMBER}`
|
||||
- PR review: `${REPO_NAME}-review-${PR_NUMBER}`
|
||||
- Feature work: `${REPO_NAME}-feature-${FEATURE_NAME}`
|
||||
|
||||
**Why sibling directory:**
|
||||
- Keeps main repo clean
|
||||
- Easy to identify worktrees
|
||||
- Simple bulk operations
|
||||
- Works with tooling that scans parent directories
|
||||
|
||||
## Creating Worktrees
|
||||
|
||||
### For Issue Implementation
|
||||
|
||||
```bash
|
||||
REPO_PATH=$(pwd)
|
||||
REPO_NAME=$(basename "$REPO_PATH")
|
||||
WORKTREES_DIR="${REPO_PATH}/../worktrees"
|
||||
ISSUE_NUMBER=42
|
||||
|
||||
# Create worktrees directory
|
||||
mkdir -p "$WORKTREES_DIR"
|
||||
|
||||
# Fetch latest
|
||||
git fetch origin
|
||||
|
||||
# Get issue title for branch name
|
||||
ISSUE_TITLE=$(tea issues $ISSUE_NUMBER | grep -i "title" | head -1 | cut -d: -f2- | xargs)
|
||||
BRANCH_NAME="issue-${ISSUE_NUMBER}-$(echo "$ISSUE_TITLE" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd '[:alnum:]-' | cut -c1-50)"
|
||||
|
||||
# Create worktree with new branch from main
|
||||
git worktree add "${WORKTREES_DIR}/${REPO_NAME}-issue-${ISSUE_NUMBER}" \
|
||||
-b "$BRANCH_NAME" origin/main
|
||||
```
|
||||
|
||||
### For PR Review
|
||||
|
||||
```bash
|
||||
# For reviewing existing PR branch
|
||||
PR_NUMBER=55
|
||||
BRANCH_NAME="issue-42-feature-name" # Get from PR details
|
||||
|
||||
git fetch origin
|
||||
git worktree add "${WORKTREES_DIR}/${REPO_NAME}-review-${PR_NUMBER}" \
|
||||
"origin/${BRANCH_NAME}"
|
||||
```
|
||||
|
||||
## Bundled Scripts
|
||||
|
||||
Use bundled scripts for error-prone operations. Scripts are located in `~/.claude/skills/worktrees/scripts/`:
|
||||
|
||||
### Create Worktree
|
||||
|
||||
```bash
|
||||
# Usage: ~/.claude/skills/worktrees/scripts/create-worktree.sh issue <issue-number>
|
||||
# Usage: ~/.claude/skills/worktrees/scripts/create-worktree.sh review <pr-number> <branch-name>
|
||||
|
||||
~/.claude/skills/worktrees/scripts/create-worktree.sh issue 42
|
||||
~/.claude/skills/worktrees/scripts/create-worktree.sh review 55 issue-42-feature-name
|
||||
```
|
||||
|
||||
Returns worktree path on success.
|
||||
|
||||
### List Worktrees
|
||||
|
||||
```bash
|
||||
~/.claude/skills/worktrees/scripts/list-worktrees.sh
|
||||
```
|
||||
|
||||
Shows all active worktrees with their branches.
|
||||
|
||||
### Cleanup Worktrees
|
||||
|
||||
```bash
|
||||
# Remove specific worktree
|
||||
~/.claude/skills/worktrees/scripts/cleanup-worktrees.sh "${WORKTREES_DIR}/${REPO_NAME}-issue-42"
|
||||
|
||||
# Remove all worktrees in directory
|
||||
~/.claude/skills/worktrees/scripts/cleanup-worktrees.sh "${WORKTREES_DIR}"
|
||||
|
||||
# Force remove even if dirty
|
||||
~/.claude/skills/worktrees/scripts/cleanup-worktrees.sh --force "${WORKTREES_DIR}"
|
||||
```
|
||||
|
||||
## Patterns
|
||||
|
||||
### Pattern: Parallel Issue Implementation
|
||||
|
||||
**Orchestrator creates all worktrees upfront:**
|
||||
```bash
|
||||
for issue in 42 43 44; do
|
||||
worktree_path=$(~/.claude/skills/worktrees/scripts/create-worktree.sh issue $issue)
|
||||
# Spawn worker with worktree_path
|
||||
done
|
||||
```
|
||||
|
||||
**Worker uses provided worktree:**
|
||||
```bash
|
||||
cd "$WORKTREE_PATH" # Provided by orchestrator
|
||||
# Do work
|
||||
git add -A && git commit -m "..."
|
||||
git push -u origin $(git branch --show-current)
|
||||
```
|
||||
|
||||
**Orchestrator cleans up after all complete:**
|
||||
```bash
|
||||
~/.claude/skills/worktrees/scripts/cleanup-worktrees.sh "${WORKTREES_DIR}"
|
||||
```
|
||||
|
||||
### Pattern: Review in Isolation
|
||||
|
||||
**Create review worktree:**
|
||||
```bash
|
||||
worktree_path=$(~/.claude/skills/worktrees/scripts/create-worktree.sh review $PR_NUMBER $BRANCH_NAME)
|
||||
cd "$worktree_path"
|
||||
git diff origin/main...HEAD # Review changes
|
||||
```
|
||||
|
||||
### Pattern: Error Recovery
|
||||
|
||||
**List stale worktrees:**
|
||||
```bash
|
||||
~/.claude/skills/worktrees/scripts/list-worktrees.sh
|
||||
```
|
||||
|
||||
**Force cleanup:**
|
||||
```bash
|
||||
~/.claude/skills/worktrees/scripts/cleanup-worktrees.sh --force "${WORKTREES_DIR}"
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
**Always provide worktree paths to agents:**
|
||||
- Orchestrator creates worktrees
|
||||
- Agents receive path as parameter
|
||||
- Agents work in provided path
|
||||
- Orchestrator handles cleanup
|
||||
|
||||
**Never nest cleanup:**
|
||||
- Only orchestrator cleans up
|
||||
- Agents never remove their own worktree
|
||||
- Cleanup happens after all work complete
|
||||
|
||||
**Track worktree paths:**
|
||||
```bash
|
||||
# In orchestrator
|
||||
declare -A worktrees
|
||||
worktrees[42]=$(~/.claude/skills/worktrees/scripts/create-worktree.sh issue 42)
|
||||
worktrees[43]=$(~/.claude/skills/worktrees/scripts/create-worktree.sh issue 43)
|
||||
|
||||
# Pass to agents
|
||||
spawn_agent --worktree="${worktrees[42]}"
|
||||
```
|
||||
|
||||
**Handle errors gracefully:**
|
||||
- Use scripts (they handle errors)
|
||||
- Always cleanup, even on failure
|
||||
- Force-remove if necessary
|
||||
|
||||
## Common Issues
|
||||
|
||||
**Worktree already exists:**
|
||||
```bash
|
||||
# Remove old worktree first
|
||||
~/.claude/skills/worktrees/scripts/cleanup-worktrees.sh "${WORKTREES_DIR}/${REPO_NAME}-issue-42"
|
||||
|
||||
# Then create new one
|
||||
~/.claude/skills/worktrees/scripts/create-worktree.sh issue 42
|
||||
```
|
||||
|
||||
**Branch already exists:**
|
||||
```bash
|
||||
# Delete branch if safe
|
||||
git branch -d issue-42-old-name
|
||||
|
||||
# Or force delete
|
||||
git branch -D issue-42-old-name
|
||||
```
|
||||
|
||||
**Stale worktrees after crash:**
|
||||
```bash
|
||||
# List and force remove
|
||||
~/.claude/skills/worktrees/scripts/list-worktrees.sh
|
||||
~/.claude/skills/worktrees/scripts/cleanup-worktrees.sh --force "${WORKTREES_DIR}"
|
||||
```
|
||||
|
||||
## Tips
|
||||
|
||||
- Keep worktrees short-lived (hours, not days)
|
||||
- Clean up regularly to avoid clutter
|
||||
- Use scripts for reliability
|
||||
- Let orchestrator manage lifecycle
|
||||
- Check `git worktree list` if unsure about state
|
||||
Reference in New Issue
Block a user