Worktree

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.