Worktree Workflow

Last Updated: 2026-02-02 Status: 📋 Active Process

Overview

This document defines our workflow for managing features, experiments, and parallel development using git worktrees.

Philosophy: Keep experimental work isolated, track everything with issues, maintain consistency across naming.

Core Principles

1. Issue-First Development - Create GitHub issue before starting work (unless throwaway experiment)
2. Naming Consistency - Issue name, branch name, worktree name, and agent name are synchronized
3. Branch from Main - All worktrees branch from main (unless explicitly branching from experiment)
4. Fast-Forward Merges - Claude coordinates integration using git merge --ff-only
5. PR Closes Issue - Merging a PR should close the associated issue (unless it's an epic with subtasks)
6. Process Serves Velocity - Don't let process slow down quick fixes and small enhancements; git commit messages are sufficient for small work

When to Skip the Full Process

Use experiment/scratch worktrees without issues for:

• Brainstorming sessions - Exploring ideas, testing approaches, prototyping
• Quick fixes - Small bug fixes or tweaks that don't need tracking
• Tiny enhancements - Minor improvements that take < 30 minutes
• Exploratory work - Trying out ideas that might inform future features
• Learning/Research - Testing libraries, patterns, or techniques

How we'll handle these:

• Create worktree with descriptive name: experiment-<topic> or scratch-<idea>
• Work freely, commit with good messages
• Either:
  • Merge directly if the work is valuable (small enough to not need PR review)
  • Delete worktree if it was just exploration
  • Create issue retroactively if it grew into something bigger

Example:

# Brainstorming glassmorphism effects
git worktree add ../worktree/experiment-glassmorphism -b experiment-glassmorphism

# Quick typography fix
git worktree add ../worktree/scratch-font-sizing -b scratch-font-sizing

Experimental work might:

• Inform the specific features we want to build (leads to future issues)
• Get merged directly as a small enhancement (no issue needed)
• Be discarded as a learning experience (no merge)

Philosophy: Good git commit messages > heavyweight process for small work

Workflow Steps

1. Create GitHub Issue

When: Before starting any non-trivial feature or experiment

Process:

1. Discuss feature/experiment with Claude
2. Create GitHub issue with:
   • Title: Clear, concise feature name (e.g., "Ambient Menu")
   • Description: Problem statement, goals, scope
   • Labels: Appropriate tags (enhancement, experiment, bug, etc.)
   • Milestone: If applicable
3. Note the issue number (e.g., #10)

Skip this step only for:

• Quick throwaway experiments we both agree on
• Tiny documentation fixes
• Trivial refactors

2. Determine Naming

Pattern: Convert issue title to kebab-case

Examples:

• "Ambient Menu" → ambient-menu
• "Unified Side Panel" → unified-side-panel
• "AI Text Generation" → ai-text-generation

Synchronized names:

• Issue title: "Ambient Menu"
• Issue label/tag: ambient-menu (if using labels for tracking)
• Branch name: ambient-menu
• Worktree directory: ../worktree/ambient-menu
• Agent name: ambient-menu (if using specialized agent)

Not a hard rule, but strong correlation. Goal is to avoid confusion.

3. Create Worktree + Branch

Command:

# From main repository directory (/Users/tony/code/zus)
git worktree add ../worktree/<branch-name> -b <branch-name>

Example:

git worktree add ../worktree/ambient-menu -b ambient-menu

What this does:

• Creates new branch ambient-menu from current branch (usually main)
• Creates worktree directory at ../worktree/ambient-menu
• Checks out the new branch in the worktree

Branch source:

• Default: Branch from main
• Exception: If building on top of another experiment, branch from that experiment's branch

4. Work in Worktree

Navigate to worktree:

cd ../worktree/ambient-menu

Development:

• Make commits as you develop
• Push branch to GitHub: git push -u origin ambient-menu
• Reference issue in commits: "Implement command palette (#10)"

Running dev server:

• Each worktree has its own working directory
• Run npm run dev in the worktree
• Can run multiple dev servers on different ports if needed

5. Create Pull Request

When: Feature/experiment is ready for review

Process:

1. Push latest changes: git push
2. Create PR using GitHub CLI or web UI
3. Title: Match or reference issue name
4. Description:
   • Summary of changes
   • Reference issue: "Closes #10" or "Part of #5"
   • Test plan
   • Screenshots/demos if applicable
5. Link to issue: Use "Closes #10" to auto-close issue on merge

6. Merge to Main

Process:

1. Review PR (Tony reviews, or self-review if minor)
2. Merge strategy: Fast-forward merge preferred
3. Claude coordinates merge: git merge --ff-only ambient-menu
4. Push to main: git push origin main
5. PR is closed, issue is closed (if "Closes #N" was used)

If fast-forward fails:

• Rebase branch onto main: git rebase main
• Resolve conflicts
• Force push: git push --force-with-lease
• Retry merge

7. Cleanup Worktree

After merge:

# From main repository
git worktree remove ../worktree/ambient-menu

# Delete branch (if no longer needed)
git branch -d ambient-menu
git push origin --delete ambient-menu

Keep worktree if:

• Continuing iteration on feature
• Using as reference for other work

Special Cases

Experiment/Scratch Worktrees

When: Brainstorming, quick fixes, exploration, small enhancements

Process:

• Skip issue creation
• Create worktree with descriptive name:
  • experiment-<topic> - Exploring ideas, prototyping
  • scratch-<idea> - Quick fixes, small tweaks
• Work freely with good commit messages
• Decide outcome:
  • Merge directly to main - If valuable and small
  • Create issue + PR - If it grew into something substantial
  • Delete worktree - If it was just exploration

Examples:

• experiment-glassmorphism - Testing visual styles
• scratch-fix-hover-color - Quick CSS fix
• experiment-keyboard-nav - Prototyping navigation patterns

When to formalize: If experimental work reveals a substantial feature, create an issue retroactively and follow the full workflow for continued development.

Epic Issues with Subtasks

When: Large feature with multiple PRs

Process:

• Create epic issue: "Ambient UI System"
• Create subtask issues: "Ambient Menu", "Ambient Status Line", etc.
• Each subtask gets its own worktree/branch/PR
• PRs reference epic: "Part of #5"
• Close epic only when all subtasks complete

Building on Experiments

When: One experiment depends on another

Process:

• Branch from experiment branch instead of main
• Example:

  cd ../worktree/ambient-menu
  git worktree add ../worktree/ambient-menu-v2 -b ambient-menu-v2
  

• Merge order: ambient-menu → main, then ambient-menu-v2 → main

Naming Convention Reference

Issue Title Format:

• Clear, concise, title case
• Describes the feature/fix
• Example: "Ambient Menu"

Branch/Worktree/Label Format:

• Lowercase kebab-case
• No issue number prefix (keep names clean)
• Example: ambient-menu

Commit Message Format:

• Imperative mood: "Add ambient menu component"
• Reference issue: "Implement keyboard shortcuts (#10)"

Worktree Management

List all worktrees

git worktree list

Current worktrees

• Main: /Users/tony/code/zus (main branch)
• Agent Plugin: ../worktree/agent-plugin (agent-plugin branch)
• (Add new worktrees here as they're created)

Remove a worktree

git worktree remove ../worktree/<name>

Prune stale worktrees

git worktree prune

Benefits of This Workflow

1. Isolation: Experiments don't interfere with main development
2. Traceability: Every feature tracked via issue → branch → PR
3. Consistency: Clear naming makes navigation easy
4. Parallel Work: Multiple experiments can run simultaneously
5. Clean History: Fast-forward merges keep git history linear
6. Context Switching: Easy to switch between experiments without stashing

Example End-to-End Flow

Scenario: Implementing the Ambient Menu feature

1. Create Issue:

   • Title: "Ambient Menu"
   • Description: Command palette triggered by Ctrl+/
   • Issue #10 created

2. Create Worktree:

   git worktree add ../worktree/ambient-menu -b ambient-menu
   cd ../worktree/ambient-menu
   

3. Develop:

   • Implement feature
   • Commit: "Add ambient menu component (#10)"
   • Push: git push -u origin ambient-menu

4. Create PR:

   • Title: "Ambient Menu"
   • Body: "Closes #10"
   • Push and create PR

5. Merge:

   • Review approved
   • Claude: git merge --ff-only ambient-menu
   • Push: git push origin main
   • Issue #10 auto-closed

6. Cleanup:

   git worktree remove ../worktree/ambient-menu
   git branch -d ambient-menu
   

Claude's Role

Claude coordinates:

• Issue creation (drafts title, description, labels)
• Worktree creation (runs git commands)
• Branch naming (ensures consistency)
• Commits (follows conventions)
• PR creation (using gh CLI)
• Merges (fast-forward when possible)
• Cleanup (removes stale worktrees)

Claude ALWAYS:

• Creates issue before worktree (unless throwaway)
• Uses consistent naming across issue/branch/worktree
• References issue numbers in commits and PRs
• Coordinates merges with --ff-only

This is a living document. Update as workflow evolves.