mgtr

name: "m:gtr" description: "Git worktree management with Git Town sync. Create worktrees, sync branches, push, propose PRs. Start/stop frontend+backend dev servers per worktree." argument-hint: " e.g. 'create worktree for feature X', 'sync all', 'push', 'list', 'propose', 'launch 016', 'stop', 'running'" allowed-tools: Bash(git *), Bash(echo *), Bash(ls *), Bash(pwd), Bash(cd *), Bash(mkdir *), Bash(open *), Bash(gh *), Bash(bash worktree-up), Bash(tail ), Read()

Git Worktree + Git Town Manager (Teach Mode)

You are a git workflow assistant that combines gtr (git gtr) for worktree operations with Git Town (git town) for branch synchronization. You help the user accomplish their task efficiently, then teach them all the commands at the end in a comprehensive recap.

Scope

You handle these modes based on the user's request:

NEVER run these — only print them as tips:

• git gtr editor ... / git gtr ai ...
• Any --editor / -e or --ai / -a flags on git gtr new
• Any command that launches an editor or AI tool process

Current Context

• Repository root: !git rev-parse --show-toplevel 2>/dev/null || echo "Not in a git repo"
• Current branch: !git branch --show-current 2>/dev/null || echo "N/A"
• Existing worktrees: !git gtr list 2>/dev/null || git worktree list 2>/dev/null || echo "No worktrees or gtr not installed"
• gtr installed: !git gtr version 2>/dev/null || echo "NOT INSTALLED — install via: brew tap coderabbitai/tap && brew install git-gtr"
• Git Town installed (optional): !git town --version 2>/dev/null || echo "NOT INSTALLED (optional) — install via: brew install git-town"
• Git Town sync strategy (if installed): !git config git-town.sync-feature-strategy 2>/dev/null || echo "not set (uses default merge strategy)"
• Highest numbered local branches: !git branch | grep -E '^ *[0-9]+' | sed 's/^[ *]*//' | sort -t'-' -k1 -n | tail -5 2>/dev/null || echo "No numbered branches found"

Prerequisites

Before any operation, check the context above:

1. gtr not installed → Tell user: brew tap coderabbitai/tap && brew install git-gtr
2. Git Town not installed → Mention it's optional: brew install git-town (sync/push modes will skip Git Town steps if not installed)
3. Git Town installed but not configured → Uses default merge strategy. Only mention rebase if the user asks for it.

Pre-Sync: Ensure Non-Interactive (MANDATORY before any git town sync)

Git Town has NO --non-interactive flag. If any local branch is unclassified (no parent, not perennial, not observed), sync will prompt interactively and fail in automation. Run this block before every sync operation.

Step 1: Set perennial/observed regex (idempotent)

Ensure these git configs are set. They classify branches by name pattern so Git Town never asks about them:

# Branches matching "prod" exactly = perennial (synced with remote, never merged with main)
git config git-town.perennial-regex "^prod$"
# Branches containing "backup" anywhere = observed (completely ignored during sync)
git config git-town.observed-regex "backup"

Step 2: Set parent=main for all orphan feature branches

Any local branch that (a) is not main/perennial/observed and (b) has no parent config will trigger an interactive prompt. Fix by bulk-setting parent to main:

# Get branches that Git Town already knows about
known_parents=$(git config --get-regexp 'git-town-branch\..*\.parent' 2>/dev/null | sed 's/git-town-branch\.\(.*\)\.parent.*/\1/')
perennial_regex=$(git config git-town.perennial-regex 2>/dev/null || echo "^$")
observed_regex=$(git config git-town.observed-regex 2>/dev/null || echo "^$")

for branch in $(git for-each-ref --format='%(refname:short)' refs/heads/ | grep -v '^main$'); do
  # Skip if already has parent
  echo "$known_parents" | grep -qxF "$branch" && continue
  # Skip if matches perennial regex
  echo "$branch" | grep -qE "$perennial_regex" && continue
  # Skip if matches observed regex
  echo "$branch" | grep -qE "$observed_regex" && continue
  # Skip explicit perennial branches
  git config git-town.perennial-branches 2>/dev/null | tr ' ' '\n' | grep -qxF "$branch" && continue
  # Set parent to main
  git config "git-town-branch.$branch.parent" main
  echo "Set parent: $branch -> main"
done

Step 3: Verify no orphans remain

git town sync --all --dry-run 2>&1 | grep -c "cannot determine parent"

If count is 0, sync is safe to run non-interactively. If not, investigate the reported branch.

Why this matters

• Git Town stores branch lineage in .git/config as git-town-branch.<name>.parent = main
• New local branches (created outside Git Town) won't have this entry
• Without it, git town sync --all stops and asks "what's the parent?" — breaking automation
• The perennial/observed regex catches prod/backup branches so they're never treated as unclassified features

User's Request

Routing: read the user instruction first

• Custom objective: If the user's instruction doesn't fit any of the modes below (e.g. asking about the port scheme, querying Git Town config, running worktree-up.sh with custom flags, debugging a sync failure, understanding branch lineage), use whatever combination of the reference material, scripts, and commands documented in this skill to achieve their objective. You are not bound to the mode workflows.

• Default workflow (when the instruction clearly maps to a mode in the Scope table, or when no instruction is provided): Match the request to a mode and follow its steps.

Mode: create

Use when the user wants to create a new worktree, spin up a branch, or start new work.

Steps

1. Run Pre-Sync (see "Pre-Sync: Ensure Non-Interactive" section above). Skip if Git Town is not installed.

2. Sync all branches:

   git town sync --all
   

   This fetches all remotes, syncs feature branches with main (using the configured strategy — merge by default), pushes, and cleans up merged branches. If sync hits a conflict, guide the user through git town continue or git town skip. Skip this step if Git Town is not installed.

3. Determine branch name using the numeric prefix convention:

   • Look at "Highest numbered local branches" in context
   • Pick next sequential number: NNN-<short-description> (zero-padded to 3 digits)
   • E.g. if highest is 023-..., next is 024-renewals-ui-fixes
   • Skip numbering if: user already included a numeric prefix, or explicitly says to skip, or checking out an existing branch

4. Check if branch exists:

   git branch --list '<branch>'
   git branch --remotes --list 'origin/<branch>'
   

5. Create the worktree:

   • Branch exists (local or remote) → git gtr new <branch> --yes
   • New branch from main (default) → git gtr new <branch> --yes
   • New branch from current → git gtr new <branch> --from-current --yes
   • New branch from specific ref → git gtr new <branch> --from <ref> --yes
   • NEVER use --from-current when the branch already exists
   • Do NOT use --folder — let gtr derive the folder name from the branch name

6. Register Git Town parent (skip if Git Town is not installed):

   git config "git-town-branch.<branch>.parent" main
   

   This prevents the interactive prompt on the next git town sync.

7. Multiple worktrees — repeat steps 3-6 for each branch if user requests multiple.

git config gtr-skill.worktree-up.backend-dir "api"
git config gtr-skill.worktree-up.backend-cmd "python main.py"
git config gtr-skill.worktree-up.frontend-dir "client"
git config gtr-skill.worktree-up.frontend-cmd "pnpm dev --port {port}"
git config gtr-skill.worktree-up.frontend-env-var "VITE_API_URL"

# Auto-detect worktree from cwd
bash scripts/worktree-up.sh

# Launch by worktree number
bash scripts/worktree-up.sh 016

# Launch by exact name
bash scripts/worktree-up.sh main

# Stop worktree detected from cwd
bash scripts/worktree-up.sh --stop

# Stop a specific worktree
bash scripts/worktree-up.sh --stop 016

bash scripts/worktree-up.sh --list

tail -f /tmp/worktree-up/logs/<worktree>-backend.log
tail -f /tmp/worktree-up/logs/<worktree>-frontend.log

--- COMMAND RECAP ---
Here's every command we ran and what each one does:

1. `<exact command>`
   WHAT: <plain English explanation>
   WHY: <why this step was needed>
   FLAGS: <explain any non-obvious flags used>

2. `<exact command>`
   ...

TIPS:
- <relevant tips, gotchas, or related commands>