home / skills / yellinzero / aico / aico-worktree

aico-worktree skill

safe

This skill creates isolated git worktrees for feature development, auto-detects setup, verifies gitignore, and runs baseline tests to ensure a clean start.

npx playbooks add skill yellinzero/aico --skill aico-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, enforces gitignore safety, runs project setup, and verifies baseline tests before reporting readiness. Use it to avoid contaminating your main workspace and to work on multiple branches concurrently.

How this skill works

The skill inspects the repository for preferred worktree locations (.worktrees/ or worktrees/) and falls back to project docs or prompts the user. It verifies the chosen directory is listed in .gitignore before creating a new branched worktree with git worktree add. After creation it auto-detects the project type (npm, pip, go, cargo), runs setup commands, and executes baseline tests, reporting pass/fail results and test counts.

When to use it

Starting a feature that must be isolated from the current workspace
Before executing an implementation plan on a new branch
When working on multiple branches or features at the same time
User asks to “create worktree”, “isolate this work”, or “separate branch”
Need a clean baseline before major refactors or experiments

Best practices

Always verify the worktree directory is gitignored for project-local paths before creating
Prefer .worktrees/ then worktrees/ when present; consult project docs next
Auto-run dependency install and environment setup to reproduce developer environment
Run baseline tests immediately and do not proceed if tests fail without user approval
Remove or prune stale worktrees after branches are merged to avoid clutter

Example use cases

Create isolated worktree and branch for a new feature without affecting open editors or uncommitted changes
Spin up parallel worktrees to implement and test two competing approaches simultaneously
Prepare a clean environment to reproduce and fix a flaky test or CI failure
Start a large refactor on a feature branch after confirming baseline tests pass

FAQ

What if the chosen directory is not in .gitignore?

The skill will refuse to create the worktree and instruct you to add the directory to .gitignore first, then retry. This prevents accidental commits of local worktrees.

Which setup and test commands are run?

It auto-detects common languages and runs npm install/npm test, pip install -r requirements.txt/pytest, go test ./..., or the equivalent for detected toolchains.

What happens if baseline tests fail?

It reports failing tests and test counts, then asks whether to proceed despite failures or abort and fix issues first.