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:

Check for sdlc-develop specs (see Mode 3)
If no specs, check for uncommitted changes (both staged and unstaged)
If no changes exist, display error and require description
If changes exist, analyze to generate description
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:

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

Naming Convention

This skill produces dual names:

Component	Format	Example
Worktree directory	`.worktrees/{keywords}`	`.worktrees/user-authentication`
Git branch	`{type}/{number}-{keywords}`	`feat/001-user-authentication`

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:

Type	Keywords
feat	add, create, implement, new, update, improve
fix	fix, bug, resolve, correct, repair
refactor	refactor, rename, reorganize
chore	remove, delete, clean, cleanup
docs	docs, document, documentation

If no keyword is detected, defaults to feat.

Keyword Extraction

Split description into words
Remove stopwords: the, a, an, for, to, in, on, at, by, with, from, and, or, but, this, that
Remove commit type keywords (add, fix, create, etc.)
Keep first 2-3 meaningful words
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