MoAI Worktree Management

Git worktree management system for parallel SPEC development with isolated workspaces, automatic registration, and seamless MoAI-ADK integration.

Core Philosophy: Each SPEC deserves its own isolated workspace to enable true parallel development without context switching overhead.

Quick Reference (30 seconds)

What is MoAI Worktree Management? A specialized Git worktree system that creates isolated development environments for each SPEC, enabling parallel development without conflicts.

Key Features:

• Isolated Workspaces: Each SPEC gets its own worktree with independent Git state

• Automatic Registration: Worktree registry tracks all active workspaces

• Parallel Development: Multiple SPECs can be developed simultaneously

• Seamless Integration: Works with /moai:1-plan , /moai:2-run , /moai:3-sync workflow

• Smart Synchronization: Automatic sync with base branch when needed

• Cleanup Automation: Automatic cleanup of merged worktrees

Quick Access:

• CLI commands → Worktree Commands Module

• Management patterns → Worktree Management Module

• Parallel workflow → Parallel Development Module

• Integration guide → Integration Patterns Module

• Troubleshooting → Troubleshooting Module

Use Cases:

• Multiple SPECs development in parallel

• Isolated testing environments

• Feature branch isolation

• Code review workflows

• Experimental feature development

Implementation Guide (5 minutes)

1. Core Architecture - Worktree Management System

Purpose: Create isolated Git worktrees for parallel SPEC development.

Key Components:

• Worktree Registry - Central registry tracking all worktrees

• Manager Layer - Core worktree operations (create, switch, remove, sync)

• CLI Interface - User-friendly command interface

• Models - Data structures for worktree metadata

• Integration Layer - MoAI-ADK workflow integration

Registry Structure:

{ "worktrees": { "SPEC-001": { "id": "SPEC-001", "path": "/Users/goos/worktrees/MoAI-ADK/SPEC-001", "branch": "feature/SPEC-001-user-auth", "created_at": "2025-11-29T22:00:00Z", "last_sync": "2025-11-29T22:30:00Z", "status": "active", "base_branch": "main" } }, "config": { "worktree_root": "/Users/goos/worktrees/MoAI-ADK", "auto_sync": true, "cleanup_merged": true } }

File Structure:

~/worktrees/MoAI-ADK/ .moai-worktree-registry.json # Central registry SPEC-001/ # Worktree directory .git # Git worktree metadata (project files) # Complete project copy SPEC-002/ # Another worktree .git (project files)

Detailed Reference: Worktree Management Module

2. CLI Commands - Complete Command Interface

Purpose: Provide intuitive CLI commands for worktree management.

Core Commands:

Create new worktree for SPEC

moai-worktree new SPEC-001 "User Authentication System"

List all worktrees

moai-worktree list

Switch to specific worktree

moai-worktree switch SPEC-001

Get worktree path for shell integration

eval $(moai-worktree go SPEC-001)

Sync worktree with base branch

moai-worktree sync SPEC-001

Remove worktree

moai-worktree remove SPEC-001

Clean up merged worktrees

moai-worktree clean

Show worktree status

moai-worktree status

Configuration management

moai-worktree config get moai-worktree config set worktree_root ~/my-worktrees

Command Categories:

• Creation: new

• Create isolated worktree

• Navigation: list , switch , go

• Browse and navigate

• Management: sync , remove , clean

• Maintain worktrees

• Status: status

• Check worktree state

• Configuration: config

• Manage settings

Shell Integration:

Direct switching

moai-worktree switch SPEC-001

Shell eval pattern (recommended)

eval $(moai-worktree go SPEC-001)

Output example:

cd /Users/goos/worktrees/MoAI-ADK/SPEC-001

Detailed Reference: Worktree Commands Module

3. Parallel Development Workflow - Isolated SPEC Development

Purpose: Enable true parallel development without context switching.

Workflow Integration:

1. Plan Phase (/moai:1-plan): SPEC creation moai-worktree new SPEC-XXX Automatic worktree setup

2. Development Phase: Isolated worktree environment Independent Git state Zero context switching

3. Sync Phase (/moai:3-sync): moai-worktree sync SPEC-XXX Clean integration Conflict resolution

4. Cleanup Phase: moai-worktree clean Automatic cleanup Registry maintenance

Parallel Development Benefits:

• Context Isolation: Each SPEC has its own Git state, files, and environment

• Zero Switching Cost: Instant switching between worktrees

• Independent Development: Work on multiple SPECs simultaneously

• Safe Experimentation: Isolated environment for experimental features

• Clean Integration: Automatic sync and conflict resolution

Example Workflow:

Create SPEC-001 worktree

moai-worktree new SPEC-001 "User Authentication" cd $(moai-worktree go SPEC-001)

Develop in isolation

/moai:2-run SPEC-001

Create another worktree

cd /path/to/main/repo moai-worktree new SPEC-002 "Payment Integration" cd $(moai-worktree go SPEC-002)

Parallel development on SPEC-002

/moai:2-run SPEC-002

Switch back and continue

moai-worktree switch SPEC-001

Continue development...

Sync and integrate

moai-worktree sync SPEC-001 moai-worktree sync SPEC-002

Detailed Reference: Parallel Development Module

4. Integration Patterns - MoAI-ADK Workflow Integration

Purpose: Seamless integration with MoAI-ADK Plan-Run-Sync workflow.

Integration Points:

• Plan Phase Integration (/moai:1-plan ):

After SPEC creation

moai-worktree new SPEC-{SPEC_ID}

Output guidance

echo "1. Switch to worktree: moai-worktree switch SPEC-{SPEC_ID}" echo "2. Or use shell eval: eval $(moai-worktree go SPEC-{SPEC_ID})"

• Development Phase (/moai:2-run ):

• Worktree isolation provides clean development environment

• Independent Git state prevents conflicts

• Automatic registry tracking

• Sync Phase (/moai:3-sync ):

Before PR creation

moai-worktree sync SPEC-{SPEC_ID}

After PR merge

moai-worktree clean --merged-only

Auto-Detection Patterns:

Check if worktree environment

if [ -f "../.moai-worktree-registry.json" ]; then SPEC_ID=$(basename $(pwd)) echo "Detected worktree environment: $SPEC_ID" fi

Auto-sync on status check

moai-worktree status

Automatically syncs if out of date

Configuration Integration:

{ "moai": { "worktree": { "auto_create": true, "auto_sync": true, "cleanup_merged": true, "worktree_root": "~/worktrees/{PROJECT_NAME}" } } }

Detailed Reference: Integration Patterns Module

Advanced Implementation (10+ minutes)

Multi-Developer Worktree Coordination

Shared Worktree Registry:

Team worktree configuration

moai-worktree config set registry_type team moai-worktree config set shared_registry ~/team-worktrees/MoAI-ADK/

Developer-specific worktrees

moai-worktree new SPEC-001 --developer alice moai-worktree new SPEC-001 --developer bob

Team coordination

moai-worktree list --all-developers moai-worktree status --team-overview

Advanced Synchronization Strategies

Selective Sync Patterns:

Sync only specific files

moai-worktree sync SPEC-001 --include "src/"

Exclude specific patterns

moai-worktree sync SPEC-001 --exclude "node_modules/"

Auto-resolve conflicts

moai-worktree sync SPEC-001 --auto-resolve

Interactive conflict resolution

moai-worktree sync SPEC-001 --resolve-interactive

Worktree Templates and Presets

Custom Worktree Templates:

Create worktree with specific setup

moai-worktree new SPEC-001 --template frontend

Includes: npm install, eslint setup, pre-commit hooks

moai-worktree new SPEC-002 --template backend

Includes: virtual environment, test setup, database config

Custom template configuration

moai-worktree config set templates.frontend.setup "npm install && npm run setup" moai-worktree config set templates.backend.setup "python -m venv venv && source venv/bin/activate && pip install -r requirements.txt"

Performance Optimization

Optimized Worktree Operations:

Fast worktree creation (shallow clone)

moai-worktree new SPEC-001 --shallow --depth 1

Background sync

moai-worktree sync SPEC-001 --background

Parallel operations

moai-worktree sync --all --parallel

Caching for faster operations

moai-worktree config set enable_cache true moai-worktree config set cache_ttl 3600

Works Well With

Commands:

• moai:1-plan - SPEC creation with automatic worktree setup

• moai:2-run - Development in isolated worktree environment

• moai:3-sync - Integration with automatic worktree sync

• moai:9-feedback - Worktree workflow improvements

Skills:

• moai-foundation-core - Parallel development patterns

• moai-workflow-project - Project management integration

• moai-workflow-spec - SPEC-driven development

• moai-git-strategy - Git workflow optimization

Tools:

• Git worktree - Native Git worktree functionality

• Rich CLI - Formatted terminal output

• Click framework - Command-line interface framework

Quick Decision Matrix

Scenario Primary Pattern Supporting

New SPEC development Worktree isolation + Auto-setup Integration with /moai:1-plan

Parallel development Multiple worktrees + Shell integration Fast switching patterns

Team coordination Shared registry + Developer prefixes Conflict resolution

Code review Isolated review worktrees Clean sync patterns

Experimental features Temporary worktrees + Auto-cleanup Safe experimentation

Module Deep Dives:

• Worktree Commands - Complete CLI reference

• Worktree Management - Core architecture

• Parallel Development - Workflow patterns

• Integration Patterns - MoAI-ADK integration

• Troubleshooting - Problem resolution

Full Examples: examples.md External Resources: reference.md

Version: 1.0.0 Last Updated: 2025-11-29 Status: Active (Complete modular architecture)