moai-workflow-worktree

The moai-workflow-worktree skill provides a robust Git worktree management system engineered for high-performance AI-assisted development. By enabling the creation of fully isolated workspaces for individual software specification (SPEC) tasks, this tool eliminates the overhead of context switching and prevents file-system conflicts during multi-task parallel development. It is designed to integrate deeply with the MoAI-ADK ecosystem, particularly the /moai:1-plan, /moai:2-run, and /moai:3-sync lifecycle, ensuring that Git state remains consistent and manageable even when juggling dozens of experimental feature branches or independent development environments simultaneously.

• Isolated Workspaces: Creates dedicated directory structures for each SPEC, allowing independent file states and branch management without impacting the main project repository.

• Automatic Registry: Maintains a central JSON-based registry that tracks active worktrees, their corresponding SPEC IDs, and metadata such as last sync time and status.

• Seamless ADK Integration: Automates the setup of worktrees during the planning phase and facilitates conflict-free synchronization with base branches during the sync phase.

• Lifecycle Automation: Supports intelligent cleanup for merged or obsolete branches, reducing developer cognitive load and preventing codebase entropy.

• CLI-Driven Workflow: Offers a comprehensive command set including new, switch, go (shell evaluation), sync, status, and config to facilitate rapid navigation between isolated environments.

• Shell Integration: Provides safe path switching via eval-compatible commands, perfect for CI/CD pipelines and automated development scripts.

• Use cases include developing multiple SPECs in parallel, testing experimental features in a sandbox, managing isolated code reviews, and maintaining long-lived development environments without context drift.

• Input requirements: Expects a valid project context initialized within MoAI-ADK. Commands rely on the global configuration root at ~/.moai/worktrees/{ProjectName}/.

• Practical constraints: Ensure your project is a Git repository. Worktrees function best when managed entirely via the provided CLI to keep the central registry metadata in sync with the actual filesystem state.

• Recommended pattern: Utilize the go command in shell scripts for dynamic workspace switching. Always run the clean command after integrating changes to keep your local machine performant.