Worktree ownership and lifecycle

Use this skill when a task needs checkout isolation, the user requests a worktree, or an existing worktree needs reconciliation/cleanup. The workflow selects it from the ordinary task request, without a separate invocation. Follow the consuming project's instructions, requested checkout and host permissions. A small clear edit can stay in its current checkout.

Create a worktree by work mode

Read the repository's work mode from harness.py resolve first. simple: no worktree; edit in the current checkout. isolated: one worktree per task. parallel: one worktree per active task, at most max_active at once, the rest queued. A small clear edit stays in the current checkout in every mode, and a chat instruction such as "just do it here" overrides the mode for that task. parallel leaves more trees to retire, so run the cleanup report at every closeout.

Resolve the repository and owner first

Inspect the current checkout, branch, HEAD, tracked/untracked changes and git worktree list --porcelain. Resolve the primary clone and common repository from Git registration and the task; the current directory may be a linked worktree. A linked worktree's .git is normally a pointer: do not treat it as an independent clone or derive another -wt root from it.

Preserve unrelated changes and outputs. Do not stash, reset, switch another owner's checkout, copy dirty files or move existing worktrees merely to enforce this convention.

Reuse before cloning or replacing

Before creating a checkout, inspect registered trees, canonical repository/remotes, host attachments and bindings, and any existing reference cache. Reuse a worktree only when its repository, task owner, branch, source and local work fit this task. Confirm that no active session still holds a clean directory before reusing it.

Continue the same task/PR in its owned branch and checkout through review and corrections. Start a new independent task from the verified current default branch and a stack from its exact reviewed dependency. Do not use a historical task branch just because it is current, or create a clone per agent/day/retry.

Sibling location and names

For a primary clone <parent>/<repo>, the default root is its sibling <parent>/<repo-slug>-wt/. Use a stable lowercase hyphenated repo slug; reuse an existing established sibling root rather than creating a case-only alternative. Each worktree has one direct child directory named for its purpose slug, not the branch's slash-separated path:

orbyn-fullstack-skills/repo/
  orbyn/                         primary clone
  orbyn-wt/
    task-rescheduling/           feat/task-rescheduling
    save-retry/                  fix/save-retry
    worktree-policy/             chore/worktree-policy

Targets use the library-root ignored repo/ workspace by default under the nested repository contract: orbyn-fullstack-skills/repo/widget uses sibling repo/widget-wt/<purpose>/. An explicit user location or an established consuming-project policy wins.

Use lowercase letters, digits and hyphens for a short directory slug, normally under 64 characters. Use neutral branch prefixes such as feat/, fix/, chore/, docs/ or refactor/. Do not use agent, assistant, vendor or model branding in a new branch or directory name. Avoid path separators, traversal, spaces, Windows device names and case-only distinctions.

Inspect collisions before choosing a name. If the existing path/branch is unrelated or still owned, choose a distinct purpose or a suffix such as -2; never overwrite a directory, reuse a foreign branch or use force to bypass Git's already-checked-out protection. Keep existing legacy paths/branch names intact.

Keep task branches local and publish deliberately

A worktree and its branch are local Git state; they need no branch on the company's remote. Reuse one owned task branch and worktree through implementation, correction and review instead of creating one per agent, phase or retry. Never push every delegate branch. Serialize operations on shared Git refs, remotes and configuration under one owner.

Keep work local by default. Before any push, follow contribution storage. A local branch is recoverable only while its checkout/Git data remain; preserve valuable unpushed work before cleanup.

Create and verify the selected checkout

Resolve the requested base revision before writes. Continue an existing task/PR from its actual branch or reviewed commit. For new work, use the project's verified default branch/ref, not an unrelated current feature branch or a stale local main. Fetch only when available and authorized; label an offline/cached base as such.

Create a new branch from a verified base with git worktree add -b <branch> <path> <base>. Reuse an existing branch with worktree add <path> <branch> only after ownership/checkout inspection. Avoid -B, --force and duplicate branch checkouts. Verify the final path, branch, base/HEAD and status before editing.

Use the selected worktree as the working directory for every subsequent edit/check. After selecting or switching checkout, reread nested instructions and re-resolve search roots there under action scope.

Preserve project environment files; do not automatically copy secrets or run setup hooks from source. Worktrees share Git objects and may still share databases, ports, fixtures or external services: assign those separately.

If the host denies Git metadata writes, preserve the patch and report delivery as blocked. Never rewrite .git, supply an alternate index or bypass the sandbox.

Designate task verification

Before expensive runs, use the CI owner's feature-worktree gates. Name focused checks, exclusions and conditions for widening in the existing task brief. A new worktree adds no entire-app suite, hosted CI or deployment.

Preserve before cleanup

At a meaningful handoff or terminal delivery result, apply the single task closeout method: reconcile source, commit, push, PR and resource states, decide retention with a reason/review trigger, and assess exact-path retirement separately from permission to remove it.

Never delete another owner's work; unknown ownership means hold. A squash merge or clean status alone does not clear a tree for removal. Retire a tree only through worktree_retire.py, which moves the whole folder to the system Trash and then clears that one Git registration (a restored folder is files only). apply proves only what the report shows: landing, a clean tree, no hidden changes, nothing open and no hold. The owning task or a person still judges ownership, dependent work, shared resources, live previews and recovery, and records any open question as a HOLD.json. A refusal has no automatic force fallback; local/remote ref deletion and tracking prune remain separate.

After a merge, retire the worktree in the same closeout when you have cleanup authority: the tool moves the whole folder, ignored files included, to the Trash, so never hand-run git worktree remove on a live tree, which deletes them. Keep a merged tree only with a named reason and review event, recorded in a HOLD.json at its root. At closeout, before creating a worktree and when harness.py resolve reports low disk, run the workspace cleanup: worktree_retire.py report, then apply. It trashes only finished worktrees, rebuildable caches and idle output, archive and references; everything else in repo/ is report-only.

Return the selected path/base/head, verified delivery state, retained resources, recovery pointers and actual closeout disposition. A dry run changes nothing.

Read when needed

• Pushing, forks, private storage, backups or a public PR: contribution storage.
• Recloning, replacing a checkout or an empty partial cache: checkout replacement.
• In-place, external or bare layouts, delegate branches, unattended runs, denied metadata writes, required dirty primary changes, host worktree tools, search results from another checkout, required statuses at delivery or a worked command example: checkout setup.
• Preview/evidence storage, server/volume ownership or retention classes: artifact lifecycle.