Add Worktree

/add-worktree

Create a new worktree for an Issue.

Usage

/add-worktree <issue-number>

Arguments

Instructions

When the user invokes /add-worktree <number>, follow these steps:

Step 1: Load Issue

gh issue view <number> --json number,title,body,labels,state

Verify the issue exists and is open.

Step 2: Determine Branch Type

Same logic as /start-issue:

• Check labels for branch type mapping
• Fall back to keyword detection
• Default to feat/

Step 3: Generate Names

Branch name:

<prefix>/<issue-number>-<normalized-title>

Worktree directory:

../<project-name>-<branch-name-with-slashes-as-hyphens>

Example:

• Branch: feat/200-add-feature
• Worktree: ../my-project-feat-200-add-feature

Step 4: Check for Existing

Check if worktree or branch already exists:

git worktree list
git branch --list <branch-name>

If exists, report error and show existing path.

Step 5: Create Worktree

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

This creates:

1. New branch
2. New worktree directory
3. Checks out the branch in the worktree

Step 6: Copy .hachimoku/ Configuration

If .hachimoku/ directory exists in the repository root, copy it to the new worktree.

If .hachimoku/ is already present in the worktree (git-tracked), skip the copy. Otherwise copy from the repository root:

if [ ! -d <worktree-path>/.hachimoku ]; then
  cp -r .hachimoku/ <worktree-path>/.hachimoku/
fi

Then remove any stale JSONL files if reviews/ exists:

find <worktree-path>/.hachimoku/reviews -name "*.jsonl" -delete 2>/dev/null || true

This preserves project-specific hachimoku agent customizations (agent configs, review settings).

If .hachimoku/ does not exist in the repository root, skip this step silently.

Note: We copy (not 8moku init) to preserve customized agent configurations.

Note: When executed via scripts/add-worktree.sh, this step is handled by the script itself (Claude CLI --allowedTools does not include cp).

Step 7: Report Success

Worktree created successfully

Issue: #200 - [Issue title]
Branch: feat/200-add-feature
Directory: ../my-project-feat-200-add-feature

To start working:
  cd ../my-project-feat-200-add-feature

Output Format

Success

Worktree created successfully

Issue: #<number> - <title>
Branch: <branch-name>
Directory: <worktree-path>

To start working:
  cd <worktree-path>

Already Exists

Worktree already exists

Issue: #<number> - <title>
Existing path: <existing-path>

To continue working in the existing worktree:
  cd <existing-path>

Error Handling

Worktree Management Tips

# List all worktrees
git worktree list

# Remove a worktree
git worktree remove ../my-project-feat-200-add-feature

# Prune stale worktree info
git worktree prune