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

name, description

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

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

5. Create worktree

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

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

7. Switch VS Code workspace to worktree

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

8. Store in BigMind

memory_store_fact(
    category="codebase",
    fact=f"{TICKET_KEY}: Worktree at <path>, 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=[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)

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