worktree · diff
git:20260313.0860d48 to git:20260409.eba6a05
12 added, 0 removed. Audit A to A.
---
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
+ ## ⚡ Execution Entry Point (READ THIS FIRST)
+
+ **When this skill is loaded, you MUST immediately begin executing the Workflow below — do not wait, do not summarize, do not ask "what should I do now". Skills are operational manuals, not reference documents.** Read the first executable step, perform it, then the next, etc., until the workflow completes or you reach an `AskUserQuestion` checkpoint.
+
+ If the harness shows you `Successfully loaded skill · N tools allowed`, that message means **the SKILL.md content was injected into your context** — it does NOT mean the skill has run. Skills do not "run" autonomously; you run them by executing the Detailed Steps below.
+
+ If you find yourself about to say "the skill didn't produce output", "skill 仍未输出", "falling back to manual worktree setup", "回退到手动 worktree", or anything similar, **STOP**. You have misunderstood how skills work. Go directly to the first executable step and start.
+
+ The first user-visible action of this skill should be either (a) the output of the first step, or (b) an `AskUserQuestion` if the first step needs disambiguation. Never an apology, never a fallback, never silence.
+
+ ---
+
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 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:
```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
```
## 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