skills.rest
h102-log
h102-logCOMMUNITY
Explore all skills by this author →
GitHub

moai-workflow-worktree

Manages Git worktrees for parallel SPEC development with isolated workspaces and registry tracking.

Updated Jun 18, 2026
Search Tags:#cli#git worktree#parallel development#registry#moai-adk#branch isolation#spec workflow
One-click install
npx skills add https://github.com/h102-log/pdfrag --skill moai-workflow-worktree-h102-log
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: moai-workflow-worktree
Source: https://github.com/h102-log/pdfrag/tree/main/.claude/skills/moai-workflow-worktree
Command: npx skills add https://github.com/h102-log/pdfrag --skill moai-workflow-worktree-h102-log

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Developing multiple features or SPECs simultaneously in a single Git repository forces constant branch switching, stashing, and context reloading, which causes conflicts and lost work. This Skill creates isolated Git worktrees per SPEC so each feature gets its own directory, branch, and environment. ## Core Features & Use Cases - Isolated Worktree Creation: Creates a dedicated worktree per SPEC with independent Git state, dependencies, and configuration, tracked in a central JSON registry. - CLI Command Interface: Provides commands to create, list, switch, sync, remove, and clean worktrees, including shell integration via eval-based navigation. - MoAI-ADK Workflow Integration: Hooks into the Plan-Run-Sync phases so worktrees are auto-created at planning, used during development, and cleaned after merge. - Use Case: A developer working on SPEC-AUTH-001 and SPEC-PAY-001 at the same time creates two worktrees, switches between them instantly, syncs each with the base branch, and removes them automatically after their PRs merge. ## Quick Start Ask the AI to create a new isolated worktree for a SPEC by running the worktree new command with the SPEC ID and a short description, then switch into it to begin 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. The moai-worktree new command creates an isolated worktree per SPEC, and the switch or go commands let you move between them instantly without stashing or reloading context.

How to sync a Git worktree with its base branch?▼

Run the worktree sync command with the SPEC ID to fetch and merge or rebase changes from the base branch. It supports include and exclude patterns, plus auto-resolve, interactive, or abort options for handling merge conflicts.

Does Git worktree support team collaboration with shared state?▼

Yes, by configuring the registry type to team mode with a shared registry path accessible to all developers. Developer-specific prefixes keep worktrees separated, and the list and status commands provide a consolidated team-wide view.

Why does worktree sync fail with uncommitted changes?▼

Sync aborts when the worktree has uncommitted changes to prevent data loss. Commit or stash your changes first, or use the force flag to override, then retry the sync operation.

When should I not use Git worktrees for development?▼

Avoid worktrees for simple single-feature work where a regular branch suffices, or when disk space is constrained since each worktree holds a full project copy. For routine commit and merge operations, use standard Git commands instead.

Related Skills

Explore More Software Engineering Skills→
SorraTheOrcSorraTheOrc

Create Worktree Skill

Create isolated Git worktrees with feature branches and synchronized Worklogs.

Community
Advanced
darkmatterdarkmatter
1

finishing-a-development-branch

Verify tests and complete a development branch via merge, pull request, keep, or discard.

Official
Advanced
modu-aimodu-ai
1.2k

moai-alfred-spec-metadata-validation

Validate SPEC YAML frontmatter for required fields and HISTORY compliance.

Official
Basic
ybbms777ybbms777
1

git-worktree

Create, list, switch, and clean up Git worktrees with environment file copying.

Community
Intermediate