Git Worktree Manager Instructions

Instructions for working with the `wt` project - a Git worktree management tool that enforces worktree-first workflows and prevents common Git branching pitfalls.

Core Principles

This project follows strict dogfooding principles:

**Never** use `git checkout` or `git switch` in the main directory

**Never** change branches within any worktree

**Always** use `wt` commands for branch/worktree operations

**Mental model**: Think "worktree-managed codebase" not "Git repository with worktree features"

Session Initialization (MANDATORY FIRST STEP)

Before ANY development work, execute this checklist:

1. **Verify current location and branch**

- Run `pwd` and `git branch --show-current`

- If in main directory on wrong branch, fix immediately with `git checkout main`

2. **Check session context**

- Read `.claude/SESSION.md` to understand current state

3. **List all worktrees**

- Run `./wt list --verbose` to see project state

4. **Update session state**

- Update `.claude/SESSION.md` with your current task

- Use TodoWrite tool to plan work

Pre-Command Validation

Before executing ANY git operation, validate:

1. **Location check**: Are you in main directory or a worktree?

2. **Branch check**: Is main directory on `main` branch?

3. **Command check**: Does this violate the three commandments?

4. **Alternative check**: What's the proper `wt` command to use instead?

Prohibited Patterns

`git checkout -b` → Use `./wt add <branch-name>` instead

`git switch -c` → Use `./wt add <branch-name>` instead

`git checkout` in main directory → Use `./wt switch <worktree>` instead

Branch switching within worktrees → Create new worktree instead

Safe Patterns

Create workspace: `./wt add <branch-name>`

Switch workspace: `./wt switch <worktree-name>`

List worktrees: `./wt list --verbose`

Check dirty state: `./wt list --dirty`

Development Workflow

Task Management

1. **Read todo list**: Use TodoRead tool to check existing tasks

2. **Plan work**: Use TodoWrite tool to create/update task list

3. **Track progress**: Update status (pending → in_progress → completed)

4. **Mark completion**: Immediately mark tasks as completed when finished

Session State Management

Maintain `.claude/SESSION.md` with:

Current tasks and progress

System constraints and blockers

Today's accomplishments

Next actions for continuity

Worktree Organization

**Location**: All worktrees in `$REPO_ROOT/worktrees/` subdirectory

**Naming**: `feature/auth` → `worktrees/feature-auth/`

**Isolation**: 1 worktree = 1 branch = 1 feature

**Main directory**: Always stays on `main` branch

Emergency Procedures

If Dogfooding Violation Detected

1. **STOP** all operations immediately

2. **Assess state**: Run `./wt list --verbose`

3. **Fix main directory**: Run `git checkout main` if needed

4. **Document lesson**: Update `.claude/SESSION.md`

5. **Restart properly**: Follow session initialization checklist

If Tools Fail

1. Try starting a new session (often resolves tool issues)

2. Use manual procedures from `.claude/WORKFLOWS.md`

3. Document the constraint in `.claude/SESSION.md`

Project Architecture

Command Design

**Primary info**: `wt list` shows all worktrees

**Detailed view**: `wt list --verbose` includes git status

**Status check**: `wt list --dirty` for uncommitted changes

**Exact matching**: No fuzzy matching to avoid complexity

Zsh Integration

**Command role**: `wt switch` resolves and returns target path

**Shell role**: Zsh functions handle actual directory changing

**Setup**: Generated by `wt shell-init` (zsh-only support)

**Tab completion**: Integrated with zsh completion system

Development Guidelines

Code Changes

Do exactly what has been asked; nothing more, nothing less

**NEVER** create files unless absolutely necessary

**ALWAYS** prefer editing existing files over creating new ones

**NEVER** proactively create documentation files

Only create documentation if explicitly requested

Documentation Updates

Before updating docs, verify:

1. **Information placement**: Which file does this belong in?

2. **Redundancy check**: Does this create duplicate information?

3. **Cognitive load**: Will this make information harder to find?

4. **Access pattern**: Does this match actual usage frequency?

Follow these principles:

**Single responsibility**: One source of truth per information type

**Progressive disclosure**: Overview → Procedure → Details

**Information density**: 1 file = 1 screen, minimize scrolling

**Separation**: Keep static and dynamic content separate

Navigation Guide

**Operational procedures**: See `.claude/WORKFLOWS.md`

**Current session status**: See `.claude/SESSION.md`

**Quick reference**: See `.claude/CLAUDE.md`

**Task-specific notes**: See `.claude/tasks/` directory

Decision Framework

Use this mental checklist before any operation:

1. **What do I want to achieve?** (New branch, switch workspace, check status)

2. **Where am I?** (Main directory or worktree)

3. **What's the wt command for this?** (Not the git command)

4. **Does this follow dogfooding principles?** (No branch switching, no checkout in main)

Examples

Creating a New Feature

```bash

✅ CORRECT

./wt add feature/new-auth

❌ WRONG

git checkout -b feature/new-auth

```

Switching Context

```bash

✅ CORRECT

./wt switch feature-auth # Returns path, shell function changes directory

❌ WRONG

git checkout feature/auth

```

Checking State

```bash

✅ CORRECT

./wt list --verbose

./wt list --dirty

❌ WRONG (but not prohibited, just not using our tool)

git worktree list

```

Key Constraints

Main directory must always remain on `main` branch

Each worktree is dedicated to exactly one branch

No branch switching within worktrees (create new worktree instead)

All worktree operations go through `wt` commands

Zsh is the only supported shell for integration features

Git Worktree Manager Instructions

Git Worktree Manager Instructions

Core Principles

Session Initialization (MANDATORY FIRST STEP)

Pre-Command Validation

Prohibited Patterns

Safe Patterns

Development Workflow

Task Management

Session State Management

Worktree Organization

Emergency Procedures

If Dogfooding Violation Detected

If Tools Fail

Project Architecture

Command Design

Zsh Integration

Development Guidelines

Code Changes

Documentation Updates

Navigation Guide

Decision Framework

Examples

Creating a New Feature

✅ CORRECT

❌ WRONG

Switching Context

✅ CORRECT

❌ WRONG

Checking State

✅ CORRECT

❌ WRONG (but not prohibited, just not using our tool)

Key Constraints

Reviews (0)