home / skills / yellinzero / aico / worktree

worktree skill

safe

This skill creates isolated git worktrees for feature development, automatically verifying gitignore, setting up the project, and validating baseline tests.

This is most likely a fork of the aico-worktree skill from yellinzero

npx playbooks add skill yellinzero/aico --skill worktree

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.5 KB

---
name: aico-worktree
description: |
  Create isolated git worktree for feature development. Handles directory selection, gitignore verification, project setup, and baseline test verification.

  Use this skill when:
  - Starting feature work that needs isolation from current workspace
  - Before executing implementation plans on a new branch
  - Want to work on multiple branches/features simultaneously
  - User asks to "create worktree", "isolate this work", "separate branch"
  - Need clean baseline before starting major changes

  Safety: ALWAYS verify worktree directory is gitignored before creating.
  Process: Check directory → Verify ignored → Create worktree → Run setup → Verify baseline tests
---

# Git Worktree

## Process

1. **Check existing directories**: `.worktrees/` or `worktrees/`
2. **Verify gitignored**: MUST verify before creating
3. **Create worktree**: `git worktree add <path> -b <branch>`
4. **Run project setup**: Auto-detect (npm/pip/go/cargo)
5. **Verify baseline tests**: Run tests, report status

## Directory Selection

| Priority | Check                  |
| -------- | ---------------------- |
| 1        | Existing `.worktrees/` |
| 2        | Existing `worktrees/`  |
| 3        | Project config/docs    |
| 4        | Ask user               |

## Safety Verification

**For project-local directories:**

```bash
git check-ignore -q .worktrees 2>/dev/null
```

If NOT ignored → Add to `.gitignore` first.

## Creation Steps

```bash
# Create worktree with new branch
git worktree add ".worktrees/$BRANCH_NAME" -b "$BRANCH_NAME"
cd ".worktrees/$BRANCH_NAME"

# Run project setup (auto-detect)
if [ -f package.json ]; then npm install; fi
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi

# Verify baseline tests
npm test / pytest / go test ./...
```

## Report Format

```
Worktree ready at <full-path>
Branch: <branch-name>
Tests: <N> passing
Ready to implement <feature-name>
```

## Worktree Management

```bash
git worktree list          # List all
git worktree remove <path> # Remove after merge
git worktree prune         # Clean stale
```

## Key Rules

- ALWAYS verify directory is gitignored for project-local
- MUST run baseline tests before reporting ready
- If tests fail → Report failures, ask whether to proceed
- ALWAYS auto-detect and run project setup

## Common Mistakes

- ❌ Skip ignore verification → ✅ Always verify gitignored
- ❌ Skip baseline tests → ✅ Verify clean starting point
- ❌ Proceed with failing tests → ✅ Ask user first
- ❌ Leave stale worktrees → ✅ Remove after merge

Overview

This skill creates an isolated git worktree for feature development and ensures a clean, reproducible starting point. It handles directory selection, verifies the worktree directory is gitignored, runs project setup, and verifies baseline tests before reporting readiness. The goal is safe parallel work on multiple branches without contaminating the main workspace.

How this skill works

The skill inspects the repository for preferred worktree directories (.worktrees or worktrees), checks that the chosen path is listed in .gitignore, and creates a new worktree on a new branch using git worktree. It auto-detects project tooling (npm, pip, go, cargo), runs the appropriate setup commands, then runs baseline tests and reports pass/fail status with a short readiness summary.

When to use it

Starting feature work that must be isolated from the current workspace
Before executing a multi-step implementation plan on a new branch
When you want to work on multiple branches/features simultaneously
User requests: 'create worktree', 'isolate this work', or 'separate branch'
When you need a verified, clean baseline before major changes

Best practices

Always verify the chosen worktree directory is gitignored before creating it
Prefer existing .worktrees/ then worktrees/ then project docs when choosing path
Run full project setup (install deps) before running tests
Require baseline tests to pass; if they fail, report failures and ask to proceed
Remove or prune stale worktrees after merge to keep repo tidy

Example use cases

Create a worktree on a feature branch to implement a new API endpoint without touching the main workspace
Open two worktrees to develop and review an experimental refactor in parallel
Prepare a clean environment to run integration tests before starting a risky change
Quickly spin up a branch-specific environment for a hotfix while keeping other work intact
Validate that tests pass on a fresh branch before sharing an implementation plan

FAQ

What if the chosen worktree directory is not gitignored?

The skill will refuse to create the worktree and prompt to add the directory to .gitignore first. It will provide the check-ignore command and suggested .gitignore entry.

Which setup commands are run automatically?

The skill auto-detects common project files and runs npm install, pip install -r requirements.txt, go test tooling, or cargo setup as appropriate, then runs the project's test command.

What happens if baseline tests fail?

The skill reports test failures with a summary and asks whether to proceed despite failures; it does not mark the worktree ready until tests pass or the user explicitly overrides.