Initial commit

skills/git-worktree-setup/modes/mode1-single-worktree.md

@@ -0,0 +1,568 @@
+# Mode 1: Single Worktree Creation
+
+## Overview
+
+This mode creates a single git worktree for parallel development. Use this when the user wants to work on one additional branch alongside their current work.
+
+## When to Use
+
+- User mentions creating "a worktree" (singular)
+- User specifies one branch name
+- User says "I need to work on [branch]"
+- Default mode when unclear
+
+## Workflow
+
+### Phase 0: Prerequisites & Validation
+
+#### Step 0.1: Verify Git Repository
+
+```bash
+git rev-parse --is-inside-work-tree
+```
+
+**Expected Output:**
+```
+true
+```
+
+**If fails:**
+- Stop immediately
+- Error: "Not in a git repository. Please navigate to your project root and try again."
+
+#### Step 0.2: Get Repository Information
+
+```bash
+# Get repository name
+basename $(git rev-parse --show-toplevel)
+
+# Get current branch
+git branch --show-current
+```
+
+**Store:**
+- `REPO_NAME`: Repository name
+- `CURRENT_BRANCH`: Current branch
+
+#### Step 0.3: Check Working Directory Status
+
+```bash
+git status --porcelain
+```
+
+**If output exists:**
+- **Warning:** "You have uncommitted changes in your current worktree:"
+- Show: `git status --short`
+- Ask: "Continue creating worktree anyway? This won't affect your changes."
+- If user declines → Stop
+
+**If clean:**
+- Proceed silently
+
+#### Step 0.4: Check Existing Worktrees
+
+```bash
+git worktree list
+```
+
+**Purpose:**
+- Show user current worktree state
+- Detect conflicts before creation
+- Store for later reference
+
+---
+
+### Phase 1: Gather Information
+
+#### Step 1.1: Extract Branch Name
+
+**From user request:**
+- "create worktree for **feature-auth**"
+- "set up worktree for **bugfix-123**"
+- "I need a worktree for **experiment-new-ui**"
+
+**Extract:**
+- `BRANCH_NAME`: The branch to work on
+
+**If unclear:**
+- Ask: "What branch name should I use for the worktree?"
+
+#### Step 1.2: Determine Branch Type
+
+**Check if branch exists:**
+```bash
+git show-ref --verify refs/heads/$BRANCH_NAME 2>/dev/null
+```
+
+**If exits (exit code 0):**
+- `BRANCH_TYPE`: "existing"
+- Message: "Found existing branch: $BRANCH_NAME"
+
+**If doesn't exist:**
+- `BRANCH_TYPE`: "new"
+- Message: "Will create new branch: $BRANCH_NAME"
+
+**Also check remote:**
+```bash
+git show-ref --verify refs/remotes/origin/$BRANCH_NAME 2>/dev/null
+```
+
+**If exists on remote but not local:**
+- Offer: "Branch exists on remote. Track remote branch or create new local?"
+- Default: Track remote
+
+#### Step 1.3: Determine Worktree Location
+
+**Default location:**
+```
+../$REPO_NAME-$BRANCH_NAME
+```
+
+**Example:**
+- Repo: `myapp`
+- Branch: `feature-auth`
+- Location: `../myapp-feature-auth`
+
+**Ask user:**
+"I'll create the worktree at: `$DEFAULT_LOCATION`"
+"Use this location? (yes/no/specify custom)"
+
+**Options:**
+- Yes → Use default
+- No → Ask for custom path
+- Custom → Use provided path
+
+**Store:**
+- `WORKTREE_PATH`: Final worktree location
+
+#### Step 1.4: Check Directory Availability
+
+```bash
+if [ -d "$WORKTREE_PATH" ]; then
+  echo "exists"
+else
+  echo "available"
+fi
+```
+
+**If exists:**
+- **Error:** "Directory already exists: $WORKTREE_PATH"
+- Ask: "Remove it and continue? (yes/no)"
+- If yes → `rm -rf $WORKTREE_PATH` (with confirmation)
+- If no → Ask for different location
+
+#### Step 1.5: Development Environment Setup
+
+**Check for package.json:**
+```bash
+if [ -f "package.json" ]; then
+  echo "found"
+fi
+```
+
+**If found:**
+- Default: "Setup development environment? (yes/no)" → yes
+- Ask: "Install dependencies in new worktree?"
+
+**Store:**
+- `SETUP_DEV`: true/false
+
+**If no package.json:**
+- Skip dev setup questions
+- `SETUP_DEV`: false
+
+---
+
+### Phase 2: Create Worktree
+
+#### Step 2.1: Execute Worktree Creation
+
+**For new branch:**
+```bash
+git worktree add $WORKTREE_PATH -b $BRANCH_NAME
+```
+
+**For existing branch:**
+```bash
+git worktree add $WORKTREE_PATH $BRANCH_NAME
+```
+
+**For tracking remote branch:**
+```bash
+git worktree add $WORKTREE_PATH -b $BRANCH_NAME --track origin/$BRANCH_NAME
+```
+
+**Expected Output:**
+```
+Preparing worktree (new branch 'feature-auth')
+HEAD is now at abc123 Initial commit
+```
+
+**Monitor for errors:**
+- "fatal: invalid reference" → Branch doesn't exist
+- "fatal: 'path' already exists" → Directory conflict
+- "fatal: 'branch' is already checked out" → Branch in another worktree
+
+**If error:**
+- Stop and report error
+- Provide fix suggestion
+- Don't continue to next phase
+
+#### Step 2.2: Verify Worktree Creation
+
+```bash
+git worktree list
+```
+
+**Check output includes:**
+```
+/path/to/worktree  abc123 [branch-name]
+```
+
+**Verify directory:**
+```bash
+ls -la $WORKTREE_PATH
+```
+
+**Must see:**
+- `.git` file (not directory - points to parent)
+- Project files
+
+**If verification fails:**
+- **Error:** "Worktree creation failed verification"
+- Show: `git worktree list`
+- Offer: "Try again with different settings?"
+- Stop
+
+#### Step 2.3: Confirm Success
+
+**Output:**
+```
+✓ Worktree created successfully
+  Location: $WORKTREE_PATH
+  Branch: $BRANCH_NAME ($BRANCH_TYPE)
+  Status: Ready
+```
+
+---
+
+### Phase 3: Setup Development Environment
+
+**Only if `SETUP_DEV` is true**
+
+#### Step 3.1: Navigate to Worktree
+
+```bash
+cd $WORKTREE_PATH
+```
+
+#### Step 3.2: Detect Package Manager
+
+**Check for lockfiles in priority order:**
+
+```bash
+# Check pnpm
+if [ -f "pnpm-lock.yaml" ]; then
+  PKG_MANAGER="pnpm"
+  INSTALL_CMD="pnpm install"
+fi
+
+# Check yarn
+if [ -f "yarn.lock" ]; then
+  PKG_MANAGER="yarn"
+  INSTALL_CMD="yarn install"
+fi
+
+# Check bun
+if [ -f "bun.lockb" ]; then
+  PKG_MANAGER="bun"
+  INSTALL_CMD="bun install"
+fi
+
+# Check npm
+if [ -f "package-lock.json" ]; then
+  PKG_MANAGER="npm"
+  INSTALL_CMD="npm install"
+fi
+
+# Default to npm if no lockfile
+if [ -z "$PKG_MANAGER" ]; then
+  PKG_MANAGER="npm"
+  INSTALL_CMD="npm install"
+fi
+```
+
+**Output:**
+```
+Detected package manager: $PKG_MANAGER
+```
+
+#### Step 3.3: Run Installation
+
+```bash
+$INSTALL_CMD
+```
+
+**Show progress:**
+```
+Installing dependencies with $PKG_MANAGER...
+```
+
+**Expected output (varies by manager):**
+- npm: "added X packages in Ys"
+- pnpm: "Packages: +X"
+- yarn: "Done in Xs"
+- bun: "X packages installed"
+
+**Monitor for errors:**
+- Network failures
+- Lockfile conflicts
+- Disk space issues
+
+**If error:**
+- Show error message
+- Suggest: "Installation failed. You can manually run `$INSTALL_CMD` in the worktree later."
+- Mark: Dev environment setup failed
+- Continue (don't stop entire process)
+
+**If success:**
+```
+✓ Dependencies installed successfully
+```
+
+#### Step 3.4: Copy Environment Files (Optional)
+
+**Check for .env in parent:**
+```bash
+if [ -f "../.env" ]; then
+  echo "found"
+fi
+```
+
+**If found:**
+- Ask: "Copy .env file to worktree? (yes/no)"
+- Default: Ask (don't assume - may contain secrets)
+
+**If yes:**
+```bash
+cp ../.env .env
+```
+
+**Output:**
+```
+✓ Environment file copied
+```
+
+**Other common files to check:**
+- `.env.local`
+- `.env.development`
+- `.env.test`
+
+#### Step 3.5: Verify Development Setup
+
+```bash
+# Check node_modules exists
+if [ -d "node_modules" ]; then
+  echo "✓ Dependencies installed"
+fi
+
+# Try running a basic script (optional)
+npm run build --dry-run 2>/dev/null && echo "✓ Build configuration valid"
+```
+
+**Final status:**
+```
+✓ Development environment ready
+  Package manager: $PKG_MANAGER
+  Dependencies: Installed
+  Environment: Ready
+```
+
+---
+
+### Phase 4: Provide User Guidance
+
+#### Step 4.1: Generate Summary
+
+**Create summary output:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Worktree Created Successfully
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Location:   $WORKTREE_PATH
+Branch:     $BRANCH_NAME (new/existing)
+Base:       $BASE_BRANCH
+Dev Setup:  ✓ Complete / ⊘ Skipped
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Next Steps
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+1. Navigate to worktree:
+   cd $WORKTREE_PATH
+
+2. Start Claude Code:
+   claude
+
+3. Begin development on $BRANCH_NAME
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+#### Step 4.2: Show All Worktrees
+
+```bash
+git worktree list
+```
+
+**Format output:**
+```
+All Worktrees:
+  /path/to/main        (main)          ← current
+  $WORKTREE_PATH       ($BRANCH_NAME)  ← new
+```
+
+**Highlight:**
+- Current worktree with `← current`
+- New worktree with `← new`
+
+#### Step 4.3: Provide Quick Reference Commands
+
+```
+Quick Reference:
+  List worktrees:    git worktree list
+  Remove worktree:   git worktree remove $WORKTREE_PATH
+  Navigate:          cd $WORKTREE_PATH
+  Return to main:    cd [original path]
+```
+
+#### Step 4.4: Offer Additional Actions
+
+**Ask user:**
+"Would you like me to:
+- [ ] Open the worktree in a new terminal
+- [ ] Generate a setup script for future worktrees
+- [ ] Show git commands for advanced management"
+
+**Based on response, provide appropriate outputs**
+
+---
+
+### Phase 5: Post-Creation Verification
+
+#### Step 5.1: Final Checks
+
+```bash
+# Verify worktree is in list
+git worktree list | grep -q "$WORKTREE_PATH"
+
+# Verify directory exists and has files
+[ -d "$WORKTREE_PATH" ] && [ "$(ls -A $WORKTREE_PATH)" ]
+
+# Verify .git file exists
+[ -f "$WORKTREE_PATH/.git" ]
+```
+
+**All must pass**
+
+#### Step 5.2: Success Confirmation
+
+**Create success checklist:**
+```
+✓ Worktree created at correct location
+✓ Branch checked out properly
+✓ Files visible in worktree directory
+✓ Development environment ready (if requested)
+✓ Worktree appears in git worktree list
+✓ Ready for Claude Code session
+```
+
+**If any fail:**
+- Report which check failed
+- Provide troubleshooting steps
+- Offer to retry or cleanup
+
+---
+
+## Error Handling
+
+### Error: Not a Git Repository
+
+```
+Error: Not in a git repository
+
+Solution:
+1. Navigate to your project root
+2. Verify with: git status
+3. Try again
+```
+
+### Error: Branch Already Checked Out
+
+```
+Error: Branch 'feature-x' is already checked out at '/path'
+
+Solution:
+1. List worktrees: git worktree list
+2. Navigate to existing worktree, or
+3. Remove existing worktree first:
+   git worktree remove /path
+```
+
+### Error: Directory Already Exists
+
+```
+Error: Directory already exists: /path/to/worktree
+
+Solutions:
+1. Use different location
+2. Remove directory: rm -rf /path/to/worktree
+3. Specify custom path when creating
+```
+
+### Error: Installation Failed
+
+```
+Error: Dependency installation failed
+
+Solutions:
+1. Check network connection
+2. Manually run in worktree:
+   cd /path/to/worktree
+   [package-manager] install
+3. Check lockfile compatibility
+```
+
+---
+
+## Stop Conditions
+
+**Stop immediately if:**
+- [ ] Not in a git repository
+- [ ] Worktree creation command fails
+- [ ] Directory already exists and user declines removal
+- [ ] User cancels during any confirmation
+
+**Continue with warnings if:**
+- [ ] Uncommitted changes in current worktree
+- [ ] Dependency installation fails
+- [ ] Environment file copy fails
+
+---
+
+## Success Criteria
+
+- [ ] Worktree created successfully
+- [ ] Branch checked out
+- [ ] Directory accessible
+- [ ] Dev environment ready (if requested)
+- [ ] User provided with clear next steps
+- [ ] All verification checks passed
+
+---
+
+## Example: Complete Flow
+
+```
+User: Create a worktree for feature-authentication