branch-management

分支与特性目录管理Skill（branch-management）

概览（职责与输入输出）

• 职责：统一管理基于“需求编号”的分支与特性目录创建/复用流程：
  • 解析并验证需求编号（强制要求）
  • 根据需求编号检查当前分支是否匹配
  • 必要时创建新的特性分支与目录
• 典型调用方：
  • reverse-on-demand（按需反构阶段1）
  • 其他基于需求编号驱动的命令/Skill
• 输出变量：
  • REQUIREMENT_ID：需求编号
  • BRANCH_MATCHES_REQUIREMENT：布尔值，当前分支是否匹配需求编号
  • BRANCH_NAME：最终选定/创建的特性分支名称
  • FEATURE_DIR：特性目录绝对路径（例如 <REPO_ROOT>/changes/<short-name>/）
  • TARGET_FILE：目标文件绝对路径（可选；本流程下允许为空）
  • REPO_ROOT：仓库根目录（在调用本 Skill 前由调用方提供或通过前置步骤获取）

本 Skill 将分支与特性目录管理流程封装为可复用 Skill，可被 reverse-on-demand 等命令/Skill 调用。

输入与前置条件

• 输入：
  • 用户输入文本（包含 $ARGUMENTS 中的内容），其中需要有“需求编号”信息；
  • 调用方可选择是否需要本 Skill 帮助获取 REPO_ROOT。
• 前置条件：
  • 需求编号是强制要求：如果未提供需求编号，本 Skill 必须给出中文错误并终止后续流程。

核心步骤（对应原命令文档）

步骤0（可选）：获取环境信息（REPO_ROOT）

• 何时执行：
  • 若调用方未明确提供 REPO_ROOT，且后续步骤需要使用绝对路径；
  • 若调用方已提供 REPO_ROOT，可以跳过。
• 操作（跨平台脚本）：
  • Linux: bash scripts/bash/check-prerequisites.sh --paths-only --json
  • Windows: pwsh scripts/powershell/check-prerequisites.ps1 --paths-only --json
  • 从 JSON 输出中解析 REPO_ROOT（必须为绝对路径）。

步骤1：解析与验证需求编号

• 解析：
  • 从用户输入中解析“需求编号”，支持多种格式：
    • 章节形式：## 需求编号 + 下一行 ID（如 TCF-123456）
    • 行内形式：需求编号: TCF-123456、MR: TCF-123456、Requirement ID: BUG-123456、PR: TCF-123456 等。
• 验证：
  • REQUIREMENT_ID 不为 null，不为空字符串，去除首尾空白后非空；
  • 若验证失败：
    • 用中文输出明确错误说明（需求编号是强制要求，并给出格式示例）；
    • 终止后续分支管理流程。

步骤2：检查当前分支是否匹配需求编号

• 逻辑：
  • 当前分支名以 <REQUIREMENT_ID>- 为前缀（不区分大小写）视为匹配；
  • 示例：TCF-123456-feature-name、tcf-123456-fix-bug 等。
• 输出：
  • BRANCH_MATCHES_REQUIREMENT = true/false
  • 若为 true：默认复用当前分支。

步骤3：生成分支简短名称（仅在需要创建新分支时）

• 前提：BRANCH_MATCHES_REQUIREMENT == false
• 逻辑：
  • 从功能描述中提取 2–4 个关键词，组合成简短英文/拼音短语（如 user-auth、fix-payment-bug）；
  • 分支名格式：<REQUIREMENT_ID>-<short-name>（如 TCF-123456-user-auth）。
  • 特性目录短名格式：<short-name>（如 rdma-sharepf-extend）。

步骤4：创建或复用特性分支与目录

• 首先检查是否已有可复用的分支/目录（按原文档优先级）：
  1. BRANCH_MATCHES_REQUIREMENT == true：复用当前分支，查找匹配目录；
  2. 当前分支已是特性分支且目录存在：直接复用；
  3. 搜索 NNN- 或需求编号前缀的目录并选择合适的一个。
• 若上述检查都未命中：
  • 调用创建特性分支脚本（仓库根目录下）：
    • Linux: scripts/bash/create-new-feature.sh --json --branch-name "<REQUIREMENT_ID>-<short-name>" --feature-dir "changes/<short-name>"
    • Windows: scripts/powershell/create-new-feature.ps1 --json --branch-name "<REQUIREMENT_ID>-<short-name>" --feature-dir "changes/<short-name>"
  • 从脚本 JSON 输出中解析得到：
    • BRANCH_NAME
    • TARGET_FILE（可为空；不再要求由本流程创建 spec.md）
    • FEATURE_DIR（特性目录绝对路径）
  • FEATURE_DIR 以脚本返回值为准；不得依赖 TARGET_FILE 反推目录路径。
  • 🔴 强制校验：FEATURE_DIR 必须匹配 <REPO_ROOT>/changes/<short-name>/；若不匹配，立即报错并终止流程。

步骤5：输出变量与终止条件

• 成功时，本 Skill 向调用方返回（或在上下文中设置）以下变量：
  • REQUIREMENT_ID
  • BRANCH_MATCHES_REQUIREMENT
  • BRANCH_NAME
  • FEATURE_DIR
  • TARGET_FILE（若适用）
  • REPO_ROOT（若在步骤0中获取）
• 终止条件：
  • 需求编号验证失败；
  • 其他脚本错误或路径解析错误（需用中文说明原因，并终止后续依赖步骤）。

参考说明

本 Skill 的详细逻辑已整合于上文步骤中；脚本参数、JSON 输出格式等以 create-new-feature 与 check-prerequisites 脚本的文档为准。执行本 Skill 时，AI Agent 应按上述步骤完成解析、校验与分支/目录创建或复用。