---
name: create-worktree
description: Git worktree setup for a Jira ticket. Supports multi-branch strategy with automatic base branch selection. Use when asked to create a worktree, start work on a ticket, or set up a branch for a Jira issue.
---

# Skill: create-worktree

Git worktree setup for a Jira ticket with correct base branch selection.

## When to use

- User asks to create a worktree for a Jira ticket
- User asks to "start work on" or "set up" a ticket
- Orchestrator delegates worktree creation for a new ticket

## When NOT to use

- Switching to an existing worktree → use `switch-worktree` skill
- Removing a worktree after merge → see Cleanup section below

## Invoked by

🎫 JiraOps mode (or 🪃 Orchestrator)

## Required Inputs

| Input | Source | Example |
|-------|--------|---------|
| `TICKET_ID` | Jira issue key | `PROJECT-123` |
| `MODULE` | Ticket context or user input | Module/component name |
| `TYPE` | Ticket issue type (Story → feature, Bug → bugfix) | `feature` or `bugfix` |
| `SHORT_DESC` | Kebab-case summary (2-4 words) | `fix-auth-timeout` |
| `BASE_BRANCH` | (Optional) Long-lived branch to base work on | `main` (default) |

## Branch Strategy

| Branch | Purpose | Use as base when... |
|--------|---------|-------------------|
| `main` | Current development — **DEFAULT** | Standard features, bugs, tasks |
| `release` | Current production release (hotfixes) | Urgent hotfixes for production |

### Base branch → worktree branch prefix mapping

| BASE_BRANCH | Allowed TYPE | Branch prefix |
|-------------|-------------|---------------|
| `main` | `feature` or `bugfix` | `feature/...` or `bugfix/...` |
| `release` | `bugfix` only | `hotfix/...` |

## Steps

### 1. Parse ticket metadata

```
TICKET_KEY  = e.g. "PROJECT-123"
```

If MODULE or TYPE are not provided, retrieve them from Jira:
- `retrieve_ticket_details(TICKET_KEY)` → read `issuetype` and `summary`
- Map issue type: `Story` / `Task` → `feature`, `Bug` → `bugfix`
- Infer module from summary keywords or ask the user

### 2. Determine base branch

If `BASE_BRANCH` is not explicitly provided, apply this decision logic:

1. **Default:** `main`
2. **If user says "hotfix" or ticket priority is Critical/Blocker:** suggest `release`

When suggesting a non-default base, confirm with the user before proceeding.

### 3. Determine branch name

```
BRANCH = <TYPE>/<MODULE>/<TICKET_KEY>-<SHORT_DESC>
```

Examples:
- `feature/auth/PROJECT-123-oauth2-timeout`
- `bugfix/api/PROJECT-456-null-pointer`
- `hotfix/api/PROJECT-789-critical-fix` (base: `release`)

### 4. Ensure base branch is up to date

```bash
cd <your-repo-path>
git fetch origin <BASE_BRANCH>
```

### 5. Create worktree

```bash
git worktree add <your-repo-path>-<TICKET_KEY> -b <BRANCH> origin/<BASE_BRANCH>
```

This creates:
- Worktree directory: `<your-repo-path>-<TICKET_KEY>`
- New branch: `<BRANCH>` tracking `origin/<BASE_BRANCH>`

### 6. Verify

```bash
cd <your-repo-path>-<TICKET_KEY> && git branch --show-current
```

### 7. Switch VS Code workspace to worktree

```bash
code --reuse-window <your-repo-path>-<TICKET_KEY>
```

### 8. Store in BigMind

```python
memory_store_fact(
    category="codebase",
    fact=f"{TICKET_KEY}: Worktree at <path>, branch {BRANCH}, based on {BASE_BRANCH}"
)
```

### 9. Announce focus

```python
memory_announce_focus(
    session_id=SESSION_ID,
    description=f"Working on {TICKET_KEY} in worktree",
    files=[target_path],
    ide_hint="Roo"
)
```

## Expected Output

- Worktree directory exists
- Branch is checked out, based on `origin/<BASE_BRANCH>`
- VS Code workspace switched to worktree directory
- BigMind fact stored with worktree path and base branch
- Focus announced

## Error Handling

| Error | Resolution |
|-------|------------|
| Worktree already exists | Check if branch matches. If yes, reuse. If no, ask user. |
| Branch already exists | `git worktree add <path> <BRANCH>` (without `-b`) |
| `origin/<BASE_BRANCH>` not found | Try `git fetch origin` first, then retry |
| Directory already exists (not a worktree) | Ask user to remove or choose different path |

## Cleanup (when ticket is done)

```bash
cd <your-repo-path>
git worktree remove <your-repo-path>-<TICKET_KEY>
git branch -d <BRANCH>  # only after merge
```