moai-workflow-worktree
Manages Git worktrees to enable simultaneous development without context switching.
Install
mkdir -p .claude/skills/moai-workflow-worktree && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/7887" && unzip -o skill.zip -d .claude/skills/moai-workflow-worktree && rm skill.zipInstalls to .claude/skills/moai-workflow-worktree
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Git worktree management for parallel SPEC development with isolated workspaces, automatic registration, and seamless MoAI-ADK integrationKey capabilities
- →Create isolated Git worktrees
- →Register worktrees in a central registry
- →Sync worktrees with base branches
- →Automate cleanup of merged worktrees
- →Integrate with MoAI-ADK workflows
How it works
The system creates a separate directory with its own Git state for each SPEC, allowing parallel development without context switching.
Inputs & outputs
When to use moai-workflow-worktree
- →Work on multiple features in parallel
- →Isolate development workspaces
- →Manage parallel branch development
About this skill
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:
- Worktree Registry - Central registry tracking all worktrees
- Manager Layer - Core worktree operations including create, switch, remove, and sync
- CLI Interface - User-friendly command interface
- Models - Data structures for worktree metadata
- 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 worktreemoai 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 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:
First, create a worktree for SPEC-001 with a description like "User Authentication" and switch to that directory. Then run /moai run SPEC-001 to develop in isolation. Next, navigate back to the main repository and create another worktree for SPEC-002 with description "Payment Integration". Switch to that worktree and run /moai run SPEC-002 for parallel development. When needed, switch between worktrees and continue development. Finally, sync both worktrees when ready for integration.
Detailed Reference: Refer to Parallel Development Module at modules/parallel-development.md
4. Integration Patterns - MoAI-ADK Workflow Integration
Purpose: Seamless integration with MoAI-ADK Plan-Run-Sync workflow.
Integration Points:
During Plan Phase Integration with /moai plan, after SPEC creation, enter the worktree through the launcher: moai cc -w <name> works inside it, and moai cc -w <name> --spawn opens it in a new tmux window.
During Development Phase with /moai run, worktree isolation provides a clean development environment with independent Git state preventing conflicts and automatic registry tracking.
During Sync Phase with /moai sync, before PR creation run the sync command for the SPEC. After PR merge, run the clean command with the merged-only flag to remove completed worktrees.
Auto-Detection Patterns:
The system detects worktree environments by checking for the registry file in the parent directory. When detected, the SPEC ID is extracted from the current directory name.
Configuration Integration:
The MoAI configuration supports worktree settings including auto_create for automatic worktree creation, auto_sync for automatic synchronization, cleanup_merged for automatic cleanup of merged branches, and worktree_root for specifying the worktree directory location with project name substitution.
Detailed Reference: Refer to Integration Patterns Module at modules/integration-patterns.md
5. --spawn — Launch a Teammate Session in a New tmux Window
Purpose: start a Claude or GLM session in a worktree without giving up the session you are in.
The launch commands (moai cc, moai glm) normally replace the running shell, which is right for "work here now" but cannot express "keep going and start a teammate alongside me". --spawn re-issues the same command in a new tmux window instead, then returns so the caller keeps working.
Combined with -w <name>, one command opens a teammate in an isolated worktree:
moai glm -w feat-auth --spawn # Explicit all-GLM session in .claude/worktrees/feat-auth
moai cc -w feat-auth --spawn # Claude teammate, same worktree
moai glm -w feat-auth --spawn # all-GLM teammate
Behavior:
- The new window is created detached, so focus stays in the caller's pane. The printed pane id (e.g.
%7) is the handle for switching to it. - The spawned window starts at the project root, so a short
-w <name>value resolves against.claude/worktrees/<name>/(an existing tree of the same name under<MoaiHome>/worktrees/projects/<project-key>is re-entered). --spawnis consumed by MoAI and never reaches Claude Code. Tokens after the--pass-through marker are left untouched.- Arguments are shell-quoted, so a worktree name containing spaces or shell metacharacters reaches the spawned process intact.
Requirements — each is refused with a clear error rather than a silent fallback, because falling back would replace the caller's session, the exact outcome --spawn exists to avoid:
| Missing | Message |
|---|---|
$TMUX (not inside a session) | tmux session required for --spawn |
tmux binary | --spawn requires the tmux binary |
moai binary in PATH | --spawn needs the moai binary in PATH |
No settings are mutated before these checks run, so a refusal leaves the environment untouched. The spawned command performs its own backend setup inside the new window.
Platform note: tmux is POSIX-only, so --spawn is unavailable on Windows and reports the missing binary. Entering a worktree in place with -w works on every platform.
Detailed Reference: the launcher's spawn entry point — flag stripping, command reconstruction with shell quoting, and the tmux window invocation.
Advanced Implementation (10+ minutes)
Synchronization Strategies
moai worktree sync merges the base branch into the worktree by default; --strategy rebase rebases the worktree onto the base instead, and --base selects the base branch. When a sync stops on a conflict, resol
Content truncated.
When not to use it
- →When using read-only agents for planning
Limitations
- →Requires relative paths for write targets to maintain isolation
How it compares
It automates the complex Git worktree lifecycle, including registration and synchronization, which is typically managed manually.
Compared to similar skills
moai-workflow-worktree side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| moai-workflow-worktree (this skill) | 0 | 5mo | Review | Advanced |
| bash-linux | 7 | 9mo | Review | Intermediate |
| create-worktree-skill | 2 | 1y | No flags | Intermediate |
| domain-dns-ops | 2 | 5mo | Review | Intermediate |
Try saying
Example prompts that trigger this skill in your AI assistant.
More by modu-ai
View all by modu-ai →You might also like
bash-linux
davila7
Bash/Linux terminal patterns. Critical commands, piping, error handling, scripting. Use when working on macOS or Linux systems.
create-worktree-skill
disler
Use when the user explicitly asks for a SKILL to create a worktree. If the user does not mention "skill" or explicitly request skill invocation, do NOT trigger this. Only use when user says things like "use a skill to create a worktree" or "invoke the worktree skill". Creates isolated git worktrees with parallel-running configuration.
domain-dns-ops
steipete
Domain/DNS ops across Cloudflare, DNSimple, Namecheap for Peter. Use for onboarding zones to Cloudflare, flipping nameservers, setting redirects (Page Rules/Rulesets/Workers), updating redirect-worker mappings, and verifying DNS/HTTP. Source of truth: ~/Projects/manager.
k8s-operations
rohitg00
kubectl operations for applying, patching, deleting, and executing commands on Kubernetes resources. Use when modifying resources, running commands in pods, or managing resource lifecycle.
makefile-dev-workflow
raphaelmansuy
Unified development workflow for EdgeQuake using Makefile commands. Use when starting services, running tests, or managing the full development stack (database, backend, frontend). Provides simplified alternatives to raw cargo/npm commands.
worktree-manager
p3nGu1nZz
Manages git worktrees for worker containers (create/remove/cleanup). Use when setting up parallel work, repairing worktree state, or cleaning up stale worktrees.