setup-branch

根据 JIRA 工单创建新的 Git 分支和工作树。根据 JIRA 工单类型自动命名分支，并设置好可供使用的工作树。

用法：

• /setup-branch PROJ-123 — 根据 JIRA ID 创建分支
• /setup-branch https://mycompany.atlassian.net/browse/PROJ-123 — 根据 JIRA URL 创建分支

说明：

1. 检查前置条件：

   • Atlassian CLI（acli）： 运行 acli auth status，检查 CLI 是否已安装并完成身份验证。
     • 如果找不到该命令，显示以下消息并停止：

       ## 缺少前置条件：Atlassian CLI
       
       尚未安装 `acli` 命令。此技能需要使用 Atlassian CLI 获取 JIRA 工单详情。
       
       使用以下命令安装：brew tap atlassian/acli && brew install acli
       

     • 如果命令因身份验证错误而失败，显示以下消息并停止：

       ## 缺少前置条件：Atlassian CLI 身份验证
       
       Atlassian CLI 尚未完成身份验证。请先运行 `acli auth login` 完成身份验证，然后再使用此技能。
       

   • GitHub CLI（gh）： 运行 gh --version，检查是否已安装 gh CLI。如果命令失败（找不到命令），显示以下消息并停止：

     ## 缺少前置条件：GitHub CLI
     
     尚未安装 `gh` 命令。此技能需要使用 GitHub CLI 执行仓库操作。
     
     请从此处安装：https://cli.github.com/
     

   • GitHub CLI 身份验证： 运行 gh auth status，检查 gh 是否已完成身份验证。如果命令显示用户尚未登录，显示以下消息并停止：

     ## 缺少前置条件：GitHub CLI 身份验证
     
     GitHub CLI 尚未完成身份验证。请先运行 `gh auth login` 完成身份验证，然后再使用此技能。
     

2. 从 $ARGUMENTS 解析 JIRA 引用：

   • 如果未提供参数，告知用户预期的用法并停止
   • 如果参数是 URL（包含 atlassian.net/browse/ 或类似内容），从 URL 路径中提取 JIRA ID（例如：https://mycompany.atlassian.net/browse/PROJ-123 → PROJ-123）。如果无法提取 JIRA ID，显示收到的内容并停止
   • 如果参数已经是 JIRA ID（匹配 PROJ-123、ABC-1 等格式），则直接使用
   • 如果参数既无法解析为 URL，也无法解析为 JIRA ID，告知用户并停止

3. 获取 JIRA 工单类型：

   • 使用 Atlassian CLI 获取所提取 JIRA ID 对应的工单详情：

     acli jira workitem view <JIRA-ID> --fields issuetype --json
     

   • 确认工单类型（Bug、Story、Task、Epic、Sub-task 等）
   • 如果获取失败，使用包含以下选项的 AskUserQuestion 询问开发者，让其手动提供工单类型："Bug"、"Story/Task/Other"

4. 确定分支名称：

   • 将 JIRA ID 转换为小写，用于分支名称（例如：PROJ-123 → proj-123）
   • 如果工单类型是 Bug：分支名称为 fix/<jira-id>（例如：fix/proj-123）
   • 对于所有其他类型（Story、Task、Epic、Sub-task 等）：分支名称为 feat/<jira-id>（例如：feat/proj-123）

5. 询问要从哪个基础分支创建分支：

   • 运行 git branch --show-current 获取当前工作目录的分支名称
   • 使用 AskUserQuestion 询问开发者要使用哪个分支作为基础
   • 第一个（默认）选项应为当前分支名称（例如，如果当前位于 develop，则建议使用 develop）
   • 如果当前分支不是 main，则将 main 作为第二个选项
   • 允许开发者通过“其他”选项输入不同的分支名称

6. 从远程获取基础分支：

   • 运行 git fetch origin <base-branch>
   • 如果获取失败（例如，远程不存在该基础分支），显示错误并立即停止。不要继续创建分支或工作树。
   • 不要检出或拉取基础分支——这样可以避免影响当前工作树中的未提交更改。

7. 同时创建新分支和工作树：

   • 如果该分支名称已在本地存在（git rev-parse --verify <branch-name> 执行成功），告知用户并停止（不要强制创建）
   • 确定工作树路径：取当前工作目录的父目录，并在其后附加将 / 替换为 - 的分支名称
     • 示例：如果 CWD 是 /Users/dev/my-project，分支是 fix/proj-123，则工作树路径为 /Users/dev/fix-proj-123
   • 如果工作树目录已存在，告知用户并停止
   • 运行 git worktree add <worktree-path> -b <branch-name> origin/<base-branch>
     • 这会基于远程基础分支创建新分支和工作树，且只需一条命令，不会触及当前工作树
   • 如果命令失败，显示错误并停止

8. 在新工作树中安装依赖项：

   • 本步骤中的所有命令都必须在新工作树目录中运行（运行命令前先使用 cd <worktree-path>，或传入 cwd 选项）
   • 检查新工作树目录中的锁文件，以确定包管理器：
     • bun.lockb 或 bun.lock → 运行 bun install --frozen-lockfile
     • pnpm-lock.yaml → 运行 pnpm install --frozen-lockfile
     • yarn.lock → 运行 yarn install --frozen-lockfile
     • package-lock.json → 运行 npm ci
     • 如果不存在这些锁文件，但存在 package.json → 运行 npm install 并警告未找到锁文件
     • 如果不存在 package.json → 完全跳过依赖项安装
   • 如果安装命令失败，显示错误，但不要删除工作树——开发者可能想手动修复问题

9. 信任 mise 配置：

   • 在新工作树目录中运行 mise trust，以信任存在的任何 .mise.toml 或 .tool-versions 文件
   • 如果未安装 mise（找不到命令），则静默跳过此步骤
   • 如果命令因其他原因失败，显示警告，但继续

10. 将 .env 文件复制到新工作树：

• 检查当前工作目录中是否存在 .env 文件
• 如果存在，将其复制到新工作树目录的根目录（cp .env <worktree-path>/.env）
• 如果不存在，则静默跳过此步骤

11. 在新工作树中创建 .agent 文件：

• 在 <worktree-path>/.agent 创建一个简单的配置文件，其中包含基础分支名称：

  baseBranch=<base-branch>
  

• 示例：如果基础分支是 main，文件内容应为 baseBranch=main

12. 显示成功消息：

显示包含所有相关信息的摘要：

## Branch Setup Complete

- JIRA: PROJ-123
- Type: Bug → fix/proj-123
- Base: origin/main
- Worktree: /Users/dev/fix-proj-123
- Dependencies: installed (npm ci)

To start working:
  cd /Users/dev/fix-proj-123

To push for the first time:
  git push -u origin fix/proj-123