moai-workflow-worktree

Manages Git worktrees for parallel SPEC development with isolated workspaces and branch registration.

Updated Mar 22, 2026
One-click install
npx skills add https://github.com/taewook486/Masters_degree --skill moai-workflow-worktree-taewook486
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: moai-workflow-worktree
Source: https://github.com/taewook486/Masters_degree/tree/main/.claude/skills/moai-workflow-worktree
Command: npx skills add https://github.com/taewook486/Masters_degree --skill moai-workflow-worktree-taewook486

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Developing multiple SPECs or features on a single Git checkout forces constant branch switching, causes merge conflicts, and blocks parallel work. This Skill creates isolated Git worktrees per SPEC so each feature gets its own workspace, branch, and registry entry without context-switching overhead. ## Core Features & Use Cases - Isolated Worktree Lifecycle: Create, switch, sync, and remove per-SPEC worktrees tracked in a central JSON registry with atomic updates and file locking. - MoAI-ADK Workflow Integration: Works with the /moai plan, /moai run, and /moai sync phases, including the moai cc -w <name> entry pattern and moai worktree done cleanup after PR merges. - Parallel and Team Development: Supports concurrent SPECs, tmux-based teammate spawning via --spawn, selective sync with include/exclude patterns, and conflict resolution strategies. - Use Case: A developer working on SPEC-AUTH-001 and SPEC-PAY-001 simultaneously creates two worktrees, develops each in isolation, syncs both with the base branch, and cleans up merged worktrees automatically. ## Quick Start Ask the assistant to create an isolated worktree for a new SPEC and switch into it to begin parallel development.

Frequently Asked Questions about moai-workflow-worktree

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

FAQPage Schema
How do I develop multiple Git features in parallel without branch switching?▼

Use Git worktrees to give each feature its own directory and branch while sharing one repository. This Skill automates creation, switching, syncing, and cleanup of per-SPEC worktrees through a central registry.

How do I create an isolated worktree for a SPEC in MoAI-ADK?▼

Enter a worktree with `moai cc -w <name>` before running workflow phases; the plan phase does not auto-create worktrees. Short names resolve under .claude/worktrees/, and absolute paths under ~/.moai/worktrees/ are also accepted.

Does the --spawn flag work on Windows?▼

No, --spawn requires tmux, which is POSIX-only, so it reports a missing binary error on Windows. Entering a worktree in place with the -w flag works on every platform.

When should worktrees be cleaned up after development?▼

Run `moai worktree done SPEC-XXX` only after both the run PR and sync PR have merged. Stale worktrees left behind accumulate branches and confuse git worktree list, so always prune after use.

Why does worktree sync fail with uncommitted changes?▼

Sync aborts when the worktree has uncommitted changes to prevent data loss. Commit your changes first, or use the force flag; conflicts can be handled with interactive or auto-resolve strategies.

Should read-only agents use worktree isolation?▼

No, read-only agents cannot write because their tools omit Write/Edit, so isolation adds overhead with no benefit. Reserve worktree isolation for implementation agents that modify files.