majiayu000 Start Ticket or Issue
Start working on a Jira ticket or GitHub issue by fetching its details and creating a feature branch in a new worktree based on origin/main. Requirements can come from Jira (e.g. RETIRE-123), GitHub (e.g. owner/repo#1 or issue URL), or unticketed (placeholder RETIRE-1908). For source rules and branch naming see sources.md.
Placeholder Ticket (Unticketed Work)
When the user is working on an unticketed task (no Jira ticket yet), use this placeholder:
- RETIRE-1908 — Use when starting a branch or worktree for work that doesn’t have a ticket. Fetch this ticket for branch naming and worktree setup; the summary/description may be generic. You can still derive a branch name from what the user is doing (e.g. "RETIRE-1908-add-settings-screen") or use the ticket summary if it’s descriptive.
If the user says they’re working on something without a ticket, unticketed work, or similar, use RETIRE-1908 and optionally ask for a short description to build the branch name.
Workflow
Step 1: Get Ticket or Issue
If the user hasn't provided a ticket or issue, ALWAYS use the AskQuestion tool:
- Title: "Which Ticket or Issue?"
- Question: "What would you like to start from?"
- Options:
- id: "jira", label: "Jira ticket (e.g., RETIRE-123)"
- id: "github", label: "GitHub issue (URL or owner/repo#N)"
- id: "unticketed", label: "Unticketed work (use RETIRE-1908)"
Based on the response:
- "jira" → Ask for the Jira ticket number (e.g. RETIRE-123)
- "github" → Ask for the GitHub issue URL or owner/repo#N (or #N if current repo)
- "unticketed" → Use RETIRE-1908 and optionally ask for a brief description for the branch name
If the user already provided a GitHub issue URL or owner/repo#N, treat as GitHub and parse it; no need to ask.
Step 2: Fetch Details
Jira: Use the jira-expert subagent to fetch the ticket by key. Present: key, type, status, priority; summary; description (condensed); sprint/epic if available.
GitHub: Fetch the issue: from URL parse owner/repo and number, then gh issue view N --repo owner/repo --json title,body,state,number; or for #N in current repo use gh issue view N --json title,body,state,number. If gh fails or is unavailable, try mcp_web_fetch with the issue URL (public repos only). Present: number, title, state; body (condensed).
Step 3: Generate Branch Name
Generate a kebab-case summary from the title/summary (lowercase, spaces/special chars → hyphens, no consecutive hyphens, 3-5 words).
- Jira:
[TICKET_KEY]-[kebab-case-summary](e.g. RETIRE-123-add-user-authentication) - GitHub:
issue-[N]-[kebab-case-summary](e.g. issue-1-add-auth-flow) - Unticketed:
RETIRE-1908-[kebab-case-summary]
Step 4: Determine Worktree Paths
[MAIN_WORKTREE]= current workspace root (e.g.,/Users/timmy.garrabrant/Developer/mobile-app)[PROJECT_NAME]= basename of main worktree (e.g.,mobile-app)[BRANCH_NAME]= generated branch name from Step 3[NEW_WORKTREE]=../[PROJECT_NAME]-[BRANCH_NAME]
Step 5: Check Prerequisites
# Check for existing branch
git branch --list [BRANCH_NAME]
# Check for existing worktree
git worktree list | grep [BRANCH_NAME]
If branch or worktree exists, ALWAYS use the AskQuestion tool:
- Title: "Branch/Worktree Already Exists"
- Question: "A branch or worktree named [BRANCH_NAME] already exists. How would you like to proceed?"
- Options:
- id: "switch", label: "Switch to existing worktree"
- id: "suffix", label: "Create with suffix (e.g., [BRANCH_NAME]-2)"
- id: "abort", label: "Abort"
Based on the response:
- "switch" → Navigate to existing worktree
- "suffix" → Create new worktree with numeric suffix
- "abort" → Stop the workflow
Step 6: Create Worktree with New Branch
Always base the new branch on origin/main:
git fetch origin main
git worktree add [NEW_WORKTREE] -b [BRANCH_NAME] origin/main
Step 7: Copy Required Files
Copy .env from the main worktree:
cp [MAIN_WORKTREE]/.env [NEW_WORKTREE]/.env
Step 8: Trust Mise Configuration
Trust the mise configuration in the new worktree to avoid permission errors:
cd [NEW_WORKTREE]
mise trust
This prevents the "Config files are not trusted" error when mise tools are invoked.
Step 9: Install Dependencies
cd [NEW_WORKTREE]
npm install
Monitor progress - this takes several minutes.
Step 10: Report Success
Started [TICKET_OR_ISSUE_REF]: "[Summary]"
Worktree created!
Branch: [BRANCH_NAME]
Location: [NEW_WORKTREE]
Based on: origin/main
Files copied: .env
Mise config: trusted
Dependencies: installed
Step 11: Open in Cursor
ALWAYS use the AskQuestion tool:
- Title: "Open in Cursor?"
- Question: "Worktree created successfully at [NEW_WORKTREE]. Would you like me to open it in a new Cursor window?"
- Options:
- id: "open", label: "Yes, open it"
- id: "skip", label: "No, I'll open it manually"
Based on the response:
- "open" → Run
cursor [NEW_WORKTREE] - "skip" → Continue to next step
Step 12: Prompt to Start Work
ALWAYS use the AskQuestion tool:
- Title: "Start Implementation?"
- Question: "Would you like me to start working on this ticket now?"
- Options:
- id: "start", label: "Yes, start implementing"
- id: "stop", label: "No, I'll do it myself"
Based on the response:
- "start" → Begin analyzing the codebase and implementing the requirements from the ticket description
- "stop" → End the workflow
Error Handling
- Ticket or issue not found: Report the error and ask for a valid Jira key or GitHub issue URL/number
- Branch exists: Ask if user wants to switch to existing worktree or create with suffix
- Worktree exists: Ask to remove/recreate or use existing
- Missing .env in main worktree: Warn user that .env is missing from main worktree and must be created manually
- mise trust fails: Warn about the failure but continue with installation (mise trust is not critical)
- npm install fails: Show error, suggest
rm -rf node_modules && npm install - Dirty working directory: Warn user about uncommitted changes (though worktrees are isolated, this is informational)
Cleanup
When done with a ticket:
# Remove worktree
git worktree remove [NEW_WORKTREE]
# Delete branch if merged
git branch -d [BRANCH_NAME]