メニュー
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.
デフォルトでは、最初にソースを確認する Prompt が選択されています。直接コマンドに切り替えるか、ローカルコピーをダウンロードすることもできます。
インストールを決める前に、SKILL.md と SkillsMP に表示されている付属ファイルをお読みください。
SOC 職業分類に基づく
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
直接コマンドでは確認用 Prompt が省略されます。実行前にソースを確認してください。
npx skills add https://github.com/modu-ai/claude --skill moai-workflow-worktreeコマンドは1行のまま表示されます。コピー前に横へスクロールして全体を確認してください。
ローカルで確認しますか？SkillsMP が現在取得できるファイルをダウンロードできます。
SKILL.md を表示中
Higgsfield MCP 기반 AI 영상을 자연어 요청 한 줄로 생성합니다. 모델·파라미터를 하드코딩하지 않고 라이브 카탈로그(models_explore)를 조회해 호출하므로, 카탈로그가 바뀌어도 드리프트 없이 동작합니다. 다음과 같은 요청 시 사용하세요: - "Higgsfield 영상 만들어줘" - "Veo로 영상" - "Kling으로 영상" - "Seedance로 다이내믹 영상" - "Cinema Studio로 시네마틱 영상" - "Marketing Studio UGC 광고 영상" - "AI 영상 생성" Veo·Kling·Seedance·Cinema Studio·Marketing Studio·Wan·Gemini Omni·Grok 등 계열의 프롬프트 크래프트는 references/prompt-craft/*.md에 출처와 함께 큐레이션돼 있고(계열마다 규칙이 다름 — 범용 공식 없음), 실제 파라미터(모델 id·해상도·비율·길이·비용)는 런타임에 라이브 조회합니다.
Higgsfield MCP 이미지·영상 생성의 공유 코어. media-higgsfield-image / media-higgsfield-video가 로드하는 SSOT(single source of truth)로, 호출 스키마·라이브 카탈로그 조회 프로토콜·공통 크래프트 규칙(R1–R5)·인터뷰 슬롯·잡 수명주기를 정의합니다. 다음과 같은 상황에서 로드됩니다: - media-higgsfield-image 또는 media-higgsfield-video가 호출 계약을 참조할 때 - Higgsfield 모델의 파라미터를 하드코딩하지 않고 런타임 조회해야 할 때 - namespace(mcp__higgsfield__ vs mcp__claude_ai_higgsfield__)를 런타임 해석해야 할 때 이 스킬은 단독 실행 스킬이 아니라 두 소비 스킬이 참조하는 공유 코어입니다.
Higgsfield MCP 기반 AI 이미지를 자연어 요청 한 줄로 생성합니다. 모델·파라미터를 하드코딩하지 않고 라이브 카탈로그(models_explore)를 조회해 호출하므로, 카탈로그가 바뀌어도 드리프트 없이 동작합니다. 다음과 같은 요청 시 사용하세요: - "Higgsfield로 이미지 만들어 줘" - "Soul로 인물 이미지" - "Nano Banana Pro로 카드뉴스 이미지" - "AI 이미지 생성해줘" - "시네마틱 키 비주얼 만들어줘" - "캐릭터 일관성 있는 시리즈 이미지" - "DTC 광고 이미지(Marketing Studio)" Soul·Nano Banana·GPT Image·Seedream·FLUX·Recraft·Marketing Studio 등 계열의 프롬프트 크래프트는 references/prompt-craft/*.md에 출처와 함께 큐레이션돼 있고, 실제 파라미터(모델 id·해상도·비율·비용)는 런타임에 라이브 조회합니다. 프롬프트만 필요하면 moai-coworker의 *-prompt 스킬을 사용하세요.
| 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, mcp__context7__resolve-library-id, mcp__context7__get-library-docs |
| user-invocable | false |
| metadata | {"version":"1.1.0","category":"workflow","status":"active","updated":"2026-01-08","modularized":"true","tags":"git, worktree, parallel, development, spec, isolation"} |
| progressive_disclosure | {"enabled":true,"level1_tokens":100,"level2_tokens":5000} |
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.
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:
Quick Access:
Use Cases:
Purpose: Create isolated Git worktrees for parallel SPEC development.
Key Components:
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. At the worktree root (~/.moai/worktrees/{ProjectName}/), 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
Purpose: Provide intuitive CLI commands for worktree management.
Core Commands:
To create a new worktree for a SPEC, use the new command followed by the SPEC ID and description. To list all worktrees, use the list command. To switch to a specific worktree, use the switch command with the SPEC ID. To get the worktree path for shell integration, use the go command with eval. To sync a worktree with its base branch, use the sync command. To remove a worktree, use the remove command. To clean up merged worktrees, use the clean command. To show worktree status, use the status command. For configuration management, use the config command with get or set subcommands.
Command Categories:
Shell Integration:
For switching to a worktree directory, two approaches work well. The switch command directly changes to the worktree directory. The go command outputs a cd command that can be evaluated by the shell, which is the recommended pattern for shell scripts and automation.
Detailed Reference: Refer to Worktree Commands Module at modules/worktree-commands.md
Purpose: Enable true parallel development without context switching.
Workflow Integration:
During the Plan Phase using /moai:1-plan, the SPEC is created and the worktree new command sets up automatic worktree isolation.
During the Development Phase, the isolated worktree environment provides independent Git state with zero context switching overhead.
During the Sync Phase using /moai:3-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:
Example Workflow:
First, create a worktree for SPEC-001 with a description like "User Authentication" and switch to that directory. Then run /moai:2-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:2-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
Purpose: Seamless integration with MoAI-ADK Plan-Run-Sync workflow.
Integration Points:
During Plan Phase Integration with /moai:1-plan, after SPEC creation, create the worktree using the new command with the SPEC ID. The output provides guidance for switching to the worktree using either the switch command or the shell eval pattern with the go command.
During Development Phase with /moai:2-run, worktree isolation provides a clean development environment with independent Git state preventing conflicts and automatic registry tracking.
During Sync Phase with /moai:3-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. The status command with sync-check option automatically identifies worktrees that need synchronization.
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
Purpose: Launch a Claude or GLM session inside a freshly created worktree based on the current environment (no user prompt).
The --team flag on moai worktree new <SPEC-ID> decides which launch pattern to apply from observable state only. The decision is fully deterministic per BODP (see the constitutional rule / .claude/rules/moai/workflow/branch-origin-protocol.md). The CLI never invokes AskUserQuestion — all four launch patterns are selected from environment signals.
Decision Matrix (4 Canonical Patterns):
| Pattern | tmux session? | CG mode active? | --team flag? | Behavior | LLM |
|---|---|---|---|---|---|
| P1 | yes | yes | yes | New tmux window: cd <wt> && moai glm (inherits CG env from session) | GLM |
| P2 | yes | no | yes | New tmux window: cd <wt> && moai cc | Claude |
| P3 | no | (n/a) | yes | syscall.Exec replaces current process; cwd = worktree path | CG-detected (glm) or Claude (cc) |
| P4 | (n/a) | (n/a) | no | Print paste-ready handoff guidance only; no spawn | (none) |
Detection Logic:
CG mode is true if and only if all three conditions hold:
tmux.NewDetector().InTmuxSession() returns true (the $TMUX env var is set).claude/settings.local.json teammateMode equals "tmux"ANTHROPIC_AUTH_TOKEN OR ANTHROPIC_BASE_URL that includes z.aiIf teammateMode == "tmux" but no GLM env vars are present (a drift case after credential rotation), the CLI emits a stderr warning per the relevant requirement and falls back to P2 (Claude).
Note — two distinct
teammateModefields. TheteammateModein this detection logic is MoAI's own.claude/settings.local.jsonlauncher-selection field ("tmux"/"glm"/"claude"). It is SEPARATE from the Claude Code runtimeteammateModesetting, whose default changed fromautotoin-processas of Claude Code v2.1.179 — with the in-process default, split panes no longer auto-open. As of Claude Code v2.1.181, an idle teammate's agent-panel row hides after 30 seconds and reappears on the next turn. The CC-runtime setting governs teammate display; MoAI's field selects the--teamlauncher. They share the nameteammateModebut are different settings.
Example Invocations:
# Setup: tmux + moai cg session (Claude leader + GLM teammates)
tmux new-session -s moai-dev
moai cg # sets teammateMode=tmux + injects GLM env
moai worktree new SPEC-X-001 --team # P1: new tmux window with moai glm
# In CC-only mode (tmux but no CG)
tmux new-session -s plain
moai worktree new SPEC-Y-001 --team # P2: new tmux window with moai cc
# Outside tmux
moai worktree new SPEC-Z-001 --team # P3: current shell replaced with moai cc (or glm)
# Default (no --team flag)
moai worktree new SPEC-Q-001 # P4: prints "cd <wt> && moai cc" paste-ready guidance
Mutual Exclusion with --tmux:
--team and --tmux are mutually exclusive (cobra enforces at flag parsing). The legacy --tmux flag (from the earlier worktree session creation contract) creates a detached tmux session for the worktree, while --team launches a session in the current pane context with contextual pattern selection. Combining them is rejected.
Swarm Registry:
After successful P1, P2, or P3 launch, the CLI writes .moai/state/swarm/<SPEC-ID>.json (per-user, 0o600) with the following fields:
spec_id, worktree_path, branch, pane_id (empty for P3)mode — one of "tmux-glm", "tmux-cc", "in-progress-glm", "in-progress-cc"created_at (RFC3339 timestamp)created_by_pidThe registry file is the baseline for future moai swarm status/done/kill-all commands (out of scope for this SPEC). P4 does not spawn anything and therefore does not write the registry.
Failure Modes:
--team automatically routes to a stub that notes tmux is unsupported on Windows, then falls back to P4 handoff guidance.Detailed Reference: the canonical worktree team-launch contract — the team-launch entry point, its POSIX and Windows variants, the swarm-registry writer, and the handoff-guidance generator.
Shared Worktree Registry:
Configure team worktree settings by setting the registry type to team mode and specifying a shared registry path accessible to all team members. For developer-specific worktrees within the shared environment, use the developer flag when creating worktrees to prefix entries with the developer name. The list command with all-developers flag shows worktrees from all team members, and the status command with team-overview provides a consolidated team view.
Selective Sync Patterns:
The sync command supports selective synchronization with include and exclude patterns to sync only specific directories or files. For conflict resolution, choose between auto-resolve for simple conflicts, interactive resolution for manual conflict handling, or abort to cancel the sync operation.
Custom Worktree Templates:
Create worktrees with specific setups using the template flag. A frontend template might include npm install and eslint setup with pre-commit hooks. A backend template might include virtual environment creation, activation, and dependency installation. Configure custom templates through the config command by setting template-specific setup commands.
Optimized Worktree Operations:
For faster worktree creation, use the shallow flag with a depth value for shallow clones. The background flag enables background synchronization. The parallel flag with all option enables parallel operations across all worktrees. Enable caching through configuration with cache enable and cache TTL settings for faster repeated operations.
Commands:
Skills:
Tools:
For new SPEC development, use the worktree isolation pattern with auto-setup. The primary approach is worktree isolation and the supporting pattern is integration with /moai:1-plan.
For parallel development across multiple SPECs, use multiple worktrees with shell integration. The primary approach is maintaining multiple worktrees and the supporting pattern is fast switching between them.
For team coordination in shared environments, use shared registry with developer prefixes. The primary approach is the shared registry pattern and the supporting pattern is conflict resolution.
For code review workflows, use isolated review worktrees. The primary approach is worktree isolation for reviews and the supporting pattern is clean sync after review completion.
For experimental features, use temporary worktrees with auto-cleanup. The primary approach is creating temporary worktrees and the supporting pattern is safe experimentation with automatic removal.
Module Deep Dives:
Full Examples: Refer to examples.md External Resources: Refer to reference.md
| Rationalization | Reality |
|---|---|
| "Worktree isolation is overkill for this small change" | Small changes on main cause merge conflicts when parallel work is in progress. Worktrees prevent this. |
| "I will just work on the main branch, it is faster" | Working on main blocks other agents from writing. Worktrees enable parallelism. |
| "Read-only agents need worktree isolation too, for safety" | Read-only agents (mode: plan) cannot write. Adding isolation wastes resources with no benefit. |
| "I can skip worktree cleanup, git handles it" | Stale worktree branches accumulate and confuse git worktree list. Always prune after use. |
| "Absolute paths in agent prompts are fine since the worktree has the same structure" | Absolute paths to the main repo bypass worktree isolation entirely. Use relative paths. |
git worktree list shows no stale worktrees after session ends