tercel/code-forge/worktree

Code Forge — Worktree

⚡ Execution Entry Point

@../shared/execution-entrypoint.md

For this skill: start at the first executable step. If you catch yourself about to say "falling back to manual worktree setup", STOP and go to the indicated step.

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:

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

# 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:

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/cleanup

Example

$ /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

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.

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