pi_mcps/zoo_backup/work/skills/create-worktree/SKILL.md

name, description

name	description
create-worktree	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

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

5. Create worktree

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

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

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

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

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)

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