branch management
- Repo stars 46
- License MIT
- Author repo Co-OmniSpec
- Domain
- Engineering
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 94 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @ZTE-AICloud · MIT
- Token usage
- Lean
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- Linux · Windows
- Runtime requirements
- No explicit requirements detected
- Detected file/system behavior
-
- Read-only
- Write / modify
- Shell exec
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
# 分支与特性目录管理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 应按上述步骤完成解析、校验与分支/目录创建或复用。
Sections and files
Listed in source order.
sections -> See the original source for section headings
terms -> No English key terms available
files/cmd -> reverse-on-demand · REQUIREMENT_ID · BRANCH_MATCHES_REQUIREMENT · BRANCH_NAME · FEATURE_DIR · <REPO_ROOT>/changes/<short-name>/ · TARGET_FILE · REPO_ROOT
body sha256 -> 31fb346e8db0