git-worktree

In the commands below, `<skill-dir>` is this skill's base directory, announced when the skill loads. Substitute the literal path. On Windows, `py -3` may replace `python`. Use this workflow: `inspect -> plan-create (ensures ignore) -> authorized execute -> record`. ## Routing - Isolation worktree create / list / owned remove / authorized prune: this skill. - Commit, split, checkpoint: `git-commit`. - PR, review, merge, CI, Release, tag-build detached worktree: `gh-pr-release`. - GitHub template bootstrap: `gh-bootstrap`. - Adopt an existing foreign worktree, or add a worktree for an existing branch: refuse. MVP is `--mode new-branch` only. If a native harness worktree tool exists, run the helper first. Call the native tool only when inspect/plan JSON already contains `worktree_path` and `ok_to_create=true`. Do not let the native tool pick an unchecked path. ## 1. Inspect From the repository root: ```text python "<skill-dir>/scripts/worktree_convention.py" inspect --repo-root <abs-repo> [--explicit-root <rel>] [--branch <name>] ``` Read `resolved_root`, `resolution_reason`, `registered_in_repo_roots`, `already_linked`, `gitignore_covers`, and `write_required`. If `already_linked` is true and the user asked to create: report the current tree and stop. Do not nest worktrees. This repository may already have a registered root such as `.claude/worktrees`. Do not invent a second default root. ## 2. Ignore gate (before any add) Matching authority is `git check-ignore -v -z --stdin`. The helper already runs that. A create request authorizes appending one planned `<resolved_root>/` line to the repository `.gitignore`. `plan-create` does that when `write_required` is true. Do not wait for a second confirmation. Do not `git add` or `git commit` the ignore line. - After `plan-create`, `gitignore_covers` must be true before executing `argv`. - If `write_required` is still true (`ignore_gate` in `refusals`), stop. - Global excludes or `.git/info/exclude` alone are not enough. `ensure-ignore` without `--apply` only previews `proposed_line`. `--apply` remains available for an ignore-only repair; create does not need that extra call. ## 3. Plan create (new-branch only) ```text python "<skill-dir>/scripts/worktree_convention.py" plan-create --repo-root <abs-repo> --mode new-branch --branch <name> [--start-point <ref>] [--owner <id>] ``` Execute `argv` only when `ok_to_create` is true. Report `ignore_wrote` and `proposed_line` when the helper appended an ignore rule. The argv is `git worktree add -b <branch> <path> <start-point>`. Do not add `--force` or `--ignore-other-worktrees`. After a successful add: ```text python "<skill-dir>/scripts/worktree_convention.py" record-meta --repo-root <abs-repo> --mode new-branch --branch <name> --owner <id> ``` ## 4. List, remove, prune ```text python "<skill-dir>/scripts/worktree_convention.py" plan-list --repo-root <abs-repo> python "<skill-dir>/scripts/worktree_convention.py" plan-remove --repo-root <abs-repo> --path <path> [--owner <id>] python "<skill-dir>/scripts/worktree_convention.py" plan-prune --repo-root <abs-repo> ``` Remove only when `ok_to_remove` is true. The helper uses `git status --porcelain -uall`, exact registered-path match, lock, in-progress Git state, submodule, and owner checks. `plan-prune` always sets `ok_to_prune=false`. Show `dry_run_output`. Run `git worktree prune` only after this-turn authorization for those exact candidates. ## 5. Report Report the absolute path, branch, resolution reason, ignore source, argv that ran, and any `missing evidence`. Do not claim a Production or Governed verification unless the matching report file exists. ## References - [references/convention.md](references/convention.md) for root resolution and the ignore gate - [references/safety.md](references/safety.md) for ownership, remove/prune, permissions, and rollback