branch management

Engineering Community
Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
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.

Author source file SKILL.md

# 分支与特性目录管理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 应按上述步骤完成解析、校验与分支/目录创建或复用。

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.