oprogramadorreal/optimus-claude / skills/worktree
worktree
VerifiedCreates a git worktree for isolated parallel development — new branch in a separate directory with project setup and test baseline. Enables multiple Claude Code sessions on different tasks simultaneously. May append .worktrees/ to .gitignore (left unstaged); never commits or pushes. Multi-repo aware. Use when you need to work on something else without disturbing current work.
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 2.9 KB |
| SKILL.md | skill md | 3.1 KB |
| agents/openai.yaml | config | 198 B |
| references/worktree-setup.md | markdown | 3.5 KB |
references/worktree-setup.md
View on GitHub# Worktree Setup Procedure
Shared reference consumed by the `worktree` and `tdd` skills. The caller runs the detection guard first, then the Setup procedure.
## Worktree detection guard
Run `git worktree list`. If the current working directory is inside a **linked** worktree (any entry other than the first, main one), skip worktree creation entirely and report the detection result — including `<worktree-path>` — to the calling skill, which defines the user-facing message and next action. This prevents recursive worktrees. Otherwise proceed with Setup.
## Setup
The caller provides `<branch-name>` (already created) and `<original-branch>` (the branch the main workspace must end on).
1. **Derive the worktree directory name**: `<worktree-dir>` = branch name with `/` replaced by `-` (e.g., `feat/add-login` → `feat-add-login`).
2. **Create `.worktrees/` and ensure Git actually ignores its contents**. Run from the target repository root; a comment containing `.worktrees` is not an ignore rule:
```bash
mkdir -p .worktrees || exit 1
if git check-ignore -q -- .worktrees/.optimus-ignore-check; then
:
else
ignore_status=$?
[ "$ignore_status" -eq 1 ] || exit "$ignore_status"
printf '\n.worktrees/\n' >> .gitignore || exit 1
git check-ignore -q -- .worktrees/.optimus-ignore-check || exit 1
fi
```
Preserve existing `.gitignore` bytes and index entries; the leading newline keeps the added rule separate even when the existing file has no final newline. Leave the rule unstaged and report it as an owned setup change for a later commit. If ignore verification fails, stop setup and report the Git error rather than creating an unignored worktree.
3. **Switch the main workspace back** if the current branch is not `<original-branch>` (e.g., the caller used `git checkout -b`): `git checkout <original-branch>`. Skip if already on it.
4. **Create the worktree**:
```bash
git worktree add .worktrees/<worktree-dir> <branch-name>
```
5. **Run project setup**: detect the project's setup command from `CLAUDE.md` or manifest files (`package.json`, `pyproject.toml`, `Makefile`, etc.) and run it inside the worktree directory. If none is detected, skip silently.
6. **Verify the test baseline**: run the test command inside the worktree. If no test command is detected, note "no test command detected" in the report. If the baseline fails, the failures are pre-existing — the worktree starts from the same commit as the main workspace. Do not block or remove the worktree; report "failing (pre-existing — N failures)" so the failures are not later attributed to new work.
## Failure handling
If Setup fails before the worktree exists (steps 2-4), report the Git error and any `.gitignore` rule step 2 added, then return to the caller, which decides what happens to `<branch-name>`. From step 3 on, the main workspace is on `<original-branch>`.
## Cleanup
When the caller offers cleanup (after the work is merged or pushed):
1. Switch to the main workspace directory (the parent of `.worktrees/`)
2. Remove the worktree: `git worktree remove .worktrees/<worktree-dir>`
- If removal fails due to uncommitted changes, inform the user: commit or discard them first, or use `git worktree remove --force .worktrees/<worktree-dir>` to discard and remove
3. If `.worktrees/` is now empty, remove it: `rmdir .worktrees 2>/dev/null`
If the user prefers to keep the worktree, skip cleanup and note: "Worktree `.worktrees/<worktree-dir>` is still active. Remove it with `git worktree remove .worktrees/<worktree-dir>` when done."
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |