using-git-worktrees

name	using-git-worktrees
description	Use when starting amd-smi feature work, executing an implementation plan, or reviewing a PR that needs an isolated workspace away from the main checkout. Sets up a worktree following the rocm-systems-pr<PR#> convention.

Using Git Worktrees — amd-smi

Ensure work happens in an isolated workspace so the main checkout is never disturbed.

Core principle: Detect existing isolation first. Then use the project convention. Never fight the harness.

Announce at start: "I'm using the using-git-worktrees skill to set up an isolated workspace."

amd-smi Worktree Convention

Worktrees of rocm-systems are created as sibling directories of the main checkout, with the parent-directory and naming pattern:

<parent-of-rocm-systems>/rocm-systems-pr<PR#>          # PR-based work
<parent-of-rocm-systems>/rocm-systems-<branch-name>    # local feature branches

Derive the parent dynamically — do not hard-code it:

MAIN_CHECKOUT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
WORKTREE_PARENT=$(dirname "$MAIN_CHECKOUT")

Never create worktrees inside the main checkout (e.g., ./worktrees/) for this repo — the convention is siblings.

Step 0: Detect Existing Isolation

Before creating anything, check whether you're already in a linked worktree:

GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)

Submodule guard — GIT_DIR != GIT_COMMON is also true inside submodules. Verify:

git rev-parse --show-superproject-working-tree 2>/dev/null

If that returns a path → you're in a submodule, treat as a normal repo.

If GIT_DIR != GIT_COMMON and not a submodule: Already in an isolated worktree. Report path + branch. Skip to Step 3.

If GIT_DIR == GIT_COMMON: Normal checkout. Continue to Step 1.

Step 1: Confirm Consent

If the user hasn't already asked for isolation in the current task:

"Would you like me to set up an isolated worktree at <parent>/rocm-systems-pr<PR#>? It protects your current checkout from changes."

If declined → work in place, skip to Step 3.

Step 2: Create the Worktree

For PR-based work:

PR_NUM=<number>
BRANCH=<branch-name>   # the PR's branch

# Derive parent from the current checkout
MAIN_CHECKOUT=$(git rev-parse --show-toplevel)
WORKTREE_PARENT=$(dirname "$MAIN_CHECKOUT")
WORKTREE="${WORKTREE_PARENT}/rocm-systems-pr${PR_NUM}"

cd "$MAIN_CHECKOUT"

# Fetch the PR branch if not already local
git fetch origin "${BRANCH}:${BRANCH}" 2>/dev/null || git fetch origin "pull/${PR_NUM}/head:${BRANCH}"

git worktree add "${WORKTREE}" "${BRANCH}"
cd "${WORKTREE}/projects/amdsmi"

For a new local feature branch:

BRANCH=<branch-name>

MAIN_CHECKOUT=$(git rev-parse --show-toplevel)
WORKTREE_PARENT=$(dirname "$MAIN_CHECKOUT")
WORKTREE="${WORKTREE_PARENT}/rocm-systems-${BRANCH}"

cd "$MAIN_CHECKOUT"
git worktree add "${WORKTREE}" -b "${BRANCH}" origin/develop
cd "${WORKTREE}/projects/amdsmi"

Sandbox fallback: If git worktree add fails with a permission error, tell the user and work in the current directory instead.

Step 3: Project Setup

Worktrees of rocm-systems already have the full source tree — no npm install / pip install needed for amd-smi work.

If the worktree is for a clean build, invoke the amdsmi-build-install skill to produce a baseline build.

Step 4: Verify Clean Baseline

If the worktree is new, build once to confirm a clean starting state:

# From the amdsmi/ subdirectory inside the worktree
mkdir -p build && cd build
cmake .. -DBUILD_TESTS=ON -DCMAKE_BUILD_TYPE=RelWithDebInfo
make -j"$(nproc)"

If the build fails on origin/develop → report the failure, ask whether to proceed or investigate. Do NOT proceed with feature work on top of a broken baseline.

Quick Reference

Situation	Action
Already in a linked worktree (GIT_DIR != GIT_COMMON)	Skip creation, report path + branch
In a submodule	Treat as a normal repo
PR-based work	rocm-systems-pr<PR#> sibling dir
Local feature branch	rocm-systems-<branch> sibling dir
Sandbox blocks worktree add	Fall back to in-place, tell the user
Build fails on baseline	Report, ask before proceeding

Common Mistakes

Mistake	Fix
Creating a worktree inside the main checkout	Sibling-directory convention only
Skipping Step 0 detection	Always detect existing isolation first
Creating a worktree without consent	Ask first (unless user already said so)
Forgetting to cd into projects/amdsmi after worktree add	The worktree root is rocm-systems-pr<N>, but amd-smi work happens in projects/amdsmi
Proceeding past a failing baseline build	Stop and report

Red Flags — STOP

• Creating a worktree without confirming current isolation status
• Building feature work on a baseline that doesn't compile
• Branching from anything other than origin/develop (unless explicitly told otherwise)
• Force-deleting a worktree without consulting restructure-commits' finishing flow

Cleanup

Cleanup happens at the end of the workflow — see the restructure-commits skill's "Finishing the Branch" section. Don't remove worktrees inline; that's the finishing skill's job.