---
name: create-worktree
description: Git worktree setup for a PAISY Jira ticket. Supports multi-branch strategy (current/main, current/release, future/release) 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 PAISY 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 delegating to JiraOps)

## Required Inputs

| Input | Source | Example |
|-------|--------|---------|
| `TICKET_ID` | Jira issue key | `ESIDEPAISY-12081` |
| `MODULE` | Ticket context or user input | `eau`, `eubp`, `svmeldungen`, `dabpv`, `rvbea` |
| `TYPE` | Ticket issue type (Story → feature, Bug → bugfix) | `feature` or `bugfix` |
| `SHORT_DESC` | Kebab-case summary (2-4 words) | `leftover-rueckmeldungen` |
| `BASE_BRANCH` | (Optional) Long-lived branch to base work on | `current/main` (default) |

## PAISY Branch Strategy

PAISY uses a multi-branch maintenance rotation (Wartungswechsel). These are the long-lived branches:

| Branch | Purpose | Use as base when... |
|--------|---------|-------------------|
| `current/main` | Current development — **DEFAULT** | Standard features, bugs, tasks |
| `current/release` | Current production release (hotfixes) | Urgent hotfixes that must reach production immediately |
| `future/release` | Next maintenance version | Changes targeting the next Wartungswechsel |
| `past/release` | Previous version (read-only) | **Never** — only receives cherry-picks |

### Base branch → worktree branch prefix mapping

| BASE_BRANCH | Allowed TYPE | Branch prefix |
|-------------|-------------|---------------|
| `current/main` | `feature` or `bugfix` | `current/<TYPE>/...` |
| `current/release` | `bugfix` only | `current/bugfix/...` |
| `future/release` | `feature` or `bugfix` | `future/<TYPE>/...` |

## Steps

### 1. Parse ticket metadata

```
TICKET_KEY  = e.g. "ESIDEPAISY-12081"
TICKET_NUM  = e.g. "12081"  (numeric part only)
```

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:** `current/main`
2. **If user says "hotfix" or ticket priority is Critical/Blocker:** suggest `current/release`
3. **If user says "future", "next Wartung", or "nächste Wartung":** suggest `future/release`

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

### 3. Determine branch name

Derive the branch prefix from the base branch:

| BASE_BRANCH | Branch name pattern |
|-------------|-------------------|
| `current/main` | `current/<TYPE>/<MODULE>/<TICKET_KEY>-<SHORT_DESC>` |
| `current/release` | `current/bugfix/<MODULE>/<TICKET_KEY>-<SHORT_DESC>` |
| `future/release` | `future/<TYPE>/<MODULE>/<TICKET_KEY>-<SHORT_DESC>` |

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

Examples:
- `current/feature/eau/ESIDEPAISY-12081-leftover-rueckmeldungen` (base: `current/main`)
- `current/bugfix/eau/ESIDEPAISY-12261-azvu-package-placeholder` (base: `current/main`)
- `current/bugfix/eau/ESIDEPAISY-12836-pai280-insufficient-fields` (base: `current/release` — hotfix)
- `future/feature/eubp/ESIDEPAISY-13000-next-wartung-prep` (base: `future/release`)

**Validation:** If `BASE_BRANCH` is `current/release` and `TYPE` is `feature`, warn the user — release branches only accept bugfixes.

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

```bash
cd /Users/pplate/git/paisy
git fetch origin <BASE_BRANCH>
```

### 5. Create worktree

```bash
git worktree add /Users/pplate/git/paisy-<TICKET_KEY> -b <BRANCH> origin/<BASE_BRANCH>
```

This creates:
- Worktree directory: `/Users/pplate/git/paisy-<TICKET_KEY>`
- New branch: `<BRANCH>` tracking `origin/<BASE_BRANCH>`

### 6. Verify

```bash
cd /Users/pplate/git/paisy-<TICKET_KEY> && git branch --show-current
```

Expected output: the branch name from step 3.

### 7. Switch VS Code workspace to worktree

```bash
code --reuse-window /Users/pplate/git/paisy-<TICKET_KEY>
```

This opens the worktree folder in the current VS Code window, making it the active workspace.

### 8. Store in BigMind

```python
memory_store_fact(
    category="codebase",
    fact=f"{TICKET_KEY}: Worktree at /Users/pplate/git/paisy-{TICKET_KEY}, 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=[f"/Users/pplate/git/paisy-{TICKET_KEY}"],
    ide_hint="Roo"
)
```

## Expected Output

- Worktree directory exists at `/Users/pplate/git/paisy-<TICKET_KEY>`
- Branch `<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 /Users/pplate/git/paisy-<TICKET_KEY> <BRANCH>` (without `-b`) |
| `origin/<BASE_BRANCH>` not found | Try `git fetch origin` first, then retry. Verify branch name spelling. |
| Directory already exists (not a worktree) | Ask user to remove or choose different path |
| VS Code `code` command not found | Ensure VS Code is in PATH. On macOS: Cmd+Shift+P → "Shell Command: Install 'code' command in PATH" |
| Feature on release branch | Warn user: release branches only accept bugfixes. Suggest `current/main` instead. |

## Cleanup (when ticket is done)

```bash
cd /Users/pplate/git/paisy
git worktree remove /Users/pplate/git/paisy-<TICKET_KEY>
git branch -d <BRANCH>  # only after merge
```