feat(git-worktree): add worktree management command and skill

[EtienneLescot]

User problem

ZCode Desktop has no worktree notion in its UI, so users who want several conversations working one repository in parallel either collide in the same folder (each git checkout rewrites the shared files under the other session) or hand-roll git commands and hit fatal: '<branch>' is already used by worktree at … with no guidance. Tracked in feedback#132 and feedback#220; no existing plugin in the marketplace covers this.

What the plugin provides

• Command /git-worktree:worktree with subcommands:
  • list (default) — table of name / branch / uncommitted file count / path, main worktree marked
  • create <name> [base] — sibling-directory worktree + branch; default base origin/HEAD → main/master → HEAD; warns before occupying a default branch (it would block every other session wanting it); offers .git/info/exclude handling for in-repo locations
  • open <name> — resolves the worktree and prints the exact File → Open Folder path
  • remove <name> — never the main worktree; summarizes uncommitted changes and requires explicit confirmation before --force; Windows "directory held by another process" guidance; merged-only git branch -d afterwards
  • prune — shows stale entries first (--dry-run --verbose), prunes, then only reports orphan directories
• Skill git-worktrees — auto-triggers on worktree questions; encodes the three isolation rules (one branch per worktree, one conversation per worktree, keep the default branch free) and translates git's errors into next actions.

How it was tested

• python scripts/validate.py → OK: 17 plugin(s) validated
• python scripts/build_dist.py → exit 0; git diff --check → clean
• Functional smoke test of every git sequence the command prescribes, on a scratch repository on Windows (git 2.x): sibling creation via worktree add -b, porcelain listing shape, clean/dirty status --porcelain counts, dirty-remove refusal message, --force removal, merged-branch branch -d, prune --dry-run --verbose, and reproduction of the exact 'feat-x' is already used by worktree at … error the command interprets.
• Not yet exercised: live invocation inside the ZCode client UI (slash-command rendering and argument-hint display). Will test from a local marketplace install and report back here if review takes place first.

Version and marketplace registration

• New plugin git-worktree v0.1.0, registered in marketplace.json (category developer-tools); manifest and marketplace name/version/description_i18n are identical, per validator requirements.
• Bilingual user docs: README.md + README_CN.md.

Dependencies, permissions, side effects

• No dependencies beyond git ≥ 2.20 on PATH; plain git invocations only, no shell-specific syntax (Windows-safe).
• Side effects limited to local git operations (worktree add/remove/list/prune, status, diff --stat, branch -d/-D) and directory creation/removal; every destructive step requires explicit user confirmation.
• No network access, no credentials, no hooks, no MCP servers, no scripts.

Licensing

Original work, no third-party code or assets. Apache-2.0, same license as this repository.

[EtienneLescot]

A note for the maintainers / ZCode team

Beyond the plugin itself: if a native worktree experience is on the roadmap (see feedback#132 and feedback#220), I'd be glad to help — with the UX insights that went into shaping this plugin, as a beta tester on Windows, and with code too if a native implementation is ever open to outside contributions.

Things that survived contact with real usage and might transfer to a GUI design:

• The default matters most. Our first version defaulted a bare invocation to list; real usage showed the natural intent is "give me isolation for this session", so v0.1.2 made bare = create with safe defaults. A native switcher likely wants the same asymmetry.
• Error translation beats raw git. Users hit branch is already used by worktree at … and read it as "a git operation is stuck" (the native branch switcher currently reports exactly that generic message). Naming the owning worktree and offering a one-click "open that one instead" dissolves the confusion.
• Guardrails are the feature. Dirty-state confirmation before removal, main-worktree protection, and reporting (never silently deleting) orphan directories are what turned worktrees from a footgun into a daily driver here.

Happy to share more UX notes or test a native implementation whenever it exists. 🤝