atxtechbro / atxtechbro/dotfiles

Research: Assess git worktree workflows vs alternatives for parallel development

Open
#811 2 comments 0 reactions 0 assignees View on GitHub
research workflow
Dominant language
Shell
Stars
27
Forks
2
PR merge metrics
No merged PRs in 30d

Description

## Problem Statement

Current git worktree workflow "presents as many problems as they solve in terms of git worktrees / tmux / claude code workflows" and causes "all kinds of side effects that are hard to debug and unjoyful."

## Research Questions

### 1. Current Pain Points Analysis
- [ ] Document specific side effects and debugging challenges
- [ ] Identify where workflow friction occurs (branch tracking, session management, etc.)
- [ ] Assess context contamination between sessions
- [ ] Evaluate web preview management issues

### 2. What are AI engineers actually doing in 2025?
- [ ] Research parallel development patterns in AI-assisted workflows
- [ ] Investigate tools like `par`, `hydra`, `uzi` for session management
- [ ] Assess terminal-first vs IDE-centric approaches
- [ ] Study how teams manage multiple Claude Code instances

### 3. Alternative Approaches to Evaluate
- [ ] **Terminal multiplexing**: tmux/screen with single repo
- [ ] **Custom scripts**: Lightweight session management without worktrees
- [ ] **Heavyweight implementations**: Full workspace management tools
- [ ] **Single-session workflows**: Simplified branch switching patterns

### 4. Specific Tool Research
- [ ] `par` - parallel command execution
- [ ] `hydra` - session management
- [ ] `uzi` - workflow automation
- [ ] Native tmux/screen session management
- [ ] Claude Code workspace handling

## Decision Framework

Evaluate each approach against:
1. **Joy factor**: Does it reduce or increase workflow friction?
2. **Debugging**: Are issues easy to identify and resolve?
3. **Setup complexity**: How much overhead to get working?
4. **Maintenance burden**: Does it create ongoing system debt?
5. **AI agent compatibility**: Works well with Claude Code workflows?

## Next Steps

1. **Research phase** (1-2 weeks): Investigate current practices and tools
2. **Prototype phase**: Test 2-3 most promising alternatives
3. **Decision**: Continue with improved worktrees, pivot to alternative, or simplify
4. **Implementation**: Update procedures and tooling based on findings

## Success Criteria

- [ ] Clear understanding of 2025 parallel development patterns
- [ ] Tested alternatives with pros/cons documented
- [ ] Recommendation with migration path (if needed)
- [ ] Updated procedures that increase joy and reduce debugging overhead

## Related

- Current procedure: `knowledge/procedures/worktree-workflow.md`
- Principle: Developer Experience (DevEx) - "Keep joy in the loop"
- Principle: Subtraction Creates Value - removing workflow friction

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reading knowledge/procedures/worktree-workflow.md and inventory the documented git worktree, tmux, and Claude Code workflow pain points. Investigate the listed alternatives and tools, compare them against the five decision criteria, prototype promising options, and finish with a recommendation, migration path, and updated procedures.

Written by the indexing model from the issue text.

Assessment

Tech stack
git, shell
Domain
developer-experience, documentation, tooling
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.