creating-worktree

Git Worktree Creation Workflow

Create isolated git worktrees in .worktrees/ with intelligent branch naming. Combines worktree isolation with the same naming convention as the creating-branch skill.

Usage

This skill is invoked when:

• User runs /worktree or /git:worktree command
• User requests to create a worktree for isolated work

Two Operation Modes

Mode 1: With Description (Manual)

The command takes a description and automatically detects the commit type.

Format: /worktree <description>

Examples:

/worktree add user authentication
# Worktree: .worktrees/user-authentication
# Branch:   feat/001-user-authentication

/worktree fix login bug
# Worktree: .worktrees/login-bug
# Branch:   fix/002-login-bug

/worktree refactor auth service
# Worktree: .worktrees/auth-service
# Branch:   refactor/003-auth-service

Mode 2: Auto-Generate from Changes (No Arguments)

When no arguments provided and no sdlc-develop specs exist, analyze uncommitted changes to generate names automatically.

Format: /worktree (no arguments)

Process:

1. Check for sdlc-develop specs (see Mode 3)
2. If no specs, check for uncommitted changes (both staged and unstaged)
3. If no changes exist, display error and require description
4. If changes exist, analyze to generate description
5. Create worktree with auto-generated names

Mode 3: From SDLC-Develop Spec (Arkhe Integration)

When no arguments provided and sdlc-develop specs exist, create worktree linked to an existing feature spec.

Detection Flow:

1. Check if .arkhe.yaml exists -> read develop.specs_dir (default: arkhe/specs)
2. Scan {specs_dir}/ for existing spec directories
3. If specs found -> present selection via AskUserQuestion
4. Use spec directory name for worktree and branch names

Naming Convention

This skill produces dual names:

The directory uses just keywords (tab-completion friendly). The branch uses the full conventional format (consistent with /create-branch).

Commit Type Detection

Automatically detect commit types from keywords in the description:

If no keyword is detected, defaults to feat.

Keyword Extraction

1. Split description into words
2. Remove stopwords: the, a, an, for, to, in, on, at, by, with, from, and, or, but, this, that
3. Remove commit type keywords (add, fix, create, etc.)
4. Keep first 2-3 meaningful words
5. Convert to lowercase, join with hyphens

Workflow Steps

Step 1: Parse Arguments and Determine Mode

# Check for arguments
DESCRIPTION="$ARGUMENTS"

If $ARGUMENTS is provided -> Mode 1 (manual) If empty -> check for .arkhe.yaml specs (Mode 3), then fall back to auto-generate (Mode 2)

For Mode 2 (auto-generate):

# Check for uncommitted changes
CHANGED_FILES=$(git diff --name-only HEAD 2>/dev/null; git diff --cached --name-only 2>/dev/null)

If no changes, display error: "No arguments and no uncommitted changes. Provide a description: /worktree <description>"

If changes exist, analyze filenames/paths to generate a description.

Step 2: Generate Names

Detect commit type from description keywords (see table above). Default to feat.

Extract keywords: Filter stopwords from description, keep first 2-3 meaningful words, hyphenate.

Find next sequential number:

# Scan ALL branches (shared number space with /create-branch)
MAX_NUM=$(git branch --list | grep -oE '/[0-9]{3}-' | grep -oE '[0-9]{3}' | sort -n | tail -1)
NEXT_NUM=$(printf "%03d" $((10#${MAX_NUM:-0} + 1)))

Assemble names:

• Worktree directory: KEYWORDS (e.g., user-authentication)
• Git branch: TYPE/NUMBER-KEYWORDS (e.g., feat/001-user-authentication)

Step 3: Validate Worktree Directory

# Check directory doesn't already exist
ls .worktrees/$KEYWORDS 2>/dev/null

If it exists, report the conflict and stop. Suggest either a different description or removing the existing worktree.

Also check if the branch already exists:

git branch --list "$TYPE/$NEXT_NUM-$KEYWORDS"

If the branch exists, increment the number and retry.

Step 4: Safety Check - Git Ignore

Verify .worktrees/ is git-ignored:

git check-ignore -q .worktrees 2>/dev/null

If NOT ignored (exit code non-zero), add .worktrees/ to .gitignore:

echo '\n# Worktrees\n.worktrees/' >> .gitignore
git add .gitignore && git commit -m "chore: add .worktrees/ to .gitignore"

Step 5: Ask Base Branch

Use AskUserQuestion to ask which branch to base the worktree on:

• main (Recommended) -- Create from the main branch
• Current branch -- Create from the currently checked out branch
• Other -- User specifies a different branch name

Step 6: Create Worktree

mkdir -p .worktrees
git worktree add ".worktrees/$KEYWORDS" -b "$TYPE/$NEXT_NUM-$KEYWORDS" "$BASE_BRANCH"

Where $BASE_BRANCH is main, HEAD, or the user-specified branch.

Step 7: Confirm Success

Report:

• Worktree path: .worktrees/<keywords>
• Git branch: <type>/<number>-<keywords> (based on <base-branch>)
• List worktrees: git worktree list
• Remove when done: git worktree remove .worktrees/<keywords>

Important Notes

• Sequential Numbering: Shared number space with /create-branch -- scans all branches
• Keyword Extraction: Filters common words, keeps 2-3 meaningful terms
• Lowercase Convention: All names are lowercase with hyphens
• Conventional Commits: Branch names align with conventional commit types
• Dual Naming: Directory name differs from branch name for usability

Supporting Documentation

• WORKFLOW.md - Detailed step-by-step process
• EXAMPLES.md - Real-world examples for all worktree types
• TROUBLESHOOTING.md - Common issues and solutions