samzong/gmc/gmc

IRON LAW: ALL WORKTREE OPERATIONS MUST USE gmc wt <subcommand>. NEVER INVENT gmc add, gmc rm, gmc prune, gmc clone, OR OTHER TOP-LEVEL WORKTREE COMMANDS.

gmc

Use $ARGUMENTS and the user's words to route into exactly one mode.

Copy this checklist and check off items as you complete them:

• [ ] Step 0: Parse intent [BLOCKING]
• [ ] Classify the request as commit, wt add, wt prune, wt share, wt sync, wt rm, wt ls, wt dup, wt pr-review, or tag
• [ ] If the intent is unclear, ask one focused question before running commands
• [ ] Step 1: Validate context [BLOCKING]
• [ ] Confirm gmc exists
• [ ] Confirm the current directory is a git repo when the command needs repo context
• [ ] If the action depends on GitHub state, confirm gh works first
• [ ] Step 2: Preview plan [REQUIRED]
• [ ] Show the exact command you plan to run
• [ ] For destructive or bulk actions, prefer --dry-run first
• [ ] Step 3: Execute exactly one workflow
• [ ] commit
• [ ] wt add
• [ ] wt prune
• [ ] wt share
• [ ] other gmc wt subcommand or tag
• [ ] Step 4: Report result
• [ ] State the exact command run
• [ ] Report the created path, cleaned worktrees, synced resources, or generated message
• [ ] State what was not run

Routing

• commit uses top-level gmc
• Any worktree action uses gmc wt <subcommand>
• If the user says gmc add, translate it to gmc wt add and say so
• If the user wants generic git help without gmc, do not use this skill

Common commands

• gmc
• gmc -y
• gmc -a -y
• gmc -a -y -p "context"
• gmc --dry-run
• gmc wt add <name>
• gmc wt add <name> --sync
• gmc wt add <name> -b <branch>
• gmc wt ls
• gmc wt list -A
• gmc wt rm <name>
• gmc wt rm -D <name>
• gmc wt prune
• gmc wt sync
• gmc wt share ls
• gmc wt share add <path> --strategy copy
• gmc wt share add <path> --strategy link
• gmc wt share sync
• gmc tag

Workflow: commit mode

• Use top-level gmc, not gmc wt
• Default to interactive gmc unless the user explicitly wants automation
• Ask before gmc -a -y because it stages all files and auto-confirms
• Use gmc --dry-run when the user wants a suggested message without committing

Workflow: create worktree

• Read worktree.root only from global configuration, alongside shared; project files cannot set it.
• New add, dup, and PR worktrees use <root>/<owner>/<repo>/<repo>--<name>; owner comes from origin or the repository directory's parent.
• If root is missing, warn and use the old location without creating root; clone's initial main worktree stays in place.
• Native Git locks protect global worktrees. Before direct git worktree remove or git worktree move, unlock them or use -f -f.
• Offline gmc wt rm and gmc wt prune preserve Git metadata and branches, including with --force. gmc manages its own locks and keeps manual locks.

• Use gmc wt add <name>
• Use -b <branch> only if the user provided a base branch or asked for one
• Use --sync only when the user wants the latest base first
• After creation, report the worktree path
• When you need the result programmatically, run gmc wt add <name> -o json, gmc wt add --pr <number> -o json, or gmc wt dup [N] -o json:

stdout is an array of {name, path, branch, base, created, error, warnings}. Continue with items where created is true, even if the command exits non-zero; report error and warnings

• gmc wt list -o json adds allocated_bytes; when a size cannot be measured it is omitted and

issues: [{source: "size", code, message}] explains why

Workflow: prune merged worktrees

• Run gmc wt prune --dry-run first to preview
• Use gmc wt prune --all --pr-aware --dry-run to preview cleanup across repositories with linked worktrees in the home directory
• Use gmc wt prune --pr-aware to check PR state before pruning
• Use gmc wt prune --branches when the user wants stale local branches without worktrees cleaned too
• Ask before actual removal
• Use --force only with explicit user approval

Workflow: shared resources

• For discovery, run gmc wt share discover --dry-run
• Use gmc wt share discover --auto only with explicit approval
• For manual control, use gmc wt share add, gmc wt share ls, gmc wt share rm, or gmc wt share sync
• Prefer copy for env files or local config
• Prefer link for large identical directories such as node_modules or .venv
• Build output directories (target, build, dist, .next, .nuxt) cannot be linked — use copy or leave them unshared

Confirmation gates

• Ask before gmc -a -y
• Ask before gmc wt rm -D <name>
• Ask before any non-dry-run prune
• Ask before gmc wt share discover --auto
• Ask before --force

Do not

• Do not run gmc add, gmc rm, gmc prune, gmc clone, or gmc share
• Do not skip dry-run for cleanup when a preview exists
• Do not use --auto, -a -y, -D, or --force without explicit user approval
• Do not guess worktree paths, base branches, or GitHub state
• Do not mix commit mode and worktree mode in the same command