/moai-workflow-worktree

name: moai-workflow-worktree
description: >
  Git worktree management for parallel SPEC development with isolated workspaces,
  automatic branch registration, and seamless MoAI-ADK integration. Use when
  setting up parallel development environments.

when_to_use: >
  Use for git worktree management: parallel SPEC development with isolated
  workspaces, automatic branch registration, branch isolation, and
  seamless MoAI-ADK integration for multiple concurrent SPECs.

license: Apache-2.0
compatibility: Designed for Claude Code
allowed-tools: Read, Write, Grep, Glob
user-invocable: false
metadata:
  version: "1.1.0"
  category: "workflow"
  status: "active"
  updated: "2026-07-10"
  modularized: "true"
  tags: "git, worktree, parallel, development, spec, isolation"

# MoAI Extension: Progressive Disclosure
progressive_disclosure:
  enabled: true
  level1_tokens: 100
  level2_tokens: 5000

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 plan, /moai run, /moai sync workflow
• Smart Synchronization: Automatic sync with base branch when needed
• Cleanup Automation: Automatic cleanup of merged worktrees

Quick Access:

• CLI commands: Refer to Worktree Commands Module at modules/worktree-commands.md
• Management patterns: Refer to Worktree Management Module at modules/worktree-management.md
• Parallel workflow: Refer to Parallel Development Module at modules/parallel-development.md
• Integration guide: Refer to Integration Patterns Module at modules/integration-patterns.md
• Troubleshooting: Refer to Troubleshooting Module at modules/troubleshooting.md

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:

1. Worktree Registry - Central registry tracking all worktrees 2. Manager Layer - Core worktree operations including create, switch, remove, and sync 3. CLI Interface - User-friendly command interface 4. Models - Data structures for worktree metadata 5. Integration Layer - MoAI-ADK workflow integration

Registry Structure:

The registry file stores worktree metadata in JSON format. Each worktree entry contains an identifier, file path, branch name, creation timestamp, last sync time, status (active or merged), and base branch reference. The config section defines the worktree root directory, auto-sync preference, and cleanup behavior for merged branches.

File Structure:

The worktree system creates a dedicated directory structure in the user's global home directory. Trees created by `moai worktree new <name>` live under the home projects root (<MoaiHome>/worktrees/projects/<project-key>/<name>/); the L2 persistent registry remains at the worktree root (~/.moai/worktrees/{ProjectName}/), where you will find the central registry JSON file and individual directories for each SPEC. Each SPEC directory contains a .git file for worktree metadata and a complete copy of all project files.

Detailed Reference: Refer to Worktree Management Module at modules/worktree-management.md

---

2. CLI Commands - Complete Command Interface

Purpose: Map each worktree task to the command that actually performs it.

Entering a worktree is the launcher's job — `moai worktree` has no creation verb:

• `moai cc -w <name>` — work inside the worktree
• `moai cc -w <name> --spawn` — open it in a new tmux window, keeping this session

For inspection, use git directly: `git worktree list`.

Management commands, as `moai worktree --help` lists them:

| Command | Purpose | |---|---| | `sync [branch-name]` | Sync worktree with base branch | | `remove [path]` | Remove a worktree | | `clean` | Clean stale worktree references | | `recover` | Repair worktree registry | | `done [branch-name]` | Complete worktree and cleanup | | `snapshot` | Capture working tree state snapshot for guard verification | | `verify` | Verify working tree state against snapshot + check agent response | | `restore` | Restore working tree to a snapshot's HEAD state |

This table is a copy of the help output. `moai worktree --help` is the authoritative list; where the two differ, the help output wins.

Detailed Reference: Refer to Worktree Commands Module at modules/worktree-commands.md. Its command examples predate the current command set; where they differ from the table above, the table and `moai worktree --help` win.

---

3. Parallel Development Workflow - Isolated SPEC Development

Purpose: Enable true parallel development without context switching.

Workflow Integration:

During the Plan Phase using /moai plan, the SPEC is created, and the launcher (`moai cc -w <name>`) enters an isolated worktree for it.

During the Development Phase, the isolated worktree environment provides independent Git state with zero context switching overhead.

During the Sync Phase using /moai sync, the worktree sync command ensures clean integration with conflict resolution support.

During the Cleanup Phase, the worktree clean command provides automatic cleanup with registry maintenance.

Parallel Development Bene