worktree git:20260226.ce66352A

Immutable. This exact content is served forever at /api/v1/blob/4c4643d67bb488ab.

---
name: worktree
description: >
  Use when starting feature work that needs workspace isolation — creates git worktree
  with automatic project setup and baseline test verification. Ensures worktree directory
  is git-ignored and safe. Integrates with code-forge:impl and code-forge:finish.
---

# Code Forge — Worktree

Create an isolated git worktree for feature development with automated project setup and safety verification.

## When to Use

- Starting feature work that should not affect the main workspace
- Before running code-forge:impl to isolate implementation changes
- When you need a clean baseline for testing or experimentation

## Iron Law

**NEVER create a project-local worktree without verifying it is git-ignored.** Worktree contents tracked by git will cause repository corruption.

## Workflow

```
Detect Directory → Verify Safety → Create Worktree → Project Setup → Baseline Tests → Report
```

### Step 1: Detect Worktree Directory

Check in order:
1. Existing `.worktrees/` or `worktrees/` directory in project root — use if found
2. Project CLAUDE.md for worktree preference — use without asking
3. Ask user:
   - **Project-local** `.worktrees/` (Recommended) — keeps worktrees near the code
   - **Global** `~/.config/code-forge/worktrees/` — outside project, no .gitignore needed

### Step 2: Verify Safety (Project-Local Only)

**CRITICAL:** If using a project-local directory:

```bash
git check-ignore -q <worktree-dir>
```

- **Ignored:** Proceed
- **NOT ignored:** Add to `.gitignore` immediately, then commit:
  ```bash
  echo "<worktree-dir>/" >> .gitignore
  git add .gitignore && git commit -m "chore: add worktree directory to .gitignore"
  ```

Global directory: skip this step.

### Step 3: Create Worktree

```bash
# Detect project name
PROJECT_NAME=$(basename "$(git rev-parse --show-toplevel)")

# Create worktree with new branch
git worktree add <worktree-dir>/<feature-name> -b <feature-name>
```

Branch naming: use the feature name provided by the user, prefixed with `feat/` if not already prefixed.

### Step 4: Project Setup

Auto-detect and run setup in the worktree directory:

| Marker | Command |
|--------|---------|
| `package.json` | `npm install` |
| `package-lock.json` | `npm ci` |
| `yarn.lock` | `yarn install` |
| `pnpm-lock.yaml` | `pnpm install` |
| `requirements.txt` | `pip install -r requirements.txt` |
| `pyproject.toml` | `pip install -e .` or `poetry install` |
| `Cargo.toml` | `cargo build` |
| `go.mod` | `go mod download` |
| `build.gradle` | `./gradlew build` |
| `pom.xml` | `mvn install -DskipTests` |

If multiple markers exist, run the most specific one. If none match, skip setup.

### Step 5: Baseline Tests

Run the project's test command to establish a clean baseline:

```bash
# Auto-detect test command from package.json, Makefile, etc.
# Run tests and report results
```

- **All pass:** Report green baseline, proceed
- **Some fail:** Warn user — "Baseline has N failing tests. These are pre-existing, not caused by your changes."
- **No test command found:** Skip, inform user

### Step 6: Report

```
Worktree created:
  Branch:    feat/<feature-name>
  Location:  <worktree-dir>/<feature-name>
  Setup:     npm install (completed)
  Baseline:  42/42 tests passing

Next steps (code-forge workflow):
  /code-forge:impl <feature-name>    Execute implementation tasks
  /code-forge:finish                  When done, merge/PR/cleanup

Next steps (ad-hoc development):
  /code-forge:tdd                    Enforce TDD discipline
  /code-forge:finish                  When done, merge/PR/cleanup
```

## Common Mistakes

- Creating project-local worktree without checking .gitignore
- Skipping baseline tests — pre-existing failures mask new regressions
- Hardcoding setup commands instead of auto-detecting
- Proceeding when baseline tests fail without user acknowledgment