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.
Create an isolated git worktree for feature development with automated project setup and safety verification.
NEVER create a project-local worktree without verifying it is git-ignored. Worktree contents tracked by git will cause repository corruption.
Detect Directory → Verify Safety → Create Worktree → Project Setup → Baseline Tests → Report
Check in order:
.worktrees/ or worktrees/ directory in project root — use if found.worktrees/ (Recommended) — keeps worktrees near the code~/.config/code-forge/worktrees/ — outside project, no .gitignore neededCRITICAL: If using a project-local directory:
git check-ignore -q <worktree-dir>
.gitignore immediately, then commit:
echo "<worktree-dir>/" >> .gitignore
git add .gitignore && git commit -m "chore: add worktree directory to .gitignore"
Global directory: skip this step.
# 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.
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.
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
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
$ /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/cleanup
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.