Worktree Context

Worktree Context Skill

Provides centralized worktree handling for workflow commands, eliminating ~50 lines of inline code per command.

Purpose

Git worktrees enable parallel development by allowing multiple branches to be checked out simultaneously. This skill provides a single source of truth for worktree detection, creation, and context generation.

Quick Reference

# Check if in worktree
bash .spec-flow/scripts/bash/worktree-context.sh in-worktree && echo "yes" || echo "no"

# Get worktree info (JSON)
bash .spec-flow/scripts/bash/worktree-context.sh info

# Create worktree for feature
bash .spec-flow/scripts/bash/worktree-context.sh create "feature" "001-auth" "feature/001-auth"

# Generate Task() agent context block
bash .spec-flow/scripts/bash/worktree-context.sh context "/path/to/worktree"

Output Format

Info Command

Returns JSON with worktree details:

{
  "is_worktree": true,
  "worktree_path": "/path/to/worktrees/feature/001-auth",
  "root_path": "/path/to/main/repo",
  "branch": "feature/001-auth",
  "worktree_type": "feature",
  "worktree_slug": "001-auth"
}

Fields

Compact Pattern (v11.2)

In Command Process Section

Replace 50+ lines of inline worktree detection with this compact reference:

### Step N: Worktree Context (Optional)

**Check worktree using centralized skill** (see `.claude/skills/worktree-context/SKILL.md`):

1. Check preference: `bash .spec-flow/scripts/utils/load-preferences.sh --key "worktrees.auto_create" --default "true"`
2. Check if already in worktree: `bash .spec-flow/scripts/bash/worktree-context.sh in-worktree`
3. If NOT in worktree AND auto_create is true:
   - Create: `bash .spec-flow/scripts/bash/worktree-context.sh create "feature" "$SLUG" "$BRANCH"`
   - Store path in state.yaml: `yq eval ".git.worktree_path = \"$PATH\"" -i state.yaml`
4. For Task() agents, generate context: `bash .spec-flow/scripts/bash/worktree-context.sh context "$PATH"`

For Task() Agent Prompts

When spawning worker agents that need to operate in a worktree:

## Worktree Context

${WORKTREE_PATH ? `
**WORKTREE MODE (CRITICAL)**

Path: ${WORKTREE_PATH}

Execute this FIRST:
\`\`\`bash
cd "${WORKTREE_PATH}"
\`\`\`

All paths are relative to worktree root.
Git commits stay local to worktree branch.
Do NOT merge or push - orchestrator handles that.
` : `
**NORMAL MODE**
Working in main repository.
`}

Commands

Usage in Commands

/feature Command

Before (50+ lines inline):

### Step 1.1.5: Create Worktree (If Preference Enabled)

Check worktree context and preference:

\`\`\`bash
# Check if already in a worktree
IS_WORKTREE=$(bash .spec-flow/scripts/bash/worktree-context.sh in-worktree && echo "true" || echo "false")

# Check worktree auto-create preference
WORKTREE_AUTO=$(bash .spec-flow/scripts/utils/load-preferences.sh --key "worktrees.auto_create" --default "true" 2>/dev/null)
...
# 40 more lines of worktree handling
\`\`\`

After (compact pattern):

### Step 1.1.5: Create Worktree (If Preference Enabled)

**Handle worktree using centralized skill** (see `.claude/skills/worktree-context/SKILL.md`):

1. Check if worktree auto-create is enabled (preference: `worktrees.auto_create`)
2. If NOT in worktree AND enabled: Create via `worktree-context.sh create`
3. Store `worktree_path` in state.yaml for Task() agents
4. Generate context block for worker prompts

/implement Command (Worker Agents)

Include worktree context in worker prompts:

Task(worker):
  prompt: |
    ${WORKTREE_ENABLED ? generate_worktree_context(WORKTREE_PATH) : ""}

    Implement ONE feature from domain memory.
    ...

Path Handling

The Duplication Bug

When operating in worktrees, paths can get duplicated:

• Bad: worktrees/epic/004-app/epics/004-app/epics/004-app
• Good: epics/004-app

Use relative-path to fix:

bash .spec-flow/scripts/bash/worktree-context.sh relative-path "worktrees/epic/004-app/epics/004-app"
# Returns: epics/004-app

Extracting Slugs

Extract slug from any path format:

bash .spec-flow/scripts/bash/worktree-context.sh extract-slug "specs/001-auth/domain-memory.yaml"
# Returns: 001-auth

Related Files

• .spec-flow/scripts/bash/worktree-context.sh - Main implementation (540 lines)
• .spec-flow/scripts/bash/worktree-manager.sh - Worktree lifecycle management
• docs/references/git-worktrees.md - Deep documentation

Benefits