/worktree

name: worktree
description: >-
  Creates or reuses an isolated AgentsMesh Git worktree from a verified base
  branch, preserves existing changes, and optionally starts the
  worktree-scoped development environment. Use when the user asks for a new
  worktree or isolated work for a feature, fix, investigation, or review.

AgentsMesh Worktree

Create worktrees next to the main checkout under `AgentsMesh-Worktrees`.

Workflow

1. Determine the requested branch name, base branch (default `main`), and whether the task actually needs a running development stack. 2. Inspect repository state and identify the base remote from the user's request, the base branch upstream, or its URL:

   git status --short --branch
   git remote -v
   git worktree list

Preserve all existing changes. Do not stash, reset, commit, or clean the main checkout as a side effect of worktree creation. 3. Fetch the selected base:

   git fetch <base-remote> <base-branch>

4. Derive a filesystem-safe directory name by replacing `/` in the branch with `-`. Use `$(dirname "$repo_root")/AgentsMesh-Worktrees`; do not embed a user-specific absolute path. 5. Check whether the branch or path already exists. If the branch is new:

   git worktree add -b <branch-name> \
     <worktree-root>/<directory-name> \
     <base-remote>/<base-branch>

If the branch already exists and is not checked out elsewhere, attach it without `-b`. Never delete or reset an existing branch to make the command succeed. 6. In the new worktree, verify:

   git status --short --branch
   git log --oneline -3
   git merge-base --is-ancestor <base-remote>/<base-branch> HEAD

7. Start the environment only when runtime verification is needed. Read `references/dev-environment.md`, run the appropriate Bazel lifecycle target, then load and report the generated `deploy/dev/.env` values.

Result

Report the absolute worktree path, branch, base ref and commit, whether the development stack was started, and the generated ports when applicable. Do not remove the worktree automatically; cleanup must preserve uncommitted or unpushed work.