gh-poindexter12-waypoint-workflows/skills/working-tree/REFERENCE.md

Git Worktree Guide - Comprehensive Reference

Complete guide to git worktrees with AI metadata integration for optimal development workflows.

Table of Contents

1. Overview
2. Core Concepts
3. Mode Semantics Deep Dive
4. Naming Conventions
5. Workflow Patterns
6. Metadata Files
7. Organization Strategies
8. Team Collaboration
9. Troubleshooting
10. Advanced Topics

---

Overview

What Are Git Worktrees?

Git worktrees allow you to check out multiple branches simultaneously in separate directories, all connected to the same repository. This eliminates the need to git stash or switch branches when context-switching.

Traditional Workflow:

# Working on feature
git checkout feature/user-auth
# ... work ...

# Need to fix bug
git stash
git checkout main
# ... fix bug ...

# Back to feature
git checkout feature/user-auth
git stash pop

Worktree Workflow:

# Create worktrees once
/working-tree:new feature/user-auth
/working-tree:new main --mode main

# Switch by changing directories
cd ../myapp-feature-user-auth  # Feature work
cd ../myapp  # Bug fix

# No stashing needed!

AI Metadata Integration

Each worktree has .ai-context.json that tells AI tools:

• What kind of work is being done (mode)
• Purpose of the worktree (description)
• When it was created
• Which branch it tracks

This allows AI to:

• Adjust suggestion style (conservative for main, aggressive for experiment)
• Understand context automatically
• Provide relevant warnings
• Suggest appropriate tools

---

Core Concepts

Worktree Structure

Parent directory/
├── myapp/                          # Main repository (or a worktree)
│   ├── .git/                       # Git metadata (worktrees link here)
│   ├── .ai-context.json            # AI metadata
│   └── README.working-tree.md      # Human-readable info
│
├── myapp-feature-user-auth/        # Feature worktree
│   ├── .git → ../myapp/.git/       # Links to main .git
│   ├── .ai-context.json
│   └── README.working-tree.md
│
└── myapp-bugfix-timeout/           # Bugfix worktree
    ├── .git → ../myapp/.git/
    ├── .ai-context.json
    └── README.working-tree.md

Metadata Files

.ai-context.json (Machine-Readable)

• JSON format
• Read by AI tools automatically
• Contains: worktree, branch, mode, created, description

README.working-tree.md (Human-Readable)

• Markdown format
• Documentation for developers
• Contains: mode semantics, paths, purpose

---

Mode Semantics Deep Dive

main - Production Stability

Philosophy: This is production-ready code. Changes must be minimal, tested, and safe.

Use Cases:

• Production hotfixes
• Critical security patches
• Emergency bug fixes
• Stable baseline for comparisons

Restrictions:

• No experimental changes
• No refactoring unless necessary for fix
• Minimal scope
• Full test coverage required

AI Behavior:

• Conservative suggestions
• Focuses on safety
• Warns about risks
• Suggests defensive code
• Recommends extensive testing

Example:

/working-tree:new main --mode main --description "Production baseline for hotfixes"

Workflow:

cd ../myapp-main
# Critical bug found in production
git pull origin main
# Make minimal surgical fix
git commit -m "fix: critical security vulnerability in auth"
git push origin main
# Deploy immediately

feature - Active Development

Philosophy: This is where real work happens. Experiment, iterate, and improve.

Use Cases:

• New features
• Enhancements to existing features
• Refactoring
• Performance improvements
• Most day-to-day work

Restrictions:

• None! Be creative
• Can make breaking changes
• Can refactor extensively
• Can add dependencies

AI Behavior:

• Helpful and proactive
• Suggests improvements freely
• Offers refactoring ideas
• Recommends best practices
• Encourages good patterns

Example:

/working-tree:new feature/user-dashboard --mode feature --description "New user settings dashboard with profile management"

Workflow:

cd ../myapp-feature-user-dashboard
# Develop freely
npm install new-library
# Refactor as needed
# Add tests
# Iterate until ready
git push origin feature/user-dashboard
# Create PR when ready

bugfix - Surgical Precision

Philosophy: Fix one specific bug without touching anything else.

Use Cases:

• Specific bug fixes
• Regression fixes
• Issue resolution
• Targeted corrections

Restrictions:

• Minimal scope (only fix the bug)
• No "while I'm here" changes
• No refactoring (unless required for fix)
• No new features

AI Behavior:

• Focused on the specific issue
• Warns about scope creep
• Suggests minimal changes
• Recommends adding tests for the bug
• Keeps changes isolated

Example:

/working-tree:new bugfix/session-timeout --mode bugfix --description "Fix session timeout not respecting user settings (issue #427)"

Workflow:

cd ../myapp-bugfix-session-timeout
# Reproduce the bug
# Write test that fails
# Fix minimal code to make test pass
# Verify no other changes
git diff  # Should show minimal changes
git push origin bugfix/session-timeout

experiment - Prototype Freely

Philosophy: This might get thrown away. Optimize for learning, not production quality.

Use Cases:

• Proof of concepts
• Technology spikes
• Architecture exploration
• A/B testing approaches
• Learning new libraries

Restrictions:

• None - can be messy
• Don't worry about code quality
• Tests optional
• Can break conventions

AI Behavior:

• Aggressive with suggestions
• OK with rough code
• Suggests quick solutions
• Encourages trying things
• Less concerned with best practices

Example:

/working-tree:new exp/graphql-migration --mode experiment --description "Spike: evaluate GraphQL migration feasibility"

Workflow:

cd ../myapp-exp-graphql-migration
# Try things quickly
# Don't worry about polish
# Document learnings
# If successful → create feature worktree for proper implementation
# If failed → /working-tree:destroy and document why

review - Analytical Mindset

Philosophy: Read and analyze code without modifying production code.

Use Cases:

• Code review (PRs)
• Security audits
• Documentation work
• Performance analysis
• Understanding unfamiliar code

Restrictions:

• Read-only mindset (changes OK for docs/tests)
• No production code modification
• Analysis and documentation only

AI Behavior:

• Analytical and critical
• Points out issues
• Suggests improvements (for author to implement)
• Focuses on understanding
• Explains complex code

Example:

/working-tree:new review/pr-543 --mode review --description "Review authentication refactor PR #543"

Workflow:

cd ../myapp-review-pr-543
git fetch origin pull/543/head:review/pr-543
git checkout review/pr-543
# Read and analyze
# Add review comments
# Test changes
# Approve or request changes in PR
# When done → /working-tree:destroy

---

Naming Conventions

Structure Pattern

Format: <repo-name>-<type>-<description>

Examples:

• myapp-feature-user-auth
• myapp-bugfix-session-timeout
• myapp-exp-graphql-spike
• api-server-feature-rate-limiting

Prefix Indicators

Use branch prefixes to auto-infer modes:

• feature/ → mode: feature
• bugfix/ or fix/ → mode: bugfix
• exp/ or experiment/ → mode: experiment
• review/ → mode: review
• main or master → mode: main

Best Practices

DO:

• Use lowercase with hyphens: user-auth ✅
• Be descriptive: feature/oauth2-integration ✅
• Include issue numbers: bugfix/issue-427-timeout ✅
• Use consistent prefixes: feature/, bugfix/, exp/ ✅

DON'T:

• Use generic names: test, temp, new ❌
• Use spaces or special chars: user auth, user_auth ❌
• Be vague: fix-bug, feature-1 ❌
• Mix naming styles ❌

---

Workflow Patterns

Pattern 1: Feature Development

Scenario: Developing a new feature over several days/weeks

Setup:

/working-tree:new feature/user-dashboard --mode feature --description "User settings dashboard with profile editing"

Workflow:

# Day 1: Setup
cd ../myapp-feature-user-dashboard
npm install needed-packages
git commit -m "feat: initial dashboard setup"

# Day 2-5: Development
# Work iteratively, commit frequently
git commit -m "feat: add profile form"
git commit -m "feat: add settings panel"

# Day 6: Review
git push origin feature/user-dashboard
# Create PR

# After merge
cd ../myapp
/working-tree:destroy ../myapp-feature-user-dashboard

Pattern 2: Parallel Feature Work

Scenario: Working on multiple features simultaneously

Setup:

/working-tree:new feature/api-v2 --description "New API endpoints"
/working-tree:new feature/ui-redesign --description "Frontend redesign"
/working-tree:new feature/user-auth --description "OAuth2 authentication"

Workflow:

# Morning: API work
cd ../myapp-feature-api-v2
# ... work on API ...

# Afternoon: UI work
cd ../myapp-feature-ui-redesign
# ... work on UI ...

# Context switching is instant - no git stash!

Management:

# Check status of all work
/working-tree:list

# See current worktree
/working-tree:status

Pattern 3: Urgent Hotfix During Feature Work

Scenario: Critical bug found while working on feature

Setup:

# Already working in feature worktree
cd ../myapp-feature-user-dashboard

# Urgent bug reported!
# Don't stash - just create bugfix worktree
cd ../myapp
/working-tree:new bugfix/critical-auth-flaw --mode bugfix

# Fix the bug
cd ../myapp-bugfix-critical-auth-flaw
# ... fix ...
git push origin bugfix/critical-auth-flaw

# Back to feature work
cd ../myapp-feature-user-dashboard
# Continue where you left off - no stash pop needed!

Pattern 4: Deployment Environment Management

Scenario: Managing dev, staging, and production deployments

Setup:

/working-tree:new develop --mode feature --description "Development environment"
/working-tree:new staging --mode review --description "Staging for QA testing"
/working-tree:new production --mode main --description "Production deployment code"

Workflow:

# Deploy to dev
cd ../myapp-develop
git pull origin develop
npm install
npm run build
npm run deploy:dev

# When ready for staging
cd ../myapp-staging
git pull origin staging
npm install
npm run build
npm run deploy:staging

# After QA approval
cd ../myapp-production
git pull origin main
npm install
npm run build
npm run deploy:prod

Each environment has its own:

• Dependencies (node_modules)
• Build artifacts
• Configuration files (.env.dev, .env.staging, .env.prod)

Pattern 5: Code Review Workflow

Scenario: Reviewing PRs without disrupting current work

Setup:

# For each PR to review
/working-tree:new review/pr-<number> --mode review --description "Review PR #<number>: <title>"

Workflow:

# Create review worktree
cd ../myapp
/working-tree:new review/pr-543 --mode review

cd ../myapp-review-pr-543
# Fetch the PR branch
git fetch origin pull/543/head:review/pr-543
git checkout review/pr-543

# Review the code
# Run tests
npm test

# Check the changes
git diff main...review/pr-543

# Add review comments in GitHub
# When done
cd ../myapp
/working-tree:destroy ../myapp-review-pr-543

---

Metadata Files

.ai-context.json Structure

Format:

{
  "worktree": "string - directory name",
  "branch": "string - git branch name",
  "mode": "main|feature|bugfix|experiment|review",
  "created": "string - ISO 8601 UTC timestamp",
  "description": "string - freeform purpose description"
}

Example:

{
  "worktree": "myapp-feature-user-auth",
  "branch": "feature/user-authentication",
  "mode": "feature",
  "created": "2025-11-23T10:30:00Z",
  "description": "Implement OAuth2 and JWT authentication with refresh tokens"
}

Field Details:

• worktree: Just the directory name (not full path)

  • Example: myapp-feature-user-auth
  • Used by AI to identify context

• branch: Full git branch name

  • Example: feature/user-authentication
  • Must match actual git branch

• mode: One of five modes

  • Values: main, feature, bugfix, experiment, review
  • Affects AI behavior significantly

• created: ISO 8601 timestamp in UTC

  • Format: YYYY-MM-DDTHH:MM:SSZ
  • Example: 2025-11-23T10:30:00Z
  • Timezone must be UTC (trailing Z)

• description: Freeform text

  • Can be empty string
  • Keep concise (one sentence ideal)
  • Explain purpose, not implementation

README.working-tree.md Structure

Purpose: Human-readable documentation about the worktree

Auto-Generated Content:

• Worktree name and branch
• Mode and its semantics
• Creation timestamp
• Purpose/description
• Path information
• Mode reference guide

Example:

# Worktree: myapp-feature-user-auth

**Branch:** `feature/user-authentication`
**Mode:** `feature`
**Created:** 2025-11-23T10:30:00Z

## Purpose

Implement OAuth2 and JWT authentication with refresh tokens

## Mode Semantics

- **main**: Minimal changes, stable work only
- **feature**: Active development, larger changes allowed
- **bugfix**: Isolated, surgical fixes only
- **experiment**: Prototypes, large swings, unsafe changes allowed
- **review**: Documentation, analysis, audits

## About This Worktree

This directory is an independent Git worktree attached to the main repository.

- Main repo: /Users/joe/Code/myapp
- Worktree path: /Users/joe/Code/myapp-feature-user-auth
- Branch: feature/user-authentication

See `.ai-context.json` for machine-readable metadata.

---

Organization Strategies

Strategy 1: Feature-Centric (Recommended)

Philosophy: One worktree per active feature/task

Structure:

myapp/                     # main repo (mode: main or feature)
myapp-feature-api-v2/     # mode: feature
myapp-feature-ui-refresh/ # mode: feature
myapp-bugfix-auth-leak/   # mode: bugfix

Best For:

• Small to medium teams
• Feature-driven development
• Agile workflows
• Parallel feature development

Commands:

/working-tree:adopt --mode main --description "Main repository"
/working-tree:new feature/api-v2
/working-tree:new feature/ui-refresh
/working-tree:new bugfix/auth-leak --mode bugfix

Strategy 2: Environment-Based

Philosophy: Permanent worktrees for each environment

Structure:

myapp-develop/       # mode: feature (develop branch)
myapp-staging/       # mode: review (staging branch)
myapp-production/    # mode: main (main branch)
myapp-feature-X/     # mode: feature (temporary feature work)

Best For:

• DevOps-heavy workflows
• Multiple deployment environments
• Configuration management
• Testing different versions

Commands:

/working-tree:new develop --mode feature --description "Development environment"
/working-tree:new staging --mode review --description "Staging for QA"
/working-tree:new main --mode main --description "Production code"

Strategy 3: Experimentation-Heavy

Philosophy: Many experiments, few stable features

Structure:

myapp/                    # mode: main (stable baseline)
myapp-exp-approach-a/    # mode: experiment
myapp-exp-approach-b/    # mode: experiment
myapp-exp-new-framework/ # mode: experiment

Best For:

• Research projects
• Prototyping
• Technology evaluation
• Rapid experimentation

Commands:

/working-tree:adopt --mode main --description "Stable baseline for comparisons"
/working-tree:new exp/approach-a --mode experiment
/working-tree:new exp/approach-b --mode experiment

Strategy 4: Review-Focused

Philosophy: Code quality and review are primary

Structure:

myapp/                  # mode: feature (main development)
myapp-review-pr-123/   # mode: review
myapp-review-pr-456/   # mode: review
myapp-review-security/ # mode: review (audit)

Best For:

• Open source maintainers
• Code review heavy workflows
• Security auditing
• Quality-focused teams

Commands:

/working-tree:new review/pr-123 --mode review --description "Review user auth PR"
/working-tree:new review/security-audit --mode review

---

Team Collaboration

Sharing Worktree Practices

Document Your Strategy:

Create WORKTREE-GUIDE.md in your repository:

# Our Worktree Strategy

## Naming Convention
- Feature: `<repo>-feature-<short-name>`
- Bugfix: `<repo>-bugfix-<issue-number>`

## Modes
- `main`: Production code only
- `feature`: All development work
- `bugfix`: Bug fixes only

## Workflow
1. Create feature worktree: `/working-tree:new feature/name`
2. Develop and commit
3. Push and create PR
4. After merge: `/working-tree:destroy ../path`

Team Conventions

Agree On:

1. Naming patterns: Consistent prefixes
2. Mode usage: When to use each mode
3. Cleanup policy: When to destroy worktrees
4. Metadata descriptions: Level of detail

Example Team Agreement:

## Team Worktree Standards

### Naming
- Always use branch name in directory: `myapp-<branch-name>`
- Replace slashes with hyphens: `feature/user-auth` → `feature-user-auth`

### Modes
- `feature` for all development
- `bugfix` for issue fixes only
- `main` reserved for production hotfixes

### Cleanup
- Destroy worktree immediately after PR merge
- Run `/working-tree:list` weekly to audit active worktrees

### Descriptions
- Always include issue number if applicable
- One sentence explaining purpose

CI/CD Integration

Worktree-Aware CI:

Each worktree can have its own CI configuration or environment:

# .github/workflows/ci.yml
name: CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      # Read .ai-context.json to customize behavior
      - name: Read worktree mode
        run: |
          MODE=$(jq -r '.mode' .ai-context.json || echo "feature")
          echo "WORKTREE_MODE=$MODE" >> $GITHUB_ENV

      # Skip certain checks for experiment mode
      - name: Lint
        if: env.WORKTREE_MODE != 'experiment'
        run: npm run lint

      # Always run tests
      - name: Test
        run: npm test

---

Troubleshooting

Issue: "Branch already has a worktree"

Symptom:

Error: Branch 'feature/login' already has a worktree at /path/to/worktree

Cause: Trying to create a second worktree for the same branch

Solution:

# Option 1: Use the existing worktree
cd /path/to/existing/worktree

# Option 2: Destroy old worktree first
/working-tree:destroy /path/to/old/worktree
/working-tree:new feature/login

# Option 3: Checkout different branch in main repo
cd /path/to/main/repo
git checkout different-branch

Issue: Metadata file is missing

Symptom: /working-tree:status shows "no metadata"

Solution:

# Add metadata to existing worktree
/working-tree:adopt --mode feature --description "Your description"

Issue: Uncommitted changes when destroying

Symptom: Want to remove worktree but have uncommitted work

Solution:

# Option 1: Commit changes
cd /path/to/worktree
git add .
git commit -m "Save work in progress"
/working-tree:destroy /path/to/worktree

# Option 2: Stash changes
cd /path/to/worktree
git stash
/working-tree:destroy /path/to/worktree
# Later: git stash pop (in main repo or another worktree)

# Option 3: Proceed anyway (DESTRUCTIVE)
/working-tree:destroy /path/to/worktree
# Will warn you, but can proceed

Issue: Too many worktrees

Symptom: Can't track all your worktrees

Solution:

# Audit all worktrees
/working-tree:list

# Identify completed work
# For each completed worktree:
/working-tree:destroy ../myapp-feature-completed-thing

# Clean up stale references
git worktree prune

Issue: Confused about which worktree to use

Symptom: Multiple worktrees, unclear which has what work

Solution:

# Check current worktree
/working-tree:status

# List all with descriptions
/working-tree:list

# Add better descriptions
/working-tree:adopt --description "Clear, specific purpose"

# Clean up unclear worktrees
/working-tree:destroy ../myapp-temp  # Vague names

Issue: Metadata and branch don't match

Symptom: .ai-context.json shows wrong branch

Cause: Branch was changed after metadata creation

Solution:

# Re-adopt to update metadata
/working-tree:adopt --description "Updated description"

# This will regenerate metadata with correct branch

---

Advanced Topics

Worktree Best Practices Summary

Creation:

• ✅ Use descriptive names
• ✅ Always add descriptions
• ✅ Choose appropriate mode
• ✅ Use branch prefixes for auto-mode

Usage:

• ✅ Run /working-tree:status when starting work
• ✅ Use /working-tree:list to see all work
• ✅ Keep modes consistent with work type
• ✅ Update descriptions if purpose changes

Cleanup:

• ✅ Destroy after PR merge
• ✅ Check for uncommitted changes first
• ✅ Run weekly audit with /working-tree:list
• ✅ Clean up experiment worktrees promptly

When NOT to Use Worktrees

Use Traditional Branches If:

• Only working on one thing at a time
• Rarely switch contexts
• Short-lived changes (< 1 hour)
• Very simple projects

Worktrees Add Overhead For:

• Single-file edits
• Quick typo fixes
• Documentation-only changes
• Projects with no parallel work

Performance Considerations

Disk Space:

• Each worktree duplicates working tree (not .git)
• Source code is duplicated, git history is shared
• For large repos, worktrees can use significant disk space

Build Artifacts:

• Each worktree has its own node_modules/, target/, etc.
• Can use significant disk space
• Consider sharing build cache if possible

Management:

• More worktrees = more to track
• Recommended max: 5-10 active worktrees
• Archive or destroy unused worktrees regularly

Integration with AI Tools

How AI Uses Metadata:

1. Context Understanding:

   • Reads .ai-context.json automatically
   • Understands mode semantics
   • Adjusts behavior accordingly

2. Suggestion Style:

   • main: Conservative, safe suggestions
   • feature: Helpful, proactive
   • bugfix: Focused, minimal scope
   • experiment: Aggressive, quick solutions
   • review: Analytical, critical

3. Warnings and Checks:

   • main: Warns about any changes
   • bugfix: Warns about scope creep
   • experiment: Minimal warnings
   • review: Suggests improvements

4. Tool Selection:

   • Recommends appropriate tools based on mode
   • Suggests testing strategies per mode
   • Provides mode-appropriate examples

---

Quick Reference

Essential Commands

# Create new worktree with metadata
/working-tree:new <branch-name> [--mode <mode>] [--description "<text>"]

# List all worktrees with metadata
/working-tree:list

# Show current worktree metadata
/working-tree:status

# Add metadata to existing worktree
/working-tree:adopt [--mode <mode>] [--description "<text>"]

# Remove worktree (preserves branch)
/working-tree:destroy <worktree-path>

Mode Quick Reference

Mode	Purpose	Restrictions	AI Behavior
main	Production code	Minimal changes only	Conservative
feature	Development	None	Helpful
bugfix	Bug fixes	Focused scope	Minimal scope
experiment	Prototypes	None	Aggressive
review	Code review	Read-only mindset	Analytical

Metadata Template

{
  "worktree": "directory-name",
  "branch": "branch-name",
  "mode": "feature",
  "created": "2025-11-23T12:34:56Z",
  "description": "Purpose of worktree"
}

---

Further Reading

• Git Worktree Official Docs: git help worktree
• Working Tree Consultant Agent: Invoke for strategic guidance
• Templates: See templates/ directory for copy-paste templates

---

Version: 1.0.0 Last Updated: 2025-11-23 Maintained by: Waypoint working-tree module