git-worktree

@rules/worktree-lifecycle.md @references/source-survey.md

Git Worktree 技能

让隔离的分支工作区更轻便、清晰且安全。

<output_language>

默认将所有面向用户的交付物、保存的产物、报告、计划、生成的文档、摘要、交接说明、提交／消息草稿和验证说明设为韩语，即使此规范技能文件使用英语编写。

保留源代码标识符、CLI 命令、文件路径、架构键、JSON/YAML 字段名、API 名称、程序包名称、专有名称，以及必须使用指定语言或原文的引述内容。

仅当用户明确要求、现有目标产物为保持一致性必须使用其他语言，或机器可读契约要求使用精确的英文标记时，才使用其他语言。如果存在本地化模板或参考文件（例如 *.ko.md 或 *.ko.json），请优先将其用于面向用户的产物。

</output_language>

• 按照项目约定，在 .hyper/git-worktree/<folder_name> 下创建和管理 Git worktree。
• 支持并行功能开发、Agent 会话、代码审查、热修复和实验，避免频繁切换分支。
• 确保 worktree 操作安全：创建前询问缺失的任务意图，移除前检查状态，未提供路径时解析当前关联的 worktree，使用明确路径，并验证 Git 的 worktree 注册信息。
• 任何澄清问题都使用用户所用的语言。对于韩语提示，请用韩语提问；不要显示英文操作菜单。

<instruction_contract>

字段	契约
意图	创建、进入、检查、移除、清理或修复隔离的 Git worktree 工作区。
触发条件	用户提出 worktree／工作区／分支目录隔离请求，或明确要求执行 git-worktree 操作时启用。
范围	负责仓库／worktree 发现、路径和分支推导、本地 exclude 设置、worktree 生命周期命令、上下文切换和状态报告。
权限依据	用户和项目指令优先于此技能；Git worktree 注册信息、分支状态和文件系统检查结果是执行依据。
证据	修改前使用 git rev-parse、git worktree list --porcelain、目标路径检查、分支引用和各 worktree 的状态。
工具	使用原生 Git 和 shell；编辑器、tmux 或 Agent 启动操作是可选的，且仅在可用并由操作请求时执行。
循环	无。每项生命周期操作执行一轮：发现仓库、解析目标、检查安全性、修改、验证并报告。仅在用户进一步请求 worktree 操作时重复；目标存在未提交更改、具有破坏性或含糊不清时，应在修改前停止。
输出	使用韩语报告 worktree 路径、分支／提交、干净或有更改的状态、活动上下文切换情况，以及剩余的设置或清理工作。
验证	确认仓库根目录、worktree 注册信息、目标路径安全性、创建后的工作目录／状态，以及移除前的状态或 prune 试运行。
停止条件	请求的生命周期操作验证完成后停止；若目标存在未提交更改、具有破坏性或含糊不清，则在修改前报告并停止。

</instruction_contract>

<routing_rule>

用户希望执行以下操作时，使用 git-worktree：

• 创建 worktree、工作区、分支目录或隔离的检出目录
• 并行运行多个编码 Agent 或任务，避免文件冲突
• 列出、打开、切换到、移除、清理、修复、锁定或解锁 worktree
• 用户已位于当前关联的 worktree 中，并提出“移除／删除此 worktree”或“删除 worktree”之类的要求时，删除该 worktree
• 将 worktree 文件夹统一放在 .hyper/git-worktree/<folder_name> 下
• 在单独的本地目录中审查或测试分支／PR／issue

以下情况不要使用 git-worktree：

</routing_rule>

• 用户只要求在当前文件夹中正常创建或切换分支
• 用户要求重写历史记录、制定变基策略或整理提交，但不涉及 worktree 操作
• 用户要求的隔离方式必须是容器、虚拟机或独立克隆，而不是 Git worktree

</routing_rule>

<activation_examples>

肯定请求：

• “为 feature/auth 创建一个 worktree，并在 Codex 中打开。”
• “git-worktree fix/api-timeout”
• “在 .hyper/git-worktree 下将此分支创建为 worktree。”
• “为并行 Agent 启动三个隔离的 worktree。”
• “创建一个新的 worktree，并将我移入其中。”
• “列出我当前启用的 git worktree，并安全地移除过时的 worktree。”
• “我已经在这个 worktree 中；安全地删除这个 worktree。”
• “我已经位于这个 worktree 中；安全地删除该 worktree。”
• “在单独的 worktree 中设置 PR #42 以供审查。”

否定请求：

• “在这里创建一个新分支并切换到它。” 使用常规 Git 分支工作流。
• “解释一下 Git worktree 是什么。” 直接回答，除非用户要求执行 worktree 操作。
• “为每个分支创建一个 Docker 开发环境。” 改用容器／开发环境工作流。

边界请求：

• “为这个有风险的重构设置一个隔离的工作区。” 如果 Git 分支隔离已足够，则使用此技能；只有在需要隔离运行时、数据库、端口或依赖项时，才升级为容器／虚拟机工作流。

</activation_examples>

<trigger_conditions>

用户意图	启用
创建特定分支的工作目录	是
在同一仓库中并行运行 AI Agent／编码会话	是
列出或打开现有 worktree	是
移除、清理、锁定、解锁、修复或移动 worktree	是
在当前链接的 worktree 内部删除该 worktree	是
配置项目默认 worktree 根目录	是
纯 git checkout 或仅涉及分支的操作	否
不涉及操作的一般 Git 教程	否

</trigger_conditions>

<support_file_read_order>

1. 阅读 rules/worktree-lifecycle.md，了解命令模式、安全检查、移除、清理、修复和上下文迁移规则。
2. 只有在需要了解原理、上游行为或进行源代码比较时，才阅读 references/source-survey.md。
3. 编辑此技能文件夹后，使用确定性验证器 scripts/validate-git-worktree-skill.mjs。

</support_file_read_order>

<argument_handling>

• 如果用户调用 git-worktree <ARGUMENT>，或在技能名称后提供一个位置参数，则将 <ARGUMENT> 视为明确的创建目标，不要询问要创建哪个 worktree。
• 将 <ARGUMENT> 解释为分支／任务标签，除非它明显是 PR／议题／引用／路径；保留分支／引用文本，仅对文件夹标签进行清理。
• 使用 .hyper/git-worktree/<folder_name>，然后将活动 Agent 上下文移入新的 worktree。
• 仅当参数不安全、属于保留项、与无关路径冲突，或无法映射为 Git 引用／分支／任务标签时才询问。

</argument_handling>

- 规范根目录：`/.hyper/git-worktree/`。 - 规范路径：`/.hyper/git-worktree/`。 - 默认 ``：如果用户尚未提供明确任务，请询问用户将在 worktree 中进行什么工作。对于韩语用户，请准确询问："이 worktree에서 어떤 작업을 할 예정인가요?" 然后根据回答生成简洁且经过安全处理的 slug。 - 如果用户已提供位置参数、分支、PR、issue 或任务名称，请根据该上下文生成 ``，无需再次询问。 - 澄清语言：尽可能根据请求推断操作。如果操作确实含糊，请用用户的语言提一个简短问题。对于韩语用户，请询问他们想执行哪种 worktree 操作，例如创建、列出、打开/切换、删除、清理、修复、锁定或解锁。切勿提供通用的英文操作选项列表。 - 创建 worktree 后，只有在当前执行上下文已切换到该文件夹后，创建才算完成：在持久 shell/会话中，实际执行 `cd `；在仅使用工具的环境中，将下一条命令的 `workdir=`，并让后续命令继续在此目录中运行。不要只在最终答复中显示 `cd `。 - 如果用户未指定路径就请求删除，且当前上下文已位于关联 worktree 内，则将当前 worktree 根目录视为删除目标；删除前先切换到安全的 worktree，绝不删除主 worktree。 - 创建嵌套 worktree 前，先添加或验证 `.hyper/git-worktree/` 的本地 ignore/exclude 规则。 - 优先使用原生 `git worktree` 命令，而不是安装额外的管理器。 - 每个 worktree 优先对应一项任务、一个分支、一个终端会话和一个编辑器窗口。

<supported_operations>

• 从新分支、现有本地分支、远程分支、PR ref、issue 任务或 commit 创建 worktree。
• 在可用时，通过 shell、编辑器、tmux 会话或 Agent CLI 进入/打开 worktree。
• 列出 worktree，并显示分支、路径、脏/干净状态、锁定/可清理标注以及下一步操作。
• 验证更改已提交或已按预期丢弃后，删除已完成的 worktree。
• 即使在当前关联 worktree 内收到请求，也能删除当前 worktree：先解析当前顶层路径，再从其他安全的 worktree 执行 git worktree remove。
• 先试运行，再清理过时的元数据。
• 修复已移动的 worktree；对于误清理可能造成损害的长期存在的 worktree，将其锁定。

</supported_operations>

1. 使用 git rev-parse --show-toplevel 确认仓库根目录。
2. 使用 git worktree list --porcelain 读取现有 worktree。
3. 推断操作：创建、打开、列出、删除、清理、修复、锁定或解锁。
4. 如果在关联 worktree 内请求删除但未提供路径，则将当前顶层路径解析为目标；如果它是主 worktree，则停止，不要删除仓库根目录。
5. 将 git-worktree <ARGUMENT> 视为创建目标，并在提问前推断分支、文件夹和基础 ref。
6. 如果要创建 worktree 且任务意图不明确，请用用户的语言简洁地询问将在其中进行什么工作。
7. 除非用户提供了其他路径，否则使用 .hyper/git-worktree/<folder_name>。
8. 按照 @rules/worktree-lifecycle.md 执行命令、安全检查和清理。
9. 对于“创建并进入/打开/切换”，不要在执行 git worktree add 后就停止；应将当前上下文切换到该目录，或证明下一条命令已通过 workdir=<path> 执行。
10. 报告路径、分支/commit、干净/脏状态、上下文切换情况、剩余设置事项；清理时还需报告剩余的 git worktree list。

确定性回归命令：

bun skills/git-worktree/scripts/validate-git-worktree-skill.mjs

触发检查：

• 上述正向示例会明确触发此技能。
• 负向示例会转交给其他技能处理。
• 边界示例仅在分支级隔离足够时选择 Git worktree。

操作检查：

• 在构造路径前，git rev-parse --show-toplevel 执行成功。
• 创建操作有明确的工作意图；如果缺少意图，应先提出一个简洁的问题，再选择 <folder_name>。
• 直接调用 git-worktree <ARGUMENT> 时，应根据参数创建，不询问要创建什么 worktree。
• 澄清问题应与用户使用的语言一致；不能向韩语用户展示英文操作菜单。
• 根据已说明的工作意图确定 <folder_name>，并在构造路径前对其进行清理。
• 在创建嵌套 worktree 前，确保 .hyper/git-worktree/ 已被忽略或在本地排除。
• 修改现有 worktree 前，先读取 git worktree list --porcelain。
• 除非用户明确要求强制删除，否则先检查 git -C <path> status --short，再执行删除。
• 删除当前 worktree 时，先解析当前顶层路径，拒绝删除主 worktree，切换到另一个安全的 worktree，并删除已保存的目标路径，而不是在目标 worktree 内执行删除。
• 清理时，先运行 git worktree prune --dry-run，再运行 git worktree prune。
• 创建后续命令时，以新 worktree 作为工作目录；如果无法持久更改父 shell 的目录，最终报告应包含 cd <path>，并说明活动 Agent 上下文是否已切换到那里。
• 操作者不能只打印 cd <path>；持久会话应实际切换目录，或者至少有一条创建后的命令通过 workdir=<path> 或等效的工具工作目录设置，在新 worktree 中运行。

资源放置检查：

• 核心工作流保留在 SKILL.md 中。
• 详细的命令策略保留在 rules/worktree-lifecycle.md 中。
• 外部调研和模式选择理由保留在 references/source-survey.md 中。