# Physical Git Worktree Isolation

Developing directly on primary branches (`main` or `master`) or in a single shared
working directory creates severe multi-agent concurrency risks:
- Uncommitted edits from concurrent tasks get overwritten or cross-contaminated.
- Branch switches abort background compilations or active test suites.
- Half-finished experiments accidentally leak into tracking branches.

Physical Git worktrees resolve concurrency at the filesystem level. Each task or
agent operates in an independent physical directory linked to the shared `.git`
repository.

## Standard worktree lifecycle

### 1. Provision a dedicated worktree
From the repository root:

```sh
# Create a new feature branch in an isolated worktree directory
git worktree add -b feat/<task-id> ../worktrees/<task-id> main
cd ../worktrees/<task-id>
```

### 2. Implement, verify, and commit
Inside the isolated worktree:
- Make targeted changes.
- Run local tests and deterministic formatters.
- Stage changes and commit using conventional commit format:
  ```sh
  git add <files>
  git commit -m "feat(module): implement scoped capability"
  ```

### 3. Push and generate pull request
Push the branch to remote origin:
```sh
git push -u origin feat/<task-id>
```

Create the pull request via GitHub CLI using the WHAT-WHY-HOW-LEARNINGS template:
```sh
gh pr create \
  --title "feat(module): implement scoped capability" \
  --body-file docs/reports/<task-id>-telemetry.md \
  --base main \
  --head feat/<task-id>
```

### 4. Cleanup after merge
Once the PR is merged or the task is completed:
```sh
cd ../main-repo
git worktree remove ../worktrees/<task-id>
```

## T3 Code managed worktrees
When operating within the T3 Code control plane, worktree provisioning, branch
isolation, and diff tracking are handled natively per conversation thread. Use
T3 Code's built-in PR tools (`link_pull_request`, `list_thread_pull_requests`) to
associate PRs with the active task.