# Worktree Context

> Worktree Context Skill

- Skill: `marcusgoll/worktree-context` (Agent Skill)
- Install (CLI): `npx skillmds@latest add marcusgoll/worktree-context`
- Raw SKILL.md: https://api.skillmd.com/api/skills/marcusgoll/worktree-context/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: marcusgoll (https://skillmd.com/u/marcusgoll)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/marcusgoll/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

```bash
# 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:

```json
{
  "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

| Field | Values | Description |
|-------|--------|-------------|
| `is_worktree` | boolean | Whether currently in a worktree |
| `worktree_path` | string | Absolute path to worktree |
| `root_path` | string | Absolute path to main repository |
| `branch` | string | Current git branch |
| `worktree_type` | `feature`, `epic` | Type of worktree |
| `worktree_slug` | string | Feature/epic slug |

## Compact Pattern (v11.2)

### In Command Process Section

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

```markdown
### 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:

```markdown
## 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

| Command | Purpose |
|---------|---------|
| `in-worktree` | Check if in worktree (exit 0 = yes) |
| `info` | Get current worktree info (JSON) |
| `root` | Get main repository path |
| `create TYPE SLUG BRANCH` | Create new worktree |
| `path SLUG` | Get worktree path for slug |
| `context PATH` | Generate Task() agent context block |
| `run PATH CMD` | Run command in worktree |
| `git PATH ARGS` | Run git command in worktree |
| `merge SLUG` | Merge worktree branch to main |
| `sync PATH` | Sync state files from worktree |
| `cleanup [--dry-run]` | Remove merged worktrees |
| `relative-path PATH` | Extract worktree-relative path |
| `extract-slug PATH` | Extract slug from any path format |

## Usage in Commands

### /feature Command

Before (50+ lines inline):
```markdown
### 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):
```markdown
### 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:

```markdown
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
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
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

| Before | After |
|--------|-------|
| 50+ lines inline per command | 5-10 lines referencing skill |
| Duplicated across 3+ commands | Single source of truth |
| Changes require multiple edits | Changes require 1 skill edit |
| Worktree bugs scattered | Worktree bugs centralized |