worktree-manager

Alpha-Forge Worktree Manager

alpha-forge リポジトリ用の Git ワークツリーを作成・管理します。ブランチ名の自動生成、一貫した規約、ライフサイクル管理に対応しています。

自己進化型スキル：このスキルは使用を通じて改善されます。手順に誤りがある、パラメーターが変わった、または回避策が必要だった場合は、先送りせず、すぐにこのファイルを修正してください。更新するのは、実際に再現できる問題がある場合に限ります。

このスキルを使用する場面

以下の場合にこのスキルを使用してください。

• alpha-forge の開発用に新しいワークツリーを作成する
• リモートブランチからワークツリーをセットアップする
• 新しいワークツリーで既存のローカルブランチを使用する
• 複数の機能ブランチを並行して管理する

動作モード

このスキルは、ユーザーの入力に応じて次の3つのモードで動作します。

モード	ユーザー入力例	アクション
新規ブランチ	"create worktree for sharpe validation"	スラッグを導出し、ブランチとワークツリーを作成
リモート追跡	"create worktree from origin/feat/existing"	新しいワークツリーでリモートブランチを追跡
ローカルブランチ	"create worktree for feat/2025-12-15-my-feat"	新しいワークツリーで既存のブランチを使用

---

モード1：説明から新規ブランチを作成（基本）

最も一般的なワークフローです。ユーザーが自然言語で説明を入力し、Claude がスラッグを導出します。

ステップ1：説明を解析してスラッグを導出する

Claude は、次のルールに従ってケバブケースのスラッグを導出します。

単語の簡潔化ルール：

• スラッグ内の各単語は、固有の意味を持つ必要があります
• 冗長な語を削除します：the、a、an、for、with、and、to、from、in、on、of、by
• 重複を避けます（例：「ClickHouse」の後に「database」を付けない）
• 最大3～5語に制限します

変換手順：

1. ユーザー入力から説明を解析します
2. 小文字に変換します
3. 単語を簡潔化します（冗長な語を削除）
4. スペースをハイフンに置き換えます

例：

ユーザーの説明	導出されたスラッグ
"sharpe statistical validation"	sharpe-statistical-validation
"fix the memory leak in metrics"	memory-leak-metrics
"implement user authentication for API"	user-authentication-api
"add BigQuery data source support"	bigquery-data-source

ステップ2：メインワークツリーの状態を確認する

重要：先に進む前に、メインワークツリーが main ブランチにあることを確認してください。

/usr/bin/env bash << 'GIT_EOF'
cd ~/eon/alpha-forge
CURRENT=$(git branch --show-current)
GIT_EOF

main または master にない場合：

AskUserQuestion を使用してユーザーに警告します。

question: "Main worktree is on '$CURRENT', not main. Best practice is to keep main worktree clean. Continue anyway?"
header: "Warning"
options:
  - label: "Continue anyway"
    description: "Proceed with worktree creation"
  - label: "Switch main to 'main' first"
    description: "I'll switch the main worktree to main branch before creating"
multiSelect: false

ユーザーが「先に main を 'main' に切り替える」を選択した場合：

cd ~/eon/alpha-forge
git checkout main

ステップ3：リモートを取得してブランチを表示する

cd ~/eon/alpha-forge
git fetch --all --prune

# Display available branches for user reference
echo "Available remote branches:"
git branch -r | grep -v HEAD | head -20

ステップ4：ブランチの種類を尋ねる

AskUserQuestion を使用します。

question: "What type of branch is this?"
header: "Branch type"
options:
  - label: "feat"
    description: "New feature or capability"
  - label: "fix"
    description: "Bug fix or correction"
  - label: "refactor"
    description: "Code restructuring (no behavior change)"
  - label: "chore"
    description: "Maintenance, tooling, dependencies"
multiSelect: false

ステップ5：ベースブランチを尋ねる

AskUserQuestion を使用します。

question: "Which branch should this be based on?"
header: "Base branch"
options:
  - label: "main (Recommended)"
    description: "Base from main branch"
  - label: "develop"
    description: "Base from develop branch"
multiSelect: false

別のブランチが必要な場合は、「Other」を選択してブランチ名を入力できます。

ステップ6：ブランチ名を組み立てる

/usr/bin/env bash << 'SKILL_SCRIPT_EOF'
TYPE="feat"           # From Step 4
DATE=$(date +%Y-%m-%d)
SLUG="sharpe-statistical-validation"  # From Step 1
BASE="main"           # From Step 5

BRANCH="${TYPE}/${DATE}-${SLUG}"
# Result: feat/2025-12-15-sharpe-statistical-validation
SKILL_SCRIPT_EOF

ステップ7：ワークツリーを作成する（アトミック）

/usr/bin/env bash << 'GIT_EOF_2'
cd ~/eon/alpha-forge

WORKTREE_PATH="$HOME/eon/alpha-forge.worktree-${DATE}-${SLUG}"

# Atomic branch + worktree creation
git worktree add -b "${BRANCH}" "${WORKTREE_PATH}" "origin/${BASE}"
GIT_EOF_2

ステップ8：タブ名を生成して報告する

/usr/bin/env bash << 'SKILL_SCRIPT_EOF_2'
# Generate acronym from slug
ACRONYM=$(echo "$SLUG" | tr '-' '\n' | cut -c1 | tr -d '\n')
TAB_NAME="AF-${ACRONYM}"
SKILL_SCRIPT_EOF_2

成功を報告します。

✓ Worktree created successfully

  Path:    ~/eon/alpha-forge.worktree-2025-12-15-sharpe-statistical-validation
  Branch:  feat/2025-12-15-sharpe-statistical-validation
  Tab:     AF-ssv
  Env:     .envrc created (loads shared secrets)

  iTerm2: Restart iTerm2 to see the new tab

---

モード2：リモートブランチの追跡

ユーザーが origin/branch-name を指定した場合、ローカルの追跡ブランチを作成します。

判定方法：ユーザー入力に origin/ のプレフィックスが含まれています。

例："create worktree from origin/feat/2025-12-10-existing-feature"

ワークフロー

/usr/bin/env bash << 'GIT_EOF_3'
cd ~/eon/alpha-forge
git fetch --all --prune

REMOTE_BRANCH="origin/feat/2025-12-10-existing-feature"
LOCAL_BRANCH="feat/2025-12-10-existing-feature"

# Extract date and slug for worktree naming
# Pattern: type/YYYY-MM-DD-slug
if [[ "$LOCAL_BRANCH" =~ ^(feat|fix|refactor|chore)/([0-9]{4}-[0-9]{2}-[0-9]{2})-(.+)$ ]]; then
    DATE="${BASH_REMATCH[2]}"
    SLUG="${BASH_REMATCH[3]}"
else
    DATE=$(date +%Y-%m-%d)
    SLUG="${LOCAL_BRANCH##*/}"
fi

WORKTREE_PATH="$HOME/eon/alpha-forge.worktree-${DATE}-${SLUG}"

# Create tracking branch + worktree
git worktree add -b "${LOCAL_BRANCH}" "${WORKTREE_PATH}" "${REMOTE_BRANCH}"
GIT_EOF_3

---

モード3：既存のローカルブランチ

ユーザーがローカルブランチ名（origin/ なし）を指定した場合、そのまま使用します。

判定方法：ユーザー入力が有効なブランチ名の形式です（例：feat/2025-12-15-slug）。

例："create worktree for feat/2025-12-15-my-feature"

ワークフロー

/usr/bin/env bash << 'VALIDATE_EOF'
cd ~/eon/alpha-forge

BRANCH="feat/2025-12-15-my-feature"

# Verify branch exists
if ! git show-ref --verify "refs/heads/${BRANCH}" 2>/dev/null; then
    echo "ERROR: Local branch '${BRANCH}' not found"
    echo "Available local branches:"
    git branch | head -20
    exit 1
fi

# Extract date and slug
if [[ "$BRANCH" =~ ^(feat|fix|refactor|chore)/([0-9]{4}-[0-9]{2}-[0-9]{2})-(.+)$ ]]; then
    DATE="${BASH_REMATCH[2]}"
    SLUG="${BASH_REMATCH[3]}"
else
    DATE=$(date +%Y-%m-%d)
    SLUG="${BRANCH##*/}"
fi

WORKTREE_PATH="$HOME/eon/alpha-forge.worktree-${DATE}-${SLUG}"

# Create worktree for existing branch (no -b flag)
git worktree add "${WORKTREE_PATH}" "${BRANCH}"
VALIDATE_EOF

---

命名規約

Worktree フォルダーの命名（ADR 形式）

形式：alpha-forge.worktree-YYYY-MM-DD-slug

場所：~/eon/

ブランチ	Worktree フォルダー
feat/2025-12-14-sharpe-statistical-validation	alpha-forge.worktree-2025-12-14-sharpe-statistical-validation
feat/2025-12-13-feature-genesis-skills	alpha-forge.worktree-2025-12-13-feature-genesis-skills
fix/quick-patch	alpha-forge.worktree-{TODAY}-quick-patch

iTerm2 タブの命名（頭字語ベース）

形式：AF-{acronym}（頭字語はスラッグ内の各単語の先頭文字）

Worktree スラッグ	タブ名
sharpe-statistical-validation	AF-ssv
feature-genesis-skills	AF-fgs
eth-block-metrics-data-plugin	AF-ebmdp

---

古い Worktree の検出

ブランチがすでに main にマージされている Worktree を確認します：

/usr/bin/env bash << 'PREFLIGHT_EOF'
cd ~/eon/alpha-forge

# Get branches merged to main
MERGED=$(git branch --merged main | grep -v '^\*' | grep -v 'main' | tr -d ' ')

# Check each worktree
git worktree list --porcelain | grep '^branch' | cut -d' ' -f2 | while read branch; do
    branch_name="${branch##refs/heads/}"
    if echo "$MERGED" | grep -q "^${branch_name}$"; then
        path=$(git worktree list | grep "\[${branch_name}\]" | awk '{print $1}')
        echo "STALE: $branch_name at $path"
    fi
done
PREFLIGHT_EOF

古い Worktree が見つかった場合は、AskUserQuestion を使ってユーザーにクリーンアップを促します。

---

クリーンアップのワークフロー

古い Worktree の削除

# Remove worktree (keeps branch)
git worktree remove ~/eon/alpha-forge.worktree-{DATE}-{SLUG}

# Optionally delete merged branch
git branch -d {BRANCH}

孤立したエントリーの整理

git worktree prune

---

エラー処理

状況	対応
ブランチがすでに存在する	モード 3（既存のブランチ）の使用または名前変更を提案
リモートブランチが見つからない	利用可能なリモートブランチを一覧表示
メインの Worktree が feature 上にある	AskUserQuestion で警告し、切り替えを提案
説明が空	使用例を表示
fetch 時のネットワークエラー	ローカルブランチのみを使うオフラインモードを許可
Worktree のパスが存在する	クリーンアップまたは別のスラッグを提案

ブランチが見つからない場合

✗ Branch 'feat/nonexistent' not found

  Available branches:
  - feat/2025-12-14-sharpe-statistical-validation
  - main

  To create from remote:
  Specify: "create worktree from origin/branch-name"

Worktree がすでに存在する場合

✗ Worktree already exists for this branch

  Existing path: ~/eon/alpha-forge.worktree-2025-12-14-sharpe-statistical-validation

  To use existing worktree:
  cd ~/eon/alpha-forge.worktree-2025-12-14-sharpe-statistical-validation

---

統合

direnv の環境設定

Worktree の作成時に .envrc ファイルが自動的に作成され、~/eon/.env.alpha-forge から共有認証情報が読み込まれます。

Worktree 作成時の処理：

1. スクリプトが ~/eon/.env.alpha-forge の存在を確認します
2. 新しい Worktree に dotenv ディレクティブを含む .envrc を作成します
3. direnv allow を実行して、新しい .envrc を許可します

共有シークレットファイル（~/eon/.env.alpha-forge）：

# ClickHouse credentials, API keys, etc.
CLICKHOUSE_HOST_READONLY="..."
CLICKHOUSE_USER_READONLY="..."
CLICKHOUSE_PASSWORD_READONLY="..."

生成される .envrc（各 Worktree 内）：

# alpha-forge worktree direnv config
# Auto-generated by create-worktree.sh

# Load shared alpha-forge secrets
dotenv $HOME/eon/.env.alpha-forge

# Worktree-specific overrides can be added below

前提条件：

• mise 経由で direnv がインストールされている（mise use -g direnv@latest）
• シェルフックが設定されている（~/.zshrc 内に eval "$(direnv hook zsh)"）
• 共有シークレットファイルが ~/eon/.env.alpha-forge にある

iTerm2 の動的検出

default-layout.py スクリプトが Worktree を自動検出します：

1. ~/eon/alpha-forge.worktree-* に一致するパスを検索します
2. 各パスを git worktree list と照合して検証します
3. AF-{acronym} 形式のタブ名を生成します
4. メインの AF タブの後にタブを挿入します

---

参考資料

• 命名規則
• ADR：Alpha-Forge の Git Worktree 管理
• 設計仕様

---

トラブルシューティング

問題	原因	解決策
ブランチがすでに存在します	同じ名前のローカルブランチがあります	モード 3（既存のブランチ）を使うか、スラッグの名前を変更します
リモートブランチが見つかりません	入力ミス、またはまだプッシュされていません	git fetch --all --prune を実行して、ブランチ一覧を確認します
ワークツリーのパスがすでに存在します	前のワークツリーがクリーンアップされていません	古いワークツリーを削除するか、別のスラッグを使います
direnv が読み込まれません	シェルフックが設定されていません	eval "$(direnv hook zsh)" を ~/.zshrc に追加します
共有シークレットが見つかりません	~/eon/.env.alpha-forge がありません	必要な変数を含む共有シークレットファイルを作成します
iTerm2 のタブが表示されません	動的レイアウトが更新されていません	レイアウトの再生成を実行するため、iTerm2 を再起動します
メインのワークツリーが main にありません	前の作業で切り替えられていません	まずメインのワークツリーで git checkout main を実行します
古いワークツリーが検出されました	ブランチがマージされた後、クリーンアップされていません	git worktree remove <path> を実行してクリーンアップします

実行後の振り返り

このスキルの完了後、タスクを終了する前に振り返ってください。

0. 現在の場所を確認します。 — 編集する前に、この SKILL.md の正式なパスを見つけます。
1. 何が失敗しましたか？ — 原因となった指示を修正します。
2. 予想以上にうまくいったことは何ですか？ — 推奨される実践方法として取り入れます。
3. 何が実態とずれていましたか？ — 現状と一致しなくなったスクリプト、参照、依存関係を修正します。
4. 記録します。 — きっかけ、修正内容、根拠を含む進化ログのエントリーを追加します。

先送りしないでください。次回の実行には、あなたが残したものが引き継がれます。