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 → ReportStep 1: Detect Worktree Directory
Check in order:
- Existing
.worktrees/orworktrees/directory in project root — use if found - Project CLAUDE.md for worktree preference — use without asking
- 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:
git check-ignore -q <worktree-dir>- Ignored: Proceed
- NOT ignored: Add to
.gitignoreimmediately, then commit: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
# 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 fetch |
go.mod | go mod download |
build.gradle | ./gradlew dependencies |
pom.xml | mvn dependency:resolve |
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:
# 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/cleanupExample
$ /code-forge:worktree user-auth
Worktree created:
Branch: feat/user-auth
Location: .worktrees/user-auth
Setup: npm ci (completed)
Baseline: 42/42 tests passing
Next steps:
/code-forge:impl user-auth Execute implementation tasks
/code-forge:finish When done, merge/PR/cleanupCleanup
To remove a stale worktree manually: git worktree remove <path>. List all worktrees with git worktree list. The /code-forge:finish skill handles cleanup automatically.
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