moai-workflow-worktree

Manage Git worktrees for parallel SPEC development across MoAI-ADK phases.

Updated Jan 16, 2026

Search Tags:#automation #workflow #registry #git-worktree #parallel-development #moai-worktree #SPEC-management

Ready to run

npx skills add https://github.com/yarang/fastapi-error-code --skill moai-workflow-worktree-yarang

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: moai-workflow-worktree
Source: https://github.com/yarang/fastapi-error-code/tree/main/.claude/skills/moai-workflow-worktree
Command: npx skills add https://github.com/yarang/fastapi-error-code --skill moai-workflow-worktree-yarang

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill provides centralized management of Git worktrees to support true parallel SPEC development by isolating worktrees, automatically registering them, and integrating with the MoAI-ADK workflow.

Core Features & Use Cases

Isolated Workspaces: Each SPEC gets its own worktree, preventing cross-contamination between development efforts.
Automatic Registration: A central registry tracks all active worktrees for fast discovery and coordination.
Parallel Development: Enables multiple SPECs to be developed concurrently without context switching.
MoAI-ADK Integration: Seamless interaction with /moai:1-plan, /moai:2-run, and /moai:3-sync to streamline planning, execution, and synchronization.
Cleanup & Sync: Automated or guided cleanup of completed worktrees and synchronization with base branches.

Quick Start

Plan a new SPEC and create a worktree: /moai:1-plan "Description of SPEC" --worktree
Switch to the worktree: moai-worktree switch SPEC-XXX
Develop in isolation: moai-worktree go SPEC-XXX (or eval $(moai-worktree go SPEC-XXX)) and run /moai:2-run SPEC-XXX
Sync and cleanup when done: moai-worktree sync SPEC-XXX; moai-worktree remove SPEC-XXX

Frequently Asked Questions about moai-workflow-worktree

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I manage git worktrees for parallel SPEC development without branch interference?▼

Git worktrees for parallel SPEC development are managed through a registry-backed system that creates isolated workspaces per SPEC. This prevents cross-contamination between efforts and ensures conflict-aware synchronization with minimal interference to main branches.

What is the best way to isolate multiple SPEC workspaces in a single repository?▼

The best way to isolate multiple SPEC workspaces is using a template-driven worktree creation process. Each SPEC receives its own isolated worktree registered in a central registry for fast discovery and coordination across parallel development efforts.

How do I create and switch to a SPEC worktree during development?▼

To create and switch to a SPEC worktree, you plan the SPEC with an automated worktree creation flag, then use a switch command to navigate to the isolated workspace. Finally, evaluate the go command to develop and execute the SPEC within that environment.

How does worktree synchronization handle conflicts with the main branch?▼

Worktree synchronization handles conflicts through a conflict-aware sync phase that integrates with the main workflow. It guides synchronization of completed worktrees with base branches to ensure minimal interference before automated cleanup occurs.

Do I need the MoAI-ADK workflow to use parallel worktree management?▼

Parallel worktree management is designed to apply across the MoAI-ADK workflow, seamlessly interacting with Plan, Run, and Sync phases. It satisfies requirements for a registry-backed creation process and per-worktree isolation within that specific ecosystem.