Git Worktree Guide

Quick reference and templates for git worktree workflows with AI metadata integration.

Progressive Disclosure

Initial Response

Quick Overview:

Git worktrees let you checkout multiple branches simultaneously in separate directories. Each worktree has AI metadata (.ai-context.json) that helps tools understand context.

Quick Start:

Create worktree: /working-tree:new <branch-name>
List worktrees: /working-tree:list
Check status: /working-tree:status
Remove worktree: /working-tree:destroy <path>
Add metadata: /working-tree:adopt

What would you like to know more about?

Mode semantics (main, feature, bugfix, experiment, review)
Metadata file structure and templates
Comprehensive best practices guide
Strategic organization patterns

On Request

Based on what you ask for, I can show you:

Mode Semantics → Detailed explanation of each mode Templates → Ready-to-use metadata templates Best Practices → Full reference guide (REFERENCE.md) Examples → Specific workflow examples

Mode Semantics Quick Reference

main

Purpose: Stable, production-ready code Restrictions: Minimal changes only, no experimentation Use For: Hotfixes, urgent production changes, stable baseline AI Behavior: Conservative suggestions, focus on safety

feature

Purpose: Active development of new features Restrictions: None, experimentation encouraged Use For: New features, enhancements, active work AI Behavior: Helpful, suggests improvements freely

bugfix

Purpose: Isolated, surgical bug fixes Restrictions: Minimal scope, no unrelated changes Use For: Specific bug fixes, targeted corrections AI Behavior: Focused on fix only, warns about scope creep

experiment

Purpose: Prototypes, spikes, research Restrictions: None, can be messy, expect to discard Use For: POCs, trying new technologies, A/B testing AI Behavior: Aggressive suggestions, OK with rough code

review

Purpose: Code review, auditing, documentation Restrictions: Read-only mindset, analysis only Use For: PR review, security audits, documentation work AI Behavior: Analytical, suggests improvements, no execution

Metadata File Structure

.ai-context.json

{
  "worktree": "directory-name",
  "branch": "branch-name",
  "mode": "main|feature|bugfix|experiment|review",
  "created": "2025-11-23T12:34:56Z",
  "description": "Purpose of this worktree"
}

Fields:

worktree: Directory name (not full path)
branch: Git branch name
mode: One of the 5 modes above
created: ISO 8601 UTC timestamp
description: Freeform text explaining purpose

README.working-tree.md

Generated automatically with worktree details, mode semantics, and paths.

Templates

Available Templates

Located in templates/ directory:

ai-context.json.template - Metadata file template with examples
README.working-tree.template - README template with placeholders

To view templates:

Ask "show me the metadata template"
Ask "show me the README template"

Common Patterns

Pattern 1: Feature Development

/working-tree:new feature/user-auth --mode feature --description "Implement OAuth2"

Work in isolation, merge when ready.

Pattern 2: Production Hotfix

/working-tree:new bugfix/critical-security-fix --mode bugfix

Quick surgical fix, minimizes risk.

Pattern 3: Experimentation

/working-tree:new exp/try-new-framework --mode experiment

Prototype freely, discard if needed.

Pattern 4: Code Review

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

Review without disrupting current work.

Pattern 5: Internationalization

/working-tree:new i18n/zh-CN --description "Chinese Simplified translations"
/working-tree:new i18n/42-ja-JP --description "Japanese translations for issue #42"

Isolated i18n work for specific locale.

Supporting Files

references/best-practices.md: Comprehensive guide with detailed best practices, naming conventions, workflows, and advanced patterns
templates/ai-context.json.template: Copy-paste template for manual metadata creation
templates/README.working-tree.template: Template for worktree README

Quick Tips

DO:

Use descriptive branch names: feature/user-dashboard
Add descriptions to worktrees: --description "User settings page"
Run /working-tree:list regularly to see active work
Choose appropriate mode for context

DON'T:

Create worktree for same branch twice
Use generic names: test, temp, new
Use branch names that match existing project folders (e.g., workflows, src, backend)
Forget to clean up: /working-tree:destroy when done
Ignore uncommitted changes before destroying

For More Detail

Comprehensive Guide: Ask to see references/best-practices.md for:

Detailed mode usage guidelines
Naming conventions and patterns
Multi-worktree organization strategies
Troubleshooting common issues
Team collaboration workflows
CI/CD integration patterns

Strategic Consulting: For complex worktree organization questions, invoke the working-tree-consultant agent:

"Help me organize my worktrees"
"Review my worktree strategy"
"Migrate to worktree workflow"

Examples

Example 1: Quick Mode Check

User: What mode should I use for a prototype?

Skill: For prototypes, use **experiment** mode.

Experiment mode:
- No restrictions, can be messy
- AI will be aggressive with suggestions
- Expect to discard if prototype fails
- Good for POCs and spikes

Command:
/working-tree:new exp/prototype-name --mode experiment --description "Testing new approach"

Example 2: Template Request

User: Show me the metadata template

Skill: Here's the .ai-context.json template:

[Shows content of templates/ai-context.json.template]

You can create this manually or use:
- /working-tree:new to auto-generate when creating
- /working-tree:adopt to auto-generate for existing worktree

Example 3: Best Practices Request

User: What are worktree best practices?

Skill: **Quick Best Practices:**

1. **Naming**: Use clear, structured names (myapp-feature-user-auth)
2. **Modes**: Choose mode based on work type (see mode semantics above)
3. **Cleanup**: Remove worktrees when done (/working-tree:destroy)
4. **Metadata**: Always add descriptions
5. **Organization**: One feature = one worktree

**Want more detail?**
- See REFERENCE.md for comprehensive guide
- Invoke working-tree-consultant for strategic advice

Commands: /working-tree:new, /working-tree:list, /working-tree:status, /working-tree:destroy, /working-tree:adopt
Agent: working-tree-consultant for strategic guidance
Documentation: See REFERENCE.md for comprehensive coverage

worktree-guide