Skip to content

oprogramadorreal/optimus-claude / skills/worktree

worktree

Verified

Creates 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.

FileKindSize
README.mdmarkdown2.9 KB
SKILL.mdskill md3.1 KB
agents/openai.yamlconfig198 B
references/worktree-setup.mdmarkdown3.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."
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 321kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 321kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 321kUpdated Claude CodeCodexVerifiedInstall
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: 197kUpdated Claude CodeCodexVerifiedInstall