worktree-manager

Alpha-Forge Worktree 管理器

为 alpha-forge 仓库创建和管理 git worktree，并自动命名分支、统一约定和管理生命周期。

自我进化技能：此技能会在使用过程中不断改进。如果说明有误、参数发生偏移，或需要变通方案，请立即修复此文件，不要拖延。仅针对真实、可复现的问题进行更新。

何时使用此技能

在以下情况下使用此技能：

• 为 alpha-forge 开发创建新的 worktree
• 从远程分支设置 worktree
• 在新的 worktree 中使用现有本地分支
• 管理多个并行功能分支

操作模式

此技能根据用户输入支持三种不同模式：

模式	用户输入示例	操作
新建分支	"create worktree for sharpe validation"	推导 slug，创建分支和 worktree
跟踪远程分支	"create worktree from origin/feat/existing"	在新 worktree 中跟踪远程分支
本地分支	"create worktree for feat/2025-12-15-my-feat"	在新 worktree 中使用现有分支

---

模式 1：根据描述新建分支（主要模式）

这是最常见的工作流。用户提供自然语言描述，Claude 推导 slug。

步骤 1：解析描述并推导 slug

Claude 按照以下规则推导 kebab-case slug：

精简用词规则：

• slug 中的每个单词都必须表达独特含义
• 删除填充词：the、a、an、for、with、and、to、from、in、on、of、by
• 避免冗余（例如，在 “ClickHouse” 后添加 “database”）
• 最多限制为 3-5 个单词

转换步骤：

1. 解析用户输入中的描述
2. 转换为小写
3. 应用精简用词规则（删除填充词）
4. 将空格替换为连字符

示例：

用户描述	推导出的 slug
"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：检查主 worktree 状态

重要：继续操作前，检查主 worktree 是否位于 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：创建 Worktree（原子操作）

/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}，其中 acronym = slug 中每个单词的首字母

Worktree Slug	标签页名称
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 位于功能分支	通过 AskUserQuestion 发出警告，并提供切换选项
描述为空	显示用法示例
获取时发生网络错误	允许仅使用本地分支的离线模式
Worktree 路径已存在	建议清理或使用其他 slug

未找到分支

✗ 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）
• 配置 Shell hook（在 ~/.zshrc 中添加 eval "$(direnv hook zsh)"）
• 共享密钥文件位于 ~/eon/.env.alpha-forge

iTerm2 动态检测

default-layout.py 脚本会自动发现 worktree：

1. 对 ~/eon/alpha-forge.worktree-* 执行 glob 匹配
2. 根据 git worktree list 验证每个 worktree
3. 生成 AF-{acronym} 标签页名称
4. 将标签页插入主 AF 标签页之后

---

参考资料

• 命名约定
• ADR：Alpha-Forge Git Worktree 管理
• 设计规范

---

故障排除

问题	原因	解决方案
分支已存在	存在同名本地分支	使用模式 3（现有分支）或重命名 slug
找不到远程分支	拼写错误或尚未推送	运行 git fetch --all --prune 并列出分支
工作树路径已存在	之前的工作树未清理	删除旧工作树或使用其他 slug
direnv 未加载	未配置 Shell 钩子	将 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. 记录下来。 — 添加演进日志条目，记录触发原因、修复内容和证据。

不要推迟。下一次调用会继承你留下的一切。