SKILL.md

Announce at start: “I’m using codi-worktrees to choose an isolation strategy.”

When to Activate

• Before codi-plan-execution begins task execution
• User wants to work on a feature without touching the main working tree
• User has multiple features in parallel that need isolation

Skip When

• User wants to finish or merge a branch — use codi-branch-finish
• User wants to commit staged changes — use codi-commit
• User wants to execute the implementation plan — use codi-plan-execution
• User wants to resolve merge conflicts — handle those in the existing tree, not a new workspace
• Change is trivial (typo fix, single-line) and no plan exists — just edit directly

Step 0: Isolation Strategy Decision

Before setting up any workspace, evaluate whether a worktree or a simple branch is the right approach. Do not assume worktrees are always needed.

Gather context

git status --porcelain        # check for uncommitted changes
git worktree list             # check for existing worktrees

Also assess task scope: is this a small targeted change or a large multi-task plan?

Decision criteria

Recommend a simple branch when:

• The change is small (bug fix, config tweak, single feature with few tasks)
• The working tree is clean and no parallel work is active
• The execution method is codi-plan-execution INLINE mode (sequential, same working tree is fine)
• No uncommitted experiments need to be preserved in the current tree

Recommend a worktree when:

• Multiple features need to run in parallel simultaneously
• The working tree has uncommitted work the user wants to preserve
• The execution method is codi-plan-execution SUBAGENT mode (subagents benefit from path isolation)
• The plan has many tasks (roughly 5+) and long-running isolation is valuable
• User explicitly asked for a worktree

Ask the user

Present your recommendation with one-line reasoning, then ask:

I recommend a [worktree / simple branch] for this task because [one-line reason].
Proceed with [worktree / branch], or would you prefer the other approach?

Wait for the user’s answer before continuing.

Path A: Simple Branch

If the user chooses a simple branch:

git checkout -b <branch-name>

Branch naming: follow codi-git-workflow rule conventions (feature/, fix/, chore/ prefix).

Report:

Branch <branch-name> created. Ready to work.

Skip Steps 1-5 below. The working tree is already set up.

Path B: Worktree

If the user chooses a worktree, continue with Steps 1-5.

Step 1: Directory Selection

Check in this priority order:

1. Does .worktrees/ exist in the project root? Use it (verify it is gitignored first)
2. Does worktrees/ exist? Use it (verify gitignored)
3. Is there a worktree directory preference in CLAUDE.md? Use that
4. Otherwise: ask the user to choose between .worktrees/<branch> (project-local, hidden) or ~/.config/worktrees/<project>/<branch> (global)

Step 2: Safety Verification

For project-local directories (.worktrees/, worktrees/):

git check-ignore -q .worktrees 2>/dev/null || echo "NOT IGNORED"

If NOT ignored: add to .gitignore immediately and commit that change before creating the worktree. This prevents worktree artifacts from polluting the repo.

Step 3: Create the Worktree

git worktree add <path> -b <branch-name>
cd <path>

Branch naming: follow codi-git-workflow rule conventions (feature/, fix/, chore/ prefix).

Step 4: Project Setup

Auto-detect and run the project setup command:

# Node.js / pnpm (check pnpm-lock.yaml)
pnpm install

# Node.js / npm (check package-lock.json)
npm install

# Rust
cargo build

# Python / uv (check pyproject.toml)
uv sync

# Python / pip (check requirements.txt)
pip install -r requirements.txt

# Go
go mod download

Step 5: Baseline Verification

Run the test suite to confirm a clean starting point:

pnpm test   # or npm test / cargo test / pytest / go test ./...

Report results. If tests fail:

• Do NOT proceed
• Report failures to the user
• Ask: “The baseline has failing tests. Do you want to fix them first, or proceed knowing the baseline is broken?”

Only proceed if the user explicitly says to continue with a broken baseline.

Status Report (Path B)

After successful worktree setup:

Worktree ready at <full-path>
Branch: <branch-name>
Tests: <N> passing, 0 failing
Ready to execute the implementation plan.

Cleanup

Worktrees are cleaned up by codi-branch-finish after work is complete:

• Merge/discard: worktree removed
• Keep branch / create PR: worktree preserved

Example Workflow

Path A example (simple branch):

You: I'm using codi-worktrees to choose an isolation strategy.

[git status --porcelain - clean]
[git worktree list - only main]
[Task scope: single bug fix, 2 files]

I recommend a simple branch for this task because it is a small targeted fix
and the working tree is clean.
Proceed with branch, or would you prefer a worktree?

User: branch

git checkout -b fix/null-check
Branch fix/null-check created. Ready to work.

Path B example (worktree):

You: I'm using codi-worktrees to choose an isolation strategy.

[git status --porcelain - 3 modified files]
[Task scope: large plan, 8 tasks, codi-plan-execution SUBAGENT mode]

I recommend a worktree because the working tree has uncommitted changes and
subagent execution benefits from path isolation.
Proceed with worktree, or would you prefer a simple branch?

User: worktree

[Check .worktrees/ - exists]
[Verify ignored - git check-ignore confirms .worktrees/ is ignored]
[Create worktree: git worktree add .worktrees/auth -b feature/auth]
[Run pnpm install]
[Run pnpm test - 47 passing]

Worktree ready at /path/to/project/.worktrees/auth
Branch: feature/auth
Tests: 47 passing, 0 failing
Ready to execute the implementation plan.

Red Flags

Never:

• Skip Step 0 and jump straight to worktree creation
• Create a worktree for a single-file change when the working tree is clean
• Create a worktree without verifying it is gitignored (project-local)
• Skip baseline test verification (Path B)
• Proceed with failing tests without asking the user
• Assume directory location when ambiguous
• Skip CLAUDE.md check

Always:

• Assess task scope and working tree state before recommending an approach
• Ask the user before proceeding with either path
• Follow directory priority (Path B): existing > CLAUDE.md > ask
• Verify directory is ignored for project-local locations (Path B)
• Auto-detect and run project setup (Path B)
• Verify a clean test baseline before reporting ready (Path B)

Quick Reference

Common Mistakes

• Skipping the decision step and creating a worktree by default (over-engineering)
• Creating a worktree in a directory that is not gitignored (pollutes the repo)
• Skipping baseline test verification on Path B (cannot distinguish new failures from existing ones)
• Hardcoding the setup command (always auto-detect from project files)