using-git-worktrees

name	using-git-worktrees
description	Use when starting feature implementation, plan execution, or risky edits that should be isolated. Detects existing isolation, prefers native worktree tools, and falls back to manual git worktrees only when no native tool exists.
activation	Activate when the description trigger applies to the current task.
required_inputs	Task request, relevant repository context, constraints, and authority dependencies.
required_outputs	Skill-specific artifact, verification evidence, canonical verdict, and next action.
authority_dependencies	00_start_here/SOURCE_OF_TRUTH.md; 10_governance/APIVR_EXECUTION_LIFECYCLE.md; 10_governance/source_of_truth/Elite_Build_Goals_v3.md.
evidence_requirements	Executed checks or an honest Unknown, Not Run, or Blocked state for every material claim.

Using Git Worktrees

Ensure work happens in an isolated workspace when risk, scope, or user preference warrants it.

Core rule: detect existing isolation first, prefer native tools second, use manual git worktrees only as fallback.

APIVR Gate

Before creating or entering a worktree:

1. Classify APIVR tier using 50_audits/AUDIT_TIER_ROUTER.md.
2. Identify whether isolation is required by risk, user preference, or implementation plan.
3. Do not create a worktree for Rapid work unless it materially reduces risk or the user asks.

Step 0: Detect Existing Isolation

Run the platform-equivalent of:

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)
BRANCH=$(git branch --show-current)
SUBMODULE_ROOT=$(git rev-parse --show-superproject-working-tree 2>/dev/null)

Interpretation:

• If GIT_DIR != GIT_COMMON and SUBMODULE_ROOT is empty, you are already in a linked worktree. Do not create another one.
• If detached, report that the workspace is externally managed and branch creation may be needed before finishing.
• If in a submodule, treat it as a normal checkout for isolation purposes.

Step 1: Ask Or Honor Preference

If no existing isolation is detected:

• Honor an explicit user or project instruction to use or avoid worktrees.
• If no preference exists and the work is Standard or above, ask before creating one unless the user already requested isolated work.
• For Critical or Forensic work, recommend isolation and explain the risk control.

Step 2: Prefer Native Worktree Tools

Use native harness/workspace tools before manual git commands. Look for tools or commands such as:

• EnterWorktree
• WorktreeCreate
• /worktree
• --worktree
• Codex worktree environments
• Cursor worktree mode
• Gemini launch-time worktree mode
• Replit branch/fork/workspace isolation if available