---
name: start-from-jira-ticket
description: Use when the user shares a Jira ticket and wants to start working on it - derives branch name from ticket ID and title, sets up a git worktree, copies .env if the worktree is outside the project, then kicks off ticket refinement.
---

# Start from Jira Ticket

## Overview

Automates the setup ceremony before working on a ticket: branch naming, worktree creation, environment setup, and refinement hand-off.

**Announce at start:** "Using start-from-jira-ticket to set up the workspace."

## Step 1 — Extract ticket info

From what the user provided, extract:

| Field | Example |
|-------|---------|
| Ticket ID | `SQEG-123`, `SQPD-456`, `SQJG-789` |
| Title | `Add onboarding step to employee lifecycle form` |

The ticket ID prefix is the squad code (e.g. `SQEG`, `SQPD`, `SQJG`), not a fixed prefix. Accept whatever prefix the ticket has.

If either field is missing, ask once before continuing.

## Step 2 — Derive branch and worktree names

Slugify the title: lowercase, words joined by hyphens, strip special chars, max 50 chars.

```bash
# Ticket ID + slugified title
BRANCH="SQEG-123/add-onboarding-step-to-employee-lifecycle-form"
WORKTREE_NAME="SQEG-123-add-onboarding-step-to-employee-lifecycle-form"
```

Show both names to the user and ask for confirmation or edits before creating anything.

## Step 3 — Resolve worktree location

Before following **humand-tech:using-git-worktrees**, detect whether the project uses the sibling convention:

```bash
REPO_ROOT=$(git rev-parse --show-toplevel)
PROJECT=$(basename "$REPO_ROOT")
PARENT=$(dirname "$REPO_ROOT")

if ls -d "$PARENT/$PROJECT-"* 2>/dev/null | grep -q .; then
  # Sibling convention detected — place worktree next to the repo
  WORKTREE_PATH="$PARENT/$PROJECT-$WORKTREE_NAME"
  USE_SIBLING=true
else
  # No sibling convention — follow using-git-worktrees normal flow
  USE_SIBLING=false
fi
```

**If sibling convention detected (`USE_SIBLING=true`):**

Skip the directory-selection flow from `using-git-worktrees` and create the worktree directly:

```bash
git worktree add "$WORKTREE_PATH" -b "$BRANCH"
```

No `.gitignore` check needed — the worktree is outside the repo.

**If no sibling convention (`USE_SIBLING=false`):**

Follow **humand-tech:using-git-worktrees** exactly for directory selection and safety verification. Use `$WORKTREE_NAME` as the subdirectory name and `$BRANCH` as the branch name.

## Step 4 — Copy .env if worktree is outside the repo

A worktree is **outside the repo** when its path does not start with `$REPO_ROOT/`.

```bash
if [[ "$WORKTREE_PATH" != "$REPO_ROOT/"* ]]; then
  # Copy every .env* file found at repo root
  for f in "$REPO_ROOT"/.env*; do
    [ -f "$f" ] && cp "$f" "$WORKTREE_PATH/"
  done
  echo "Copied .env files from $REPO_ROOT to $WORKTREE_PATH"
fi
```

If no `.env` files exist at the repo root, skip silently — do not error.

## Step 5 — Hand off to refinement

Once the worktree is ready, invoke **humand-react:refine-jira-ticket** with the ticket the user originally provided. No extra questions — the context carries over directly.

## Step 6 — Auto-implement Figma design (optional, soft)

After refinement completes, look for a Figma URL in this order:

1. The refinement output (REFINEMENT-*.md or the assistant message).
2. The Jira ticket's `customfield_10107` field (via Atlassian MCP `getJiraIssue` if available).
3. Any figma.com link in the ticket description body.

**If a Figma URL is found and the `humand-design:implement-figma` skill is available**, invoke it with the Figma URL and `targetRepoPath` set to `$WORKTREE_PATH` (resolved in Step 3). If no worktree was created, use `$REPO_ROOT` as `targetRepoPath`. Pass it explicitly — cross-plugin skill calls do not guarantee that cwd matches the worktree.

**If `humand-design:implement-figma` is not available** (plugin not installed), skip silently. Optionally print one line:

> Figma URL detected. Install the `humand-design` plugin to auto-implement Figma designs.

**If no Figma URL is found**, do nothing — refinement is the final step.

This delegation mirrors the existing `humand-react:refine-jira-ticket` hand-off in Step 5: invoke by skill name, no hard dependency.

## Quick reference

| Situation | Action |
|-----------|--------|
| Ticket ID missing | Ask once before continuing |
| Title missing | Ask once before continuing |
| User wants to rename branch | Adjust slug, confirm again |
| Siblings named `{project}-*` exist next to repo | Use sibling location, skip `.gitignore` check |
| No siblings, `.worktrees/` or `worktrees/` exists | Follow `using-git-worktrees` flow |
| Worktree inside repo (`.worktrees/`) | Skip .env copy |
| Worktree outside repo (sibling / global) | Copy all `.env*` from repo root |
| No `.env` at repo root | Skip silently |
| Worktree creation fails | Stop, report error, do not proceed to refinement |
| Figma URL in ticket + `humand-design` installed | Auto-invoke `humand-design:implement-figma` after refinement |
| Figma URL in ticket + `humand-design` NOT installed | Skip silently with a one-line install hint |
| No Figma URL anywhere | Stop after refinement, do nothing extra |

## Common mistakes

- **Skipping name confirmation** — branch names are hard to rename after worktree is created; always show them first.
- **Copying .env unconditionally** — only copy when the worktree is outside the project tree.
- **Proceeding to refinement on failure** — if worktree creation fails, stop and report; don't call refine-jira-ticket.
